{
"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 (alpha)",
"version": "0.0.1"
},
"servers": [
{
"url": "https://api.test.ripple.com"
},
{
"url": "https://api.ripple.com"
}
],
"tags": [
{
"name": "Authentication",
"description": "Endpoints for authentication"
},
{
"name": "Collection Links",
"description": "Endpoints for managing one-time collection links"
},
{
"name": "Collection Channels",
"description": "Endpoints for managing persistent collection channels"
},
{
"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"
},
{
"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"
}
}
}
},
"/v0/collections/links": {
"get": {
"tags": [
"Collection Links"
],
"summary": "List collections",
"description": "Retrieves a list of collections, filterable by query parameters.",
"operationId": "listCollections",
"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": "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/Collection"
}
},
"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.",
"operationId": "createCollection",
"security": [
{
"Bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateCollectionRequest"
},
"examples": {
"example_with_excluded_fee": {
"summary": "Example for EXCLUDED fee_mode",
"value": {
"payer_id": "0c5479ff-3772-4123-b2b7-e679e71eb570",
"beneficiary_id": "01467076-8bb0-41c1-ad54-5751dd4a9e80",
"amount": "800.00",
"currency": "USD",
"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",
"beneficiary_id": "01467076-8bb0-41c1-ad54-5751dd4a9e80",
"amount": "800.00",
"currency": "USD",
"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/Collection"
},
"example": {
"id": "e8d43598-107d-4694-9fb2-934e7484c3d4",
"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"
},
"reference_id": "INV-2025-009",
"gross_amount": "808.00",
"net_amount": "800.00",
"currency": "USD",
"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",
"transactions": [],
"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"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v0/collections/links/{collection_id}": {
"get": {
"tags": [
"Collection Links"
],
"summary": "Get collection details",
"description": "Retrieves the details of a specific collection by its ID.",
"operationId": "getCollectionById",
"security": [
{
"Bearer": []
}
],
"parameters": [
{
"name": "collection_id",
"in": "path",
"required": true,
"description": "Unique identifier of the collection to retrieve",
"schema": {
"type": "string",
"format": "uuid",
"example": "22a0337b-8e62-449c-91ca-a0f830c55733"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Collection"
},
"example": {
"id": "22a0337b-8e62-449c-91ca-a0f830c55733",
"payer": {
"id": "0c5479ff-3772-4123-b2b7-e679e71eb570",
"name": "Nigerian Imports Ltd.",
"email": "nigerian@imports.com"
},
"reference_id": "INV-2025-009",
"beneficiary": {
"id": "01467076-8bb0-41c1-ad54-5751dd4a9e80",
"name": "Hong Kong Exports Ltd.",
"email": "hongkong@exports.com"
},
"gross_amount": "800.00",
"net_amount": "792.00",
"currency": "USD",
"fee_mode": "INCLUDED",
"fee": "8.00",
"amount_remaining": "750.50",
"description": "Payment for Order #2670",
"link_expiry": 172800,
"return_url": "https://example.com/payment/completion",
"expires_at": "2025-06-30T23:59:59Z",
"transactions": [
{
"id": "487ba009-56cf-4ad9-8b5c-045e27893e00",
"parent_id": "22a0337b-8e62-449c-91ca-a0f830c55733",
"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"
},
"fiat_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_transaction_details": {
"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
}
],
"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"
}
}
}
},
"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"
}
}
}
}
}
}
},
"/v0/collections/links/cancel": {
"post": {
"tags": [
"Collection Links"
],
"summary": "Cancel a collection",
"description": "API to cancel a payment collection.",
"operationId": "cancelCollection",
"security": [
{
"Bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the collection to cancel",
"example": "92e001a4-311a-4a63-ab2a-f050207c5283"
},
"reason": {
"type": "string",
"description": "Optional reason for cancelling the collection",
"example": "Collection cancelled"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Collection cancelled successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Collection"
},
"example": {
"id": "92e001a4-311a-4a63-ab2a-f050207c5283",
"payer": {
"id": "0c5479ff-3772-4123-b2b7-e679e71eb570",
"name": "Nigerian Imports Ltd.",
"email": "nigerian@imports.com"
},
"reference_id": "INV-2025-009",
"beneficiary": {
"id": "01467076-8bb0-41c1-ad54-5751dd4a9e80",
"name": "Hong Kong Exports Ltd.",
"email": "hongkong@exports.com"
},
"gross_amount": "800.00",
"net_amount": "792.00",
"currency": "USD",
"fee_mode": "INCLUDED",
"fee": "8.00",
"amount_remaining": "800.00",
"description": "Payment for Order #2669",
"link_expiry": 172800,
"return_url": "https://example.com/payment/completion",
"expires_at": "2025-06-30T23:59:59Z",
"transactions": [],
"payment_link": "https://collections.ripple.com/link/pay/124c5f9b",
"status": "CANCELLED",
"reason": "Collection cancelled",
"created_at": "2025-06-17T12:00:00Z",
"updated_at": "2025-06-17T12:30:00Z"
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters or collection cannot be cancelled",
"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"
}
}
}
}
}
}
},
"/v0/collections/partners": {
"get": {
"tags": [
"Partners"
],
"summary": "List partners",
"description": "Retrieves a list of partners, filterable by ID or type.",
"operationId": "listPartners",
"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/Partner"
}
},
"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": "createPartner",
"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/Partner"
}
}
}
},
"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"
}
}
}
}
}
}
},
"/v0/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": "getPartnerById",
"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/Partner"
}
}
}
},
"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": "updatePartner",
"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/Partner"
}
}
}
},
"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"
}
}
}
}
}
}
},
"/v0/collections/settlements": {
"get": {
"tags": [
"Settlements"
],
"summary": "List settlements",
"description": "API to fetch first party payouts (settlements).",
"operationId": "listSettlements",
"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,
"default": 10
},
"description": "Page size (items 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/Settlement"
}
},
"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"
}
}
}
}
}
}
},
"/v0/collections/settlements/{settlement_id}": {
"get": {
"tags": [
"Settlements"
],
"summary": "Get settlement by ID",
"description": "API to fetch a first party payout (settlement to our customer).",
"operationId": "getSettlementById",
"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/Settlement"
}
}
}
},
"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"
}
}
}
}
}
}
},
"/v0/collections/channels": {
"get": {
"tags": [
"Collection Channels"
],
"summary": "List channels",
"description": "Retrieves a list of channels, filterable by query parameters.",
"operationId": "listChannels",
"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": "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": "payment_currency",
"in": "query",
"description": "Filter channels by payment currency asset",
"schema": {
"type": "string"
},
"example": "USDC"
},
{
"name": "network",
"in": "query",
"description": "Filter channels by payment currency network",
"schema": {
"type": "string",
"$ref": "#/components/schemas/Network"
},
"example": "ETHEREUM"
},
{
"name": "wallet_address",
"in": "query",
"description": "Filter channels by wallet address",
"schema": {
"type": "string"
},
"example": "0xBb592aaaF9AcE2fbE3F735645819FA94c95a9cb5"
},
{
"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/Channel"
}
},
"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"
},
"channel_currency": {
"type": "FIAT",
"asset": "USD"
},
"payment_currency": {
"type": "CRYPTO",
"asset": "USDC",
"network": "ETHEREUM"
},
"wallet": {
"address": "0xBb592aaaF9AcE2fbE3F735645819FA94c95a9cb5",
"currency": "USDC",
"network": "ETHEREUM"
},
"payment_link": "https://collections.ripplenet.com/pay/channel/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"transactions": [
{
"id": "487ba009-56cf-4ad9-8b5c-045e27893e00",
"parent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"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": "USDC"
},
"fiat_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": "USDC",
"counter": "USD",
"rate": "1.00"
},
"exchange_rate": {
"base": "USDC",
"counter": "USD",
"rate": "0.99"
},
"source_transaction_details": {
"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
}
],
"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": 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"
}
}
}
}
}
},
"post": {
"tags": [
"Collection Channels"
],
"summary": "Create a channel",
"description": "Creates a new payment channel between payer and beneficiary.",
"operationId": "createChannel",
"security": [
{
"Bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateChannelRequest"
},
"examples": {
"default": {
"summary": "Example channel creation request",
"value": {
"payer_id": "e471b938-98ad-45e4-b144-53a556ea047d",
"beneficiary_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
"payment_currency": {
"type": "CRYPTO",
"asset": "USDC",
"network": "ETHEREUM"
},
"channel_currency": {
"type": "FIAT",
"asset": "USD"
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Channel created successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Channel"
},
"examples": {
"default": {
"summary": "Example 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"
},
"channel_currency": {
"type": "FIAT",
"asset": "USD"
},
"payment_currency": {
"type": "CRYPTO",
"asset": "USDC",
"network": "ETHEREUM"
},
"wallet": {
"address": "0xBb592aaaF9AcE2fbE3F735645819FA94c95a9cb5",
"currency": "USDC",
"network": "ETHEREUM"
},
"payment_link": "https://collections.ripplenet.com/pay/channel/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"transactions": [],
"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"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v0/collections/channels/{channel_id}": {
"get": {
"tags": [
"Collection Channels"
],
"summary": "Get channel details",
"description": "Retrieves the details of a specific channel by its ID.",
"operationId": "getChannelById",
"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/Channel"
},
"examples": {
"default": {
"summary": "Example 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"
},
"channel_currency": {
"type": "FIAT",
"asset": "USD"
},
"payment_currency": {
"type": "CRYPTO",
"asset": "USDC",
"network": "ETHEREUM"
},
"wallet": {
"address": "0xBb592aaaF9AcE2fbE3F735645819FA94c95a9cb5",
"currency": "USDC",
"network": "ETHEREUM"
},
"payment_link": "https://collections.ripplenet.com/pay/channel/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"transactions": [
{
"id": "487ba009-56cf-4ad9-8b5c-045e27893e00",
"parent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"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": "USDC"
},
"fiat_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": "USDC",
"counter": "USD",
"rate": "1.00"
},
"exchange_rate": {
"base": "USDC",
"counter": "USD",
"rate": "0.99"
},
"source_transaction_details": {
"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
}
],
"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"
}
}
}
}
}
}
},
"/v0/collections/transactions": {
"get": {
"tags": [
"Transactions"
],
"summary": "List Transactions",
"description": "API to fetch transactions across collections links or channels (transactions).",
"operationId": "listTransactions",
"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": "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 addresss",
"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/Transaction"
}
},
"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"
}
}
}
}
}
}
},
"/v0/collections/transactions/{transaction_id}": {
"get": {
"tags": [
"Transactions"
],
"summary": "Get transaction by ID",
"description": "API to fetch a transaction (payment from a payer to beneficiary)",
"operationId": "getTransactionById",
"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/Transaction"
}
}
}
},
"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"
}
}
}
}
}
}
},
"/v0/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"
}
}
}
}
}
}
},
"/v0/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"
}
}
}
},
"Partner": {
"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"
},
"CreateCollectionRequest": {
"type": "object",
"description": "Request payload for creating a new collection",
"required": [
"payer_id",
"beneficiary_id",
"amount",
"currency",
"link_expiry",
"return_url"
],
"properties": {
"payer_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the payer partner",
"example": "0c5479ff-3772-4123-b2b7-e679e71eb570"
},
"beneficiary_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the beneficiary partner",
"example": "01467076-8bb0-41c1-ad54-5751dd4a9e80"
},
"amount": {
"type": "string",
"description": "Collection amount as a string to preserve precision",
"pattern": "^[0-9]+(\\.[0-9]{1,8})?$",
"example": "800.00"
},
"currency": {
"type": "string",
"description": "Currency or asset symbol",
"example": "USD"
},
"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"
}
}
},
"UpdateCollectionRequest": {
"type": "object",
"description": "Request payload for updating a collection status",
"required": [
"status"
],
"properties": {
"status": {
"$ref": "#/components/schemas/CollectionStatus"
}
}
},
"Collection": {
"type": "object",
"description": "Complete collection information",
"required": [
"id",
"payer",
"beneficiary",
"gross_amount",
"net_amount",
"currency",
"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"
}
}
},
"reference_id": {
"type": "string",
"description": "External reference identifier for the collection",
"example": "INV-2025-009"
},
"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"
}
}
},
"gross_amount": {
"type": "string",
"description": "Total amount including fees",
"example": "808.00"
},
"net_amount": {
"type": "string",
"description": "Amount excluding buyer fees",
"example": "800.00"
},
"currency": {
"type": "string",
"description": "Currency or asset symbol",
"example": "USD"
},
"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"
},
"transactions": {
"type": "array",
"description": "List of blockchain transactions associated with this collection",
"items": {
"$ref": "#/components/schemas/Transaction"
}
},
"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"
}
}
},
"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"
},
"Transaction": {
"type": "object",
"description": "Blockchain transaction details",
"required": [
"id",
"parent_id",
"payer",
"beneficiary",
"payment_amount",
"fiat_equivalent",
"market_rate",
"exchange_rate",
"source_transaction_details",
"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"
},
"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": "Crypto 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": "Crypto asset symbol of the payment",
"example": "USDT"
}
}
},
"fiat_equivalent": {
"type": "object",
"description": "Fiat equivalent amounts for payment, fee, and net",
"required": [
"gross_amount",
"fee_amount",
"net_amount"
],
"properties": {
"gross_amount": {
"type": "object",
"required": [
"value",
"currency"
],
"properties": {
"value": {
"type": "string",
"description": "Gross amount in fiat",
"example": "50.00"
},
"currency": {
"type": "string",
"description": "Fiat currency code",
"example": "USD"
}
}
},
"fee_amount": {
"type": "object",
"required": [
"value",
"currency"
],
"properties": {
"value": {
"type": "string",
"description": "Fee amount in fiat",
"example": "0.50"
},
"currency": {
"type": "string",
"description": "Fiat currency code",
"example": "USD"
}
}
},
"net_amount": {
"type": "object",
"required": [
"value",
"currency"
],
"properties": {
"value": {
"type": "string",
"description": "Net amount in fiat",
"example": "49.50"
},
"currency": {
"type": "string",
"description": "Fiat 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_transaction_details": {
"type": "object",
"description": "On-chain transaction details",
"required": [
"network",
"transaction_hash",
"block_id",
"source_address",
"destination_address",
"gas_fee"
],
"properties": {
"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"
}
}
}
}
},
"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 on blockchain",
"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"
},
"CreateSettlementRequest": {
"type": "object",
"description": "Request payload for creating a new settlement",
"required": [
"type",
"currency",
"amount"
],
"properties": {
"type": {
"$ref": "#/components/schemas/SettlementType"
},
"currency": {
"type": "string",
"description": "Currency code for the settlement",
"example": "USD"
},
"amount": {
"type": "string",
"description": "Settlement amount as a string to preserve precision",
"pattern": "^[0-9]+(\\.[0-9]{1,8})?$",
"example": "100.00"
}
}
},
"Settlement": {
"type": "object",
"description": "Settlement information",
"required": [
"id",
"type",
"currency",
"gross_amount",
"settlement_amount",
"fees",
"status",
"data",
"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": "string",
"description": "Total fees applied to the settlement",
"example": "0.50"
},
"data": {
"type": "object",
"description": "Additional settlement data including account details",
"properties": {
"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"
}
}
},
"transactions": {
"type": "array",
"description": "List of transactions associated with this settlement",
"items": {
"$ref": "#/components/schemas/Transaction"
}
},
"status": {
"$ref": "#/components/schemas/SettlementStatus"
},
"reason": {
"type": "string",
"nullable": true,
"description": "Reason for current status (if applicable)",
"example": null
}
}
},
"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"
}
}
},
"CreateChannelRequest": {
"type": "object",
"required": [
"payer_id",
"beneficiary_id",
"payment_currency",
"channel_currency"
],
"properties": {
"payer_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the payer partner",
"example": "e471b938-98ad-45e4-b144-53a556ea047d"
},
"beneficiary_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the beneficiary partner",
"example": "291ecf34-a01d-466a-b0fd-662a88b7a1bb"
},
"payment_currency": {
"$ref": "#/components/schemas/CryptoCurrency"
},
"channel_currency": {
"$ref": "#/components/schemas/FiatCurrency"
}
}
},
"Channel": {
"type": "object",
"description": "Complete channel information",
"required": [
"id",
"payer",
"beneficiary",
"channel_currency",
"payment_currency",
"wallet",
"transactions",
"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 for the beneficiary partner",
"example": "291ecf34-a01d-466a-b0fd-662a88b7a1bb"
},
"name": {
"type": "string",
"description": "Full name of the beneficiary partner",
"example": "Hong Kong Exports Ltd."
},
"email": {
"type": "string",
"format": "email",
"description": "Email address of the beneficiary partner",
"example": "hongkong@exports.com"
}
}
},
"payment_currency": {
"$ref": "#/components/schemas/CryptoCurrency"
},
"channel_currency": {
"$ref": "#/components/schemas/FiatCurrency"
},
"wallet": {
"$ref": "#/components/schemas/Wallet"
},
"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"
},
"transactions": {
"type": "array",
"description": "List of blockchain transactions associated with this channel",
"items": {
"$ref": "#/components/schemas/Transaction"
}
},
"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"
}
}
},
"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"
},
"Wallet": {
"type": "object",
"description": "Wallet details for the channel",
"required": [
"address",
"currency",
"network"
],
"properties": {
"address": {
"type": "string",
"description": "Wallet address for the channel",
"example": "0xBb592aaaF9AcE2fbE3F735645819FA94c95a9cb5"
},
"currency": {
"type": "string",
"description": "Currency held in the wallet",
"example": "USDC"
},
"network": {
"$ref": "#/components/schemas/Network",
"description": "Blockchain network for the wallet",
"example": "ETHEREUM"
}
}
},
"Currency": {
"type": "object",
"description": "Currency (crypto or fiat)",
"discriminator": {
"propertyName": "type",
"mapping": {
"CRYPTO": "#/components/schemas/CryptoCurrency",
"FIAT": "#/components/schemas/FiatCurrency"
}
},
"oneOf": [
{
"$ref": "#/components/schemas/CryptoCurrency"
},
{
"$ref": "#/components/schemas/FiatCurrency"
}
]
},
"CryptoCurrency": {
"type": "object",
"description": "Metadata for a crypto asset",
"required": [
"type",
"asset",
"network"
],
"properties": {
"type": {
"type": "string",
"enum": [
"CRYPTO"
],
"description": "Discriminator: indicates crypto asset metadata"
},
"asset": {
"type": "string",
"description": "Ticker symbol of the crypto asset",
"example": "USDC"
},
"network": {
"$ref": "#/components/schemas/Network"
}
}
},
"FiatCurrency": {
"type": "object",
"description": "Metadata for a fiat currency",
"required": [
"type",
"asset"
],
"properties": {
"type": {
"type": "string",
"enum": [
"FIAT"
],
"description": "Discriminator: indicates fiat currency metadata"
},
"asset": {
"type": "string",
"description": "Fiat currency code (ISO 4217)",
"example": "USD"
}
}
},
"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"
],
"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"
},
"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"
]
}
}
}
}