Payout APIs Overview

​

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

​

Integration Flow

HitPay simplifies the complex payout process with two straightforward APIs:

​

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.

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.

{
  "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"
}