{
"openapi": "3.0.1",
"info": {
"description": "The Ripple Collection APIs are used to manage collections, manage payment channels, manage partners and settlements.\n## API Environments\nThe Ripple Collection APIs offers the following environments:\n| Environment
| Base URL | Description |\n| ------------------------------------------ | ----------------------------- | ----------------------------------------- |\n| Sandbox | `https://docs.ripple.com/products/collections/_mock/api/collections` | Sandbox environment with mock data which does not require auth.|\n| UAT | `https://api.test.ripple.com` | UAT environment with simulated transactions. |\n| Production | `https://api.ripple.com` | Production environment |\n\nFor guides on API authentication, idempotency, and webhook verification, see the sidebar. ",
"title": "Ripple Collections",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.test.ripple.com"
},
{
"url": "https://api.ripple.com"
}
],
"tags": [
{
"name": "Authentication",
"description": "Endpoints for authentication"
},
{
"name": "Accounts",
"description": "Endpoints for managing payment accounts"
},
{
"name": "Collection Links",
"description": "Endpoints for managing one-time collection links with account-based routing"
},
{
"name": "Collection Channels",
"description": "Endpoints for managing persistent collection channels with account-based routing"
},
{
"name": "Partners",
"description": "Endpoints for managing partners who can transact"
},
{
"name": "Settlements",
"description": "Endpoints for managing settlements"
},
{
"name": "Transactions",
"description": "Endpoints for viewing transactions across collection links and channels with account-based routing"
},
{
"name": "Webhooks",
"description": "Endpoints for managing webhook registrations"
}
],
"paths": {
"/v2/oauth/token": {
"post": {
"tags": [
"Authentication"
],
"operationId": "authenticate",
"summary": "Request an access token",
"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/AuthErrorResponse"
},
"example": {
"error_description": "Missing required parameter: grant_type",
"error": "invalid_request"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthErrorResponse"
},
"example": {
"error_description": "Unauthorized",
"error": "access_denied"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthErrorResponse"
},
"example": {
"error_description": "Service not enabled within domain: "
}
}
}
}
},
"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](../../tutorials/request-an-access-token/).\n\n#### Environments\n\n| Environment | Domain | Description |\n| --- | --- | --- |\n| UAT | `api.test.ripple.com` | UAT environment with simulated transactions. |\n| Production | `api.ripple.com` | Production environment |\n"
}
},
"/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"
}
}
}
},
"/v1/collections/accounts": {
"get": {
"tags": [
"Accounts"
],
"summary": "List accounts",
"description": "Retrieves a list of accounts, filterable by query parameters.",
"operationId": "listAccountsV1",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "id",
"in": "query",
"description": "Filter accounts by specific account identifier",
"schema": {
"type": "string",
"format": "uuid",
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
},
{
"name": "account_owner_id",
"in": "query",
"description": "Filter accounts by account owner identifier",
"schema": {
"type": "string",
"format": "uuid",
"example": "291ecf34-a01d-466a-b0fd-662a88b7a1bb"
}
},
{
"name": "currency",
"in": "query",
"description": "Filter accounts by currency",
"schema": {
"type": "string"
},
"example": "USD"
},
{
"name": "type",
"in": "query",
"description": "Filter accounts by type",
"schema": {
"$ref": "#/components/schemas/AccountType"
},
"example": "FIAT"
},
{
"name": "status",
"in": "query",
"description": "Filter accounts by status",
"schema": {
"$ref": "#/components/schemas/AccountStatus"
},
"example": "ACTIVE"
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
},
"description": "Page number (starts at 1)",
"example": 1
},
{
"name": "size",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"default": 10
},
"description": "Page size (items per page)",
"example": 10
}
],
"responses": {
"200": {
"description": "A list of accounts.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Account"
}
},
"page": {
"$ref": "#/components/schemas/PageMetadata"
}
}
},
"examples": {
"default": {
"summary": "Example account list response",
"value": {
"content": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"account_owner_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"currency": "USD",
"type": "FIAT",
"rails": [
"FEDWIRE",
"ACH",
"RTP"
],
"balances": {
"available": {
"amount": "1250.50"
},
"pending": {
"inbound": {
"amount": "50.00"
},
"outbound": {
"amount": "25.00"
}
}
},
"ownership_level": "PARTNER",
"status": "ACTIVE",
"created_at": "2025-09-18T22:54:00.542Z",
"updated_at": "2025-09-18T22:54:00.542Z"
},
{
"id": "250d6dc5-382f-4750-8657-0780be594d68",
"account_owner_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"currency": "BRL",
"type": "FIAT",
"rails": [
"PIX"
],
"balances": {
"available": {
"amount": "0.00"
},
"pending": {
"inbound": {
"amount": "0.00"
},
"outbound": {
"amount": "0.00"
}
}
},
"ownership_level": "PARTNER",
"status": "ACTIVE",
"created_at": "2025-09-18T22:54:00.542Z",
"updated_at": "2025-09-18T22:54:00.542Z"
},
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"account_owner_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"currency": "USDC",
"type": "CRYPTO",
"rails": [
"BLOCKCHAIN"
],
"balances": {
"available": {
"amount": "0.00"
},
"pending": {
"inbound": {
"amount": "0.00"
},
"outbound": {
"amount": "0.00"
}
}
},
"ownership_level": "PARTNER",
"status": "ACTIVE",
"created_at": "2025-09-18T22:54:00.542Z",
"updated_at": "2025-09-18T22:54:00.542Z"
}
],
"page": {
"page": 1,
"size": 10,
"total_elements": 3,
"total_pages": 1
}
}
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"tags": [
"Accounts"
],
"summary": "Create an account",
"description": "Creates a new payment account for a beneficiary partner. The account type (CRYPTO or FIAT)\nis determined by the currency specified. Account creation is subject to the beneficiary's\npartner eligibility.\n",
"operationId": "createAccountV1",
"security": [
{
"Bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateAccountRequest"
},
"examples": {
"crypto_account": {
"summary": "Example crypto account creation",
"value": {
"beneficiary_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"currency": "USDC"
}
},
"usd_fiat_account": {
"summary": "Example USD fiat account creation",
"value": {
"beneficiary_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"currency": "USD"
}
},
"brl_fiat_account": {
"summary": "Example BRL fiat account creation",
"value": {
"beneficiary_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"currency": "BRL"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Account created successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
},
"examples": {
"customer_usd_fiat_account": {
"summary": "Example customer USD fiat account response",
"value": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"account_owner_id": "87a6b830-1bbe-409c-9bff-9cf12bed774f",
"currency": "USD",
"type": "FIAT",
"rails": [
"FEDWIRE",
"ACH",
"RTP"
],
"balances": {
"available": {
"amount": "0.00"
},
"pending": {
"inbound": {
"amount": "0.00"
},
"outbound": {
"amount": "0.00"
}
}
},
"ownership_level": "CUSTOMER",
"status": "ACTIVE",
"created_at": "2025-09-18T22:54:00.542Z",
"updated_at": "2025-09-18T22:54:00.542Z"
}
},
"customer_brl_fiat_account": {
"summary": "Example customer BRL fiat account response",
"value": {
"id": "250d6dc5-382f-4750-8657-0780be594d68",
"account_owner_id": "87a6b830-1bbe-409c-9bff-9cf12bed774f",
"currency": "BRL",
"type": "FIAT",
"rails": [
"PIX"
],
"balances": {
"available": {
"amount": "0.00"
},
"pending": {
"inbound": {
"amount": "0.00"
},
"outbound": {
"amount": "0.00"
}
}
},
"ownership_level": "CUSTOMER",
"status": "ACTIVE",
"created_at": "2025-09-18T22:54:00.542Z",
"updated_at": "2025-09-18T22:54:00.542Z"
}
},
"customer_usdc_crypto_account": {
"summary": "Example customer USDC crypto account response",
"value": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"account_owner_id": "87a6b830-1bbe-409c-9bff-9cf12bed774f",
"currency": "USDC",
"type": "CRYPTO",
"rails": [
"BLOCKCHAIN"
],
"balances": {
"available": {
"amount": "0.00"
},
"pending": {
"inbound": {
"amount": "0.00"
},
"outbound": {
"amount": "0.00"
}
}
},
"ownership_level": "CUSTOMER",
"status": "ACTIVE",
"created_at": "2025-09-18T22:54:00.542Z",
"updated_at": "2025-09-18T22:54:00.542Z"
}
},
"crypto_account": {
"summary": "Example crypto account response",
"value": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"account_owner_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"currency": "USDC",
"type": "CRYPTO",
"rails": [
"BLOCKCHAIN"
],
"balances": {
"available": {
"amount": "0.00"
},
"pending": {
"inbound": {
"amount": "0.00"
},
"outbound": {
"amount": "0.00"
}
}
},
"ownership_level": "PARTNER",
"status": "ACTIVE",
"created_at": "2025-09-18T22:54:00.542Z",
"updated_at": "2025-09-18T22:54:00.542Z"
}
},
"usd_fiat_account": {
"summary": "Example USD fiat account response",
"value": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"account_owner_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"currency": "USD",
"type": "FIAT",
"rails": [
"FEDWIRE",
"ACH",
"RTP"
],
"balances": {
"available": {
"amount": "0.00"
},
"pending": {
"inbound": {
"amount": "0.00"
},
"outbound": {
"amount": "0.00"
}
}
},
"ownership_level": "PARTNER",
"status": "ACTIVE",
"created_at": "2025-09-18T22:54:00.542Z",
"updated_at": "2025-09-18T22:54:00.542Z"
}
},
"brl_fiat_account": {
"summary": "Example BRL fiat account response",
"value": {
"id": "250d6dc5-382f-4750-8657-0780be594d68",
"account_owner_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"currency": "BRL",
"type": "FIAT",
"rails": [
"PIX"
],
"balances": {
"available": {
"amount": "0.00"
},
"pending": {
"inbound": {
"amount": "0.00"
},
"outbound": {
"amount": "0.00"
}
}
},
"ownership_level": "PARTNER",
"status": "ACTIVE",
"created_at": "2025-09-18T22:54:00.542Z",
"updated_at": "2025-09-18T22:54:00.542Z"
}
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Forbidden - Partner access does not allow this account type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/collections/accounts/{account_id}": {
"get": {
"tags": [
"Accounts"
],
"summary": "Get account by ID",
"description": "Retrieves the details of a specific account by its ID.",
"operationId": "getAccountByIdV1",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "account_id",
"in": "path",
"required": true,
"description": "Unique identifier of the account to retrieve",
"schema": {
"type": "string",
"format": "uuid",
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Account"
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Account not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/collections/accounts/{account_id}/transactions": {
"get": {
"tags": [
"Accounts"
],
"summary": "List transactions for an account",
"description": "Retrieves a paginated list of transactions associated with a specific account. Replaces the embedded transactions array in channel/collection responses for better scalability and pagination support.\n",
"operationId": "listTransactionsByAccountIdV1",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "account_id",
"in": "path",
"required": true,
"description": "Unique identifier of the account",
"schema": {
"type": "string",
"format": "uuid",
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
},
{
"name": "status",
"in": "query",
"schema": {
"$ref": "#/components/schemas/TransactionStatus"
},
"description": "Filter by transaction status"
},
{
"name": "since",
"in": "query",
"schema": {
"type": "string",
"format": "date-time"
},
"description": "ISO 8601 timestamp — return transactions created after this time",
"example": "2025-06-17T12:00:00Z"
},
{
"name": "until",
"in": "query",
"schema": {
"type": "string",
"format": "date-time"
},
"description": "ISO 8601 timestamp — return transactions created before this time",
"example": "2025-06-17T12:00:00Z"
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
},
"description": "Page number (starts at 1)",
"example": 1
},
{
"name": "size",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"default": 10
},
"description": "Page size (items per page)",
"example": 10
}
],
"responses": {
"200": {
"description": "A paginated list of transactions for the account.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TransactionV1"
}
},
"page": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"size": {
"type": "integer"
},
"total_elements": {
"type": "integer"
},
"total_pages": {
"type": "integer"
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Account not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/collections/partners": {
"get": {
"tags": [
"Partners"
],
"summary": "List partners",
"description": "Retrieves a list of partners, filterable by ID or type.",
"operationId": "listPartnersV1",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "id",
"in": "query",
"description": "Filter partners by specific partner ID",
"schema": {
"type": "string",
"format": "uuid",
"example": "0c5479ff-3772-4123-b2b7-e679e71eb570"
}
},
{
"name": "since",
"in": "query",
"schema": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp after partner was created"
},
"example": "2025-06-17T12:00:00Z"
},
{
"name": "until",
"in": "query",
"schema": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp before partner was created"
},
"example": "2025-06-17T12:00:00Z"
},
{
"name": "type",
"in": "query",
"description": "Filter partners by type",
"schema": {
"type": "string",
"$ref": "#/components/schemas/PartnerType"
}
},
{
"name": "status",
"in": "query",
"description": "Filter partners by status",
"schema": {
"type": "string",
"$ref": "#/components/schemas/PartnerStatus"
}
},
{
"name": "external_reference_id",
"in": "query",
"schema": {
"type": "string",
"description": "External reference id for partner"
},
"example": "Ref-123"
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
},
"description": "Page number (starts at 1)",
"example": 1
},
{
"name": "size",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"default": 10
},
"description": "Page size (items per page)",
"example": 10
}
],
"responses": {
"200": {
"description": "A list of partners.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PartnerV1"
}
},
"page": {
"$ref": "#/components/schemas/PageMetadata"
}
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters or invalid field partner for business or individual partner",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"tags": [
"Partners"
],
"summary": "Create a partner",
"description": "This API allows users to add new parties who can transact.",
"operationId": "createPartnerV1",
"security": [
{
"Bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePartnerRequest"
}
}
}
},
"responses": {
"201": {
"description": "Partner created successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PartnerV1"
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/collections/partners/{partner_id}": {
"get": {
"tags": [
"Partners"
],
"summary": "Get partner by ID",
"description": "This API allows users to retrieve a specific partner by their ID.",
"operationId": "getPartnerByIdV1",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "partner_id",
"in": "path",
"required": true,
"description": "Unique identifier of the partner to retrieve",
"schema": {
"type": "string",
"format": "uuid",
"example": "0c5479ff-3772-4123-b2b7-e679e71eb570"
}
},
{
"name": "external_reference_id",
"in": "query",
"schema": {
"type": "string",
"description": "External reference id for partner"
},
"example": "Ref-123"
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PartnerV1"
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Not Found - Partner does not exist",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"put": {
"tags": [
"Partners"
],
"summary": "Update a partner",
"description": "API to update a partner to use in collections API.",
"operationId": "updatePartnerV1",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "partner_id",
"in": "path",
"required": true,
"description": "Unique identifier of the partner to update",
"schema": {
"type": "string",
"format": "uuid",
"example": "0c5479ff-3772-4123-b2b7-e679e71eb570"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdatePartnerRequest"
}
}
}
},
"responses": {
"200": {
"description": "Partner updated successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PartnerV1"
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Not Found - Partner does not exist",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/collections/settlements": {
"get": {
"tags": [
"Settlements"
],
"summary": "List settlements",
"description": "API to fetch first party payouts (settlements) with enhanced v1 response format.",
"operationId": "listSettlementsV1",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "id",
"in": "query",
"description": "Filter settlements by specific settlement ID",
"schema": {
"type": "string",
"format": "uuid",
"example": "63dd59dd-88be-41a2-a246-2f6724209422"
}
},
{
"name": "type",
"in": "query",
"schema": {
"$ref": "#/components/schemas/SettlementType"
},
"description": "Settlement type"
},
{
"name": "status",
"in": "query",
"schema": {
"$ref": "#/components/schemas/SettlementStatus"
},
"description": "Settlement status"
},
{
"name": "since",
"in": "query",
"schema": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp after settlement was created"
},
"example": "2025-06-17T12:00:00Z"
},
{
"name": "until",
"in": "query",
"schema": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp before settlement was created"
},
"example": "2025-06-17T12:00:00Z"
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
},
"description": "Page number (starts at 1)",
"example": 1
},
{
"name": "size",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10
},
"description": "Number of settlements per page",
"example": 10
}
],
"responses": {
"200": {
"description": "A list of settlements.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SettlementV1"
}
},
"page": {
"$ref": "#/components/schemas/PageMetadata"
}
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"tags": [
"Settlements"
],
"summary": "Create a settlement",
"description": "API to initiate a first party payout (settlement to our customer).",
"operationId": "createSettlementV1",
"security": [
{
"Bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateSettlementRequestV1"
}
}
}
},
"responses": {
"201": {
"description": "Settlement created successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SettlementV1"
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/collections/settlements/{settlement_id}": {
"get": {
"tags": [
"Settlements"
],
"summary": "Get settlement by ID",
"description": "API to fetch a first party payout (settlement to our customer) with enhanced v1 response format.",
"operationId": "getSettlementByIdV1",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "settlement_id",
"in": "path",
"required": true,
"description": "Unique identifier of the settlement to retrieve",
"schema": {
"type": "string",
"format": "uuid",
"example": "63dd59dd-88be-41a2-a246-2f6724209422"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SettlementV1"
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Not Found - Settlement does not exist",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/collections/channels": {
"get": {
"tags": [
"Collection Channels"
],
"summary": "List channels",
"description": "Retrieves a list of channels using account-based routing, filterable by query parameters.",
"operationId": "listChannelsV1",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "id",
"in": "query",
"description": "Filter channels by specific channel identifier",
"schema": {
"type": "string",
"format": "uuid",
"example": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
},
{
"name": "payer_id",
"in": "query",
"description": "Filter channels by payer identifier",
"schema": {
"type": "string",
"format": "uuid",
"example": "e471b938-98ad-45e4-b144-53a556ea047d"
}
},
{
"name": "account_id",
"in": "query",
"description": "Filter channels by account identifier",
"schema": {
"type": "string",
"format": "uuid",
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
},
{
"name": "beneficiary_id",
"in": "query",
"description": "Filter channels by beneficiary identifier",
"schema": {
"type": "string",
"format": "uuid",
"example": "291ecf34-a01d-466a-b0fd-662a88b7a1bb"
}
},
{
"name": "status",
"in": "query",
"description": "Filter channels by status",
"schema": {
"$ref": "#/components/schemas/ChannelStatus"
},
"example": "ACTIVE"
},
{
"name": "since",
"in": "query",
"schema": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp after channel was created"
},
"example": "2025-06-17T12:00:00Z"
},
{
"name": "until",
"in": "query",
"schema": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp before channel was created"
},
"example": "2025-06-17T12:00:00Z"
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
},
"description": "Page number (starts at 1)",
"example": 1
},
{
"name": "size",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"default": 10
},
"description": "Page size (items per page)",
"example": 10
}
],
"responses": {
"200": {
"description": "A list of channels.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChannelV1"
}
},
"page": {
"$ref": "#/components/schemas/PageMetadata"
}
}
},
"examples": {
"default": {
"summary": "Example channel list response",
"value": {
"content": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"payer": {
"id": "e471b938-98ad-45e4-b144-53a556ea047d",
"name": "Nigerian Imports Ltd.",
"email": "nigerian@imports.com"
},
"beneficiary": {
"id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"name": "Hong Kong Exports Ltd.",
"email": "hongkong@exports.com"
},
"account": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"beneficiary_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"currency": "USDC",
"type": "CRYPTO"
},
"payment_methods": [
{
"type": "BLOCKCHAIN",
"network": "ETHEREUM",
"address": "0xBb592aaaF9AcE2fbE3F735645819FA94c95a9cb5",
"currency": "USDC"
}
],
"payment_link": "https://collections.ripplenet.com/pay/channel/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "ACTIVE",
"reason": null,
"created_at": "2025-09-18T22:54:00.542Z",
"updated_at": "2025-09-18T22:54:00.542Z"
},
{
"id": "cb34b0e3-d20d-4a7c-9ad7-b461d7991555",
"payer": {
"id": "e471b938-98ad-45e4-b144-53a556ea047d",
"name": "Nigerian Imports Ltd.",
"email": "nigerian@imports.com"
},
"beneficiary": {
"id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"name": "Hong Kong Exports Ltd.",
"email": "hongkong@exports.com"
},
"account": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"beneficiary_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"currency": "USD",
"type": "FIAT"
},
"payment_methods": [
{
"type": "FEDWIRE",
"account_number": "1234567890",
"routing_number": "021000021",
"swift_code": "CHASUS33",
"memo": "CH-cb34b0e3"
},
{
"type": "ACH",
"account_number": "1234567890",
"routing_number": "021000021",
"memo": "CH-cb34b0e3"
}
],
"payment_link": "https://collections.ripplenet.com/pay/channel/cb34b0e3-d20d-4a7c-9ad7-b461d7991555",
"status": "ACTIVE",
"reason": null,
"created_at": "2025-09-18T22:54:00.542Z",
"updated_at": "2025-09-18T22:54:00.542Z"
}
],
"page": {
"page": 1,
"size": 10,
"total_elements": 2,
"total_pages": 1
}
}
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"tags": [
"Collection Channels"
],
"summary": "Create a channel",
"description": "Creates a new payment channel using account-based routing. The channel is associated\nwith an account which determines the available payment rails (crypto networks or fiat\nrails) based on the account's currency.\n",
"operationId": "createChannelV1",
"security": [
{
"Bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateChannelRequestV1"
},
"examples": {
"default": {
"summary": "Example channel creation request",
"value": {
"payer_id": "e471b938-98ad-45e4-b144-53a556ea047d",
"account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Channel created successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelV1"
},
"examples": {
"crypto_channel": {
"summary": "Example crypto channel response",
"value": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"payer": {
"id": "e471b938-98ad-45e4-b144-53a556ea047d",
"name": "Nigerian Imports Ltd.",
"email": "nigerian@imports.com"
},
"beneficiary": {
"id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"name": "Hong Kong Exports Ltd.",
"email": "hongkong@exports.com"
},
"account": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"beneficiary_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"currency": "USDC",
"type": "CRYPTO"
},
"payment_methods": [
{
"type": "BLOCKCHAIN",
"network": "ETHEREUM",
"address": "0xBb592aaaF9AcE2fbE3F735645819FA94c95a9cb5",
"currency": "USDC"
},
{
"type": "BLOCKCHAIN",
"network": "SOLANA",
"address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
"currency": "USDC"
}
],
"payment_link": "https://collections.ripplenet.com/pay/channel/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "ACTIVE",
"reason": null,
"created_at": "2025-09-18T22:54:00.542Z",
"updated_at": "2025-09-18T22:54:00.542Z"
}
},
"fiat_channel": {
"summary": "Example fiat channel response",
"value": {
"id": "cb34b0e3-d20d-4a7c-9ad7-b461d7991555",
"payer": {
"id": "e471b938-98ad-45e4-b144-53a556ea047d",
"name": "Nigerian Imports Ltd.",
"email": "nigerian@imports.com"
},
"beneficiary": {
"id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"name": "Hong Kong Exports Ltd.",
"email": "hongkong@exports.com"
},
"account": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"beneficiary_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"currency": "USD",
"type": "FIAT"
},
"payment_methods": [
{
"type": "FEDWIRE",
"account_number": "1234567890",
"routing_number": "021000021",
"swift_code": "CHASUS33",
"memo": "CH-cb34b0e3"
},
{
"type": "ACH",
"account_number": "1234567890",
"routing_number": "021000021",
"memo": "CH-cb34b0e3"
},
{
"type": "RTP",
"account_number": "1234567890",
"routing_number": "021000021",
"memo": "CH-cb34b0e3"
}
],
"payment_link": "https://collections.ripplenet.com/pay/channel/4gb96g75-6828-5673-c4gd-3d074g77bgb7",
"status": "ACTIVE",
"reason": null,
"created_at": "2025-09-18T22:54:00.542Z",
"updated_at": "2025-09-18T22:54:00.542Z"
}
},
"brl_fiat_channel": {
"summary": "Example BRL fiat channel response with PIX",
"value": {
"id": "d45e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
"payer": {
"id": "e471b938-98ad-45e4-b144-53a556ea047d",
"name": "Brazilian Imports Ltd.",
"email": "brazil@imports.com"
},
"beneficiary": {
"id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"name": "Hong Kong Exports Ltd.",
"email": "hongkong@exports.com"
},
"account": {
"id": "250d6dc5-382f-4750-8657-0780be594d68",
"beneficiary_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"currency": "BRL",
"type": "FIAT"
},
"payment_methods": [
{
"type": "PIX",
"pix_key": "payments@hongkongexports.com",
"pix_key_type": "EMAIL",
"beneficiary_name": "Hong Kong Exports Ltd."
}
],
"payment_link": "https://collections.ripplenet.com/pay/channel/d45e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
"status": "ACTIVE",
"reason": null,
"created_at": "2025-09-18T22:54:00.542Z",
"updated_at": "2025-09-18T22:54:00.542Z"
}
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Forbidden - Account type not allowed for this operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Not Found - Account or payer not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/collections/channels/{channel_id}": {
"get": {
"tags": [
"Collection Channels"
],
"summary": "Get channel details",
"description": "Retrieves the details of a specific channel by its ID using account-based routing.",
"operationId": "getChannelByIdV1",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "channel_id",
"in": "path",
"required": true,
"description": "Unique identifier of the channel to retrieve",
"schema": {
"type": "string",
"format": "uuid",
"example": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelV1"
},
"examples": {
"crypto_channel": {
"summary": "Example crypto channel response",
"value": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"payer": {
"id": "e471b938-98ad-45e4-b144-53a556ea047d",
"name": "Nigerian Imports Ltd.",
"email": "nigerian@imports.com"
},
"beneficiary": {
"id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"name": "Hong Kong Exports Ltd.",
"email": "hongkong@exports.com"
},
"account": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"beneficiary_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"currency": "USDC",
"type": "CRYPTO"
},
"payment_methods": [
{
"type": "BLOCKCHAIN",
"network": "ETHEREUM",
"address": "0xBb592aaaF9AcE2fbE3F735645819FA94c95a9cb5",
"currency": "USDC"
},
{
"type": "BLOCKCHAIN",
"network": "SOLANA",
"address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
"currency": "USDC"
}
],
"payment_link": "https://collections.ripplenet.com/pay/channel/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "ACTIVE",
"reason": null,
"created_at": "2025-09-18T22:54:00.542Z",
"updated_at": "2025-09-18T22:54:00.542Z"
}
},
"fiat_channel": {
"summary": "Example fiat channel response",
"value": {
"id": "cb34b0e3-d20d-4a7c-9ad7-b461d7991555",
"payer": {
"id": "e471b938-98ad-45e4-b144-53a556ea047d",
"name": "Nigerian Imports Ltd.",
"email": "nigerian@imports.com"
},
"beneficiary": {
"id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"name": "Hong Kong Exports Ltd.",
"email": "hongkong@exports.com"
},
"account": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"beneficiary_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"currency": "USD",
"type": "FIAT"
},
"payment_methods": [
{
"type": "FEDWIRE",
"account_number": "1234567890",
"routing_number": "021000021",
"swift_code": "CHASUS33",
"memo": "CH-cb34b0e3"
},
{
"type": "ACH",
"account_number": "1234567890",
"routing_number": "021000021",
"memo": "CH-cb34b0e3"
},
{
"type": "RTP",
"account_number": "1234567890",
"routing_number": "021000021",
"memo": "CH-cb34b0e3"
}
],
"payment_link": "https://collections.ripplenet.com/pay/channel/cb34b0e3-d20d-4a7c-9ad7-b461d7991555",
"status": "ACTIVE",
"reason": null,
"created_at": "2025-09-18T22:54:00.542Z",
"updated_at": "2025-09-18T22:54:00.542Z"
}
},
"brl_fiat_channel": {
"summary": "Example BRL fiat channel response with PIX",
"value": {
"id": "d45e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
"payer": {
"id": "e471b938-98ad-45e4-b144-53a556ea047d",
"name": "Brazilian Imports Ltd.",
"email": "brazil@imports.com"
},
"beneficiary": {
"id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"name": "Hong Kong Exports Ltd.",
"email": "hongkong@exports.com"
},
"account": {
"id": "250d6dc5-382f-4750-8657-0780be594d68",
"beneficiary_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"currency": "BRL",
"type": "FIAT"
},
"payment_methods": [
{
"type": "PIX",
"pix_key": "payments@hongkongexports.com",
"pix_key_type": "EMAIL",
"beneficiary_name": "Hong Kong Exports Ltd."
}
],
"payment_link": "https://collections.ripplenet.com/pay/channel/d45e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
"status": "ACTIVE",
"reason": null,
"created_at": "2025-09-18T22:54:00.542Z",
"updated_at": "2025-09-18T22:54:00.542Z"
}
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Not Found - Channel does not exist",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/collections/links": {
"get": {
"tags": [
"Collection Links"
],
"summary": "List collections",
"description": "Retrieves a list of collections using account-based routing, filterable by query parameters.",
"operationId": "listCollectionsV1",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "id",
"in": "query",
"description": "Filter collections by specific collection identifier",
"schema": {
"type": "string",
"format": "uuid",
"example": "e8d43598-107d-4694-9fb2-934e7484c3d4"
}
},
{
"name": "payer_id",
"in": "query",
"description": "Filter collections by payer identifier",
"schema": {
"type": "string",
"format": "uuid",
"example": "0c5479ff-3772-4123-b2b7-e679e71eb570"
}
},
{
"name": "account_id",
"in": "query",
"description": "Filter collections by account identifier",
"schema": {
"type": "string",
"format": "uuid",
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
},
{
"name": "beneficiary_id",
"in": "query",
"description": "Filter collections by beneficiary identifier",
"schema": {
"type": "string",
"format": "uuid",
"example": "01467076-8bb0-41c1-ad54-5751dd4a9e80"
}
},
{
"name": "since",
"in": "query",
"schema": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp after collection was created"
},
"example": "2025-06-17T12:00:00Z"
},
{
"name": "until",
"in": "query",
"schema": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp before collection was created"
},
"example": "2025-06-17T12:00:00Z"
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
},
"description": "Page number (starts at 1)",
"example": 1
},
{
"name": "size",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"default": 10
},
"description": "Page size (items per page)",
"example": 10
}
],
"responses": {
"200": {
"description": "A list of collections.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CollectionV1"
}
},
"page": {
"$ref": "#/components/schemas/PageMetadata"
}
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"tags": [
"Collection Links"
],
"summary": "Create a collection",
"description": "Creates a new payment link for a collection using account-based routing. The collection\nis associated with an account which determines the available payment rails and currency.\nThe amount is denominated in the account's currency.\n",
"operationId": "createCollectionV1",
"security": [
{
"Bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateCollectionRequestV1"
},
"examples": {
"example_with_excluded_fee": {
"summary": "Example for EXCLUDED fee_mode",
"value": {
"payer_id": "0c5479ff-3772-4123-b2b7-e679e71eb570",
"account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"amount": "800.00",
"fee_mode": "EXCLUDED",
"reference_id": "INV-2025-009",
"description": "Payment for Order #2668",
"link_expiry": 172800,
"return_url": "https://example.com/payment/completion"
}
},
"example_with_included_fee": {
"summary": "Example for INCLUDED fee_mode",
"value": {
"payer_id": "0c5479ff-3772-4123-b2b7-e679e71eb570",
"account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"amount": "800.00",
"fee_mode": "INCLUDED",
"reference_id": "INV-2025-009",
"description": "Payment for Order #2668",
"link_expiry": 172800,
"return_url": "https://example.com/payment/completion"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Collection Created Successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CollectionV1"
},
"examples": {
"default": {
"summary": "Example collection response",
"value": {
"id": "e8d43598-107d-4694-9fb2-934e7484c3d4",
"payer": {
"id": "0c5479ff-3772-4123-b2b7-e679e71eb570",
"name": "Nigerian Imports Ltd.",
"email": "nigerian@imports.com"
},
"beneficiary": {
"id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"name": "Hong Kong Exports Ltd.",
"email": "hongkong@exports.com"
},
"reference_id": "INV-2025-009",
"account": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"beneficiary_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"currency": "USDC",
"type": "CRYPTO"
},
"gross_amount": "808.00",
"net_amount": "800.00",
"fee_mode": "EXCLUDED",
"fee": "8.00",
"amount_remaining": "808.00",
"description": "Payment for Order #2668",
"link_expiry": 172800,
"return_url": "https://example.com/payment/completion",
"expires_at": "2025-06-30T23:59:59Z",
"payment_link": "https://collections.ripple.com/link/pay/384c5f9b",
"status": "CREATED",
"reason": null,
"created_at": "2025-06-17T12:00:00Z",
"updated_at": "2025-06-17T12:30:00Z"
}
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Forbidden - Account type not allowed for this operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Not Found - Account or payer not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/collections/links/{collection_id}": {
"get": {
"tags": [
"Collection Links"
],
"summary": "Get collection details",
"description": "Retrieves the details of a specific collection by its ID using account-based routing.",
"operationId": "getCollectionByIdV1",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "collection_id",
"in": "path",
"required": true,
"description": "Unique identifier of the collection to retrieve",
"schema": {
"type": "string",
"format": "uuid",
"example": "e8d43598-107d-4694-9fb2-934e7484c3d4"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CollectionV1"
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Not Found - Collection does not exist",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/collections/transactions": {
"get": {
"tags": [
"Transactions"
],
"summary": "List Transactions",
"description": "API to fetch transactions across collection links or channels using account-based routing.",
"operationId": "listTransactionsV1",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "id",
"in": "query",
"description": "Filter transactions by specific transaction ID",
"schema": {
"type": "string",
"format": "uuid",
"example": "63dd59dd-88be-41a2-a246-2f6724209422"
}
},
{
"name": "status",
"in": "query",
"schema": {
"$ref": "#/components/schemas/TransactionStatus"
},
"description": "Transaction status"
},
{
"name": "payer_id",
"in": "query",
"description": "Filter transactions by payer identifier",
"schema": {
"type": "string",
"format": "uuid",
"example": "e471b938-98ad-45e4-b144-53a556ea047d"
}
},
{
"name": "beneficiary_id",
"in": "query",
"description": "Filter transactions by beneficiary identifier",
"schema": {
"type": "string",
"format": "uuid",
"example": "291ecf34-a01d-466a-b0fd-662a88b7a1bb"
}
},
{
"name": "account_id",
"in": "query",
"description": "Filter transactions by account identifier",
"schema": {
"type": "string",
"format": "uuid",
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
},
{
"name": "currency",
"in": "query",
"description": "Filter transactions by transaction currency",
"schema": {
"type": "string"
},
"example": "USDT"
},
{
"name": "network",
"in": "query",
"description": "Filter transactions by transaction network",
"schema": {
"type": "string",
"$ref": "#/components/schemas/Network"
},
"example": "ETHEREUM"
},
{
"name": "wallet_address",
"in": "query",
"description": "Filter transactions by wallet address",
"schema": {
"type": "string"
},
"example": "0xBb592aaaF9AcE2fbE3F735645819FA94c95a9cb5"
},
{
"name": "since",
"in": "query",
"schema": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp after transaction was created"
},
"example": "2025-06-17T12:00:00Z"
},
{
"name": "until",
"in": "query",
"schema": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp before transaction was created"
},
"example": "2025-06-17T12:00:00Z"
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
},
"description": "Page number (starts at 1)",
"example": 1
},
{
"name": "size",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"default": 10
},
"description": "Page size (items per page)",
"example": 10
}
],
"responses": {
"200": {
"description": "A list of transactions.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TransactionV1"
}
},
"page": {
"$ref": "#/components/schemas/PageMetadata"
}
}
},
"examples": {
"default": {
"summary": "Example transaction list response",
"value": {
"content": [
{
"id": "487ba009-56cf-4ad9-8b5c-045e27893e00",
"parent_id": "22a0337b-8e62-449c-91ca-a0f830c55733",
"account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"settlement_id": "9f3e4d2c-1a5b-4c8e-9d7f-2e1a3b4c5d6e",
"payer": {
"id": "0c5479ff-3772-4123-b2b7-e679e71eb570",
"name": "Nigerian Imports Ltd.",
"email": "nigerian@imports.com"
},
"beneficiary": {
"id": "01467076-8bb0-41c1-ad54-5751dd4a9e80",
"name": "Hong Kong Exports Ltd.",
"email": "hongkong@exports.com"
},
"payment_amount": {
"value": "50.00000000",
"asset": "USDT"
},
"account_equivalent": {
"gross_amount": {
"value": "50.00",
"currency": "USD"
},
"fee_amount": {
"value": "0.50",
"currency": "USD"
},
"net_amount": {
"value": "49.50",
"currency": "USD"
}
},
"market_rate": {
"base": "USDT",
"counter": "USD",
"rate": "1.00"
},
"exchange_rate": {
"base": "USDT",
"counter": "USD",
"rate": "0.99"
},
"source_payment_method": {
"type": "BLOCKCHAIN",
"network": "ETHEREUM",
"transaction_hash": "0x94365ftfr76iy45t6ghu876567ytr54ertyui987uyt698uyh87u",
"block_id": "0xh7865gugi87yea94e8267987a9e91eddcd0da916b22f3cfa0c8bd91dbad85",
"source_address": "0x880f622a1933ACf82bFC5e630c9ab7f18eF47809",
"destination_address": "0x02937b288b588058533C48b18EdFDdd76A324D6",
"gas_fee": {
"value": "0.0045",
"asset": "ETH"
}
},
"status": "COMPLETED",
"transaction_processed_date": "2025-06-17T12:20:00Z",
"date_created": 1566203005000,
"date_confirmed": 1566203005000
}
],
"page": {
"page": 1,
"size": 10,
"total_elements": 1,
"total_pages": 1
}
}
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/collections/transactions/{transaction_id}": {
"get": {
"tags": [
"Transactions"
],
"summary": "Get transaction by ID",
"description": "API to fetch a transaction (payment from a payer to beneficiary) using account-based routing.",
"operationId": "getTransactionByIdV1",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "transaction_id",
"in": "path",
"required": true,
"description": "Unique identifier of the transaction to retrieve",
"schema": {
"type": "string",
"format": "uuid",
"example": "487ba009-56cf-4ad9-8b5c-045e27893e00"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TransactionV1"
},
"examples": {
"blockchain_transaction": {
"summary": "Example blockchain transaction response",
"value": {
"id": "487ba009-56cf-4ad9-8b5c-045e27893e00",
"parent_id": "22a0337b-8e62-449c-91ca-a0f830c55733",
"account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"settlement_id": "9f3e4d2c-1a5b-4c8e-9d7f-2e1a3b4c5d6e",
"payer": {
"id": "0c5479ff-3772-4123-b2b7-e679e71eb570",
"name": "Nigerian Imports Ltd.",
"email": "nigerian@imports.com"
},
"beneficiary": {
"id": "01467076-8bb0-41c1-ad54-5751dd4a9e80",
"name": "Hong Kong Exports Ltd.",
"email": "hongkong@exports.com"
},
"payment_amount": {
"value": "50.00000000",
"asset": "USDT"
},
"account_equivalent": {
"gross_amount": {
"value": "50.00",
"currency": "USD"
},
"fee_amount": {
"value": "0.50",
"currency": "USD"
},
"net_amount": {
"value": "49.50",
"currency": "USD"
}
},
"market_rate": {
"base": "USDT",
"counter": "USD",
"rate": "1.00"
},
"exchange_rate": {
"base": "USDT",
"counter": "USD",
"rate": "0.99"
},
"source_payment_method": {
"type": "BLOCKCHAIN",
"network": "ETHEREUM",
"transaction_hash": "0x94365ftfr76iy45t6ghu876567ytr54ertyui987uyt698uyh87u",
"block_id": "0xh7865gugi87yea94e8267987a9e91eddcd0da916b22f3cfa0c8bd91dbad85",
"source_address": "0x880f622a1933ACf82bFC5e630c9ab7f18eF47809",
"destination_address": "0x02937b288b588058533C48b18EdFDdd76A324D6",
"gas_fee": {
"value": "0.0045",
"asset": "ETH"
}
},
"status": "COMPLETED",
"transaction_processed_date": "2025-06-17T12:20:00Z",
"date_created": 1566203005000,
"date_confirmed": 1566203005000
}
},
"fiat_transaction": {
"summary": "Example fiat (PIX) transaction response",
"value": {
"id": "63dd59dd-88be-41a2-a246-2f6724209422",
"parent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"account_id": "250d6dc5-382f-4750-8657-0780be594d68",
"settlement_id": null,
"payer": {
"id": "e471b938-98ad-45e4-b144-53a556ea047d",
"name": "Brazilian Imports Ltd.",
"email": "brazil@imports.com"
},
"beneficiary": {
"id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"name": "Hong Kong Exports Ltd.",
"email": "hongkong@exports.com"
},
"payment_amount": {
"value": "1000.00",
"asset": "BRL"
},
"account_equivalent": {
"gross_amount": {
"value": "1000.00",
"currency": "BRL"
},
"fee_amount": {
"value": "10.00",
"currency": "BRL"
},
"net_amount": {
"value": "990.00",
"currency": "BRL"
}
},
"market_rate": {
"base": "BRL",
"counter": "BRL",
"rate": "1.00"
},
"exchange_rate": {
"base": "BRL",
"counter": "BRL",
"rate": "1.00"
},
"source_payment_method": {
"type": "PIX",
"pix_key": "12345678901",
"pix_key_type": "CPF",
"sender_name": "João Silva"
},
"status": "COMPLETED",
"transaction_processed_date": "2025-06-17T14:30:00Z",
"date_created": 1566203005000,
"date_confirmed": 1566203005000
}
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Not Found - Transaction does not exist",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/collections/webhooks": {
"get": {
"tags": [
"Webhooks"
],
"summary": "List webhooks",
"operationId": "listWebhooks",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "event_type",
"in": "query",
"required": true,
"description": "Unique identifier event type to filter webhooks",
"schema": {
"type": "string",
"$ref": "#/components/schemas/EventType"
}
},
{
"name": "since",
"in": "query",
"schema": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp after webhook was created"
},
"example": "2025-06-17T12:00:00Z"
},
{
"name": "until",
"in": "query",
"schema": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp before webhook was created"
},
"example": "2025-06-17T12:00:00Z"
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
},
"description": "Page number (starts at 1)",
"example": 1
},
{
"name": "size",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"default": 10
},
"description": "Page size (items per page)",
"example": 10
}
],
"responses": {
"200": {
"description": "List of webhooks for the customer and page requested",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookResponse"
}
},
"page": {
"$ref": "#/components/schemas/PageMetadata"
}
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"tags": [
"Webhooks"
],
"summary": "Create webhooks",
"description": "Creates one webhook per event type supplied.",
"operationId": "createWebhooks",
"security": [
{
"Bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWebhookRequest"
},
"examples": {
"create": {
"value": {
"callback_url": "https://webhook.partner.example/webhooks",
"event_types": [
"WALLET_ADDRESS_CREATED",
"SETTLEMENT_COMPLETED"
]
}
}
}
}
}
},
"responses": {
"201": {
"description": "Webhooks created (one per event type)",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookResponse"
}
},
"examples": {
"created": {
"value": [
{
"id": "5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10",
"event_type": "WALLET_ADDRESS_CREATED",
"callback_url": "https://webhook.partner.example/webhooks",
"signature_verification_key": "9abc1234..."
},
{
"id": "1c9fe6fd-1dd8-4e9a-8de2-7f4c89b4d210",
"event_type": "SETTLEMENT_COMPLETED",
"callback_url": "https://webhook.partner.example/webhooks",
"signature_verification_key": "1def5678..."
}
]
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/collections/webhooks/{webhook_id}": {
"get": {
"tags": [
"Webhooks"
],
"summary": "Get a webhook",
"operationId": "getWebhook",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "webhook_id",
"in": "path",
"required": true,
"description": "Unique identifier of the webhook to retrieve",
"schema": {
"type": "string",
"format": "uuid",
"example": "5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10"
}
}
],
"responses": {
"200": {
"description": "Webhook found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookResponse"
},
"examples": {
"webhook": {
"value": {
"id": "5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10",
"event_type": "WALLET_ADDRESS_CREATED",
"callback_url": "https://webhook.partner.example/webhooks",
"signature_verification_key": "04bfcabf3c3e5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8"
}
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Not Found - Webhook does not exist",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"put": {
"tags": [
"Webhooks"
],
"summary": "Update a webhook",
"operationId": "updateWebhook",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "webhook_id",
"in": "path",
"required": true,
"description": "Unique identifier of the webhook to update",
"schema": {
"type": "string",
"format": "uuid",
"example": "5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWebhookRequest"
}
}
}
},
"responses": {
"200": {
"description": "Updated webhook id",
"content": {
"application/json": {
"schema": {
"type": "object",
"$ref": "#/components/schemas/WebhookResponse"
},
"examples": {
"updated": {
"value": {
"id": "5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10",
"event_type": "WALLET_ADDRESS_CREATED",
"callback_url": "https://webhook-updated.partner.example/webhooks",
"signature_verification_key": "1dec2311..."
}
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Not Found - Webhook does not exist",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"delete": {
"tags": [
"Webhooks"
],
"summary": "Delete a webhook",
"operationId": "deleteWebhook",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "webhook_id",
"in": "path",
"required": true,
"description": "Unique identifier of the webhook to retrieve",
"schema": {
"type": "string",
"format": "uuid",
"example": "5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10"
}
}
],
"responses": {
"200": {
"description": "Deleted webhook id",
"content": {
"application/json": {
"schema": {
"type": "string",
"format": "uuid"
},
"examples": {
"deleted": {
"value": "5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10"
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Not Found - Webhook does not exist",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"Bearer": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
},
"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| UAT | `uat` | UAT environment with simulated transactions. |\n| Production | `prod` | Production environment for Ripple's internal services. |\n\n**Example**: `urn:ripplexcurrent-uat:{YOUR_TENANT_ID}`\n",
"example": "urn:ripplexcurrent-uat:{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`."
},
"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"
},
"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
}
}
},
"CreatePartnerRequest": {
"type": "object",
"description": "Request payload for creating a new partner",
"required": [
"name",
"email"
],
"properties": {
"name": {
"type": "string",
"description": "Full name of the partner organization or individual",
"example": "Nigerian Imports Ltd."
},
"email": {
"type": "string",
"description": "Email address for partner communications",
"format": "email",
"example": "nigerian@imports.com"
},
"external_reference_id": {
"type": "string",
"description": "External reference id for partner",
"example": "Ref-123"
},
"data": {
"$ref": "#/components/schemas/PartnerMetadata",
"example": {
"type": "BUSINESS",
"legal_entity": "Nigerian Imports Ltd.",
"registration_number": "RC-123456-NGR",
"registration_type": "AIIN",
"country": "NG",
"city": "Lagos Island",
"postal_code": "10010",
"address": "15 Marina Street",
"address_line_2": "Suite 200"
}
}
}
},
"UpdatePartnerRequest": {
"type": "object",
"description": "Request payload for updating an existing partner",
"properties": {
"name": {
"type": "string",
"description": "Full name of the partner organization or individual",
"example": "Nigerian Imports Ltd."
},
"email": {
"type": "string",
"description": "Email address for partner communications",
"format": "email",
"example": "nigerian@imports.com"
},
"external_reference_id": {
"type": "string",
"description": "External reference id for partner",
"example": "Ref-123"
},
"data": {
"$ref": "#/components/schemas/PartnerMetadata",
"example": {
"type": "BUSINESS",
"legal_entity": "Nigerian Imports Ltd.",
"registration_number": "RC-123456-NGR",
"registration_type": "AIIN",
"country": "NG",
"city": "Lagos Island",
"postal_code": "10010",
"address": "15 Marina Street",
"address_line_2": "Suite 200"
}
}
}
},
"PartnerV1": {
"type": "object",
"description": "Partner response",
"required": [
"id",
"name",
"email",
"status",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the partner",
"readOnly": true,
"example": "0c5479ff-3772-4123-b2b7-e679e71eb570"
},
"name": {
"type": "string",
"description": "Full name of the partner organization or individual",
"example": "Nigerian Imports Ltd."
},
"email": {
"type": "string",
"description": "Email address for partner communications",
"format": "email",
"example": "nigerian@imports.com"
},
"external_reference_id": {
"type": "string",
"description": "External reference id for partner",
"example": "Ref-123"
},
"data": {
"$ref": "#/components/schemas/PartnerMetadata",
"example": {
"type": "BUSINESS",
"legal_entity": "Nigerian Imports Ltd.",
"registration_number": "RC-123456-NGR",
"registration_type": "AIIN",
"country": "NG",
"city": "Lagos Island",
"postal_code": "10010",
"address": "15 Marina Street",
"address_line_2": "Suite 200"
}
},
"status": {
"type": "string",
"description": "Current status of the partner",
"$ref": "#/components/schemas/PartnerStatus",
"example": "PENDING"
},
"reason": {
"type": "string",
"nullable": true,
"description": "Reason for current status (if applicable)",
"example": null
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the partner was created",
"readOnly": true,
"example": "2025-09-18T22:54:00.542Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the partner was last updated",
"readOnly": true,
"example": "2025-09-18T23:54:00.542Z"
}
}
},
"PartnerType": {
"type": "string",
"description": "Partner type",
"enum": [
"BUSINESS",
"INDIVIDUAL"
],
"x-enum-descriptions": {
"BUSINESS": "Partner is a business entity",
"INDIVIDUAL": "Partner is an individual"
},
"example": "BUSINESS"
},
"PartnerMetadata": {
"type": "object",
"discriminator": {
"propertyName": "type",
"mapping": {
"BUSINESS": "#/components/schemas/BusinessMetadata",
"INDIVIDUAL": "#/components/schemas/IndividualMetadata"
}
},
"oneOf": [
{
"$ref": "#/components/schemas/BusinessMetadata"
},
{
"$ref": "#/components/schemas/IndividualMetadata"
}
]
},
"BusinessMetadata": {
"type": "object",
"description": "Metadata specific to business partners",
"required": [
"type",
"legal_entity",
"registration_number",
"registration_type",
"country",
"address"
],
"properties": {
"type": {
"type": "string",
"enum": [
"BUSINESS"
],
"description": "Discriminator: indicates this is business metadata"
},
"legal_entity": {
"type": "string",
"description": "Legal name of the business entity",
"example": "Nigerian Imports Ltd."
},
"registration_number": {
"type": "string",
"description": "Business registration number",
"example": "RC-123456-NGR"
},
"registration_type": {
"$ref": "#/components/schemas/RegistrationType"
},
"country": {
"type": "string",
"description": "Country where the business is registered",
"example": "NG"
},
"city": {
"type": "string",
"description": "City where the business is located",
"example": "Lagos Island"
},
"postal_code": {
"type": "string",
"description": "Postal code of the business address",
"example": "10010"
},
"address": {
"type": "string",
"description": "Primary address of the business",
"example": "15 Marina Street"
},
"address_line_2": {
"type": "string",
"description": "Secondary address line",
"example": "Suite 200"
}
}
},
"RegistrationType": {
"type": "string",
"description": "Business registration/identification type",
"enum": [
"AIIN",
"BANK",
"BOID",
"CBID",
"CHID",
"CINC",
"COID",
"CUST",
"DUNS",
"EMPL",
"GS1G",
"SREN",
"SRET",
"TXID",
"USCC"
],
"x-enum-descriptions": {
"AIIN": "Issuer Identification Number",
"BANK": "Bank Party Identification",
"BOID": "BusinessOtherIdentification",
"CBID": "Central Bank Identification Number",
"CHID": "Clearing Identification Number",
"CINC": "Certificate Of Incorporation Number",
"COID": "Country Identification Code",
"CUST": "Customer Number",
"DUNS": "Data Universal Numbering System",
"EMPL": "Employer Identification Number",
"GS1G": "GS1GLN Identifier",
"SREN": "SIREN",
"SRET": "SIRET",
"TXID": "Tax Identification Number",
"USCC": "Unified Social Credit Code"
},
"example": "AIIN"
},
"IndividualMetadata": {
"type": "object",
"description": "Metadata specific to individual partners",
"required": [
"type",
"first_name",
"last_name",
"date_of_birth",
"country",
"address",
"identification_number",
"identification_type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"INDIVIDUAL"
],
"description": "Discriminator: indicates this is individual metadata"
},
"first_name": {
"type": "string",
"description": "First name of the individual",
"example": "John"
},
"last_name": {
"type": "string",
"description": "Last name of the individual",
"example": "Doe"
},
"date_of_birth": {
"type": "string",
"format": "date",
"description": "Date of birth of the individual",
"example": "1990-05-15"
},
"identification_number": {
"type": "string",
"description": "Identification number of the individual"
},
"identification_type": {
"$ref": "#/components/schemas/IdentificationType"
},
"country": {
"type": "string",
"description": "Country of residence",
"example": "United States"
},
"city": {
"type": "string",
"description": "City of residence",
"example": "New York"
},
"postal_code": {
"type": "string",
"description": "Postal code of residence",
"example": "10001"
},
"address": {
"type": "string",
"description": "Primary address of residence",
"example": "123 Main Street"
},
"address_line_2": {
"type": "string",
"description": "Secondary address line",
"example": "Suite 200"
}
}
},
"IdentificationType": {
"type": "string",
"description": "Identification type for the individual identifier",
"enum": [
"AIIN",
"ARNU",
"CCPT",
"DRLC",
"NIDN",
"POID",
"SOS",
"TXID"
],
"x-enum-descriptions": {
"AIIN": "Issuer Identification Number",
"ARNU": "Alien Registration Number",
"CCPT": "Passport Number",
"DRLC": "Driver's License Number",
"NIDN": "National Identity Number",
"POID": "PersonCommercialIdentification",
"SOS": "Social Security Number",
"TXID": "Tax Identification Number"
},
"example": "CCPT"
},
"PartnerStatus": {
"type": "string",
"description": "Partner status for collection links or channels",
"enum": [
"PENDING",
"ON_HOLD",
"FAILED",
"ACTIVATED",
"DEACTIVATED"
],
"x-enum-descriptions": {
"PENDING": "Partner is pending review",
"ON_HOLD": "Partner is on hold due to review",
"FAILED": "Partner has failed review",
"ACTIVATED": "Partner hs been activated",
"DEACTIVATED": "Partner has been deactivated"
},
"example": "PENDING"
},
"AccountType": {
"type": "string",
"description": "Type of account",
"enum": [
"CRYPTO",
"FIAT"
],
"x-enum-descriptions": {
"CRYPTO": "Cryptocurrency account with blockchain wallet addresses",
"FIAT": "Fiat currency account with bank deposit instructions"
},
"example": "CRYPTO"
},
"AccountStatus": {
"type": "string",
"description": "Status of the account",
"enum": [
"PENDING",
"ACTIVE",
"INACTIVE",
"CLOSED"
],
"x-enum-descriptions": {
"PENDING": "Account is pending activation",
"ACTIVE": "Account is active and ready to receive funds",
"INACTIVE": "Account is temporarily inactive",
"CLOSED": "Account has been closed"
},
"example": "ACTIVE"
},
"RailType": {
"type": "string",
"description": "Type of payment rail",
"enum": [
"BLOCKCHAIN",
"FEDWIRE",
"ACH",
"RTP",
"PIX"
],
"x-enum-descriptions": {
"BLOCKCHAIN": "Blockchain network for cryptocurrency payments",
"FEDWIRE": "Federal Reserve Wire Network (USD)",
"ACH": "Automated Clearing House (USD)",
"RTP": "Real-Time Payments (USD)",
"PIX": "Brazilian instant payment system (BRL)"
},
"example": "BLOCKCHAIN"
},
"Rail": {
"type": "object",
"description": "Payment rail with deposit instructions",
"discriminator": {
"propertyName": "type",
"mapping": {
"BLOCKCHAIN": "#/components/schemas/BlockchainRail",
"FEDWIRE": "#/components/schemas/FedwireRail",
"ACH": "#/components/schemas/AchRail",
"RTP": "#/components/schemas/RtpRail",
"PIX": "#/components/schemas/PixRail"
}
},
"oneOf": [
{
"$ref": "#/components/schemas/BlockchainRail"
},
{
"$ref": "#/components/schemas/FedwireRail"
},
{
"$ref": "#/components/schemas/AchRail"
},
{
"$ref": "#/components/schemas/RtpRail"
},
{
"$ref": "#/components/schemas/PixRail"
}
]
},
"BlockchainRail": {
"type": "object",
"description": "Blockchain payment rail with network details",
"required": [
"type",
"network",
"address",
"currency"
],
"properties": {
"type": {
"type": "string",
"enum": [
"BLOCKCHAIN"
],
"description": "Discriminator: indicates blockchain rail"
},
"network": {
"$ref": "#/components/schemas/Network"
},
"address": {
"type": "string",
"description": "Blockchain wallet address for receiving funds",
"example": "0xBb592aaaF9AcE2fbE3F735645819FA94c95a9cb5"
},
"currency": {
"type": "string",
"description": "Cryptocurrency asset symbol",
"example": "USDC"
}
}
},
"FedwireRail": {
"type": "object",
"description": "Fedwire payment rail for USD wire transfers",
"required": [
"type",
"account_number",
"routing_number"
],
"properties": {
"type": {
"type": "string",
"enum": [
"FEDWIRE"
],
"description": "Discriminator: indicates Fedwire rail"
},
"account_number": {
"type": "string",
"description": "Bank account number",
"example": "1234567890"
},
"routing_number": {
"type": "string",
"description": "ABA routing number",
"example": "021000021"
},
"swift_code": {
"type": "string",
"description": "SWIFT/BIC code for international transfers",
"example": "CHASUS33"
},
"memo": {
"type": "string",
"description": "Reference memo to include with the transfer",
"example": "ACC-123456"
}
}
},
"AchRail": {
"type": "object",
"description": "ACH payment rail for USD domestic transfers",
"required": [
"type",
"account_number",
"routing_number"
],
"properties": {
"type": {
"type": "string",
"enum": [
"ACH"
],
"description": "Discriminator: indicates ACH rail"
},
"account_number": {
"type": "string",
"description": "Bank account number",
"example": "1234567890"
},
"routing_number": {
"type": "string",
"description": "ABA routing number",
"example": "021000021"
},
"swift_code": {
"type": "string",
"description": "SWIFT/BIC code (optional for ACH)",
"example": "CHASUS33"
},
"memo": {
"type": "string",
"description": "Reference memo to include with the transfer",
"example": "ACC-123456"
}
}
},
"RtpRail": {
"type": "object",
"description": "RTP (Real-Time Payments) rail for instant USD transfers",
"required": [
"type",
"account_number",
"routing_number"
],
"properties": {
"type": {
"type": "string",
"enum": [
"RTP"
],
"description": "Discriminator: indicates RTP rail"
},
"account_number": {
"type": "string",
"description": "Bank account number",
"example": "1234567890"
},
"routing_number": {
"type": "string",
"description": "ABA routing number",
"example": "021000021"
},
"swift_code": {
"type": "string",
"description": "SWIFT/BIC code (optional for RTP)",
"example": "CHASUS33"
},
"memo": {
"type": "string",
"description": "Reference memo to include with the transfer",
"example": "ACC-123456"
}
}
},
"PixRail": {
"type": "object",
"description": "PIX payment rail for instant BRL transfers in Brazil",
"required": [
"type",
"pix_key",
"pix_key_type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"PIX"
],
"description": "Discriminator: indicates PIX rail"
},
"pix_key": {
"type": "string",
"description": "PIX key for receiving payments",
"example": "12345678901"
},
"pix_key_type": {
"type": "string",
"description": "Type of PIX key",
"enum": [
"CPF",
"CNPJ",
"EMAIL",
"PHONE",
"RANDOM"
],
"example": "CPF"
},
"beneficiary_name": {
"type": "string",
"description": "Name of the beneficiary as registered with PIX",
"example": "Empresa ABC Ltda"
}
}
},
"SourcePaymentMethod": {
"type": "object",
"description": "Source payment method details for a transaction",
"discriminator": {
"propertyName": "type",
"mapping": {
"BLOCKCHAIN": "#/components/schemas/BlockchainSourcePaymentMethod",
"FEDWIRE": "#/components/schemas/FedwireSourcePaymentMethod",
"ACH": "#/components/schemas/AchSourcePaymentMethod",
"RTP": "#/components/schemas/RtpSourcePaymentMethod",
"PIX": "#/components/schemas/PixSourcePaymentMethod"
}
},
"oneOf": [
{
"$ref": "#/components/schemas/BlockchainSourcePaymentMethod"
},
{
"$ref": "#/components/schemas/FedwireSourcePaymentMethod"
},
{
"$ref": "#/components/schemas/AchSourcePaymentMethod"
},
{
"$ref": "#/components/schemas/RtpSourcePaymentMethod"
},
{
"$ref": "#/components/schemas/PixSourcePaymentMethod"
}
]
},
"BlockchainSourcePaymentMethod": {
"type": "object",
"description": "Blockchain/crypto source payment method with on-chain transaction details",
"required": [
"type",
"network",
"transaction_hash",
"block_id",
"source_address",
"destination_address",
"gas_fee"
],
"properties": {
"type": {
"type": "string",
"enum": [
"BLOCKCHAIN"
],
"description": "Discriminator: indicates blockchain payment method"
},
"network": {
"$ref": "#/components/schemas/Network"
},
"transaction_hash": {
"type": "string",
"description": "Blockchain transaction hash",
"example": "0x94365ftfr76iy45t6ghu876567ytr54ertyui987uyt698uyh87u"
},
"block_id": {
"type": "string",
"description": "Blockchain block identifier containing this transaction",
"example": "0xh7865gugi87yea94e8267987a9e91eddcd0da916b22f3cfa0c8bd91dbad85"
},
"source_address": {
"type": "string",
"description": "Blockchain address from which funds were sent",
"example": "0x880f622a1933ACf82bFC5e630c9ab7f18eF47809"
},
"destination_address": {
"type": "string",
"description": "Blockchain address to which funds were sent",
"example": "0x02937b288b588058533C48b18EdFDdd76A324D6"
},
"gas_fee": {
"type": "object",
"description": "Blockchain gas fee details",
"properties": {
"value": {
"type": "string",
"description": "Gas fee value",
"example": "0.0045"
},
"asset": {
"type": "string",
"description": "Asset used to pay gas fee",
"example": "ETH"
}
}
}
}
},
"FedwireSourcePaymentMethod": {
"type": "object",
"description": "Fedwire source payment method for USD wire transfers",
"required": [
"type",
"account_number",
"routing_number"
],
"properties": {
"type": {
"type": "string",
"enum": [
"FEDWIRE"
],
"description": "Discriminator: indicates Fedwire payment method"
},
"account_number": {
"type": "string",
"description": "Source bank account number",
"example": "1234567890"
},
"routing_number": {
"type": "string",
"description": "ABA routing number",
"example": "021000021"
},
"swift_code": {
"type": "string",
"description": "SWIFT/BIC code for international transfers",
"example": "CHASUS33"
},
"memo": {
"type": "string",
"description": "Reference memo included with the transfer",
"example": "Payment for invoice INV-2024-001"
}
}
},
"AchSourcePaymentMethod": {
"type": "object",
"description": "ACH source payment method for USD domestic transfers",
"required": [
"type",
"account_number",
"routing_number"
],
"properties": {
"type": {
"type": "string",
"enum": [
"ACH"
],
"description": "Discriminator: indicates ACH payment method"
},
"account_number": {
"type": "string",
"description": "Source bank account number",
"example": "1234567890"
},
"routing_number": {
"type": "string",
"description": "ABA routing number",
"example": "021000021"
},
"swift_code": {
"type": "string",
"description": "SWIFT/BIC code (optional for ACH)",
"example": "CHASUS33"
},
"memo": {
"type": "string",
"description": "Reference memo included with the transfer",
"example": "Payment for invoice INV-2024-001"
}
}
},
"RtpSourcePaymentMethod": {
"type": "object",
"description": "RTP (Real-Time Payments) source payment method for instant USD transfers",
"required": [
"type",
"account_number",
"routing_number"
],
"properties": {
"type": {
"type": "string",
"enum": [
"RTP"
],
"description": "Discriminator: indicates RTP payment method"
},
"account_number": {
"type": "string",
"description": "Source bank account number",
"example": "1234567890"
},
"routing_number": {
"type": "string",
"description": "ABA routing number",
"example": "021000021"
},
"swift_code": {
"type": "string",
"description": "SWIFT/BIC code (optional for RTP)",
"example": "CHASUS33"
},
"memo": {
"type": "string",
"description": "Reference memo included with the transfer",
"example": "Payment for invoice INV-2024-001"
}
}
},
"PixSourcePaymentMethod": {
"type": "object",
"description": "PIX source payment method for instant BRL transfers in Brazil",
"required": [
"type",
"pix_key",
"pix_key_type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"PIX"
],
"description": "Discriminator: indicates PIX payment method"
},
"pix_key": {
"type": "string",
"description": "PIX key used for the payment",
"example": "12345678901"
},
"pix_key_type": {
"type": "string",
"description": "Type of PIX key",
"enum": [
"CPF",
"CNPJ",
"EMAIL",
"PHONE",
"RANDOM"
],
"example": "CPF"
},
"sender_name": {
"type": "string",
"description": "Name of the sender as registered with PIX",
"example": "João Silva"
}
}
},
"CreateAccountRequest": {
"type": "object",
"description": "Request payload for creating a new account",
"required": [
"beneficiary_id",
"currency"
],
"properties": {
"beneficiary_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the beneficiary partner who will own this account",
"example": "291ecf34-a01d-466a-b0fd-662a88b7a1bb"
},
"currency": {
"type": "string",
"description": "Currency for the account (crypto: RLUSD, USDC, USDT or fiat: USD, BRL)",
"example": "USD"
}
}
},
"Account": {
"type": "object",
"description": "Account for receiving payments with associated rails",
"required": [
"id",
"account_owner_id",
"currency",
"type",
"rails",
"balances",
"ownership_level",
"status",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the account",
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"account_owner_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the account owner can be customer or partner",
"example": "291ecf34-a01d-466a-b0fd-662a88b7a1bb"
},
"currency": {
"type": "string",
"description": "Currency for the account",
"example": "USD"
},
"type": {
"$ref": "#/components/schemas/AccountType"
},
"rails": {
"type": "array",
"description": "Available payment rail types for this account",
"items": {
"$ref": "#/components/schemas/RailType"
}
},
"balances": {
"type": "object",
"description": "Account balance information",
"required": [
"available",
"pending"
],
"properties": {
"available": {
"type": "object",
"description": "Available balance that can be withdrawn or used",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "string",
"description": "Available balance amount as a string to preserve precision",
"example": "1250.50"
}
}
},
"pending": {
"type": "object",
"description": "Pending balance information",
"required": [
"inbound",
"outbound"
],
"properties": {
"inbound": {
"type": "object",
"description": "Pending inbound balance",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "string",
"description": "Pending inbound amount as a string to preserve precision",
"example": "50.00"
}
}
},
"outbound": {
"type": "object",
"description": "Pending outbound balance",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "string",
"description": "Pending outbound amount as a string to preserve precision",
"example": "25.00"
}
}
}
}
}
}
},
"ownership_level": {
"type": "string",
"description": "Indicates whether this account is owned at the partner or customer level",
"enum": [
"PARTNER",
"CUSTOMER"
],
"x-enum-descriptions": {
"PARTNER": "Account owned by a specific partner (beneficiary). Funds in this account are moved to a customer-level accounts for the same currency.",
"CUSTOMER": "Account owned at the customer level. Eligible for settlement and receiving funds from partner accounts."
},
"example": "PARTNER"
},
"status": {
"$ref": "#/components/schemas/AccountStatus"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp when the account was created",
"example": "2025-09-18T22:54:00.542Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp when the account was last updated",
"example": "2025-09-18T22:54:00.542Z"
}
}
},
"CollectionStatus": {
"type": "string",
"description": "The status of the collection",
"enum": [
"CREATED",
"CLOSED",
"HOLD",
"EXPIRED",
"PENDING",
"PROCESSING",
"COMPLETED",
"UNDERPAID",
"OVERPAID",
"CANCELLED"
],
"x-enum-descriptions": {
"CREATED": "Collection has been created",
"CLOSED": "Collection has been closed",
"HOLD": "Collection is on hold",
"EXPIRED": "Collection has expired",
"PENDING": "Collection is pending",
"PROCESSING": "Collection is being processed",
"COMPLETED": "Collection has been completed",
"UNDERPAID": "Collection has been underpaid",
"OVERPAID": "Collection has been overpaid",
"CANCELLED": "Collection has been cancelled"
},
"example": "PENDING"
},
"FeeMode": {
"type": "string",
"description": "How fees are handled in the collection",
"enum": [
"INCLUDED",
"EXCLUDED"
],
"x-enum-descriptions": {
"INCLUDED": "Fee is included in the collection net amount based on the receiving currency specified by the user",
"EXCLUDED": "Fee is excluded from the collection net amount based on the receiving currency specified by the user"
},
"example": "EXCLUDED"
},
"TransactionV1": {
"type": "object",
"description": "Transaction details",
"required": [
"id",
"parent_id",
"account_id",
"payer",
"beneficiary",
"payment_amount",
"account_equivalent",
"market_rate",
"exchange_rate",
"source_payment_method",
"status",
"transaction_processed_date",
"date_created",
"date_confirmed"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the transaction",
"example": "487ba009-56cf-4ad9-8b5c-045e27893e00"
},
"parent_id": {
"type": "string",
"format": "uuid",
"description": "Identifier of the parent entity (collection link or channel) for this transaction",
"example": "e8d43598-107d-4694-9fb2-934e7484c3d4"
},
"account_id": {
"type": "string",
"format": "uuid",
"description": "Identifier of the account associated with this transaction",
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"settlement_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Identifier of the settlement associated with this transaction. Null if the transaction has not been included in a settlement yet.",
"example": "9f3e4d2c-1a5b-4c8e-9d7f-2e1a3b4c5d6e"
},
"payer": {
"type": "object",
"description": "Payer partner details",
"required": [
"id",
"name",
"email"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the payer partner",
"example": "0c5479ff-3772-4123-b2b7-e679e71eb570"
},
"name": {
"type": "string",
"description": "Full name of the payer partner",
"example": "Nigerian Imports Ltd."
},
"email": {
"type": "string",
"description": "Email address of the payer partner",
"format": "email",
"example": "nigerian@imports.com"
}
}
},
"beneficiary": {
"type": "object",
"description": "Beneficiary partner details",
"required": [
"id",
"name",
"email"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the beneficiary partner",
"example": "01467076-8bb0-41c1-ad54-5751dd4a9e80"
},
"name": {
"type": "string",
"description": "Full name of the beneficiary partner",
"example": "Hong Kong Exports Ltd."
},
"email": {
"type": "string",
"description": "Email address of the beneficiary partner",
"format": "email",
"example": "hongkong@exports.com"
}
}
},
"payment_amount": {
"type": "object",
"description": "Payment amount and asset",
"required": [
"value",
"asset"
],
"properties": {
"value": {
"type": "string",
"description": "Payment amount as a string to preserve precision",
"example": "50.00000000"
},
"asset": {
"type": "string",
"description": "Asset symbol of the payment",
"example": "USDT"
}
}
},
"account_equivalent": {
"type": "object",
"description": "Account equivalent amounts for payment, fee, and net (converted to account's native currency)",
"required": [
"gross_amount",
"fee_amount",
"net_amount"
],
"properties": {
"gross_amount": {
"type": "object",
"required": [
"value",
"currency"
],
"properties": {
"value": {
"type": "string",
"description": "Gross amount in account currency",
"example": "50.00"
},
"currency": {
"type": "string",
"description": "Account currency code",
"example": "USD"
}
}
},
"fee_amount": {
"type": "object",
"required": [
"value",
"currency"
],
"properties": {
"value": {
"type": "string",
"description": "Fee amount in account currency",
"example": "0.50"
},
"currency": {
"type": "string",
"description": "Account currency code",
"example": "USD"
}
}
},
"net_amount": {
"type": "object",
"required": [
"value",
"currency"
],
"properties": {
"value": {
"type": "string",
"description": "Net amount in account currency",
"example": "49.50"
},
"currency": {
"type": "string",
"description": "Account currency code",
"example": "USD"
}
}
}
}
},
"market_rate": {
"type": "object",
"description": "Market rate reference for the transaction",
"properties": {
"base": {
"type": "string",
"description": "Base currency for the exchange rate",
"example": "USDT"
},
"counter": {
"type": "string",
"description": "Counter currency for the exchange rate",
"example": "USD"
},
"rate": {
"type": "string",
"description": "Exchange rate from base to counter currency",
"example": "1.00"
}
}
},
"exchange_rate": {
"type": "object",
"description": "Exchange rate applied on the transaction",
"properties": {
"base": {
"type": "string",
"description": "Base currency for the exchange rate",
"example": "USDT"
},
"counter": {
"type": "string",
"description": "Counter currency for the exchange rate",
"example": "USD"
},
"rate": {
"type": "string",
"description": "Exchange rate from base to counter currency",
"example": "0.99"
}
}
},
"source_payment_method": {
"$ref": "#/components/schemas/SourcePaymentMethod"
},
"status": {
"$ref": "#/components/schemas/TransactionStatus"
},
"reason": {
"type": "string",
"nullable": true,
"description": "Reason for current status (if applicable)",
"example": null
},
"transaction_processed_date": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of the transaction",
"example": "2025-06-17T12:20:00Z"
},
"date_created": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (milliseconds) when transaction was created",
"example": 1566203005000
},
"date_confirmed": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (milliseconds) when transaction was confirmed",
"example": 1566203005000
}
}
},
"TransactionStatus": {
"type": "string",
"description": "Transaction status",
"enum": [
"COMPLETED",
"FAILED_KYT",
"FAILED",
"HOLD_KYT",
"REFUNDED_KYT",
"PROCESSING"
],
"x-enum-descriptions": {
"COMPLETED": "Funds have been successfully converted into the desired currency",
"HOLD_KYT": "Funds have been held for our KYT checks",
"FAILED_KYT": "Funds have failed our KYT checks",
"REFUNDED_KYT": "Funds have been refunded based on our kyt checks",
"PROCESSING": "Funds are settled and being processed in our system",
"FAILED": "Funds have failed transaction processing and will not be settled"
},
"example": "COMPLETED"
},
"SettlementType": {
"type": "string",
"description": "Settlement type",
"enum": [
"FIAT",
"CRYPTO"
],
"x-enum-descriptions": {
"FIAT": "Settlement of fiat currency",
"CRYPTO": "Settlement of crypto currency"
},
"example": "FIAT"
},
"SettlementStatus": {
"type": "string",
"description": "Settlement status",
"enum": [
"PENDING",
"PROCESSING",
"COMPLETED",
"FAILED",
"CANCELLED"
],
"x-enum-descriptions": {
"PENDING": "Settlement is pending",
"PROCESSING": "Settlement is being processed",
"COMPLETED": "Settlement has been completed",
"FAILED": "Settlement has failed",
"CANCELLED": "Settlement has been cancelled"
},
"example": "PENDING"
},
"SettlementAccountDetails": {
"type": "object",
"description": "Account details for settlement transactions",
"required": [
"account_holder",
"institution_name",
"account_number",
"routing_number"
],
"properties": {
"account_holder": {
"type": "string",
"description": "Full name of the account holder",
"example": "John Doe"
},
"institution_name": {
"type": "string",
"description": "Name of the financial institution",
"example": "Bank of America"
},
"account_number": {
"type": "string",
"description": "Account number for the settlement",
"example": "XXXX6789"
},
"routing_number": {
"type": "string",
"description": "Routing number for the financial institution",
"example": "XXXX4321"
}
}
},
"FiatSettlementDataV1": {
"type": "object",
"description": "Settlement data for fiat settlements",
"required": [
"type",
"sending_account",
"receiving_account"
],
"properties": {
"type": {
"type": "string",
"enum": [
"FIAT"
],
"description": "Discriminator for fiat settlement data",
"example": "FIAT"
},
"sending_account": {
"$ref": "#/components/schemas/SettlementAccountDetails"
},
"receiving_account": {
"$ref": "#/components/schemas/SettlementAccountDetails"
},
"transaction_reference_numbers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Bank reference numbers for the settlement transaction",
"example": [
"ABC12345"
]
},
"description": {
"type": "string",
"description": "Human-readable description of the settlement",
"example": "Monthly Payout"
}
}
},
"CryptoSettlementDataV1": {
"type": "object",
"description": "Settlement data for crypto settlements",
"required": [
"type",
"network",
"transaction_hash",
"block_id",
"source_address",
"destination_address",
"gas_fee"
],
"properties": {
"type": {
"type": "string",
"enum": [
"CRYPTO"
],
"description": "Discriminator for crypto settlement data",
"example": "CRYPTO"
},
"network": {
"$ref": "#/components/schemas/Network"
},
"transaction_hash": {
"type": "string",
"description": "Blockchain transaction hash",
"example": "0x94365ftfr76iy45t6ghu876567ytr54ertyui987uyt698uyh87u"
},
"block_id": {
"type": "string",
"description": "Blockchain block identifier containing this transaction",
"example": "0xh7865gugi87yea94e8267987a9e91eddcd0da916b22f3cfa0c8bd91dbad85"
},
"source_address": {
"type": "string",
"description": "Blockchain address from which funds were sent",
"example": "0x880f622a1933ACf82bFC5e630c9ab7f18eF47809"
},
"destination_address": {
"type": "string",
"description": "Blockchain address to which funds were sent",
"example": "0x02937b288b588058533C48b18EdFDdd76A324D6"
},
"gas_fee": {
"type": "object",
"description": "Blockchain gas fee details",
"required": [
"value",
"asset"
],
"properties": {
"value": {
"type": "string",
"description": "Gas fee value",
"example": "0.0045"
},
"asset": {
"type": "string",
"description": "Asset used to pay gas fee",
"example": "ETH"
}
}
}
}
},
"SettlementDataV1": {
"description": "Settlement data - varies based on settlement type (FIAT or CRYPTO)",
"oneOf": [
{
"$ref": "#/components/schemas/FiatSettlementDataV1"
},
{
"$ref": "#/components/schemas/CryptoSettlementDataV1"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"FIAT": "#/components/schemas/FiatSettlementDataV1",
"CRYPTO": "#/components/schemas/CryptoSettlementDataV1"
}
}
},
"SettlementTransactionV1": {
"type": "object",
"description": "Settlement transaction details",
"required": [
"id",
"account_id",
"amount"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the settlement transaction",
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"account_id": {
"type": "string",
"format": "uuid",
"description": "Account ID associated with this settlement transaction",
"example": "f9e8d7c6-b5a4-3210-fedc-ba0987654321"
},
"market_rate": {
"type": "object",
"description": "Market rate at the time of settlement",
"properties": {
"base": {
"type": "string",
"description": "Base currency for the exchange rate",
"example": "USDC"
},
"counter": {
"type": "string",
"description": "Counter currency for the exchange rate",
"example": "USD"
},
"rate": {
"type": "string",
"description": "Exchange rate from base to counter currency",
"example": "1.00"
}
}
},
"exchange_rate": {
"type": "object",
"description": "Exchange rate from base to counter currency",
"properties": {
"base": {
"type": "string",
"description": "Base currency for the exchange rate",
"example": "USDC"
},
"counter": {
"type": "string",
"description": "Counter currency for the exchange rate",
"example": "USD"
},
"rate": {
"type": "string",
"description": "Exchange rate from base to counter currency",
"example": "0.99"
}
}
},
"amount": {
"type": "string",
"pattern": "^[0-9]+(\\.[0-9]{1,8})?$",
"example": "49.50"
}
}
},
"CreateSettlementRequestV1": {
"type": "object",
"description": "Request to create a new settlement",
"required": [
"source_account_id",
"amount",
"currency"
],
"properties": {
"source_account_id": {
"type": "string",
"format": "uuid",
"description": "Source customer account ID for the settlement",
"example": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
},
"amount": {
"type": "string",
"description": "Amount for the settlement",
"example": "100.00"
},
"currency": {
"type": "string",
"description": "Currency for the settlement",
"example": "USD"
},
"network": {
"type": "string",
"description": "Network for crypto settlements (only applicable when type is CRYPTO)"
}
}
},
"SettlementV1": {
"type": "object",
"description": "Complete settlement information",
"required": [
"id",
"type",
"currency",
"gross_amount",
"settlement_amount",
"fees",
"status",
"data",
"settlement_transactions"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the settlement",
"example": "63dd59dd-88be-41a2-a246-2f6724209422"
},
"type": {
"$ref": "#/components/schemas/SettlementType"
},
"currency": {
"type": "string",
"description": "Currency code for the settlement",
"example": "USD"
},
"gross_amount": {
"type": "string",
"description": "Total settlement amount before fees",
"example": "50.00"
},
"settlement_amount": {
"type": "string",
"description": "Net settlement amount after fees",
"example": "49.50"
},
"fees": {
"type": "object",
"description": "Settlement fees",
"properties": {
"transaction_fees": {
"type": "string",
"description": "Total fees applied to the settlement",
"example": "0.50"
}
}
},
"status": {
"$ref": "#/components/schemas/SettlementStatus"
},
"data": {
"$ref": "#/components/schemas/SettlementDataV1"
},
"settlement_transactions": {
"type": "array",
"description": "List of settlement transactions",
"items": {
"$ref": "#/components/schemas/SettlementTransactionV1"
}
}
}
},
"ChannelStatus": {
"type": "string",
"description": "Status of the channel",
"enum": [
"ACTIVE",
"INACTIVE",
"CLOSED"
],
"x-enum-descriptions": {
"ACTIVE": "Channel is active",
"INACTIVE": "Channel is inactive",
"CLOSED": "Channel is closed"
},
"example": "ACTIVE"
},
"CreateChannelRequestV1": {
"type": "object",
"description": "Request payload for creating a new channel using account-based routing",
"required": [
"payer_id",
"account_id"
],
"properties": {
"payer_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the payer partner",
"example": "e471b938-98ad-45e4-b144-53a556ea047d"
},
"account_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the account to receive funds",
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"payment_currencies": {
"type": "array",
"description": "List of currencies accepted for payment on this channel. If not specified, defaults to the account's supported currencies.",
"items": {
"type": "string",
"enum": [
"USD",
"BRL",
"USDT",
"USDC",
"RLUSD"
]
},
"example": [
"USD",
"USDC"
]
}
}
},
"ChannelV1": {
"type": "object",
"description": "Channel information with account-based routing",
"required": [
"id",
"payer",
"beneficiary",
"account",
"payment_methods",
"payment_link",
"status",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the channel",
"example": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"payer": {
"type": "object",
"description": "Payer partner details",
"required": [
"id",
"name",
"email"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the payer partner",
"example": "e471b938-98ad-45e4-b144-53a556ea047d"
},
"name": {
"type": "string",
"description": "Full name of the payer partner",
"example": "Nigerian Imports Ltd."
},
"email": {
"type": "string",
"format": "email",
"description": "Email address of the payer partner",
"example": "nigerian@imports.com"
}
}
},
"beneficiary": {
"type": "object",
"description": "Beneficiary partner details",
"required": [
"id",
"name",
"email"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the beneficiary partner",
"example": "01467076-8bb0-41c1-ad54-5751dd4a9e80"
},
"name": {
"type": "string",
"description": "Full name of the beneficiary partner",
"example": "Hong Kong Exports Ltd."
},
"email": {
"type": "string",
"description": "Email address of the beneficiary partner",
"format": "email",
"example": "hongkong@exports.com"
}
}
},
"account": {
"type": "object",
"description": "Account associated to this channel, which funds will be routed to",
"required": [
"id",
"beneficiary_id",
"currency",
"type"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the account",
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"beneficiary_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the beneficiary partner",
"example": "291ecf34-a01d-466a-b0fd-662a88b7a1bb"
},
"currency": {
"type": "string",
"description": "Currency for the account",
"example": "USD"
},
"type": {
"type": "string",
"description": "Type of account",
"enum": [
"FIAT",
"CRYPTO"
],
"example": "FIAT"
}
}
},
"payment_methods": {
"type": "array",
"description": "Available payment methods with full deposit instructions",
"items": {
"$ref": "#/components/schemas/Rail"
}
},
"payment_link": {
"type": "string",
"format": "uri",
"description": "URL for payer UI to access this channel",
"example": "https://collections.ripplenet.com/pay/channel/3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"status": {
"$ref": "#/components/schemas/ChannelStatus"
},
"reason": {
"type": "string",
"nullable": true,
"description": "Reason for current status (if applicable)",
"example": null
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp when the channel was created",
"example": "2025-09-18T22:54:00.542Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp when the channel was last updated",
"example": "2025-09-18T22:54:00.542Z"
}
}
},
"CreateCollectionRequestV1": {
"type": "object",
"description": "Request payload for creating a new collection using account-based routing",
"required": [
"payer_id",
"account_id",
"amount",
"link_expiry",
"return_url"
],
"properties": {
"payer_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the payer partner",
"example": "0c5479ff-3772-4123-b2b7-e679e71eb570"
},
"account_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the account to receive funds",
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"amount": {
"type": "string",
"description": "Collection amount as a string to preserve precision",
"pattern": "^[0-9]+(\\.[0-9]{1,8})?$",
"example": "800.00"
},
"fee_mode": {
"allOf": [
{
"$ref": "#/components/schemas/FeeMode"
}
],
"default": "EXCLUDED"
},
"reference_id": {
"type": "string",
"description": "External reference identifier for the collection",
"example": "INV-2025-009"
},
"description": {
"type": "string",
"description": "Human-readable description of the collection purpose",
"example": "Payment for Order #2668"
},
"link_expiry": {
"type": "integer",
"description": "Payment link expiry time in seconds from creation",
"minimum": 300,
"maximum": 2592000,
"example": 172800
},
"return_url": {
"type": "string",
"format": "uri",
"description": "URL to redirect user after payment completion",
"example": "https://example.com/payment/completion"
}
}
},
"CollectionV1": {
"type": "object",
"description": "Collection information with account-based routing",
"required": [
"id",
"payer",
"beneficiary",
"account",
"gross_amount",
"net_amount",
"fee_mode",
"fee",
"amount_remaining",
"description",
"link_expiry",
"return_url",
"expires_at",
"status",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the collection",
"example": "e8d43598-107d-4694-9fb2-934e7484c3d4"
},
"payer": {
"type": "object",
"description": "Payer partner details",
"required": [
"id",
"name",
"email"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the payer partner",
"example": "0c5479ff-3772-4123-b2b7-e679e71eb570"
},
"name": {
"type": "string",
"description": "Full name of the payer partner",
"example": "Nigerian Imports Ltd."
},
"email": {
"type": "string",
"description": "Email address of the payer partner",
"format": "email",
"example": "nigerian@imports.com"
}
}
},
"beneficiary": {
"type": "object",
"description": "Beneficiary partner details",
"required": [
"id",
"name",
"email"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the beneficiary partner",
"example": "01467076-8bb0-41c1-ad54-5751dd4a9e80"
},
"name": {
"type": "string",
"description": "Full name of the beneficiary partner",
"example": "Hong Kong Exports Ltd."
},
"email": {
"type": "string",
"description": "Email address of the beneficiary partner",
"format": "email",
"example": "hongkong@exports.com"
}
}
},
"account": {
"type": "object",
"description": "Account associated to this collection, which funds will be routed to",
"required": [
"id",
"beneficiary_id",
"currency",
"type"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the account",
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"beneficiary_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the beneficiary partner",
"example": "291ecf34-a01d-466a-b0fd-662a88b7a1bb"
},
"currency": {
"type": "string",
"description": "Currency for the account",
"example": "USD"
},
"type": {
"type": "string",
"description": "Type of account",
"enum": [
"FIAT",
"CRYPTO"
],
"example": "FIAT"
}
}
},
"reference_id": {
"type": "string",
"description": "External reference identifier for the collection",
"example": "INV-2025-009"
},
"gross_amount": {
"type": "string",
"description": "Total amount including fees",
"example": "808.00"
},
"net_amount": {
"type": "string",
"description": "Amount excluding buyer fees",
"example": "800.00"
},
"fee_mode": {
"$ref": "#/components/schemas/FeeMode"
},
"fee": {
"type": "string",
"description": "Fee amount charged for the collection",
"example": "8.00"
},
"amount_remaining": {
"type": "string",
"description": "Amount remaining for an incomplete payment",
"example": "758.50"
},
"description": {
"type": "string",
"description": "Human-readable description of the collection purpose",
"example": "Payment for Order #2668"
},
"link_expiry": {
"type": "integer",
"description": "Payment link expiry time in seconds from creation",
"example": 172800
},
"return_url": {
"type": "string",
"format": "uri",
"example": "https://example.com/payment/completion"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp when the collection expires",
"example": "2025-06-30T23:59:59Z"
},
"payment_link": {
"type": "string",
"format": "uri",
"description": "URL for the payment interface",
"example": "https://collections.ripple.com/link/pay/384c5f9b"
},
"status": {
"$ref": "#/components/schemas/CollectionStatus"
},
"reason": {
"type": "string",
"nullable": true,
"description": "Reason for current status (if applicable)",
"example": null
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp when the collection was created",
"example": "2025-06-17T12:00:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp when the collection was last updated",
"example": "2025-06-17T12:30:00Z"
}
}
},
"Network": {
"type": "string",
"description": "Supported blockchain networks",
"enum": [
"ETHEREUM",
"ETHEREUM_SEPOLIA_TESTNET",
"SOLANA",
"SOLANA_TESTNET",
"XRPL",
"XRPL_TESTNET"
],
"example": "ETHEREUM"
},
"EventType": {
"type": "string",
"description": "Event type for which a webhook can be created.",
"enum": [
"WEBHOOK_CREATED",
"WEBHOOK_UPDATED",
"WEBHOOK_DELETED",
"TRANSACTION_STATUS_CHANGED",
"PARTNER_STATUS_CHANGED",
"WALLET_ADDRESS_CREATED",
"WALLET_ADDRESS_ROTATED",
"SETTLEMENT_INITIATED",
"SETTLEMENT_COMPLETED",
"SETTLEMENT_FAILED",
"CHANNEL_CREATED",
"CHANNEL_ARCHIVED",
"ACCOUNT_CREATED",
"ACCOUNT_STATUS_CHANGED",
"ACCOUNT_BALANCE_UPDATED"
],
"x-enum-descriptions": {
"WEBHOOK_CREATED": "Fired when a new webhook subscription is created",
"WEBHOOK_UPDATED": "Fired when a webhook subscription is updated",
"WEBHOOK_DELETED": "Fired when a webhook subscription is deleted",
"TRANSACTION_STATUS_CHANGED": "Fired when a transaction status changes",
"PARTNER_STATUS_CHANGED": "Fired when a partner status changes",
"WALLET_ADDRESS_CREATED": "Fired when a new wallet address is created",
"WALLET_ADDRESS_ROTATED": "Fired when a wallet address is rotated",
"SETTLEMENT_INITIATED": "Fired when a settlement is initiated",
"SETTLEMENT_COMPLETED": "Fired when a settlement is completed",
"SETTLEMENT_FAILED": "Fired when a settlement fails",
"CHANNEL_CREATED": "Fired when a new channel is created",
"CHANNEL_ARCHIVED": "Fired when a channel is archived",
"ACCOUNT_CREATED": "Fired when a new account is created for a beneficiary",
"ACCOUNT_STATUS_CHANGED": "Fired when an account status changes (e.g., ACTIVE, SUSPENDED, CLOSED)",
"ACCOUNT_BALANCE_UPDATED": "Fired when an account balance is updated after transactions settle"
},
"example": "TRANSACTION_STATUS_CHANGED"
},
"CreateWebhookRequest": {
"type": "object",
"required": [
"callback_url",
"event_types"
],
"properties": {
"callback_url": {
"type": "string",
"format": "uri",
"description": "HTTPS URL to POST events to.",
"example": "https://webhook.partner.example/webhooks"
},
"event_types": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/components/schemas/EventType"
}
}
}
},
"UpdateWebhookRequest": {
"type": "object",
"required": [
"callback_url"
],
"properties": {
"callback_url": {
"type": "string",
"format": "uri",
"description": "HTTPS URL to POST events to.",
"example": "https://webhook-updated.partner.example/webhooks"
}
}
},
"WebhookResponse": {
"type": "object",
"required": [
"id",
"event_type",
"callback_url",
"signature_verification_key"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the webhook.",
"example": "5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10"
},
"event_type": {
"allOf": [
{
"$ref": "#/components/schemas/EventType"
}
],
"example": "TRANSACTION_STATUS_CHANGED"
},
"callback_url": {
"type": "string",
"format": "uri",
"description": "HTTPS URL to which events will be sent.",
"example": "https://webhook.partner.example/webhooks"
},
"signature_verification_key": {
"type": "string",
"description": "Hex-encoded public key used to verify webhook signatures.",
"example": "04bfcabf3c3e5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8"
}
}
},
"AuthErrorResponse": {
"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"
}
}
},
"Error": {
"type": "object",
"description": "Standard error response format",
"required": [
"code",
"reason"
],
"properties": {
"code": {
"type": "string",
"description": "Error code identifying the type of error"
},
"reason": {
"type": "string",
"description": "Human-readable error message"
}
}
},
"PageMetadata": {
"type": "object",
"description": "Pagination metadata.",
"properties": {
"page": {
"type": "integer",
"example": 1
},
"size": {
"type": "integer",
"example": 10
},
"total_elements": {
"type": "integer",
"example": 100
},
"total_pages": {
"type": "integer",
"example": 10
}
},
"required": [
"page",
"size",
"total_elements",
"total_pages"
]
}
}
}
}