From 96ba05a7906db83bea766497940566dae100253f Mon Sep 17 00:00:00 2001 From: hallstain Date: Wed, 28 Oct 2026 11:25:15 +0300 Subject: [PATCH] Document payer_account on on-ramp orders Co-Authored-By: Claude Opus 5.5 --- changelog.md | 10 ++++++++++ openapi/swagger.yaml | 41 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+) diff --git a/changelog.md b/changelog.md index 1f3a754..9d09607 100644 --- a/changelog.md +++ b/changelog.md @@ -2,6 +2,16 @@ Notable changes to the Unigox partner API, newest first. +## 2026-10-28 + +**Declare the customer's sending account on an on-ramp.** On-ramp orders take an optional `payer_account` (`account_number`, optional `bank_code`). + +- Send it on `POST /api/v1/partner/onramp/initiate`, or later with `POST /api/v1/partner/orders/{order_id}/submit-payer-details` while the order still awaits the customer's transfer. +- The customer's transfer is then matched to the order by the account it comes from, so two customers paying the same amount at the same time are not confused. Without it, the transfer is matched by the exact amount only, as before. +- It must be the customer's own account the transfer will come from. A transfer from another account is not matched to that order on amount. +- The account number may contain spaces and dashes; it must have 6 to 20 digits. It is echoed back as `payer_account` (digits only) on the initiate response and the order. +- Optional: orders without it work exactly as before. + ## 2026-10-26 **Webhooks for business customers.** Business-customer events are now sent to your webhook, signed and retried like order events. See [Business customers: Webhooks](./api-reference/business-customers.md#webhooks). diff --git a/openapi/swagger.yaml b/openapi/swagger.yaml index bc6100a..703811c 100644 --- a/openapi/swagger.yaml +++ b/openapi/swagger.yaml @@ -3249,6 +3249,8 @@ paths: example: quote_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" reference_id: "your-internal-order-id" + payer_account: + account_number: "1822611806" responses: '200': description: >- @@ -9813,6 +9815,26 @@ components: the nearest whole hour and never below `1`. `null` on an instant quote. example: 24 + PayerAccount: + type: object + description: | + On-ramp only, optional. The bank account the customer pays FROM, as you know it in your app. + When present, the incoming transfer is matched to the order by this account first, so two + customers paying the same amount at the same time are not confused. Without it the transfer is + matched by the exact amount only. Must be the customer's own account the transfer will come + from; a transfer from a different account is not matched to the order on amount. + required: [account_number] + properties: + account_number: + type: string + description: Account number. Spaces and dashes are ignored; 6 to 20 digits. + example: "182-2-61180-6" + bank_code: + type: string + maxLength: 32 + description: Optional bank identifier, for your own reference. + example: "kbank" + PartnerInitiateRequest: type: object required: [quote_id] @@ -9826,10 +9848,16 @@ components: type: string description: Optional partner-supplied external reference ID (e.g. your internal order ID). Stored on the order and echoed back in responses. example: "your-internal-order-id" + payer_account: + $ref: '#/components/schemas/PayerAccount' PartnerInitiateResponse: type: object properties: + payer_account: + allOf: + - $ref: '#/components/schemas/PayerAccount' + description: On-ramp only. The declared sending account as stored (digits only). Omitted when none was declared. order_id: type: string format: uuid @@ -9906,6 +9934,10 @@ components: PartnerOrderResponse: type: object properties: + payer_account: + allOf: + - $ref: '#/components/schemas/PayerAccount' + description: On-ramp only. The declared sending account as stored (digits only). Omitted when none was declared. order_id: type: string format: uuid @@ -10937,7 +10969,16 @@ components: description: | Submit the payer's payment details for a `payment_request` on-ramp order. Provide exactly one of `payment_details_id` (saved profile) or `payment_details` (inline object). + + On any on-ramp order you can instead (or additionally) send `payer_account`: the customer's + sending bank account, used to match their transfer. Accepted while the order is still awaiting + the transfer (`created`, `awaiting_vendor_escrow_funding`, `awaiting_fiat_transfer`, + `fiat_transfer_pending`). oneOf: + - required: [payer_account] + properties: + payer_account: + $ref: '#/components/schemas/PayerAccount' - required: [payment_details_id] properties: payment_details_id: