On this page
Payment Intent Network
PaymentIntentService
PaymentIntentService provides Payment Intent APIs for providers.
Payment Intent is a flow where:
- Beneficiary provider creates a payment intent specifying amount/currency
- End-user pays via one of the returned payment options
- Pay-in provider confirms funds received
- Settlement will happen periodically between providers
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| UpdateQuote | UpdateQuoteRequest | UpdateQuoteResponse | Atomically replaces the calling provider’s full pay-in quote set. An empty payment_intent_quotes withdraws all of this provider’s quotes. |
| GetQuote | GetQuoteRequest | GetQuoteResponse | GetQuote returns available quotes for a given currency and amount. Use this to check indicative rates before creating a payment intent, and for the current rates of a created payment intent’s options. The returned quotes show which providers can accept pay-ins and their current rates. Note: Quotes are indicative only. The actual rate used for settlement is determined at the time of ConfirmFundsReceived. |
| GetQuotes | GetQuotesRequest | GetQuotesResponse | Lists the active pay-in quotes the caller can collect against, grouped by currency, then payment method: for each, the pay-in providers permitted to the caller and their tiered rate bands. Indicative — request a priced quote via GetQuote to act on one. |
| CreatePaymentIntent | CreatePaymentIntentRequest | CreatePaymentIntentResponse | Creates a payment intent and returns the pay-in options to present to the end-user. |
| ConfirmFundsReceived | ConfirmFundsReceivedRequest | ConfirmFundsReceivedResponse | Confirms funds landed for a payment intent and locks the binding settlement rate. Business failures return a typed Reject.Reason rather than a Connect transport error. |
Requests And Response Types
ConfirmFundsReceivedRequest
Request to confirm that funds have been received from the end-user.
| Field | Type | Label | Description |
|---|---|---|---|
| payment_intent_id | uint64 | The payment intent ID being confirmed. Must be a valid, pending payment intent. | |
| confirmation_code | string | Confirmation code received in the GetPaymentDetails response along with the payment_intent_id. Guards against confirming the wrong payment intent; a mismatch is rejected with REJECT_REASON_CONFIRMATION_CODE_MISMATCH. | |
| payment_method | tzero.v1.common.PaymentMethodType | The payment method used by the end-user. Must match one of the payment methods returned in CreatePaymentIntentResponse. | |
| transaction_reference | string | Pay-in’s rail-native reference (SEPA EndToEndId, SWIFT UETR, PIX e2e_id) — do not generate. Forwarded to the beneficiary for end-to-end tracking and dispute resolution. | |
| originator_provider_legal_entity_id | uint32 | optional | Legal entity ID of the pay-in provider that received the funds. Required when the provider has multiple registered legal entities. If the provider has a single entity, this field may be omitted. |
ConfirmFundsReceivedResponse
| Field | Type | Label | Description |
|---|---|---|---|
| accept | ConfirmFundsReceivedResponse.Accept | Funds confirmed successfully. Settlement will proceed. | |
| reject | ConfirmFundsReceivedResponse.Reject | Funds receipt rejected. No settlement will occur. |
ConfirmFundsReceivedResponse.Accept
Funds accepted - settlement will proceed. The beneficiary provider will receive a PaymentIntentUpdate notification with settlement details.
| Field | Type | Label | Description |
|---|---|---|---|
| settlement_amount | tzero.v1.common.Decimal | The settlement amount in USD that the pay-in provider owes the beneficiary provider for this payment intent. Locked from the chosen quote at confirm-time as (payment_amount / rate) − fix. | |
| rate | tzero.v1.common.Decimal | USD/ | |
| fix | tzero.v1.common.Decimal | Flat USD charge retained by the pay-in provider per transfer, already subtracted from settlement_amount. Settlement is computed as (payment_amount / rate) − fix. |
ConfirmFundsReceivedResponse.Reject
Funds rejected.
| Field | Type | Label | Description |
|---|---|---|---|
| reason | ConfirmFundsReceivedResponse.Reject.Reason |
CreatePaymentIntentRequest
Request to create a new payment intent.
| Field | Type | Label | Description |
|---|---|---|---|
| external_reference | string | Provider-supplied unique identifier for this payment intent. Used for idempotency - subsequent requests with the same external_reference return the existing payment_intent_id instead of creating a new one. Should be unique per beneficiary provider. | |
| currency | string | Pay-in currency code in ISO 4217 format. The currency that the end-user will pay in. | |
| amount | tzero.v1.common.Decimal | Pay-in amount in the specified currency. The exact fiat amount the end-user should pay. | |
| travel_rule_data | CreatePaymentIntentRequest.TravelRuleData | Travel rule compliance data. Required for regulatory compliance under FATF guidelines. | |
| pay_in_provider_ids | uint32 | repeated | Optional list of pay-in provider IDs to consider. When specified, only quotes from these providers will be used. When empty, all available providers are considered. |
CreatePaymentIntentRequest.TravelRuleData
Travel rule data containing originator information.
| Field | Type | Label | Description |
|---|---|---|---|
| beneficiary | ivms101.Person | repeated | The natural or legal person or legal arrangement who is identified as the receiver of the requested payment. |
| payer | ivms101.Person | optional | Optional travel rule data of the payer |
CreatePaymentIntentResponse
| Field | Type | Label | Description |
|---|---|---|---|
| success | CreatePaymentIntentResponse.Success | Payment intent created successfully with available payment options. | |
| failure | CreatePaymentIntentResponse.Failure | Failed to create payment intent. |
CreatePaymentIntentResponse.Failure
Payment intent creation failed.
| Field | Type | Label | Description |
|---|---|---|---|
| reason | CreatePaymentIntentResponse.Failure.Reason | The reason for failure. | |
| details | string | Human-readable explanation of the failure, for display or logging. Free text, not a stable code; branch on reason. |
CreatePaymentIntentResponse.Success
Payment intent created successfully.
| Field | Type | Label | Description |
|---|---|---|---|
| payment_intent_id | uint64 | Unique identifier for this payment intent. Store this ID to correlate with: - PaymentIntentUpdate notifications delivered later | |
| pay_in_details | PaymentIntentPayInDetails | repeated | Available payment options for the end-user. Present these options to the end-user so they can choose how to pay. Each entry contains the payment details needed to complete the payment. The set of options is fixed at first call and returned unchanged on every idempotent retry, whether or not a live quote still covers it. |
GetQuoteRequest
Request to get indicative quotes for a currency/amount pair.
| Field | Type | Label | Description |
|---|---|---|---|
| currency | string | Pay-in currency code in ISO 4217 format. Examples: “EUR”, “GBP”, “USD”, “KES” | |
| amount | tzero.v1.common.Decimal | Pay-in amount in the specified currency. This is the fiat amount the end-user will pay. | |
| pay_in_provider_ids | uint32 | repeated | Optional list of pay-in provider IDs to filter by. When specified, only quotes from these providers are returned. When empty, quotes from all providers are returned. |
GetQuoteResponse
| Field | Type | Label | Description |
|---|---|---|---|
| success | GetQuoteResponse.Success | ||
| quote_not_found | GetQuoteResponse.QuoteNotFound |
GetQuoteResponse.QuoteNotFound
No providers have active quotes for the requested currency/amount.
This message has no fields defined.
GetQuoteResponse.Success
Quotes were found for the requested currency/amount.
| Field | Type | Label | Description |
|---|---|---|---|
| best_quotes | GetQuoteResponse.Success.IndicativeQuote | repeated | Best quotes per payment method available for the specified currency and amount. |
| all_quotes | GetQuoteResponse.Success.IndicativeQuote | repeated | Available indicative quotes. Each entry represents a different pay-in provider and payment method combination. Use CreatePaymentIntent to get the actual payment details for making a payment. |
GetQuoteResponse.Success.IndicativeQuote
Represents an indicative quote from a pay-in provider.
| Field | Type | Label | Description |
|---|---|---|---|
| payment_method | tzero.v1.common.PaymentMethodType | The payment method type (e.g., SEPA, SWIFT, mobile money). | |
| provider_id | uint32 | The T-0 provider ID of the pay-in provider offering this quote. | |
| indicative_rate | tzero.v1.common.Decimal | Indicative exchange rate USD/XXX (base currency is always USD). Note: This is indicative only. The actual rate is determined when pay-in provider calls ConfirmFundsReceived | |
| indicative_fix | tzero.v1.common.Decimal | Indicative fixed charge in USD retained by the pay-in provider per transfer. Settlement is calculated as (amount / indicative_rate) - indicative_fix. Indicative only: the actual fix is locked in at ConfirmFundsReceived time. |
GetQuotesRequest
Request to browse the pay-in quotes available to the calling beneficiary.
This message has no fields defined.
GetQuotesResponse
The pay-in quotes the caller can collect against, grouped by currency.
| Field | Type | Label | Description |
|---|---|---|---|
| quotes | GetQuotesResponse.CurrencyQuote | repeated | One entry per pay-in currency with at least one quoting permitted provider. no validation: any count is valid, including none |
GetQuotesResponse.CurrencyQuote
All pay-in quotes for one currency, grouped by payment method.
| Field | Type | Label | Description |
|---|---|---|---|
| currency | string | ISO 4217 pay-in currency code, e.g. EUR, GBP. | |
| payment_method_quotes | GetQuotesResponse.CurrencyQuote.PaymentMethodQuote | repeated | The payment methods this currency can be collected through. |
GetQuotesResponse.CurrencyQuote.PaymentMethodQuote
All pay-in quotes for one payment method within the enclosing currency, across providers.
| Field | Type | Label | Description |
|---|---|---|---|
| payment_method | tzero.v1.common.PaymentMethodType | ||
| provider_quotes | GetQuotesResponse.CurrencyQuote.PaymentMethodQuote.ProviderQuote | repeated | The permitted pay-in providers quoting this currency and payment method. |
GetQuotesResponse.CurrencyQuote.PaymentMethodQuote.ProviderQuote
One pay-in provider’s offering for the enclosing currency and payment method.
| Field | Type | Label | Description |
|---|---|---|---|
| provider_id | uint32 | The T-0 provider ID of the pay-in provider that published these bands. | |
| quotes | GetQuotesResponse.CurrencyQuote.PaymentMethodQuote.ProviderQuote.Quote | repeated | Tiered rate bands, ascending by max_amount. |
GetQuotesResponse.CurrencyQuote.PaymentMethodQuote.ProviderQuote.Quote
One pricing band: the rate and fixed charge that apply up to max_amount.
| Field | Type | Label | Description |
|---|---|---|---|
| max_amount | tzero.v1.common.Decimal | USD ceiling this band applies up to. A pay-in amount falls in this band when amount / rate is at or below the ceiling — the ceiling is in USD, not in the pay-in currency. | |
| rate | tzero.v1.common.Decimal | Indicative exchange rate, pay-in currency per USD. | |
| fix | tzero.v1.common.Decimal | Fixed charge in USD retained by the pay-in provider per transfer. | |
| expires_at | google.protobuf.Timestamp | When these terms stop being offered. |
PaymentIntentPayInDetails
Represents pay-in details for a payment intent option.
| Field | Type | Label | Description |
|---|---|---|---|
| payment_method | tzero.v1.common.PaymentMethodType | The payment method type (e.g., SEPA, SWIFT, mobile money). Determines which payment details format is provided. | |
| provider_id | uint32 | The T-0 provider ID of the pay-in provider offering this option. | |
| payment_details | tzero.v1.common.PaymentDetails | Payment details for the end-user to make the payment. Contains bank account info, mobile money details, etc. based on payment_method. This should be displayed to the end-user to complete their payment. |
UpdateQuoteRequest
Base currency is always USD, so the quotes are always in USD/currency format.
| Field | Type | Label | Description |
|---|---|---|---|
| payment_intent_quotes | 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. An empty list withdraws all quotes. |
UpdateQuoteRequest.Quote
| Field | Type | Label | Description |
|---|---|---|---|
| currency | string | BRL, EUR, GBP, etc. (ISO 4217 currency code) | |
| payment_method | tzero.v1.common.PaymentMethodType | Payment method must be specified | |
| bands | UpdateQuoteRequest.Quote.Band | repeated | list of bands for this quote |
| expiration | google.protobuf.Timestamp | expiration time of the quote | |
| timestamp | google.protobuf.Timestamp | timestamp quote was created |
UpdateQuoteRequest.Quote.Band
| 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 retained by the pay-in provider per transfer. Covers flat operational costs that do not scale with amount (wire fees, rail fees, compliance checks). Subtracted from the settlement amount: settlement = (amount / rate) - fix. Defaults to 0 when absent — no fixed charge applied. |
UpdateQuoteResponse
This message has no fields defined.
ConfirmFundsReceivedResponse.Reject.Reason
| Name | Number | Description |
|---|---|---|
| REJECT_REASON_UNSPECIFIED | 0 | |
| REJECT_REASON_CONFIRMATION_CODE_MISMATCH | 10 | |
| REJECT_REASON_NO_ACTIVE_QUOTE | 20 | |
| REJECT_REASON_PROVIDER_NOT_ALLOWED | 30 | |
| REJECT_REASON_AMOUNT_TOO_SMALL | 40 | The pay-in amount would yield a zero or negative beneficiary settlement (pay_in / rate − fix) at every active quote. |
| REJECT_REASON_NO_VALID_OFFER | 50 | The requested payment method was not offered on this intent — either the intent was rejected at creation, or no valid payment details were returned for the method. Retry with a method from the returned options. |
| REJECT_REASON_TRANSACTION_REFERENCE_ALREADY_USED | 60 | Transaction_reference is already attached to a different pay-in with the same payment_method. References must be unique per payment_method; retry with a fresh transaction_reference, or treat the prior pay-in as the authoritative confirmation. |
CreatePaymentIntentResponse.Failure.Reason
| Name | Number | Description |
|---|---|---|
| FAILURE_REASON_UNSPECIFIED | 0 | |
| FAILURE_REASON_QUOTE_NOT_FOUND | 10 | No live quote covers the requested currency/amount, so the payment intent is not created. Final for this external_reference. |
| FAILURE_REASON_REJECTED | 20 | Payment intent rejected. |