Առանց ինտերֆեյսի վճարումներ՝ ավանդի վրա հիմնված չեքաութ մեկ հարցումով

Եթե սեփական չեքաութ ես կառուցում — մոբայլ հավելված, գործընկերային հարթակ, կամ հատուկ խանութ — ֆիլհոսթ /pay/{id} էջը միշտ չէ, որ հարմար է: Դու արդեն ունես քո սեփական դրամապանակի հոսքը: Արդեն գիտես, թե որ ցանցում և որ թոքենով է հաճախորդդ ուզում վճարել: Քեզ իրականում պետք է մեկ API հարցում, որը կվերադարձնի ավանդի հասցեն և ուղարկելիք ճշգրիտ գումարը:

Դրա համար է POST /api/payments/headless-ը:

Հարցման ձևը

Մեկ հարցում ներս: Մեկ պատասխան դուրս:

curl -X POST https://mutopay.com/api/payments/headless \
  -H "X-API-Key: ep_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.00,
    "currency": "USD",
    "description": "Պատվեր #1042",
    "external_id": "order_1042",

    "src_token_symbol": "USDT",
    "src_token_address": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    "src_chain_id": "137",
    "src_decimals": 6,
    "src_address": "0xCustomerWallet..."
  }'

{
  "id": "pay_abc123...",
  "status": "awaiting_payment",
  "route_type": "bridge",
  "protocol": "rubic",
  "deposit": {
    "address": "0xRubicDepositAddress...",
    "chain_id": "137",
    "chain_type": "evm",
    "token_symbol": "USDT",
    "token_address": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    "token_decimals": 6,
    "amount_raw": "25100000",
    "amount_human": "25.10",
    "payment_uri": "ethereum:0x...@137?value=25100000"
  },
  "bridge": {
    "name": "Across",
    "estimated_time_ms": 60000,
    "src_usd": "25.10",
    "bridge_fee_usd": "0.10"
  },
  "order_id": "rubic_exchange_id...",
  "expires_at": "2026-04-14T15:30:00Z"
}

Քո հավելվածն այժմ ունի այն ամենը, ինչ պետք է․ ասա հաճախորդին, որ ուղարկի ճշգրիտ amount_raw չափով սկզբնաղբյուր թոքեն address հասցեով: Ցանկության դեպքում ցուցադրիր QR կոդ payment_uri-ից: Պարբերաբար հարցիր GET /api/payments/{id}/status՝ մինչև վերջնական վիճակի հասնելը:

Երկու երթուղու տիպ, նույն ձևը

• Ուղիղ — նույն թոքեն, նույն ցանց (հաճախորդը վճարում է USDT Polygon-ով, դու վերջահաշիվ ստանում ես USDT Polygon-ով): Ավանդի հասցեն քո դրամապանակն է: Առանց բրիջի վարձավճարների, առանց սպասման:
• Սվափ/բրիջ ավանդ — միջթոքենային կամ միջցանցային երթուղի, որտեղ հաճախորդը մեկ գործարքով ուղարկում է մուտքի հասցեին, իսկ վերջահաշվային թոքենը հասնում է քո դրամապանակին: Առանց որևէ պատվեր ստորագրելու:

Երթուղիները, որոնք պահանջում են հաճախորդից ստորագրել տիպավորված պատվեր կամ ուղարկել on-chain սվափ գործարք, չեն սպասարկվում այս էնդփոյնթով — եթե դա միակ հասանելի երթուղին է, դու կստանաս 422: Այդ դեպքերի համար օգտագործիր ֆիլհոսթ /pay/{id} էջը կամ ավելի ցածր մակարդակի /quotes + /build-order + /submit-order երրորդյակը:

Ինչ է մնում քեզ անել

Երկու բան:

1. Ստացիր tx hash-ը, եթե կարող ես: Սվափ/բրիջ ավանդների դեպքում ոչինչ պետք չէ անել — ֆոնային մոնիտորը ինքը կնկատի ավանդը և կնշի վճարումը որպես ավարտված: Ուղիղ երթուղիների դեպքում մոնիտորը ստուգում է միայն, երբ ունի tx hash, ուստի հաճախորդի կողմից գործարքի հեռարձակումից հետո կանչիր POST /api/payments/{id}/confirm՝ { "tx_hash": "0x..." }-ով: Եթե քո դրամապանակի UI-ն քեզ տալիս է hash-ը (շատերը տալիս են), սա մեկ տողանոց փոփոխություն է:

2. Հետևիր կարգավիճակին: GET /api/payments/{id}/status վերադարձնում է ընթացիկ վիճակը և tx hash-ը, երբ վճարումը հասնում է: Քո կանալում կարգավորած webhook-ը նույն իրադարձություններն է կրակում (payment.completed, payment.failed, և այլն) — ընտրիր այն, ինչ ավելի լավ է համապատասխանում քո ճարտարապետությանը:

Երբ որն օգտագործել

Ինչ ես կառուցում	Օգտագործիր
WooCommerce / Shopify-ի ոճի ինտեգրացիա՝ վերաուղղորդմամբ	POST /api/payments → /pay/{id}
Անհատականացված չեքաութ, որտեղ ինքդ ես ղեկավարում դրամապանակի հոսքը	POST /api/payments/headless
Պետք է առաջարկել մի քանի սվափ երթուղի և օգտատիրոջը թողնել ընտրությունը	POST /api/payments + /quotes + /build-order

Headless էնդփոյնթը նեղ է՝ դիտավորությամբ: Ինքնաշխատ ընտրում է լավագույն ավանդի վրա հիմնված երթուղին, ամրագրում է այն և վերադարձնում ավանդի հասցե: Եթե ավելի շատ վերահսկողություն է պետք — արագություն vs գին, մի քանի երթուղու տարբերակ, ստորագրված պատվերի հոսքեր — մանրամասն էնդփոյնթները դեռ տեղում են:

Ամբողջական տեղեկատու՝ API փաստաթղթերում: Հարցերը ողջունվում են: