AcquirerCallbackService

Acquirer-implemented callbacks t-0 pushes: authorization, settlement progress, expiry, and payment failure. Each is delivered to the Acquirer’s registered callback URL at least once; the Acquirer dedupes on the t-0-minted id it carries.

Method NameRequest TypeResponse TypeDescription
PaymentAuthorizedPaymentAuthorizedRequestPaymentAuthorizedResponseTells the merchant the payment is approved; from here the Issuer is obligated to settle.
SettlementInitiatedSettlementInitiatedRequestSettlementInitiatedResponsePre-notice that the LP sent a fiat bank transfer, naming the reference to expect; fiat settlement mode only, and does not settle the intents.
SettlementCompletedSettlementCompletedRequestSettlementCompletedResponseThe Issuer’s USDt settlement verified on-chain as reaching the Acquirer’s wallet, with the intents it clears; USDt settlement mode only — in fiat mode the Acquirer’s own SettlementReceived is the terminal event.
PaymentExpiredPaymentExpiredRequestPaymentExpiredResponseThe QR window lapsed with no payment; clear the pending order and drop the QR.
PaymentFailedPaymentFailedRequestPaymentFailedResponseA deposit arrived that the Issuer will not process; the payment is over and will not settle.

AcquirerService

t-0 endpoints the Acquirer calls to price a payment, open a payment intent, and confirm fiat receipt.

Method NameRequest TypeResponse TypeDescription
GetPaymentQuoteGetPaymentQuoteRequestGetPaymentQuoteResponsePrices an upcoming local-fiat payment from t-0’s Order Book of standing LP quotes; fiat settlement mode only.
CreatePaymentIntentCreatePaymentIntentRequestCreatePaymentIntentResponseOpens a payment intent; t-0 reserves deposit addresses with the Issuer inline and returns the payment instructions.
SettlementReceivedSettlementReceivedRequestSettlementReceivedResponseConfirms that a fiat settlement landed in the Acquirer’s bank account; fiat settlement mode only, and the only event that settles the covered intents.

Requests And Response Types

CreatePaymentIntentRequest

FieldTypeLabelDescription
payment_refstringPayment identifier from the Acquirer’s own ledger, echoed on PaymentAuthorized, PaymentExpired, and PaymentFailed. Not an idempotency key, and not required to be unique.
idempotency_keystringRetry 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 payment takes a fresh key under the same payment_ref.
settlementCreatePaymentIntentRequest.SettlementAmount
localLocalAmount
quote_iduint64A standing quote from GetPaymentQuote; it must still stand, and its currency must equal local.currency when local is given.

CreatePaymentIntentRequest.SettlementAmount

The payment in the settlement asset, USDt: the asset every settlement leg moves, so this figure is present for every payment whatever the Acquirer is settled in. What it becomes in fiat, and at which rate, is the response’s fiat settlement block, never this message.

FieldTypeLabelDescription
valuetzero.v1.pay.DecimalAmount in USDt, at most 2 decimal places. In fiat settlement mode t-0 derives the local amount from it at the locked rate; in USDt settlement mode it is also what the Acquirer is settled.

CreatePaymentIntentResponse

FieldTypeLabelDescription
successCreatePaymentIntentResponse.Success
failureCreatePaymentIntentResponse.Failure

CreatePaymentIntentResponse.Failure

FieldTypeLabelDescription
reasonCreatePaymentIntentResponse.Failure.Reason

CreatePaymentIntentResponse.Success

FieldTypeLabelDescription
payment_intent_iduint64t-0’s id for the intent; carried on every later event.
expires_atgoogle.protobuf.TimestampAfter this moment the payment instructions are invalid; on the QR method the Issuer releases the deposit addresses.
settlement_amounttzero.v1.pay.DecimalUSDt the customer pays and the settlement leg moves, the same figure in every mode: as sent in amount.settlement, or round(local / fx_rate, 2 dp, half-up) from amount.local. In fiat settlement mode the Acquirer itself receives the fiat block’s local amount.
usdt_on_chainCreatePaymentIntentResponse.Success.UsdtOnChainInstructions
fiatFiatSettlement
onchainCreatePaymentIntentResponse.Success.OnchainSettlement

CreatePaymentIntentResponse.Success.OnchainSettlement

On-chain settlement mode; carries no data. The Issuer settles settlement_amount in USDt to the Acquirer’s registered wallet; no quote and no FX.

This message has no fields defined.

CreatePaymentIntentResponse.Success.UsdtOnChainInstructions

The customer’s USDt-via-QR payment instructions.

FieldTypeLabelDescription
deposit_optionsCreatePaymentIntentResponse.Success.UsdtOnChainInstructions.DepositOptionrepeatedOne deposit option per chain the Issuer supports for this intent; the customer picks one in their wallet.

CreatePaymentIntentResponse.Success.UsdtOnChainInstructions.DepositOption

One selectable deposit option: the chain, the one-time address reserved on it, and the USDt token contract with its decimals. Together with settlement_amount these are everything the POS needs to build whatever it carries to the customer (a QR image, a wallet deep link, or a plain address).

FieldTypeLabelDescription
chaintzero.v1.pay.BlockchainChain this deposit option pays on.
deposit_addressstringOne-time deposit address reserved for this intent on chain.
token_contractstringUSDt token contract on chain the deposit must be made in.
token_decimalsuint32Decimals of token_contract: the amount to transfer in the token’s base units is settlement_amount * 10^token_decimals. USDt does not use the same decimals on every chain.

FiatSettlement

The fiat terms locked for a payment whose Acquirer is settled in fiat: the standing quote, its rate, and the local amount the Acquirer is settled. Returned on CreatePaymentIntent and repeated unchanged on PaymentAuthorized, PaymentExpired and PaymentFailed; absent for an Acquirer settled on-chain.

FieldTypeLabelDescription
quote_iduint64t-0’s id of the standing quote the intent locked: the referenced one, or the one t-0 resolved when the request named none.
fx_ratetzero.v1.pay.DecimalLocked rate, in units of local.currency per 1 USDt.
localLocalAmountFiat amount the Acquirer is settled: as sent in the request’s local, or, for a payment denominated in USDt, round(settlement_amount × fx_rate, half-up) to the currency’s minor units.

GetPaymentQuoteRequest

FieldTypeLabelDescription
local_currencystringThree-letter currency code in ISO 4217 form the merchant is quoting in (e.g. COP); not checked against the ISO list.
local_amounttzero.v1.pay.DecimalFiat amount in local_currency to price; a value finer than the currency’s minor units is invalid input.

GetPaymentQuoteResponse

FieldTypeLabelDescription
successGetPaymentQuoteResponse.Success
failureGetPaymentQuoteResponse.Failure

GetPaymentQuoteResponse.Failure

FieldTypeLabelDescription
reasonGetPaymentQuoteResponse.Failure.Reason

GetPaymentQuoteResponse.Success

FieldTypeLabelDescription
quote_iduint64t-0’s id for the standing quote that priced this request; not consumed by use, any number of intents may reference it while it stands.
settlement_amounttzero.v1.pay.DecimalThe payment in the settlement asset (USDt): round(local_amount / fx_rate, 2 dp, half-up). Indicative; the binding figure is derived the same way on CreatePaymentIntent.
fx_ratetzero.v1.pay.DecimalStanding quote’s rate, in units of local_currency per 1 USDt.
expires_atgoogle.protobuf.TimestampMoment the quote stops standing, on t-0’s clock; it cannot be referenced after this.

LocalAmount

An amount in the local fiat currency the customer was quoted in. Minor units are t-0’s own rule, not ISO 4217’s: COP, CLP, PYG and JPY are kept in whole units, every other currency at two decimal places.

FieldTypeLabelDescription
valuetzero.v1.pay.DecimalAmount in currency; a value finer than the currency’s minor units is invalid input.
currencystringThree-letter currency code in ISO 4217 form (e.g. COP); not checked against the ISO list.

PaymentAuthorizedRequest

FieldTypeLabelDescription
payment_intent_iduint64Intent that was authorized.
payment_refstringEcho of the CreatePaymentIntent payment_ref, so the merchant order can be matched by it or by payment_intent_id.
usdt_on_chaintzero.v1.pay.UsdtOnChainPayment
approved_atgoogle.protobuf.TimestampMoment t-0 accepted the Issuer’s report and authorized the payment.
settlement_amounttzero.v1.pay.DecimalUSDt the deposit credited; equals the intent’s settlement_amount, stated so the Acquirer’s ledger derives nothing.
received_atgoogle.protobuf.TimestampMoment the Issuer observed the deposit final on-chain.
fiat_settlementFiatSettlementThe fiat terms locked on CreatePaymentIntent; present only for an Acquirer settled in fiat.

PaymentAuthorizedResponse

This message has no fields defined.

PaymentExpiredRequest

The QR window lapsed on t-0’s clock with no payment reported; the payment is over and nothing will settle for it.

FieldTypeLabelDescription
payment_intent_iduint64Intent that expired.
payment_refstringEcho of the CreatePaymentIntent payment_ref, alongside payment_intent_id.
expired_atgoogle.protobuf.TimestampMoment the intent expired on t-0’s clock.
fiat_settlementFiatSettlementThe fiat terms locked on CreatePaymentIntent; present only for an Acquirer settled in fiat.

PaymentExpiredResponse

This message has no fields defined.

PaymentFailedRequest

A customer deposit against this intent will not settle and the intent is terminally failed: clear the pending order and drop the QR. Sent only while the QR window is still open; once an intent has expired, its expiry notice is the last word on that payment.

FieldTypeLabelDescription
payment_intent_iduint64Intent the deposit was made against.
payment_refstringEcho of the CreatePaymentIntent payment_ref, alongside payment_intent_id.
amount_usdttzero.v1.pay.DecimalUSDt the deposit credited, as reported by the Issuer; may differ from the intent’s settlement_amount.
usdt_on_chaintzero.v1.pay.UsdtOnChainPayment
dispositiontzero.v1.pay.FundsDispositionWhere the funds go, so the merchant can tell the customer what to expect.
reasontzero.v1.pay.PaymentFailureReasonWhy the Issuer will not process the deposit, so the merchant can tell the customer.
failed_atgoogle.protobuf.TimestampMoment the intent became terminally failed.
fiat_settlementFiatSettlementThe fiat terms locked on CreatePaymentIntent; present only for an Acquirer settled in fiat.

PaymentFailedResponse

This message has no fields defined.

SettlementCompletedRequest

FieldTypeLabelDescription
settlement_iduint64t-0’s id for this on-chain settlement; the Acquirer dedupes on it.
settlement_amounttzero.v1.pay.DecimalUSDt amount that reached the Acquirer’s wallet.
settled_payment_intent_idsuint64repeatedIntents this settlement clears.
settled_atgoogle.protobuf.TimestampMoment t-0 verified the settlement final on-chain.
settlementtzero.v1.pay.OnChainSettlementDetailsThe on-chain USDt transfer that reached the Acquirer’s registered wallet.
acquirer_iduint64t-0’s id for the Acquirer this settlement is addressed to.

SettlementCompletedResponse

This message has no fields defined.

SettlementInitiatedRequest

FieldTypeLabelDescription
fiat_settlement_iduint64t-0’s id for this fiat settlement; the Acquirer dedupes on it.
lp_iduint64t-0’s id for the LP that sent the transfer; scopes bank_transfer_ref.
bank_transfer_refstringReference the LP put on the bank-rails transfer; matched against the statement.
settled_payment_intent_idsuint64repeatedIntents this settlement clears; the Acquirer maps them to its own payment_refs.
localLocalAmountFiat amount and currency of the bank-rails transfer the LP reported; SettlementReceived must confirm exactly this figure.
acquirer_iduint64t-0’s id for the Acquirer this settlement is addressed to.
initiated_atgoogle.protobuf.TimestampMoment t-0 accepted the LP’s fiat-settlement report.
settled_atgoogle.protobuf.TimestampMoment the LP reported completing the bank-rails transfer — the value date to match on the statement.

SettlementInitiatedResponse

This message has no fields defined.

SettlementReceivedRequest

FieldTypeLabelDescription
lp_iduint64t-0’s id for the LP that sent the transfer, echoed from SettlementInitiated.
bank_transfer_refstringReference on the received transfer, matched against the bank statement.
local_currencystringISO 4217 currency credited.
amount_receivedtzero.v1.pay.DecimalFiat amount credited to the Acquirer’s account.
received_atgoogle.protobuf.TimestampMoment the funds landed in the Acquirer’s account.

SettlementReceivedResponse

FieldTypeLabelDescription
acceptedSettlementReceivedResponse.Accepted
rejectedSettlementReceivedResponse.Rejected

SettlementReceivedResponse.Accepted

The confirmation is recorded and the covered intents are settled.

This message has no fields defined.

SettlementReceivedResponse.Rejected

The confirmation was not recorded and the covered intents stay authorized; resubmit the same (lp_id, bank_transfer_ref) with corrected fields.

FieldTypeLabelDescription
reasonSettlementReceivedResponse.Rejected.Reason

CreatePaymentIntentResponse.Failure.Reason

NameNumberDescription
REASON_UNSPECIFIED0
REASON_ISSUER_UNAVAILABLE10The Issuer could not be reached, or returned no usable instructions.
REASON_ADDRESS_POOL_EMPTY20The Issuer has no free one-time deposit addresses.
REASON_AMOUNT_OUT_OF_RANGE40The amount falls outside the acceptable range.
REASON_QUOTE_EXPIRED50The referenced quote no longer stands.
REASON_QUOTE_INSUFFICIENT_HEADROOM70The quote’s remaining validity is too short to guarantee execution before it expires.
REASON_QUOTE_UNAVAILABLE80No standing quote for the payment’s currency right now (quote_id omitted).

GetPaymentQuoteResponse.Failure.Reason

NameNumberDescription
REASON_UNSPECIFIED0
REASON_QUOTE_UNAVAILABLE10No standing quote available for this currency right now.

SettlementReceivedResponse.Rejected.Reason

NameNumberDescription
REASON_UNSPECIFIED0
REASON_AMOUNT_MISMATCH10amount_received does not equal the settlement_amount announced on SettlementInitiated.
REASON_UNKNOWN_TRANSFER20No fiat settlement matches the (lp_id, bank_transfer_ref) pair.
REASON_CURRENCY_MISMATCH30local_currency is not the currency announced on SettlementInitiated for the matched transfer.