Sign UpLog In

Disbursement APIs

Brick Disbursement product helps sending money out to users, We support disbursements to banks and eWallets accounts.

If you have not created the Brick account till now, Please feel to create a new account from here.

Brick always believes in upgrading their platform to provide the best experience. Following this, We have added support of the BI-Fast Payment method in our system.

Sending Funds

Sending funds via Brick allows you to perform digital fund transfers. Brick currently supports fund transfers to bank accounts, e-wallets, and virtual accounts. You can check the list of available institutions for disbursement and limits per transaction here.

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. Generate a JWT bearer token (Public Access Token)

Use your Sandbox API keys: ClientId & ClientSecret with the payment public token API generation to get a JWT (JSON Web Token).This JWT or what we call a public access token is needed to call all payment-related APIs. Please note that the public access token is valid for 5 minutes and can be used for one time only. 

curl --request GET \
     --url https://sandbox.onebrick.io/v2/payments/auth/token \
     --header 'Accept: application/json' \
     -u "clientId:clientSecret"

3. 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 --request GET \
     --url https://sandbox.onebrick.io/v2/payments/gs/bank-account-validation?accountNumber=accountNumber&bankShortCode=bankShortCode \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'publicAccessToken: Bearer publicAccessToken' \

{
  "status": 200,
  "data": {
    "message": "We are successfully able to verify the account",
    "accountNo": "123456789",
    "accountName": "PROD ONLY",
    "bankShortCode": "PERMATA"
  },
  "metaData": {
    "source": "API",
    "entity": "Payment"
  },
  "error": null
}

4. 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 --request POST \
     --url https://sandbox.onebrick.io/v2/payments/gs/disbursements \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'publicAccessToken: Bearer publicAccessToken' \
     --data '{
    "amount": 10000,
    "referenceId": "referenceId-1",
    "description": "description-1",
    "disbursementMethod": {
        "type": "bank_transfer",
        "bankShortCode": "12345678",
        "bankAccountNo": "BCA",
        "bankAccountHolderName": "PROD ONLY"
    }
}'

{
  "status": 200,
  "data": {
    "message": "We have received your request and are processing it, please check your callback URL for transaction status",
    "id": "a0123sdd23fsd32sds23",
    "type": "disbursement",
    "attributes": {
      "referenceId": "referenceId-1",
      "description": "description-1",
      "amount": "10000",
      "status": "processing",
      "settlementStatus":"reversed",
      "createdAt": "2022-07-21T13:49:39.752+07:00",
      "disbursementMethod": {
        "type": "bank_transfer",
        "bankAccountNo": "12345678",
        "bankShortCode": "BCA",
        "bankAccountHolderName": "PROD ONLY"
      }
    }
  },
  "metaData": {
    "source": "API",
    "entity": "Payment"
  },
  "error": null
}

Settlement status can be Hanging, Revered, or null. If the balance is settled back due to failure of the transaction then it will be marked as Reversed, If the balance is settle back due to transaction was hanged in mid then it will be marked as Hanging and the value will be null for all other cases.

5. 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. Please setup Disbursement callback via Dashboard. 

{
  "data": {
    "id": "a0123sdd23fsd32sds23",
    "type": "disbursement",
    "attributes": {
      "referenceId": "referenceId-1",
      "description": "description-1",
      "amount": "29999.0",
      "status": "completed",
      "settlementStatus":"null",
      "createdAt": "2022-07-26T11:06:49+07:00",
      "disbursementMethod": {
        "type": "bank_transfer",
        "bankAccountNo": "12345678",
        "bankShortCode": "MANDIRI",
        "bankAccountHolderName": "PROD ONLY",
        "bankName": "BCA"
      }
    }
  }
}



{
  "data": {
    "id": "65f929a62bb14c6caa6dfa2f8",
    "type": "disbursement",
    "attributes": {
      "referenceId": "dodo-26aug-test-11",
      "description": "semoga berhasil",
      "amount": "39999",
      "status": "failed",
      "settlementStatus":"reversed",
      "createdAt": "2022-08-26T10:45:56.000+07:00",
      "errorCode": "unexpected_behaviour",
      "errorReason": "We are facing some problem, Please reach out to Brick support team.",
      "disbursementMethod": {
        "type": "bank_transfer",
        "bankAccountNo": "123456789",
        "bankShortCode": "LINKAJA",
        "bankAccountHolderName": "PROD ONLY",
        "bankName": ""
      }
    }
  }
}

📘

Testing Callback in Sandbox

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 with accountNo: 2100000 OR bankShortCode: "AGRIS" -> will change status to "failed" + callback
b. Completed status test: "amount": 29999, accountNo can be any random valid number, same goes for bankShortCode -> will change status to "completed" + callback

6. Retrieve the data of your disbursement

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

curl --request GET \
     --url https://sandbox.onebrick.io/v2/payments/gs/disbursements/{id} \
     --header 'Accept: application/json' \
     --header 'publicAccessToken: Bearer publicAccessToken'

{
  "status": 200,
  "data": {
    "message": "We have received your request and are processing it, please check your callback URL for transaction status",
    "id": "a0123sdd23fsd32sds23",
    "type": "disbursement",
    "attributes": {
      "referenceId": "referenceId-1",
      "description": "description-1",
      "amount": "10000",
      "settlementStatus":"reversed",
      "status": "processing",
      "createdAt": "2022-07-21T13:49:39.752+07:00",
      "disbursementMethod": {
        "type": "bank_transfer",
        "bankAccountNo": "12345678",
        "bankShortCode": "BCA",
        "bankAccountHolderName": "PROD ONLY"
      }
    }
  },
  "metaData": {
    "source": "API",
    "entity": "Payment"
  },
  "error": null
}

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.

Updated 3 months ago

What’s Next

Both Account Validation API & Disbursement API can be found here