VPOS.am API — ինտեգրման հանրային փաստաթղթեր

Հանրային API-ի սահմանները

Փաստաթղթավորված է

Վճարային սեսիայի ստեղծումը, վճարման կարգավիճակի ստուգումը, ծառայության հանրային պատրաստվածության ստուգումը, Webhook-ները և հարցումների իդեմպոտենտ կրկնումը։

Չի հրապարակվում

Կոնսոլի և ադմինիստրատիվ API մեթոդները, օպերատորի token-ները, պրովայդերի կամ բանկի մուտքի գաղտնի տվյալները, վճարումների տվյալները և ներքին հաշվարկների համադրման մեխանիզմները։

Աշխատանքային միջավայրի հասանելիություն

Աշխատանքային միջավայրի հասանելիությունը հաստատվում է կոնկրետ տեղադրման և պրովայդերի երթուղու համար՝ վաճառողի ու դոմենի ստուգումից, պրովայդերի պայմանագրի ու մուտքի տվյալների հաստատումից, հետադարձ կանչի ստուգումից և փորձնական միջավայրում պահանջվող ապացույցներից հետո։ Գումարի վերադարձի (refund), չեղարկման (void/cancel) և հաշվարկների համադրման ապացույցը պահանջվում է, երբ երթուղին աջակցում է այդ գործողություններին։

Վաճառողի API մեթոդները մի կանչեք բրաուզերի կոդից և գաղտնիքները մի ներդրեք բջջային հավելվածում։ Bearer token-ը և Webhook ստորագրության գաղտնիքը պահեք միայն վստահելի սերվերում։

Նույնականացում և հարցման ձևաչափ

Վաճառողի API հարցումները օգտագործում են կոնկրետ տեղադրմանը կապված Bearer token։ Սերվերային կապակցումը որոշում է վաճառողին, ալիքը, ռեժիմը, պրովայդերի երթուղին և մուտքի տվյալները․ հարցման մարմինը չի կարող վերասահմանել այդ կապակցումը։

Հիմնական URL: https://api.vpos.am
Նույնականացում: Authorization: Bearer <merchant_api_token>
Հարցման մարմին: application/json
API տարբերակ: v1

Մուտքի տվյալներն ուղարկեք միայն HTTPS-ով՝ վստահելի սերվերից։ Վաճառողի token-ը երբեք մի տեղադրեք բրաուզերային փաթեթում, բջջային հավելվածում կամ կայքի կոնստրուկտորի հանրային կարգավորումներում։

Արագ մեկնարկ

Նվազագույն ինտեգրումը բաղկացած է երեք սերվերային քայլից՝ ստեղծել վճարային սեսիա, գնորդին ուղղորդել վերադարձված checkoutUrl հասցեով, ապա վերջնական կարգավիճակը հաստատել API հարցմամբ կամ ստորագրված Webhook-ով։

Ստեղծեք վճարային սեսիա՝ օգտագործելով պատվերի կայուն հղում և Idempotency-Key վերնագիրը։
Գնորդին ուղղորդեք VPOS.am-ի վերադարձված checkoutUrl հասցեով։
Պատվերը կատարեք միայն այն բանից հետո, երբ ստորագրված Webhook-ը կամ սերվերային կարգավիճակի հարցումը հաստատի paid կարգավիճակը։

returnUrl-ով գնորդի վերադարձը չի հաստատում վճարումը․ դա միայն օգտատիրոջ միջերեսի իրադարձություն է։ Ապրանքը կամ ծառայությունը տրամադրեք միայն սերվերային ստուգումից կամ վավեր ստորագրված Webhook-ից հետո։

Հիմնական API մեթոդներ

Քարտերը նկարագրում են վաճառողի վճարման հիմնական ընթացքը։ Հանրային գործողությունների և սխեմաների ամբողջական ցանկը հասանելի է OpenAPI 3.1 սպեցիֆիկացիայում։

GET/api/health

Հանրային #

Վերադարձնում է ծառայության հանրային պատրաստվածության կարգավիճակը՝ մոնիթորինգի և ինտեգրման ստուգումների համար։ JSON պատասխանը կարող է ներառել պատրաստվածության խոչընդոտներ, սակայն դրանց տեքստը կայուն API պայմանագիր չէ։

Կարգավիճակ	Նշանակություն
200	Ծառայությունը հասանելի է։ Պատրաստվածությունը նշվում է JSON պատասխանում։
405	HTTP մեթոդը չի աջակցվում։

GET/v1/capabilities

Bearer token #

Վերադարձնում է պրովայդերի հնարավորությունների պահպանողական մատրիցը։ Օգտագործեք այն՝ PayLink, QR, refund, fiscalization և tokenization գործողությունները օգտատիրոջ միջերեսում ակտիվացնելու համար միայն պատրաստ երթուղիների դեպքում։

Դաշտ	Կանոններ
`providers[].capabilities`	Պրովայդերի յուրաքանչյուր երթուղու աջակցության և ակտիվացման տրամաբանական ցուցիչները։
`connectors.statusSync`	VPOS-ի նորմալացված կարգավիճակները և հարթակներին հատուկ համապատասխանեցումները։ Բրաուզերից վերադարձը վճարման ապացույց չէ։
`payment_links, qr_presentation`	Ակտիվ է միայն այն դեպքում, երբ ընտրված երթուղին կարող է ստեղծել վճարային սեսիա։
`refund, capture, void, tokenization, subscriptions`	Գործողությունը հասանելի է միայն պրովայդերի ակտիվ հնարավորության դեպքում, հակառակ դեպքում API-ն վերադարձնում է disabled/not-configured սխալ։

POST/api/widget/checkout

Հանրային #

Հանրային վիջեթի բանալիով ստեղծում է վճարային էջ Webflow, Squarespace, Wix, Ucraft և պարզ կայքէջերի համար։ Բրաուզերը չի ստանում վաճառողի API token կամ բանկային մուտքի տվյալներ․ VPOS.am-ը սերվերում որոշում է բանալու, թույլատրելի հարցման աղբյուրի, վաճառողի և պրովայդերի երթուղու կապը։

Դաշտ	Կանոններ
`publicKey`	Վիջեթի տեղադրման հանրային բանալի, որը սերվերում կապված է թույլատրելի հարցման աղբյուրների ճշգրիտ ցանկին։
`productId`	Կարգավորված ապրանքի բանալի։ Լռելյայն գումարը վերցվում է VPOS.am-ի ռեեստրից։
`clientReference`	Բրաուզերում ստեղծված վճարման փորձի իդեմպոտենտ նույնացուցիչ։
`returnUrl`	Պետք է պատկանի վիջեթի տեղադրման թույլատրելի հարցման աղբյուրին։

POST/v1/payment-links

Bearer token #

Ստեղծում է իդեմպոտենտ վճարման հղում, որի հիմքում վճարային սեսիան է։ QR տվյալները միայն URL-ի ներկայացում են․ վճարման վերջնական կարգավիճակը հաստատվում է Webhook-ով կամ համադրմամբ։

Դաշտ	Կանոններ
`Idempotency-Key`	Պարտադիր վերնագիր։ Կրկնվող հարցումների ժամանակ օգտագործեք նույն բանալին՝ երկրորդ հղում չստեղծելու համար։
`amount, currency`	Գումարը հիմնական միավորներով և AMD/USD/EUR արժույթը։ AMD-ի համար պահանջվում է ամբողջ թիվ։
`description`	Գնորդին ցուցադրվող վճարման պարտադիր նկարագրություն։
`expiresAt`	Ոչ պարտադիր ապագա ISO ամսաթիվ և ժամ։ Հղման ժամկետի ավարտը չի հաստատում վճարման արդյունքը։
`provider`	Սպասվող պրովայդերի ոչ պարտադիր սահմանափակում։ Երթուղին և մուտքի տվյալներն ընտրվում են կոնկրետ տեղադրմանը կապված API բանալիով, անհամապատասխանությունը մերժվում է։

POST/v1/payment-sessions

Bearer token #

Ստեղծում է նորմալացված վճարային սեսիա և վերադարձնում պաշտպանված վճարային էջի URL, եթե ընտրված պրովայդերի երթուղին կարող է ստեղծել վճարային սեսիա։

Դաշտ	Կանոններ
`merchantOrderId`	Վաճառողի համակարգում պատվերի պարտադիր նույնացուցիչ։ Համադրման համար օգտագործեք կայուն արժեք։
`amountMinor`	Պարտադիր ամբողջ գումար՝ արժույթի նվազագույն միավորներով։
`currency`	API enum-ի արժեքներն են AMD, USD, EUR։ Իրականում հասանելի արժույթները որոշվում են տեղադրմանը կապված պրովայդերի երթուղով և մուտքի տվյալներով։
`returnUrl`	Բացարձակ HTTPS URL, ուր գնորդը վերադառնում է վճարային էջից։
`customer`	email, phone և name դաշտերը պարտադիր չեն։ Փոխանցեք միայն բիզնես գործընթացին անհրաժեշտ տվյալները։

POST/v1/payments/{paymentId}/refunds

POST/v1/payments/{paymentId}/capture

POST/v1/payments/{paymentId}/void

Bearer token #

Պաշտպանված refund, capture, void, fiscal retry, tokenization և subscriptions մեթոդները պահանջում են Idempotency-Key։ Միացված պրովայդերի երթուղին գործողությունը կատարում է սերվերում, իսկ վճարման տեղական կարգավիճակը փոխվում է միայն պրովայդերի վերջնական կարգավիճակի ստուգումից հետո։

Դաշտ	Կանոններ
`Idempotency-Key`	Պարտադիր է վճարման գումարի կամ կյանքի ցիկլի վրա ազդող յուրաքանչյուր գործողության համար։
`refund`	Պահանջում է հաստատված paid/partially_refunded վճարում, amountMinor, համապատասխան currency և reason։
`capture, void`	Capture-ը պահանջում է authorized կարգավիճակ։ Void/cancel-ը հասանելի է միայն պրովայդերի թույլատրած կարգավիճակների համար։
`tokenization`	Քարտի չմշակված տվյալները մերժվում են․ անհրաժեշտ են պրովայդերի token lifecycle-ը և հաճախորդի համաձայնությունը։
`subscriptions`	Ակտիվացնելուց առաջ անհրաժեշտ են պրովայդերի token և անհաջող երկարաձգման փորձարկված վարքագիծ։

GET/v1/payments?paymentId={paymentId}

Bearer token #

Վերադարձնում է նախապես ստեղծված վճարային սեսիայի ընթացիկ նորմալացված կարգավիճակը։

Կարգավիճակ	Առաջարկվող գործողություն
`created, pending_*, authorized`	Մի կատարեք պատվերը։ Շարունակեք կարգավիճակի հարցումը կամ սպասեք Webhook-ին։
`paid`	Պատվերը կարելի է կատարել amount, currency և merchantOrderId արժեքները ստուգելուց հետո։
`failed, cancelled, expired`	Ցույց տվեք սխալը կամ ստեղծեք վճարման նոր փորձ։
`refunded, partially_refunded, reversed, disputed`	Համաժամեցրեք հաշվապահությունը, CRM-ը և աջակցության գործընթացները։

Webhook-ներ

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

{
  "id": "evt_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "type": "payment.status_changed",
  "livemode": false,
  "createdAt": "2026-05-25T08:00:00.000Z",
  "trigger": "provider_callback",
  "data": {
    "payment": {
      "id": "pay_abcdef012345678901",
      "merchantOrderId": "order-1001",
      "provider": "ameriabank_vpos",
      "amountMinor": 15000,
      "currency": "AMD",
      "status": "paid",
      "fiscalStatus": "not_required"
    }
  }
}

Ստորագրության վերնագրի ձևաչափը՝ X-VPOS-Signature: t=<unix_timestamp>,v1=<hex_hmac_sha256>։ HMAC-SHA256-ը հաշվարկեք <timestamp>.<raw_request_body> տողի համար՝ վաճառողի Webhook գաղտնիքով, և կիրառեք timestamp-ի ստանդարտ հինգ րոպեանոց թույլատրելի միջակայքը։ Գաղտնիքի ռոտացիայի ժամանակ header-ը կարող է պարունակել մի քանի v1 արժեք․ ընդունեք event-ը, եթե թեկնածուներից որևէ մեկը անվտանգ համընկնում է ընթացիկ կամ անցումային շրջանում դեռ գործող գաղտնիքի հետ։ Առաքումը ներառում է նաև X-VPOS-Event-Id, X-VPOS-Event-Type և X-VPOS-Webhook-Timestamp header-ները։

Իդեմպոտենտություն

Idempotency-Key-ը օգտագործեք կրկնվող հարցումներ թույլատրող գործողությունների, օրինակ՝ վճարային սեսիա ստեղծելու համար։ Բանալին պահեք պատվերի և վճարման փորձի հետ։ Ցանցային սխալից հետո կրկնվող հարցումը չպետք է ստեղծի երկրորդ վճարվող պատվեր կամ հաշիվ։

Յուրաքանչյուր պատվերի վճարման փորձի համար օգտագործեք որոշարկված կայուն բանալի, ոչ թե նոր պատահական բանալի ամեն կրկնման ժամանակ։
Օգտատիրոջ նախաձեռնած առանձին փորձերի համար օգտագործեք առանձին բանալիներ։
Միասին գրանցեք paymentId-ը, merchantOrderId-ը, amountMinor-ը և currency-ն։

Սխալներ

HTTP կարգավիճակ	Նշանակություն	Ինտեգրողի գործողություն
`401`	Վաճառողի Bearer token-ը բացակայում է կամ անվավեր է։	Մի կրկնեք հարցումն առանց պատճառը պարզելու։ Փոխեք կամ վերաթողարկեք մուտքի տվյալները։
`403`	Հարցման աղբյուրը վստահելի չէ։	Օգտագործեք սերվերների միջև հարցում կամ գրանցեք սերվերային հավելվածի աղբյուրը։
`422`	Վավերացումը ձախողվել է։	Ուղղեք հարցման տվյալները և միայն հետո կրկնեք։
`429`	Հարցումների սահմանաչափը գերազանցվել է։	Սպասեք և կրկնեք՝ ավելացնելով պատահական ուշացում։
`503`	Պրովայդերը, պահեստը կամ նույնականացման կախվածությունը պատրաստ չէ։	Կրկնեք ավելի ուշ կամ կապվեք աջակցության հետ, եթե դա արգելափակում է աշխատանքային միջավայրը։

Անվտանգության կանոններ

Երբեք մի հրապարակեք վաճառողի Bearer token-ը, Webhook ստորագրության գաղտնիքը կամ պրովայդերի մուտքի տվյալները հաճախորդային կոդում։
Օգտագործեք միայն HTTPS և սերվերային ծրագրերում ստուգեք սերվերի վկայականները։
Վճարումը վերջնական համարեք միայն սերվերային կարգավիճակի հաստատումից հետո։
Մինչև պատվերի, CRM-ի կամ ERP-ի կարգավիճակը փոխելը ստուգեք amount-ը, currency-ն և merchantOrderId-ը։
Պահեք Webhook իրադարձությունների նույնացուցիչները և կանխեք կրկնվող բիզնես գործողությունները։
Գրանցեք ստորագրության ձախողված ստուգումները և կարգավիճակի անսպասելի անցումները՝ առանց ավելորդ անձնական տվյալներ պահելու։

Այս հանրային էջում դիտավորյալ չեն հրապարակվում աշխատանքային միջավայրի token-ները, կոնսոլի ներքին երթուղիները, պրովայդերի փակ հետադարձ կանչերը, տվյալների բազայի մանրամասները կամ բանկային մուտքի տվյալները։

CMS և կայքերի կոնստրուկտորներ

Tilda, WooCommerce, OpenCart և CS-Cart հարթակների դեպքում VPOS.am-ը մնում է տեխնիկական սերվերային ինտեգրման շերտ։ Կայքը ստանում է միայն ալիքի կարգավորումները և վերահասցեավորման հանրային URL-ները, իսկ բանկի կամ լիցենզավորված վճարային պրովայդերի մուտքի տվյալները պահվում են VPOS.am-ի պաշտպանված միջավայրում։

Tilda-ի համար VPOS.am-ը ստեղծում է վաճառողի login-ը, HMAC գաղտնիքը և Universal payment gateway-ի checkout URL-ը․ բանկի ClientID, login և password դաշտերը Tilda-ում չեն մուտքագրվում։
Մինչև աշխատանքային ռեժիմը միացնելը օպերատորը ստուգում է կայքի պատրաստվածությունը, վճարային էջի տվյալների ստորագրությունը, պրովայդերի երթուղու կապակցումը, հետադարձ կանչի մշակումը և թեստային վճարումը փորձնական միջավայրում։
Աշխատանքային միջավայրի միացումը մնում է օպերատորի վերահսկվող գործողություն և կատարվում է միայն վաճառողի՝ բանկի կամ լիցենզավորված պրովայդերի հետ պայմանագրի, պրովայդերի երթուղու և թեստավորման ապացույցների հաստատումից հետո։

Հասանելիության հարցում

Պիլոտային կամ աշխատանքային միջավայրի հասանելիություն ստանալու համար info@vpos.am հասցեին ուղարկեք ընկերության անվանումը, կայքը, ինտեգրման տեսակը, նախատեսվող բանկը կամ լիցենզավորված վճարային ծառայություն մատուցողը, արժույթները, հետադարձ կանչի URL-ը և տեխնիկական կոնտակտային անձի տվյալները։

Մինչև աշխատանքային միջավայրի հասանելիություն տրամադրելը VPOS.am-ը ստուգում է վաճառողի ինքնությունը, դոմենի պատկանելիությունը, հետադարձ կանչի URL-ի անվտանգությունը, թեստային վճարման արդյունքները, refund և հաշվարկների համադրման գործընթացները, ինչպես նաև աջակցության պատասխանատվության բաշխումը։

Հանրային API՝ վճարային սցենարների անվտանգ ինտեգրման համար։

Հանրային API-ի սահմանները

Նույնականացում և հարցման ձևաչափ

Արագ մեկնարկ

Հիմնական API մեթոդներ

Webhook-ներ

Իդեմպոտենտություն

Սխալներ

Անվտանգության կանոններ

CMS և կայքերի կոնստրուկտորներ

Հասանելիության հարցում