Skip to main content

Gapura Custom Checkout

Document Version 1.2.1

A customizable integration for businesses to create their own checkout experience. This solution provides the APIs of the Gapura Custom Checkout core system. It is specifically designed for merchants who wants to use their own checkout pages to display payment methods, such as virtual account or QRIS.

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 Gapura Custom Checkout 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.

Process Flow​

The general flow of payment using the Gapura payment gateway is as follows:

Visit the Payment Gateway API Overview for edge cases and other scenarios.

Gapura Custom Checkout
  1. User browses merchant website/app, adds items to cart, and initiates checkout process.
  2. Merchant queries DANA Consult Pay APIto retrieve current list of supported payment options.
  3. DANA returns comprehensive list of available payment methods with their details and requirements.
  4. Merchant presents payment interface showing all available DANA payment options in a user-friendly format.
  5. User reviews available payment methods and selects their preferred option (e.g., DANA Balance, VA, etc.).
  6. Merchant system prepares transaction details including amount, items, and user information.
  7. Merchant sends Create Order API request to DANA API with complete order parameters.
  8. DANA system performs comprehensive validation of order data and creates transaction record.
  9. DANA returns detailed order information including payment instructions and transaction reference.
  10. For Virtual Account and QRIS payments: Merchant displays complete VA or QRIS details with payment instructions.
  11. Merchant shows e-wallet app or web page checkout page to user.
  12. User follows payment method-specific steps to complete their transaction.
  13. DANA sends a payment notification to the merchant's system via the Finish Notify API, updating the payment status of the order.
  14. DANA redirects to the merchant URL that already set when hitting Create Order API.

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, PaymentGatewayApi as PaymentGatewayApiClient } 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.ENV or "sandbox" or "production"
});
const { PaymentGatewayApi } = danaClient;

Step 3 : Obtain the Available Payment Method via Consult Pay API​

Use the Consult Pay API to get a list of available payment methods. In the sandbox environment, all payment methods will be displayed for testing. In production, only the payment methods specified in Perjanjian Kerja Sama (PKS) will be shown.

To consult the available payment method, make a POST request to the Consult Pay API:

Calling Consult Pay API
import { Dana } from 'dana-node';

// .. initialize client with authentication

const request: ConsultPayRequest = {
    // Fill in required fields here, refer to Consult Pay API Detail
};

const response: ConsultPayResponse = await PaymentGatewayApi.consultPay(request);

Step 4 : Use the Create Order API to get a hosted checkout URL​

Use the Create Order 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 Create Order API:

Calling Create Order API
import { Dana } from 'dana-node';

// .. initialize client with authentication

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

const response: CreateOrderResponse = await PaymentGatewayApi.createOrder(request);

When sending the request parameters, ensure you include payOptionDetails and set additionalInfo.order.scenario to API.

If successful, the response will include the URL for the hosted payment page. For example:

Sample response from Create Order API
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&..."
  ...
}

After receiving the webRedirectUrl in the API response, direct your users to the appropriate checkout flow:

  • For Virtual Account (VA) or QRIS payments: Display the VA number or QR code to the user on your checkout page.
  • For e-wallet payments: Redirect the user to either the e-wallet app or web checkout page.

If you want to simulate payments in the sandbox environment. Contact our Merchant Services team to access our sandbox simulation tools.

Step 5 : Query Order Status, Cancel Order, and Refund Order​

Here are the APIs you need to implement for proper integration:

  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';

    //initiate danaClient with authentication

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

    const response: QueryPaymentResponse = await PaymentGatewayApi.queryPayment(request);
  2. Cancel Order API - Cancel unpaid orders or paid orders within 24 hours. Cancellation can be initiated by users through the merchant platform or directly through DANA (for DANA Balance payments).

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

    //initiate danaClient with authentication

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

    const response: CancelOrderResponse = await PaymentGatewayApi.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';

    //initiate danaClient with authentication

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

    const response: RefundOrderResponse = await PaymentGatewayApi.refundOrder(request);

Step 6 : Receive Payment Outcome via Finish Notify API​

After a successful payment:

  1. The user will be redirected to your specified Redirect URL, which you can configure using the urlParams parameter in the Create Order API API request.
  2. 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., POST
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/payment_gateway/v1';

const ipg = EnvInfoSourcePlatformEnum.Ipg;

The following enums are available in the Library Payment Gateway:

  1. AcquirementStatusEnum
  2. ActorTypeEnum
  3. OrderTerminalTypeEnum
  4. PayMethodEnum
  5. PayOptionEnum
  6. ScenarioEnum
  7. SourcePlatformEnum
  8. TerminalTypeEnum
  9. 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
Version 1.2.1 - May 08, 2025
Affected APIs
Changes
  • Added additional information section for all APIs
Version 1.2.0 - January 15, 2025
Affected APIs
Changes
  • Removed BusinessScenario Enum
  • Create Order API: Updated Service Code
  • Create Order API: Updated URL
  • Create Order API: Updated Idempotent Key and Rules
  • Create Order API: Updated Condition webRedirectUrl on Response section
  • Create Order API: Added new request sample programming language
  • Create Order API: Updated Request and Response Sample
  • Create Order API: Updated Response Code
  • Query Payment, Cancel Order, and Refund Order API: Updated URL
  • Query Payment, Cancel Order, and Refund Order API: Removed additionalInfo.businessScenario on Request section
  • Query Payment, Cancel Order, and Refund Order API: Updated Request Sample
Version 1.1.2 - November 22, 2024
Affected APIs
Changes
  • Updated value of ``REDIRECTION`` become ``REDIRECT`` on ScenarioEnum
Version 1.1.1 - October 07, 2024
Affected APIs
Changes
  • Updated Environment URL for Sandbox on Specification section for all APIs
  • Updated Request Sample on URL Section for all APIs
Version 1.1.0 - August 15, 2024
Affected APIs
Changes
  • Added Environment URL on Specification section for all APIs
  • Added new programming language (Go, Java, JavaScript, Python, Ruby) on Request Sample for all APIs
Version 1.0.0 - April 05, 2024
  • Initial Version