Ծրագրավորողի ուղեցույց · API v1

Ընդունեք քարտային վճարումներ GetPay-ի վճարման հղումներով

Ստեղծեք վճարման հղում ձեր սերվերից, ուղարկեք հաճախորդին այդ հղումով և ստացեք ծանուցում, երբ նա վճարի։ GetPay-ը տրամադրում է վճարման էջը, աշխատում է բանկի հետ և ձեզ հայտնում յուրաքանչյուր արդյունքի մասին։

API-ի բազային URL Այս էջի բոլոր օրինակներն օգտագործում են այս հասցեն։ Տեղադրեք ձերը GetPay կառավարման վահանակից (Դոմեն բաժին)․ յուրաքանչյուր խանութ ունի իր հասցեն՝ իր դոմենի վրա։

01Ինչպես է աշխատում

Վճարման հղումը GetPay-ում տեղակայված վճարման էջ է մեկ պատվերի համար։ Ձեր սերվերը ստեղծում է այն ձեր պատվերի տվյալներով, իսկ մնացածը հոգում է GetPay-ը։

Ձեր սերվերըՍտեղծում է վճարման հղում՝ ապրանքներով, գումարով և ձեր պատվերի համարով։ GetPay-ը վերադարձնում է url։
Ձեր կայքըՎերահղում է հաճախորդին այդ url-ին։
ՀաճախորդըՍտուգում է պատվերը, մուտքագրում իր տվյալները և վճարում քարտով բանկի պաշտպանված էջում։ Եթե քարտը մերժվում է, նա կարող է նորից փորձել նույն հղումով։
GetPayՍտուգում է արդյունքը բանկում, ուղարկում հաճախորդին ձեր success_url-ին և ձեր սերվերին ուղարկում payment_link.completed webhook։
Ձեր սերվերըՀաստատում է վճարումը և կատարում պատվերը։

sequenceDiagram
    participant S as Ձեր սերվերը
    participant C as Հաճախորդը
    participant G as GetPay
    participant B as Բանկ (vPOS)
    S->>G: POST /payment-links
    G-->>S: { id, url }
    S->>C: Վերահղում url-ին
    C->>G: Բացում է վճարման էջը, սեղմում «Վճարել»
    G->>B: Վճարման գրանցում
    C->>B: Քարտի տվյալներ, 3-D Secure
    B->>G: Արդյունք
    G->>C: Վերահղում success_url-ին
    G->>S: Webhook payment_link.completed
    S->>G: GET /payment-links/{id} (հաստատում)

02Նախքան սկսելը

Ձեր դոմենը և բազային URL-ը

API-ն աշխատում է ձեր սեփական դոմենի վրա, ոչ թե getpay.am-ի։ GetPay կառավարման վահանակում բացեք Դոմեն բաժինը, մուտքագրեք ձեր դոմենը (օրինակ՝ shopx.am) և ավելացրեք ցուցադրված չորս DNS գրառումները, որոնք բոլորը ցույց են տալիս GetPay-ի IP հասցեն․

Տեսակ	Անուն	Նշանակություն
A	api	Ձեր API-ի բազային URL-ը՝ `https://api.shopx.am/api/v1`
A	merchant	Ձեր կառավարման վահանակը
A	checkout	Վճարման էջերը, որտեղ վճարում են ձեր հաճախորդները
A	receipt	Անդորրագրերի էջերը

Այնուհետև սեղմեք Ստուգել միացումը։ Երբ բոլոր գրառումները գտնվեն, վահանակում կերևա ձեր API-ի բազային URL-ը։ Ցանկացած այլ հասցեի, այդ թվում՝ api.getpay.am-ի ուղարկված հարցումները մերժվում են 403 պատասխանով։

API բանալիներ

Ձեր բանալիները գտնվում են GetPay կառավարման վահանակի Գլխավոր → API բանալիներ բաժնում։ Դրանք երկուսն են՝ յուրաքանչյուր միջավայրի համար մեկական․

Բանալի	Ինչի համար է
sk_sandbox_…	Մշակում և թեստավորում։ Վճարումներն ավարտվում են GetPay-ի թեստային էջում․ բանկին դիմում չի կատարվում, և գումար չի գանձվում։
sk_live_…	Իրական վճարումներ։ Աշխատում է այն բանից հետո, երբ ձեր առևտրականի հաշիվն անցնում է live ռեժիմի և բանկը միացված է։

Բանալին փոխանցեք յուրաքանչյուր հարցման Authorization header-ում․

Գաղտնի բանալիները պահեք ձեր սերվերում։Երբեք մի տեղադրեք դրանք բրաուզերում, բջջային հավելվածում կամ հանրային ռեպոզիտորիայում։ Պահեք դրանք միջավայրի փոփոխականում, օրինակ՝ GETPAY_SECRET_KEY։

Պայմանավորվածություններ

Գումարները նշվում են նվազագույն միավորներով (լումա)։ 150000-ը նշանակում է 1 500,00 AMD։ Միշտ ուղարկեք ամբողջ թվեր։
Արժույթ՝ GetPay-ի կողմից միացված արժույթները՝ GET /meta/currencies (առայժմ AMD)։ Մյուսները վերադարձնում են CURRENCY_NOT_SUPPORTED։
Հարցումները և պատասխանները JSON ձևաչափով են։ Ուղարկեք Content-Type: application/json։
Ժամանակը նշվում է UTC-ով՝ ISO 8601 ձևաչափով, օրինակ՝ 2026-09-30T10:15:00Z։
Նույնականացուցիչները UUID են։ Պահեք վճարման հղման id-ն ձեր պատվերի հետ։

03Վճարման հղման ստեղծում

POST/payment-links

Կանչեք այս մեթոդը ձեր սերվերից, երբ հաճախորդը պատրաստ է վճարել։ Ուղարկեք, թե ինչ է նա գնում, ով է նա (եթե գիտեք) և ուր ուղարկել նրան վճարումից հետո։

Պարամետրեր

Ուղարկեք կա՛մ line_items, կա՛մ amount, բայց ոչ երկուսը միասին։ Մնացած ամեն ինչը պարտադիր չէ։

Դաշտ	Պարտադիր	Նկարագրություն
line_items[]	Երկուսից մեկը	Ապրանքները, որոնց համար վճարում է հաճախորդը՝ մինչև 100 հատ։ Ընդհանուր գումարը հաշվարկվում է դրանց հիման վրա։
line_items[].name	Այո	Ապրանքի անվանումը, որը ցուցադրվում է վճարման էջում։ Մինչև 255 նիշ։
line_items[].unit_amount	Այո	Մեկ միավորի գինը՝ նվազագույն միավորներով։
line_items[].quantity	Ոչ	1-ից 10 000։ Լռելյայն՝ 1։
line_items[].description	Ոչ	Կարճ տեքստ անվանման տակ։ Մինչև 1 000 նիշ։
line_items[].image_url	Ոչ	Նկարի հանրային http(s) հասցե, որը ցուցադրվում է ապրանքի կողքին։
line_items[].product_id	Ոչ	Ձեր SKU-ն կամ ապրանքի նույնականացուցիչը։
line_items[].metadata	Ոչ	«Բանալի — արժեք» տողային զույգեր՝ ձեր սեփական կարիքների համար։
line_items[].ehdm	Ոչ	Ֆիսկալ կտրոնի տվյալներ։ Պարտադիր է, երբ Է-ՀԴՄ-ն միացված է, տե՛ս Ֆիսկալ կտրոններ։
amount	Երկուսից մեկը	Ֆիքսված ընդհանուր գումար՝ նվազագույն միավորներով, երբ ապրանքներ չեք ուղարկում։ Պահանջում է `title` կամ `description`։
currency	Ոչ	`AMD` (լռելյայն) կամ GetPay-ի կողմից միացված այլ արժույթ (տե՛ս `GET /meta/currencies`)։
title	Ոչ	Վերնագիր վճարման էջում, օրինակ՝ «Պատվեր №1001»։
description	Ոչ	Ավելի երկար տեքստ էջում։ Մինչև 2 000 նիշ։
merchant_reference	Ոչ	Ձեր պատվերի համարը։ Վերադարձվում է հղման, դրա վճարումների և յուրաքանչյուր webhook-ի մեջ․ դրանով կարելի է որոնել։
language	Ոչ	Էջի լեզուն՝ `hy` (լռելյայն), `en` կամ `ru`։ Հաճախորդը կարող է փոխել այն։
customer.email	Ոչ	Նախապես լրացվում է վճարման էջում։
customer.name	Ոչ	Նախապես լրացվում է վճարման էջում։
customer.phone	Ոչ	Նախապես լրացվում է վճարման էջում։
customer.external_id	Ոչ	Ձեր հաճախորդի նույնականացուցիչը։ Հաճախորդին երբեք չի ցուցադրվում։
customer.address	Ոչ	`line1`, `line2`, `city`, `region`, `postal_code`, `country` (երկտառ կոդ, օրինակ՝ `AM`)։
customer_fields	Ոչ	Ինչ տվյալներ է հարցնում էջը։ `email`, `name`, `phone`, `address` դաշտերից յուրաքանչյուրի համար՝ `required`, `optional` կամ `hidden`։ Լռելյայն՝ էլ․ փոստը պարտադիր է, անունն ու հեռախոսը՝ ոչ պարտադիր, հասցեն՝ թաքցված։
success_url	Ոչ	Ուր է գնում հաճախորդը վճարելուց հետո։ GetPay-ը հասցեին ավելացնում է `payment_link_id`, `payment_id`, `receipt_number` և `receipt_url` (տե՛ս Անդորրագրեր)։
cancel_url	Ոչ	«Վերադառնալ խանութ» հղումը վճարման էջում։
payment_methods	Ոչ	Սահմանափակում է առաջարկվող վճարման եղանակները, օրինակ՝ `["ameriabank"]`։ Լռելյայն՝ բոլորը, որոնք միացված են ձեզ մոտ։
expires_in_minutes	Ոչ	30-ից 43 200 (30 օր)։ Լռելյայն՝ 1 440 (24 ժամ)։
metadata	Ոչ	Մինչև 50 բանալի։ Բանալիները՝ մինչև 40 նիշ, արժեքները՝ մինչև 500։ Վերադարձվում է հղման, դրա վճարումների և webhook-ների մեջ։
ehdm	Ոչ	Ֆիսկալ կտրոնի կարգավորումներ՝ `skip`, `skip_reason`, `item`։ Տե՛ս Ֆիսկալ կտրոններ։

Պատասխան

201 Created՝ վճարման հղումով։ Պահեք id-ն ձեր պատվերի հետ և ուղարկեք հաճախորդին url-ին։

Եթե հարցման սպասման ժամանակը լրանա,դուք կարող եք չիմանալ՝ հղումը ստեղծվե՞լ է, թե ոչ։ Նորը ստեղծելուց առաջ գտեք այն ձեր պատվերի համարով՝ GET /payment-links?merchant_reference=order-1001։

04Հաճախորդի ուղղորդում վճարման էջ

Վերահղեք հաճախորդի բրաուզերը պատասխանում ստացված url-ին։ Էջը ցուցադրում է ձեր բիզնեսի անվանումը, ապրանքները և ընդհանուր գումարը, հարցնում է ձեր ընտրած դաշտերը և առաջարկում վճարել քարտով։ Հաճախորդը կարող է ընտրել հայերեն, անգլերեն կամ ռուսերեն լեզուն։

Ինչ է լինում հետո

Արդյունք	Ուր է հայտնվում հաճախորդը
վճարված	Ձեր `success_url`-ը՝ ավելացված `?payment_link_id=…&payment_id=…&receipt_number=…&receipt_url=…` պարամետրերով։ Եթե `success_url` չկա՝ GetPay-ի հաստատման էջը՝ անդորրագրի հղումով։
մերժված	Կրկին վճարման էջում՝ պատճառի նշումով (օրինակ՝ «Քարտի վրա բավարար գումար չկա»)։ Նա կարող է նորից փորձել կամ օգտագործել այլ քարտ, քանի դեռ հղման ժամկետը չի լրացել։
սեղմել է «հետ»	Ձեր `cancel_url`-ը։ Հղումը մնում է բաց, այնպես որ նա կարող է վերադառնալ դրան։

Վերահղումը վճարման ապացույց չէ։Ցանկացած մարդ կարող է բացել ձեր հաջողության էջը ցանկացած պարամետրերով։ Պատվերը կատարելուց առաջ միշտ հաստատեք վճարումը ձեր սերվերում։

05Վճարման հաստատում

Օգտագործեք եղանակներից որևէ մեկը կամ երկուսը միասին։ Webhook-ներն ավելի հուսալի են, քանի որ դրանք հասնում են նույնիսկ այն դեպքում, երբ հաճախորդը փակում է բրաուզերը՝ ձեր հաջողության էջին չհասած։

Webhook՝ մշակեք payment_link.completed իրադարձությունը (տե՛ս Webhook-ներ)։
API՝ երբ հաճախորդը հայտնվում է ձեր success_url-ում, հարցրեք հղման տվյալները։

GET/payment-links/{id}

Պատվերը կատարեք միայն այն դեպքում, երբ status-ը complete է, payment_status-ը՝ paid, իսկ amount_total-ը և currency-ն համընկնում են ձեր պատվերի հետ։ Այս կանչը նաև կրկին ստուգում է բանկում սպասման մեջ գտնվող վճարումը։

Վճարման հղման կարգավիճակներ

status	Նշանակություն
open	Սպասում է վճարման։ Մերժված փորձերից հետո հղումը մնում է բաց։
complete	Վճարված է։ `payment_status`-ը `paid` է, իսկ `payment` դաշտում հաջողված վճարումն է։
expired	`expires_at` ժամկետը լրացել է մինչև վճարումը։
canceled	Դուք փակել եք այն `POST /payment-links/{id}/expire` կանչով։

Վճարման կարգավիճակներ

Վճարելու յուրաքանչյուր փորձ վճարում է, որը վերադարձվում է հղման payment դաշտում և վճարումների API-ով։

status	Նշանակություն
pending	Հաճախորդը վճարում է, կամ բանկը դեռ չի հաստատել։
succeeded	Գումարը գանձվել է քարտից։
failed	Մերժված է։ Պատճառը նշված է `failure_reason`-ում։ Հաճախորդը կարող է նորից փորձել։
refunded	Ամբողջությամբ վերադարձված է։
partially_refunded	Գումարի մի մասը վերադարձված է։ Տե՛ս `amount_refunded`։
reversed	Դուք չեղարկել եք ամբողջ վճարումը բանկում 72 ժամվա ընթացքում։ Տե՛ս `reversed_at`։
canceled	Ընդհատված է, օրինակ՝ հղումը չեղարկվել է վճարման ընթացքում։

06Webhook-ներ

Երբ որևէ բան է տեղի ունենում, GetPay-ը HTTPS POST հարցում է ուղարկում ձեր սերվերին, այնպես որ API-ն պարբերաբար հարցնելու կարիք չկա։ Յուրաքանչյուր հարցում ստորագրված է գաղտնի բանալիով, որը հայտնի է միայն ձեզ և GetPay-ին։

Endpoint-ի կարգավորում

Կառավարման վահանակում բացեք Webhook-ներ բաժինը, ընտրեք Sandbox կամ Live և ավելացրեք ձեր URL-ը, օրինակ՝ https://your-site.am/webhooks/getpay։
Ընտրեք բոլոր իրադարձությունները կամ միայն ձեզ անհրաժեշտները։
Պատճենեք ստորագրման գաղտնի բանալին (whsec_…) և պահեք այն ձեր սերվերում որպես GETPAY_WEBHOOK_SECRET։ Այն տարբերվում է ձեր API բանալուց։
Սեղմեք Ուղարկել թեստ՝ ձեր endpoint-ը ստուգելու համար։ Կառավարման վահանակը ցուցադրում է յուրաքանչյուր առաքում՝ ձեր սերվերի պատասխանի հետ միասին։

Live endpoint-ները պետք է օգտագործեն https://։ Sandbox endpoint-ները կարող են օգտագործել http://։ GetPay-ը չի կարող հասնել localhost-ին․ մշակման ընթացքում ձեր համակարգչում իրադարձություններ ստանալու համար օգտագործեք թունել, օրինակ՝ ngrok http 8001, և գրանցեք դրա տրամադրած հանրային URL-ը։

Իրադարձություններ

Իրադարձություն	Երբ	data.object
payment_link.completed	Հղումը վճարվել է։ Պատվերը կատարեք այս իրադարձության հիման վրա։	վճարման հղում
payment.succeeded	Քարտային վճարումը հաստատվել է։	վճարում
payment.failed	Վճարման փորձը մերժվել է։ Հաճախորդը դեռ կարող է նորից փորձել և վճարել։	վճարում
payment.refunded	Վճարումն ամբողջությամբ կամ մասնակի վերադարձվել է։	վճարում
payment.reversed	Վճարումն ամբողջությամբ չեղարկվել է բանկում։	վճարում
receipt.created	Վճարումը կատարվել է, և թողարկվել է անդորրագիր։ Ուղարկեք `url`-ը հաճախորդին։	անդորրագիր
receipt.updated	Անդորրագիրը փոխվել է վերադարձից կամ չեղարկումից հետո։	անդորրագիր
payment_link.canceled	Դուք փակել եք հղումը API-ի միջոցով։	վճարման հղում
webhook.test	Դուք սեղմել եք «Ուղարկել թեստ» կառավարման վահանակում։	թեստային հաղորդագրություն

Հարցման ձևաչափ

Header	Արժեք
GetPay-Signature	`t=1790755839,v1=5f2b…`՝ ուղարկման ժամանակը և HMAC-SHA256 ստորագրությունը։
GetPay-Event-Id	Իրադարձության եզակի նույնականացուցիչ։ Օգտագործեք այն՝ կրկնօրինակները անտեսելու համար։
GetPay-Event-Type	Օրինակ՝ `payment_link.completed`։
Content-Type	`application/json`

data.object-ն ունի ճիշտ նույն կառուցվածքը, ինչ տվյալ օբյեկտի API պատասխանը։

Ստորագրության ստուգում

Ստորագրությունը HMAC-SHA256(secret, t + "." + raw_body) է՝ hex ձևաչափով։ Հաշվարկեք այն հարցման չփոփոխված մարմնի վրա (վերակոդավորված JSON-ը չի համընկնի), համեմատեք հաստատուն ժամանակում և մերժեք 5 րոպեից հին հարցումները։

Պատասխան և կրկնակի փորձեր

Վերադարձրեք ցանկացած 2xx կոդ 10 վայրկյանի ընթացքում։ Դանդաղ աշխատանքը (նամակներ, պահեստի թարմացում, ERP համաժամացում) կատարեք ֆոնային առաջադրանքով՝ պատասխանելուց հետո։
Ցանկացած այլ դեպքում առաքումը կրկնվում է 1 րոպե, 5 րոպե, 30 րոպե, 2 ժամ, 6 ժամ, 12 ժամ և 24 ժամ անց։ Դրանից հետո առաքումը նշվում է որպես ձախողված, և այն կարող եք նորից ուղարկել կառավարման վահանակից։
Պատրաստ եղեք կրկնօրինակների։ Նույն իրադարձությունը կարող է հասնել մեկից ավելի անգամ։ Պահեք մշակված GetPay-Event-Id արժեքները և բաց թողեք կրկնությունները։
Մի՛ հիմնվեք հերթականության վրա։ Իրադարձությունները կարող են հասնել ոչ հերթականությամբ։ Օգտագործեք data.object-ի ներսում նշված կարգավիճակը կամ ստացեք վերջին վիճակը API-ից։
Կասկածի դեպքում վերստուգեք։ Ստացեք իրադարձությունը GET /events/{id} կանչով՝ ձեր գաղտնի բանալիով։

07Թեստավորում sandbox-ում

sk_sandbox_… բանալիով ամեն ինչ աշխատում է այնպես, ինչպես live ռեժիմում, բայց Վճարել կոճակը բանկի փոխարեն բացում է GetPay-ի թեստային էջը։ Դուք եք ընտրում, թե ինչպես կավարտվի վճարումը։ Webhook-ները, վերահղումները, մերժման հաղորդագրությունները և գումարի վերադարձները գործում են ճիշտ այնպես, ինչպես live ռեժիմում։ Բանկային մուտքի տվյալներ պետք չեն։

Թեստային էջի կոճակ	Արդյունք	Բանկի կոդ
Հաջող վճարում	succeeded՝ 424242******4242 թեստային քարտով	00
Անբավարար միջոցներ	failed	0116
Քարտի ժամկետը լրացել է	failed	0101
Մերժվել է թողարկողի կողմից	failed	0100
3-D Secure-ը ձախողվել է	failed	0-2006
Թողնել մշակման մեջ	pending՝ բանկը դեռ չի հաստատել․ ավարտեք այն ավելի ուշ թեստային էջից	—

Live ռեժիմի անցնելուց առաջ ստուգեք հետևյալը՝ հաջող վճարում, մերժում և դրան հաջորդող հաջող կրկնակի փորձ, հաճախորդ, որը վճարելուց հետո փակում է բրաուզերը (ձեր webhook-ը միևնույն է պետք է կատարի պատվերը), և գումարի վերադարձ։

08Գումարի վերադարձ և չեղարկում

Գումարը հետ տալու երկու եղանակ կա։ Երկու դեպքում էլ այն բանկի միջոցով վերադառնում է հաճախորդի քարտին։

Գործողություն	Գումար	Երբ	Արդյունք
Չեղարկում	Միշտ ամբողջ վճարումը	Վճարման սկզբից 72 ժամվա ընթացքում և միայն եթե դեռ ոչինչ չի վերադարձվել	reversed
Ամբողջական վերադարձ	Այն ամենը, ինչ դեռ չի վերադարձվել	Հաջող վճարումից հետո ցանկացած ժամանակ	refunded
Մասնակի վերադարձ	Ցանկացած գումար՝ մնացորդի սահմաններում․ կարելի է կրկնել	Հաջող վճարումից հետո ցանկացած ժամանակ	partially_refunded, այնուհետև refunded, երբ մնացորդ չի մնում

Յուրաքանչյուր վճարում ինքն է հայտնում, թե ինչ է հնարավոր անել տվյալ պահին, այնպես որ կանոններին ինքնուրույն հետևելու կարիք չկա․

Դաշտ	Նշանակություն
can_reverse	`true`, քանի դեռ չեղարկումը հնարավոր է։
reversible_until	Չեղարկման վերջնաժամկետը՝ վճարման սկզբից 72 ժամ անց։ Ցույց տվեք այն ձեր աշխատակիցներին։
can_refund	`true`, քանի դեռ վերադարձնելու գումար կա։
amount_refundable	Առավելագույն գումարը, որը դեռ կարող եք վերադարձնել՝ նվազագույն միավորներով։
amount_refunded	Մինչ այժմ վերադարձված գումարը։
reversed_at	Երբ է վճարումը չեղարկվել։

Վճարման չեղարկում

POST/payments/{id}/reverse

Չեղարկում է ամբողջ վճարումը բանկում։ Օգտագործեք այն, երբ պատվերը չեղարկվում է վճարումից կարճ ժամանակ անց։ 72 ժամ անցնելուց կամ որևէ վերադարձ կատարելուց հետո հարցումը վերադարձնում է 409, և չեղարկման փոխարեն պետք է կատարել վերադարձ։ Դրան հաջորդում է payment.reversed webhook-ը։

Վճարման վերադարձ

POST/payments/{id}/refund

Մասնակի վերադարձի համար ուղարկեք {"amount": 500000}՝ մինչև amount_refundable գումարի չափով։ Ամբողջ մնացորդը վերադարձնելու համար ուղարկեք դատարկ մարմին կամ {}։ Կարող եք կատարել մի քանի մասնակի վերադարձ։ Յուրաքանչյուրին հաջորդում է payment.refunded webhook-ը։

Երկու հարցումներն էլ վերադարձնում են թարմացված վճարումը։ Վճարման նույնականացուցիչը գտնվում է հղման payment.id դաշտում և ձեր success URL-ին ավելացված payment_id պարամետրում։

09Անդորրագրեր

Յուրաքանչյուր վճարված վճարում ստանում է անդորրագիր, ինչպես Stripe-ում․ կարճ համար, որը հաճախորդը կարող է նշել (օրինակ՝ 4821-0937), և GetPay-ի կողմից ձեր դոմենի վրա հյուրընկալվող անդորրագրի էջ՝ https://receipt.your-domain.am/… հասցեով։ Էջում երևում են ձեր բիզնեսի տվյալները, ապրանքները, օգտագործված քարտը, վերադարձները և PDF-ով պահպանելու կոճակ։ Էջը հասանելի է հայերեն, անգլերեն և ռուսերեն։

Անդորրագիրը թողարկվում է վճարման պահին, ուստի հղումն արդեն կա, երբ հաճախորդը վերադառնում է ձեր կայք, և երբ գալիս են webhook-ները։ Ոչինչ ստեղծել կամ միացնել պետք չէ։

Որտեղ եք ստանում անդորրագրի հղումը

Ալիք	Ինչ եք ստանում
Success URL	`receipt_number` և `receipt_url` պարամետրերը ավելացվում են ձեր `success_url`-ին՝ `payment_link_id`-ի և `payment_id`-ի կողքին։ Օգտագործեք դրանք՝ շնորհակալության էջում «Դիտել անդորրագիրը» հղում ցույց տալու համար։
Webhook-ներ	`receipt.created`՝ վճարման պահին, և `receipt.updated`՝ յուրաքանչյուր վերադարձից կամ չեղարկումից հետո։ `data.object`-ը ամբողջական անդորրագիրն է։ Բոլոր `payment.` և `payment_link.` իրադարձություններում վճարումը նույնպես պարունակում է `receipt_number` և `receipt_url`։
API	`receipt_number` և `receipt_url`՝ յուրաքանչյուր վճարման վրա (`GET /payments/{id}` և հղման `payment` դաշտը), իսկ ամբողջական անդորրագիրը՝ `GET /payments/{id}/receipt`-ով։

Ցույց տվեք անդորրագրի հղումը, բայց մի՛ վստահեք դրան։Ինչպես վերահղման մյուս պարամետրերը, սրանք էլ կարող է փոխել ցանկացած մեկը։ Պատվերը կատարելուց առաջ հաստատեք վճարումը ձեր սերվերում (տե՛ս Վճարման հաստատում)։ Էլ․ նամակների և անձնական էջի համար receipt_url-ը վերցրեք webhook-ից կամ API-ից։

Անդորրագրի օբյեկտը

Դաշտ	Նշանակություն
number	Հաճախորդին ցուցադրվող անդորրագրի համարը։ Եզակի է ձեր հաշվի սահմաններում։
url	Անդորրագրի հրապարակային էջը։ Նույն արժեքն է, ինչ վճարման `receipt_url`-ը։
status	Վճարման կարգավիճակը՝ `succeeded`, `partially_refunded`, `refunded` կամ `reversed`։
amount	Վճարված գումարը՝ մանր միավորներով։
amount_refunded	Մինչ այժմ վերադարձված գումարը։ Յուրաքանչյուր վերադարձ իր ամսաթվով նշված է `refunds[]`-ում։
amount_net	Հաճախորդի վերջնական վճարած գումարը՝ `amount − amount_refunded`, իսկ չեղարկումից հետո՝ `0`։
line_items[]	Վճարման հղման ապրանքները։
merchant	Ձեր բիզնեսի անվանումը, իրավաբանական անվանումը, ՀՎՀՀ-ն, հասցեն և աջակցության կոնտակտները՝ վերցված կառավարման վահանակի պրոֆիլից։
customer	Հաճախորդի մուտքագրած էլ․ հասցեն, անունը և հեռախոսը։
payment_method	Բանկը, քողարկված քարտի համարը, քարտապանի անունը, հաստատման կոդը և RRN-ը։
paid_at, issued_at	Երբ է կատարվել վճարումը և երբ է թողարկվել անդորրագիրը։

Պահեք անդորրագրի հղումները գաղտնի։Հղումն ունեցող ցանկացած մեկը կարող է բացել անդորրագիրը, և հղումը հնարավոր չէ գուշակել։ Կիսվեք այն միայն հաճախորդի հետ։ Sandbox անդորրագրերը բացվում են նույն էջում՝ «Թեստային ռեժիմ» նշումով։

10Ֆիսկալ կտրոններ (Է-ՀԴՄ)

Եթե ձեր բիզնեսը պարտավոր է տրամադրել ՀԴՄ կտրոն, GetPay-ը կարող է յուրաքանչյուր հաջող վճարում գրանցել Պետական եկամուտների կոմիտեում PayX էլեկտրոնային ՀԴՄ-ի միջոցով (Է-ՀԴՄ, ehdm.am)։ Անհրաժեշտ է ձեր սեփական պայմանագիրը PayX-ի հետ։ Նրանց տրամադրած API մուտքանունը միացրեք վահանակում՝ Կարգավորումներ → Է-ՀԴՄ։

Քանի դեռ Է-ՀԴՄ-ն միացված է, յուրաքանչյուր վճարման հղում պետք է նշի, թե ինչ է վաճառվում՝ դասակարգչի կոդը, անվանումը հայերեն և չափման միավորը։ Վճարումը հաջողվելուց հետո GetPay-ը ավտոմատ տրամադրում է ֆիսկալ կտրոնը, իսկ չեղարկումից կամ ամբողջական վերադարձից հետո՝ վերադարձի կտրոնը։

Ստուգեք՝ արդյոք Է-ՀԴՄ-ն միացված է

GET/ehdm

enabled: true նշանակում է, որ ձեր վճարման հղումները պետք է պարունակեն ֆիսկալ տվյալներ (կամ բաց թողնեն դրանք)։ dep-ը ձեր Է-ՀԴՄ կարգավորումներում ընտրված հարկային բաժինն է․ այն օգտագործվում է dep չուղարկող ապրանքների համար։

Ֆիսկալ տվյալներ վճարման հղման մեջ

Դաշտ	Պարտադիր	Նկարագրություն
line_items[].ehdm.adg_code	Այո*	Դասակարգչի կոդ՝ ԱԴԳՏ ծառայությունների համար (օր.՝ `85.59` — դասընթացներ) կամ ԱՏԳ ԱԱ ապրանքների համար (օր.՝ `5401`)։ Որոնեք `GET /ehdm/adg-codes?q=…`-ով։
line_items[].ehdm.good_name	Այո*	Անվանումը հայերեն, ինչպես տպվում է կտրոնում, մինչև 50 նիշ։ Լռելյայն՝ `line_items[].name`, եթե տեղավորվում է։
line_items[].ehdm.unit	Այո*	Հետևյալներից մեկը՝ `հատ`, `կգ`, `գրամ`, `լիտր`, `մետր`, `ք/մ`, `խ/մ`, `մլ`, `այլ`։ Կտրոնում տպվում է ինչպես ուղարկվել է։
line_items[].ehdm.good_code	Այո*	Ներքին կոդ՝ ձեր ապրանքի կոդը կամ շտրիխ-կոդը (մինչև 50 նիշ), տպվում է կտրոնի վրա որպես Ն/Կ։
line_items[].ehdm.dep	Ոչ	Հարկային բաժին՝ `1` ԱԱՀ, `2` ԱԱՀ-ից ազատված, `3` շրջանառության հարկ, `7` միկրոձեռնարկություն։ Լռելյայն՝ Է-ՀԴՄ կարգավորումներում ընտրված հարկային բաժինը։
ehdm.item	Ոչ	Նույն դաշտերը՝ առանց ապրանքների `amount` հղման համար։ `good_name`-ը լռելյայն՝ `title`։
ehdm.skip	Ոչ	`true`՝ հղումը ստեղծվում է առանց ֆիսկալ կտրոնի, օրինակ՝ երբ այն տրամադրվում է այլ տեղում։ `ehdm.skip_reason`՝ ոչ պարտադիր նշում։

* Պարտադիր է միայն, երբ Է-ՀԴՄ-ն միացված է։ Եթե ինչ-որ բան բացակայում է, հղումը չի ստեղծվում, և ստանում եք EHDM_FIELDS_REQUIRED՝ բացակայող դաշտերի ցանկով։

Վճարումից հետո

Կտրոնը գրանցվում է ֆոնային ռեժիմում, սովորաբար մի քանի վայրկյանում։ Հաճախորդի անդորրագրի էջը (receipt_url) այն ցույց է տալիս ՀԴՄ կտրոնի տեսքով՝ ֆիսկալ համարով, QR կոդով և PayX PDF-ի հղումով։ Դուք այն ստանում եք երեք տեղում․

Ալիք	Ինչ եք ստանում
API	`fiscal_receipt`՝ յուրաքանչյուր վճարման մեջ, և `GET /payments/{id}/fiscal-receipt`։
Webhook-ներ	`receipt.updated`՝ երբ ֆիսկալ կտրոնը տրամադրվում է և երբ վերադարձվում է։ Այն `data.object.fiscal`-ում է։
Վահանակ	Գործարքի մանրամասներում երևում են ֆիսկալ կտրոնը, դրա կարգավիճակը և Կրկնել կոճակը։

Ֆիսկալ կտրոնի կարգավիճակներ

Կարգավիճակ	Նշանակություն
`pending`	Սպասում է գրանցման (կամ կրկնվում է)։
`issued`	Գրանցված է հարկային մարմնում։
`failed`	Բոլոր փորձերից հետո չհաջողվեց գրանցել։ Կրկնեք վահանակից կամ API-ից։
`reverse_pending`	Չեղարկումից կամ ամբողջական վերադարձից հետո տրամադրվում է վերադարձի կտրոն։
`reversed`	Վերադարձի կտրոնը տրամադրված է։
`reverse_failed`	Վերադարձի կտրոնը չհաջողվեց տրամադրել։ Կրկնեք։
`canceled`	Վճարումը վերադարձվել է նախքան կտրոնի գրանցումը, ուստի ոչինչ չի գրանցվել։

Վճարումը երբեք չի սպասում կտրոնին։Եթե PayX-ը հասանելի չէ, GetPay-ը կրկնում է մոտ 10 ժամ, ապա սահմանում failed․ կրկնեք POST /payments/{id}/fiscal-receipt/retry-ով։ Մասնակի վերադարձը հնարավոր չէ ավտոմատ վերադարձնել ըստ ապրանքների․ needs_manual_return-ը դառնում է true, և վերադարձի կտրոնը տրամադրում եք PayX-ում։

Sandbox կտրոնները մոդելավորված են։Դրանք ունեն livemode: false և երբեք չեն հասնում PayX-ին կամ հարկային մարմնին, ուստի կարող եք թեստավորել ամբողջ հոսքը, ներառյալ վավերացման սխալները։

11API տեղեկագիր

Բոլոր endpoint-ներն օգտագործում են ձեր գաղտնի բանալին։ Sandbox բանալին տեսնում է միայն sandbox-ի տվյալները, իսկ live բանալին՝ միայն live-ի տվյալները։

Endpoint	Նկարագրություն
POST /payment-links	Ստեղծել վճարման հղում։
GET /payment-links	Հղումների ցանկ՝ սկզբում նորերը։Ֆիլտրեր՝ `status`, `merchant_reference`, `customer_external_id`, `limit` (1–100, լռելյայն՝ 20), `offset`։
GET /payment-links/{id}	Ստանալ հղումը և դրա վերջին վճարումը։
POST /payment-links/{id}/expire	Փակել չվճարված հղումը, որպեսզի դրանով այլևս հնարավոր չլինի վճարել։
GET /payments	Վճարումների ցանկ։Ֆիլտրեր՝ `status`, `merchant_reference`, `payment_link_id`, `limit`, `offset`։
GET /payments/{id}	Ստանալ վճարումը՝ ներառյալ քարտի տվյալները (քողարկված համար, քարտապանի անուն, հաստատման կոդ, RRN)։
GET /payments/{id}/receipt	Ստանալ վճարված վճարման անդորրագիրը (`404`, քանի դեռ վճարված չէ)։ Նույն օբյեկտն է, ինչ `receipt.*` webhook-ներում։
POST /payments/{id}/refund	Վերադարձնել վճարումն ամբողջությամբ (առանց գումարի) կամ մասնակի (`amount`)։
POST /payments/{id}/reverse	Չեղարկել ամբողջ վճարումը 72 ժամվա ընթացքում։
GET /meta/currencies	GetPay-ի արժույթները․ վճարման հղումներ կարելի է ստեղծել `is_enabled: true` ունեցողներով։ Բանալի պետք չէ։
GET /ehdm	Արդյոք Է-ՀԴՄ-ն միացված է ձեր հաշվի համար, և ձեր հարկային բաժինը։
GET /ehdm/adg-codes	Դասակարգչի կոդերի որոնում։Ֆիլտրեր՝ `q` (կոդի սկիզբ կամ անվան մաս), `kind` (`adgt` կամ `atg`), `limit`։
GET /payments/{id}/fiscal-receipt	Վճարման ֆիսկալ կտրոնը։
POST /payments/{id}/fiscal-receipt/retry	Կրկնել `failed` կամ `reverse_failed` ֆիսկալ կտրոնը։
GET /events	Իրադարձությունների ցանկ՝ սկզբում նորերը։Ֆիլտրեր՝ `type`, `limit`, `offset`։
GET /events/{id}	Ստանալ մեկ իրադարձություն, օրինակ՝ ստացված webhook-ը հաստատելու համար։

Ցանկերը վերադարձվում են հետևյալ տեսքով՝ { "object": "list", "items": [...], "total", "limit", "offset" }։

12Սխալներ

Սխալի դեպքում վերադարձվում է JSON՝ HTTP կարգավիճակով, կայուն message_code-ով, որը կարող եք ստուգել ձեր կոդում, և ընթեռնելի message-ով։

Կարգավիճակ	message_code	Նշանակություն
400	`BAD_REQUEST`	Հարցումը հնարավոր չէ մշակել, օրինակ՝ չաջակցվող արժույթ, կամ վճարման ոչ մի եղանակ միացված չէ։ Կարդացեք `message`-ը։
400	`EHDM_FIELDS_REQUIRED`	Է-ՀԴՄ-ն միացված է, և ֆիսկալ տվյալներ են բացակայում։ `details.missing`-ը թվարկում է դաշտերը, օր.՝ `line_items[0].ehdm.adg_code`։
400	`CURRENCY_NOT_SUPPORTED`	Արժույթը միացված չէ GetPay-ի կողմից։ `details.supported`-ը թվարկում է թույլատրված արժույթները։
400	`EHDM_CURRENCY_NOT_SUPPORTED`	Ֆիսկալ կտրոնները միայն AMD-ով են։ Օգտագործեք AMD կամ ուղարկեք `ehdm.skip: true`։
401	`UNAUTHORIZED`	Գաղտնի բանալին բացակայում է կամ անվավեր է։
403	`FORBIDDEN`	Բանալին չի կարող կատարել այս գործողությունը, օրինակ՝ live բանալի, երբ ձեր հաշիվը դեռ live ռեժիմում չէ։
404	`NOT_FOUND`	Այս բանալու և միջավայրի համար նման օբյեկտ չկա։
409	`CONFLICT`	Ընթացիկ վիճակում հնարավոր չէ, օրինակ՝ չեղարկում 72 ժամից հետո, չվճարված վճարման վերադարձ կամ վճարված հղման փակում։ `message`-ում նշված է, թե ինչ անել դրա փոխարեն։
422	`VALIDATION_ERROR`	Դաշտը բացակայում է կամ անվավեր է։ `details.errors`-ում թվարկված է յուրաքանչյուր դաշտ։
502	`PAYMENT_GATEWAY_ERROR`	Բանկը մերժել է վերադարձը կամ չի պատասխանել։ Կարելի է անվտանգ կրկնել ավելի ուշ։

13Գործարկման ստուգացանկ

Ձեր դոմենը միացված է Դոմեն բաժնում, և ձեր սերվերն օգտագործում է այնտեղ նշված API-ի բազային URL-ը։
Ձեր առևտրականի հաշիվն ավարտել է գրանցման գործընթացը և կառավարման վահանակում փոխարկված է live ռեժիմի։
Ձեր բանկի (Ameriabank vPOS) մուտքի տվյալները միացված և ակտիվացված են Վճարային համակարգեր → Live բաժնում։
Ձեր սերվերն օգտագործում է sk_live_… բանալին միջավայրի փոփոխականից, ոչ թե կոդից։
Ավելացված է live webhook endpoint՝ https:// հասցեով, և դրա whsec_… գաղտնի բանալին ձեր սերվերում է։
Ձեր webhook-ի մշակիչը ստուգում է ստորագրությունները, մերժում հին ժամանակադրոշմները և անտեսում իրադարձությունների կրկնվող նույնականացուցիչները։
Պատվերները կատարում եք միայն complete / paid կարգավիճակը հաստատելուց և գումարի ու արժույթի համընկնումը ստուգելուց հետո։
Ձեր շնորհակալության էջը կամ պատվերի էլ․ նամակը հաճախորդին ցույց է տալիս receipt_url-ը։
Եթե օգտագործում եք Է-ՀԴՄ՝ PayX-ը միացված և ակտիվացված է Կարգավորումներ → Է-ՀԴՄ բաժնում, և ձեր հղումներն ուղարկում են line_items[].ehdm։
Կատարել եք մեկ փոքր իրական վճարում և վերադարձրել այն։