Skip to content

Payments Direct API (0.0.1)

Use the Payments Direct API to get quotes, create and manage payments, and manage originator and beneficiary identities.

API environments

The Payments Direct API offers the following environments:

Environment
Base URLDescription
Testhttps://api.test.ripple.comTest environment with simulated currency.
Productionhttps://api.ripple.comProduction environment

API authentication

All Ripple Payments Direct API operations require a Bearer access token specific to the environment you're using. Ripple provides a secure model for authentication and authorization by providing access tokens scoped for a set of credentials.

Generate client ID and client secret

You will need your client ID and client secret to obtain an access token.

If you do not already have your client ID and client secret, do the following:

  1. Log into the Ripple Payments UI.
  2. In the left navigation menu, click Settings.
  3. Under Administration, click API Credentials.
  4. In the dropdown list next to the page title, select the access environment. For example, to provision credentials for the test environment, select Test from the dropdown list.
  5. In the upper right corner of the page, click New Credential.
  6. Click Save and Generate Key.

Caution: The client secret is displayed only once when you are creating new credentials. You cannot retrieve the secret after exiting this page. Copy and store the client secret securely and share it with authorized individuals in accordance with your organization's security policy.

You can now use the client ID and client secret to generate access tokens using the Request an access token operation.

Request an access token

To get an access token, use the Request an access token operation with your client_id and client_secret. The response contains a token in the access_token field.

We recommend rotating your API credentials at regular intervals according to your organization's security policy.

Note: Authentication tokens are not a fixed length and can vary, avoid validating tokens based on character length.

Overview
License

Apache 2.0

Languages
Servers
Mock server

https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/examples/payments-direct-external-openapi/

Test environment with simulated currency

https://api.test.ripple.com/

Production environment

https://api.ripple.com/

Authentication

Use these API operations to manage your authentication tokens.

OperationMethodDescription
Request an access tokenPOSTRequest an access token for authentication with Ripple APIs.
Test access tokenGETTest if an access token can be used for authentication.
Operations

Identities

Use these API operations to manage your identities.

OperationMethodDescription
Create an identityPOSTCreate a new identity.
List identitiesGETGet a list of existing identities.
Get an identity by IDGETGet an identity by its unique ID.
Deactivate an identityDELETEDeactivate an identity.
Operations

Payments

Use these API operations to manage your payments.

OperationMethodDescription
Search paymentsPOSTSearch for payments based on filtering criteria.
Create a paymentPOSTCreate a payment by accepting a quote.
Get payment by payment IDGETGet a specific payment by payment ID.
Operations

Search payments

Request

Search for payments based on filtering criteria.

Security
Bearer
Bodyapplication/jsonrequired

Search payments request

filterobject

Filter criteria to return desired payment search results.

paymentIdsArray of strings(uuid)

Specify a list of uuids to search for payment with payment ids equals one from the list

Example: ["aaaaaaaa-1111-bbbb-abab-123412341234"]
paymentStatesArray of strings

Array of payment states like EXECUTING or COMPLETED.

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

Example: ["INITIATED"]
filterRangeTypestring

The range type to filter payments on.

Enum ValueDescription
PAYMENT_CREATION

Filter results to show payments that were created within the specified time period.

PAYMENT_EXPIRY

Filter results to show payments that expired or are set to expire within the specified time period.

PAYMENT_STATUS_LAST_UPDATED

Filter results to show payments whose status was last updated within the specified time period.

Example: "PAYMENT_CREATION"
beforeTimestampstring(date-time)

Depending on the value of the filterRangeType field, this timestamp returns a list of payments that were created/modified/expired at or before the specified time.

Example: "2024-04-24T14:15:22Z"
afterTimestampstring(date-time)

Depending on the value of the filterRangeType field, this timestamp returns a list of payments that were created/modified/expired at or after the specified time.

Example: "2024-03-24T13:15:22Z"
beneficiaryIdentityIdsArray of strings(uuid)

To get all payments made to one or more beneficiaries, specify the identity ID(s) of those beneficiaries in this field. You can find the identity ID using the GET /identities operation.

Example: ["aaaaaaaa-1111-bbbb-abab-123412341234"]
internalIdstring

Specify an internalId to get payments associated with them. A prefix match will be executed.

beneficiaryIdentityNicknamestring<= 100 characters

To get all payments made to a beneficiary, specify the nickname of that beneficiary in this field. You can find the nickname using the GET /identities operation.

Example: "Successful business beneficiary"
destinationCurrenciesArray of strings^[A-Z]{3,5}$

Specify one or more currency codes to get payments where the beneficiary received funds in these currencies.

paymentLabelsArray of strings<= 10 items

List of labels associated with the payment. A label typically contains a UUID of your choice, designated as the batchId.

Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]
sortobject

Specify sorting direction and the filtering criterion to sort by.

sortFieldstring

The field based on which you want to sort the payments in the specified sort order.

Default "initiatedAt"
Enum ValueDescription
internalId

Sort by an internalId of payment

paymentState

Sort by payment state

sourceCurrency

Sort by source currency of payment

sourceCountry

Sort by source country of payment

sourceAmount

Sort by source amount of payment

destinationCurrency

Sort by destination currency of payment

destinationCountry

Sort by destination currency of payment

destinationAmount

Sort by destination amount of payment

initiatedAt

Sort by payment initiated timestamp

expiresAt

Sort by payment expiry timestamp

Example: "initiatedAt"
sortDirectionstring

Sort results in ascending or descending order.

Default "DESC"
Enum ValueDescription
ASC

Sort results in ascending order.

DESC

Sort results in descending order.

Example: "DESC"
pageobject

Specify page size and the ID of the last fetched result.

sizeinteger[ 1 .. 100 ]

Size of the page

Default 20
Example: 20
lastPageTokenstring

The unique reference ID of the last fetched item. To retrieve subsequent item(s) if any, specify this value as the value of the Page.list field in the POST /payments/filter operation request body.

curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/examples/payments-direct-external-openapi/v2/payments/filter \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "paymentIds": [
        "aaaaaaaa-1111-bbbb-abab-123412341234"
      ],
      "paymentStates": [
        "INITIATED"
      ],
      "filterRangeType": "PAYMENT_CREATION",
      "beforeTimestamp": "2024-04-24T14:15:22Z",
      "afterTimestamp": "2024-03-24T13:15:22Z",
      "beneficiaryIdentityIds": [
        "aaaaaaaa-1111-bbbb-abab-123412341234"
      ],
      "internalId": "string",
      "beneficiaryIdentityNickname": "Successful business beneficiary",
      "destinationCurrencies": [
        "string"
      ],
      "paymentLabels": [
        "batchId=aaaaaaaa-1111-bbbb-abab-123412341234"
      ]
    },
    "sort": {
      "sortField": "initiatedAt",
      "sortDirection": "DESC"
    },
    "page": {
      "size": 20,
      "lastPageToken": "string"
    }
  }'

Responses

Payments matching the specified filtering criteria.

Bodyapplication/json
dataArray of objects

Array of Payment objects

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

Example: "INITIATED"
originatorobject

Payment originator and source details.

originatorIdentityIdstring(uuid)<= 36 characters

The unique ID associated with the payment originator's identity record.

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

The current version of the originator's identity record.

Example: 1
originatorIdentityNickNamestring<= 100 characters

Nickname associated with the originator's identity record.

Example: "Successful Business Sender"
internalIdstring<= 35 characters

An ID associated with this payment, if provided by the customer during payment initiation.

Example: "Invoice-123"
sourceCountrystring<= 2 characters^[A-Z]{2}$

The country where the payment originator is located or incorporated, specified in Alpha-2 Code format as defined in the ISO CountryCode ISO 3166-1 list.

Example: "US"
sourceCurrencystring<= 5 characters^[A-Z]{3,5}$

originator's currency

Example: "USD"
sourceAmountnumber(double)

The amount sent by the originator in this payment. This field can hold a value with up to 6 decimal places.

Example: 100
payinstring

Details about how this payment is funded.

Example: "FUNDED"
destinationobject

Payment beneficiary and destination details.

destinationAmountnumber(double)

The amount received by the payment beneficiary. This field can hold a value with up to 6 decimal places.

Example: 1234.111223
destinationCountrystring<= 2 characters^[A-Z]{2}$

The country where the beneficiary is located specified in Alpha-2 Code format as defined in the ISO CountryCode ISO 3166-1 list. If the beneficiary is an individual, then this value is their country of residence. If the beneficiary is an institution, then this value is their the country of incorporation.

Example: "US"
destinationCurrencystring<= 5 characters^[A-Z]{3,5}$

The currency code of the currency in which the beneficiary will receive this payment.

Example: "USD"
destinationBlockchainNetworkstring[ 1 .. 20 ] characters

The name of the blockchain network on which the beneficiary will receive this payment.

Example: "Ethereum, TRON"
beneficiaryIdentityIdstring(uuid)<= 36 characters

The unique ID associated with the payment beneficiary's identity record.

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

The current version of the beneficiary's identity record.

Example: 1
beneficiaryIdentityNickNamestring<= 100 characters

Nickname associated with the beneficiary's identity record.

Example: "Successful business beneficiary"
payoutstring

The payout category for this payment.

Example: "BANK"
adjustedExchangeRateobject

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

adjustedRatenumber(double)

Value of the Foreign Exchange (FX) rate.

Example: 2
feesArray of objects

A summary of fees included in payment quote.

totalFeenumber(double)

The value of the total fee included in this quote.

Example: 12.23
feeCurrencystring^[a-zA-Z]{3,5}$

The currency in which fees are charged.

Example: "USD"
feeBreakdownArray of objects

An array of fees that provides a breakdown of how the total fees is calculated for this quote.

calculatedFeenumber(double)

Value of the fee when the configured fee unit is applied against the value.

Example: 2.43
feeNamestring[ 1 .. 128 ] characters

The name of the fee.

Example: "Service fee"
feeDescriptionstring[ 1 .. 256 ] characters

Description of the fee.

Example: "The service fee charged for this transaction."
sourceOfCashstring

Indicates the source of funds

Enum ValueDescription
ALMY

Alimony

CASH

Cash Proceeds

COMP

Compensation

EMIN

Employee Income

GIFT

Gift

INHE

Inheritance

INLQ

Insurance Premium Liquidation

PACA

Paid Up Capital

REDM

Redemption

REPY

Retirement Policy

Example: "EMIN"
purposeCodestring

Indicates the purpose of the payment

For more information about the purposeCode options, see purposeCode.

Example: "PAYR"
transactionDetailsobject

A summary of the payment category.

paymentProductstring or null

The Ripple payments product used to make this payment.

ValueDescription
LICENSED

Identifies a transaction using Ripple Payments Direct.

flowTypestring or null

Specifies the type of payment you're making as categorized by the identity type of the payment originator and beneficiary.

Enum ValueDescription
B2B

Specifies that this payment is made by a business originator to a business beneficiary.

Identification of third-party payment:

  • If the thirdPartyPayment property is true, it indicates that you're making this payment on behalf of a business originator.
  • If the thirdPartyPayment property is false, it indicates that you are the business originator making this payment.
B2C

Specifies that this payment is made by a business originator to an individual beneficiary.

Identification of third-party payment:

  • If the thirdPartyPayment property is true, it indicates that you're making this payment on behalf of a business originator.
  • If the thirdPartyPayment property is false, it indicates that you are the business originator making this payment.
thirdPartyPaymentboolean or null

Flag to indicate if this payment is initiated on behalf of a third-party originator.

Example: false
businessUseCasestring or null

Indicates the type of payment you're making.

ValueDescription
FIAT_TRANSFER

Indicates fiat source currency to fiat destination.

paymentLabelsArray of strings<= 10 items

List of labels associated with the payment. A label typically contains a UUID of your choice, designated as the batchId.

Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]
filterobject

Filter criteria to return desired payment search results.

paymentIdsArray of strings(uuid)

Specify a list of uuids to search for payment with payment ids equals one from the list

Example: ["aaaaaaaa-1111-bbbb-abab-123412341234"]
paymentStatesArray of strings

Array of payment states like EXECUTING or COMPLETED.

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

Example: ["INITIATED"]
filterRangeTypestring

The range type to filter payments on.

Enum ValueDescription
PAYMENT_CREATION

Filter results to show payments that were created within the specified time period.

PAYMENT_EXPIRY

Filter results to show payments that expired or are set to expire within the specified time period.

PAYMENT_STATUS_LAST_UPDATED

Filter results to show payments whose status was last updated within the specified time period.

Example: "PAYMENT_CREATION"
beforeTimestampstring(date-time)

Depending on the value of the filterRangeType field, this timestamp returns a list of payments that were created/modified/expired at or before the specified time.

Example: "2024-04-24T14:15:22Z"
afterTimestampstring(date-time)

Depending on the value of the filterRangeType field, this timestamp returns a list of payments that were created/modified/expired at or after the specified time.

Example: "2024-03-24T13:15:22Z"
beneficiaryIdentityIdsArray of strings(uuid)

To get all payments made to one or more beneficiaries, specify the identity ID(s) of those beneficiaries in this field. You can find the identity ID using the GET /identities operation.

Example: ["aaaaaaaa-1111-bbbb-abab-123412341234"]
internalIdstring

Specify an internalId to get payments associated with them. A prefix match will be executed.

beneficiaryIdentityNicknamestring<= 100 characters

To get all payments made to a beneficiary, specify the nickname of that beneficiary in this field. You can find the nickname using the GET /identities operation.

Example: "Successful business beneficiary"
destinationCurrenciesArray of strings^[A-Z]{3,5}$

Specify one or more currency codes to get payments where the beneficiary received funds in these currencies.

paymentLabelsArray of strings<= 10 items

List of labels associated with the payment. A label typically contains a UUID of your choice, designated as the batchId.

Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]
sortobject

Specify sorting direction and the filtering criterion to sort by.

sortFieldstring

The field based on which you want to sort the payments in the specified sort order.

Default "initiatedAt"
Enum ValueDescription
internalId

Sort by an internalId of payment

paymentState

Sort by payment state

sourceCurrency

Sort by source currency of payment

sourceCountry

Sort by source country of payment

sourceAmount

Sort by source amount of payment

destinationCurrency

Sort by destination currency of payment

destinationCountry

Sort by destination currency of payment

destinationAmount

Sort by destination amount of payment

initiatedAt

Sort by payment initiated timestamp

expiresAt

Sort by payment expiry timestamp

Example: "initiatedAt"
sortDirectionstring

Sort results in ascending or descending order.

Default "DESC"
Enum ValueDescription
ASC

Sort results in ascending order.

DESC

Sort results in descending order.

Example: "DESC"
pageobject

Specify page size and the ID of the last fetched result.

sizeinteger[ 1 .. 100 ]

Size of the page

Default 20
Example: 20
lastPageTokenstring

The unique reference ID of the last fetched item. To retrieve subsequent item(s) if any, specify this value as the value of the Page.list field in the POST /payments/filter operation request body.

Response
application/json
{
  "data": [
    { … }
  ],
  "filter": {
    "paymentIds": [ … ],
    "paymentStates": [ … ],
    "filterRangeType": "PAYMENT_CREATION",
    "beforeTimestamp": "2024-04-24T14:15:22Z",
    "afterTimestamp": "2024-03-24T13:15:22Z",
    "beneficiaryIdentityIds": [ … ],
    "internalId": "string",
    "beneficiaryIdentityNickname": "Successful business beneficiary",
    "destinationCurrencies": [ … ],
    "paymentLabels": [ … ]
  },
  "sort": {
    "sortField": "initiatedAt",
    "sortDirection": "DESC"
  },
  "page": {
    "size": 20,
    "lastPageToken": "string"
  }
}

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

Indicates the purpose of the payment

For more information about the purposeCode options, see purposeCode.

Example: "PAYR"
sourceOfCashstring

Source of cash for payout.

Enum ValueDescription
ALMY

Alimony

CASH

Cash Proceeds

COMP

Compensation

EMIN

Employee Income

GIFT

Gift

INHE

Inheritance

INLQ

Insurance Premium Liquidation

PACA

Paid Up Capital

REDM

Redemption

REPY

Retirement Policy

Example: "EMIN"
paymentLabelsArray of strings<= 10 items

List of labels associated with the payment. A label typically contains a UUID of your choice, designated as the batchId.

Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]
curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/examples/payments-direct-external-openapi/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"
    ]
  }'

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

Example: "INITIATED"
originatorobject

Payment originator and source details.

originatorIdentityIdstring(uuid)<= 36 characters

The unique ID associated with the payment originator's identity record.

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

The current version of the originator's identity record.

Example: 1
originatorIdentityNickNamestring<= 100 characters

Nickname associated with the originator's identity record.

Example: "Successful Business Sender"
internalIdstring<= 35 characters

An ID associated with this payment, if provided by the customer during payment initiation.

Example: "Invoice-123"
sourceCountrystring<= 2 characters^[A-Z]{2}$

The country where the payment originator is located or incorporated, specified in Alpha-2 Code format as defined in the ISO CountryCode ISO 3166-1 list.

Example: "US"
sourceCurrencystring<= 5 characters^[A-Z]{3,5}$

originator's currency

Example: "USD"
sourceAmountnumber(double)

The amount sent by the originator in this payment. This field can hold a value with up to 6 decimal places.

Example: 100
payinstring

Details about how this payment is funded.

Example: "FUNDED"
destinationobject

Payment beneficiary and destination details.

destinationAmountnumber(double)

The amount received by the payment beneficiary. This field can hold a value with up to 6 decimal places.

Example: 1234.111223
destinationCountrystring<= 2 characters^[A-Z]{2}$

The country where the beneficiary is located specified in Alpha-2 Code format as defined in the ISO CountryCode ISO 3166-1 list. If the beneficiary is an individual, then this value is their country of residence. If the beneficiary is an institution, then this value is their the country of incorporation.

Example: "US"
destinationCurrencystring<= 5 characters^[A-Z]{3,5}$

The currency code of the currency in which the beneficiary will receive this payment.

Example: "USD"
destinationBlockchainNetworkstring[ 1 .. 20 ] characters

The name of the blockchain network on which the beneficiary will receive this payment.

Example: "Ethereum, TRON"
beneficiaryIdentityIdstring(uuid)<= 36 characters

The unique ID associated with the payment beneficiary's identity record.

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

The current version of the beneficiary's identity record.

Example: 1
beneficiaryIdentityNickNamestring<= 100 characters

Nickname associated with the beneficiary's identity record.

Example: "Successful business beneficiary"
payoutstring

The payout category for this payment.

Example: "BANK"
adjustedExchangeRateobject

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

adjustedRatenumber(double)

Value of the Foreign Exchange (FX) rate.

Example: 2
feesArray of objects

A summary of fees included in payment quote.

totalFeenumber(double)

The value of the total fee included in this quote.

Example: 12.23
feeCurrencystring^[a-zA-Z]{3,5}$

The currency in which fees are charged.

Example: "USD"
feeBreakdownArray of objects

An array of fees that provides a breakdown of how the total fees is calculated for this quote.

calculatedFeenumber(double)

Value of the fee when the configured fee unit is applied against the value.

Example: 2.43
feeNamestring[ 1 .. 128 ] characters

The name of the fee.

Example: "Service fee"
feeDescriptionstring[ 1 .. 256 ] characters

Description of the fee.

Example: "The service fee charged for this transaction."
sourceOfCashstring

Indicates the source of funds

Enum ValueDescription
ALMY

Alimony

CASH

Cash Proceeds

COMP

Compensation

EMIN

Employee Income

GIFT

Gift

INHE

Inheritance

INLQ

Insurance Premium Liquidation

PACA

Paid Up Capital

REDM

Redemption

REPY

Retirement Policy

Example: "EMIN"
purposeCodestring

Indicates the purpose of the payment

For more information about the purposeCode options, see purposeCode.

Example: "PAYR"
transactionDetailsobject

A summary of the payment category.

paymentProductstring or null

The Ripple payments product used to make this payment.

ValueDescription
LICENSED

Identifies a transaction using Ripple Payments Direct.

flowTypestring or null

Specifies the type of payment you're making as categorized by the identity type of the payment originator and beneficiary.

Enum ValueDescription
B2B

Specifies that this payment is made by a business originator to a business beneficiary.

Identification of third-party payment:

  • If the thirdPartyPayment property is true, it indicates that you're making this payment on behalf of a business originator.
  • If the thirdPartyPayment property is false, it indicates that you are the business originator making this payment.
B2C

Specifies that this payment is made by a business originator to an individual beneficiary.

Identification of third-party payment:

  • If the thirdPartyPayment property is true, it indicates that you're making this payment on behalf of a business originator.
  • If the thirdPartyPayment property is false, it indicates that you are the business originator making this payment.
thirdPartyPaymentboolean or null

Flag to indicate if this payment is initiated on behalf of a third-party originator.

Example: false
businessUseCasestring or null

Indicates the type of payment you're making.

ValueDescription
FIAT_TRANSFER

Indicates fiat source currency to fiat destination.

paymentLabelsArray of strings<= 10 items

List of labels associated with the payment. A label typically contains a UUID of your choice, designated as the batchId.

Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]
Response
application/json
{
  "paymentId": "7ea3399c-1234-5678-8d8f-d320ea406630",
  "cryptoTransactionHash": "0x2b1f8b57dd6008143ff926ea9d9cd2365774cd0c5e6f379558a88c61c52071eb",
  "initiatedAt": "2019-08-24T14:15:22Z",
  "expiresAt": "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",
    "sourceCountry": "US",
    "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": [
    { … }
  ],
  "sourceOfCash": "EMIN",
  "purposeCode": "PAYR",
  "transactionDetails": {
    "paymentProduct": "string",
    "flowType": "B2B",
    "thirdPartyPayment": false,
    "businessUseCase": "ON_RAMP"
  },
  "paymentLabels": [
    "batchId=aaaaaaaa-1111-bbbb-abab-123412341234"
  ]
}

Get a payment by ID

Request

Gets a payment by ID.

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/examples/payments-direct-external-openapi/v2/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"
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.

Example: "INITIATED"
originatorobject

Payment originator and source details.

originatorIdentityIdstring(uuid)<= 36 characters

The unique ID associated with the payment originator's identity record.

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

The current version of the originator's identity record.

Example: 1
originatorIdentityNickNamestring<= 100 characters

Nickname associated with the originator's identity record.

Example: "Successful Business Sender"
internalIdstring<= 35 characters

An ID associated with this payment, if provided by the customer during payment initiation.

Example: "Invoice-123"
sourceCountrystring<= 2 characters^[A-Z]{2}$

The country where the payment originator is located or incorporated, specified in Alpha-2 Code format as defined in the ISO CountryCode ISO 3166-1 list.

Example: "US"
sourceCurrencystring<= 5 characters^[A-Z]{3,5}$

originator's currency

Example: "USD"
sourceAmountnumber(double)

The amount sent by the originator in this payment. This field can hold a value with up to 6 decimal places.

Example: 100
payinstring

Details about how this payment is funded.

Example: "FUNDED"
destinationobject

Payment beneficiary and destination details.

destinationAmountnumber(double)

The amount received by the payment beneficiary. This field can hold a value with up to 6 decimal places.

Example: 1234.111223
destinationCountrystring<= 2 characters^[A-Z]{2}$

The country where the beneficiary is located specified in Alpha-2 Code format as defined in the ISO CountryCode ISO 3166-1 list. If the beneficiary is an individual, then this value is their country of residence. If the beneficiary is an institution, then this value is their the country of incorporation.

Example: "US"
destinationCurrencystring<= 5 characters^[A-Z]{3,5}$

The currency code of the currency in which the beneficiary will receive this payment.

Example: "USD"
destinationBlockchainNetworkstring[ 1 .. 20 ] characters

The name of the blockchain network on which the beneficiary will receive this payment.

Example: "Ethereum, TRON"
beneficiaryIdentityIdstring(uuid)<= 36 characters

The unique ID associated with the payment beneficiary's identity record.

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

The current version of the beneficiary's identity record.

Example: 1
beneficiaryIdentityNickNamestring<= 100 characters

Nickname associated with the beneficiary's identity record.

Example: "Successful business beneficiary"
payoutstring

The payout category for this payment.

Example: "BANK"
adjustedExchangeRateobject

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

adjustedRatenumber(double)

Value of the Foreign Exchange (FX) rate.

Example: 2
feesArray of objects

A summary of fees included in payment quote.

totalFeenumber(double)

The value of the total fee included in this quote.

Example: 12.23
feeCurrencystring^[a-zA-Z]{3,5}$

The currency in which fees are charged.

Example: "USD"
feeBreakdownArray of objects

An array of fees that provides a breakdown of how the total fees is calculated for this quote.

calculatedFeenumber(double)

Value of the fee when the configured fee unit is applied against the value.

Example: 2.43
feeNamestring[ 1 .. 128 ] characters

The name of the fee.

Example: "Service fee"
feeDescriptionstring[ 1 .. 256 ] characters

Description of the fee.

Example: "The service fee charged for this transaction."
sourceOfCashstring

Indicates the source of funds

Enum ValueDescription
ALMY

Alimony

CASH

Cash Proceeds

COMP

Compensation

EMIN

Employee Income

GIFT

Gift

INHE

Inheritance

INLQ

Insurance Premium Liquidation

PACA

Paid Up Capital

REDM

Redemption

REPY

Retirement Policy

Example: "EMIN"
purposeCodestring

purposeCode for RPD payments

transactionDetailsobject

A summary of the payment category.

paymentProductstring or null

The Ripple payments product used to make this payment.

ValueDescription
LICENSED

Identifies a transaction using Ripple Payments Direct.

flowTypestring or null

Specifies the type of payment you're making as categorized by the identity type of the payment originator and beneficiary.

Enum ValueDescription
B2B

Specifies that this payment is made by a business originator to a business beneficiary.

Identification of third-party payment:

  • If the thirdPartyPayment property is true, it indicates that you're making this payment on behalf of a business originator.
  • If the thirdPartyPayment property is false, it indicates that you are the business originator making this payment.
B2C

Specifies that this payment is made by a business originator to an individual beneficiary.

Identification of third-party payment:

  • If the thirdPartyPayment property is true, it indicates that you're making this payment on behalf of a business originator.
  • If the thirdPartyPayment property is false, it indicates that you are the business originator making this payment.
thirdPartyPaymentboolean or null

Flag to indicate if this payment is initiated on behalf of a third-party originator.

Example: false
businessUseCasestring or null

Indicates the type of payment you're making.

ValueDescription
FIAT_TRANSFER

Indicates fiat source currency to fiat destination.

errorsArray of objects
codestringrequired

A unique identifier for the error

Example: "SYS_003"
typestringrequired

A high-level categorization of the error, indicating the type of issue that occurred

Example: "SYSTEM_ERROR"
titlestringrequired

A brief, user-friendly description of the error

Example: "Internal Server Error"
descriptionstringrequired

A more detailed explanation of the error, potentially including information about what caused the error and the next steps

Example: "The payout category value must be one of BANK, EWALLET, CASH_PICKUP, or ATM."
timestampstring(date-time)required
Example: "2024-11-21T14:15:22Z"
paymentLabelsArray of strings<= 10 items

List of labels associated with the payment. A label typically contains a UUID of your choice, designated as the batchId.

Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]
Response
application/json
{
  "paymentId": "7ea3399c-1234-5678-8d8f-d320ea406630",
  "cryptoTransactionHash": "0x2b1f8b57dd6008143ff926ea9d9cd2365774cd0c5e6f379558a88c61c52071eb",
  "initiatedAt": "2019-08-24T14:15:22Z",
  "expiresAt": "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",
    "sourceCountry": "US",
    "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": [
    { … }
  ],
  "sourceOfCash": "EMIN",
  "purposeCode": "string",
  "transactionDetails": {
    "paymentProduct": "string",
    "flowType": "B2B",
    "thirdPartyPayment": false,
    "businessUseCase": "ON_RAMP"
  },
  "errors": [
    { … }
  ],
  "paymentLabels": [
    "batchId=aaaaaaaa-1111-bbbb-abab-123412341234"
  ]
}

Get state transitions by payment ID

Request

Gets the state transitions for a payment by ID.

Security
Bearer
Path
paymentIdstring(uuid)required

Unique identifier of the payment for which you want to get state transition information.

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

Responses

Successfully fetched payment state transitions.

Bodyapplication/json
stateTransitionsArray of objectsrequired
updatedFromstringrequired
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.

Example: "INITIATED"
updatedTostringrequired
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.

Example: "INITIATED"
updatedAtstring(date-time)required

The timestamp when the payment state was updated.

Example: "2024-08-13T20:15:50.990995Z"
Response
application/json
{
  "stateTransitions": [
    { … }
  ]
}

Update payment labels

Request

Add or remove labels for a payment.

Security
Bearer
Path
paymentIdstring(uuid)required

The unique ID that identifies the payment for which you want to update labels.

Example: 7ea3399c-1234-5678-8d8f-d320ea406630
Bodyapplication/jsonrequired

Labels to add to or remove from the payment.

labelsToAddArray of strings<= 10 items

List of labels associated with the payment. A label typically contains a UUID of your choice, designated as the batchId.

Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]
labelsToRemoveArray of strings<= 10 items

List of labels associated with the payment. A label typically contains a UUID of your choice, designated as the batchId.

Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]
curl -i -X PATCH \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/examples/payments-direct-external-openapi/v2/payments/7ea3399c-1234-5678-8d8f-d320ea406630/labels \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "labelsToAdd": [
      "batchId=aaaaaaaa-1111-bbbb-abab-123412341234"
    ],
    "labelsToRemove": [
      "batchId=aaaaaaaa-1111-bbbb-abab-123412341234"
    ]
  }'

Responses

Successfully updated the payment labels.

Bodyapplication/json
labelsArray of strings<= 10 itemsrequired

List of labels associated with the payment. A label typically contains a UUID of your choice, designated as the batchId.

Example: ["batchId=aaaaaaaa-1111-bbbb-abab-123412341234"]
Response
application/json
{
  "labels": [
    "batchId=aaaaaaaa-1111-bbbb-abab-123412341234"
  ]
}

Quotes

Use these API operations to manage your quotes.

OperationMethodDescription
Create quote collectionPOSTCreate a collection of quotes.
Get quote collectionGETGet a quote collection by ID.
Get a quoteGETGet a specific quote by ID.
Operations

Balances

Use this API operation to view your balances.

OperationMethodDescription
Get balancesGETView your existing
balances
Operations