Skip to main content

Documentation

Create Beneficiary

Create a beneficiary for use in payouts.

The response provides a unique beneficiary ID, which you can use in place of the beneficiary object for Create Payout

This method triggers the Beneficiary Created Webhook webhook. This webhook contains the same information as the response.

Note

In addition to the required fields documented below, you must include all other fields listed for the beneficiary in the response to Get Payout Required Fields, and you must conform to the regex provided.

To create a beneficiary that you can use with multiple payout methods, include all fields that are required by each payout method. The client is responsible for including all required fields.

The additional fields used in the Create Beneficiary - individual example are for the ca_general_bank payout method. The additional fields used in the Create Beneficiary - company example are for the us_ach_bank payout method.

Code Samples
    • .NET

      • using System;
        using System.Text.Json;
        
        namespace RapydApiRequestSample
        {
            class Program
            {
                static void Main(string[] args)
                {
                    try
                    {
                        var requestObj = new
                        {
                            category = "bank",                    
                            country = "CA",
                            currency = "USD",
                            entity_type = "individual",
                            first_name = "John",
                            identification_type = "identification_id",
                            identification_value = "123456789",
                            last_name = "Doe",
                            payment_type = "priority",
                            address = "1 Main Street",
                            city = "Montreal",
                            state = "Quebec",
                            postcode = "12345",
                            account_number = "1234567",
                            merchant_reference_id = "JDoe",
                            bic_swift = "12345678XXX"
                        };
        
                        string request = JsonSerializer.Serialize(requestObj);
        
                        string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/payouts/beneficiary", request);
        
                        Console.WriteLine(result);
                    }
                    catch (Exception e)
                    {
                        Console.WriteLine("Error completing request: " + e.Message);
                    }
                }
            }
        }
    • JavaScript

      • const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;
        
        async function main() {
          try {
            const body = {
              category: 'bank',
              country: 'CA',
              currency: 'USD',
              entity_type: 'individual',
              first_name: 'John',
              identification_type: 'identification_id',
              identification_value: '123456789',
              last_name: 'Doe',
              payment_type: 'priority',
              address: '1 Main Street',
              city: 'Montreal',
              state: 'Quebec',
              postcode: '12345',
              account_number: '1234567',
              merchant_reference_id: 'JDoe',
              bic_swift: '12345678XXX'
            };
            const result = await makeRequest('POST', '/v1/payouts/beneficiary', body);
        
            console.log(result);
          } catch (error) {
            console.error('Error completing request', error);
          }
        }
    • PHP

      • <?php
        $path = $_SERVER['DOCUMENT_ROOT'];
        $path .= "/<path-to-your-utility-file>/utilities.php";
        include($path);
        $beneficiary = [
            "category" => "bank",
            "country" => "CA",
            "currency" => "USD",
            "entity_type" => "individual",
            "first_name" => "John",
            "identification_type" => "identification_id",
            "identification_value" => "123456789",
            "last_name" => "Doe",
            "payment_type" => "priority",
            "address" => "1 Main Street",
            "city" => "Montreal",
            "state" => "Quebec",
            "postcode" => "12345",
            "account_number" => "1234567",
            "merchant_reference_id" => "JDoe",
            "bic_swift" => "12345678XXX"
        ];
        
        try {
            $object = make_request('post', '/v1/payouts/beneficiary', $beneficiary);
            var_dump($object);
        } catch(Exception $e) {
            echo "Error: $e";
        }
        ?>
    • Python

      • from pprint import pprint
        
        from utilities import make_request
        
        beneficiary_details = {
            "category": "bank",
            "country": "CA",
            "currency": "USD",
            "entity_type": "individual",
            "first_name": "John",
            "identification_type": "identification_id",
            "identification_value": "123456789",
            "last_name": "Doe",
            "payment_type": "priority",
            "address": "1 Main Street",
            "city": "Montreal",
            "state": "Quebec",
            "postcode": "12345",
            "account_number": "1234567",
            "merchant_reference_id": "JDoe",
            "bic_swift": "12345678XXX"
        }
        
        result = make_request(method='post',
                              path='/v1/payouts/beneficiary',
                              body=beneficiary_details)
        pprint(result)
  • /v1/payouts/beneficiary

  • Create Beneficiary - individual

  • curl -X post
    https://sandboxapi.rapyd.net/v1/payouts/beneficiary
    -H 'access_key: your-access-key-here'
    -H 'Content-Type: application/json'
    -H 'idempotency: your-idempotency-parameter-here'
    -H 'salt: your-random-string-here'
    -H 'signature: your-calculated-signature-here'
    -H 'timestamp: your-unix-timestamp-here'
    -d '{
        "category": "bank",
        "country": "CA",
        "currency": "USD",
        "entity_type": "individual",
        "first_name": "John",
        "last_name": "Doe",
        "identification_type": "identification_id",
        "identification_value": "123456789",
        "default_payout_method_type": "ca_general_bank",	
        "merchant_reference_id": "JohnDoe",
    // Fields from 'beneficiary_required_fields' in the response to 'Get Payout Method Type Required Fields'
        "payment_type": "priority",
        "address": "1 Main Street",
        "city": "Montreal",
        "state": "Quebec",
        "postcode": "12345",
        "account_number": "1234567",
        "bic_swift": "12345678XXX"
    }
    '
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "c63dbcc5-4bdf-49b5-907e-1320184bde74"
        },
        "data": {
            "id": "beneficiary_9a49c928c059886341898699992112d2",
            "last_name": "Doe",
            "first_name": "John",
            "country": "CA",
            "entity_type": "individual",
            "address": "1 Main Street",
            "name": "John Doe",
            "postcode": "12345",
            "city": "Montreal",
            "state": "Quebec",
            "account_number": "1234567",
            "currency": "USD",
            "identification_type": "identification_id",
            "identification_value": "*********",
            "merchant_reference_id": "JohnDoe",
            "bic_swift": "12345678XXX",
            "payment_type": "priority",
            "category": "bank",
            "default_payout_method_type": "ca_general_bank"
        }
    }
  • Create Beneficiary - company

  • curl -X post
    https://sandboxapi.rapyd.net/v1/payouts/beneficiary
    -H 'access_key: your-access-key-here'
    -H 'Content-Type: application/json'
    -H 'idempotency: your-idempotency-parameter-here'
    -H 'salt: your-random-string-here'
    -H 'signature: your-calculated-signature-here'
    -H 'timestamp: your-unix-timestamp-here'
    -d '{
        "category": "bank",
        "company_name": "All Star Limousine",
        "country": "US",
        "currency": "USD",
        "entity_type": "company",
        "identification_type": "company_registered_number",
        "identification_value": "9876543210",
        "merchant_reference_id": "AllStarLimo",
    // Fields from 'beneficiary_required_fields' in the response to 'Get Payout Method Type Required Fields'
        "account_number": "0987654321",
        "aba": "987654321"
    }
    '
    
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "54a91bf6-00a8-4838-b1ee-28dfb815797b"
        },
        "data": {
            "id": "beneficiary_d895d90d276869efe1e359386a1fb3e3",
            "country": "US",
            "entity_type": "company",
            "name": "All Star Limousine",
            "company_name": "All Star Limousine",
            "account_number": "0987654321",
            "currency": "USD",
            "identification_type": "company_registered_number",
            "identification_value": "9876543210",
            "bank_name": "All Star Limousine",
            "merchant_reference_id": "AllStarLimo",
            "aba": "987654321",
            "category": "bank"
        }
    }
  • Create Beneficiary - rapyd_ewallet confirmation required

  • curl -X post
    https://sandboxapi.rapyd.net/v1/payouts/beneficiary
    -H 'access_key: your-access-key-here'
    -H 'Content-Type: application/json'
    -H 'idempotency: your-idempotency-parameter-here'
    -H 'salt: your-random-string-here'
    -H 'signature: your-calculated-signature-here'
    -H 'timestamp: your-unix-timestamp-here'
    -d '{
        "category": "rapyd_ewallet",
        "currency": "USD",
    // Fields from 'beneficiary_required_fields' in the response to 'Get Payout Method Type Required Fields'
        "confirmation_required": true,
        "ewallet": "ewallet_3801e782955b29955445586a2405a5db"
    }
    '
    
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "81026979-6ae7-49bc-9130-3226691df46b"
        },
        "data": {
            "id": "beneficiary_f7cd32a5bc72e1deb490f380683f4256",
            "currency": "USD",
            "ewallet": "ewallet_3801e782955b29955445586a2405a5db",
            "confirmation_required": true,
            "category": "rapyd_ewallet"
        }
    }
  • Create Beneficiary with card_id

  • curl -X post
    https://sandboxapi.rapyd.net/v1/payouts/beneficiary
    -H 'access_key: your-access-key-here'
    -H 'Content-Type: application/json'
    -H 'idempotency: your-idempotency-parameter-here'
    -H 'salt: your-random-string-here'
    -H 'signature: your-calculated-signature-here'
    -H 'timestamp: your-unix-timestamp-here'
    -d '{
        "category": "card",
        "country": "US",
        "currency": "USD",
        "entity_type": "individual",
        "first_name": "John",
        "last_name": "Doe",
        "identification_type": "work permit",
        "identification_value": "6658412",
        "merchant_reference_id": "JohnDoeOffice",
    // Fields from 'beneficiary_required_fields' in the response to 'Get Payout Method Type Required Fields'
        "payment_type": "regular",
        "address": "123 Main Street",
        "city": "NY",
        "postcode": "12345",
        "card_id": "card_28b1dc9999123aba49703ee82f57ccb3"
    }
    '
    
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "8acf3c5c-ff1a-48ec-b5e9-79d6abe5642c"
        },
        "data": {
            "id": "beneficiary_4d13aa2f3ef76536a6b4062d127475ce",
            "last_name": "Doe",
            "first_name": "John",
            "country": "US",
            "entity_type": "individual",
            "address": "123 Main Street",
            "name": "John Doe",
            "postcode": "12345",
            "city": "NY",
            "currency": "USD",
            "identification_type": "work permit",
            "identification_value": "*******",
            "merchant_reference_id": "JohnDoeOffice",
            "card_expiration_year": "23",
            "card_expiration_month": "10",
            "card_number": "0001",
            "payment_type": "regular",
            "category": "card"
        }    
    }
  • Create Beneficiary with card details

  • curl -X post
    https://sandboxapi.rapyd.net/v1/payouts/beneficiary
    -H 'access_key: your-access-key-here'
    -H 'Content-Type: application/json'
    -H 'idempotency: your-idempotency-parameter-here'
    -H 'salt: your-random-string-here'
    -H 'signature: your-calculated-signature-here'
    -H 'timestamp: your-unix-timestamp-here'
    -d '
    {
        "category": "card",
        "country": "CA",
        "currency": "USD",
        "entity_type": "individual",
        "first_name": "John",
        "last_name": "Doe",
        "identification_type": "identification_id",
        "identification_value": "123456789",
        "default_payout_method_type": "us_visa_card",
        "email": "janedoe@Rapyd.net ",
        "card_number": "4111111111111111",
        "card_expiration_month": "11",
        "card_expiration_year": "24",
        "card_cvv": "123",
        "merchant_reference_id": "JohnDoe",
        "payment_type": "priority",
        "address": "1 Main Street",
        "city": "Montreal",
        "state": "Quebec",
        "postcode": "12345"   
    }
    '
    
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "b2d2721c-d6d1-4954-a2bf-8c5aac2a86c4"
        },
        "data": {
            "id": "beneficiary_03db3e06ed883087b59cb8da12afc33f",
            "last_name": "Doe",
            "first_name": "John",
            "country": "CA",
            "entity_type": "individual",
            "address": "1 Main Street",
            "name": "John Doe",
            "postcode": "12345",
            "city": "Montreal",
            "state": "Quebec",
            "currency": "USD",
            "email": "janedoe@Rapyd.net ",
            "identification_type": "identification_id",
            "identification_value": "*********",
            "merchant_reference_id": "JohnDoe",
            "bin_details": {
                "type": "CREDIT",
                "brand": "VISA",
                "level": null,
                "issuer": "JPMORGAN CHASE BANK, N.A.",
                "country": "US",
                "bin_number": "411111"
            },
            "card_expiration_year": "24",
            "card_expiration_month": "11",
            "card_number": "1111",
            "payment_type": "priority",
            "category": "card",
            "default_payout_method_type": "us_visa_card"
        }
    }