Create payment

Request

Initiates a new cross-border payment. Payments are processed asynchronously. Use Get a payment by ID to poll for status updates, or Get state transitions to view the full status history.

Security

Bearer

Bodyapplication/jsonrequired

create payment request

quoteIdstring, (uuid)required

ID of the quote you want to accept to initiate this payment. Must be in UUID format. This will be used as paymentId.

Example:"7ea3399c-1234-5678-8d8f-d320ea406630"

originatorIdentityIdstring

The identity ID of the payment originator. You can find the identity ID using the GET /identities operation.

Example:"c1e92b47-4579-4a7e-9c9a-02f3e3e4bb11"

beneficiaryIdentityIdstringrequired

The identity ID of the payment beneficiary. You can find the identity ID using the GET /identities operation.

Example:"99254c4f-f207-4792-a846-06928825018c"

internalIdstring, <= 36 characters

Customer defined value, such as an invoice number.

Example:"Invoice-123"

purposeCodestring

Purpose Code may be required depending on corridor and payout partner. Valid Purpose Code values vary by corridor.

Example:"PAYR"

sourceOfCashstring

Source of Cash may be required depending on corridor and payout partner. Valid Source of Cash values vary by corridor.

Example:"EMIN"

paymentLabelsArray of strings, <= 10 items

Application-defined labels for grouping and categorizing payments (e.g., campaign IDs, workflow tags, or batch identifiers). Labels are optional and mutable; they can be added or removed over the payment's lifetime.

beneficiaryFinancialInstrumentIdstringrequired

The financial instrument ID associated with a payment beneficiary's identity. This value must reference a financial instrument created for the same beneficiary identity using Identity Management v3. Use the financialInstrumentId returned when you create or fetch the beneficiary's payout instrument.

Example:"0e0d7b5a-7f2b-4c75-9bb9-8c4d0ff5f2a1"

receiverRelationshipstring

The relationship to the debtor.

Example:"SUBS"

paymentMemostring

Optional, transaction-specific memo carried with the payment for beneficiary reconciliation. Validation rules (required, allowed characters, max length) vary by corridor. Consult the data requirements for your corridor. Not stored in PII; persisted on the payment object and forwarded to compliance and payout partners. Where possible, the memo will also be delivered to the final beneficiary's credit record, but delivery cannot be guaranteed in all cases due to payout partner or downstream constraints. If omitted, Ripple may generate a memo automatically.

Example:"ORDER 2025-09-001 PAYMENT"

curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/payments \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630",
    "originatorIdentityId": "c1e92b47-4579-4a7e-9c9a-02f3e3e4bb11",
    "beneficiaryIdentityId": "99254c4f-f207-4792-a846-06928825018c",
    "internalId": "Invoice-123",
    "purposeCode": "PAYR",
    "sourceOfCash": "EMIN",
    "paymentLabels": [
      "batchId=aaaaaaaa-1111-bbbb-abab-123412341234"
    ],
    "beneficiaryFinancialInstrumentId": "0e0d7b5a-7f2b-4c75-9bb9-8c4d0ff5f2a1",
    "receiverRelationship": "SUBS",
    "paymentMemo": "ORDER 2025-09-001 PAYMENT"
  }'

Responses

Valid payment

Bodyapplication/json

paymentIdstring, (uuid), <= 36 charactersrequired

The unique ID that identifies this payment. This value is the same as the quote ID.

Example:"7ea3399c-1234-5678-8d8f-d320ea406630"

cryptoTransactionHashstring

Transaction hash of the crypto payment on the destination blockchain network

Example:"0x2b1f8b57dd6008143ff926ea9d9cd2365774cd0c5e6f379558a88c61c52071eb"

initiatedAtstring, (date-time)

The time at which the payment was initiated, specified in UTC.

Example:"2019-08-24T14:15:22Z"

expiresAtstring, (date-time)

The time at which this payment expires, specified in UTC.

Example:"2019-08-24T14:15:22Z"

jitFundingExpiresAtstring, (date-time)

The time at which JIT funding for this payment expires, specified in UTC.

Example:"2019-08-24T14:15:22Z"

lastStateUpdatedAtstring, (date-time)

The time at which the payment state was last updated for this payment, specified in UTC.

Example:"2019-08-24T14:15:22Z"

paymentStatestringrequired

Current state of a payment.

The payment lifecycle currently uses the following values:

QUOTED
INITIATED
VALIDATING
TRANSFERRING
COMPLETED
FAILED
RETURNED
DECLINED
AWAITING_FUNDING

Additional states may be introduced in the future without breaking existing integrations.

Enum Value	Description
QUOTED	A quote has been created, but the payment has not yet been initiated.
INITIATED	The payment has been submitted and is awaiting validation.
VALIDATING	Ripple is validating the payment details and reserving funds from the originator's available balance.
TRANSFERRING	The payment is being processed and funds are moving through the network toward the beneficiary.
COMPLETED	The payment has completed and the beneficiary has received the funds.
FAILED	The payment could not be completed. The failure reason, if available, is listed in the response. Funds that were previously reserved to complete the payment are released and added back to the available balance.
RETURNED	The payment was returned by a downstream institution. The return reason, if available, is listed in the response. Funds that were previously reserved and debited to complete the payment are returned and added back to the available balance.
DECLINED	The payment was declined due to user input errors or business rule violations. The decline reason, if available, is listed in the response. Funds that were previously reserved to complete the payment are released and added back to the available balance.
AWAITING_FUNDING	The payment is waiting for funds to be transferred to your Ripple ledger account. This state applies only to just-in-time (JIT) funded payments.

Example:"INITIATED"

originatorobject

Payment originator and source details.

destinationobject

adjustedExchangeRateobject

Foreign Exchange (FX) rate used to calculate the quote.

feesArray of objects

A summary of fees included in the payment quote.

taxesArray of objects

A summary of taxes included in the payment quote.

sourceOfCashstring

Source of Cash may be required depending on corridor and payout partner. Valid Source of Cash values vary by corridor.

Example:"EMIN"

purposeCodestring

Purpose Code may be required depending on corridor and payout partner. Valid Purpose Code values vary by corridor.

Example:"PAYR"

transactionDetailsobject

A summary of the payment category.

paymentLabelsArray of strings, <= 10 items

receiverRelationshipstring

The relationship to the debtor.

Example:"SUBS"

paymentMemostring

Example:"ORDER 2025-09-001 PAYMENT"

Response

{
  "paymentId": "7ea3399c-1234-5678-8d8f-d320ea406630",
  "cryptoTransactionHash": "0x2b1f8b57dd6008143ff926ea9d9cd2365774cd0c5e6f379558a88c61c52071eb",
  "initiatedAt": "2019-08-24T14:15:22Z",
  "expiresAt": "2019-08-24T14:15:22Z",
  "jitFundingExpiresAt": "2019-08-24T14:15:22Z",
  "lastStateUpdatedAt": "2019-08-24T14:15:22Z",
  "paymentState": "INITIATED",
  "originator": {
    "originatorIdentityId": "c1e92b47-4579-4a7e-9c9a-02f3e3e4bb11",
    "originatorIdentityIdVersion": 1,
    "originatorIdentityNickName": "Successful Business Sender",
    "internalId": "Invoice-123",
    "sourceCurrency": "USD",
    "sourceAmount": 100,
    "payin": "FUNDED"
  },
  "destination": {
    "beneficiaryFinancialInstrumentId": "0e0d7b5a-7f2b-4c75-9bb9-8c4d0ff5f2a1",
    "destinationAmount": 1234.111223,
    "destinationCountry": "US",
    "destinationCurrency": "USD",
    "destinationBlockchainNetwork": "Ethereum, TRON",
    "beneficiaryIdentityId": "99254c4f-f207-4792-a846-06928825018c",
    "beneficiaryIdentityVersion": 1,
    "beneficiaryIdentityNickName": "Successful business beneficiary",
    "payout": "BANK",
    "selectedPaymentRail": "XRP_LEDGER"
  },
  "adjustedExchangeRate": {
    "adjustedRate": 2
  },
  "fees": [
    { … }
  ],
  "taxes": [
    { … }
  ],
  "sourceOfCash": "EMIN",
  "purposeCode": "PAYR",
  "transactionDetails": {
    "paymentProduct": "string",
    "flowType": "string",
    "thirdPartyPayment": false,
    "businessUseCase": "string"
  },
  "paymentLabels": [
    "batchId=aaaaaaaa-1111-bbbb-abab-123412341234"
  ],
  "receiverRelationship": "SUBS",
  "paymentMemo": "ORDER 2025-09-001 PAYMENT"
}

Create payment

Request

Responses

Was this helpful?