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. This method is idempotent, meaning that multiple calls with the same parameters will have no additional effect. |
| GetPayoutQuote | GetPayoutQuoteRequest | GetPayoutQuoteResponse | 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. PayIn currency and QuoteId are the optional parameters. If the payIn currency is not specified, the network will use USD as the default payIn currency, and considering the amount in USD. If specified, it must be a valid currency code - in this case the network will try to find the payIn quote for the specified currency and considering the band from the provider initiated this request. So this is only possible, if this provider already submitted the payIn quote for the specified currency using UpdateQuote rpc. 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. This method is idempotent, meaning that multiple calls with the same parameters will have no additional effect. |
| UpdatePayout | UpdatePayoutRequest | UpdatePayoutResponse | Inform the network that a payout has been completed or failed. 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. This method is idempotent, meaning that multiple calls with the same parameters will have no additional effect. |
| CreatePayIn | CreatePayInRequest | CreatePayInResponse | Inform the network that the provider has received a pay-in from the user. This method is idempotent, meaning that multiple calls with the same parameters will have no additional effect. |
| GetKycData | GetKycDataRequest | GetKycDataResponse | Retrieve KYC verification data (e.g., SumSub token) for a person involved in the payment. |
Requests And Response Types link
CreatePayInRequest link
CreatePayInResponse link
This message has no fields defined.
CreatePaymentRequest link
| Field | Type | Label | Description |
|---|
| payment_client_id | string | | unique client generated id for this payment |
| payout_currency | string | | ISO 4217 currency code, e.g. EUR, GBP, etc. in which the payout should be made |
| amount | tzero.v1.common.Decimal | | amount in the payin currency, by default USD (if the payIn currency is not specified) |
| payin_currency | string | optional | if not specified, USD is used for calculations |
| sender | CreatePaymentRequest.Sender | | |
| recipient | CreatePaymentRequest.Recipient | | |
| quote_id | QuoteId | optional | if specified, must be a valid quoteId that was previously returned by the GetPayoutQuote method |
CreatePaymentRequest.PrivatePerson link
Work in progress
CreatePaymentRequest.Recipient link
Work in progress
CreatePaymentRequest.Sender link
Work in progress
CreatePaymentResponse link
| Field | Type | Label | Description |
|---|
| payment_client_id | string | | client generated id supplied in the request |
| success | CreatePaymentResponse.Success | | Success response - means the payment was accepted, but the payout is not yet completed. This means, the network found a suitable quote for the payout currency and amount, and instructed the payout provider to process the payout. |
| 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.Failure link
This message has no fields defined.
CreatePaymentResponse.Success link
| Field | Type | Label | Description |
|---|
| payment_id | int64 | | payment id assigned by the network |
GetKycDataRequest link
| Field | Type | Label | Description |
|---|
| person_id | string | | |
GetKycDataResponse link
| Field | Type | Label | Description |
|---|
| sumsub_kyc_token | string | | |
GetPayoutQuoteRequest link
| Field | Type | Label | Description |
|---|
| payout_currency | string | | ISO 4217 currency code, e.g. EUR, GBP, etc. in which the payout should be made |
| amount | tzero.v1.common.Decimal | | amount in quote currency, only USD is supported |
| quote_type | QuoteType | | type of the quote, e.g. real-time or guaranteed |
GetPayoutQuoteResponse link
| Field | Type | Label | Description |
|---|
| quote_id | int64 | | unique identifier of the quote within the specified provider |
| provider_id | int32 | | provider id of the quote |
UpdatePayoutRequest link
| Field | Type | Label | Description |
|---|
| payment_id | int64 | | payment id assigned by the network, this is the same payment id that was provided in the PayoutRequest |
| payout_id | int64 | | payout id assigned by the payout provider, this is the same payout id that was provided in the PayoutRequest |
| success | UpdatePayoutRequest.Success | | success response with the details of the payout |
| failure | UpdatePayoutRequest.Failure | | failure response with the reason of the failure |
UpdatePayoutRequest.Failure link
This message has no fields defined.
UpdatePayoutRequest.Success link
This message has no fields defined.
UpdatePayoutResponse link
This message has no fields defined.
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 | |
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) |
Scalar Value Types link
| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
|---|
| double | | double | double | float | float64 | double | float | Float |
| float | | float | float | float | float32 | float | float | Float |
| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) |
| uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) |
| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) |
| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum |
| sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass |
| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) |
| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |