Payment Intent link

Overview link

Payment Intent enables beneficiary providers to receive fiat payments from end-users through pay-in providers, with automatic settlement tracking on the T-0 Network.

Participants link

Flow Diagram link

sequenceDiagram
    actor BP as Beneficiary Provider
    participant N as Network
    actor PIP as Pay-in Provider
    participant BC as Blockchain
    actor P as Payer
    autonumber
    Note over BP, P: Payment Intent Flow
    PIP ->> N: Publish quotes
    BP ->>+ N: Check available rates (optional)
    N -->>- BP: Indicative quotes
    BP ->>+ N: Create payment intent
    N ->>+ PIP: Request payment details
    PIP -->>- N: Payment details
    N -->>- BP: Payment intent with options
    BP -->> P: Display payment options
    P ->> PIP: Fiat Payment
    PIP ->>+ N: Confirm funds received
    N -->> N: Calculate settlement & create ledger entries
    N -->>- PIP: Confirmation result
    N ->> BP: Settlement notification
    N ->> PIP: Balance update notification
    N ->> BP: Balance update notification
    Note over BP, BC: Settlement (Asynchronous)
    PIP ->> BC: Settlement transfer
    BC ->> N: Transaction notification
    N ->> PIP: Balance update notification
    N ->> BP: Balance update notification

Flow Description link

Phase 1: Quote Discovery (Optional) link

The beneficiary provider can check available exchange rates before creating a payment intent. This helps understand which pay-in providers are available and their current rates.

Each option includes:

• Payment method (e.g., SEPA, mobile money)
• Pay-in provider identifier
• Indicative exchange rate

Note: Rates are indicative only. The actual settlement rate is determined when funds are confirmed.

Phase 2: Create Payment Intent link

The beneficiary provider creates a payment intent specifying:

• Amount and currency for the payment
• External reference for tracking
• Travel rule compliance data (beneficiary information)

The network retrieves payment details from available pay-in providers and returns the options to the beneficiary provider.

The response includes:

• payment_intent_id - Unique identifier to track this payment
• Available payment options with details for each supported method

Phase 3: End-User Payment link

The beneficiary provider displays the payment options to their end-user. The end-user selects a payment method and sends fiat to the pay-in provider using the provided payment details (bank account, mobile money number, etc.).

This step happens outside the T-0 Network.

Phase 4: Confirm Funds Received link

When the pay-in provider receives and verifies the payment, they notify the network. The network then:

1. Determines the current quote from the pay-in provider
2. Calculates the settlement amount
3. Creates ledger entries for the settlement

Phase 5: Settlement Notification link

The beneficiary provider receives a notification containing:

• settlement_amount - Amount credited to their balance
• rate - Exchange rate used for settlement
• source_amount - Fiat amount received from the end-user

After receiving this notification, the beneficiary provider can safely release goods/services to their end-user.

Phase 6: Settlement (Asynchronous) link

Outstanding balances between providers are settled periodically via blockchain transfers. Balance update notifications keep both providers informed of their current positions.

Technical Reference link

Services Overview link

PaymentIntentService (network.proto) link

Called by providers to interact with the payment intent system.

GetQuote link

Returns available indicative quotes for a given currency and amount. Use this to check rates before creating a payment intent.

Request Fields:

Response:

Returns Success with available quotes[] or QuoteNotFound if no providers support the request.

Each IndicativeQuote contains:

• payment_method - Payment method type
• provider_id - Pay-in provider identifier
• indicative_rate - Current indicative exchange rate (USD/XXX)

Note: This endpoint returns indicative quotes only, without payment details. Use CreatePaymentIntent to get actual payment details for making a payment.

CreatePaymentIntent link

Creates a new payment intent for collecting a fiat payment.

Request Fields:

TravelRuleData Fields:

Response:

On success, returns:

• payment_intent_id - Unique identifier for this payment intent
• pay_in_details[] - Available payment options for the end-user

On failure, returns a reason code (e.g., QUOTE_NOT_FOUND).

Idempotency: Multiple calls with the same external_reference return the existing payment intent.

ConfirmFundsReceived link

Called by pay-in providers to confirm receipt of funds from the end-user.

Request Fields:

Response:

Returns Accept or Reject. On acceptance:

1. Network selects the best available quote
2. Settlement amount is calculated
3. Ledger entries are created
4. Beneficiary provider receives a notification

Important: This endpoint assumes full payment. Partial payments are not supported.

PayInProviderService (pay_in_provider.proto) link

Implemented by pay-in providers to participate in the payment intent flow.

GetPaymentDetails link

Called by the network during payment intent creation to obtain payment details.

Request Fields:

TravelRuleData Fields:

Response:

Returns payment_details[] for each supported payment method.

Implementation Notes:

• Return details for methods you support; omit unsupported methods
• Include reference numbers needed to identify incoming payments
• Monitor for incoming payments and call ConfirmFundsReceived when received

BeneficiaryService (beneficiary.proto) link

Implemented by beneficiary providers to receive payment status notifications.

PaymentIntentUpdate link

Notifies the beneficiary provider of payment intent status changes.

Request Fields:

FundsReceived Fields:

Response:

Empty response indicates successful processing. Return an error status if processing failed and retry is needed.

Idempotency: This endpoint must be idempotent. The network may retry delivery on failures.

Error Handling link

Idempotency link

All endpoints are idempotent:

Beneficiary providers must implement idempotent handling for PaymentIntentUpdate notifications.