Create a payment

Prerequisite: IP allowlisting

You must add any IP addresses that will be connecting to Ripple servers to the IP allowlist.

This guide walks you through the API calls required to create a payment.

  1. Request an authentication token to access secured API endpoints.
  2. Create a new identity to serve as a sender or beneficiary.
  3. Get a payout method for a given country and currency.
  4. Create a quote collection for a proposed payment.
  5. Accept a quote to begin the payment process.
  6. Get a payment to view your completed payment.
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.

Request an access token

You must include a valid access token in your request header when you send requests to secured API endpoints.

To get an access token, you must have your client ID and client secret. Learn how to generate a client ID and client secret for use with Ripple APIs.

Request format

To get an authentication token for the test environment, send a POST request to the following URL:
Copy
Copied!
https://auth-test.rnc.ripplenet.com/oauth/token

Authentication request

To get an access token, use the request an access token operation with your client_id and client_secret.

Include the audience and grant_type as shown in the example below.

The value of the audience field is based on URN syntax.

Format: urn:ripplexcurrent-ENVIRONMENT_STRING:YOUR_TENANT_ID

Example: urn:ripplexcurrent-test:YOUR_TENANT_ID

{
  • "client_id": "{YOUR_CLIENT_ID}",
  • "client_secret": "{YOUR_CLIENT_SECRET}",
  • "audience": "urn:ripplexcurrent-prod:{YOUR_TENANT_ID}",
  • "grant_type": "client_credentials"
}

Authentication response

Store the access_token for use with all other API operations.
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ",
  • "scope": "identities:create identities:read identities:write quote_collections:write payments:accept payments:read routing_table:lookup",
  • "expires_in": 3600,
  • "token_type": "Bearer"
}



Create an identity

You need to create an identity for the beneficiary or sending party so they can be identified in the payment request.

Identity request body

This example uses the create a new identity operation to create a new identity of the type BENEFICIARY.
  • identityType : This example uses BENEFICIARY to create a beneficiary identity.
  • nickName : This example uses a recognizable name such as Successful Beneficiary.
  • piiData : Populate this object with the required PII information for the chosen identityType.
application/json
{
  • "identityType": "BENEFICIARY",
  • "nickName": "Successful Beneficiary",
  • "piiData": {
    • "Cdtr": {
      },
    • "CdtrAcct": {
      },
    • "CdtrAgt": {
      }
    }
}

Identity response

Store the identityId value for use later with the accept quote operation. The accept quote operation's request body requires a user_info object containing this value as the sender_token property.
{
  • "identityId": "22222222-aaaa-2222-bbbb-222222222222",
  • "version": 2
}
Tip
You can use the identityId with the get an identity by ID operation to view the newly created identity.



Get a payout method

You need to find the payout method that's available in the target destination for a given currency.

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.
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&global=true' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Payout method response

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.
{
  • "id": "235b9711-cf8c-44ea-85aa-11dbbfcfde8b",
  • "destination_address": "rn.sgp.exampleReceiver",
  • "payout_method": "CSM_EU_EUR_SEPA"
}



Create a quote collection

Get a collection of quotes containing one or more quotes for a payment using the chosen payout method.

Create quote collection request

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 whose value is the payment_method value received from the Get a payout method operation.
  • The receiving_address field whose value is the destination_address value received from 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 : This example uses 10000.
  • currency : This example uses USD.
  • quote_type : This example uses 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.
Note
Contact your Ripple liaison to receive your sending_address.

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. Each quote object contains a unique quote_id, and several quote elements containing the fees associated with the payment.
{
  • "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

This example uses the accept a quote operation to start the payment process.

Accept quote request

Prerequisite
You must have the quote_id of the quote you want to accept from the create a quote response.

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 user_info properties.
    • sender_token : Set this value to the identityId UUID associated with the sender 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 EMIN to indicate that the Source of Cash is employment income.
  • 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": {
    • "sender_token": "12345678-abcd-1234-abcd-123456789123",
    • "beneficiary_token": "11111111-abcd-2222-efgh-333333333333",
    • "purpose": "PAYR",
    • "SourceOfCash": "EMIN"
    },
  • "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 to look up the status of a payment.

Payment request

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