NetworkService link
This service is used by provider to interact with the Network, e.g. push quotes and initiate 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 | Used by the provider to publish pay-in and pay-out quotes (FX rates) into the network. These quotes include 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 that was previously returned by the GetPayoutQuote method. If the quoteId is not specified, the network will try to find a suitable quote for the payout currency and amount, same way as GetPayoutQuote rpc. |
| ConfirmPayout | ConfirmPayoutRequest | ConfirmPayoutResponse | Inform the network that a payout has been completed. This endpoint is called by the payout provider, specifying the payment ID and payout ID, which was provided when the payout request was made to this provider. |
| FinalizePayout | FinalizePayoutRequest | FinalizePayoutResponse | |
| CompleteManualAmlCheck | CompleteManualAmlCheckRequest | CompleteManualAmlCheckResponse | Pay-out provider reports the result of manual AML check. This endpoint is called after the manual AML check is completed. The network will find the new best quotes for the payment and will return the updated settlement/payout amount along with the updated quotes in the response. |
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 the GetPayoutQuote method otherwise last available quote will be used |
| travel_rule_data | CreatePaymentRequest.TravelRuleData | optional | 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. |
CreatePaymentResponse link
| Field | Type | Label | Description |
|---|
| payment_client_id | string | | client generated id supplied in the request |
| accepted | CreatePaymentResponse.Accepted | | Accepted response - the payment was accepted by the network and it’s going to be passed to payout provider. Means the network found a suitable quote for the payout 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 | | Failure response - means the payment was not accepted, e.g. the network could not find a suitable quote for the payout 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 | | Success response - the network found a suitable quote for the provided parameters and with available credit or pre-settlement option. The returned quoteId can be used later to call the create payment endpoint. |
| 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. Includes has_sufficient_credit flag to indicate if quote 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. |
| pay_in | UpdateQuoteRequest.Quote | repeated | Zero or more quotes for pay-in 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 | | max amount of USD this quote is applicable for. Please look into documentation for valid amounts. |
| rate | tzero.v1.common.Decimal | | USD/currency rate |
UpdateQuoteResponse link
This message has no fields defined.
CreatePaymentResponse.Failure.Reason link
| Name | Number | Description |
|---|
| REASON_UNSPECIFIED | 0 | |
| REASON_QUOTE_NOT_FOUND | 10 | No matching quote for the specified payout currency found or provider limits would exceed by processing this payment |
| REASON_CREDIT_OR_PREDEPOSIT_REQUIRED | 20 | Payments with amount in pay out currency require available credit or pre-deposit |
GetQuoteResponse.Failure.Reason link
| Name | Number | Description |
|---|
| REASON_UNSPECIFIED | 0 | |
| REASON_QUOTE_NOT_FOUND | 10 | No matching quote par for the specified payout currency found or provider limits would exceed by processing this payment |
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) |