Skip to main content

Disbursement to Balance

Disbursement to Balance enables merchants to transfer balance to users' DANA balance. This API lets you validate account details, topup, and check topup statuses. It offers a secure, automated disbursement process that reduces manual work and improves efficiency.

Disbursement is also available for transfer to Bank Account. 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.

User Experience​

Below is a sample of the user experience for users paying using Disbursement to Balance. The checkout page is available using web browsers on mobile devices.

User experience 1

Top Up Amount
Merchant shows merchant page to user to input amount for top up transactions.

User experience 2

Notification from DANA
User receive top up notification from DANA.

User experience 3

Top up result
Merchant receive top up result.

Process Flow​

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

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

Disbursement to Balance
  1. Merchant calls DANA's Check Disbursement Account API to verify their current account balance before processing any disbursements.
  2. DANA processes the request and returns the merchant's current balance information, enabling them to confirm sufficient funds are available for disbursements.
  3. User initiates a top up request through the merchant by entering their DANA registered phone number, indicating their intention to add funds to their DANA account.
  4. Merchant calls Account Inquiry API to verify the user's DANA account details and ensure the account is valid and active for receiving funds.
  5. DANA processes the account inquiry request by validating information about the user and the merchant to determine their eligibility for top-up by checking limits, payer and risk scope to returns the user's account information to the merchant.
  6. Merchant displays the user to specify the desired top up amount they wish to add to their DANA account.
  7. User provides the top up amount to the merchant, confirming the transaction details.
  8. Merchant deducts the specified amount from the user's payment method or account balance within their platform.
  9. Merchant calls Customer Top Up API, sending the user's account details and the top up amount to initiate the disbursement.
  10. DANA processes the disbursement by deducting the specified amount from merchant's balance and crediting the amount to the user's DANA account.
  11. DANA returns a successful transaction result to merchant, confirming the top up has been completed.
  12. Merchant notifies user that their DANA account top up was successful.
  13. DANA sends a push notification directly to the user's mobile device, confirming the successful top up and updated account balance.

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 transfer funds, 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 Account​

When you want to top up transaction to user's DANA account, you should call DANA's Account Inquiry API to verify the user's DANA account details and ensure the account is valid and active for receiving balance. You'll need to provide the amount, additionalInfo.fundType, customerNumber or customerName. DANA will process this inquiry and send the result to the merchant by providing the detail account information.

Account Inquiry API
import { Dana } from 'dana-node';
import { DanaAccountInquiryRequest, DanaAccountInquiryResponse } from 'dana-node/disbursement/v1';

// .. initialize client with authentication

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

const response: DanaAccountInquiryResponse = await disbursementApi.danaAccountInquiry(request);

Step 5 : Execute the Customer Top Up​

First, you provide top up amount page to user. After user puts the top up amount, call DANA's Customer Top Up API to process the top up from merchant to the user's DANA balance, this process starting by merchant deducts user’s account balance and requests of top up transaction to DANA. DANA will validate your request. After that, DANA deducts merchant’s deposit balance and at the same time, DANA credits user’s DANA Balance. You’ll receive an response result of top up process as success.

Customer Top Up API
import { Dana } from 'dana-node';
import { TransferToDanaRequest, TransferToDanaResponse } from 'dana-node/disbursement/v1';

// .. initialize client with authentication

const request: TransferToDanaRequest = {
  // Fill in required fields here, refer to Customer Top Up API Detail
};

const response: TransferToDanaResponse = await disbursementApi.transferToDana(request);

Step 6 : Receive Top Up Status Updates​

If you don't receive result from Customer Top Up API and got the timeout after do retry for 5 times, use the Customer Top Up Inquiry Status API to manually check the top up status and get the latest transaction status and information.

Customer Top Up Inquiry Status API
import { Dana } from 'dana-node';
import { TransferToDanaInquiryStatusRequest, TransferToDanaInquiryStatusResponse } from 'dana-node/disbursement/v1';

// .. initialize client with authentication

const request: TransferToDanaInquiryStatusRequest = {
  // Fill in required fields here, refer to Customer Top Up Inquiry Status API Detail
};

const response: TransferToDanaInquiryStatusResponse = await disbursementApi.transferToDanaInquiryStatus(request);

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