Skip to content

Create payment

Request

Create a payment

Tutorials

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, (uuid)

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

Example:"7ea3399c-1234-5678-8d8f-d320ea406630"
beneficiaryIdentityIdstring, (uuid)required

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

Example:"7ea3399c-1234-5678-8d8f-d320ea406630"
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.

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/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/v2/payments \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630",
    "originatorIdentityId": "7ea3399c-1234-5678-8d8f-d320ea406630",
    "beneficiaryIdentityId": "7ea3399c-1234-5678-8d8f-d320ea406630",
    "internalId": "Invoice-123",
    "purposeCode": "PAYR",
    "sourceOfCash": "EMIN",
    "paymentLabels": [
      "batchId=aaaaaaaa-1111-bbbb-abab-123412341234"
    ],
    "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
Enum ValueDescription
INITIATED

You, the payment originator, have initiated a payment. The payment now has a unique paymentId that's the same as the quoteId of the quote you accepted.

VALIDATING

Ripple validates the payment details and reserves funds from your available balance to complete the payment.

TRANSFERRING

The payment is moving through the network to the ultimate beneficiary. The payment amount is debited from your available balance.

COMPLETED

The payment is complete and the beneficiary has received the funds.

FAILED

The payment failed. 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.

QUOTED

A quote has been created, but you haven't accepted it yet to initiate a payment. Note: This state is not shown as part of the payment detail as the payment doesn't exist yet.

RETURNED

The payment is returned. 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.

Example:"INITIATED"
originatorobject

Payment originator and source details.

destinationobject

Payment beneficiary and destination details.

adjustedExchangeRateobject

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

feesArray of objects

A summary of fees included in payment quote.

taxesArray of objects

A summary of taxes included in the payment quote.

sourceOfCashstring

The source of cash may be required depending on corridor and payout partner. Valid values for the source of cash 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

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.

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"
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": "7ea3399c-1234-5678-8d8f-d320ea406630",
    "originatorIdentityIdVersion": 1,
    "originatorIdentityNickName": "Successful Business Sender",
    "internalId": "Invoice-123",
    "sourceCurrency": "USD",
    "sourceAmount": 100,
    "payin": "FUNDED"
  },
  "destination": {
    "destinationAmount": 1234.111223,
    "destinationCountry": "US",
    "destinationCurrency": "USD",
    "destinationBlockchainNetwork": "Ethereum, TRON",
    "beneficiaryIdentityId": "7ea3399c-1234-5678-8d8f-d320ea406630",
    "beneficiaryIdentityVersion": 1,
    "beneficiaryIdentityNickName": "Successful business beneficiary",
    "payout": "BANK"
  },
  "adjustedExchangeRate": {
    "adjustedRate": 2
  },
  "fees": [
    { … }
  ],
  "taxes": [
    { … }
  ],
  "sourceOfCash": "EMIN",
  "purposeCode": "PAYR",
  "transactionDetails": {
    "paymentProduct": "string",
    "flowType": "B2B",
    "thirdPartyPayment": false,
    "businessUseCase": "ON_RAMP"
  },
  "paymentLabels": [
    "batchId=aaaaaaaa-1111-bbbb-abab-123412341234"
  ],
  "paymentMemo": "ORDER 2025-09-001 PAYMENT"
}