Skip to content

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 paying an individual beneficiary. To pay an individual beneficiary, specify their beneficiaryIdentityId in the Create payment step.

There are three 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 details about the initiated payment.

Prerequisites

You must have the following items to be able to carry out the steps in this tutorial:

  • An access token to access secured API endpoints.
  • Obtain the beneficiary identityID using the Get a list of identities operation.
    • A beneficiaryIdentityId identifies the beneficiary of your payment and is required for all payments. This value is the identityId associated with the identity of the beneficiary you want to pay.
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 returns a collection of quotes containing one or more quotes for a payment using the chosen payout method.

Create quote collection request

In this tutorial, we are sending 10,000 USD to a beneficiary in Mexico, who will receive it in MXN in their bank account.

You must include the following parameters in the request body:

  • quoteAmount : Set this value to 10000.
  • quoteAmountType : Set this value to SOURCE_AMOUNT.
    • Setting this value returns a quote for the amount you want to send and not the amount the beneficiary of this payment will receive.
  • sourceCurrency : Set this value to USD.
  • 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.
destinationCountry

This field must be specified if destinationCurrency is a fiat currency. If destinationCurrency is a digital asset, the destinationCountry field is not required.

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 contains a unique quoteId and quote details such as the amount that the beneficiary will receive, foreign exchange (FX) rate, and fees.

Quotes have an expiration date

Each quote includes an expiresAt field the indicates the expiration date and time of the quote. You must create a payment using the quoteId before it expires.

{
  "quoteCollectionId": "11111111-aaaa-2222-bbbb-222222222222",
  "quotes": [
    {
      "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630",
      "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": [
        {
          "totalFee": 14,
          "feeCurrency": "USD",
          "feeBreakdown": [
            {
              "calculatedFee": 3,
              "feeName": "Example flat service fee",
              "feeDescription": "Fees with unit 3$ FLAT"
            },
            {
              "calculatedFee": 11,
              "feeName": "Example BPS service fee",
              "feeDescription": "Fees with unit BPS"
            }
          ]
        }
      ],
      "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.

To do this, we'll call the create payment operation to start 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 identityId of the beneficiary.

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.
  • internalId : This example uses Invoice-123.
    • Note : This is a required sender-created ID to use with filtering in other API operations.
  • purposeCode : This example uses PAYR to indicate that the Purpose of this payment is payroll.
  • sourceOfCash : This example uses SVGS to indicate that the Source of Cash for this payment is savings.
{
  "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630",
  "beneficiaryIdentityId": "22222222-aaaa-2222-bbbb-222222222222",
  "internalId": "Invoice-123",
  "purposeCode": "PAYR",
  "sourceOfCash": "SVGS"
}

Create payment response

A success response from the API 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": {
    "internalId": "Invoice-123",
    "sourceCountry": "US",
    "sourceCurrency": "USD",
    "sourceAmount": 10000,
    "payin": "FUNDED"
  },
  "destination": {
    "destinationAmount": 203766.88,
    "destinationCountry": "MX",
    "destinationCurrency": "MXN",
    "beneficiaryIdentityId": "22222222-aaaa-2222-bbbb-222222222222",
    "beneficiaryIdentityVersion": 1,
    "beneficiaryIdentityNickName": "Successful Beneficiary",
    "payout": "BANK"
  },
  "fxRate": 20.4052,
  "adjustedExchangeRate": {
    "adjustedRate": 20.3422
  },
  "fees": [
    {
      "totalFee": 14,
      "feeCurrency": "USD"
    }
  ],
  "purposeCode": "PAYR",
  "transactionDetails": {
    "paymentProduct": "PAYMENTS_DIRECT",
    "flowType": "B2B",
    "thirdPartyPayment": false,
    "businessUseCase": "FIAT_TRANSFER"
  }
}

Get a payment

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

Get payment request

Use the paymentId path parameter to specify the unique ID of the payment whose status you want to monitor.

curl -i -X GET \
  https://api.test.ripple.com/v2/payments/7ea3399c-1234-5678-8d8f-d320ea406630 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Get payment response

Check the paymentState field in the response 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": "22222222-aaaa-2222-bbbb-222222222222",
    "beneficiaryIdentityVersion": 1,
    "beneficiaryIdentityNickName": "Successful Beneficiary",
    "payout": "BANK"
  },
  "fxRate": 20.4052,
  "fees": [
    {
      "totalFee": 14,
      "feeCurrency": "USD"
    }
  ],
  "purposeCode": "PAYR"
}

Get state transitions

In addition to getting the current state of a payment, you can also use the get state transitions operation to see when the payment transitioned between states.

curl -i -X GET \
  https://api.test.ripple.com/v2/payments/7ea3399c-1234-5678-8d8f-d320ea406630/states \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Get state transition response

Examine the response to view the state transitions.

{
  "stateTransitions": [
    {
      "updatedFrom": "QUOTED",
      "updatedTo": "INITIATED",
      "updatedAt": "2025-02-21T15:32:34.557Z"
    },
    {
      "updatedFrom": "INITIATED",
      "updatedTo": "VALIDATING",
      "updatedAt": "2025-02-21T15:32:38.380Z"
    },
    {
      "updatedFrom": "VALIDATING",
      "updatedTo": "TRANSFERRING",
      "updatedAt": "2025-02-21T15:32:49.552Z"
    },
    {
      "updatedFrom": "TRANSFERRING",
      "updatedTo": "COMPLETED",
      "updatedAt": "2025-02-21T15:34:54.496Z"
    }
  ]
}