NetworkService link
Network surface for publishing quotes and initiating pay-out payments.
All methods of this service are idempotent, meaning they are safe to retry and multiple calls with the same parameters will have no additional effect.
| Method Name | Request Type | Response Type | Description |
|---|
| UpdateQuote | UpdateQuoteRequest | UpdateQuoteResponse | Publishes pay-in and pay-out quotes (FX rates) into the network. Quotes carry tiered pricing bands and an expiration timestamp. |
| GetQuote | GetQuoteRequest | GetQuoteResponse | Request the best available quote for a payout in a specific currency, for a given amount. If the payout quote exists, but the credit limit is exceeded, this quote will not be considered. |
| CreatePayment | CreatePaymentRequest | CreatePaymentResponse | Submit a request to create a new payment for the specified pay-out currency. QuoteId is the optional parameter. If the quoteId is specified, it must be a valid quoteId previously returned by GetQuote. If the quoteId is not specified, a suitable quote is selected for the pay-out currency and amount, as GetQuote does. |
| ConfirmPayout | ConfirmPayoutRequest | ConfirmPayoutResponse | Informs the network that a payout has been completed, specifying the payment ID and payout ID from the original payout request. deprecated, use the FinalizePayout rpc instead. |
| FinalizePayout | FinalizePayoutRequest | FinalizePayoutResponse | Report the final outcome of a payout to the network, identified by the payment id from the original PayoutRequest, as either success (with an optional receipt) or failure with a reason. Supersedes the deprecated ConfirmPayout, which could only signal completion. |
| CompleteManualAmlCheck | CompleteManualAmlCheckRequest | CompleteManualAmlCheckResponse | Reports the result of a manual AML check on a payment. On approval, the response carries the updated settlement/payout amount and quotes. |
Requests And Response Types link
CompleteManualAmlCheckRequest link
CompleteManualAmlCheckRequest.Approved link
This message has no fields defined.
CompleteManualAmlCheckRequest.Rejected link
| Field | Type | Label | Description |
|---|
| reason | string | | |
CompleteManualAmlCheckResponse link
CompleteManualAmlCheckResponse.Approved link
| Field | Type | Label | Description |
|---|
| pay_out_amount | tzero.v1.common.Decimal | | updated amount based on updated quote approved by the pay-in provider |
| settlement_amount | tzero.v1.common.Decimal | | updated settlement amount based on updated quote approved by the pay-in provider |
| pay_out_quote_id | int64 | | unique identifier of the updated pay-out quote |
| pay_out_client_quote_id | string | | client_quote_id of the updated pay-out quote assigned by pay-out provider |
CompleteManualAmlCheckResponse.Rejected link
Rejected means that the updated quotes were rejected by pay-in provider, and the payout provider should not proceed
with the payout.
This message has no fields defined.
ConfirmPayoutRequest link
| Field | Type | Label | Description |
|---|
| payment_id | uint64 | | payment id assigned by the network, this is the same payment id that was provided in the PayoutRequest |
| payout_id | uint64 | | Deprecated. deprecated, this is 1->1 mapping between payment and payout ids |
| receipt | tzero.v1.common.PaymentReceipt | optional | Payment receipt might contain metadata about payment recognizable by pay-in provider. |
ConfirmPayoutResponse link
This message has no fields defined.
CreatePaymentRequest link
| Field | Type | Label | Description |
|---|
| payment_client_id | string | | unique client generated id for this payment |
| amount | PaymentAmount | | payment amount - should be either pay-out amount or settlement amount |
| currency | string | | pay-out currency |
| payment_details | tzero.v1.common.PaymentDetails | | pay-out payment details |
| quote_id | QuoteId | optional | if specified, must be a valid quoteId that was previously returned by GetQuote otherwise last available quote will be used |
| travel_rule_data | CreatePaymentRequest.TravelRuleData | | travel rule data |
CreatePaymentRequest.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_legal_entity_id | uint32 | optional | Legal entity ID of the originating provider. Required when the provider has multiple registered legal entities. If the provider has a single entity, this field may be omitted. |
CreatePaymentResponse link
| Field | Type | Label | Description |
|---|
| payment_client_id | string | | client generated id supplied in the request |
| accepted | CreatePaymentResponse.Accepted | | The payment was accepted and will be passed to the payout provider. A suitable quote was found for the pay-out currency and amount. |
| settlement_required | CreatePaymentResponse.SettlementRequired | | Deprecated. Deprecated: Settlement required response - presettlement flow is being removed. This response type will no longer be returned. |
| failure | CreatePaymentResponse.Failure | | The payment was not accepted — e.g. no suitable quote exists for the pay-out currency and amount, or the credit limit is exceeded for the available quotes. |
CreatePaymentResponse.Accepted link
CreatePaymentResponse.Failure link
CreatePaymentResponse.SettlementRequired link
Deprecated: presettlement flow is being removed. This message will no longer be used.
| Field | Type | Label | Description |
|---|
| payment_id | uint64 | | payment ID assigned by the network |
| settlement_amount | tzero.v1.common.Decimal | | |
| payout_provider_id | uint32 | | payout provider id with the best quote selected for this payment |
FinalizePayoutRequest link
FinalizePayoutRequest.Failure link
| Field | Type | Label | Description |
|---|
| reason | string | | |
FinalizePayoutRequest.Success link
| Field | Type | Label | Description |
|---|
| receipt | tzero.v1.common.PaymentReceipt | optional | Payment receipt might contain metadata about payment recognizable by pay-in provider. |
FinalizePayoutResponse link
This message has no fields defined.
GetQuoteRequest link
| Field | Type | Label | Description |
|---|
| amount | PaymentAmount | | payment amount - must be either pay-out amount or settlement amount |
| pay_out_currency | string | | ISO 4217 currency code, e.g. EUR, GBP, etc. in which the payout should be made |
| pay_out_method | tzero.v1.common.PaymentMethodType | | payment method to use for the payout, e.g. bank transfer, card, etc. |
| quote_type | QuoteType | | type of the quote, e.g. real-time |
GetQuoteResponse link
| Field | Type | Label | Description |
|---|
| success | GetQuoteResponse.Success | | A suitable quote was found for the provided parameters, with available credit or pre-settlement option. Use the returned quoteId to call CreatePayment. |
| failure | GetQuoteResponse.Failure | | Failure response - means the quote was not found for the specified parameters, or provider limits would exceed by processing the payment amount with the specified amount. |
| all_quotes | GetQuoteResponse.ProviderQuote | repeated | All best quotes from providers with credit lines. Each quote is the best rate for that provider for the requested amount. Each quote indicates whether it can be executed immediately. Always returned alongside success/failure - providers can compare alternatives or see options when no executable quote exists. |
GetQuoteResponse.Failure link
GetQuoteResponse.ProviderQuote link
Best quote from a provider with credit line configured.
Contains settlement status and calculated amounts for the payment request.
GetQuoteResponse.ProviderQuote.Settlement link
Settlement details between pay-in and pay-out providers.
All amounts are in USD (settlement currency).
GetQuoteResponse.Success link
PaymentAmount link
Payment amount could be specified either as settlement amount and then converted to corresponding amount of pay-out amount
or as pay-out amount, so that the settlement amount is calculated accordingly
| Field | Type | Label | Description |
|---|
| quote_id | int64 | | unique identifier of the quote within the specified provider |
| provider_id | int32 | | provider id of the quote |
UpdateQuoteRequest link
Base currency is always USD, so the quotes are always in USD/currency format.
| Field | Type | Label | Description |
|---|
| pay_out | UpdateQuoteRequest.Quote | repeated | Zero or more quotes for pay-out operations, each quote must have a unique currency, and one or more bands, with the unique client_quote_id for each band. |
UpdateQuoteRequest.Quote link
UpdateQuoteRequest.Quote.Band link
| Field | Type | Label | Description |
|---|
| client_quote_id | string | | unique client generated id for this band |
| max_amount | tzero.v1.common.Decimal | | Maximum amount of USD this band applies to. |
| rate | tzero.v1.common.Decimal | | USD/currency rate |
| fix | tzero.v1.common.Decimal | optional | Fixed charge in USD applied per transfer on top of the exchange rate. This covers payment method costs (e.g. wire transfer fees). Added to the settlement amount: settlement = (amount / rate) + fix. Defaults to 0 when absent — no fixed charge applied. |
UpdateQuoteResponse link
This message has no fields defined.
CreatePaymentResponse.Failure.Reason link
| Name | Number | Description |
|---|
| REASON_UNSPECIFIED | 0 | |
| REASON_QUOTE_NOT_FOUND | 10 | No candidate quote was returned for the requested currency / payment method (e.g. no published quote, all expired, no credit line configured between the providers, or the requested amount exceeds the provider’s max_amount band). |
| REASON_CREDIT_OR_PREDEPOSIT_REQUIRED | 20 | At least one provider quoted, but none has enough credit / prefunding headroom to execute the requested amount. Call GetQuote to inspect all_quotes[].settlement for the per-provider prefunding gap. |
| REASON_AMOUNT_EXCEEDS_QUOTE_BAND | 30 | The pinned quote’s band cannot cover the requested amount. The quote is still live; retry with a smaller amount, split the payment across bands, or request a fresh GetQuote for a quote that covers the full amount. |
| REASON_QUOTE_EXPIRED | 40 | The pinned quote’s expires_at has passed. Auto-retry by calling GetQuote to obtain a fresh quote id and re-submit with it. |
| REASON_QUOTE_ID_UNKNOWN | 50 | The pinned quote id does not exist for the pay-in/pay-out provider pair. Indicates a client-side plumbing bug (stale / mismatched id); no auto-retry will succeed until the client fixes quote propagation. |
GetQuoteResponse.Failure.Reason link
| Name | Number | Description |
|---|
| REASON_UNSPECIFIED | 0 | |
| REASON_QUOTE_NOT_FOUND | 10 | No candidate quote was returned for the requested currency / payment method (e.g. no published quote, all expired, no credit line configured between the providers, or the requested amount exceeds the provider’s max_amount band). |
| REASON_CREDIT_OR_PREDEPOSIT_REQUIRED | 20 | At least one provider quoted, but none has enough credit / prefunding headroom to execute the requested amount. Inspect all_quotes[].settlement for the per-provider prefunding gap. |
QuoteType link
| Name | Number | Description |
|---|
| QUOTE_TYPE_UNSPECIFIED | 0 | |
| QUOTE_TYPE_REALTIME | 1 | real-time quote must be valid at least for 30 seconds (TBD) |