Skip to content

Create a v2 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 identities v2 operation in the API reference.

Create a quote collection

We'll begin by calling the Create quote collection operation to get a quote for the payment.

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.

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. This is an optional sender-created reference (maximum 36 characters) for correlating payments with your own records and 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": "PRE_FUNDING"
  },
  "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": "PRE_FUNDING"
  },
  "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",
  "payoutExecutionDetails": {
    "paymentRailUsed": "ACH",
    "payoutStartTime": "2025-02-13T23:25:00.000Z",
    "payoutEndTime": "2025-02-13T23:34:54.000Z",
    "trackingReferences": [
      {
        "referenceType": "IMAD",
        "value": "20250213MMQFMP9N000123",
        "displayName": "IMAD Number",
        "description": "Input Message Accountability Data (IMAD) for Fedwire transfer tracking"
      }
    ]
  }
}
payoutExecutionDetails

payoutExecutionDetails is an optional field returned only by GET /v2/payments/{paymentId}. It provides informational metadata about payout execution: the rail used (paymentRailUsed), timing (payoutStartTime, payoutEndTime), and network-specific tracking references (trackingReferences). Coverage varies by corridor and payout partner. Do not build required workflows that depend on its presence.

Use the referenceType field on each tracking reference to identify what a value represents, for example, IMAD and OMAD for Fedwire transfers.

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"
    }
  ]
}
Previous page
Next page