Skip to content

Create a third-party payment

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

In a third-party payment, you process payments on behalf of a third-party business or institution which is paying a business or individual beneficiary.

Note

While this tutorial focuses on creating a payment on behalf of a business to pay another 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 third-party payment where you are the intermediary:

  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 payment where you - a business or institution - are the payment originator and you're paying another business or institutional beneficiary, see Create a 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 identityIDs. Work with your Ripple liaison to get them.
    • A beneficiaryIdentityId identifies the beneficiary of your payment and is required for all payments.
    • An originatorIdentityId is required when performing third-party 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

In this step, we call 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, a third-party is sending 10,000 USD to a beneficiary in Mexico, who will receive it in MXN. So now we can construct the request body to fetch a quote.

This example shows how to construct the request body.

  • 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 correspond to each step of the payment transaction and include account addresses, amounts, foreign exchange (FX) rates, and fees for each step.

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 prior to expiration.

{
  "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 a payment using the quoteId and include the originatorIdentityId and beneficiaryIdentityId. 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 use from the create a quote response.
  • You must have the identity IDs.

Construct the request body as follows:

  • quoteId : Set this value to the quoteId you received in the Create quote collection response.
  • originatorIdentityId : Set this value to the UUID associated with the originator identity.
  • beneficiaryIdentityId : Set this value to the UUID associated with the beneficiary identity.
  • internalId : This example uses Invoice number 123.
  • 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.
{
  "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630",
  "originatorIdentityId": "11111111-abcd-2222-efgh-333333333333",
  "beneficiaryIdentityId": "22222222-aaaa-2222-bbbb-222222222222",
  "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": {
    "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 to look up the status of a payment.

Get payment request

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 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": "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"
  }
}