Skip to main content

Disbursement to Bank

Disbursement to Bank enables direct fund transfers from DANA to users' bank accounts. This API lets you validate bank details, transfer funds, receive status updates, and check transfer statuses. It offers a secure, automated disbursement process that reduces manual work and improves efficiency.

Disbursement is also available for top up to DANA Balance. Check our Disbursement Overview for more details

Before you start​

You will need to register your business in our Merchant Portal to obtain your testing credentials. After you have created your test account, make sure you have done the following:

  • Finish your company registration and select XXX as your payment solution.
  • Merchant Disbursement Account (MDA) will be automatically created for you to store your balance. For sandbox testing, contact the DANA team to top up your account. In production, simply top up via the Virtual Account (VA) displayed in Merchant Portal.
  • Setup your webhooks & redirect URLs to receive payment outcomes & redirect user after payment.
  • Obtain your testing credentials from the merchant portal.

Process Flow​

The general flow of payment using the Disbursement to Bank is as follows:

Visit the Disbursement API Overview for edge cases and other scenarios.

Disbursement to Bank
  1. Merchant calls DANA's Check Disbursement Account API to verify their current account balance before processing any bank transfers.
  2. DANA processes the request and returns the merchant's current balance information, ensuring sufficient funds are available for the intended disbursement.
  3. Merchant receives a transfer request from a user who wants to transfer funds to their bank account.
  4. Merchant calls DANA's Transfer to Bank Account Inquiry API to validate the recipient's bank account details before initiating the transfer.
  5. DANA forwards the account inquiry request to the destination bank to verify the account information and availability.
  6. Bank processes the inquiry and returns the account validation results to DANA, confirming whether the account is valid and can receive transfers.
  7. DANA returns the bank account inquiry results to merchant, providing confirmation of account validity and transfer eligibility.
  8. Merchant calls DANA's Transfer to Bank API to initiate fund transfer to the validated bank account.
  9. DANA processes the transfer request by validating the account information to Bank and deducting the specified amount from the merchant's balance.
  10. DANA sends the transfer request to the destination bank, initiating the fund transfer process.
  11. Bank processes the transfer by crediting amount to the user's beneficiary bank account.
  12. DANA returns transfer result to the merchant, confirming that the transfer request has been successfully submitted.
  13. If merchant has enabled notifications (needNotify == true), DANA sends an additional status update indicating "Request in Progress (2024300)" to keep the merchant informed of the transfer processing status
  14. Bank sends the final transfer status result to DANA, confirming whether the transfer was successfully completed or failed.
  15. DANA calls merchant's Transfer to Bank Notify API webhook endpoint to deliver the final transfer result, providing complete transaction status and details.

Step 1 : Library Installation​

Visit our Libraries & Plugins guide for detailed information on our SDK.

DANA provides server-side API libraries for several programming languages, available through common package managers, for easier installation and version management. Follow the guide below to install our library:

Requirements

Installation

Install using npm or visit our Github

View in Github
Install the API Library using npm
npm install dana-node@latest --save

Set up the env

Required Credentials
PRIVATE_KEY or PRIVATE_KEY_PATH        # Your private key 
ORIGIN                                 # Your application's origin URL
X_PARTNER_ID                           # clientId provided during onboarding 
ENV                                    # DANA's environment either 'sandbox' or 'production'

Obtaining merchant credentials: Authentication

Step 2 : Initialize the library​

Visit our Authentication guide to learn about the authentication process when not using our Library.

Follow the guide below to initialize the library

Initialize the library
import { Dana } from 'dana-node';

const danaClient = new Dana({
  partnerId: "YOUR_PARTNER_ID", // process.env.X_PARTNER_ID
  privateKey: "YOUR_PRIVATE_KEY", // process.env.X_PRIVATE_KEY
  origin: "YOUR_ORIGIN", // process.env.ORIGIN
  env: "sandbox", // process.env.DANA_ENV or process.env.ENV or "sandbox" or "production"
});
const { disbursementApi } = danaClient;

Step 3 : Check Your Merchant Balance​

Before processing any bank transfer, call DANA's Check Disbursement Account API to verify that your merchant deposit account has sufficient funds. DANA will return your current available balance so you can confirm you have enough money for the transfer amount. If your balance is insufficient, top up your account balance via the Virtual Account (VA) displayed in Merchant Portal.

Check Disbursement Account
import { Dana } from 'dana-node';
import { QueryMerchantResourceRequest, QueryMerchantResourceResponse } from 'dana-node/merchant_management/v1';

// .. initialize client with authentication

const request: QueryMerchantResourceRequest = {
  // Fill in required fields here, refer to Check Disbursement Account API Detail
};

const response: QueryMerchantResourceResponse = await merchantManagementApi.queryMerchantResource(request);

Step 4 : Validate User's Bank Account​

When a user wants to transfer money to their bank account, call DANA's Transfer to Bank Account Inquiry API to validate their bank account details before initiating the actual transfer. You'll need to provide the customerNumber, beneficiaryAccountNumber, amount, additionalInfo.fundType, and additionalInfo.beneficiaryBankCode. DANA will forward this inquiry to the destination bank, which will verify the account and return by providing the detail account information.

Transfer to Bank Account Inquiry API
import { Dana } from 'dana-node';
import { BankAccountInquiryRequest, BankAccountInquiryResponse } from 'dana-node/disbursement/v1';

// .. initialize client with authentication

const request: BankAccountInquiryRequest = {
  // Fill in required fields here, refer to Transfer to Bank Account Inquiry API Detail
};

const response: BankAccountInquiryResponse = await disbursementApi.bankAccountInquiry(request);;

Step 5 : Execute the Bank Transfer​

Call DANA's Transfer to Bank API to process the actual fund transfer from your merchant account to the user's bank account, this process starting by validating again the user’s bank account in order to xxx. DANA will validate your request, deduct the funds from your merchant balance, and initiate the transfer to the user’s destination bank. The bank will then process the transfer and credit the amount to the user's account. You'll receive an response confirming the transfer submission (not completion).

Transfer to Bank API
import { Dana } from 'dana-node';
import { TransferToBankRequest, TransferToBankResponse } from 'dana-node/disbursement/v1';

// .. initialize client with authentication

const request: TransferToBankRequest = {
  // Fill in required fields here, refer to Transfer to Bank API Detail
};

const response: TransferToBankResponse = await disbursementApi.transferToBank(request);

Set additionalInfo.needNotify = true to receive notifications when the bank transfer request is in progress

Step 6 : Receive Transfer Status Updates​

After bank processing completes, DANA sends transfer status notifications to your configured endpoint via the Transfer to Bank Notify API. Your notification URL must follow the ASPI-mandated format: /v1.0/debit/emoney/transfer-bank/notify.htm.

Example of a successful payment webhook payload:

Example of a successful Transfer to Bank Notify:
Content-type: application/json
X-TIMESTAMP: 2020-12-21T17:50:44+07:00
{
  "responseCode": "2004300",
  "responseMessage": "Successful",
}

Optional Check Transfer Status Manually​

If you don't receive result from Transfer to Bank API within the expected timeframe or if your transfer API call times out, use the Transfer to Bank Inquiry Status API to manually check the transfer status. You'll need your originalPartnerReferenceNo and serviceCode.

Sample Transfer to Bank Inquiry Status API
import { Dana } from 'dana-node';
import { TransferToBankInquiryStatusRequest, TransferToBankInquiryStatusResponse } from 'dana-node/disbursement/v1';

// .. initialize client with authentication

const request: TransferToBankInquiryStatusRequest = {
    // Fill in required fields here, refer to Transfer to Bank Inquiry Status API Detail
};

const response: TransferToBankInquiryStatusResponse = await disbursementApi.transferToBankInquiryStatus(request);

Additional Enum Configuration​

The library provides several enums (enumerations) to represent a fixed set of constant values, ensuring consistency and reducing errors during integration.

Example Usage
import { EnvInfoSourcePlatformEnum } from 'dana-node/dist/widget/v1';

const ipg = EnvInfoSourcePlatformEnum.Ipg;

The following enums are available in the Library DANA Widget:

  1. AcquirementStatusEnum
  2. ActorTypeEnum
  3. GrantTypeEnum
  4. OrderTerminalTypeEnum
  5. PayMethodEnum
  6. PayOptionEnum
  7. PromoTypeEnum
  8. ResourceTypeEnum
  9. ResultStatusEnum
  10. ServiceScenarioEnum
  11. ServiceTypeEnum
  12. SourcePlatformEnum
  13. TerminalTypeEnum
  14. TypeEnum

Step 7 : Automated UAT Testing Suite​

To verify your integration, run our automated test suite. It takes under 2 minutes to tests your integration with mandated test scenarios. Check out the Github repo for more instructions

View in Github

Step 8 : Apply for Live Payment​

As part of regulatory compliance, merchants are required to submit UAT testing documents to meet Bank Indonesia's requirements. After completing sandbox testing, follow these steps to move to production:

  1. Generate production keys
    Create your production private and public keys, follow this instruction: Authentication - Production Credential.

  2. Confirm UAT testing logs
    Confirm that you have completed all testing scenarios from our Merchant Portal.

  3. Fill go-live submission form
    Follow the instructions inside our Merchant Portal to apply for production credentials. We will process your application in 1-2 days.

  4. Obtain production credentials
    Once approved, you will receive your production credentials such as: Merchant ID, Client ID known as X-PARTNER-ID, and Client Secret.

Testing in production environment

  1. Configure production environment
    Switch your application settings from sandbox to production environment by updating the API endpoints and credentials.

  2. Test using production credentials
    Conduct the same testing scenarios as sandbox testing, using your production credentials.

  3. UAT production sign-off
    Once testing is complete, DANA will prepare the UAT Production Sign Off document in the Merchant Portal. Both merchant and DANA representatives must sign this document to formally approve the integration.

  4. Go-live
    After receiving all approvals, your DANA integration will be activated and ready for live payments from your customers.

Ready to submit testing documents?
Access our merchant portal for detailed guide to start receiving live payments

Open Merchant Portal