Get a payment by ID

Request

Returns the current status and full details of a payment, including amounts, beneficiary information, and the associated quote.

Security

Bearer

Path

paymentIdstring, (uuid)required

Unique identifier of the payment to get.

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

curl -i -X GET \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/payments/7ea3399c-1234-5678-8d8f-d320ea406630 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successfully fetched payment details.

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 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.

errorsArray of objects

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.

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"

payoutExecutionDetailsobject

Metadata about the payout execution, including the payment rail used, timing, and tracking references.

payoutExecutionDetails is an optional field that should be treated as informational only. Do not build required workflows that depend on its presence, as availability varies by corridor and partner.

When present, trackingReferences provides network-specific identifiers useful for audit, reconciliation, or customer inquiry resolution. Use the referenceType field on each tracking reference to identify what a value represents rather than relying on its position in the array.

Coverage will expand as additional corridors and partners are onboarded.

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"
  },
  "errors": [
    { … }
  ],
  "paymentLabels": [
    "batchId=aaaaaaaa-1111-bbbb-abab-123412341234"
  ],
  "receiverRelationship": "SUBS",
  "paymentMemo": "ORDER 2025-09-001 PAYMENT",
  "payoutExecutionDetails": {
    "paymentRailUsed": "FEDWIRE",
    "payoutStartTime": "2026-02-18T14:22:15.789Z",
    "payoutEndTime": "2026-02-18T14:25:30.123Z",
    "trackingReferences": [ … ]
  }
}