Skip to main content

DANA Widget Non Binding

DANA Widget Non Binding integrates DANA as a payment method in your platform without account binding. Users simply select DANA, get redirected to the DANA App, and complete payments using their DANA account.

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​

User experience 1

Pay with DANA
User selects DANA as their payment method.

User experience 2

Payment Details
User reviews transaction details and completes payment in the DANA App.

User experience 3

Payment Result
User instantly receive payment result.

Process Flow​

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

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

DANA Widget Binding
  1. The user browses the merchant's website or app and proceeds to checkout after selecting a product and selects DANA as a payment method.
  2. The merchant system generates an order internally, preparing it for payment processing.
  3. The merchant's backend sends a request to DANA's Direct Debit Payment API, passing the necessary order details.
  4. After successfully creating the order, DANA responds with a webRedirectUrl for the checkout page and order information.
  5. Open DANA App.
  6. If the user's session is valid, DANA will show the DANA’s cashier page.
  7. If there is no session, DANA will require the user to login/register.
  8. After successful authorization, DANA redirects the user to the DANA’s cashier page.
  9. DANA display payment details to user and available payment method.
  10. The user chooses one of the supported payment methods provided by DANA and follows the instructions on the DANA checkout page to complete the payment.
  11. DANA App receives the payment details and sends it to DANA Server.
  12. DANA processes the payment.
  13. DANA shows payment result screen to user.
  14. DANA redirects back the UI page to URL Link that merchant set when hitting Direct Debit Payment API. with the format URL: https:xxx?originalReferenceNo=xxx&originalPartnerReferenceNo=xxx&merchantId=xxxx&status=xxx.
  15. If merchant add urlParams.type = NOTIFICATION, DANA will send a payment notification to the merchant's system via the Finish Notify API, updating the payment status of the order.

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 : 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":{}
}

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 4 : 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 Non Binding:

  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 5 : 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 6 : 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