Payments

Use these API operations to manage your payments with Payment Management v3 (recommended for all new integrations).

Operation	Method	Description
Search payments	POST	Search for payments based on filtering criteria.
Create a payment	POST	Create a payment by accepting a quote.
Get payment by payment ID	GET	Get a specific payment by payment ID.
Get state transitions by payment ID	GET	Get the state transitions for a specific payment by payment ID.
Update payment labels	PATCH	Update the labels for a specific payment by payment ID.

Operations

Search payments

Request

Returns a paginated list of payments matching the specified filters. You can filter by status, date range, destination country, currency, or custom labels.

Security

Bearer

Bodyapplication/jsonrequired

Search payments request

filterobject

Filter criteria to return desired payment search results.

sortobject

Defines the sorting parameters for listing payments, including the field and sort direction.

pageobject

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

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

Responses

Payments matching the specified filtering criteria.

Bodyapplication/json

dataArray of objects

Array of Payment objects