Create Disbursement

Endpoint URL : https://disburse.sandbox.bnk.to/v1/disbursements
Method : POST

Endpoint Brief

Initiates a new disbursement to transfer funds from your source corporate bank account to beneficiaries. Create Disbursement endpoint supports multiple fund transfers within a single disbursement order from a single source of fund or a corporate bank account.

For testing purposes, use Brankas sandbox baseURL. For UAT and live disbursement, use Brankas live baseURL. Sandbox and live baseURL are available here.

Sample Request

Sample provided is the request payload in the sandbox environment.

curl -X POST https://disburse.sandbox.bnk.to/v1/disbursements \ 
-H 'x-api-key: EtT6UI126a6KR7OTWbj1lXeUrYE6EHM5srbZI4NfbhkNjiwnLSNTl4A1gLp9eABC' \ 
-H 'Content-Type: application/json' \ 
-d '{
  "credentials": {
  	"BRANKAS_TEST_CLIENT": {
  		"identifier": "brankas-test",
  		"secret": "brankas-test-secret"
  	},
    	"BRANKAS_TEST_PARTNER": {
  		"identifier": "user+7@example.com",
  		"secret": "user+7"
  	}
  },
  "disbursements": [
    {
    	 "corporate_id": "brankas",
        "reference_id": "22082021002001",
        "type": "ON_DEMAND",
        "source_account": {
            "bank": "DUMMY_BANK_CORPORATE",
            "number": "11111111",
            "holder_name": "PT Brankas Teknologi Indonesia"
        },
        "source_amount": {
            "cur": "IDR"
        },
	 "destination_account": {
            "bank": "DUMMY_DESTINATION_BANK",
            "number": "1234000012340000",
            "holder_name": "Brankas Teknologi Indonesia"
        },
        “description":"merchant defined description",
        "destination_amount": {
            "num": "10000000",
            "cur": "IDR"
        }
    }
  ]'
}
Parameter Required Description
credentials yes Credentials object
credentials.key yes Credential specific keys for specific Brankas Partner Bank, for example : ID: BCA_CLIENT/BCA_PARTNER
PH: UBP_CLIENT/UBP_PARTNER
credentials.key.identifier yes The identifier/user id for the credential
credentials.key.secret yes Secret for the credential
credentials.key.corporate_id yes unique id for the organization given by bank (applicable for UBP)
disbursements yes Disbursements object
disbursements.corporate_id yes For UBP:
Merchant name, merchant defined
For BNI, Permata, BCA :
unique id for the organization given by bank
disbursements.reference_id yes Merchant-generated unique ID. Maximum 40 chars
disbursements.type yes Type of disbursement: ON_DEMANDor FUTURE
disbursements.source_account yes Source account object
disbursements.source_account.bank yes Source account bank name. Follow the list here
disbursements.source_account.number yes Source account number
disbursements.source_account.holder_name yes Source account holder name
disbursements.source_amount yes Source amount object
disbursements.source_amount.cur yes Source account currency
disbursements.destination_account yes Destination account object
disbursements.destination_account.bank yes Beneficiary account bank name. Follow the list here
disbursements.destination_account.number yes Beneficiary account number
disbursements.destination_account.holder_name yes Beneficiary account holder name
disbursements.destination_account.address Conditional Beneficiary address object. This object is used for interbank disbursement via Pesonet / Instapay in the Philippines. Required in PH.
disbursements.description Optional Merchant description for disbursement
disbursements.destination_amount yes Destination amount object
disbursements.destination_amount.num yes Amount of disbursement
(in cents) i.e. 340,20
disbursements.destination_amount.cur yes Beneficiary account currency i.e. PHP, IDR

Credentials Object

The following section shows the credentials object that is applicable to each Brankas Partner Banks that will be applicable in the LIVE environment.

Bank Name Country Credentials Object
Union Bank Philippines PH

  "credentials": {
    "UBP_CLIENT": {
    "identifier": "[clientId]",
  "secret": "[clientSecret]"
    },
    "UBP_PARTNER_ACCOUNT": {
  "identifier": "[accountId]",
  "secret": "[accountPassword]",
    "corporate_id": "[partnerId]"
    }
  }

                
Bank Central Asia (BCA) ID

"credentials": {
  "BCA_CLIENT": {
    "identifier": "[clientId]",
  "secret": "[clientSecret]"
  },
  "BCA_API": {
  "identifier": "[apiKey]",
  "secret": "[apiSecret]",
  "corporate_id":"[corporateId]"
  }
}

                
Bank Negara Indonesia (BNI) ID

"credentials": {
  "BNI_CLIENT": {
    "identifier": "[clientId]",
  "secret": "[clientSecret]"
  }
}

                
Bank Permata ID

"credentials": {
  "PERMATA_CLIENT": {
    "identifier": "[clientId]",
  "secret": "[clientSecret]"
  },
  "PERMATA_API": {
  "identifier": "[apiKey]",
  "secret": "[apiSecret]",
  }
}

                
Credentials object also applicable for Update External Status endpoint in the Philippines.

Sample Response

Sample provided is the response payload in the sandbox environment.

Response Payload
{
  "result": [
    {
      "disbursement": {
        "corporate_id": "brankas",
        "reference_id": "22082021002001",
        "type": "ON_DEMAND",
        "source_account": {
          "bank": "DUMMY_BANK_CORPORATE",
          "number": "11111111",
          "holder_name": "PT Brankas Teknologi Indonesia"
        },
        "destination_account": {
          "bank": "DUMMY_DESTINATION_BANK",
          "number": "1234000012340000",
          "holder_name": "Brankas Teknologi Indonesia",
          "address": {
            "line1": "Address line 01",
            "line2": "Address line 02",
            "city": "City Name",
            "province": "Province Name",
            "zip_code": "12345",
            "country": "Country Name"
          }
        },
        "source_amount": {
          "cur": "IDR"
        },
        "destination_amount": {
          "cur": "IDR",
          "num": "10000000"
        },
        "Description":"merchant defined description",
        "fees": {},
        "disbursement_id": "dd09f0e6-a576-4442-a3b4-2bb4adc4cfaf",
        "external": {
          "reference_id": "294835"
        },
        "status": "SUCCESS",
        "created": "2021-08-22T16:08:03.390Z",
        "updated": "2021-08-22T16:08:03.390Z",
        "processed": "2021-08-22T16:08:03.390Z",
        "batch_id": "474da23a-37a0-49af-bb9e-537ab3ef2dba"
      },
      "result": {
        "success": true
      }
    }
  ]
}
Parameter Description
result.disbursement Disbursements object
result.disbursement.corporate_id Merchant name, merchant defined
result.disbursement.reference_id Merchant-generated unique ID. Maximum 40 chars
result.disbursement.type Type of disbursement:
ON_DEMANDor FUTURE
result.disbursement.source_account Source account object
result.disbursement.source_account.bank Source account bank name. Follow the list here
result.disbursement.source_account.number Source account number
result.disbursement.source_account.holder_name Source account holder name
result.disbursement.destination_account Destination account object
result.disbursement.destination_account.bank Beneficiary account bank name. Follow the list here
result.disbursement.destination_account.number Beneficiary account number
result.disbursement.destination_account.holder_name Beneficiary account holder name
result.disbursement.destination_account.address Beneficiary address object.

This object is used for interbank disbursement via Pesonet / Instapay in the Philippines. Required in PH.
result.disbursement.source_amount Source amount object
result.disbursement.source_amount.cur Source account currency
result.disbursement.destination_amount Destination amount object
result.disbursement.destination_amount.cur Amount of disbursement
(in cents)

i.e. 340,20
result.disbursement.destination_amount.num Beneficiary account currency

i.e. PHP, IDR
result.disbursement.description Merchant description for disbursement
result.disbursement.fees Associated fees for the disbursement
result.disbursement.fees.name The name of the fee
result.disbursement.fees.amount The amount of the fee
result.disbursement.fees.cur The currency of the fee
result.disbursement.disbursement_id Unique ID for the related disbursement within the batch
result.disbursement.external External info from bank object
result.disbursement.external.reference_id Reference ID returned from bank API or link to receipt
result.disbursement.status The status of the disbursement. List of disbursement status available here
result.disbursement.created The creation time of the disbursement (GMT)
result.disbursement.updated The last updated time of the disbursement (GMT)
result.disbursement.processed The processed time when the disbursement was sent to the bank(GMT)
result.disbursement.batch_id Unique ID for this the batch
result.result The endpoint request result object
result.result.success Indicate that the request to Brankas endpoint was successful. i.e.

 "result": {
     "success": true,
     "Message": "success message"
 }

result.result.message The success message of the response
result.result.error Indicate there is an error with the request to Brankas endpoint. i.e.

"result": {
  "error": [
    {
      "code":"XX",
      "Message":"error message"
    }
  ]
}

result.result.error.code The error code of the response
result.result.error.message The error message of the response

Response codes

Parameter Description
200 Request executed successfully.
404 Returned when the resource is not found.
400 Returned when the request body is malformatted or does not match the expected request.
401 Returned when the request does not contain the user’s credentials.
403 Returned when the user does not have permission to access the resource.
500 Returned when an unexpected error occurred on the server side.

Retrieve Disbursement

Endpoint URL : https://disburse.sandbox.bnk.to/v1/disbursements
Method : GET

Endpoint Brief

Retrieve all the disbursements with or without a given filter. Disbursements can be filtered by date or disbursement ids.

The following filters are applicable when required:

Filter Related Parameter Notes
Filter by disbursement ID result.disbursement.disbursement_id
Filter by batch ID result.disbursement.batch_id
Filter by Created Date result.disbursement.created Date range

The following parameters are used to apply the filter:

Params Description
disbursement_request_id Unique ID of the batch
disbursement_ids Unique ID of the related disbursement within the batch
start_date.year Start date year
start_date.month Start date month (1-12)
start_date.day Start date day (1-31)
end_date.year End date year
end_date.month End date month (1-12)
end_date.day End date day (1-31)

Sample Request

Sample provided is the request payload in the sandbox environment.

Request Payload

curl -X GET https://disburse.sandbox.bnk.to/v1/disbursements \
-H 'x-api-key: EtT6UI126a6KR7OTWbj1lXeUrYE6EHM5srbZI4NfbhkNjiwnLSNTl4A1gLp9eABC'

Simply add your api key to access the lists of disbursement. Alternatively, you can apply filter using params as the sample request shows below.

Request Payload

curl -X GET https://disburse.sandbox.bnk.to/v1/disbursements?disbursement_request_id=18c2ad55-ebc3-430e-890f-b4bb349fef5e \
-H 'x-api-key: EtT6UI126a6KR7OTWbj1lXeUrYE6EHM5srbZI4NfbhkNjiwnLSNTl4A1gLp9eABC'

Sample Request

Response Payload

{
"disbursements": [
  {
    "corporate_id": "brankas",
    "reference_id": "22082021002001",
    "type": "ON_DEMAND",
    "source_account": {
      "bank": "DUMMY_BANK_CORPORATE",
      "number": "11111111",
      "holder_name": "PT Brankas Teknologi Indonesia"
    },
    "destination_account": {
      "bank": "DUMMY_DESTINATION_BANK",
      "number": "************0000",
      "holder_name": "Brankas Teknologi Indonesia",
      "address": {
        "line1": "Address line 01",
        "line2": "Address line 02",
        "city": "City Name",
        "province": "Province Name",
        "zip_code": "12345",
        "country": "Country Name"
      }
    },
    "source_amount": {
      "cur": "IDR"
    },
    "destination_amount": {
      "cur": "IDR",
      "num": "10000000"
    },
    "description":"merchant defined description",
    "fees": {},
    "disbursement_id": "dd09f0e6-a576-4442-a3b4-2bb4adc4cfaf",
    "external": {
      "reference_id": "294835"
    },
    "status": "SUCCESS",
    "created": "2021-08-22T16:08:03.390Z",
    "updated": "2021-08-22T16:08:03.390Z",
    "processed": "2021-08-22T16:08:03.390Z",
    "batch_id": "474da23a-37a0-49af-bb9e-537ab3ef2dba"
  }
"total_record": 1
}
Parameter Description
disbursements Disbursements object
disbursements.corporate_id Merchant name, merchant defined
disbursements.reference_id Merchant-generated unique ID. Maximum 40 chars
disbursements.type Type of disbursement:
ON_DEMANDor FUTURE
disbursements.source_account Source account object
disbursements.source_account.bank Source account bank name. Follow the list here
disbursements.source_account.number Source account number
disbursements.source_account.holder_name Source account holder name
disbursements.destination_account Destination account object
disbursements.destination_account.bank Beneficiary account bank name. Follow the list here
disbursements.destination_account.number Beneficiary account number
disbursements.destination_account.holder_name Beneficiary account holder name
disbursements.destination_account.address Beneficiary address object.

This object is used for interbank disbursement via Pesonet / Instapay in the Philippines. Required in PH.
disbursements.source_amount Source amount object
disbursements.source_amount.cur Source account currency
disbursements.destination_amount Destination amount object
disbursements.destination_amount.cur Amount of disbursement
(in cents)

i.e. 340,20
disbursements.destination_amount.num Beneficiary account currency

i.e. PHP, IDR
disbursements.description Merchant description for disbursement
disbursements.fees Associated fees for the disbursement
disbursements.fees.name The name of the fee
disbursements.fees.amount The amount of the fee
disbursements.fees.cur The currency of the fee
disbursements.disbursement_id Unique ID for the related disbursement within the batch
disbursements.external External info from bank object
result.disbursement.external.reference_id Reference ID returned from bank API or link to receipt
result.disbursement.status The status of the disbursement. List of disbursement status available here

This endpoint will return the last status returned by Brankas.
result.disbursement.created The creation time of the disbursement (GMT)
result.disbursement.updated The last updated time of the disbursement (GMT)
result.disbursement.processed The processed time when the disbursement was sent to the bank(GMT)
disbursements.batch_id Unique ID for this the batch
total_record Count of disbursements retrieved on a particular request

Response Codes

Parameter Description
200 Request executed successfully.
404 Returned when the resource is not found.
400 Returned when the request body is malformatted or does not match the expected request.
401 Returned when the request does not contain the user’s credentials.
403 Returned when the user does not have permission to access the resource.
500 Returned when an unexpected error occurred on the server side.

Update External Status

Endpoint URL : https://disburse.sandbox.bnk.to/v1/disbursements/external-status-updates
Method : POST

Endpoint Brief

Allows merchants to request the latest status of a particular transaction. If a merchant encounters non-final status on Brankas Create Disbursement endpoint, the merchant should check the latest status of the related disbursement request by calling this endpoint.

This endpoint is only applicable for PH market and transactions issued with UBP_CORPORATE value set in source_account.bank

Merchants can do status checks for a single batch or one or more disbursements.

Sample Request

Request Payload
curl -X POST https://disburse.sandbox.bnk.to/v1/disbursements/external-status-updates \
-H 'x-api-key: EtT6UI126a6KR7OTWbj1lXeUrYE6EHM5srbZI4NfbhkNjiwnLSNTl4A1gLp9eABC' \
-H 'Content-Type: application/json' \
-d '{
  "credentials": {
    "UBP_CLIENT": {
      "identifier": "client_id_provided_by_UBP",
      "secret": "client_secret_provided_by_UBP"
    },
    "UBP_PARTNER_ACCOUNT": {
      "identifier": "account_username_provided_by_UBP",
      "secret": "account_password_provided_by_UBP",
      "corporate_id": "corporate_id_provided_by_UBP"
    }
  },
  "disbursement_request_id": "f8b04d0b-4bea-4551-a118-070df7fe5d89",
  "disbursement_ids": [
    "8043d7e3-e672-494a-ae59-c9bb6bd2b97b"
  ]
}'
Parameter Required Description
credentials yes Credentials object
credentials.key yes Credential specific keys for specific Brankas Partner Bank, only UBP_CLIENT& UBP_PARTNER are applicable for this endpoint.
credentials.key.identifier yes The identifier/user id for the credential
credentials.key.secret yes Secret for the credential
credentials.key.corporate_id yes unique id for the organization given by bank (applicable for UBP, BNI, Permata)
disbursement_request_id optional Unique ID for the batch that requires a status check.


Sending this parameter will return all disbursements within the related batch.

This parameter acts independently to the disbursement_id parameter
disbursement_id optional Unique ID(s) for the related disbursement within a single batch

This parameter acts independently to the disbursement_request_id parameter

Note that the credentials will be based on the source bank which sample you can find here.

Sample Response

Response Payload
{
"result": [
  {
  "disbursement": {
    "corporate_id": "brankas",
    "reference_id": "22082021002001",
    "type": "ON_DEMAND",
    "source_account": {
      "bank": "UNIONBANK_CORPORATE",
      "number": "123456789012",
      "holder_name": "Merchant Company Inc."
    },
    "destination_account": {
      "bank": "PH_UB",
      "number": "********2907",
      "holder_name": "Beneficiary Name",
      "address": {
        "line1": "Address line 01",
        "line2": "Address line 02",
        "city": "City Name",
        "province": "Province Name",
        "zip_code": "12345",
        "country": "Country Name"
      }
    },
    "source_amount": {
      "cur": "PHP"
    },
    "destination_amount": {
      "cur": "PHP",
      "num": "700.00"
    },
    "description": "merchant defined description",
    "fees": {},
    "disbursement_id": "8043d7e3-e672-494a-ae59-c9bb6bd2b97b",
    "external": {
      "reference_id": "UB966102"
    },
    "status": "SUCCESS",
    "created": "2021-08-23T04:13:15.383Z",
    "updated": "2021-08-23T07:45:23.497Z",
    "processed": "2021-08-23T04:13:15.383Z",
    "batch_id": "22d543cd-5729-411d-8d55-6cf9afcd98ce"
  },
Parameter Description
result.disbursement Disbursements object
result.disbursement.corporate_id Merchant name, merchant defined
result.disbursement.reference_id Merchant-generated unique ID. Maximum 40 chars
result.disbursement.type Type of disbursement:
ON_DEMANDor FUTURE
result.disbursement.source_account Source account object
result.disbursement.source_account.bank Source account bank name. Follow the list here
result.disbursement.source_account.number Source account number
result.disbursement.source_account.holder_name Source account holder name
result.disbursement.destination_account Destination account object
result.disbursement.destination_account.bank Beneficiary account bank name. Follow the list here
result.disbursement.destination_account.number Beneficiary account number
result.disbursement.destination_account.holder_name Beneficiary account holder name
result.disbursement.destination_account.address Beneficiary address object.

This object is used for interbank disbursement via Pesonet / Instapay in the Philippines. Required in PH.
result.disbursement.source_amount Source amount object
result.disbursement.source_amount.cur Source account currency
result.disbursement.destination_amount Destination amount object
result.disbursement.destination_amount.cur Amount of disbursement
(in cents)

i.e. 340,20
result.disbursement.destination_amount.num Beneficiary account currency

i.e. PHP, IDR
result.disbursement.description Merchant description for disbursement
result.disbursement.fees Associated fees for the disbursement
result.disbursement.fees.name The name of the fee
result.disbursement.fees.amount The amount of the fee
result.disbursement.fees.cur The currency of the fee
result.disbursement.disbursement_id Unique ID for the related disbursement within the batch
result.disbursement.external External info from bank object
result.disbursement.external.reference_id Reference ID returned from bank API or link to receipt
result.disbursement.status The status of the disbursement. List of disbursement status available here

This endpoint will return the most recent status of the disbursement.
result.disbursement.created The creation time of the disbursement (GMT)
result.disbursement.updated The last updated time of the disbursement (GMT)
result.disbursement.processed The processed time when the disbursement was sent to the bank(GMT)
result.disbursement.batch_id Unique ID for this the batch
result.result The endpoint request result object
result.result.success Indicate that the request to Brankas endpoint was successful. i.e.

"result": {
  "success": true,
  "Message": "success message"
 }

result.result.message The success message of the response
result.result.error Indicate there is an error with the request to Brankas endpoint. i.e.

"result": {
  "error": [
    {
      "code":"XX",
      "Message":"error message"
    }
  ]
 }

result.result.error.code The error code of the response
result.result.error.message The error message of the response

Response Codes

Parameter Description
200 Request executed successfully.
404 Returned when the resource is not found.
400 Returned when the request body is malformatted or does not match the expected request.
401 Returned when the request does not contain the user’s credentials.
403 Returned when the user does not have permission to access the resource.
500 Returned when an unexpected error occurred on the server side.

Account Inquiry

Endpoint URL : https://disburse.sandbox.bnk.to/v1/disbursements/account-inquiry
Method : POST

Endpoint Brief

Allows merchants to do inquiry of the destination account / beneficiary account before executing a disbursement.

Currently only applicable for ID market and ID destination banks.

Sample Request

Request Payload
curl -X PUT https://disburse.sandbox.bnk.to/v1/disbursements/account-inquiry \
-H 'x-api-key: EtT6UI126a6KR7OTWbj1lXeUrYE6EHM5srbZI4NfbhkNjiwnLSNTl4A1gLp9eABC' \
-H 'Content-Type: application/json' \
-d '{
  "bank_account": {
    "bank": "DUMMY_DESTINATION_BANK",
    "number": "8581319920"
  }'
}
Parameter Description
bank_account.bank Beneficiary account bank name. Follow the list here
bank_account.number Beneficiary account number

Sample Request

{
  "result": {
    "success": true
   },
  "bank_account": { 
    "bank": "DUMMY_DESTINATION_BANK",
    "number": "8581319920",
    "holder_name": "NOOP Bank Holder Name"
  }
}
Parameter Description
result The endpoint request result object
result.success Indicate that the request to Brankas endpoint was successful. i.e.

"result": {
  "success": true,
 }

bank_account.bank Beneficiary account bank name. Follow the list here
bank_account.number Beneficiary account number
bank_account.holder_name Beneficiary account holder name

It is possible however to receive an error upon request if the request is invalid

Response Payload
{
  "code": XX,
  "message": "error message provided here"
}
Parameter Description
code The error code provided by Brankas
message The error message provided by Brankas

Response Codes

Parameter Description
200 Request executed successfully.
404 Returned when the resource is not found.
400 Returned when the request body is malformatted or does not match the expected request.
401 Returned when the request does not contain the user’s credentials.
403 Returned when the user does not have permission to access the resource.
500 Returned when an unexpected error occurred on the server side.