PaymentIntentService link
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. 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. |
| CreatePaymentIntent | CreatePaymentIntentRequest | CreatePaymentIntentResponse | CreatePaymentIntent initiates a new payment intent. Returns the available payment options to present to the end-user. The returned payment_intent_id must be stored by the beneficiary provider to correlate with the PaymentIntentUpdate notification received later. Idempotency: Multiple calls with the same external_reference return the same payment_intent_id. |
| 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 link
ConfirmFundsReceivedRequest link
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 link
ConfirmFundsReceivedResponse.Accept link
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/ exchange rate locked in for this settlement. Matches the rate forwarded to the beneficiary in PaymentIntentUpdate.FundsReceived. |
| 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 link
Funds rejected.
CreatePaymentIntentRequest link
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 link
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 | no validation: ivms101.Person opaque to protovalidate; structural checks delegated to travel-rule layer |
CreatePaymentIntentResponse link
CreatePaymentIntentResponse.Failure link
Payment intent creation failed.
CreatePaymentIntentResponse.Success link
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. Indicative rate/fix are resolved live on every call, including idempotent retries. The set of options is fixed at first call; individual options whose underlying quote has lapsed are omitted on retry. |
GetQuoteRequest link
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 link
GetQuoteResponse.QuoteNotFound link
No providers have active quotes for the requested currency/amount.
This message has no fields defined.
GetQuoteResponse.Success link
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 link
Represents an indicative quote from a pay-in provider.
Contains the payment method, provider info, and indicative exchange rate.
| 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. |
PaymentIntentPayInDetails link
Represents pay-in details for a payment intent option.
Contains the payment method, provider info, payment details, and indicative exchange rate.
| 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 quote. |
| 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. |
| indicative_rate | tzero.v1.common.Decimal | | Indicative exchange rate USD/XXX (base currency is always USD). Reflects the current quote on every call, including idempotent retries. The binding rate is locked in at ConfirmFundsReceived and may differ. |
| 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. Reflects the current quote on every call, including idempotent retries. The binding fix is locked in at ConfirmFundsReceived and may differ. |
UpdateQuoteRequest link
Base currency is always USD, so the quotes are always in USD/currency format.
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.
| Field | Type | Label | Description |
|---|
| payment_intent_quotes | UpdateQuoteRequest.Quote | repeated | no validation: zero items is valid — empty list withdraws all quotes for this provider |
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 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 link
This message has no fields defined.
ConfirmFundsReceivedResponse.Reject.Reason link
| 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 link
| Name | Number | Description |
|---|
| FAILURE_REASON_UNSPECIFIED | 0 | |
| FAILURE_REASON_QUOTE_NOT_FOUND | 10 | No live quote covers the requested currency/amount. On first call this means the intent was never created. On an idempotent retry this means every stored offer has since lost its live quote; a subsequent retry may succeed once providers republish. |
| FAILURE_REASON_REJECTED | 20 | Payment intent rejected. |