IssuerCallbackService link
Issuer-implemented endpoint t-0 calls to reserve deposit addresses and obtain
the deposit options for an intent.
IssuerService link
t-0 endpoints the Issuer calls to report what it did with a customer deposit
and the USDt settlements that clear the intents it covers.
Requests And Response Types link
CreatePaymentInstructionsRequest link
| Field | Type | Label | Description |
|---|
| payment_intent_id | uint64 | | Intent the deposit addresses are reserved for. |
| acquirer_id | uint64 | | t-0’s stable id for the Acquirer; the Issuer resolves its settlement wallet from it. |
| amount_usdt | tzero.v1.pay.Decimal | | USDt amount the reserved addresses should accept. |
| expires_at | google.protobuf.Timestamp | | Absolute moment t-0 requires the reservation held until, on t-0’s clock. |
CreatePaymentInstructionsResponse link
CreatePaymentInstructionsResponse.Failure link
CreatePaymentInstructionsResponse.Success link
CreatePaymentInstructionsResponse.Success.DepositOption link
One selectable deposit option: the chain, the one-time address reserved on it, and the USDt token contract.
| Field | Type | Label | Description |
|---|
| chain | tzero.v1.pay.Blockchain | | Chain this deposit option pays on. |
| deposit_address | string | | One-time deposit address reserved for this intent on chain. |
| token_contract | string | | USDt token contract on chain the deposit must be made in. |
PaymentReceivedRequest link
PaymentReceivedRequest.Authorized link
The deposit passed the Issuer’s screening. Once t-0 accepts the report the
Issuer owns the on-chain risk and is obligated to settle the intent.
This message has no fields defined.
PaymentReceivedRequest.Unprocessable link
The Issuer will not process the deposit and the intent ends failed. The
disposition says where the funds go and is final when reported.
PaymentReceivedResponse link
PaymentReceivedResponse.Accepted link
The disposition is recorded.
This message has no fields defined.
PaymentReceivedResponse.Rejected link
The report was not recorded.
SettlementSentRequest link
| Field | Type | Label | Description |
|---|
| settlement_ref | string | | Issuer’s id for this USDt settlement; idempotency key, unique per Issuer. |
| amount_usdt | tzero.v1.pay.Decimal | | Total USDt settled across the covered intents. |
| settlement | tzero.v1.pay.OnChainSettlementDetails | | On-chain transaction, chain, and registered destination wallet for this settlement. |
| settled_payment_intent_ids | uint64 | repeated | Intents this settlement clears, treated as a set; per-intent amounts come from t-0’s ledger. |
| settled_at | google.protobuf.Timestamp | | Moment the Issuer broadcast the settlement transaction. |
SettlementSentResponse link
SettlementSentResponse.Accepted link
This message has no fields defined.
SettlementSentResponse.Rejected link
The report is not accepted. For a first-time ref the settlement is not recorded;
for a CONFLICT on an already-accepted ref the original settlement stands.
ON_CHAIN_UNCONFIRMED clears on its own and the report is resubmitted under the
same settlement_ref once the transaction confirms; the other reasons open a manual
reconciliation with t-0, and the corrected report follows from it.
CreatePaymentInstructionsResponse.Failure.Reason link
| Name | Number | Description |
|---|
| REASON_UNSPECIFIED | 0 | |
| REASON_ADDRESS_POOL_EMPTY | 20 | No free one-time deposit addresses. |
| REASON_AMOUNT_OUT_OF_RANGE | 40 | The amount falls outside the acceptable range. |
PaymentReceivedResponse.Rejected.Reason link
| Name | Number | Description |
|---|
| REASON_UNSPECIFIED | 0 | |
| REASON_INTENT_EXPIRED | 10 | Processing started after expires_at on t-0’s clock. |
| REASON_UNKNOWN_INTENT | 20 | No such intent exists, or another Issuer serves it. |
| REASON_AMOUNT_MISMATCH | 30 | amount_usdt is not exactly the amount_usdt commanded on CreatePaymentInstructions; authorized outcome only. |
| REASON_TRANSFER_RECORDED_FOR_ANOTHER_INTENT | 40 | The transfer is already another intent’s recorded deposit; no refund or disposition action follows — reconciled out of band. |
SettlementSentResponse.Rejected.Reason link
| Name | Number | Description |
|---|
| REASON_UNSPECIFIED | 0 | |
| REASON_ON_CHAIN_UNCONFIRMED | 10 | The on-chain transaction is not yet confirmed. SettlementSent does not return this reason. |
| REASON_AMOUNT_MISMATCH | 20 | The confirmed amount does not equal amount_usdt or the covered intents’ sum. |
| REASON_WRONG_DESTINATION | 30 | destination_address (or its chain) is not the expected registered (chain, address) pair for the mode. |
| REASON_INTENT_NOT_SETTLEABLE | 40 | A listed intent is unknown, not authorized, or already covered. Fiat mode also accepts a settled intent, whose Acquirer confirmation may land before this reimbursement. |
| REASON_SETTLEMENT_REF_CONFLICT | 50 | Either this on-chain transfer is already recorded under a different settlement_ref, or this settlement_ref is already recorded with different identity fields. The stored settlement stands; a genuinely different transfer needs a different ref. |