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 beneficiary_token in the Accept a quote step.

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

  1. Get a payout method for a given country and currency.
  2. Create a quote collection for a proposed payment.
  3. Accept a quote to begin the payment process.
  4. 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.
  • The sending_address provided by your Ripple Liaison. You'll need this value to request a quote.
  • Have obtained the necessary identity tokens (see Create an identity for instructions):
    • A beneficiary_token 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://customer-name.test.rnc.ripplenet.com/v4 as the base URL.

Get a payout method

We'll start by fetching the available payout methods for a given currency in the target destination.

A payout method specifies the clearing and settlement mechanisms or exchanges used to facilitate the transfer of funds, while a payment method defines how the beneficiary ultimately receives those funds.

Payout method lookup request

Use the get a payout method operation with the country_code and payment_method query parameters.

Example request

This example shows how to construct a query to find a payout method for a beneficiary located in Austria where the payout is in EUR.

These are the query parameters:

  • payment_method : This field must be set to BANK_PAYOUT.
  • country_code : This example uses AT to represent Austria in alpha-2 format.
  • payout_currency_code : This example uses EUR to indicate the payout currency is euro.
Copy
Copied!
curl -i -X GET \
  'https://[customer-name].test.rnc.ripplenet.com/v4/config/routing_table/lookup?country_code=AT&payout_currency_code=EUR&payment_method=BANK_PAYOUT' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Payout method response

In this example, we'll use the response of the previous request to help create the next API request.

The response from the API includes the following fields:

  • destination_address: Use the value of this field as the receiving_address address when you create a quote collection.
  • payout_method: Use the value of this field value as the payment_method when you create a quote collection.

In this example, payout_method returns CSM_EU_EUR_SEPA which is used in the Create quote collection operation to specify the payment_method parameter.

{
  • "id": "235b9711-cf8c-44ea-85aa-11dbbfcfde8b",
  • "destination_address": "rn.sgp.exampleReceiver",
  • "payout_method": "CSM_EU_EUR_SEPA"
}

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, we are sending 10,000 USD to a beneficiary in Austria, who will receive it in EUR. We have our payment_method value of CSM_EU_EUR_SEPA, so now we can construct the request body to fetch a quote.

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

Prerequisite

This request body includes:

  • The payment_method field uses the payout_method value returned by the Get a payout method operation.
  • The receiving_address field uses the destination_address value returned by the Get a payout method operation.
  • sending_address : Set this to the address provided by your Ripple liaison.
  • receiving_address: Set this to match the destination_address returned when looking up a payout method.
    • In this example it's rn.sgp.exampleReceiver
  • amount : Set this value to 10000.
  • currency : Set this value to USD.
  • quote_type : Set this value to SENDER_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.
    • For more information, see the quote_type param in the API reference.
  • payment_method : This example uses CSM_EU_EUR_SEPA so that it matches the response you received from the payout method lookup.

Example quote collection request payload

{
  • "sending_address": "test.usa.askYourRippleLiaisonForThisValue",
  • "receiving_address": "test.sgp.exampleReceiver",
  • "amount": 10000,
  • "currency": "USD",
  • "quote_type": "SENDER_AMOUNT",
  • "payment_method": "CSM_EU_EUR_SEPA"
}

Create quote collection response

The response contains an array of one or more quote objects as a collection. Each quote object has a unique quote_id, 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 expires_at field the indicates the expiration date and time of the quote. Quotes must be accepted prior to expiration.
{
  • "quote_collection_id": "63963322-29fc-41d3-8df6-948959a5ec77",
  • "quotes": [
    • {
      • "quote_id": "203642d1-c657-4963-9620-a3f9da2cf60d",
      • "created_at": "2024-03-22T15:13:31.275Z",
      • "expires_at": "2024-03-22T16:13:31.275Z",
      • "type": "SENDER_AMOUNT",
      • "price_guarantee": "FIRM",
      • "sender_address": "trans_usd_exampleSender@staging.usa.exampleSender",
      • "receiver_address": "trans_aud_exampleReceiver@staging.usa.exampleReceiver",
      • "amount": "10000",
      • "currency_code": "USD",
      • "currency_code_filter": null,
      • "service_type": null,
      • "quote_elements": [
        • {
          },
        • {
          }
        ],
      • "liquidity_warning": null,
      • "payment_method": "CSM_EU_EUR_SEPA",
      • "payment_method_fields": null,
      • "payout_method_info": {
        • "payout_method_name": "CSM_EU_EUR_SEPA",
        • "payout_method_category": "OTHER",
        • "description": "local rails",
        • "estimated_time_to_credit": "5 Seconds"
        }
      }
    ],
  • "quote_errors": [ ]
}

Accept a quote

Now that we have the quote for the payment, it's time to accept the quote and include the beneficiary token we generated earlier. To do this, we'll construct the accept a quote operation. Calling this operation starts the payment process.

Accept quote request

Prerequisites
  • You must have the quote_id 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:

  • quote_id : Set this value to the quote_id you received in the Create quote collection response.
  • user_info : This object contains the required identity token we generated earlier, as well as the purpose of the payment and source of funding.
    • beneficiary_token : Set this value to the identityId UUID associated with the beneficiary identity.
    • purpose : 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.
  • sender_end_to_end_id : This example uses 226f827a-04ec-471f-a3ba-2c241a00c55f.
    • Note : This is a required sender-created ID to use with filtering in other API operations.
Note
The following user_info object is for reference. Learn more about working with the user_info object
{
  • "quote_id": "4209ca26-28e2-4256-9ef2-746afbe1fb5a",
  • "user_info": {
    • "beneficiary_token": "11111111-abcd-2222-efgh-333333333333",
    • "purpose": "PAYR",
    • "SourceOfCash": "SVGS"
    },
  • "sender_end_to_end_id": "226f827a-04ec-471f-a3ba-2c241a00c55f"
}

Accept quote response

The accept a quote response contains the payment_id and other information you can use to monitor the status of the payment.
{
}

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 payment_state field in the response output for the current payment state, and refer to the user_info object for detailed payment information.
{
  • "payment_id": "d485f100-2af7-4e48-9ab1-3c7e28775691",
  • "contract_hash": "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103",
  • "payment_state": "COMPLETED",
  • "modified_at": "2019-10-01T18:25:47.347Z",
  • "contract": {
    },
  • "ripplenet_info": [
    ],
  • "execution_condition": "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}",
  • "crypto_transaction_id": "4e05da26-7872-4a1f-b9b7-db7604757c37",
  • "validator": "rn.us.ca.san_francisco",
  • "payment_type": "DIRECT",
  • "execution_results": [
    ],
  • "liquidation_execution_results": [
    ],
  • "liquidation_details": {
    },
  • "push_forward_execution_results": [
    ],
  • "accepted_at": "2019-10-01T18:25:47.347Z",
  • "executed_at": "2019-10-01T18:25:47.347Z",
  • "completed_at": "2019-10-01T18:25:47.347Z",
  • "internal_info": {
    },
  • "user_info": [
    ]
}