Stablecoin Payout

Create a payout for a beneficiary using cryptocurrency.

You can create a payout for a beneficiary with a cryptocurrency wallet. You can disburse the payout in stablecoin, a type of cryptocurrency.

Common use cases may include:

A payout to an employee
A payout to a supplier
A cross-border payout to a contractor

Stablecoin Payout Workflow

Step 1: Getting Payout Information

You request to List Payout Methods by Country to get supported payout methods.
Rapyd returns the list of supported payout types.
You call Get Payout Method Required Fields to get required fields to be completed.
Rapyd returns the list of required fields to be passed for processing.

Step 2: Processing the Payout

You call Create Payout and pass required fields.
Rapyd processes the payout.
The funds are credited to the beneficiary crypto wallet.
Rapyd sends notification of completed Payout.

How a Stablecoin Payout Works

Finding Payout Method Types

You need to find payout method types that match your criteria, such as the payout country and currency.

In this example, you'll find payout method types that support transfers in stablecoin to a beneficiary in Belgium.

For that, you'll use List Payout Method Types with the following parameters:

Description of Query Parameters

Query Parameter	Description
category	Enter ewallet as the category of the payout method.
beneficiary_country	Enter BE as the code for Belgium, the beneficiary's country.
payout_currency	Enter USDC as the code for stablecoin, the currency received by the beneficiary.

List Payout Method Types provides examples of the request and response.

Finding Required Fields for the Payout Method Type

You need to find the required fields for the xx_stablecoin_ewallet payout method type.

For that, you'll use Get Payout Required Fields with the following parameters:

Note

USDC is the only supported currency for this payout method.

Description of Path Parameters

Path Parameter	Description
payout_method_type	Enter xx_stablecoin_ewallet as the payout method type.

Description of Query Parameters

Query Parameter	Description
sender_country	Enter AU as the code for Australia, the sender's country.
sender_currency	Enter USD as the code for United States Dollar, the sender's currency.
beneficiary_country	Enter BE as the code for Belgium, the beneficiary's country.
payout_currency	Enter USDC as the code for stablecoin, the currency received by the beneficiary.
sender_entity_type	Enter company as the type of entity for the sender.
beneficiary_entity_type	Enter company as the type of entity for the beneficiary.
payout_amount	Enter 15 as the amount received by the beneficiary.

Get Payout Required Fields shows an example of the request and response.

Tip

Use Validate Beneficiary to check the beneficiary fields before you request the payout. See Validating Beneficiary Details.

Requesting a Payout

Use Create Payout with the following parameters:

Description of Body Parameters

Body Parameter	Description
amount	Enter 15 as the amount received by the beneficiary.
payout_method_type	Enter xx_stablecoin_ewallet as the payout method type.
sender_currency	Enter USD as the code for United States Dollar, the sender's currency.
sender_country	Enter AU as the code for Australia, the sender's country.
beneficiary_country	Enter BE as the code for Belgium, the beneficiary's country. This field is not required.
payout_currency	Enter USDC as the code for stablecoin, the currency received by the beneficiary.
sender_entity_type	Enter ‘company’ as the type of entity for the sender.
beneficiary_entity_type	Enter ‘company’ as the type of entity for the beneficiary.
beneficiary	Enter a 'beneficiary' object that has the following fields: company_name - company identification_value - company first_name - individual last_name - individual date_of_birth - individual crypto_wallet_address crypto_wallet_protocol - Possible values: Ethereum (ERC20) BNB Smart Chain (BEP20) Polygon (POLYGON) address - individual or company city - individual or company country - individual or company
sender	Enter a 'sender' object that has the following fields: company_name - company
description	Enter ‘salary payout’ as the description of the payout transaction.

Create Payout Request

Request

// Request URL: POST https://sandboxapi.rapyd.net/v1/payouts

// Message body: 

{
        "amount": 15,
        "beneficiary": {
          "company_name": "Bene Company",
          "crypto_wallet_address": "0x02ae6765C6991813a3EAa86fe63ebBCA1c9EC156",
          "crypto_wallet_protocol": "ERC20",
          "address": "a2123",
          "city": "test",
          "country": "DE",
          "identification_value": "31425791789"
        },
        "beneficiary_country": "BE",
        "beneficiary_entity_type": "company",
        "payout_currency": "USDC",
        "payout_method_type": "xx_stablecoin_ewallet",
        "sender": {
          "company_name": "Sen"
        },
        "confirm_automatically": true,
        "sender_country": "AU",
        "sender_currency": "USD",
        "sender_entity_type": "company",
        "description": "new description"      
}

Create Payout Response

Response

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "2b9f713f-0710-48d5-9cc8-559cd8980a00"
    },
    "data": {
        "id": "payout_97247402357168cb96af1f637c50ef16",
        "payout_type": "ewallet",
        "payout_method_type": "xx_stablecoin_ewallet",
        "amount": 15,
        "payout_currency": "USDC",
        "sender_amount": 16.28,
        "sender_currency": "USD",
        "status": "Created",
        "sender_country": "AU",
        "sender": {
            "id": "sender_ad97cb5c91de8bf5ddab4673904f8a6b",
            "country": "AU",
            "entity_type": "company",
            "name": "Sen",
            "company_name": "Sen",
            "currency": "USD"
        },
        "beneficiary_country": "BE",
        "beneficiary": {
            "id": "beneficiary_269a4dcdde6ccc408dfc8af3379b5096",
            "country": "DE",
            "entity_type": "company",
            "address": "a2123",
            "name": "Bene Company",
            "city": "test",
            "company_name": "Bene Company",
            "currency": "USDC",
            "identification_value": "***********",
            "crypto_wallet_address": "0x02ae6765C6991813a3EAa86fe63ebBCA1c9EC156",
            "crypto_wallet_protocol": "ERC20"
        },
        "fx_rate": 0.9215,
        "instructions": [
            {
                "name": "instructions",
                "steps": [
                    {
                        "step1": "The funds will be transferred to the Crypto wallet address of the beneficiary"
                    }
                ]
            }
        ],
        "ewallets": [
            {
                "ewallet_id": "ewallet_c4bb3c5ae31339a86490096b73075860",
                "amount": 16.28,
                "percent": 100
            }
        ],
        "metadata": {},
        "description": "new description",
        "created_at": 1743602136,
        "payout_fees": null,
        "expiration": null,
        "paid_at": null,
        "identifier_type": null,
        "identifier_value": null,
        "error": null,
        "paid_amount": 0,
        "statement_descriptor": null,
        "gc_error_code": null,
        "batch_file": null,
        "estimated_time_of_arrival": "The beneficiary will receive the funds within few minutes.",
        "crypto_payout_hash": null
    }
}

Besides parameter values that you entered in the request, the data section of this response shows:

The id of the 'payout' object is payout_97247402357168cb96af1f637c50ef16. Webhooks that relate to this payout refer to this ID.
The payout_type is ewallet.
Under sender:
- The id is sender_ad97cb5c91de8bf5ddab4673904f8a6b.
- Fields of the 'sender' object are listed.
Under beneficiary:
- The id is beneficiary_269a4dcdde6ccc408dfc8af3379b5096.
- Fields of the 'beneficiary' object are listed.
Note: The value for the crypto_payout_hash field can be used to look up the transaction on the relevant network and provide proof of payment.

Closing the Transaction

Simulating Payout Completion

The sandbox does not directly simulate the action of the beneficiary receiving the payout funds. You can simulate this action with the procedure described in Complete Payout. For this, you will need the payout ID and payout amount that you generated in your sandbox.

When a payout completion is simulated, Rapyd sends a webhook. Configure your system to receive webhooks with the procedure described in Defining a Webhook Endpoint

After you simulate that the payout was accepted, Rapyd sends you Webhook - Payout Completed. The webhook confirms that the payout was completed.

In this section:

Documentation