AcquirerCallbackService link
Acquirer-implemented callbacks t-0 pushes — authorization, settlement
progress, and expiry. Delivered at least once and deduped on the t-0 id.
AcquirerService link
t-0 endpoints the Acquirer calls to price a sale, open a payment intent, and
confirm fiat receipt.
Requests And Response Types link
AcquirerPaymentExpiredRequest link
PaymentExpired exists on both the acquirer and issuer edges of this flat package,
so each side’s request and response carry their role as a prefix. This is the
acquirer’s.
| Field | Type | Label | Description |
|---|
| payment_intent_id | uint64 | | Intent that expired. |
| payment_ref | string | | Echo of the Acquirer’s CreatePaymentIntent payment_ref — a non-authoritative correlation ref the Acquirer can match by, alongside payment_intent_id. |
| expired_at | google.protobuf.Timestamp | | Moment the intent became terminal. |
AcquirerPaymentExpiredResponse link
This message has no fields defined.
CreatePaymentIntentRequest link
| Field | Type | Label | Description |
|---|
| payment_ref | string | | Sale identifier from the Acquirer’s own ledger, echoed on PaymentAuthorized and PaymentExpired. Not an idempotency key, and not required to be unique. |
| idempotency_key | string | | Retry identity for this call, unique per Acquirer. At most one payment intent is ever created under one key, and repeating a key whose intent exists returns it unchanged. Retrying a declined sale takes a fresh key under the same payment_ref. |
| local_amount | Decimal | | Fiat amount of the sale, in the settlement currency. |
| usdt_settlement | CreatePaymentIntentRequest.UsdtSettlementTerms | | |
| fiat_settlement | CreatePaymentIntentRequest.FiatSettlementTerms | | |
CreatePaymentIntentRequest.FiatSettlementTerms link
Reference to a standing quote when the Acquirer is settled in fiat via an LP.
| Field | Type | Label | Description |
|---|
| quote_id | uint64 | | Standing quote obtained from GetPaymentQuote; supplies local_currency and fx_rate. |
CreatePaymentIntentRequest.UsdtSettlementTerms link
Acquirer-supplied terms when it settles in USDt and runs its own FX.
| Field | Type | Label | Description |
|---|
| local_currency | string | | ISO 4217 currency the merchant quoted the customer in. |
| fx_rate | Decimal | | Units of local_currency per 1 USDt, set by the Acquirer. |
CreatePaymentIntentResponse link
CreatePaymentIntentResponse.Failure link
CreatePaymentIntentResponse.Success link
| Field | Type | Label | Description |
|---|
| payment_intent_id | uint64 | | t-0’s id for the opened intent. |
| local_currency | string | | ISO 4217; echoed in USDt mode, resolved from the quote in fiat mode. |
| local_amount | Decimal | | Fiat amount of the sale. |
| fx_rate | Decimal | | Units of local_currency per 1 USDt locked for this intent. |
| amount_usdt | Decimal | | Exact amount the customer pays, round(local_amount / fx_rate, 2dp, half-up). |
| expires_at | google.protobuf.Timestamp | | After this moment the Issuer releases the deposit addresses and the QR is invalid. |
| qr_options | QrOption | repeated | One option per chain the Issuer supports for this intent; the customer picks one. |
GetPaymentQuoteRequest link
| Field | Type | Label | Description |
|---|
| local_currency | string | | ISO 4217 currency the merchant is quoting in (e.g. COP). |
| local_amount | Decimal | | Fiat amount the merchant wants to price. |
GetPaymentQuoteResponse link
GetPaymentQuoteResponse.Failure link
GetPaymentQuoteResponse.Success link
| Field | Type | Label | Description |
|---|
| quote_id | uint64 | | t-0’s id for the priced standing quote. |
| amount_usdt | Decimal | | USDt the customer pays for local_amount at fx_rate. |
| fx_rate | Decimal | | Standing quote’s rate, in units of local_currency per 1 USDt. |
| expires_at | google.protobuf.Timestamp | | Moment the standing quote stops standing on t-0’s clock. |
PaymentAuthorizedRequest link
| Field | Type | Label | Description |
|---|
| payment_intent_id | uint64 | | Intent that was authorized. |
| payment_ref | string | | Echo of the Acquirer’s CreatePaymentIntent payment_ref — a non-authoritative correlation ref, so the merchant order can be matched by either this or payment_intent_id. |
| usdt_on_chain | UsdtOnChainPayment | | |
| approved_at | google.protobuf.Timestamp | | Moment t-0 accepted PaymentReceived. |
PaymentAuthorizedResponse link
This message has no fields defined.
SettlementCompletedRequest link
| Field | Type | Label | Description |
|---|
| settlement_id | uint64 | | t-0’s id for the settlement being completed. |
| settlement_amount | Decimal | | Amount the Acquirer actually received; currency set by the settlement variant. |
| settled_payment_intent_ids | uint64 | repeated | Intents this settlement clears. |
| settled_at | google.protobuf.Timestamp | | Moment the settlement reached the Acquirer. |
| settlement | OnChainSettlementDetails | | The on-chain USDt settlement that reached the Acquirer. USDt mode only — fiat mode has no SettlementCompleted (the Acquirer’s SettlementReceived is terminal). |
SettlementCompletedResponse link
This message has no fields defined.
SettlementInitiatedRequest link
| Field | Type | Label | Description |
|---|
| fiat_settlement_id | uint64 | | t-0’s id for this fiat settlement; the bank-rails leg’s key. |
| lp_id | uint64 | | t-0’s id for the LP that sent the transfer; scopes bank_transfer_ref. |
| bank_transfer_ref | string | | Reference the LP put on the bank-rails transfer; matched against the statement. |
| settled_payment_intent_ids | uint64 | repeated | Intents this settlement clears, resolved by t-0 from the LP’s executions. |
| local_currency | string | | ISO 4217 currency of the bank-rails transfer. |
| settlement_amount | Decimal | | Fiat amount the LP transferred. |
| acquirer_id | uint64 | | t-0’s id for the Acquirer this settlement is addressed to. |
| initiated_at | google.protobuf.Timestamp | | Moment t-0 accepted the LP’s fiat-settlement report. |
SettlementInitiatedResponse link
This message has no fields defined.
SettlementReceivedRequest link
| Field | Type | Label | Description |
|---|
| lp_id | uint64 | | t-0’s id for the LP that sent the transfer, echoed from SettlementInitiated. |
| bank_transfer_ref | string | | Reference on the received transfer, matched against the bank statement. |
| local_currency | string | | ISO 4217 currency credited. |
| amount_received | Decimal | | Fiat amount credited to the Acquirer’s account. |
| received_at | google.protobuf.Timestamp | | Moment the funds landed in the Acquirer’s account. |
SettlementReceivedResponse link
SettlementReceivedResponse.Accepted link
This message has no fields defined.
SettlementReceivedResponse.Rejected link
CreatePaymentIntentResponse.Failure.Reason link
| Name | Number | Description |
|---|
| REASON_UNSPECIFIED | 0 | |
| REASON_ISSUER_UNAVAILABLE | 10 | The Issuer could not be reached to allocate instructions. |
| REASON_ADDRESS_POOL_EMPTY | 20 | The Issuer has no free one-time deposit addresses. |
| REASON_AMOUNT_OUT_OF_RANGE | 40 | The amount falls outside the acceptable range. |
| REASON_QUOTE_EXPIRED | 50 | The referenced quote no longer stands. |
| REASON_QUOTE_INSUFFICIENT_HEADROOM | 70 | The quote’s remaining validity is too short to guarantee execution before it expires. |
GetPaymentQuoteResponse.Failure.Reason link
| Name | Number | Description |
|---|
| REASON_UNSPECIFIED | 0 | |
| REASON_QUOTE_UNAVAILABLE | 10 | No standing quote available for this currency right now. |
SettlementReceivedResponse.Rejected.Reason link
| Name | Number | Description |
|---|
| REASON_UNSPECIFIED | 0 | |
| REASON_AMOUNT_MISMATCH | 10 | amount_received does not equal the matched transfer’s settlement amount. |
| REASON_UNKNOWN_TRANSFER | 20 | No fiat settlement matches the (lp_id, bank_transfer_ref) pair. |
| REASON_CURRENCY_MISMATCH | 30 | local_currency is not the currency t-0 recorded for the matched transfer; resend with the correct currency. |