Skip to main content

DANA Widget Binding

DANA Widget Binding lets you seamlessly integrate DANA payments into your platform, allowing customers to link their DANA accounts for faster, smoother transactions across all your services. Currently there are two available binding methods:

  • Normal Binding: Users enter their DANA-registered phone number manually.
  • Seamless Binding: The merchant securely passes the user's phone number (already registered on their platform) to DANA, skipping manual input.

You can initiate DANA account binding between mobile apps by using a Deeplink to open the DANA App from your mobile app for a seamless in-app experience. This flexibility helps enhance user experience while ensuring secure account linking across channels.

DANA Widget is also available for payments without account binding. Check our DANA Widget 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 Integrated Payment as your payment solution.
  • 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 DANA Widget Binding. The checkout page is available using web browsers on mobile devices.

User experience 1

Bind with DANA Account
Connect customer’s DANA accounts with your own!

User experience 2

Simple binding process
Just provide the customer phone number and we’ll do the rest!

User experience 3

Provide seamless payment
Linked accounts can enjoy a more seamless payment experience.

User experience 4

Pay with DANA
Customers can pay using payment methods available in their DANA Account.

User experience 5

Instant Payment Result
You & your customers instantly receive payment result.

Process Flow​

The general flow of payment using the DANA Widget Binding is as follows:

Visit the DANA Widget API Overview for edge cases and other scenarios.

DANA Widget Binding
  1. User begins DANA account binding with the merchant platform.
  2. Merchant calls Deeplink Binding to create redirect URL.
  3. Redirect customer to DANA App using the returned Deeplink URL.
  4. If merchant provides seamlessData parameter, the Seamless Binding process will be used and DANA will check if the user's phone number inside the seamlessData matches with then account that is logged into their DANA app. If they match, DANA will direct to agreement page.
  5. If the seamlessData user's phone number is different from the logged in account, DANA will require the user to log out of their current phone number and login or register using the seamlessData phone number.
  6. After successful authorization, DANA redirects the user to the agreement page.
  7. When merchant does not provide seamlessData, the Normal Binding process will be used and DANA will show the phone number input screen.
  8. User enters phone number and do login or register.
  9. After successful authorization, DANA redirects the user to the agreement page.
  10. User makes an agreement to continue the process.
  11. DANA returns the result of binding process to DANA Server.
  12. DANA redirects the customer to the redirectUrl set by merchant along with the authCode.
  13. Merchant exchanges the authCode for an accessToken by calling Apply Token API.
  14. DANA returns the accessToken and refreshToken that are valid for each user.
  15. The merchant stores accessToken and refreshToken.

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, WidgetApi as WidgetApiClient } 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 { WidgetApi } = danaClient;

Step 3 : Bind to DANA Account​

Generate a redirect URL for DANA account binding. Users will be directed to the DANA App where they can complete the binding process. Configure the OAuth URL as shown below:

Generate OAuth 2.0 URL
import { WidgetUtils } from 'dana-node/widget/v1';

// Generate OAuth URL
const oauth2UrlData = {
    redirectUrl: 'https://your-redirect-url.com',
    externalId: 'your-external-id', // or use uuidv4()
    merchantId: process.env.MERCHANT_ID,
    seamlessData: {
        mobileNumber: '08xxxxxxxxx' // Optional
    }
};

const oauthUrl = WidgetUtils.generateOauthUrl(oauth2UrlData);
console.log(oauthUrl);

The above code redirects users to the DANA App authorization page. By providing the user's phone number in seamlessData, you can streamline the experience so users don't need to enter their number manually.line the experience so users don't need to enter their number manually.

After successful authorization, the user will be redirected to your specified redirectUrl with an authCode that expires in 10 minutes. Example:

Sample response from Get OAuth 2.0 URL
https://www.merchant.com/oauth/callback?responseCode=2001000&responseMessage=Successful&authCode=xxx&state=2345555

Step 4 : Exchange the authCode into accessToken​

After obtaining the authCode, exchange it for an accessToken using the Apply Token API. The returned accessToken and refreshToken both have a 3-year validity period. Once expired, users must rebind their DANA account.

Apply Token API
import { Dana } from 'dana-node';

const danaClient = new Dana({
    // .. initialize client with authentication
});
const { WidgetApi } = danaClient;

const request: ApplyTokenRequest = {
    // Fill in required fields here, refer to Apply Token API Detail
};

const response: ApplyTokenResponse = await WidgetApi.applyToken(request);

Step 5 : Use the Direct Debit Payment API to get a hosted checkout URL​

Use the Direct Debit Payment API to create new payment requests which will then return the Checkout URL of the hosted payment page.

To create a new order, make a POST request to the Direct Debit Payment API:

Direct Debit Payment API
import { Dana } from 'dana-node';

// .. initialize client with authentication

const request: WidgetPaymentRequest = {
    // Fill in required fields here, refer to Direct Debit Payment API Detail
};

const response: WidgetPaymentResponse = await WidgetApi.widgetPayment(request);

If successful, the response will include the URL for the DANA's payment page. For example:

Sample response from Create Order API
Content-Type: application/json
X-TIMESTAMP: 2020-12-23T08:31:11+07:00
{
  "responseCode": "2005400", // Refer to response code list
  "responseMessage": "Successful", // Refer to response code list
  "referenceNo": "2020102977770000000009", // Transaction identifier on DANA system
  "partnerReferenceNo": "2020102900000000000001", // Transaction identifier on partner system
  "webRedirectUrl": "https://pjsp.com/universal?bizNo=REF993883&...",
  "additionalInfo":{}
}

Step 6 : Access DANA's page by hitting Apply OTT API​

To access DANA's payment page, convert the user's access token to a one-time token (OTT) via the Apply OTT API. This token has a 10-minute expiration period and can be used only once.

Apply OTT API
import { Dana } from 'dana-node';

const danaClient = new Dana({
    // .. initialize client with authentication
});
const { WidgetApi } = danaClient;

const request: ApplyOTTRequest = {
    // Fill in required fields here, refer to Apply OTT API Detail
};

const response: ApplyOTTResponse = await WidgetApi.applyOTT(request);

Step 7 : Redirect to DANA's checkout page​

Generate a payment URL by combining the webRedirectUrl from the Direct Debit Payment API with an OTT token from the Apply OTT API.

Sample webRedirectUrl
import { Util } from 'dana-node/widget/v1';
import { WidgetPaymentResponse, ApplyOTTResponse } from 'dana-node/widget/v1/models';

// Example response from createWidgetPayment
const widgetPaymentResponse = new WidgetPaymentResponse({
  webRedirectUrl: 'https://example.com/payment?token=abc123'
}); // this should be from createPayment Widget API

// Example response from applyOTT
const applyOTTResponse = new ApplyOTTResponse({
  userResources: [
    {
      value: 'ott_token_value'
    }
  ]
}); // this should be from applyOTT Widget API

// Generate the payment URL
const paymentUrl = Util.generateCompletePaymentUrl(widgetPaymentResponse, applyOTTResponse);

Optional Query Order Status, Cancel Order, Refund Order, and Balance Inquiry​

There are additional APIs available to enhance your integration process:

  1. Query Payment API - Use this API to inquire the latest status of a payment request.

    2. Sample Query Payment API
    import { Dana } from 'dana-node';
    const danaClient = new Dana({
        // .. initialize client with authentication
    });
    const { WidgetApi } = danaClient;

    const request: QueryPaymentRequest = {
        // Fill in required fields here, refer to Query Payment API Detail
    };

    const response: QueryPaymentResponse = await WidgetApi.queryPayment(request);
  2. Cancel Order API - For unpaid orders or those paid within 24 hours, a full refund returns to the customer's original payment source.

    3. Sample Cancel Order API
    import { Dana } from 'dana-node';

    const danaClient = new Dana({
      // .. initialize client with authentication
    });
    const { WidgetApi } = danaClient;

    const request: CancelOrderRequest = {
        // Fill in required fields here, refer to Cancel Order API Detail
    };

    const response: CancelOrderResponse = await WidgetApi.cancelOrder(request);
  3. Refund Order API - Process refunds for completed orders. You can trigger a refund request on behalf of the customer using this API, who will then process the refund through DANA.

    4. Sample Refund Order API
    import { Dana } from 'dana-node';

    const danaClient = new Dana({
      // .. initialize client with authentication
    });
    const { WidgetApi } = danaClient;

    const request: RefundOrderRequest = {
        // Fill in required fields here, refer to Refund Order API Detail
    };

    const response: RefundOrderResponse = await WidgetApi.refundOrder(request);
  4. Balance Inquiry API - Implement this API to verify the customer's balance before order creation. Disabling payment methods with insufficient funds will increase your order success rate.

    5. Sample Balance Inquiry API
    import { Dana } from 'dana-node';

    const danaClient = new Dana({
        // .. initialize client with authentication
    });
    const { WidgetApi } = danaClient;

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

    const response: BalanceInquiryResponse = await WidgetApi.balanceInquiry(request);

Step 8 : Receive Payment Outcome​

After a successful payment:

  1. Notification: The user will be redirected to your specified Redirect URL, which you can configure using the urlParams parameter in the Direct Debit Payment API request, the redirection URL has a format like: https:xxx?originalReferenceNo=xxx&originalPartnerReferenceNo=xxx&merchantId=xxxx&status=xxx

  2. [Optional] Finish Notify: In case you add urlParams.type = NOTIFICATION, DANA will send payment notifications to your Notification URL via the Finish Notify API. Configure your notification endpoint with the ASPI-mandated path format: /v1.0/debit/notify.

Construction

Construction
new WebhookParser(publicKey?: string, publicKeyPath?: string)

Request

ParameterTypeRemarks
publicKeystringThe DANA gateway's public key as a PEM formatted string. This is used if publicKeyPath is not provided or is empty
publicKeyPathstringThe file path to the DANA gateway's public key PEM file. If provided, this will be prioritized over the publicKey string

Notes: One of publicKey or publicKeyPath must be provided.

Method

Method
parseWebhook(httpMethod: string, relativePathUrl: string, headers: { [key: string]: string }, body: string): FinishNotifyRequest

Request

ParameterTypeRemarks
httpMethodstringThe HTTP method of the incoming webhook request e.g., http.MethodPost
relative_path_urlstringThe relative URL path of the webhook endpoint that received the notification e.g /v1.0/debit/notify
headersmap[string]stringA map containing the HTTP request headers. This map must include X-SIGNATURE and X-TIMESTAMP headers provided by DANA for signature verification
bodystringThe raw JSON string payload from the webhook request body
  • Returns: A pointer to a FinishNotifyRequeststruct containing the parsed and verified webhook data, or an error if parsing or signature verification fails.
  • Raises: ValueError if signature verification fails or the payload is invalid.

Security Notes

  • Always use the official public key provided by DANA for webhook verification.
  • Reject any webhook requests that fail signature verification or have malformed payloads.
  • Never trust webhook data unless it passes verification.
Webhook Finish Notify
import { WebhookParser } from 'dana-node/dist/webhook'; // Adjust import path as needed

async function handleDanaWebhook(req: AnyRequestType, res: AnyResponseType) {
    // Retrieve the DANA public key from environment variables or a secure configuration.
    // Option 1: Public key as a string
    const danaPublicKeyString: string | undefined = process.env.DANA_WEBHOOK_PUBLIC_KEY_STRING;
    // Option 2: Path to the public key file (recommended for production)
    const danaPublicKeyPath: string | undefined = process.env.DANA_WEBHOOK_PUBLIC_KEY_PATH;

    if (!danaPublicKeyString && !danaPublicKeyPath) {
        console.error('DANA webhook public key not configured.');
        res.status(500).send('Webhook processor configuration error.'); // Or appropriate error handling
        return;
    }

    const httpMethod: string = req.method!; // e.g., "POST"
    const relativePathUrl: string = req.path!; // e.g., "/v1.0/debit/notify". Ensure this is the path DANA signs.

    const headers: Record<string, string> = req.headers as Record<string, string>;

    let requestBodyString: string;
    if (typeof req.body === 'string') {
        requestBodyString = req.body;
    } else if (req.body && typeof req.body === 'object') {
        requestBodyString = JSON.stringify(req.body);
    } else {
        console.error('Request body is not a string or a parseable object.');
        res.status(400).send('Invalid request body format.');
        return;
    }

    // Initialize WebhookParser.
    const parser = new WebhookParser(danaPublicKeyString, danaPublicKeyPath);

    try {
        // Verify the signature and parse the webhook payload
        const finishNotify = parser.parseWebhook(
            httpMethod,
            relativePathUrl,
            headers,
            requestBodyString
        );

        console.log('Webhook verified successfully:');
        console.log('Original Partner Reference No:', finishNotify.originalPartnerReferenceNo);
        // TODO: Process the finishNotify object (e.g., update order status in your database)

        res.status(200).send('Webhook received and verified.');
    } catch (error: any) { // Catching as 'any' to access error.message
        console.error('Webhook verification failed:', error.message);
        // Respond with an error status. DANA might retry if it receives an error.
        res.status(400).send(`Webhook verification failed: ${error.message}`);
    }
}

For detailed example, please refer to the following resource: Example Webhook.

Example of a successful payment webhook payload:

Example of a successful Finish Notify:
Content-Type: application/json
X-TIMESTAMP: 2024-12-23T09:10:11+07:00
{
  "responseCode": "2005400", // Refer to response code list
  "responseMessage": "Successful", // Refer to response code list
  "referenceNo": "2020102977770000000009", // Transaction identifier on DANA system
  "partnerReferenceNo": "2020102900000000000001", // 	Transaction identifier on partner system
  "webRedirectUrl": "https://pjsp.com/universal?bizNo=REF993883&..."
  ...
}

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

Optional Revoke DANA's user account​

Use the Account Unbinding API to remove the connection between your platform and a user's DANA account. For specific users, contact DANA directly.

Sample Account Unbinding API
import { Dana } from 'dana-node';

const danaClient = new Dana({
    // .. initialize client with authentication
});
const { WidgetApi } = danaClient;

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

const response: AccountUnbindingResponse = await WidgetApi.accountUnbinding(request);

Step 9 : 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 10 : 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