Disbursement APIs

Learn how to send funds fuss-free and automatically on your platform with Brick's Disbursement APIs.

📘

Note

Make sure that you have signed up for a Brick developer account with API keys generated.

Sending Funds

Sending funds via Brick allows you to perform digital fund transfers. Brick currently supports fund transfers to bank accounts (please find the complete list here) and e-wallets (via virtual accounts), with other methods of fund disbursements coming soon!

Before you can send out funds, you will need to make sure that there are sufficient funds in your account with Brick for disbursements to be possible. To do that, make a deposit of funds to your Brick account.

Create Disbursements to send funds

1. Make sure that you have enough funds in your Brick account

If there aren't enough funds, and you're not approved for sufficient credit make sure you deposit money to your Brick account.

2. Check the validity of the Financial Institution account you intend to send to

Before you request a fund transfer, make sure to check that the receiving Financial Institution account belongs to the person you intend to send to!

You can do this using our Account Verification API . Check that the name of the bank account owner is the name of the person you intend to send money to.

curl -X POST {{url}}/payments/bank-account-validation
     -d '{"accountNumber" : "accountNumber","bankShortCode" : "BCA"}'
     -H 'Content-Type: application/json' 
     -H 'Authorization:Bearer public-access-token'
{
    "status": 200,
    "message": "OK",
    "data": {
        "accountName": "PROD ONLY",
        "accountNo": "1213214123",
        "bankShortCode": "BCA"
    }
}

3. Request for a Disbursement once you're sure of the Financial Institution account validity

Create a disbursement by calling the Disbursement API with the following parameters:

  • amount
  • referenceId
  • description
  • type
  • bank short code
  • bank account number
  • bank account holder name
curl -X POST {{url}}/payments/disbursements
     -d '{"amount" : 10000, "referenceId": "referenceId", "description": "description", "disbursementMethod": {"type" : "bank_transfer", "bankShortCode" : "BCA", "bankAccountNo": "123123", "bankAccountHolderName" : "Name"}}'
     -H 'Content-Type: application/json' 
     -H 'Authorization:Bearer public-access-token'
{
    "status": 200,
    "message": "OK",
    "data": {
        "id": "contract_538e2252caec483bb388e129dc62ad36",
        "type": "disbursement",
        "attributes": {
            "referenceId": "referenceId",
            "description": "description",
            "amount": "10000.0",
            "status": "processing",
            "createdAt": "2021-07-05T09:02:28.000+00:00",
            "disbursementMethod": {
                "type": "bank_transfer",
                "bankAccountNo": "123123",
                "bankShortCode": "BCA",
                "bankAccountHolderName": "Name",
                "serverBankAccountHolderName": "PROD ONLY",
                "bankName": "Bank Central Asia"
            }
        }
    }
}

4. Brick notifies you of the status of the Disbursement via callbacks

Once the disbursement status is confirmed, Brick will notify your platform with callbacks that will notify you of the status of the Disbursement. You need to register your callback URLs to Brick on the integration process.

{
    "data": {
        "id": "contract_bd07b1260d92457ca11eb87c0f3e81d5",
        "type": "disbursement",
        "attributes": {
            "referenceId": "987123",
            "description": "pay utang",
            "amount": "10000.0",
            "status": "processing",
            "createdAt": "2021-07-05T07:55:45.000+00:00",
            "disbursementMethod": {
                "type": "bank_transfer",
                "bankAccountNo": "123123",
                "bankShortCode": "BCA",
                "bankAccountHolderName": "Test",
                "serverBankAccountHolderName": "PROD ONLY",
                "bankName": "Bank Central Asia"
            }
}

📘

Testing Callback

Callbacks are sent when there are changes in transaction status. It will be sent automatically in production, but in Sandbox, because there is no real transaction happening, how callbacks are triggered is different.

Special value, Some parameter value in sandbox can automatically change status and send callback:
a. Failed status test: "amount": 39999 -> will change status to "failed" + callback
b. Completed status test: "amount": 29999 -> will change status to "completed" + callback

5. Retrieve the data of your disbursement

You can see your disbursement information whenever you like, by using your disbursement id in the parameter.

curl {{url}}/payments/disbursements/contract_bd07b1260d92457ca11eb87c0f3e81d5
     -H 'Authorization:Bearer public-access-token'
{
    "status": 200,
    "message": "OK",
    "data": {
        "id": "contract_bd07b1260d92457ca11eb87c0f3e81d5",
        "type": "disbursement",
        "attributes": {
            "referenceId": "987123",
            "description": "pay utang",
            "amount": "10000.0",
            "status": "processing",
            "createdAt": "2021-07-05T07:55:45.000+00:00",
            "disbursementMethod": {
                "type": "bank_transfer",
                "bankAccountNo": "123123",
                "bankShortCode": "BCA",
                "bankAccountHolderName": "Test",
                "serverBankAccountHolderName": "PROD ONLY",
                "bankName": "Bank Central Asia"
            }
        }
    }
}

Disbursement Statuses

Payment status changes based on various scenarios, such as whether the payment succeeds or fails.

Learn about the different statuses, and what to do at each stage of a payment's life cycle here.

Pending

  • A Disbursement has been created successfully.
  • Brick will send instructions to make the fund transfers to the specified destination.

Processing

  • Brick has sent instructions to make the fund transfers, awaiting confirmation that the fund transfers are complete.

Failed

Reasons

Disbursements can fail for various reasons.
Requested fund transfers can sometimes be declined by the payment network, or a congested payment network may not respond successfully.
Other reasons could be errors made during the disbursement request.

Handling Failed Disbursements

If you did not receive a response, or the request timed out, you may attempt to safely retry the disbursement with the same referenceId.

If a disbursement has failed, take note of the error code and message. Try to rectify any issues with the API request and try again with a new referenceId.

Completed

The disbursement has successfully completed.


What’s Next

Both Account Validation API & Disbursement API can be found here

Did this page help you?