{
"openapi": "3.0.3",
"info": {
"title": "Payments Direct API",
"version": 2026.03,
"license": {
"name": "Apache 2.0",
"url": "http://apache.org"
},
"description": "Use the Payments Direct API to get quotes, create and manage payments, and manage originator and beneficiary identities.\n\n## API environments\n\nThe Payments Direct API offers the following environments:\n\n| Environment
| Base URL | Description |\n| ------------------------------------------ | ----------------------------- | ----------------------------------------- |\n| UAT | `https://api.test.ripple.com` | UAT environment with simulated currency. |\n| Production | `https://api.ripple.com` | Production environment |\n\n## API authentication\n\nAll {% $env.PUBLIC_VAR_RPD %} 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.\n\n### Generate client ID and client secret\n\nYou will need your _client ID_ and _client secret_ to obtain an access token.\n\nIf you do not already have your client ID and client secret, do the following:\n\n1. Log into the Ripple Payments UI.\n2. In the left navigation menu, click **Settings**.\n3. Under **Administration**, click **API Credentials**.\n4. In the dropdown list next to the page title, select the access environment. For example, to provision credentials for the test environment, select **UAT** from the dropdown list.\n5. In the upper right corner of the page, click **New Credential**.\n6. Click **Save and Generate Key**.\n\n**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.\n\nYou can now use the client ID and client secret to generate access tokens using the [Request an access token](/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/authentication/authenticate) operation.\n\n### Request an access token\n\nTo get an access token, use the [Request an access token](/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/authentication/authenticate) operation with your `client_id` and `client_secret`. The response contains a token in the `access_token` field.\n\nWe recommend rotating your API credentials at regular intervals according to your organization's security policy.\n\n**Note**: Authentication tokens are not a fixed length and can vary, avoid validating tokens based on character length.\n"
},
"servers": [
{
"url": "https://api.test.ripple.com",
"description": "UAT environment with simulated currency"
},
{
"url": "https://api.ripple.com",
"description": "Production environment"
}
],
"tags": [
{
"name": "Authentication",
"description": "Use these API operations to manage your authentication tokens.\n\n| Operation | Method | Description |\n| --- | --- | --- |\n| [Request an access token](#operation/authenticate) | POST | Request an access token for authentication with Ripple APIs. |\n| [Test access token](#operation/testAuthToken) | GET | Test if an access token can be used for authentication. |\n",
"x-displayName": "Authentication"
},
{
"name": "IdentitiesV3",
"x-displayName": "Identities (v3)",
"description": "Use these API operations to manage your identities with **Identity Management v3** (recommended for all new integrations).\n**Note:** **Identity Management v3** is scheduled for release in **April 2026**. For early access or specific migration details, please contact your Ripple representative.\nFor more information about identity management, see [Payment identities](/products/payments-direct-2/api-docs/concepts/payment-identities) and [Financial instruments](/products/payments-direct-2/api-docs/concepts/financial-instruments).\n| Operation | Method | Description |\n| --- | --- | --- |\n| [Create an identity (v3)](./#operation/createIdentity) | POST | Create a new identity (INDIVIDUAL/BUSINESS; ORIGINATOR/BENEFICIARY). |\n| [Get a list of identies (v3)](./#operation/getIdentities) | GET | Retrieve a list of identities with optional filters (e.g., `paymentRole`, `identityType`). |\n| [Get an identity by ID (v3)](./#operation/getIdentityById) | GET | Retrieve a specific identity by `identityId` (latest version by default). |\n| [Get an identity by internal ID (v3)](./#operation/getIdentityByInternalId) | GET | Retrieve an active identity by client-provided `internalId`. |\n| [Update an identity (v3)](./#operation/putIdentity) | PUT | Update one or more fields; creates a new version. |\n| [Deactivate an identity (v3)](./#operation/deactivateIdentityV3) | DELETE | Set the identity state to `DEACTIVATED` (cannot be used for new payments). |\n| [Add a financial instrument (v3)](./#operation/createFinancialInstrument) | POST | Add a financial instrument to an identity. |\n| [Get a list of financial instruments (v3)](./#operation/getFinancialInstruments) | GET | Get a list of financial instruments for an identity. |\n| [Get a financial instrument by ID (v3)](./#operation/getFinancialInstrumentById) | GET | Get a specific financial instrument by `financialInstrumentId`. |\n| [Update a financial instrument (v3)](./#operation/putFinancialInstrument) | PUT | Update a financial instrument by `financialInstrumentId`. |\n| [Deactivate a financial instrument (v3)](./#operation/deactivateFinancialInstrumentV3) | DELETE | Deactivate a financial instrument by `financialInstrumentId`. |\n"
},
{
"name": "Quote",
"x-displayName": "Quotes",
"description": "Use these API operations to manage your quotes.\n\n| Operation | Method | Description |\n| --- | --- | --- |\n| [Create quote collection](./#operation/createQuoteCollection) | POST | Create a collection of quotes. |\n| [Get quote collection](./#operation/getQuoteCollection) | GET | Get a quote collection by ID. |\n| [Get a quote](./#operation/getQuote) | GET | Get a specific quote by ID. |\n"
},
{
"name": "PaymentsV2",
"x-displayName": "Payments (v3)",
"description": "Use these API operations to manage your payments with **Payment Management v3** (recommended for all new integrations).\n\n| Operation | Method | Description |\n| --- | --- | --- |\n| [Search payments (v3)](./#operation/searchPaymentsV2) | POST | Search for v3 payments based on filtering criteria. |\n| [Create a payment (v3)](./#operation/createPaymentV2) | POST | Create a v3payment by accepting a quote. |\n| [Get payment by payment ID (v3)](./#operation/getPaymentByIdV2) | GET | Get a specific v3 payment by payment ID. |\n| [Get state transitions by payment ID (v3)](./#operation/getPaymentStateTransitionsByIdV2) | GET | Get the state transitions for a specific v3 payment by payment ID. |\n| [Update payment labels (v3)](./#operation/updatePaymentLabelsV2) | PATCH | Update the labels for a specific v3 payment by payment ID. |\n"
},
{
"name": "ledger-public",
"x-displayName": "Ledger",
"description": "Use these API operation to fetch ledger transactions and check balances.\n\n| Operation | Method | Description |\n| --- | --- | --- |\n| [Get balances](./#operation/getBalances) | GET | View your existing balances |\n| [Get ledger transactions](./#operation/getStatementsTransactionsForCustomer) | GET | View your ledger transactions. |\n"
}
],
"paths": {
"/v2/oauth/token": {
"post": {
"tags": [
"Authentication"
],
"operationId": "authenticate",
"summary": "Request an access token",
"parameters": [
{
"in": "header",
"name": "Authorization",
"required": false,
"schema": {
"type": "string",
"description": "Optional [base64-encoded](https://datatracker.ietf.org/doc/html/rfc7617) `client_id:client_secret`. If provided here they aren't required in the request body.",
"example": "Basic ZGVtbzpwQDU1dzByZA=="
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthenticationRequest"
}
},
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/AuthenticationRequest"
}
}
}
},
"responses": {
"200": {
"description": "Returns the authentication response object that includes the token, type, scopes, and expiry.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthenticationResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error_description": "Missing required parameter: grant_type",
"error": "invalid_request"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error_description": "Unauthorized",
"error": "access_denied"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"error_description": "Service not enabled within domain: ",
"error": "access_denied"
}
}
}
}
},
"description": "Request an access token for authentication with Ripple APIs.\n\nYou need to request a token for the environment you want to authenticate with.\n\n**Note**: The length of the access token isn't fixed, hence it can vary. Avoid validating tokens based on character length.\n\n**Tutorials**\n\n* Learn how to [Request an access token](/products/payments-direct-2/api-docs/tutorials/request-an-access-token).\n\n#### Environments\n\n| Environment | Domain | Description |\n| --- | --- | --- |\n| Test | `api.test.ripple.com` | Test environment with simulated currency. |\n| Production | `api.ripple.com` | Production environment for Ripple Payments Direct |\n",
"security": [
{
"BasicAuth": []
}
]
}
},
"/v2/oauth/token/test": {
"get": {
"tags": [
"Authentication"
],
"operationId": "testAuthToken",
"security": [
{
"Bearer": []
}
],
"summary": "Test access token",
"description": "Test if an access token can be used for authentication with Ripple APIs and how much time remains on it.",
"responses": {
"200": {
"description": "If a valid bearer token is supplied, the time remaining before the token expires is returned.",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/ValidateTokenResponse"
},
"type": "array"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"text/plain": {
"schema": {
"type": "string"
},
"example": "Invalid Request parameters [Invalid bearer authentication token]"
}
}
},
"401": {
"description": "Unauthorized"
}
}
}
},
"/v3/payments/filter": {
"post": {
"tags": [
"PaymentsV2"
],
"security": [
{
"Bearer": []
}
],
"operationId": "searchPaymentsV2",
"summary": "Search payments V2",
"description": "Search for payments based on filtering criteria.",
"requestBody": {
"description": "Search payments request",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchPaymentsRequestV2"
}
}
}
},
"responses": {
"200": {
"description": "Payments matching the specified filtering criteria.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentsResponseV2"
}
}
}
},
"400": {
"description": "Invalid input variables for the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentErrorResponse"
},
"example": {
"status": 400,
"errors": {
"code": "USR_001",
"type": "USER_VALIDATION_ERROR",
"title": "Bad Request",
"description": "Invalid request. Check your request parameters and try again.",
"timestamp": "2024-12-01T12:00:00Z"
}
}
}
}
},
"500": {
"description": "Internal processing error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentErrorResponse"
},
"example": {
"status": 500,
"errors": {
"code": "SYS_001",
"type": "SYSTEM_ERROR",
"title": "Internal Server Error",
"description": "Unable to process the request due to an internal server error.",
"timestamp": "2024-12-01T12:00:00Z"
}
}
}
}
}
}
}
},
"/v3/payments": {
"post": {
"tags": [
"PaymentsV2"
],
"security": [
{
"Bearer": []
}
],
"operationId": "createPaymentV2",
"summary": "Create payment V2",
"description": "Create a payment\n\n**Tutorial**\n\n* Learn how to [Create a payment](/products/payments-direct-2/api-docs/tutorials/create-a-payment/).\n",
"requestBody": {
"description": "create payment request",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentRequestV2"
}
}
}
},
"responses": {
"201": {
"description": "Valid payment",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentV2"
}
}
}
},
"400": {
"description": "Invalid input variables for the payment.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentErrorResponse"
},
"example": {
"status": 400,
"errors": {
"code": "USR_001",
"type": "USER_VALIDATION_ERROR",
"title": "Bad Request",
"description": "Invalid request. Check your request parameters and try again.",
"timestamp": "2024-12-01T12:00:00Z"
}
}
}
}
},
"402": {
"description": "Problems related to payment limits.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentErrorResponse"
},
"example": {
"status": 402,
"errors": {
"code": "USR_067",
"type": "USER_ERROR",
"title": "Insufficient balance",
"description": "Payment failed due to insufficient balance. Add funds to your account and try again.",
"timestamp": "2024-12-01T12:00:00Z"
}
}
}
}
},
"500": {
"description": "Internal processing error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentErrorResponse"
},
"example": {
"status": 500,
"errors": {
"code": "SYS_001",
"type": "SYSTEM_ERROR",
"title": "Internal Server Error",
"description": "Unable to process the request due to an internal server error.",
"timestamp": "2024-12-01T12:00:00Z"
}
}
}
}
}
}
}
},
"/v3/payments/{paymentId}": {
"get": {
"tags": [
"PaymentsV2"
],
"security": [
{
"Bearer": []
}
],
"operationId": "getPaymentByIdV2",
"description": "Gets a payment by ID.",
"summary": "Get a payment by ID V2",
"parameters": [
{
"in": "path",
"name": "paymentId",
"description": "Unique identifier of the payment to get.",
"example": "7ea3399c-1234-5678-8d8f-d320ea406630",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successfully fetched payment details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentWithDetailsV2"
}
}
}
},
"400": {
"description": "Invalid input variables for the payment.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentErrorResponse"
},
"example": {
"status": 400,
"errors": {
"code": "USR_001",
"type": "USER_VALIDATION_ERROR",
"title": "Bad Request",
"description": "Invalid request. Check your request parameters and try again.",
"timestamp": "2024-12-01T12:00:00Z"
}
}
}
}
},
"404": {
"description": "Payment not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentErrorResponse"
},
"example": {
"status": 404,
"errors": {
"code": "USR_002",
"type": "NOT_FOUND",
"title": "Resource Not Found",
"description": "The requested resource could not be found.",
"timestamp": "2024-12-01T12:00:00Z"
}
}
}
}
},
"500": {
"description": "Internal processing error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentErrorResponse"
},
"example": {
"status": 500,
"errors": {
"code": "SYS_001",
"type": "SYSTEM_ERROR",
"title": "Internal Server Error",
"description": "Unable to process the request due to an internal server error.",
"timestamp": "2024-12-01T12:00:00Z"
}
}
}
}
}
}
}
},
"/v3/payments/{paymentId}/states": {
"get": {
"tags": [
"PaymentsV2"
],
"security": [
{
"Bearer": []
}
],
"operationId": "getPaymentStateTransitionsByIdV2",
"description": "Gets the state transitions for a payment by ID.",
"summary": "Get state transitions by payment ID",
"parameters": [
{
"in": "path",
"name": "paymentId",
"description": "Unique identifier of the payment for which you want to get state transition information.",
"example": "7ea3399c-1234-5678-8d8f-d320ea406630",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successfully fetched payment state transitions.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StateTransitionsResponseV2"
}
}
}
},
"400": {
"description": "Invalid input variables for the payment.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentErrorResponse"
},
"example": {
"status": 400,
"errors": {
"code": "USR_001",
"type": "USER_VALIDATION_ERROR",
"title": "Bad Request",
"description": "Invalid request. Check your request parameters and try again.",
"timestamp": "2024-12-01T12:00:00Z"
}
}
}
}
},
"404": {
"description": "Payment not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentErrorResponse"
},
"example": {
"status": 404,
"errors": {
"code": "USR_002",
"type": "NOT_FOUND",
"title": "Resource Not Found",
"description": "The requested resource could not be found.",
"timestamp": "2024-12-01T12:00:00Z"
}
}
}
}
},
"500": {
"description": "Internal processing error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentErrorResponse"
},
"example": {
"status": 500,
"errors": {
"code": "SYS_001",
"type": "SYSTEM_ERROR",
"title": "Internal Server Error",
"description": "Unable to process the request due to an internal server error.",
"timestamp": "2024-12-01T12:00:00Z"
}
}
}
}
}
}
}
},
"/v3/payments/{paymentId}/labels": {
"patch": {
"tags": [
"PaymentsV2"
],
"security": [
{
"Bearer": []
}
],
"operationId": "updatePaymentLabelsV2",
"summary": "Update payment labels",
"description": "Add or remove labels for a payment.",
"parameters": [
{
"in": "path",
"name": "paymentId",
"description": "The unique ID that identifies the payment for which you want to update labels.",
"example": "7ea3399c-1234-5678-8d8f-d320ea406630",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"description": "Labels to add to or remove from the payment.",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdatePaymentLabelsRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successfully updated the payment labels.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdatePaymentLabelsResponse"
}
}
}
},
"400": {
"description": "Invalid input variables for the request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentErrorResponse"
},
"example": {
"status": 400,
"errors": {
"code": "USR_001",
"type": "USER_VALIDATION_ERROR",
"title": "Bad Request",
"description": "Invalid request. Check your request parameters and try again.",
"timestamp": "2024-12-01T12:00:00Z"
}
}
}
}
},
"404": {
"description": "Payment not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentErrorResponse"
},
"example": {
"status": 404,
"errors": {
"code": "USR_002",
"type": "NOT_FOUND",
"title": "Resource Not Found",
"description": "The requested resource could not be found.",
"timestamp": "2024-12-01T12:00:00Z"
}
}
}
}
},
"500": {
"description": "Internal processing error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentErrorResponse"
},
"example": {
"status": 500,
"errors": {
"code": "SYS_001",
"type": "SYSTEM_ERROR",
"title": "Internal Server Error",
"description": "Unable to process the request due to an internal server error.",
"timestamp": "2024-12-01T12:00:00Z"
}
}
}
}
}
}
}
},
"/v3/identities": {
"post": {
"tags": [
"IdentitiesV3"
],
"security": [
{
"Bearer": []
}
],
"operationId": "createIdentity",
"summary": "Create an identity (v3)",
"description": "Create a new payment identity as an ORIGINATOR or BENEFICIARY for either an INDIVIDUAL or BUSINESS.\nThe request body must follow the v3 identity schema and will be validated against corridor rules where applicable.\nOn success, the API returns the new identityId and its initial version.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create-identity-request-v3"
},
"examples": {
"create-individual-originator": {
"summary": "INDIVIDUAL ORIGINATOR",
"value": {
"identityType": "INDIVIDUAL",
"paymentRole": "ORIGINATOR",
"internalId": "customer-12345-uuid",
"nickName": "Alice Sender USD",
"tags": [
"sender",
"priority"
],
"validatePayoutRails": [
"CO_PSE"
],
"individual": {
"firstName": "Alice",
"lastName": "Chen",
"dateOfBirth": "1990-05-14",
"citizenship": "US",
"address": {
"streetAddress": [
"123 Main Street"
],
"city": "San Francisco",
"stateOrProvince": "CA",
"postalCode": "94105",
"country": "US"
}
}
}
},
"create-business-beneficiary": {
"summary": "BUSINESS BENEFICIARY",
"value": {
"identityType": "BUSINESS",
"paymentRole": "BENEFICIARY",
"nickName": "Widgets Org MX",
"tags": [
"beneficiary",
"mx"
],
"validatePayoutRails": [
"CO_PSE"
],
"business": {
"businessName": "Widgets Org",
"incorporationCountry": "US",
"registration": [
{
"number": "123ABC",
"type": "INCORPORATION_CERTIFICATE"
}
],
"email": "fake@example.com",
"phone": "+1234567890",
"address": {
"streetAddress": [
"123 Example MA"
],
"city": "Boston",
"stateOrProvince": "MS",
"postalCode": "12345",
"country": "US"
}
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Identity created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create-identity-response-v3"
},
"example": {
"identityId": "99254c4f-f207-4792-a846-06928825018c",
"version": "1"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-400": {
"$ref": "#/components/examples/error-400-example"
}
}
}
}
},
"409": {
"description": "Conflict - An identity with the provided internalId already exists.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
}
}
}
},
"500": {
"description": "Internal processing error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-500": {
"$ref": "#/components/examples/error-500-example"
}
}
}
}
}
}
},
"get": {
"tags": [
"IdentitiesV3"
],
"security": [
{
"Bearer": []
}
],
"operationId": "getIdentities",
"summary": "Get a list of identities (v3)",
"description": "Retrieve identities for your tenant with optional filters.\nUse `limit` and `next-token` for pagination. The response includes a `data` array and an optional `nextToken`.\n",
"parameters": [
{
"in": "query",
"name": "payment-role",
"required": false,
"schema": {
"type": "string"
},
"example": "BENEFICIARY",
"description": "Filter by payment role."
},
{
"in": "query",
"name": "nick-name",
"required": false,
"schema": {
"type": "string",
"maxLength": 256
},
"example": "Alice",
"description": "Filter by nickname."
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"example": 20,
"default": 10
},
"description": "Maximum number of identities to return. Default value is 10, maximum is 100."
},
{
"in": "query",
"name": "next-token",
"required": false,
"schema": {
"type": "string"
},
"example": "eyJrZXkxIjoidmFsdWVfMSIsImtleTIiOiJ2YWx1ZTIifQ==",
"description": "Opaque token to fetch the next page of results."
}
],
"responses": {
"200": {
"description": "A page of identities.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list-identities-response-v3"
},
"examples": {
"list-identities-v3": {
"value": {
"data": [
{
"identityId": "0116bacc-ffbf-4fa2-a29c-ecd9ea346806",
"identityType": "BUSINESS",
"paymentRole": "BENEFICIARY",
"createdAt": "2025-10-01T16:14:13.200Z",
"updatedAt": "2025-10-01T16:14:15.763Z",
"identityState": "ACTIVE",
"nickName": "testNickName",
"tags": [
"tag1"
],
"version": 2,
"schemaVersion": "1.0.0"
},
{
"identityId": "1d927c62-45fa-4f42-b9f8-8210e1a111bb",
"identityType": "INDIVIDUAL",
"paymentRole": "ORIGINATOR",
"createdAt": "2025-10-01T17:20:05.111Z",
"updatedAt": "2025-10-01T17:20:06.500Z",
"identityState": "ACTIVE",
"nickName": "Alice Originator",
"tags": [
"sender",
"priority"
],
"version": 1,
"schemaVersion": "1.0.0"
}
],
"nextToken": "eyJrZXkxIjoidmFsdWUifQ=="
}
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-400": {
"$ref": "#/components/examples/error-400-example"
}
}
}
}
},
"404": {
"description": "No identities found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-404": {
"$ref": "#/components/examples/error-404-example"
}
}
}
}
},
"500": {
"description": "Internal processing error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-500": {
"$ref": "#/components/examples/error-500-example"
}
}
}
}
}
}
}
},
"/v3/identities/{identity-id}": {
"get": {
"tags": [
"IdentitiesV3"
],
"security": [
{
"Bearer": []
}
],
"operationId": "getIdentityById",
"summary": "Get an identity by ID (v3)",
"description": "Retrieve a specific identity by ID.\nIf `version` is not provided, the latest version is returned.\n",
"parameters": [
{
"name": "identity-id",
"in": "path",
"required": true,
"description": "The ID of the identity to retrieve.",
"example": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "version",
"description": "Specific version to retrieve. If omitted, returns the latest version.",
"example": "2",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Identity details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get-identity-response-v3"
},
"examples": {
"get-identity-v3": {
"value": {
"identityId": "9d839f58-7fd3-4913-a27e-48d31973d3f9",
"identityState": "ACTIVE",
"nickName": "nickName",
"tags": [
"tag1"
],
"version": "2",
"schemaVersion": "1.0.0",
"createdAt": "2025-10-01T18:46:41.833Z",
"updatedAt": "2025-10-01T18:46:47.430Z",
"identityType": "BUSINESS",
"paymentRole": "BENEFICIARY",
"business": {
"businessName": "Widgets Org",
"address": {
"streetAddress": [
"123 Example MA"
],
"country": "US",
"city": "Boston",
"stateOrProvince": "MS",
"postalCode": "12345"
},
"email": "fake@example.com",
"phone": "+1234567890",
"registration": [
{
"number": "123ABC",
"type": "INCORPORATION_CERTIFICATE"
}
],
"incorporationCountry": "US"
}
}
}
}
}
}
},
"400": {
"description": "Invalid identity ID.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-400": {
"$ref": "#/components/examples/error-400-example"
}
}
}
}
},
"404": {
"description": "Identity not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-404": {
"$ref": "#/components/examples/error-404-example"
}
}
}
}
},
"500": {
"description": "Internal processing error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-500": {
"$ref": "#/components/examples/error-500-example"
}
}
}
}
}
}
},
"put": {
"tags": [
"IdentitiesV3"
],
"security": [
{
"Bearer": []
}
],
"operationId": "putIdentity",
"summary": "Update an identity (v3)",
"description": "Update all fields of an existing identity. Supports updates to PII fields and metadata.\nEach successful PUT creates a new version and preserves prior versions for audit.\n",
"parameters": [
{
"name": "identity-id",
"in": "path",
"required": true,
"description": "The ID of the identity to update.",
"example": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/put-identity-request-v3"
},
"examples": {
"put-metadata": {
"summary": "Update nickname and tags",
"value": {
"nickName": "Alice Sender USD - Updated",
"tags": [
"usd",
"high-value"
]
}
},
"put-individual-address": {
"summary": "Update INDIVIDUAL address",
"value": {
"individual": {
"address": {
"streetAddress": [
"500 Market Street"
],
"city": "San Francisco",
"stateOrProvince": "CA",
"postalCode": "94103",
"country": "US"
}
}
}
},
"put-business-contact": {
"summary": "Update BUSINESS contact info",
"value": {
"business": {
"email": "ops@example.com",
"phone": "+14155551234"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Identity updated. Latest version returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get-identity-response-v3"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-400": {
"$ref": "#/components/examples/error-400-example"
}
}
}
}
},
"404": {
"description": "Identity not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-404": {
"$ref": "#/components/examples/error-404-example"
}
}
}
}
},
"409": {
"description": "Conflict - The provided internalId already exists on a different identity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
}
}
}
},
"500": {
"description": "Internal processing error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-500": {
"$ref": "#/components/examples/error-500-example"
}
}
}
}
}
}
},
"delete": {
"tags": [
"IdentitiesV3"
],
"security": [
{
"Bearer": []
}
],
"operationId": "deactivateIdentityV3",
"summary": "Deactivate an identity (v3)",
"description": "Deactivate an identity and its financial instruments.\nDeactivation is permanent and prevents further use in payments.\nHistorical versions remain available for audit.\n",
"parameters": [
{
"in": "path",
"name": "identity-id",
"required": true,
"description": "ID of the identity to deactivate.",
"example": "146f3c51-c313-47ce-b6f2-691c5a238b3e",
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Identity deactivated."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-400": {
"$ref": "#/components/examples/error-400-example"
}
}
}
}
},
"404": {
"description": "Identity not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-404": {
"$ref": "#/components/examples/error-404-example"
}
}
}
}
},
"422": {
"description": "Identity already deactivated or cannot be deactivated.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
}
}
}
},
"500": {
"description": "Internal processing error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-500": {
"$ref": "#/components/examples/error-500-example"
}
}
}
}
}
}
}
},
"/v3/identities/by-internal-id/{internal-id}": {
"get": {
"tags": [
"IdentitiesV3"
],
"security": [
{
"Bearer": []
}
],
"operationId": "getIdentityByInternalId",
"summary": "Get an identity by Internal ID (v3)",
"description": "Retrieve a specific identity by its internal ID.\n\n**Behavior:**\n- Only returns identities in the `ACTIVE` state. Deactivated identities will result in an error.\n- Always returns the latest version of the identity. Historical versions are not accessible through this endpoint.\n- If no active identity exists for the given `internal-id`, a 404 is returned.\n",
"parameters": [
{
"name": "internal-id",
"in": "path",
"required": true,
"description": "The Internal ID of the identity to retrieve.",
"example": "customer-12345-uuid",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Identity details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get-identity-response-v3"
},
"examples": {
"get-identity-v3": {
"value": {
"identityId": "9d839f58-7fd3-4913-a27e-48d31973d3f9",
"identityState": "ACTIVE",
"nickName": "nickName",
"tags": [
"tag1"
],
"version": "2",
"schemaVersion": "1.0.0",
"createdAt": "2025-10-01T18:46:41.833Z",
"updatedAt": "2025-10-01T18:46:47.430Z",
"identityType": "BUSINESS",
"paymentRole": "ORIGINATOR",
"internalId": "customer-12345-uuid",
"business": {
"businessName": "Widgets Org",
"address": {
"streetAddress": [
"123 Example MA"
],
"country": "US",
"city": "Boston",
"stateOrProvince": "MS",
"postalCode": "12345"
},
"email": "fake@example.com",
"phone": "+1234567890",
"registration": [
{
"number": "123ABC",
"type": "INCORPORATION_CERTIFICATE"
}
],
"incorporationCountry": "US"
}
}
}
}
}
}
},
"400": {
"description": "Invalid internal ID.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-400": {
"$ref": "#/components/examples/error-400-example"
}
}
}
}
},
"404": {
"description": "Active Identity not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-404": {
"$ref": "#/components/examples/error-404-example"
}
}
}
}
},
"500": {
"description": "Internal processing error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-500": {
"$ref": "#/components/examples/error-500-example"
}
}
}
}
}
}
}
},
"/v3/identities/{identity-id}/financial-instruments": {
"post": {
"tags": [
"IdentitiesV3"
],
"security": [
{
"Bearer": []
}
],
"operationId": "createFinancialInstrument",
"summary": "Add a financial instrument (v3)",
"description": "Create a financial instrument for the specified identity. The request body must include the payment rail (financialInstrumentType), currency or asset code, and the rail-specific details (for example, US ACH account numbers or a wallet address).\nIn the current release, each identity can have **one** financial instrument.\nFuture releases will support multiple instruments per identity.\n",
"parameters": [
{
"name": "identity-id",
"in": "path",
"required": true,
"description": "Unique identifier of the identity that will own the financial instrument.",
"example": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ripple-financial-instrument"
},
"examples": {
"create-us-ach": {
"summary": "US_ACH bank account",
"value": {
"financialInstrumentType": "US_ACH",
"currency": "USD",
"label": "US bank account",
"usAch": {
"bankName": "Bank of Example",
"bankRoutingNumber": "266231608",
"accountNumber": "60480",
"accountType": "CHECKING"
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Financial instrument created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create-financial-instrument-response"
},
"example": {
"financialInstrumentId": "d3cd4f8e-3a6d-46e6-bdb6-0b7f358f2ad8"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-400": {
"$ref": "#/components/examples/error-400-example"
}
}
}
}
},
"404": {
"description": "Identity not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-404": {
"$ref": "#/components/examples/error-404-example"
}
}
}
}
},
"500": {
"description": "Internal processing error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-500": {
"$ref": "#/components/examples/error-500-example"
}
}
}
}
}
}
},
"get": {
"tags": [
"IdentitiesV3"
],
"security": [
{
"Bearer": []
}
],
"operationId": "getFinancialInstruments",
"summary": "Get a list of financial instruments of the identity (v3)",
"description": "List financial instruments for an identity.",
"parameters": [
{
"in": "path",
"name": "identity-id",
"required": true,
"description": "Unique UUID string that maps to an identity",
"example": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "version",
"required": false,
"description": "Version of the identity",
"example": "2",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "next-token",
"required": false,
"schema": {
"type": "string"
},
"example": "eyJrZXkxIjoidmFsdWVfMSIsImtleTIiOiJ2YWx1ZTIifQ==",
"description": "The token to use for the next page of results. If provided, the API will return financial instruments after this token."
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 20,
"default": 10
},
"description": "The maximum number of financial instruments to return. Default is 10, maximum is 100."
}
],
"responses": {
"200": {
"description": "Requested financial instruments of the identity in JSON format",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list-financial-instruments-response"
},
"examples": {
"list-fi-v3": {
"value": {
"data": [
{
"financialInstrumentId": "7f2bac05-42a3-4b26-89fd-333396fdba70",
"financialInstrumentType": "US_ACH",
"currency": "USD",
"label": "US bank account",
"country": "US",
"createdAt": "2025-10-01T18:46:47.430Z",
"updatedAt": "2025-10-01T18:46:47.430Z"
}
]
}
}
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-400": {
"$ref": "#/components/examples/error-400-example"
}
}
}
}
},
"404": {
"description": "No identity or financial instruments found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-404": {
"$ref": "#/components/examples/error-404-example"
}
}
}
}
},
"500": {
"description": "Internal Processing Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-500": {
"$ref": "#/components/examples/error-500-example"
}
}
}
}
}
}
}
},
"/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}": {
"get": {
"tags": [
"IdentitiesV3"
],
"security": [
{
"Bearer": []
}
],
"operationId": "getFinancialInstrumentById",
"summary": "Get a financial instrument by ID (v3)",
"description": "Retrieves one financial instrument associated with the specified identity.\nIn the current release, one instrument is retrieved at most because only a single instrument is allowed per identity.\n",
"parameters": [
{
"name": "identity-id",
"in": "path",
"required": true,
"description": "Unique identifier of the identity whose instruments you want to list.",
"example": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
"schema": {
"type": "string"
}
},
{
"name": "financial-instrument-id",
"in": "path",
"required": true,
"description": "The ID of the financial instrument of the identity.",
"example": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "version",
"required": false,
"description": "Version of the identity",
"example": "2",
"schema": {
"type": "string"
}
},
{
"name": "expand-identity",
"in": "query",
"required": false,
"description": "Optional parameter to expand the financial instrument details.\nIf set to true, the details about the identity will be included in the response.\n",
"schema": {
"type": "boolean",
"example": true
}
}
],
"responses": {
"200": {
"description": "List of financial instruments for the identity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get-financial-instrument-response"
},
"examples": {
"get-fi-v3": {
"value": {
"financialInstrument": {
"country": "US",
"financialInstrumentId": "7f2bac05-42a3-4b26-89fd-333396fdba70",
"createdAt": "2025-10-01T18:46:47.430Z",
"updatedAt": "2025-10-01T18:46:47.430Z",
"usAch": {
"bankName": "string",
"bankRoutingNumber": "266231608",
"accountNumber": "60480",
"accountType": "CHECKING"
},
"currency": "USD",
"label": "US bank account",
"financialInstrumentType": "US_ACH"
}
}
}
}
}
}
},
"400": {
"description": "Identity ID or financial instrument ID is not valid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-400": {
"$ref": "#/components/examples/error-400-example"
}
}
}
}
},
"404": {
"description": "The specified identity-id does not exist.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-404": {
"$ref": "#/components/examples/error-404-example"
}
}
}
}
},
"500": {
"description": "Internal processing error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-500": {
"$ref": "#/components/examples/error-500-example"
}
}
}
}
}
}
},
"put": {
"tags": [
"IdentitiesV3"
],
"security": [
{
"Bearer": []
}
],
"operationId": "putFinancialInstrument",
"summary": "Update a financial instrument (v3)",
"description": "Update editable fields of a financial instrument including rail-specific details and labels.\nThe financialInstrumentType is immutable after creation.\n",
"parameters": [
{
"name": "identity-id",
"in": "path",
"required": true,
"description": "The unique ID of the identity.",
"example": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
"schema": {
"type": "string"
}
},
{
"name": "financial-instrument-id",
"in": "path",
"required": true,
"description": "The ID of the financial instrument to update.",
"example": "c7e2f5b4-d1a2-4c3a-9e1b-4d5c6f7e8a9d",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/put-ripple-financial-instrument"
},
"examples": {
"put-label-only": {
"summary": "Update label",
"value": {
"label": "Operating account"
}
},
"put-ach-details": {
"summary": "Update ACH details",
"value": {
"usAch": {
"bankRoutingNumber": "266231608",
"accountNumber": 987654321,
"accountType": "SAVINGS"
}
}
},
"put-xrpl-wallet": {
"summary": "Update XRPL destination tag",
"value": {
"xrplWallet": {
"destinationTag": 654321
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Financial instrument updated.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/update-financial-instrument-response"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-400": {
"$ref": "#/components/examples/error-400-example"
}
}
}
}
},
"404": {
"description": "Identity or financial instrument not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-404": {
"$ref": "#/components/examples/error-404-example"
}
}
}
}
},
"409": {
"description": "Conflicting resource state.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-409": {
"$ref": "#/components/examples/error-409-example"
}
}
}
}
},
"500": {
"description": "Internal processing error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-500": {
"$ref": "#/components/examples/error-500-example"
}
}
}
}
}
}
},
"delete": {
"tags": [
"IdentitiesV3"
],
"security": [
{
"Bearer": []
}
],
"operationId": "deactivateFinancialInstrumentV3",
"summary": "Deactivate a Financial Instrument (v3)",
"description": "Deactivate a financial instrument of an Identity.\nDeactivation is permanent and prevents further use in payments.\nHistorical versions remain available for audit.\n",
"parameters": [
{
"name": "identity-id",
"in": "path",
"required": true,
"description": "The unique ID of the identity.",
"example": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
"schema": {
"type": "string"
}
},
{
"name": "financial-instrument-id",
"in": "path",
"required": true,
"description": "The ID of the financial instrument to deactivate.",
"example": "c7e2f5b4-d1a2-4c3a-9e1b-4d5c6f7e8a9d",
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Financial Instrument deactivated."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-400": {
"$ref": "#/components/examples/error-400-example"
}
}
}
}
},
"404": {
"description": "Financial Instrument not found for the identity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-404": {
"$ref": "#/components/examples/error-404-example"
}
}
}
}
},
"405": {
"description": "Method not allowed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
}
}
}
},
"409": {
"description": "Conflicting resource state. Identity/Financial Instrument already deactivated or cannot be deactivated.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-409": {
"$ref": "#/components/examples/error-409-example"
}
}
}
}
},
"500": {
"description": "Internal processing error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error-response"
},
"examples": {
"error-response-500": {
"$ref": "#/components/examples/error-500-example"
}
}
}
}
}
}
}
},
"/v2/quotes/quote-collection": {
"post": {
"tags": [
"Quote"
],
"security": [
{
"Bearer": []
}
],
"operationId": "createQuoteCollection",
"summary": "Create quote collection",
"description": "Creates a collection of quotes for a proposed payment..\n",
"requestBody": {
"description": "Create quote collection request",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteCollectionRequest"
}
}
}
},
"responses": {
"201": {
"description": "Creates a collection of quotes",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteCollection"
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteErrorResponse"
}
}
}
},
"403": {
"description": "The principal identified by the authorization header doesn't have enough scopes to perform this operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteErrorResponse"
}
}
}
}
}
}
},
"/v2/quotes/quote-collection/{quote-collection-id}": {
"get": {
"tags": [
"Quote"
],
"security": [
{
"Bearer": []
}
],
"operationId": "getQuoteCollection",
"summary": "Get quote collection",
"parameters": [
{
"in": "path",
"name": "quote-collection-id",
"description": "The unique identifier of the quote collection you want to retrieve",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "11111111-aaaa-2222-bbbb-222222222222"
}
}
],
"responses": {
"200": {
"description": "Valid quote collection found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteCollection"
}
}
}
},
"401": {
"description": "Unauthorized request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteErrorResponse"
}
}
}
},
"403": {
"description": "The principal identified by the authorization header doesn't have enough scopes to perform this operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteErrorResponse"
}
}
}
},
"404": {
"description": "Quote collection not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteErrorResponse"
}
}
}
}
}
}
},
"/v2/quotes/{quote-id}": {
"get": {
"tags": [
"Quote"
],
"security": [
{
"Bearer": []
}
],
"operationId": "getQuote",
"summary": "Get quote",
"parameters": [
{
"in": "path",
"name": "quote-id",
"description": "The unique identifier of the quote to retrieve",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"example": "22222222-aaaa-2222-bbbb-222222222222"
}
}
],
"responses": {
"200": {
"description": "Valid quote found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Quote"
}
}
}
},
"401": {
"description": "Unauthorized request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteErrorResponse"
}
}
}
},
"403": {
"description": "The principal identified by the authorization header doesn't have enough scopes to perform this operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteErrorResponse"
}
}
}
},
"404": {
"description": "Quote not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteErrorResponse"
}
}
}
}
}
}
},
"/v2/balances": {
"get": {
"summary": "Get available balances",
"operationId": "getBalances",
"tags": [
"ledger-public"
],
"parameters": [
{
"in": "query",
"name": "currency",
"required": false,
"schema": {
"type": "string"
},
"description": "The currency for which you want to get the balance."
}
],
"responses": {
"200": {
"description": "Successful response containing balance details.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Customer available prefund balance details.",
"properties": {
"timestamp": {
"type": "string",
"format": "date-time",
"example": "2025-01-10T00:00:00.000000Z",
"description": "Timestamp of the balance response."
},
"balances": {
"type": "array",
"items": {
"type": "object",
"description": "Customer available prefund balance for specific currency",
"properties": {
"fundingType": {
"enum": [
"FUNDED"
],
"x-enumDescriptions": {
"FUNDED": "Indicates that you initiate payments using the funds you added to your account."
},
"description": "The funding method associated with your account."
},
"currency": {
"type": "string",
"example": "USD",
"description": "Currency code."
},
"availableBalance": {
"type": "number",
"example": 1000,
"description": "Available funded balance that you can use to initiate payments."
},
"reservedBalance": {
"type": "number",
"example": 100,
"description": "Amount reserved to complete in-progress transactions. You can't use this amount to initiate new payments."
}
},
"required": [
"fundingType",
"currency",
"availableBalance",
"reservedBalance"
]
},
"description": "List of available prefund balances."
}
},
"required": [
"timestamp",
"balances"
]
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"status",
"errors"
],
"properties": {
"status": {
"type": "integer",
"description": "The HTTP status code representing the error response",
"example": 400
},
"errors": {
"type": "array",
"description": "An array containing details about the errors encountered",
"items": {
"type": "object",
"required": [
"code",
"title",
"type",
"description",
"timestamp"
],
"properties": {
"code": {
"type": "string",
"description": "A unique error code that identifies the specific error",
"example": "SYS_003"
},
"type": {
"type": "string",
"description": "A high-level categorization of the error, indicating the type of issue that occurred",
"example": "SYSTEM_ERROR"
},
"title": {
"type": "string",
"description": "A brief, user-friendly description of the error",
"example": "Internal Server Error"
},
"description": {
"type": "string",
"description": "A more detailed explanation of the error, including potential causes and next steps",
"example": "The payout category value must be one of BANK, EWALLET, CASH_PICKUP, or ATM."
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "The timestamp of the error occurrence",
"example": "2024-01-02T14:16:00Z"
}
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized access",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"status",
"errors"
],
"properties": {
"status": {
"type": "integer",
"description": "The HTTP status code representing the error response",
"example": 400
},
"errors": {
"type": "array",
"description": "An array containing details about the errors encountered",
"items": {
"type": "object",
"required": [
"code",
"title",
"type",
"description",
"timestamp"
],
"properties": {
"code": {
"type": "string",
"description": "A unique error code that identifies the specific error",
"example": "SYS_003"
},
"type": {
"type": "string",
"description": "A high-level categorization of the error, indicating the type of issue that occurred",
"example": "SYSTEM_ERROR"
},
"title": {
"type": "string",
"description": "A brief, user-friendly description of the error",
"example": "Internal Server Error"
},
"description": {
"type": "string",
"description": "A more detailed explanation of the error, including potential causes and next steps",
"example": "The payout category value must be one of BANK, EWALLET, CASH_PICKUP, or ATM."
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "The timestamp of the error occurrence",
"example": "2024-01-02T14:16:00Z"
}
}
}
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"status",
"errors"
],
"properties": {
"status": {
"type": "integer",
"description": "The HTTP status code representing the error response",
"example": 400
},
"errors": {
"type": "array",
"description": "An array containing details about the errors encountered",
"items": {
"type": "object",
"required": [
"code",
"title",
"type",
"description",
"timestamp"
],
"properties": {
"code": {
"type": "string",
"description": "A unique error code that identifies the specific error",
"example": "SYS_003"
},
"type": {
"type": "string",
"description": "A high-level categorization of the error, indicating the type of issue that occurred",
"example": "SYSTEM_ERROR"
},
"title": {
"type": "string",
"description": "A brief, user-friendly description of the error",
"example": "Internal Server Error"
},
"description": {
"type": "string",
"description": "A more detailed explanation of the error, including potential causes and next steps",
"example": "The payout category value must be one of BANK, EWALLET, CASH_PICKUP, or ATM."
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "The timestamp of the error occurrence",
"example": "2024-01-02T14:16:00Z"
}
}
}
}
}
}
}
}
}
},
"security": [
{
"Bearer": []
}
]
}
},
"/v2/ledger-transactions": {
"get": {
"summary": "Get ledger transactions",
"operationId": "getStatementsTransactionsForCustomer",
"tags": [
"ledger-public"
],
"description": "Retrieve a paginated list of ledger transactions for your tenant within a specified date and time range. This endpoint returns detailed transaction data, including amounts, references, operations, and running balances, so you can reconcile balance changes over time for a given currency.\n",
"parameters": [
{
"name": "currency",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Three-letter ISO 4217 currency code for the transactions to return (for example, USD).\n",
"example": "USD"
},
{
"name": "start-dttm",
"in": "query",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Start of the date and time range (inclusive), in UTC, for which you want to retrieve ledger transactions.\n",
"example": "2022-02-27T08:30:00Z"
},
{
"name": "end-dttm",
"in": "query",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "End of the date and time range (exclusive), in UTC, for which you want to retrieve ledger transactions.\n",
"example": "2022-02-27T08:30:00Z"
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter results by transaction status. Allowed values: - SUCCESS: the ledger transaction completed successfully. - PENDING: reserved for future use to represent an in-flight ledger transaction.\n"
},
{
"name": "txnReference",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter results by an exact transaction reference. Use this to locate all ledger transactions associated with a specific external reference.\n"
},
{
"name": "page-size",
"in": "query",
"required": true,
"schema": {
"type": "integer",
"default": 25,
"minimum": 1,
"maximum": 50
},
"description": "Number of records to return in the response page. Use page-size together with offset for offset-based pagination\n"
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer"
},
"description": "Number of records to skip before starting to return results. Use this with page-size to implement offset-based pagination.\nFor example, `offset=25&page-size=25` returns the second page of results.\n"
},
{
"name": "sort-key",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Field to use for sorting the results. Allowed values include: - CREATED_AT: sort by transaction creation timestamp. - STATEMENT_OPERATION: sort by the operation type (for example, CREDIT, DEBIT). - STATEMENT_SOURCE: sort by the transaction source (for example, PAYMENTS, BANK). - STATEMENT_STATUS: sort by the ledger transaction status. - STATEMENT_TXN_REFERENCE: sort by the transaction reference. - STATEMENT_UPDATED_AT: sort by the last update timestamp.\n"
},
{
"name": "sort-direction",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Sort direction. Allowed values: - ASC: ascending order. - DESC: descending order.\n"
}
],
"responses": {
"200": {
"description": "A page of ledger statement transactions for the tenant that match the specified query parameters.\n",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"description": "A page of ledger statement transactions and pagination metadata.",
"properties": {
"offset": {
"type": "integer",
"description": "Offset used in the request to skip a specific number of records.\n",
"example": 0
},
"pageSize": {
"type": "integer",
"description": "Number of records requested per page",
"example": 25
},
"pageElements": {
"type": "integer",
"description": "Number of records returned in requested page",
"example": 25
},
"total": {
"type": "integer",
"format": "int64",
"description": "Total number of records available for the given filters.",
"example": 1000
},
"statementTransactions": {
"type": "array",
"description": "Statement transaction details for the tenant.",
"items": {
"type": "object",
"properties": {
"tenant": {
"type": "string",
"description": "Identifier of the tenant that owns this ledger transaction.",
"example": "rocketfuel"
},
"amount": {
"type": "number",
"description": "Amount of the transaction applied to the tenant's ledger account.\n",
"example": 100
},
"currency": {
"type": "string",
"description": "Three-letter ISO 4217 currency code of the transaction.",
"example": "USD"
},
"txnReference": {
"type": "string",
"nullable": true,
"description": "External reference that links this ledger transaction to a payment or other upstream operation. Present for RESERVE and DEBIT operations, where it matches the Payments Direct payment ID. Null for all other operation types.\n"
},
"operation": {
"type": "string",
"description": "Operation performed on the tenant's prefunded ledger account.\n",
"x-enumDescriptions": {
"CREDIT": "Credit to the ledger account.",
"RESERVE": "Funds reserved in an intermediate state.",
"DEBIT": "Funds debited from the reserved state.",
"RELEASE": "Reserved funds released back to the account.",
"VOID_PREFUND_BALANCE": "Prefund balance has been voided. [Deprecated]",
"OVERRIDE_PREFUND_BALANCE": "Prefund balance has been overridden. [Deprecated]",
"VOID_BALANCE": "Balance has been voided.",
"OVERRIDE_BALANCE": "Balance has been overridden."
}
},
"txnSource": {
"type": "string",
"description": "Source of the ledger transaction (for example, which system or flow created it).\n",
"x-enumDescriptions": {
"PAYMENTS": "Created by a payments flow.",
"BANK": "Created by a bank transaction.",
"POSTED_PAYMENT": "Created by a posted payment operation.",
"CREDIT_MEMO": "Created by a credit memo.",
"MANUAL": "Created manually via API."
}
},
"status": {
"type": "string",
"description": "State of the ledger transaction.",
"x-enumDescriptions": {
"SUCCESS": "Ledger transaction completed successfully.",
"PENDING": "Reserved for future use to represent an in-flight ledger transaction."
}
},
"createdDttm": {
"type": "string",
"format": "date-time",
"nullable": false,
"description": "Timestamp (UTC) when the ledger transaction was created.",
"example": "2024-06-01T00:00:00.000000Z"
},
"updatedDttm": {
"type": "string",
"format": "date-time",
"nullable": false,
"description": "Timestamp (UTC) when the ledger transaction was last updated.",
"example": "2024-06-01T00:00:00.000000Z"
},
"availableBalanceBefore": {
"type": "number",
"description": "Available ledger account balance (in the transaction currency) immediately before this transaction was applied.\n",
"example": 100
},
"availableBalanceAfter": {
"type": "number",
"description": "Available ledger account balance (in the transaction currency) immediately after this transaction was applied.\n",
"example": 90
}
}
}
}
}
}
}
},
"text/csv": {
"schema": {
"items": {
"type": "object",
"description": "A page of ledger statement transactions and pagination metadata.",
"properties": {
"offset": {
"type": "integer",
"description": "Offset used in the request to skip a specific number of records.\n",
"example": 0
},
"pageSize": {
"type": "integer",
"description": "Number of records requested per page",
"example": 25
},
"pageElements": {
"type": "integer",
"description": "Number of records returned in requested page",
"example": 25
},
"total": {
"type": "integer",
"format": "int64",
"description": "Total number of records available for the given filters.",
"example": 1000
},
"statementTransactions": {
"type": "array",
"description": "Statement transaction details for the tenant.",
"items": {
"type": "object",
"properties": {
"tenant": {
"type": "string",
"description": "Identifier of the tenant that owns this ledger transaction.",
"example": "rocketfuel"
},
"amount": {
"type": "number",
"description": "Amount of the transaction applied to the tenant's ledger account.\n",
"example": 100
},
"currency": {
"type": "string",
"description": "Three-letter ISO 4217 currency code of the transaction.",
"example": "USD"
},
"txnReference": {
"type": "string",
"nullable": true,
"description": "External reference that links this ledger transaction to a payment or other upstream operation. Present for RESERVE and DEBIT operations, where it matches the Payments Direct payment ID. Null for all other operation types.\n"
},
"operation": {
"type": "string",
"description": "Operation performed on the tenant's prefunded ledger account.\n",
"x-enumDescriptions": {
"CREDIT": "Credit to the ledger account.",
"RESERVE": "Funds reserved in an intermediate state.",
"DEBIT": "Funds debited from the reserved state.",
"RELEASE": "Reserved funds released back to the account.",
"VOID_PREFUND_BALANCE": "Prefund balance has been voided. [Deprecated]",
"OVERRIDE_PREFUND_BALANCE": "Prefund balance has been overridden. [Deprecated]",
"VOID_BALANCE": "Balance has been voided.",
"OVERRIDE_BALANCE": "Balance has been overridden."
}
},
"txnSource": {
"type": "string",
"description": "Source of the ledger transaction (for example, which system or flow created it).\n",
"x-enumDescriptions": {
"PAYMENTS": "Created by a payments flow.",
"BANK": "Created by a bank transaction.",
"POSTED_PAYMENT": "Created by a posted payment operation.",
"CREDIT_MEMO": "Created by a credit memo.",
"MANUAL": "Created manually via API."
}
},
"status": {
"type": "string",
"description": "State of the ledger transaction.",
"x-enumDescriptions": {
"SUCCESS": "Ledger transaction completed successfully.",
"PENDING": "Reserved for future use to represent an in-flight ledger transaction."
}
},
"createdDttm": {
"type": "string",
"format": "date-time",
"nullable": false,
"description": "Timestamp (UTC) when the ledger transaction was created.",
"example": "2024-06-01T00:00:00.000000Z"
},
"updatedDttm": {
"type": "string",
"format": "date-time",
"nullable": false,
"description": "Timestamp (UTC) when the ledger transaction was last updated.",
"example": "2024-06-01T00:00:00.000000Z"
},
"availableBalanceBefore": {
"type": "number",
"description": "Available ledger account balance (in the transaction currency) immediately before this transaction was applied.\n",
"example": 100
},
"availableBalanceAfter": {
"type": "number",
"description": "Available ledger account balance (in the transaction currency) immediately after this transaction was applied.\n",
"example": 90
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"status",
"errors"
],
"properties": {
"status": {
"type": "integer",
"description": "The HTTP status code representing the error response",
"example": 400
},
"errors": {
"type": "array",
"description": "An array containing details about the errors encountered",
"items": {
"type": "object",
"required": [
"code",
"title",
"type",
"description",
"timestamp"
],
"properties": {
"code": {
"type": "string",
"description": "A unique error code that identifies the specific error",
"example": "SYS_003"
},
"type": {
"type": "string",
"description": "A high-level categorization of the error, indicating the type of issue that occurred",
"example": "SYSTEM_ERROR"
},
"title": {
"type": "string",
"description": "A brief, user-friendly description of the error",
"example": "Internal Server Error"
},
"description": {
"type": "string",
"description": "A more detailed explanation of the error, including potential causes and next steps",
"example": "The payout category value must be one of BANK, EWALLET, CASH_PICKUP, or ATM."
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "The timestamp of the error occurrence",
"example": "2024-01-02T14:16:00Z"
}
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"status",
"errors"
],
"properties": {
"status": {
"type": "integer",
"description": "The HTTP status code representing the error response",
"example": 400
},
"errors": {
"type": "array",
"description": "An array containing details about the errors encountered",
"items": {
"type": "object",
"required": [
"code",
"title",
"type",
"description",
"timestamp"
],
"properties": {
"code": {
"type": "string",
"description": "A unique error code that identifies the specific error",
"example": "SYS_003"
},
"type": {
"type": "string",
"description": "A high-level categorization of the error, indicating the type of issue that occurred",
"example": "SYSTEM_ERROR"
},
"title": {
"type": "string",
"description": "A brief, user-friendly description of the error",
"example": "Internal Server Error"
},
"description": {
"type": "string",
"description": "A more detailed explanation of the error, including potential causes and next steps",
"example": "The payout category value must be one of BANK, EWALLET, CASH_PICKUP, or ATM."
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "The timestamp of the error occurrence",
"example": "2024-01-02T14:16:00Z"
}
}
}
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"status",
"errors"
],
"properties": {
"status": {
"type": "integer",
"description": "The HTTP status code representing the error response",
"example": 400
},
"errors": {
"type": "array",
"description": "An array containing details about the errors encountered",
"items": {
"type": "object",
"required": [
"code",
"title",
"type",
"description",
"timestamp"
],
"properties": {
"code": {
"type": "string",
"description": "A unique error code that identifies the specific error",
"example": "SYS_003"
},
"type": {
"type": "string",
"description": "A high-level categorization of the error, indicating the type of issue that occurred",
"example": "SYSTEM_ERROR"
},
"title": {
"type": "string",
"description": "A brief, user-friendly description of the error",
"example": "Internal Server Error"
},
"description": {
"type": "string",
"description": "A more detailed explanation of the error, including potential causes and next steps",
"example": "The payout category value must be one of BANK, EWALLET, CASH_PICKUP, or ATM."
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "The timestamp of the error occurrence",
"example": "2024-01-02T14:16:00Z"
}
}
}
}
}
}
}
}
}
},
"security": [
{
"Bearer": []
}
]
}
}
},
"components": {
"securitySchemes": {
"Bearer": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
},
"BasicAuth": {
"type": "http",
"scheme": "basic"
}
},
"schemas": {
"AuthenticationRequest": {
"description": "The authentication request.",
"properties": {
"client_id": {
"type": "string",
"description": "The client ID associated with a specific set of API credentials.",
"example": "{YOUR_CLIENT_ID}"
},
"client_secret": {
"type": "string",
"description": "The client secret associated with a specific set of API credentials.",
"example": "{YOUR_CLIENT_SECRET}"
},
"audience": {
"type": "string",
"description": "The value of the `audience` field is based on [URN](https://en.wikipedia.org/wiki/Uniform_Resource_Name) syntax.\n\n**Format**: `urn:ripplexcurrent-{ENVIRONMENT_STRING}:{YOUR_TENANT_ID}`\n\n* The first component is `urn:ripplenetxcurrent-`.\n* The second component refers to the environment you want to access.\n* The third component is your tenant ID. Ripple integration engineers provide this component during training.\n\n| Environment | Environment string | Description |\n| --- | --- | --- |\n| Test | `test` | Test environment with simulated partners and simulated currency. |\n| Production | `prod` | Production environment for Ripple's internal services. |\n\n**Example**: `urn:ripplexcurrent-test:{YOUR_TENANT_ID}`\n",
"example": "urn:ripplexcurrent-test:{YOUR_TENANT_ID}"
},
"grant_type": {
"type": "string",
"description": "Set the grant-type for this client credentials request. This must be set to `client_credentials`.",
"enum": [
"client_credentials"
],
"example": "client_credentials"
}
},
"required": [
"client_id",
"client_secret",
"audience",
"grant_type"
],
"type": "object"
},
"AuthenticationResponse": {
"description": "The authentication response object that includes the token, type, scopes, and expiry.",
"properties": {
"access_token": {
"type": "string",
"description": "The bearer token you use when authenticating with a Ripple API.",
"example": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ"
},
"scope": {
"type": "string",
"description": "List of scopes applied to your `access_token`.",
"example": "pos:payments:create quote_collection:quote:create quote:quote:read pos:payments:read pcs_config:external_read data_requirements:read identities:create identities:read identities:write ledger:balance:read ledger:read"
},
"expires_in": {
"type": "integer",
"format": "int64",
"description": "How long your `access_token` is valid. You need to request a new token when it expires.",
"example": 3600
},
"token_type": {
"type": "string",
"description": "The type of token. Ripple APIs use `Bearer` auth tokens.",
"example": "Bearer"
}
},
"type": "object"
},
"ErrorResponse": {
"description": "The response object containing the error and its description if the authentication call fails.",
"properties": {
"error_description": {
"type": "string",
"description": "Summary of the returned problem.",
"example": "Unauthorized"
},
"error": {
"type": "string",
"description": "Error status.",
"example": "access_denied"
}
}
},
"ValidateTokenResponse": {
"description": "The response object indicating a token's validity and the time remaining on it",
"properties": {
"message": {
"type": "string",
"example": "token_ok"
},
"seconds_to_expiry": {
"type": "integer",
"format": "int64",
"description": "Remaining time in seconds before the tested token expires.",
"example": 3600
}
}
},
"PaymentErrorResponse": {
"type": "object",
"required": [
"status",
"errors"
],
"properties": {
"errors": {
"description": "List of payment errors",
"type": "array",
"$ref": "#/components/schemas/PaymentError"
},
"status": {
"type": "string",
"description": "Error Response Status",
"example": 400
}
}
},
"PaymentError": {
"type": "object",
"required": [
"code",
"title",
"type",
"description",
"timestamp"
],
"properties": {
"code": {
"type": "string",
"description": "A unique identifier for the error",
"example": "SYS_003"
},
"type": {
"type": "string",
"description": "A high-level categorization of the error, indicating the type of issue that occurred",
"example": "SYSTEM_ERROR"
},
"title": {
"type": "string",
"description": "A brief, user-friendly description of the error",
"example": "Internal Server Error"
},
"description": {
"type": "string",
"description": "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."
},
"timestamp": {
"type": "string",
"format": "date-time",
"example": "2024-11-21T14:15:22Z"
}
}
},
"PaymentV2": {
"type": "object",
"required": [
"paymentId",
"paymentState"
],
"properties": {
"paymentId": {
"description": "The unique ID that identifies this payment. This value is the same as the quote ID.",
"type": "string",
"format": "uuid",
"maxLength": 36,
"example": "7ea3399c-1234-5678-8d8f-d320ea406630"
},
"cryptoTransactionHash": {
"description": "Transaction hash of the crypto payment on the destination blockchain network",
"type": "string",
"example": "0x2b1f8b57dd6008143ff926ea9d9cd2365774cd0c5e6f379558a88c61c52071eb"
},
"initiatedAt": {
"description": "The time at which the payment was initiated, specified in UTC.",
"type": "string",
"format": "date-time",
"example": "2019-08-24T14:15:22Z"
},
"expiresAt": {
"description": "The time at which this payment expires, specified in UTC.",
"type": "string",
"format": "date-time",
"example": "2019-08-24T14:15:22Z"
},
"jitFundingExpiresAt": {
"description": "The time at which JIT funding for this payment expires, specified in UTC.",
"type": "string",
"format": "date-time",
"example": "2019-08-24T14:15:22Z"
},
"lastStateUpdatedAt": {
"description": "The time at which the payment state was last updated for this payment, specified in UTC.",
"type": "string",
"format": "date-time",
"example": "2019-08-24T14:15:22Z"
},
"paymentState": {
"$ref": "#/components/schemas/PaymentStateV2"
},
"originator": {
"$ref": "#/components/schemas/OriginatorV2"
},
"destination": {
"$ref": "#/components/schemas/DestinationV2"
},
"adjustedExchangeRate": {
"$ref": "#/components/schemas/AdjustedExchangeRate"
},
"fees": {
"type": "array",
"description": "A summary of fees included in the payment quote.",
"items": {
"$ref": "#/components/schemas/FeeSummary"
}
},
"taxes": {
"type": "array",
"description": "A summary of taxes included in the payment quote.",
"items": {
"$ref": "#/components/schemas/TaxSummary"
}
},
"sourceOfCash": {
"description": "Source of Cash may be required depending on corridor and payout partner. Valid Source of Cash values vary by corridor.",
"type": "string",
"example": "EMIN"
},
"purposeCode": {
"description": "Purpose Code may be required depending on corridor and payout partner. Valid Purpose Code values vary by corridor.",
"type": "string",
"example": "PAYR"
},
"transactionDetails": {
"$ref": "#/components/schemas/TransactionDetailsV2"
},
"paymentLabels": {
"$ref": "#/components/schemas/PaymentLabels"
},
"receiverRelationship": {
"description": "The relationship to the debtor.",
"type": "string",
"example": "SUBS"
},
"paymentMemo": {
"$ref": "#/components/schemas/PaymentMemo"
}
}
},
"PaymentWithDetailsV2": {
"type": "object",
"required": [
"paymentId",
"paymentState"
],
"properties": {
"paymentId": {
"description": "The unique ID that identifies this payment. This value is the same as the quote ID.",
"type": "string",
"format": "uuid",
"maxLength": 36,
"example": "7ea3399c-1234-5678-8d8f-d320ea406630"
},
"cryptoTransactionHash": {
"description": "Transaction hash of the crypto payment on the destination blockchain network",
"type": "string",
"example": "0x2b1f8b57dd6008143ff926ea9d9cd2365774cd0c5e6f379558a88c61c52071eb"
},
"initiatedAt": {
"description": "The time at which the payment was initiated, specified in UTC.",
"type": "string",
"format": "date-time",
"example": "2019-08-24T14:15:22Z"
},
"expiresAt": {
"description": "The time at which this payment expires, specified in UTC.",
"type": "string",
"format": "date-time",
"example": "2019-08-24T14:15:22Z"
},
"jitFundingExpiresAt": {
"description": "The time at which JIT funding for this payment expires, specified in UTC.",
"type": "string",
"format": "date-time",
"example": "2019-08-24T14:15:22Z"
},
"lastStateUpdatedAt": {
"description": "The time at which the payment state was last updated for this payment, specified in UTC.",
"type": "string",
"format": "date-time",
"example": "2019-08-24T14:15:22Z"
},
"paymentState": {
"$ref": "#/components/schemas/PaymentStateV2"
},
"originator": {
"$ref": "#/components/schemas/OriginatorV2"
},
"destination": {
"$ref": "#/components/schemas/DestinationV2"
},
"adjustedExchangeRate": {
"$ref": "#/components/schemas/AdjustedExchangeRate"
},
"fees": {
"type": "array",
"description": "A summary of fees included in payment quote.",
"items": {
"$ref": "#/components/schemas/FeeSummary"
}
},
"taxes": {
"type": "array",
"description": "A summary of taxes included in the payment quote.",
"items": {
"$ref": "#/components/schemas/TaxSummary"
}
},
"sourceOfCash": {
"description": "Source of Cash may be required depending on corridor and payout partner. Valid Source of Cash values vary by corridor.",
"type": "string",
"example": "EMIN"
},
"purposeCode": {
"description": "Purpose Code may be required depending on corridor and payout partner. Valid Purpose Code values vary by corridor.",
"type": "string",
"example": "PAYR"
},
"transactionDetails": {
"$ref": "#/components/schemas/TransactionDetailsV2"
},
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PaymentError"
}
},
"paymentLabels": {
"$ref": "#/components/schemas/PaymentLabels"
},
"receiverRelationship": {
"description": "The relationship to the debtor.",
"type": "string",
"example": "SUBS"
},
"paymentMemo": {
"$ref": "#/components/schemas/PaymentMemo"
},
"payoutExecutionDetails": {
"$ref": "#/components/schemas/PayoutExecutionDetails"
}
}
},
"StateTransitionsResponseV2": {
"type": "object",
"properties": {
"stateTransitions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StateTransitionV2"
}
}
},
"required": [
"stateTransitions"
]
},
"StateTransitionV2": {
"type": "object",
"properties": {
"updatedFrom": {
"$ref": "#/components/schemas/PaymentStateV2",
"description": "The initial payment state before it was updated.",
"example": "INITIATED"
},
"updatedTo": {
"$ref": "#/components/schemas/PaymentStateV2",
"description": "The payment state after it was updated.",
"example": "VALIDATING"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "The timestamp when the payment state was updated.",
"example": "2024-08-13T20:15:50.990995Z"
}
},
"required": [
"updatedFrom",
"updatedTo",
"updatedAt"
]
},
"PaymentsResponseV2": {
"type": "object",
"properties": {
"data": {
"description": "Array of Payment objects",
"type": "array",
"items": {
"$ref": "#/components/schemas/PaymentV2"
}
},
"filter": {
"$ref": "#/components/schemas/PaymentFilterV2"
},
"sort": {
"$ref": "#/components/schemas/SortV2"
},
"page": {
"$ref": "#/components/schemas/Page"
}
}
},
"PaymentRequestV2": {
"type": "object",
"required": [
"quoteId",
"beneficiaryIdentityId",
"beneficiaryFinancialInstrumentId"
],
"properties": {
"quoteId": {
"description": "ID of the quote you want to accept to initiate this payment. Must be in UUID format. This will be used as paymentId.",
"type": "string",
"format": "uuid",
"example": "7ea3399c-1234-5678-8d8f-d320ea406630"
},
"originatorIdentityId": {
"description": "The identity ID of the payment originator. You can find the identity ID using the `GET /identities` operation.",
"type": "string",
"example": "7ea3399c-1234-5678-8d8f-d320ea406630"
},
"beneficiaryIdentityId": {
"description": "The identity ID of the payment beneficiary. You can find the identity ID using the `GET /identities` operation.",
"type": "string",
"example": "7ea3399c-1234-5678-8d8f-d320ea406630"
},
"internalId": {
"maxLength": 36,
"description": "Customer defined value, such as an invoice number.",
"type": "string",
"example": "Invoice-123"
},
"purposeCode": {
"description": "Purpose Code may be required depending on corridor and payout partner. Valid Purpose Code values vary by corridor.",
"type": "string",
"example": "PAYR"
},
"sourceOfCash": {
"description": "Source of Cash may be required depending on corridor and payout partner. Valid Source of Cash values vary by corridor.",
"type": "string",
"example": "EMIN"
},
"paymentLabels": {
"$ref": "#/components/schemas/PaymentLabels"
},
"beneficiaryFinancialInstrumentId": {
"description": "The financial instrument ID associated with a payment beneficiary's identity.\nThis value must reference a financial instrument created for the same beneficiary identity using Identity Management v3. Use the `financialInstrumentId` returned when you create or fetch the beneficiary's payout instrument.\n",
"type": "string",
"example": "7ea3399c-1234-5678-8d8f-d320ea406630"
},
"receiverRelationship": {
"description": "The relationship to the debtor.",
"type": "string",
"example": "SUBS"
},
"paymentMemo": {
"$ref": "#/components/schemas/PaymentMemo"
}
}
},
"PaymentStateV2": {
"type": "string",
"example": "INITIATED",
"description": "Current state of a payment.\n\nThe payment lifecycle currently uses the following values: \n- `QUOTED` \n- `INITIATED` \n- `VALIDATING` \n- `TRANSFERRING` \n- `COMPLETED` \n- `FAILED` \n- `RETURNED` \n- `DECLINED` \n- `AWAITING_FUNDING`\n\nAdditional states may be introduced in the future without breaking existing integrations.\n",
"x-enumDescriptions": {
"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."
}
},
"PaymentSortFieldV2": {
"type": "string",
"description": "The field to use when sorting payments in the requested sort order.\n\nCurrently supported values include: \n- `internalId` \n- `paymentState` \n- `sourceCurrency` \n- `sourceAmount` \n- `destinationCurrency` \n- `destinationCountry` \n- `destinationAmount` \n- `initiatedAt` \n- `expiresAt` \n- `lastStateUpdatedAt` \n- `paymentLabel`\n\nIf an unsupported value is provided, the request fails with a validation error.\n",
"default": "initiatedAt",
"example": "initiatedAt",
"x-enumDescriptions": {
"internalId": "Internal identifier of a payment",
"paymentState": "Current state of a payment",
"sourceCurrency": "Source currency of a payment",
"sourceAmount": "Source amount of a payment",
"destinationCurrency": "Destination currency of a payment",
"destinationCountry": "Destination country of a payment",
"destinationAmount": "Destination amount of a payment",
"initiatedAt": "Timestamp when a payment was initiated",
"expiresAt": "Timestamp when a payment will expire",
"lastStateUpdatedAt": "Timestamp when a payment state was last updated",
"paymentLabel": "Label associated with a payment"
}
},
"OriginatorV2": {
"type": "object",
"description": "Payment originator and source details.",
"properties": {
"originatorIdentityId": {
"description": "The unique ID associated with the payment originator's identity record.",
"type": "string",
"example": "7ea3399c-1234-5678-8d8f-d320ea406630"
},
"originatorIdentityIdVersion": {
"description": "The current version of the originator's identity record.",
"type": "integer",
"example": 1
},
"originatorIdentityNickName": {
"description": "Nickname associated with the originator's identity record.",
"type": "string",
"maxLength": 100,
"example": "Successful Business Sender"
},
"internalId": {
"description": "An ID associated with this payment, if provided by the customer during payment initiation.",
"type": "string",
"maxLength": 36,
"example": "Invoice-123"
},
"sourceCurrency": {
"description": "originator's currency",
"type": "string",
"pattern": "^[A-Z]{3,5}$",
"maxLength": 5,
"example": "USD"
},
"sourceAmount": {
"description": "The amount sent by the originator in this payment. This field can hold a value with up to 6 decimal places.",
"type": "number",
"format": "double",
"example": 100
},
"payin": {
"description": "Details about how this payment is funded.",
"type": "string",
"example": "FUNDED"
}
}
},
"DestinationV2": {
"type": "object",
"properties": {
"beneficiaryFinancialInstrumentId": {
"description": "The financial instrument ID, the identity ID of the payment beneficiary is related to.",
"type": "string",
"example": "7ea3399c-1234-5678-8d8f-d320ea406630"
},
"destinationAmount": {
"description": "The amount received by the payment beneficiary. This field can hold a value with up to 6 decimal places.",
"type": "number",
"format": "double",
"example": 1234.111223
},
"destinationCountry": {
"description": "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.",
"type": "string",
"pattern": "^[A-Z]{2}$",
"maxLength": 2,
"example": "US"
},
"destinationCurrency": {
"description": "The currency code of the currency in which the beneficiary will receive this payment.",
"type": "string",
"pattern": "^[A-Z]{3,5}$",
"maxLength": 5,
"example": "USD"
},
"destinationBlockchainNetwork": {
"description": "The name of the blockchain network on which the beneficiary will receive this payment.",
"type": "string",
"minLength": 1,
"maxLength": 20,
"example": "Ethereum, TRON"
},
"beneficiaryIdentityId": {
"description": "The unique ID associated with the payment beneficiary's identity record.",
"type": "string",
"example": "7ea3399c-1234-5678-8d8f-d320ea406630"
},
"beneficiaryIdentityVersion": {
"description": "The current version of the beneficiary's identity record.",
"type": "integer",
"example": 1
},
"beneficiaryIdentityNickName": {
"description": "Nickname associated with the beneficiary's identity record.",
"type": "string",
"maxLength": 100,
"example": "Successful business beneficiary"
},
"payout": {
"description": "The payout category for this payment.",
"type": "string",
"example": "BANK"
}
}
},
"TransactionDetailsV2": {
"type": "object",
"description": "A summary of the payment category.",
"properties": {
"paymentProduct": {
"description": "The Ripple payments product used to make this payment.",
"type": "string",
"nullable": true,
"x-enumDescriptions": {
"LICENSED": "Identifies a transaction using Ripple Payments Direct."
}
},
"flowType": {
"description": "Specifies the type of payment you're making as categorized by the identity type of the payment originator and beneficiary.",
"type": "string",
"nullable": true,
"x-enumDescriptions": {
"B2B": "Specifies that this payment is made by a business originator to a business beneficiary.\n\n**Identification of third-party payment**:\n * If the `thirdPartyPayment` property is `true`, it indicates that you're making this payment on behalf of a business originator.\n * If the `thirdPartyPayment` property is `false`, it indicates that you are the business originator making this payment.\n",
"B2C": "Specifies that this payment is made by a business originator to an individual beneficiary.\n\n**Identification of third-party payment**:\n * If the `thirdPartyPayment` property is `true`, it indicates that you're making this payment on behalf of a business originator.\n * If the `thirdPartyPayment` property is `false`, it indicates that you are the business originator making this payment.\n"
}
},
"thirdPartyPayment": {
"description": "Flag to indicate if this payment is initiated on behalf of a third-party originator.",
"nullable": true,
"type": "boolean",
"example": false
},
"businessUseCase": {
"description": "Indicates the type of payment you're making.",
"type": "string",
"nullable": true,
"x-enumDescriptions": {
"FIAT_TRANSFER": "Indicates fiat source currency to fiat destination."
}
}
}
},
"PayoutExecutionDetails": {
"type": "object",
"description": "Metadata about the payout execution, including the payment rail used, timing, and tracking references.\n\n`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.\n\nWhen 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.\n\nCoverage will expand as additional corridors and partners are onboarded.\n",
"properties": {
"paymentRailUsed": {
"type": "string",
"description": "The payment rail or network used to execute the payout (e.g., FEDWIRE, ACH, RTP, SEPA, SWIFT).\n",
"example": "FEDWIRE"
},
"payoutStartTime": {
"type": "string",
"format": "date-time",
"description": "The time at which the payout execution started, specified in UTC.\n",
"example": "2026-02-18T14:22:15.789Z"
},
"payoutEndTime": {
"type": "string",
"format": "date-time",
"description": "The timestamp when the payout execution completed or was last updated, as reported by the payout partner.\nSpecified in UTC using ISO 8601 format. For in-progress payouts, this may represent the last status update time.\n",
"example": "2026-02-18T14:25:30.123Z"
},
"trackingReferences": {
"type": "array",
"description": "A list of tracking references for this transaction, such as transaction IDs and confirmation numbers.\n",
"items": {
"$ref": "#/components/schemas/TrackingReference"
}
}
}
},
"TrackingReference": {
"type": "object",
"description": "A tracking reference provided by the payout partner for this transaction.\n",
"properties": {
"referenceType": {
"type": "string",
"description": "The type or category of this tracking reference. Known values include IMAD and OMAD for Fedwire transfers, but additional types may be provided depending on the payment rail and payout partner.\n",
"example": "IMAD"
},
"value": {
"type": "string",
"description": "The tracking reference value. Use this to locate the transaction with the payout partner or payment rail operator. Format varies by referenceType.",
"example": "TXN-RTP-20260218-456789"
},
"displayName": {
"type": "string",
"description": "A human-readable name for this tracking reference, suitable for display in user interfaces.",
"example": "IMAD Number"
},
"description": {
"type": "string",
"description": "A detailed description of what this tracking reference represents and how it can be used.",
"example": "Input Message Accountability Data (IMAD) for Fedwire transfer tracking"
}
}
},
"Page": {
"type": "object",
"description": "Specify page size and the ID of the last fetched result.",
"properties": {
"size": {
"type": "integer",
"description": "Size of the page",
"default": 20,
"minimum": 1,
"maximum": 100,
"example": 20
},
"lastPageToken": {
"type": "string",
"description": "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."
}
}
},
"SearchPaymentsRequestV2": {
"type": "object",
"description": "Request body containing search criteria for payments.",
"properties": {
"filter": {
"$ref": "#/components/schemas/PaymentFilterV2"
},
"sort": {
"$ref": "#/components/schemas/SortV2"
},
"page": {
"$ref": "#/components/schemas/Page"
}
}
},
"SortV2": {
"type": "object",
"description": "Defines the sorting parameters for listing payments, including the field and sort direction.",
"properties": {
"sortField": {
"$ref": "#/components/schemas/PaymentSortFieldV2"
},
"sortDirection": {
"description": "Indicates whether results are sorted in ascending (`ASC`) or descending (`DESC`) order.",
"type": "string",
"default": "DESC",
"example": "DESC",
"enum": [
"ASC",
"DESC"
],
"x-enumDescriptions": {
"ASC": "Sort results in ascending order.",
"DESC": "Sort results in descending order."
}
}
}
},
"PaymentFilterV2": {
"type": "object",
"description": "Filter criteria to return desired payment search results.",
"properties": {
"paymentIds": {
"description": "Specify a list of uuids to search for payment with payment ids equals one from the list",
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"example": "aaaaaaaa-1111-bbbb-abab-123412341234",
"maxLength": 36
}
},
"paymentStates": {
"description": "Array of payment states like `EXECUTING` or `COMPLETED`.",
"type": "array",
"items": {
"$ref": "#/components/schemas/PaymentStateV2"
}
},
"filterRangeType": {
"description": "Specify a type to filter on. For example, PAYMENT_CREATION, PAYMENT_EXPIRY, or PAYMENT_STATUS_LAST_UPDATED",
"$ref": "#/components/schemas/PaymentFilterRangeTypeV2"
},
"beforeTimestamp": {
"description": "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.",
"type": "string",
"format": "date-time",
"example": "2024-04-24T14:15:22Z"
},
"afterTimestamp": {
"description": "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.",
"type": "string",
"format": "date-time",
"example": "2024-03-24T13:15:22Z"
},
"beneficiaryIdentityIds": {
"description": "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.",
"type": "array",
"items": {
"type": "string",
"example": "aaaaaaaa-1111-bbbb-abab-123412341234"
}
},
"internalId": {
"description": "Specify an `internalId` to get payments associated with them. A prefix match will be executed.",
"type": "string",
"maxLength": 36
},
"beneficiaryIdentityNickname": {
"description": "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.",
"type": "string",
"example": "Successful business beneficiary",
"maxLength": 100
},
"destinationCurrencies": {
"description": "Specify one or more currency codes to get payments where the beneficiary received funds in these currencies.",
"type": "array",
"items": {
"type": "string"
},
"pattern": "^[A-Z]{3,5}$"
},
"paymentLabels": {
"$ref": "#/components/schemas/PaymentLabels"
}
}
},
"PaymentFilterRangeTypeV2": {
"description": "The type of timestamp to use when filtering payments by a date and time range.\n\nSupported values include: \n- `PAYMENT_CREATION` \n- `PAYMENT_EXPIRY` \n- `PAYMENT_STATUS_LAST_UPDATED`\n\nIf another value is provided, the filter is rejected with a validation error.\n",
"type": "string",
"example": "PAYMENT_CREATION",
"x-enumDescriptions": {
"PAYMENT_CREATION": "Filter by the time a payment was created",
"PAYMENT_EXPIRY": "Filter by the time a payment is scheduled to expire",
"PAYMENT_STATUS_LAST_UPDATED": "Filter by the time a payment state was last updated"
}
},
"PaymentLabels": {
"description": "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.",
"type": "array",
"maxItems": 10,
"items": {
"type": "string",
"example": "batchId=aaaaaaaa-1111-bbbb-abab-123412341234",
"maxLength": 100
}
},
"UpdatePaymentLabelsResponse": {
"type": "object",
"description": "Response body for modifying payment labels",
"required": [
"labels"
],
"properties": {
"labels": {
"$ref": "#/components/schemas/PaymentLabels"
}
}
},
"UpdatePaymentLabelsRequest": {
"type": "object",
"description": "Request body containing the list of labels you want to add to or remove from the payment.",
"properties": {
"labelsToAdd": {
"$ref": "#/components/schemas/PaymentLabels"
},
"labelsToRemove": {
"$ref": "#/components/schemas/PaymentLabels"
}
}
},
"PaymentMemo": {
"type": "string",
"description": "Optional, transaction-specific memo carried with the payment for beneficiary reconciliation.\nValidation rules (required, allowed characters, max length) vary by corridor. Consult the data requirements for your corridor.\nNot stored in PII; persisted on the payment object and forwarded to compliance and payout partners.\nWhere 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.\nIf omitted, Ripple may generate a memo automatically.\n",
"example": "ORDER 2025-09-001 PAYMENT"
},
"AdjustedExchangeRate": {
"description": "Foreign Exchange (FX) rate used to calculate the quote.",
"type": "object",
"properties": {
"adjustedRate": {
"description": "Value of the Foreign Exchange (FX) rate.",
"type": "number",
"format": "double",
"example": 2
}
},
"additionalProperties": false
},
"TotalFeeBreakdown": {
"description": "A breakdown of the total fees included in this quote.",
"type": "object",
"properties": {
"calculatedFee": {
"description": "Value of the fee when the configured fee unit is applied against the `value`.",
"type": "number",
"format": "double",
"example": 2.43
},
"feeName": {
"description": "The name of the fee.",
"type": "string",
"minLength": 1,
"maxLength": 128,
"example": "Service fee"
},
"feeDescription": {
"description": "Description of the fee.",
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "The service fee charged for this transaction."
}
},
"additionalProperties": false
},
"FeeSummary": {
"type": "object",
"description": "A summary of fees included in this quote.",
"properties": {
"totalFee": {
"description": "The value of the total fee included in this quote.",
"type": "number",
"format": "double",
"example": 12.23
},
"feeCurrency": {
"description": "The currency in which fees are charged.",
"type": "string",
"pattern": "^[a-zA-Z]{3,5}$",
"example": "USD"
},
"feeBreakdown": {
"description": "An array of fees that provides a breakdown of how the total fees is calculated for this quote.",
"type": "array",
"items": {
"$ref": "#/components/schemas/TotalFeeBreakdown"
}
}
}
},
"TaxBreakdown": {
"description": "A breakdown of the individual taxes.",
"type": "object",
"properties": {
"taxAmount": {
"description": "tax amount for this tax line item.",
"type": "number",
"format": "double",
"example": 2.43
},
"taxName": {
"description": "The name of the tax.",
"type": "string",
"minLength": 1,
"maxLength": 128,
"example": "ISS/ VAT/ GST etc"
},
"taxDescription": {
"description": "GST service fee tax .",
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "The service fee tax charged for this transaction."
},
"taxRate": {
"description": "The tax rate applied to calculate the tax amount.",
"type": "number",
"format": "double",
"example": 5
}
},
"additionalProperties": false
},
"TaxSummary": {
"type": "object",
"description": "A summary of taxes included in this quote.",
"properties": {
"totalTaxes": {
"description": "The value of the total taxes included in this quote.",
"type": "number",
"format": "double",
"example": 5.12
},
"taxCurrency": {
"description": "The currency in which taxes are charged.",
"type": "string",
"pattern": "^[a-zA-Z]{3,5}$",
"example": "USD"
},
"taxBreakdown": {
"description": "An array of taxes with details such as tax description, rate, name and tax amount.",
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxBreakdown"
}
}
}
},
"get-identity-response-v3": {
"allOf": [
{
"$ref": "#/components/schemas/ripple-identity"
}
],
"type": "object",
"properties": {
"identityId": {
"type": "string",
"description": "Server-generated unique identifier of the identity.",
"example": "2f4ac57f-c5ba-4051-b51f-b3565778717b"
},
"identityState": {
"$ref": "#/components/schemas/identity-state"
},
"nickName": {
"type": "string",
"description": "Optional human-readable alias set by the client.",
"example": "nickName"
},
"tags": {
"type": "array",
"description": "Optional labels used to categorize or filter identities.",
"items": {
"type": "string",
"example": "tag1"
}
},
"validatePayoutRails": {
"type": "array",
"description": "List of payout methods where this identity is considered valid. Use this to indicate which payout methods (for example, US_ACH, EU_SEPA) the identity can be used with in payments.",
"items": {
"$ref": "#/components/schemas/financial-instrument-type"
}
},
"version": {
"type": "string",
"description": "Sequential version number. Each successful PUT creates a higher version.",
"example": 2
},
"schemaVersion": {
"type": "string",
"description": "Schema version used to validate this identity, for example 1.0.0.",
"example": "1.0.0"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "RFC 3339 timestamp when the identity was created.",
"example": "2023-11-02T18:26:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "RFC 3339 timestamp when the identity was last updated.",
"example": "2023-11-03T18:26:00.000Z"
}
}
},
"put-identity-request-v3": {
"allOf": [
{
"$ref": "#/components/schemas/put-ripple-identity"
}
],
"type": "object",
"properties": {
"nickName": {
"type": "string",
"description": "The new nickname for the identity",
"example": "nickName"
},
"validatePayoutRails": {
"type": "array",
"description": "The payout rails to validate the identity against",
"items": {
"$ref": "#/components/schemas/financial-instrument-type"
}
},
"tags": {
"type": "array",
"description": "Tags are used to categorize the identity.\n",
"items": {
"type": "string",
"example": "tag1"
}
}
}
},
"create-identity-request-v3": {
"allOf": [
{
"$ref": "#/components/schemas/ripple-identity"
}
],
"type": "object",
"properties": {
"nickName": {
"type": "string",
"description": "The nickname for the identity",
"example": "nickName",
"maxLength": 256
},
"validatePayoutRails": {
"type": "array",
"description": "The payout rails to validate the identity against",
"items": {
"$ref": "#/components/schemas/financial-instrument-type"
}
},
"tags": {
"type": "array",
"description": "Tags are used to categorize the identity.\n",
"items": {
"type": "string",
"example": "tag1"
}
}
}
},
"identity-state": {
"type": "string",
"description": "The state of the identity\n * ACTIVE\n * DEACTIVATED\n",
"x-enumDescriptions": {
"ACTIVE": "The identity requested exists and is active.",
"DEACTIVATED": "The identity requested has been deactivated."
},
"example": "ACTIVE"
},
"create-identity-response-v3": {
"type": "object",
"required": [
"identityId",
"version"
],
"properties": {
"identityId": {
"type": "string",
"description": "The unique ID of the identity",
"example": "2f4ac57f-c5ba-4051-b51f-b3565778717b"
},
"version": {
"type": "string",
"description": "The version number of the identity",
"example": "2"
}
}
},
"error": {
"type": "object",
"required": [
"code",
"title",
"type",
"description",
"timestamp"
],
"properties": {
"code": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Unique identifier of an error",
"example": "SYS_100"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Error message providing a brief summary of the error",
"example": "No identity exists for identityId"
},
"type": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Identifies the problem type",
"example": "USER_VALIDATION_ERROR"
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"description": "Provides more technical information",
"example": "Unable to get identity. Identity ID should be in UUID format"
},
"timestamp": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"format": "date-time",
"description": "The time when this error occurred, specified in UTC.",
"example": "2023-11-02T18:26:00.000123Z"
}
}
},
"error-response": {
"type": "object",
"required": [
"status",
"errors"
],
"properties": {
"status": {
"type": "integer",
"description": "The HTTP status code of the error",
"example": 404
},
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/error"
}
},
"timestamp": {
"type": "string",
"description": "The timestamp of the error",
"example": "2023-11-02T18:26:00.000Z"
}
}
},
"list-identities-response-v3": {
"type": "object",
"format": "application/json",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/identity-response-v3"
},
"description": "The list of the identities that match the query parameters"
},
"nextToken": {
"type": "string",
"description": "The token to retrieve the next page of results"
}
}
},
"create-financial-instrument-response": {
"type": "object",
"required": [
"financialInstrumentId"
],
"properties": {
"financialInstrumentId": {
"type": "string",
"description": "The unique ID of the financial instrument",
"example": "2f4ac57f-c5ba-4051-b51f-b3565778717b"
}
}
},
"identity-response-v3": {
"type": "object",
"required": [
"identityId",
"identityType",
"paymentRole",
"createdAt",
"updatedAt",
"identityState",
"version",
"schemaVersion"
],
"properties": {
"identityId": {
"type": "string",
"description": "The unique ID of the identity",
"example": "2f4ac57f-c5ba-4051-b51f-b3565778717b"
},
"identityType": {
"$ref": "#/components/schemas/identity-type-v3"
},
"paymentRole": {
"$ref": "#/components/schemas/payment-role"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "The time at which the identity was created",
"example": "2023-11-02T18:26:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "The time at which the identity was last updated",
"example": "2023-11-03T18:26:00.000Z"
},
"identityState": {
"$ref": "#/components/schemas/identity-state"
},
"nickName": {
"type": "string",
"description": "The nickname for the identity provided at the time of identity creation",
"example": "nickName"
},
"internalId": {
"type": "string",
"description": "The internal ID of the identity used for internal processing",
"example": "2f4ac57f-c5ba-4051-b51f-b3565778717b"
},
"tags": {
"type": "array",
"description": "Tags are used to categorize the identity.\n",
"items": {
"type": "string",
"example": "tag1"
}
},
"version": {
"type": "integer",
"description": "The version number of the identity",
"example": 2
},
"schemaVersion": {
"type": "string",
"description": "The version of the schema",
"example": "1.0.0"
}
}
},
"get-financial-instrument-response": {
"type": "object",
"required": [
"financialInstrument"
],
"description": "This object contains the details of a financial instrument and optional identity if requested.",
"properties": {
"financialInstrument": {
"$ref": "#/components/schemas/ripple-financial-instrument-entry"
},
"identity": {
"$ref": "#/components/schemas/get-identity-response-v3"
}
}
},
"update-financial-instrument-response": {
"allOf": [
{
"$ref": "#/components/schemas/ripple-financial-instrument-entry"
}
],
"type": "object",
"description": "This object contains the details of the updated financial instrument.",
"required": [
"financialInstrumentId"
]
},
"list-financial-instruments-response": {
"type": "object",
"format": "application/json",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/financial-instrument-metadata"
},
"description": "The list of the financial instruments that match the query parameters"
},
"nextToken": {
"type": "string",
"description": "The token to retrieve the next page of results"
}
}
},
"identity-type-v3": {
"type": "string",
"x-extensible-enum": [
"BUSINESS",
"INDIVIDUAL"
],
"x-enumDescriptions": {
"BUSINESS": "Identity associated with an institution or business",
"INDIVIDUAL": "Identity associated with an individual"
},
"description": "The type of the identity",
"example": "BUSINESS"
},
"payment-role": {
"type": "string",
"x-extensible-enum": [
"ORIGINATOR",
"BENEFICIARY"
],
"x-enumDescriptions": {
"ORIGINATOR": "Refers to originator identity",
"BENEFICIARY": "Refers to beneficiary identity"
},
"description": "The payment role of the identity",
"example": "BENEFICIARY"
},
"business-identity": {
"type": "object",
"title": "Business identity",
"description": "PII data to support business and institutional identities\n",
"required": [
"businessName",
"address"
],
"properties": {
"businessName": {
"type": "string",
"description": "Business Legal Name",
"pattern": "^(?![ .,'&\\/()-])(?!.*([ .,'&\\/()-])\\1)[\\p{L}\\p{N} .,'&\\/()-]+(?]+$"
},
"example": [
"123 Example St. Boston, MA"
]
},
"country": {
"type": "string",
"description": "Allows the country of the business to be held. Use Alpha-2 Code as defined in the [ISO CountryCode ISO 3166-1](https://www.iso.org/obp/ui/#search) list.",
"minLength": 2,
"maxLength": 2,
"pattern": "^[A-Z]+$",
"example": "US"
},
"city": {
"type": "string",
"description": "City",
"minLength": 1,
"maxLength": 140,
"pattern": "^(?![ .'-])(?!.*[ .'-]{2})[\\p{L} .'-]+(?]+$"
},
"example": [
"123 Example St. Boston, MA"
]
},
"country": {
"type": "string",
"description": "Allows the Country of the individual to be held. Use Alpha-2 Code as defined in the [ISO CountryCode ISO 3166-1](https://www.iso.org/obp/ui/#search) list.",
"minLength": 2,
"maxLength": 2,
"pattern": "^[A-Z]+$",
"example": "US"
},
"city": {
"type": "string",
"description": "City",
"minLength": 1,
"maxLength": 140,
"pattern": "^(?![ .'-])(?!.*[ .'-]{2})[\\p{L} .'-]+(?