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
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.
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:
{
"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 currencyreference
: 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"
}
Was this page helpful?