Paying Vendors with the Rapyd Disburse API

[Community_Team]

By Daniel Olaogun

The world has become more interconnected than ever, which has also changed the way people think and do business with each other. Thanks to the internet, large and small organizations alike employ talent internationally, freelancers collaborate globally, and companies do business with each other across oceans with ease.

However, despite the global nature of modern business, companies and employers still face challenges disbursing funds to their vendors in different parts of the world. Transferring funds worldwide can be complex, and companies are always looking for solutions that fit their needs and use cases.

One such solution is Rapyd Disburse, a global payout platform that allows businesses to pay freelancers, contractors, employers, and other companies worldwide.

Rapyd Disburse enables you to send payments to more than a hundred countries, making it possible to pay your employees, vendors, and hired contractors directly in any part of the globe. Furthermore, it also gives you the functionality to send funds directly to their local bank account.

There are two ways of using the Rapyd Disburse platform: through the secured client platform to send payouts, or by integrating the Rapyd Disburse API into your company’s financial application. How you use the platform will depend on your use case.

This article explains how you can integrate the Rapyd Disburse API into your application using Node.js.

What Is the Rapyd Disburse API?

The Rapyd Disburse API allows you to integrate your application with the Disburse APIs to easily transfer funds from your wallet to other services outside of the Rapyd system.

The Rapyd Disburse API opens a world of possibilities for business. For instance, your company can integrate the API with your in-house payroll solution to pay each employee at a specific time each month without needing further intervention; this makes paying your employees easy and flexible and frees you or the person in charge to perform other responsibilities.

Other use cases for the Rapyd Disburse API include:

• Automatic transfer of employee salaries directly into their bank account
• Payment of services provided by vendors and contractors
• Sending funds directly to individuals across the world

Payout to Bank Account Workflow

Payout to your employees’ bank accounts is easy and seamless with Rapyd. It allows you to transfer employees’ salaries from any wallet to your employees’ bank accounts.

Here’s how it works.

You have your human resource management (HRM) application registered on the Rapyd platform, and you’ve also created a wallet specifically for the payment of salaries.

On the website, your HR or Payroll Manager can initiate a request from the salary wallet to the employees’ bank account. Furthermore, you can automate this process to specify the date your HRM application should initiate payouts to your employees.

Once the payout is triggered, Rapyd processes the payout to the employees’ bank account and notifies your HRM application of successful completion; it also notifies the application should an error occur during payout processing.

The notification from Rapyd to your HRM application is made possible by your application webhook, which you also configure on Rapyd.

Integrating the Rapyd Disburse API in Node.js

Using the Express framework, you’ll create a simple Node.js application that handles different Rapyd Disburse functionality requests. You’ll also learn how to set up additional HTTP requests for managing the following functionalities:

• Listing payout method types
• Getting payout required fields
• Creating a Beneficiary (optional if recurring payout or reusing contact)
• Creating a payout request
• Closing a payout transaction

Prerequisites

You must have a Rapyd account to get started. If you don’t, you should first sign up for a Rapyd account. Complete the registration form, verify your email and complete the multifactor authentication. Once that’s done, you gain access to your dashboard.

Additionally, you should have Node.js installed on the host machine that will serve the application.

Getting Your API Keys

Log in to your dashboard and toggle your environment from production to sandbox by clicking the toggle button at the bottom left of the screen; this allows you to test and perform multiple API calls and experiments with the Disburse APIs in a sandbox environment.

Once you’ve switched to the sandbox, return to the home page and click View API Keys.

You’ll use the credentials on this page to build your API request headers.

Setting Up Your Application

Using your preferred code editor, create a directory for your sample Disburse application, move into the directory, and create an index.js file.

Open a terminal that points to the same directory and run npm init -y to create a default package.json file. Next, you install the Express framework:

npm install express

After installation, in your index.js file, paste the following:

const express = require('express')
const app = express();
const PORT = 3000;

app.use(express.urlencoded({ extended: false }));
app.use(express.json());

app.get('/', (req, res) => {
  res.json('Hello, Welcome to Disburse API Sandbox')
})

app.listen(PORT, function(err){
  if (err) console.log(err);
  console.log("Server listening on PORT", PORT);
});

Start the server by running node index.js, and have a server running on port 3000. If you visit http://localhost:3000, you should receive a response like the following:

Hello, Welcome to Disburse API Sandbox

This is the starting point of the application. As you proceed with the article, you’ll add other endpoints for the different Disburse API functionalities.

Setting Up Request Authorization

When you want to make a request to the Disburse API from your application, you need to attach extra credentials to the header of your request; this ensures that the Disburse server recognizes you and returns a response to your request. Part of the credentials you will include in your headers consists of the following:

• The Access key, retrieved from the API page.
• the timestamp of when the request is initiated.
• salt, which is randomly generated data to secure your data requests.
• signatures, which will be used to validate the integrity and authenticity of your requests.

In your application directory, create a file named utilities.js and paste the content of this link into the file.

At the top of the utilities.js file, replace the accessKey and secretKey from the APIs page.

For security reasons, it’s advisable to load the keys from an env file or secrets manager; it’s not advisable to expose secret keys directly in your codebase.

Now that you’ve configured your request authorization and application, it’s time to implement some of the Disburse API functionalities in your application.

Making a Request to List Payout Method Types

You can use Payout method types to list the available payout methods and preferred currency in a beneficiary country on the Rapyd platform. For instance, you can fetch the available methods for USD payout in the US.

In the index.js file, you create a new GET API for fetching the payout method types. In the callback, you request the Disburse payout method API /payouts/supported_types using the makeRequest function, which you import from the utilities.js file into the index.js file.

You pass the following parameters: beneficiary_country and payout_currency. These are sufficient to retrieve the results you need. However, you can include other parameters to get specific results.

You can read more on the Payout Method API and the parameters you can pass to get particular results.

The description above should result in the following code sample:

const { makeRequest } = require('./utilities') // Move to the top of the index.js file

app.get('/payout-method-types', async (req, res) => {
  try {
    const {beneficiary_country, payout_currency} = req.query
    const result = await makeRequest('GET', `/v1/payouts/supported_types?beneficiary_country=${beneficiary_country}&payout_currency=${payout_currency}`);
    res.json(result);
  } catch (error) {
    res.json(error);
  }
})

Initially, you ran node index.js to test the first API, terminate the process, and rerun it so that node could process your new changes. However, if you don’t want to perform this action every time you update your code, you can install nodemon.

Now make a request to http://localhost:3000/payout-method-types?beneficiary_country=US&payout_currency=USD; you should receive a response similar to the following:

{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "status": {
      "error_code": "",
      "status": "SUCCESS",
      "message": "",
      "response_code": "",
      "operation_id": "b9ce5424-c526-40b1-9053-f9ee9daeecff"
    },
    "data": [
      {...},
      {
        "payout_method_type": "us_atmdebit_card",
        "name": "ATM Debit",
        "is_cancelable": 0,
        "is_expirable": 0,
        "is_location_specific": 0,
        "status": 1,
        "image": "/checkout/us_atmdebit_card.png",
        "category": "card",
        "beneficiary_country": "US",
        "sender_country": "*",
        "payout_currencies": [
          "USD"
        ],
        "sender_entity_types": [
          "company",
          "individual"
        ],
        "beneficiary_entity_types": [
          "company",
          "individual"
        ],
        "amount_range_per_currency": [
          {
            "maximum_amount": null,
            "minimum_amount": null,
            "payout_currency": "USD"
          }
        ],
        "minimum_expiration_seconds": null,
        "maximum_expiration_seconds": null,
        "sender_currencies": [
          "SGD",
          "*"
        ]
      },
      {...},
      {...},
      {...}
    ]
  }
}

Now that you’ve seen how to make a secured request to the Disburse APIs, you can follow the same pattern for the remaining Disburse functionalities you want to implement in the app.

Making a Request to Get Payout Required Fields

Using the API request you created, you’ve retrieved the payout methods available in the beneficiaries’ country and currency. Next, you’ll create another API to fetch the required fields to make a payout.

From the response of the Payout Method Type functionality, you use us_atmdebit_card for your preferred payout mode for this example. As seen below, you must fetch the required fields using the attributes associated with the us_atmdebit_card response. Copy the code in your index.js file:

app.get('/payout-required-fields', async (req, res) => {
  try {
    const { 
      sender_country, 
      sender_currency, 
      beneficiary_country, 
      payout_currency, 
      sender_entity_type, 
      beneficiary_entity_type, 
      payout_amount,
      payout_method_type
    } = req.query

    const result = await makeRequest('GET', `/v1/payouts/${payout_method_type}/details?sender_country=${sender_country}&sender_currency=${sender_currency}&beneficiary_country=${beneficiary_country}&payout_currency=${payout_currency}&sender_entity_type=${sender_entity_type}&beneficiary_entity_type=${beneficiary_entity_type}&payout_amount=${payout_amount}`);
    res.json(result);
  } catch (error) {
    res.json(error);
  }
})

Then, make a request to http://localhost:3000/payout-required-fields?sender_country=US&sender_currency=USD&beneficiary_country=US&payout_currency=USD&sender_entity_type=individual&beneficiary_entity_type=individual&payout_method_type=us_atmdebit_card&payout_amount=1000.

You should receive a success response showing the required fields to use in the chosen payout method:

{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "status": {...},
    "data": {
      "payout_method_type": "us_atmdebit_card",
      "sender_currency": "*",
      "sender_country": "*",
      "sender_entity_type": "individual",
      "beneficiary_country": "us",
      "payout_currency": "USD",
      "beneficiary_entity_type": "individual",
      "is_cancelable": 0,
      "is_location_specific": 0,
      "is_expirable": 0,
      "minimum_expiration_seconds": null,
      "maximum_expiration_seconds": null,
      "is_online": null,
      "image": "/checkout/us_atmdebit_card.png",
      "status": 1,
      "beneficiary_required_fields": [...],
      "sender_required_fields": [],
      "payout_options": [],
      "minimum_amount": 0,
      "maximum_amount": 0,
      "batch_file_header": "payout_method_type,sender_currency,payout_currency,beneficiary.email,beneficiary.card_number,beneficiary.card_expiration_month,beneficiary.card_expiration_year,beneficiary.card_cvv,beneficiary.company_name,beneficiary.postcode"
    }
  }
}

Creating a Beneficiary (Optional)

Creating a Beneficiary is useful in making recurring payouts to an entity such as clients, employees, contractors, and so on. However, if you don’t need to make a recurring payout, you can move on to the next section.

You first create a POST API for this functionality:

app.post('/beneficiary', async (req, res) => {
  try {
    
    const result = await makeRequest('POST','/v1/payouts/beneficiary' , req.body);
    res.json(result);
  } catch (error) {
    res.json(error);
  }
})

Using the Create Beneficiary reference from the official documentation, you then create a new Beneficiary by making a POST request with your beneficiary details using any API client of your choice, for example, Postman or Insomnia:

POST http://localhost:3000/beneficiary

Body: {
    "category": "bank",
    "default_payout_method_type": "us_wires_bank",
    "country": "US",
    "currency": "USD",
    "entity_type": "individual",
    "first_name": "John",
    "identification_type": "work permit",
    "identification_value": "6658412",
    "last_name": "Doe",
    "payment_type": "regular",
    "address": "123 Main Street",
    "city": "NY",
    "postcode": "12345",
    "account_number": "1234567890",
    "merchant_reference_id": "JohnDoeOffice",
    "company_name": "CompanyTest",
    "bank_account_type": "CACC"
}

You’ll get a response similar to the following:

{
  "statusCode": 200,
  "headers": {...},
  "body": {
    "status": {...},
    "data": {
      "id": "beneficiary_5041383b70a112f4e7aebbb95e4281a7",
      "last_name": "Doe",
      "first_name": "John",
      "country": "US",
      "entity_type": "individual",
      "address": "123 Main Street",
      "name": "John Doe",
      "postcode": "12345",
      "city": "NY",
      "company_name": "CompanyTest",
      "account_number": "1234567890",
      "currency": "USD",
      "identification_type": "work permit",
      "identification_value": "6658412",
      "merchant_reference_id": "JohnDoeOffice",
      "bank_account_type": "CACC",
      "payment_type": "regular",
      "category": "bank",
      "default_payout_method_type": "us_wires_bank"
    }
  }
}

Creating a Payout Request

You can use the information you’ve learned how to retrieve, including payout method types and the preferred payout required fields, to initiate a payout request.

You make a payout request via us_atmdebit_card (the payout method you selected), while including the required fields for processing the transaction.

In your index.js file, paste the following code:

app.post('/payouts', async (req, res) => {
  try {
    
    const result = await makeRequest('POST','/v1/payouts' , req.body);
    res.json(result);
  } catch (error) {
    res.json(error);
  }
})

Then make a POST request to your application’s payouts API at http://localhost:3000/payouts. You can use the JSON body below, but replace the value of eWallet in the post details value with a wallet in your Rapyd account:

{
    "beneficiary": {
        "email": "sandboxtest@rapyd.net",
        "card_number": "4111111111111111",
        "card_expiration_month": "11",
        "card_expiration_year": "2024",
        "card_cvv": "123",
        "company_name": "Test Company",
        "postcode": "56789"
    },
    "beneficiary_country": "US",
    "beneficiary_entity_type": "individual",
    "description": "desc1562234632",
    "payout_method_type": "us_atmdebit_card",
    "ewallet": "ewallet_d2888b33cd11503eb660a1ee9f996e32",
    "metadata": {
        "merchant_defined": true
    },
    "payout_amount": "2.66",
    "payout_currency": "USD",
    "sender": {
        "first_name": "John",
        "last_name": "Doe",
        "identification_type": "work_permit",
        "identification_value": "asdasd123123",
        "phone_number": "19019019011",
        "occupation": "plumber",
        "source_of_income": "business",
        "date_of_birth": "11/12/1913",
        "address": "1 Main Street",
        "purpose_code": "investment_income",
        "beneficiary_relationship": "spouse"
    },
    "sender_country": "US",
    "sender_currency": "USD",
    "sender_entity_type": "individual"
}

You’ll get a response similar to the below:

{
    "status": {...},
    "data": {
        "id": "payout_074b9370a0b53fb3b7d0ff303de47e4f",
        "payout_type": "card",
        "payout_method_type": "us_atmdebit_card",
        "amount": 2.66,
        "payout_currency": "USD",
        "sender_amount": 2.66,
        "sender_currency": "USD",
        "status": "Completed",
        "sender_country": "US",
        "sender": {...},
        "beneficiary_country": "US",
        "beneficiary": {...},
        "fx_rate": 1,
        "instructions": {...},
        "ewallets": [...],
        "metadata": {... },
        "description": "desc1562234632",
        "created_at": 1654273149,
        "payout_fees": null,
        "expiration": null,
        "merchant_reference_id": "",
        "paid_at": null,
        "identifier_type": null,
        "identifier_value": null,
        "error": null,
        "paid_amount": 2.66,
        "statement_descriptor": null,
        "gc_error_code": null
    }
}

Closing a Payout Transaction

Once the beneficiary receives the payout funds, your configured PAYOUT_COMPLETED webhook is triggered; however, if the payout method requires the confirmation of a third-party application to complete the process, then the webhook is triggered when the third-party application completes the process.

You can follow the webhook guide for more information on how they can be configured.

The response sent to the webhook should be similar to the JSON data below:

{
    "id": "wh_dde9a153560da4c135f02fa1092f4a5c",
    "data": {
        "id": "payout_8bd651b2bb56380430f1852d1066d863",
        "error": null,
        "amount": 20,
        "sender": {
            "id": "sender_56ed0d8f333e2e88692877859d21b1e4",
            "country": "RU",
            "currency": "USD",
            "entity_type": "company"
        },
        "status": "Completed",
        "fx_rate": 1,
        "paid_at": "1631520050",
        "ewallets": [{
                "amount": 20,
                "percent": 100,
                "ewallet_id": "ewallet_d75ba0bebd3a580d3cc958dbff4948b7"
            }
        ],
        "metadata": {},
        "created_at": 1631520047,
        "expiration": null,
        "beneficiary": {
            "id": "beneficiary_681f977be051d1ca90dc3f9286560055",
            "country": "RU",
            "currency": "USD",
            "entity_type": "individual",
            "phone_number": "42773664"
        },
        "description": null,
        "paid_amount": 20,
        "payout_fees": null,
        "payout_type": "ewallet",
        "instructions": {
            "name": "instructions",
            "steps": [{
                    "step1": "The funds will be transferred to the provided account details of the beneficiary ."
                }
            ]
        },
        "gc_error_code": null,
        "sender_amount": 20,
        "sender_country": "RU",
        "identifier_type": null,
        "payout_currency": "USD",
        "sender_currency": "USD",
        "identifier_value": null,
        "instructions_value": {},
        "payout_method_type": "ru_qiwi_ewallet",
        "beneficiary_country": "RU",
        "statement_descriptor": null,
        "merchant_reference_id": null
    },
    "type": "PAYOUT_COMPLETED",
    "status": "NEW",
    "created_at": 1631520050,
    "trigger_operation_id": "fab8a244-cc7c-407a-b57d-21385eecad4d"
}

Next, you simulate the action of a third-party application completing the process. In your index.js file, paste the following code:

app.post('/simulate-payouts/:payout/:amount', async (req, res) => {
  try {
    const {payout, amount} = req.params;

    const result = await makeRequest('POST',`/v1/payouts/complete/${payout}/${amount}`,);
    res.json(result);
  } catch (error) {
    res.json(error);
  }
})

Then, make a request to the simulate-payouts API you created with the required parameters, and you’ll get a response similar to the webhook sample response data above.

Conclusion

Rapyd Disburse provides you with APIs that you can integrate into your application to automatically disburse payouts to your clients, employees, contractors, and so on. In this article, you learned how to form your request headers and initiate payouts via the Disburse APIs.

The Rapyd platform is not limited to Rapyd Disburse; it also provides other payment solutions that make sending and collecting payment easy worldwide.

Other payment solutions Rapyd offers include Rapyd Wallet, which lets you receive and send money using a digital wallet, and Rapyd Collect, which is a payment solution that allows you to collect funds from your customers and transfer them to your merchant wallet, other Rapyd wallets, or external cards.