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.

There are four main steps for creating a third-party payment where you are the intermediary:

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 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 received the sending_address from your Ripple Liaison.
• 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.
  • An originator_token is required when performing third-party payments.

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 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.
• global : This field must be set to true.

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&global=true' \
  -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 get payout method response 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.

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 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.

• 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 : Here, you apply CSM_EU_EUR_SEPA as it matches the response you received from the payout method lookup.

Example quote collection request payload

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.

Accept a quote

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

Accept quote request

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 tokens we generated earlier, as well as the purpose of the payment and source of funding.
  • originator_token : Set this value to the identityId UUID associated with the originator identity.
  • 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.

Accept quote response

Get a payment

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

Get payment request

Get payment response