Payments Direct API (2.0)

License: Apache 2.0

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 URL Description
Test https://api.test.ripple.com Test environment with simulated currency.
Production https://api.ripple.com Production 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.

Authentication

Use these API operations to manage your authentication tokens.

Operation Method Description
Request an access token POST Request an access token for authentication with Ripple APIs.
Test access token GET Test if an access token can be used for authentication.

Request an access token

Request an access token for authentication with Ripple APIs.

You need to request a token for the environment you want to authenticate with.

Note: The length of the access token isn't fixed, hence it can vary. Avoid validating tokens based on character length.

Environments

Environment Domain Description
Test api.test.ripple.com Test environment with simulated currency.
Production api.ripple.com Production environment for Ripple Payments Direct
SecurityBasicAuth
Request
header Parameters
Authorization
string

Optional base64-encoded client_id:client_secret. If provided here they aren't required in the request body.

Example: Basic ZGVtbzpwQDU1dzByZA==
Request Body schema:
client_id
required
string

The client ID associated with a specific set of API credentials.

client_secret
required
string

The client secret associated with a specific set of API credentials.

audience
required
string

The value of the audience field is based on URN syntax.

Format: urn:ripplexcurrent-{ENVIRONMENT_STRING}:{YOUR_TENANT_ID}

  • The first component is urn:ripplenetxcurrent-.
  • The second component refers to the environment you want to access.
  • The third component is your tenant ID. Ripple integration engineers provide this component during training.
Environment Environment string Description
Test test Test environment with simulated partners and simulated currency.
Production prod Production environment for Ripple's internal services.

Example: urn:ripplexcurrent-test:{YOUR_TENANT_ID}

grant_type
required
string

Set the grant-type for this client credentials request. This must be set to client_credentials.

Value: "client_credentials"
Responses
200

Returns the authentication response object that includes the token, type, scopes, and expiry.

Response Schema: application/json
access_token
string

The bearer token you use when authenticating with a Ripple API.

scope
string

List of scopes applied to your access_token.

expires_in
integer <int64>

How long your access_token is valid. You need to request a new token when it expires.

token_type
string

The type of token. Ripple APIs use Bearer auth tokens.

400

Bad Request

401

Unauthorized

403

Forbidden

post/v2/oauth/token
Request samples
{
  • "client_id": "{YOUR_CLIENT_ID}",
  • "client_secret": "{YOUR_CLIENT_SECRET}",
  • "audience": "urn:ripplexcurrent-test:{YOUR_TENANT_ID}",
  • "grant_type": "client_credentials"
}
Response samples
application/json
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ",
  • "scope": "pos:payments:create quote:quote:read pos:payments:read quote_collection:quote:create pcs_config:external_read data_requirements:read identities:read identities:write identities:create quote_collection:quote:read",
  • "expires_in": 3600,
  • "token_type": "Bearer"
}

Test access token

Test if an access token can be used for authentication with Ripple APIs and how much time remains on it.

SecurityBearer
Responses
200

If a valid bearer token is supplied, the time remaining before the token expires is returned.

Response Schema: application/json
Array
message
string
seconds_to_expiry
integer <int64>

Remaining time in seconds before the tested token expires.

400

Bad Request

401

Unauthorized

get/v2/oauth/token/test
Request samples 
Response samples 
application/json
[
  • {
    • "message": "token_ok",
    • "seconds_to_expiry": 3600
    }
]
Identities
Use these API operations to manage your identities.






Operation
Method
Description





Create an identity
POST
Create a new identity.




List identities
GET
Get a list of existing identities.




Get an identity by ID
GET
Get an identity by its unique ID.




Deactivate an identity
DELETE
Deactivate an identity.





Create a new identity
Create a new identity.


Tutorials



SecurityBearer 
Request 
Request Body schema: application/json
required
object
PII data in JSON format.


You must use the correct piiData schema for the type of identity you want to create.






Identity Type
Resources





Originator
View Originator schemas




Beneficiary
View Beneficiary schemas





 
identityType
required
string (identity-type-v2) 
The type of the identity


 Enum: Description
BENEFICIARY
Identity associated with the beneficiary.


ORIGINATOR
Identity associated with the party originating the payment.


 
nickName
string
The nickname for the identity provided at the time of identity creation


 
useCaseType
required
string (useCaseType) 
The use case type for the identity


 Enum: Description
INDIVIDUAL
Identity associated with an individual


BUSINESS
Identity associated with an institution or business


 
Responses 
201
successful operation


400
Invalid Request


500
Internal Processing Error


default
Error when processing the request


post/v2/identities
Request samples 
application/json
{
  • "piiData": { },
  • "identityType": "BENEFICIARY",
  • "nickName": "MyCompany",
  • "useCaseType": "BUSINESS"
}
Response samples 
application/json
{
  • "identityId": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
  • "version": 2
}
Get a list of identities
Get a list of identities that match the query parameters.


Note: Depending on the number of identities in your account, not all of them may be returned even if they match your query parameters.


SecurityBearer 
Request 
query Parameters
identityType
string (identity-type-v2) 
The type of identities you want to retrieve


 Enum: Description
BENEFICIARY
Identity associated with the beneficiary.


ORIGINATOR
Identity associated with the party originating the payment.


 
 Example:  identityType=BENEFICIARY
nickName
string
The nickname for the identity provided at the time of identity creation


 
 Example:  nickName=Successful Beneficiary
Responses 
200
Requested identity info in JSON format


Response Schema: application/json
Array of objects (identity-v2) 
The list of the identities that match the query parameters


 
400
Invalid request


404
No identities found


500
Internal Processing Error


get/v2/identities
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "identityId": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
      • "nickName": "MyCompany",
      • "createdAt": "2023-11-02T18:26:00.000Z",
      • "identityType": "BENEFICIARY",
      • "useCaseType": "BUSINESS"
      }
    ]
}
Get an identity by ID
Get an identity by its unique ID


SecurityBearer 
Request 
path Parameters
identity-id
required
string <uuid> 
The ID of the identity to get.


 
 Example:  2f4ac57f-c5ba-4051-b51f-b3565778717b
query Parameters
version
integer  >= 1 
Version of the identity you want to retrieve.


Note: If you don't specify a version, the latest version of the identity is returned.


 
 Example:  version=2
Responses 
200
Requested identity info in JSON format


Response Schema: application/json
identityId
required
string
The unique ID of the identity


 
identityType
required
string (identity-type-v2) 
The type of the identity


 Enum: Description
BENEFICIARY
Identity associated with the beneficiary.


ORIGINATOR
Identity associated with the party originating the payment.


 
createdAt
required
string <date-time> 
The time at which the identity was created


 
identityState
required
string (state-type) 
The state of the identity


 Enum: Description
ACTIVE
The identity requested exists and is active.


BLOCKED
The identity requested exists, but is blocked.


DEACTIVATED
The identity requested has been deactivated.


 
nickName
string
The nickname for the identity provided at the time of identity creation


 
required
object
PII data in JSON format


 
version
required
integer
The version number of the identity


 
useCaseType
required
string (useCaseType) 
The use case type for the identity


 Enum: Description
INDIVIDUAL
Identity associated with an individual


BUSINESS
Identity associated with an institution or business


 
400
Identity ID is not in UUID format


404
Invalid - identity ID does not exist


422
Identity ID is an invalid UUID string


default
Error when processing the request


get/v2/identities/{identity-id}
Request samples 
Response samples 
application/json
{
  • "identityId": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
  • "identityType": "BENEFICIARY",
  • "createdAt": "2023-11-02T18:26:00.000Z",
  • "identityState": "ACTIVE",
  • "nickName": "MyCompany",
  • "piiData": { },
  • "version": 2,
  • "useCaseType": "BUSINESS"
}
Delete an identity
Delete an identity


SecurityBearer 
Request 
path Parameters
identity-id
required
string
Unique UUID string that maps to the identity to be deleted.


 
 Example:  2f4ac57f-c5ba-4051-b51f-b3565778717b
Responses 
204
The identity was deleted successfully


400
Identity id is not of UUID format


404
Invalid Identity id does not exist


422
Unprocessable Identity Id


500
Internal Processing Error


default
Error when processing the request


delete/v2/identities/{identity-id}
Request samples 
Response samples 
application/json
{
  • "status": 404,
  • "errors": [
    • {
      • "code": "SYS_100",
      • "title": "No identity exists for identityId",
      • "type": "USER_VALIDATION_ERROR",
      • "description": "Unable to get identity. Identity ID should be in UUID format",
      • "timestamp": "2023-11-02T18:26:00.000123Z"
      }
    ],
  • "timestamp": "2023-11-02T18:26:00.000Z"
}
Quotes
Use these API operations to manage your quotes.






Operation
Method
Description





Create quote collection
POST
Create a collection of quotes.




Get quote collection
GET
Get a quote collection by ID.




Get a quote
GET
Get a specific quote by ID.





Create quote collection
SecurityBearer 
Request 
Request Body schema: application/json
Create quote collection request


quoteAmount
required
number <double>   [ 1 .. 100000000 ] 
The amount for which you wish to receive a collection of quotes.


 
quoteAmountType
required
string (QuoteAmountType) 
 Default:  "SOURCE_AMOUNT"
The type of amount for which you want to get a quote.


 Enum: Description
SOURCE_AMOUNT
Specify this value to get a quote for the amount that you want to send.


DESTINATION_AMOUNT
Specify this value to get a quote for the amount that the beneficiary should receive.


 
sourceCurrency
required
string^[a-zA-Z]{3,5}$
The currency code of the currency that you are sending.


 
destinationCurrency
required
string^[a-zA-Z]{3,5}$
The currency code of the currency in which your beneficiary will receive this payment.


 
sourceCountry
required
string^[a-zA-Z]{2}$
The country code of the country from where you are sending the funds. This is an ISO 3166-1 alpha-2 code.


 
destinationCountry
required
string^[a-zA-Z]{2}$
The country code of the country where the beneficiary receiving the funds is located. This is an ISO 3166-1 alpha-2 code.


 
payoutCategory
required
string  [ 1 .. 128 ] characters 
The name of the payout category.


 Value: Description
BANK
Indicates that the payout category is a bank.


 
payinCategory
required
string  [ 1 .. 128 ] characters 
The name of the pay in category indicating how this payment will be funded.


 Enum: Description
FUNDED
Indicates that the payment is being made from funds you've deposited with Ripple.


T_PLUS_ONE
Indicates the payment is being made and you will pay the outstanding invoice.


 
Responses 
201
Creates a collection of quotes


400
Bad request


401
Unauthorized request


403
The principal identified by the authorization header doesn't have enough scopes to perform this operation


500
Internal server error


post/v2/quotes/quote-collection
Request samples 
application/json
{
  • "quoteAmount": 123.45,
  • "quoteAmountType": "SOURCE_AMOUNT",
  • "sourceCurrency": "USD",
  • "destinationCurrency": "MXN",
  • "sourceCountry": "US",
  • "destinationCountry": "PH",
  • "payoutCategory": "BANK",
  • "payinCategory": "FUNDED"
}
Response samples 
application/json
{
  • "quoteCollectionId": "11111111-aaaa-2222-bbbb-222222222222",
  • "quotes": [
    • {
      • "quoteId": "22222222-aaaa-2222-bbbb-222222222222",
      • "quoteStatus": "ACTIVE",
      • "quoteAmountType": "SOURCE_AMOUNT",
      • "sourceAmount": 123.45,
      • "destinationAmount": 2438.19,
      • "sourceCurrency": "USD",
      • "destinationCurrency": "MXN",
      • "sourceCountry": "US",
      • "destinationCountry": "MX",
      • "payoutCategory": "BANK",
      • "payinCategory": "FUNDED",
      • "adjustedExchangeRate": {
        • "adjustedRate": 2
        },
      • "fees": [
        • {
          • "totalFee": 3.12,
          • "feeCurrency": "USD",
          • "feeBreakdown": [
            • {
              • "calculatedFee": 3.03,
              • "feeName": "Service fee",
              • "feeDescription": "The service fee charged for this transaction."
              }
            ]
          }
        ],
      • "createdAt": "2023-11-02T18:26:00.000123Z",
      • "expiresAt": "2023-11-02T18:26:00.000123Z"
      }
    ]
}
Get quote collection
SecurityBearer 
Request 
path Parameters
quote-collection-id
required
string <uuid> 
The unique identifier of the quote collection you want to retrieve


 
 Example:  11111111-aaaa-2222-bbbb-222222222222
Responses 
200
Valid quote collection found


Response Schema: application/json
quoteCollectionId
required
string <uuid>   [ 1 .. 36 ] characters 
Unique ID that represents this quote collection.


 
required
Array of objects (Quote)   >= 0 items 
List of quotes


 
401
Unauthorized request


403
The principal identified by the authorization header doesn't have enough scopes to perform this operation


404
Quote collection not found


500
Internal server error


get/v2/quotes/quote-collection/{quote-collection-id}
Request samples 
Response samples 
application/json
{
  • "quoteCollectionId": "11111111-aaaa-2222-bbbb-222222222222",
  • "quotes": [
    • {
      • "quoteId": "22222222-aaaa-2222-bbbb-222222222222",
      • "quoteStatus": "ACTIVE",
      • "quoteAmountType": "SOURCE_AMOUNT",
      • "sourceAmount": 123.45,
      • "destinationAmount": 2438.19,
      • "sourceCurrency": "USD",
      • "destinationCurrency": "MXN",
      • "sourceCountry": "US",
      • "destinationCountry": "MX",
      • "payoutCategory": "BANK",
      • "payinCategory": "FUNDED",
      • "adjustedExchangeRate": {
        • "adjustedRate": 2
        },
      • "fees": [
        • {
          • "totalFee": 3.12,
          • "feeCurrency": "USD",
          • "feeBreakdown": [
            • {
              • "calculatedFee": 3.03,
              • "feeName": "Service fee",
              • "feeDescription": "The service fee charged for this transaction."
              }
            ]
          }
        ],
      • "createdAt": "2023-11-02T18:26:00.000123Z",
      • "expiresAt": "2023-11-02T18:26:00.000123Z"
      }
    ]
}
Get quote
SecurityBearer 
Request 
path Parameters
quote-id
required
string <uuid> 
The unique identifier of the quote to retrieve


 
 Example:  22222222-aaaa-2222-bbbb-222222222222
Responses 
200
Valid quote found


Response Schema: application/json
quoteId
required
string <uuid>   [ 1 .. 36 ] characters 
Unique ID that represents this quote.


 
quoteStatus
required
string (QuoteStatus) 
 Enum: Description
EXPIRED
Expired quote


ACTIVE
Quote that you can accept to create a payment.


 
quoteAmountType
string (QuoteAmountType) 
 Default:  "SOURCE_AMOUNT"
The type of amount for which you want to get a quote.


 Enum: Description
SOURCE_AMOUNT
Specify this value to get a quote for the amount that you want to send.


DESTINATION_AMOUNT
Specify this value to get a quote for the amount that the beneficiary should receive.


 
sourceAmount
number <double>   [ 1 .. 100000000 ] 
Amount to be sent by the originator.


 
destinationAmount
number <double>   [ 1 .. 100000000 ] 
Amount to be received by destination


 
sourceCurrency
required
string^[a-zA-Z]{3,5}$
The currency code of the currency that you are sending.


 
destinationCurrency
required
string^[a-zA-Z]{3,5}$
The currency code of the currency in which your beneficiary will receive this payment.


 
sourceCountry
required
string^[a-zA-Z]{2}$
The country code to which you wish to receive the funds. It follows ISO 3166-1 alpha-2 code


 
destinationCountry
required
string^[a-zA-Z]{2}$
The country code to which you wish to send the funds. It follows ISO 3166-1 alpha-2 code


 
payoutCategory
required
string  [ 1 .. 128 ] characters 
Name of the payout category specified in the quote request.


 
payinCategory
required
string  [ 1 .. 128 ] characters 
The name of payin category specified in the quote request.


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


 
Array of objects (QuoteQuoteFeeSummary) 
A summary of fees included in this quote.


 
createdAt
string <date-time>   [ 1 .. 128 ] characters 
The time when this quote was created, specified in UTC.


 
expiresAt
string <date-time>   [ 1 .. 128 ] characters 
The time when this quote expires, specified in UTC.


 
401
Unauthorized request


403
The principal identified by the authorization header doesn't have enough scopes to perform this operation


404
Quote not found


500
Internal server error


get/v2/quotes/{quote-id}
Request samples 
Response samples 
application/json
{
  • "quoteId": "22222222-aaaa-2222-bbbb-222222222222",
  • "quoteStatus": "ACTIVE",
  • "quoteAmountType": "SOURCE_AMOUNT",
  • "sourceAmount": 123.45,
  • "destinationAmount": 2438.19,
  • "sourceCurrency": "USD",
  • "destinationCurrency": "MXN",
  • "sourceCountry": "US",
  • "destinationCountry": "MX",
  • "payoutCategory": "BANK",
  • "payinCategory": "FUNDED",
  • "adjustedExchangeRate": {
    • "adjustedRate": 2
    },
  • "fees": [
    • {
      • "totalFee": 3.12,
      • "feeCurrency": "USD",
      • "feeBreakdown": [
        • {
          • "calculatedFee": 3.03,
          • "feeName": "Service fee",
          • "feeDescription": "The service fee charged for this transaction."
          }
        ]
      }
    ],
  • "createdAt": "2023-11-02T18:26:00.000123Z",
  • "expiresAt": "2023-11-02T18:26:00.000123Z"
}
Payments
Use these API operations to manage your payments.






Operation
Method
Description





Search payments
POST
Search for payments based on filtering criteria.




Create a payment
POST
Create a payment by accepting a quote.




Get payment by payment ID
GET
Get a specific payment by payment ID.





Search payments
Search for payments based on filtering criteria.


SecurityBearer 
Request 
Request Body schema: application/json
Search payments request


object (PaymentFilter) 
Filter criteria to return desired payment search results.


 
object (Sort) 
Specify sorting direction and the filtering criterion to sort by.


 
object (Page) 
Specify page size and the ID of the last fetched result.


 
Responses 
200
Payments matching the specified filtering criteria.


Response Schema: application/json
Array of objects (Payment) 
Array of Payment objects


 
object (PaymentFilter) 
Filter criteria to return desired payment search results.


 
object (Page) 
Specify page size and the ID of the last fetched result.


 
400
Invalid input variables for the request.


500
Internal processing error


post/v2/payments/filter
Request samples 
application/json
{
  • "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"
      ]
    },
  • "sort": {
    • "sortField": "initiatedAt",
    • "sortDirection": "DESC"
    },
  • "page": {
    • "size": 20,
    • "lastPageToken": 1738865155690
    }
}
Response samples 
application/json
{
  • "data": [
    • {
      • "paymentId": "7ea3399c-1234-5678-8d8f-d320ea406630",
      • "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",
        • "beneficiaryIdentityId": "7ea3399c-1234-5678-8d8f-d320ea406630",
        • "beneficiaryIdentityVersion": 1,
        • "beneficiaryIdentityNickName": "Successful business beneficiary",
        • "payout": "BANK"
        },
      • "fxRate": 2,
      • "fees": [
        • {
          • "totalFee": 12.23,
          • "feeCurrency": "USD"
          }
        ],
      • "sourceOfCash": "EMIN",
      • "purposeCode": "PAYR"
      }
    ],
  • "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"
      ]
    },
  • "page": {
    • "size": 20,
    • "lastPageToken": 1738865155690
    }
}
Create payment
Create a payment


SecurityBearer 
Request 
Request Body schema: application/json
create payment request


quoteId
required
string <uuid> 
ID of the quote you want to accept to initiate this payment. Must be in UUID format. This will be used as paymentId.


 
originatorIdentityId
string <uuid> 
The identity ID of the payment originator in UUID format. You can find the identity ID using the GET /identities operation.


 
beneficiaryIdentityId
required
string <uuid> 
The identity ID of the payment beneficiary in UUID format. You can find the identity ID using the GET /identities operation.


 
internalId
string  <= 36 characters 
Customer defined value, such as an invoice number.


 
purposeCode
string
Indicates the purpose of the payment


For more information about the purposeCode options, see purposeCode.


 
sourceOfCash
string
Source of cash for payout.


 Enum: Description
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


REST
Real Estate Sale


RETA
Retained Earnings


SALE
Sale Of Goods


SEAQ
Sale Aquisition Corporation


SELF
Self Employment Income


SVGS
Savings


WINS
Winnings


 
Responses 
200
Valid payment


Response Schema: application/json
paymentId
required
string <uuid>   <= 36 characters 
The unique ID that identifies this payment. This value is the same as the quote ID.


 
initiatedAt
string <date-time> 
The time at which the payment was initiated, specified in UTC.


 
expiresAt
string <date-time> 
The time at which this payment expires, specified in UTC.


 
lastStateUpdatedAt
string <date-time> 
The time at which the payment state was last updated for this payment, specified in UTC.


 
paymentState
required
string (PaymentState) 
 Enum: Description
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.


 
object (Originator) 
Payment originator and source details.


 
object (Destination) 
Payment beneficiary and destination details.


 
fxRate
number <double> 
The quoted foreign exchange rate for this payment.


 
Array of objects (FeeSummary) 
A summary of fees included in payment quote.


 
sourceOfCash
string
Indicates the source of funds


 Enum: Description
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


REST
Real Estate Sale


RETA
Retained Earnings


SALE
Sale Of Goods


SEAQ
Sale Aquisition Corporation


SELF
Self Employment Income


SVGS
Savings


WINS
Winnings


 
purposeCode
string
Indicates the purpose of the payment


For more information about the purposeCode options, see  purposeCode.


 
400
Invalid input variables for the payment.


402
Problems related to payment limits.


500
Internal processing error


post/v2/payments
Request samples 
application/json
{
  • "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"
}
Response samples 
application/json
{
  • "paymentId": "7ea3399c-1234-5678-8d8f-d320ea406630",
  • "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",
    • "beneficiaryIdentityId": "7ea3399c-1234-5678-8d8f-d320ea406630",
    • "beneficiaryIdentityVersion": 1,
    • "beneficiaryIdentityNickName": "Successful business beneficiary",
    • "payout": "BANK"
    },
  • "fxRate": 2,
  • "fees": [
    • {
      • "totalFee": 12.23,
      • "feeCurrency": "USD"
      }
    ],
  • "sourceOfCash": "EMIN",
  • "purposeCode": "PAYR"
}
Get a payment by ID
Gets a payment by ID.


SecurityBearer 
Request 
path Parameters
paymentId
required
string <uuid> 
Unique identifier of the payment to get.


 
 Example:  7ea3399c-1234-5678-8d8f-d320ea406630
Responses 
200
Successfully fetched payment details.


Response Schema: application/json
paymentId
required
string <uuid>   <= 36 characters 
The unique ID that identifies this payment. This value is the same as the quote ID.


 
initiatedAt
string <date-time> 
The time at which the payment was initiated, specified in UTC.


 
expiresAt
string <date-time> 
The time at which this payment expires, specified in UTC.


 
lastStateUpdatedAt
string <date-time> 
The time at which the payment state was last updated for this payment, specified in UTC.


 
paymentState
required
string (PaymentState) 
 Enum: Description
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.


 
object (Originator) 
Payment originator and source details.


 
object (Destination) 
Payment beneficiary and destination details.


 
fxRate
number <double> 
The quoted foreign exchange rate for this payment.


 
Array of objects (FeeSummary) 
A summary of fees included in payment quote.


 
sourceOfCash
string
Indicates the source of funds


 Enum: Description
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


REST
Real Estate Sale


RETA
Retained Earnings


SALE
Sale Of Goods


SEAQ
Sale Aquisition Corporation


SELF
Self Employment Income


SVGS
Savings


WINS
Winnings


 
purposeCode
string
purposeCode for RPD payments


 
Array of objects (PaymentError) 
 
400
Invalid input variables for the payment.


404
Payment not found.


500
Internal processing error


get/v2/payments/{paymentId}
Request samples 
Response samples 
application/json
{
  • "paymentId": "7ea3399c-1234-5678-8d8f-d320ea406630",
  • "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",
    • "beneficiaryIdentityId": "7ea3399c-1234-5678-8d8f-d320ea406630",
    • "beneficiaryIdentityVersion": 1,
    • "beneficiaryIdentityNickName": "Successful business beneficiary",
    • "payout": "BANK"
    },
  • "fxRate": 2,
  • "fees": [
    • {
      • "totalFee": 12.23,
      • "feeCurrency": "USD"
      }
    ],
  • "sourceOfCash": "EMIN",
  • "purposeCode": "string",
  • "errors": [
    • {
      • "code": "SYS_003",
      • "type": "SYSTEM_ERROR",
      • "title": "Internal Server Error",
      • "description": "The payout category value must be one of BANK, EWALLET, CASH_PICKUP, or ATM.",
      • "timestamp": "2024-11-21T14:15:22Z"
      }
    ]
}
Get state transitions by payment ID
Gets the state transitions for a payment by ID.


SecurityBearer 
Request 
path Parameters
paymentId
required
string <uuid> 
Unique identifier of the payment for which you want to get state transition information.


 
 Example:  7ea3399c-1234-5678-8d8f-d320ea406630
Responses 
200
Successfully fetched payment state transitions.


Response Schema: application/json
required
Array of objects (StateTransition) 
 
400
Invalid input variables for the payment.


404
Payment not found.


500
Internal processing error


get/v2/payments/{paymentId}/states
Request samples 
Response samples 
application/json
{
  • "stateTransitions": [
    • {
      • "updatedFrom": "INITIATED",
      • "updatedTo": "INITIATED",
      • "updatedAt": "2024-08-13T20:15:50.990995Z"
      }
    ]
}