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. Full snapshot: omitted quotes are deleted. |
| 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 that provider’s best effective price for the requested amount: the lowest settlement amount, and on a tie the largest pay-out 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) |