Create a payment

In this tutorial, we'll step through the API calls required to create a B2B payment.

In a B2B payment, you - a business or institution - are the payment originator and you're paying another business or institutional beneficiary.

Note
While this tutorial focuses on paying a business beneficiary, the process is similar for making a payment to an individual beneficiary. To pay an individual beneficiary, specify their beneficiaryIdentityId in the Create payment step.

There are four main steps for creating a payment where you are the originator:

  1. Create a quote collection for a proposed payment.
  2. Create payment to begin the payment process.
  3. Get a payment to view your completed payment.

For instructions on creating a third-party payment, where you facilitate a payment on the behalf of a third-party originator, see Create a third-party payment.

Prerequisites

The following items must be addressed before you can carry out the instructions in this tutorial:

  • An access token to access secured API endpoints.
  • Have obtained the necessary identity tokens (see Create an identity for instructions):
    • A beneficiaryIdentityId identifies the beneficiary of your payment and is required for all payments.
Base URL for the test environment
The API calls in this tutorial use the test environment with https://api.test.ripple.com/v2 as the base URL.

Create a quote collection

We'll begin by calling the Create quote collection operation, which fetches a collection of quotes containing one or more quotes for a payment using the chosen payout method.

Create quote collection request

In our payment scenario, we are sending 10,000 USD to a beneficiary in Mexico, who will receive it in MXN.

This example shows how to construct the request body to get a quote to send USD 10,000 to a beneficiary in Mexico who will receive it in MXN.

  • quoteAmount : Set this value to 10000.
  • sourceCurrency : Set this value to USD.
  • quoteAmountType : Set this value to SOURCE_AMOUNT.
  • destinationCurrency : Set this value to MXN.
  • sourceCountry : Set this value to US.
  • destinationCountry : Set this value to MX.
  • payoutCategory : Set this value to BANK.
  • payinCategory : Set this value to FUNDED.

Example quote collection request payload

{
  • "quoteAmount": 10000,
  • "quoteAmountType": "SOURCE_AMOUNT",
  • "sourceCurrency": "USD",
  • "destinationCurrency": "MXN",
  • "sourceCountry": "US",
  • "destinationCountry": "MX",
  • "payoutCategory": "BANK",
  • "payinCategory": "FUNDED"
}

Create quote collection response

The response contains an array of one or more quote objects as a collection. Each quote object has a unique quoteId, and each quote contains quote elements that include regions, amounts, foreign exchange (FX) rates, and fees.

Quotes have an expiration date
Each quote includes an expiresAt field the indicates the expiration date and time of the quote. Quotes must be accepted prior to expiration.
{
  • "quoteCollectionId": "11111111-aaaa-2222-bbbb-222222222222",
  • "quotes": [
    • {
      • "quoteId": "22222222-aaaa-2222-bbbb-222222222222",
      • "quoteStatus": "ACTIVE",
      • "quoteAmountType": "SOURCE_AMOUNT",
      • "sourceAmount": 10000,
      • "destinationAmount": 204533.3,
      • "sourceCurrency": "USD",
      • "destinationCurrency": "MXN",
      • "sourceCountry": "US",
      • "destinationCountry": "MX",
      • "payoutCategory": "BANK",
      • "payinCategory": "FUNDED",
      • "adjustedExchangeRate": {
        • "adjustedRate": 20.4136
        },
      • "fees": [
        • {
          }
        ],
      • "createdAt": "2025-02-13T22:44:34.711Z",
      • "expiresAt": "2025-02-13T22:59:34.767Z"
      }
    ]
}

Create payment

Now that we have the quote for the payment, it's time to create the payment using the quoteId and include the beneficiary token we generated earlier.

To do this, we'll construct the create payment operation. Calling this operation starts the payment process.

Create payment request

Prerequisites
  • You must have the quoteId of the quote you want to accept from the create a quote response.
  • You must have the beneficiary token you created with the create an identity operation.

Construct the request body as follows:

  • quoteId : Set this value to the quoteId you received in the Create quote collection response.
  • beneficiaryIdentityId : Set this value to the UUID associated with the beneficiary identity.
  • purposeCode : This example uses PAYR to indicate that the Purpose is payroll.
  • sourceOfCash : This example uses SVGS to indicate that the Source of Cash is savings.
  • internalId : This example uses Invoice-123.
    • Note : This is a required sender-created ID to use with filtering in other API operations.
{
  • "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630",
  • "beneficiaryIdentityId": "7ea3399c-1234-5678-8d8f-d320ea406630",
  • "internalId": "Invoice-123",
  • "purposeCode": "PAYR",
  • "sourceOfCash": "SVGS"
}

Create payment response

The payment creation response contains the paymentId and other information you can use to monitor the status of the payment.
{
  • "paymentId": "7ea3399c-1234-5678-8d8f-d320ea406630",
  • "initiatedAt": "2025-02-13T23:24:15.770Z",
  • "expiresAt": "2025-04-14T23:24:15.770Z",
  • "lastStateUpdatedAt": "2025-02-13T23:24:15.770Z",
  • "paymentState": "TRANSFERRING",
  • "originator": {
    },
  • "destination": {
    },
  • "fxRate": 20.4052,
  • "fees": [
    ],
  • "purposeCode": "PAYR"
}

Get a payment

Use the get payment by payment ID operation to look up the status of a payment.

Get payment request

Get payment response
Check the paymentState field in the response output for the current payment state.
{
  • "paymentId": "7ea3399c-1234-5678-8d8f-d320ea406630",
  • "initiatedAt": "2025-02-13T23:24:15.770Z",
  • "expiresAt": "2025-04-14T23:24:15.770Z",
  • "lastStateUpdatedAt": "2025-02-13T23:24:15.770Z",
  • "paymentState": "INITIATED",
  • "originator": {
    • "internalId": "Invoice-123",
    • "sourceCountry": "US",
    • "sourceCurrency": "USD",
    • "sourceAmount": 10000,
    • "payin": "FUNDED"
    },
  • "destination": {
    • "destinationAmount": 203766.88,
    • "destinationCountry": "MX",
    • "destinationCurrency": "MXN",
    • "beneficiaryIdentityId": "7ea3399c-1234-5678-8d8f-d320ea406630",
    • "beneficiaryIdentityVersion": 1,
    • "beneficiaryIdentityNickName": "Successful Beneficiary",
    • "payout": "BANK"
    },
  • "fxRate": 20.4052,
  • "fees": [
    • {
      }
    ],
  • "purposeCode": "PAYR"
}