ProviderService link
Provider surface for executing payouts and receiving payment, limit, and ledger updates.
All methods of this service must be idempotent, meaning they are safe to retry and multiple calls with the same parameters must not have additional effect.
| Method Name | Request Type | Response Type | Description |
|---|
| PayOut | PayoutRequest | PayoutResponse | Execute a payout to the recipient. This method should be idempotent, meaning that multiple calls with the same parameters will have no additional effect. |
| UpdatePayment | UpdatePaymentRequest | UpdatePaymentResponse | Reports the current status of a payment — either a success or a failure. This method should be idempotent, meaning that multiple calls with the same parameters will have no additional effect. |
| UpdateLimit | UpdateLimitRequest | UpdateLimitResponse | Delivers updated credit limit and credit usage. |
| AppendLedgerEntries | AppendLedgerEntriesRequest | AppendLedgerEntriesResponse | Carries ledger-entry updates for the provider’s accounts. It can be used to keep track of the provider’s exposure to other participants and other important financial events. (see the list in the message below) |
| ApprovePaymentQuotes | ApprovePaymentQuoteRequest | ApprovePaymentQuoteResponse | Approves the final pay-out quotes — the “Last Look” before payment executes. Applies after a manual AML check completes, when one was required. |
Requests And Response Types link
AppendLedgerEntriesRequest link
| Field | Type | Label | Description |
|---|
| transactions | AppendLedgerEntriesRequest.Transaction | repeated | This is a list of transactions that were appended to the ledger of the provider. The transaction_id should be used to identify the transaction and ensure that it is processed only once. |
AppendLedgerEntriesRequest.LedgerEntry link
| Field | Type | Label | Description |
|---|
| account_owner_id | uint32 | | 1 is network account, others are ids of participants |
| account_type | AppendLedgerEntriesRequest.AccountType | | account_type is the type of the account that the entry belongs to. It is used to categorize the entries and understand the nature of the financial event. |
| debit | tzero.v1.common.Decimal | | debit is the amount that was debited from the account. If the entry is a credit, this field should be 0. |
| credit | tzero.v1.common.Decimal | | credit is the amount that was credited to the account. If the entry is a debit, this field should be 0. |
AppendLedgerEntriesRequest.Transaction link
AppendLedgerEntriesRequest.Transaction.FeeSettlement link
| Field | Type | Label | Description |
|---|
| fee_settlement_id | uint64 | | |
| amount_usd | tzero.v1.common.Decimal | | Fee settlement amount in USD, truncated to cents. Equals the SETTLEMENT_OUT credit this fee produces. The fee always flows to the network from the provider receiving this callback, so the descriptor carries no provider_id. |
AppendLedgerEntriesRequest.Transaction.Payout link
| Field | Type | Label | Description |
|---|
| payment_id | uint64 | | |
AppendLedgerEntriesRequest.Transaction.PiFundsReceived link
Funds were received from the payer by the pay-in provider, creating the
inter-provider obligation to settle. The descriptor fields mirror values
the entries already encode; the entries remain authoritative for balances.
Only payment_intent_id is guaranteed non-zero; the remaining descriptor
fields may be zero-valued.
| Field | Type | Label | Description |
|---|
| payment_intent_id | uint64 | | |
| pay_in_provider_id | uint32 | | |
| beneficiary_provider_id | uint32 | | |
| settlement_amount | tzero.v1.common.Decimal | | no validation: descriptor mirror of the entries, which are authoritative for balances |
| beneficiary_fee | tzero.v1.common.Decimal | | no validation: descriptor mirror of the entries, which are authoritative for balances |
| pay_in_fee | tzero.v1.common.Decimal | | no validation: descriptor mirror of the entries, which are authoritative for balances |
AppendLedgerEntriesRequest.Transaction.ProviderSettlement link
An on-chain settlement between two providers. The on-chain fields let the
counterparty reconcile the settlement against the USDT transfer actually
sent. The settlement participants and USD amount below are authoritative;
the ledger entries remain authoritative for the resulting account balances.
Each recipient’s counterparty is whichever provider id is not its own.
| Field | Type | Label | Description |
|---|
| settlement_id | uint64 | | |
| blockchain | tzero.v1.common.Blockchain | | no validation: observed settlement chain; informational reconciliation descriptor. defined_only intentionally omitted: this flows network->provider and the receiving provider may lag common.Blockchain, so defined_only would reject an append carrying a newly-added chain. |
| tx_hash | string | | no validation: observed on-chain transaction hash; informational descriptor for reconciliation, not a gating constraint |
| on_chain_amount | tzero.v1.common.Decimal | | Observed on-chain (USDT) amount; differs from the settlement amount the ledger entries encode (full precision vs. truncated to cents). |
| sender_provider_id | uint32 | | Provider whose ledger records this settlement as SETTLEMENT_OUT (the sender). |
| receiver_provider_id | uint32 | | Provider whose ledger records this settlement as SETTLEMENT_IN (the receiver). |
| amount_usd | tzero.v1.common.Decimal | | Settlement amount in USD, truncated to cents. Differs from on_chain_amount (full-precision USDT); equals the settlement ledger leg’s credit/debit. |
AppendLedgerEntriesResponse link
This message has no fields defined.
ApprovePaymentQuoteRequest link
| Field | Type | Label | Description |
|---|
| payment_id | uint64 | | Payment id assigned by the network, identifying the payment being re-priced. |
| pay_out_quote_id | int64 | | Updated pay-out quote id the approval applies to. |
| pay_out_rate | tzero.v1.common.Decimal | | Exchange rate the network applied to this payout, pay-out currency per USD. |
| pay_out_amount | tzero.v1.common.Decimal | | Updated payout amount in the pay-out currency. |
| settlement_amount | tzero.v1.common.Decimal | | Updated settlement amount in USD. |
| pay_out_fix | tzero.v1.common.Decimal | | Fixed charge in USD included in the settlement amount for this payout. |
ApprovePaymentQuoteResponse link
ApprovePaymentQuoteResponse.Accepted link
This message has no fields defined.
ApprovePaymentQuoteResponse.Rejected link
This message has no fields defined.
PayoutRequest link
| Field | Type | Label | Description |
|---|
| payment_id | uint64 | | Payment id assigned by the network. Store it to reference this payment in FinalizePayout later. |
| payout_id | uint64 | | Deprecated. payout_id is deprecated now, since it’s 1->1 mapping between payout_id and payment_id |
| currency | string | | currency of the payout (participant could support multiple currencies) This is the currency in which the payout should be made. |
| client_quote_id | string | | client quote id of the quote used for this payout (the provider provides the quote IDs in the UpdateQuote rpc) This is the identifier of the quote that was used to calculate the payout amount. |
| amount | tzero.v1.common.Decimal | | amount in currency of the payout This is the amount that should be paid out to the recipient. |
| payout_details | tzero.v1.common.PaymentDetails | optional | Payment details specifying how the payout should be made (bank transfer, crypto transfer, etc.). |
| pay_in_provider_id | uint32 | | Pay-in provider id which initiated the pay out. |
| travel_rule_data | PayoutRequest.TravelRuleData | | |
PayoutRequest.TravelRuleData link
| Field | Type | Label | Description |
|---|
| originator | ivms101.Person | repeated | the natural or legal person that requests payment with originating provider |
| beneficiary | ivms101.Person | repeated | the natural or legal person or legal arrangement who is identified by the originator as the receiver of the requested payment. |
| originator_provider | ivms101.Person | optional | IVMS101 travel rule data of the originating provider’s legal entity. Taken from the originator entity in the corresponding CreatePaymentRequest. |
PayoutResponse link
| Field | Type | Label | Description |
|---|
| beneficiary_provider_legal_entity_id | uint32 | optional | Legal entity ID of the payout provider handling this transaction. Required when the provider has multiple registered legal entities. If the provider has a single entity, this field may be omitted. |
| accepted | PayoutResponse.Accepted | | Accepted response - means the payout was accepted by the pay-out provider and pay-out provider is obligated to make a pay-out. |
| failed | PayoutResponse.Failed | | Failure response - means the payout was not executed successfully, e.g. the payout provider could not process the payout. |
| manual_aml_check | PayoutResponse.ManualAmlCheck | | Manual AML check required - means the payout provider requires additional Anti-Money Laundering (AML) verification before the payment can proceed. The pay-out provider will need to perform the manual AML check and then call CompleteManualAmlCheck rpc with the result of the check. |
PayoutResponse.Accepted link
This message has no fields defined.
PayoutResponse.Failed link
PayoutResponse.ManualAmlCheck link
This message has no fields defined.
UpdateLimitRequest link
All the amounts are in USD
| Field | Type | Label | Description |
|---|
| limits | UpdateLimitRequest.Limit | repeated | can contain one or more Limit messages, each representing a credit limit for a specific counterparty provider. |
UpdateLimitRequest.Limit link
| Field | Type | Label | Description |
|---|
| version | int64 | | Incrementally growing for the provider - same as in Ledger. |
| counterpart_id | int32 | | the Id of the counterparty provider, e.g. the provider that is providing the credit limit. It’s usually the payOut provider, which provides the credit line to the payIn provider. |
| payout_limit | tzero.v1.common.Decimal | | payout_limit = credit_limit - credit_usage - reserve, negative value means credit limit is exceeded, e.g. if counterparty decreased credit limit. no validation: any sign is valid. |
| credit_limit | tzero.v1.common.Decimal | | This is the credit limit that the counterparty is willing to extend to the provider. |
| credit_usage | tzero.v1.common.Decimal | | This is the credit usage that the provider has used so far. It is the sum of all payouts made by the provider minus the settlement net (settlement balance). It could be negative if the provider has received more in settlements than made payouts. |
| reserve | tzero.v1.common.Decimal | | This indicates how much is reserved for the pending payments (not yet finalized) |
UpdateLimitResponse link
Empty message - means no response is needed.
This message has no fields defined.
UpdatePaymentRequest link
| Field | Type | Label | Description |
|---|
| payment_id | uint64 | | payment_id is a payment id in the T-0 network. The upper bound is the largest value the network assigns, so a provider can store it in a signed 64-bit column. |
| payment_client_id | string | | payment_client_id is a payment id assigned by the client, this is the same id that was provided in the CreatePaymentRequest. |
| accepted | UpdatePaymentRequest.Accepted | | Accepted response - means the payout was accepted by the pay-out provider and pay-out provider is obligated to make a pay-out. |
| failed | UpdatePaymentRequest.Failed | | Payment failed and would not be retried. |
| confirmed | UpdatePaymentRequest.Confirmed | | Confirmed response - final state meaning the payout was executed successfully and the payment is now complete. This happens when the payout is successfully processed by the payout provider, and the payment was made to the recipient. |
| manual_aml_check | UpdatePaymentRequest.ManualAmlCheck | | In case of manual AML check, pay-out provider needs to perform additional checks and then call CompleteManualAmlCheck rpc with the result of the check. |
UpdatePaymentRequest.Accepted link
UpdatePaymentRequest.Accepted.TravelRuleData link
UpdatePaymentRequest.Confirmed link
| Field | Type | Label | Description |
|---|
| paid_out_at | google.protobuf.Timestamp | | Time of the payout. No validation: the field is absent when the exact payout time is not known, so treat absence as unknown and fall back to the provider’s own recorded time for this update rather than rejecting the callback. |
| receipt | tzero.v1.common.PaymentReceipt | optional | Payment receipt might contain metadata about payment recognizable by pay-in provider. |
UpdatePaymentRequest.Failed link
UpdatePaymentRequest.ManualAmlCheck link
This message has no fields defined.
UpdatePaymentResponse link
This message has no fields defined.
AppendLedgerEntriesRequest.AccountType link
| Name | Number | Description |
|---|
| ACCOUNT_TYPE_UNSPECIFIED | 0 | |
| ACCOUNT_TYPE_BALANCE | 20 | |
| ACCOUNT_TYPE_PAY_IN | 40 | |
| ACCOUNT_TYPE_PAY_OUT | 50 | |
| ACCOUNT_TYPE_FEE_EXPENSE | 60 | Reflects the fees that the provider has to pay for the services provided by the network. |
| ACCOUNT_TYPE_SETTLEMENT_IN | 80 | |
| ACCOUNT_TYPE_SETTLEMENT_OUT | 90 | |
| ACCOUNT_TYPE_PAYMENT_INTENT_IN | 100 | |
| ACCOUNT_TYPE_PAYMENT_INTENT_OUT | 110 | |
PayoutResponse.Failed.Reason link
| Name | Number | Description |
|---|
| REASON_UNSPECIFIED | 0 | |
UpdatePaymentRequest.Failed.Reason link
Additive-only. Consumers must treat unknown values as UNSPECIFIED.
| Name | Number | Description |
|---|
| REASON_UNSPECIFIED | 0 | |
| REASON_NO_QUOTE_AFTER_AML_APPROVAL | 1 | AML review completed, but the pay-out provider no longer has a valid quote available. |
| REASON_QUOTE_REJECTED_AFTER_AML_APPROVAL | 2 | AML review completed and a new quote was required, but the pay-in provider rejected the updated quote (e.g. due to rate change after AML delay). |
| REASON_AML_RISK_CHECK_FAILED | 3 | Payment was rejected by the pay-out provider because the AML / risk checks failed. |
| REASON_CREDIT_LIMIT_EXCEEDED_AFTER_AML_APPROVAL | 4 | AML review completed and a new quote was found, but the updated settlement amount exceeds the credit limit between the pay-in and pay-out providers. |
| REASON_REJECTED_BY_BENEFICIARY | 5 | Pay-out provider rejected the initial PayOut request (no AML check involved). |
| REASON_FINALIZE_FAILURE | 6 | Pay-out provider accepted initially, then reported failure via FinalizePayout (e.g. payment rails rejected). |