Payout APIs Overview

Guide to using the APIs to payout to any of your beneficiaries

The Payout APIs are currently only available for Singapore, Malaysia and Philippines businesses.

Overview

This guide helps you understand how to add a beneficiary and initiate a payout. It’s an essential tool for platforms and businesses that need to pay suppliers or other entities.

Example Use Cases

These APIs are designed for a variety of payment scenarios, including:

• Paying suppliers
• Employee payroll
• Automating commission payouts to partners

Integrate these APIs for efficient and secure payouts.

Integration Flow

HitPay simplifies the complex payout process with two straightforward APIs:

Create Beneficiary

Start by creating a Beneficiary in your system.

Initiate a Transfer

With the Beneficiary set up, you can initiate the transfer.

Create Beneficiary

A beneficiary is a person or business receiving the funds. HitPay currently supports local beneficiaries, enabling payouts within the same country and region. It’s important to note that the information needed to create a beneficiary is not the same for all countries, so it’s best practice to always use the ‘Get Schema’ API to see the exact parameters needed for creating a beneficiary. The type of transfer, for example, Local or Swift, also depends on the beneficiary that you add. So make sure to add the right beneficiary before initiating the transfer.

Get Schema

API To get the Beneficiary Schema

Network Coverage

List of Networks and Rails Supported

To create your beneficiary with the details you’ve gathered, use the following API as described below:

Endpoint

POST https://api.sandbox.hit-pay.com/v1/beneficiaries

Request Body

Below are sample requests for creating beneficiaries in Malaysia and the Philippines:

• Singapore
• Malaysia
• Philippines

{
  "is_external": false,
  "country": "SG",
  "currency": "SGD",
  "nickname": "Paper Supplier",
  "remark": "to be paid monthly",
  "holder_type": "company",
  "holder_name": "Big Paper Company",
  "transfer_method": "local",
  "bank_id": "DBSSSGSGXXX",
  "bank_branch_code": "050",
  "account_number": "1234567890"
}

Response

The response includes the beneficiary’s details. Store the id for initiating transfers:

{
  "id": "99a0f5bc-4ff5-413e-a2a8-ffd780a144c9",
  "country": "sg",
  "currency": "sgd",
  "transfer_method": "local",
  "nickname": "Paper Supplier",
  "holder_name": "Big Paper Company",
  "holder_type": "company",
  "bank_id": "ABNASG2AXXX[7010]",
  "bank_code": "7010",
  "branch_code": "050",
  "bank_swift_code": "ABNASG2AXXX",
  "bank_routing_number": "7010-050",
  "account_number": "1234567890",
  "is_deleted": false,
  "created_at": "2023-07-12T20:46:05+08:00",
  "updated_at": "2023-07-12T20:46:05+08:00",
  "deleted_at": null
}

Initiate a Transfer

Once a beneficiary is created, you can easily initiate a transfer to send funds. Make sure you have the beneficiary id obtained from the previous step to proceed.

Endpoint

POST https://api.sandbox.hit-pay.com/v1/transfers

Request Body

{
  "beneficiary_id": "99a0f5bc-4ff5-413e-a2a8-ffd780a144c9",
  "source_amount": 100,
  "reference": "Invoice Payment #123"
}

• beneficiary_id: The unique identifier of the beneficiary you want to send the funds to.
• source_amount: The amount of money you wish to transfer. The currency will be same as the beneficiary currency
• reference: An optional field for adding notes or references related to the transfer.

Response

The response provides the details of the initiated transfer including its status and the detailed information of the beneficiary. Always check the status field to confirm if the transfer requires additional actions or is processed.

{
  "id": "99a1085b-46d0-49e2-83d5-17cc87750232",
  "beneficiary": {
    "id": "99a1085b-39f7-49f6-9c17-8c8e031015f4",
    "country": "us",
    "currency": "sgd",
    "transfer_method": null,
    "nickname": null,
    "holder_name": "Miss Keira Keebler Sr.",
    "holder_type": "individual",
    "bank_id": "FAKESWIFT",
    "bank_swift_code": "FAKESWIFT",
    "bank_routing_number": "test",
    "account_number": "0123456789",
    "is_deleted": false,
    "created_at": "2023-07-12T21:38:09+08:00",
    "updated_at": "2023-07-12T21:38:09+08:00",
    "deleted_at": null
  },
  "currency": "sgd",
  "amount": 100,
  "remark": "Test SGD transfer to US",
  "status": "requires_admin_action",
  "source_type": null,
  "created_at": "2023-07-12T21:38:09+08:00"
}

Statuses and Webhooks

The completion of the transfer API call doesn’t necessarily mean that the funds have reached the beneficiaries. In most cases, the status will immediately change to “pending” after initiating a transfer because bank transfers are not instant.

To be notified about the transfer status, you need to subscribe to the “Payout” webhook event. Click here to learn more about listening to events.

• requires_admin_action: The transfer needs a manual review or additional actions.
• processed: The transfer has been processed, and the funds have been sent to the beneficiary.
• failed: The transfer failed for reasons such as insufficient funds, incorrect beneficiary details, etc.

Sample Webhook Payload

{
  "id": "98f2a4dd-7685-409c-8f6e-a504760a533e",
  "bank_name": null,
  "bank_switf_code": null,
  "bank_swift_code": null,
  "bank_account_number": "acct_233mmmuNxCM62r",
  "currency": "sgd",
  "amount": 1636.16,
  "remark": "HitPay Payouts for 2023-04-17",
  "status": "paid",
  "source_type": null,
  "created_at": "2023-04-17T05:05:54+08:00"
}