# Get Started with DOKU API

Welcome to the DOKU API reference documentation, your comprehensive guide to seamlessly integrate our Payment Gateway, Wallet, Billing, and other services into your applications.

### 🚀  Unlock the Power of Seamless Transactions with DOKU API: Your Gateway to Smarter Commerce 🚀

Welcome, savvy merchants, to the future of frictionless transactions! If you're ready to elevate your business game, then DOKU's API is your golden ticket. 🌐✨

### 🔗 Dive into the World of DOKU: <https://www.doku.com/>&#x20;

In the dynamic landscape of modern commerce, mastering the art of seamless transactions is non-negotiable. That's where DOKU steps in, revolutionizing the way you handle payments and transactions. To ensure you harness the full potential of our offerings, we present to you the key to unlocking a world of possibilities: our API reference.

### 💡**Explore the DOKU API Reference:**

Ready to take the plunge? Our comprehensive API reference is your go-to guide for navigating the intricacies of DOKU's offerings. Gain insights into authentication, endpoints, and data formats, ensuring a smooth integration that aligns perfectly with your business requirements.

### 🚀**Top Tips for Developers:**

{% hint style="info" %}
**Dive into Documentation:** Familiarize yourself with our API documentation, offering detailed insights into every aspect of integration.
{% endhint %}

{% hint style="info" %}
**Test in Sandbox:** Utilize our sandbox environment to test your integration before going live. It's the perfect playground to ensure everything runs like clockwork.
{% endhint %}

{% hint style="info" %}
**Stay Updated:** Subscribe to our updates to stay in the loop about the latest features, enhancements, and best practices for optimizing your integration.
{% endhint %}

## Ready to transform the way you transact? Let's make it happen with DOKU's API!&#x20;

#### Try your first request  🚀🌐💼

To make your first request, choose any payment channels on this Demo Site <https://sandbox.doku.com/demo/>

<figure><img src="/files/4PuV6CeaR5YjAplGQPGB" alt=""><figcaption><p>Demo Site</p></figcaption></figure>

Take a look at how you might call this method using our official demosite.&#x20;

{% tabs %}
{% tab title="Virtual Account" %}

```json
{
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "virtual_account_info": {
        "billing_type": "FIX_BILL",
        "expired_time": 60,
        "reusable_status": false,
        "info1": "Merchant Demo Store",
        "info2": "Thank you for shopping",
        "info3": "on our store"
    },
    "customer": {
        "name": "Jessica Tessalonika",
        "email": "jessica@example.com"
    }
}
```

{% endtab %}

{% tab title="Credit Card" %}

```json
{
    "order": {
        "invoice_number": "INV-20210118-0001",
        "amount": 90000,
        "line_items": [
            {
                "name": "T-Shirt Red",
                "price": 30000,
                "quantity": 2
            },
            {
                "name": "Polo Navy",
                "price": 30000,
                "quantity": 1
            }
        ],
        "callback_url": "https://merchant.com/success-url",
        "failed_url": "https://merchant.com/failed-url",
        "auto_redirect": false
    },
    "card": {
        "token": "a55b8d8df709607d2a343778898f41d0",
        "save": false
    },
    "customer": {
        "id": "CUST-0001",
        "name": "Jessica Tessalonika",
        "email": "jessica@example.com"
        "phone": "6285694566147",
        "address": "Sianjur Mula-Mula",
        "country": "ID"
    },
    "payment": {
        "type": "INSTALLMENT",
        "acquirer":"BRI",
        "tenor": 3
    },
    "override_configuration": {
        "themes": {
            "language": "EN",
            "background_color": "F5F8FB",
            "font_color": "1A1A1A",
            "button_background_color": "E1251B",
            "button_font_color": "FFFFFF"
        },
        "promo": [
            {
                "bin": "142498",
                "discount_amount": 20000
            },
            {
                "bin": "314498",
                "discount_amount": 20000
            },
            {
                "bin": "091234",
                "discount_amount": 10000
            },
            {
                "bin": "091234",
                "discount_amount": 10000
            }
        ],
        "allow_bin": ["461700","410505","557338"],
        "allow_tenor": [0,3,6]
    },
    "additional_info": {
    "override_notification_url": "https://google.com",
    "disclaimer" : {
            "id" : "Testing",
            "en" : "testing englis"
        }
}
```

{% endtab %}
{% endtabs %}


# User Registration

## Create your Business Account​

To start using our services, you must register a user. Follow these quick and easy steps to register your account:​

1. Visit [DOKU Dashboard Registration page](https://dashboard.doku.com/bo/register?utm_source=docs)
2. Fill the registration form by entering your full name, business name, business email address, phone number, and password
3. Check the Terms and Conditions and Privacy Policy, then submit the form
4. Verify your account by entering the OTP that was sent to your email address
5. Business Account has been successfully created. You can proceed to activate your Business account by following the next guide [here](https://docs.doku.com/get-started/activate-business).

<figure><img src="/files/xmeBtA9ASAb3ND76rYML" alt=""><figcaption></figcaption></figure>

If you are looking to explore and test our products, you can register for sandbox account [below](#explore-our-sandbox).

## Create a Sandbox Account

While DOKU Business Account is used to accept real payments in the production environment, DOKU Sandbox Account is a demo account that you can use to simulate payments in the testing environment. If you are looking to test payments, the following is a step-by-step guide on how you could create a DOKU Sandbox Account.

1. Visit [DOKU Sandbox Registration page](https://sandbox.doku.com/bo/sandbox-registration?utm_source=docs)
2. Fill the registration form by entering your full name, business name, business email address, and password
3. Check the Terms and Conditions and Privacy Policy, then submit the form
4. DOKU Sandbox Account has been successfully created. You can proceed to log in to [DOKU Sandbox](https://sandbox.doku.com/bo/login?utm_source=docs) using the credentials you used in the registration form.

<figure><img src="/files/ly1jlMNcVWoAaFh0phVg" alt=""><figcaption></figcaption></figure>


# Idempotency Request

Idempotency is a concept where a request can be send multiple times with the same result as the first request, that means the system only performs one process for identical requests.

A request is identical if it is sent with the same request-id. However, the implementation may different in other systems, for example for processing transactions additional parameters such as "order-no, amount" may be required to compliment when decide a request is identical or not.

### How Idempotency Works

<figure><img src="/files/O6DNr5kjv2UpbMZiXn0y" alt=""><figcaption></figcaption></figure>

### Guidance for Idempotency Key <a href="#guide-for-idempotency-key" id="guide-for-idempotency-key"></a>

> **IDEMPOTENCY KEY IN DOKU**
>
> We make `idempotency key` in our system is `Request ID`

To implement this, you must do below :

1. Every API Request must send unique `request ID`.
2. If something happen in Merchant Side and merchant can't get response, then merchant send request again with same request ID and same Request Body, DOKU system will send the same Response body with HTTP Status Code 409 Conflict.


# Notification

DOKU uses HTTP Notification to notify your application when an event happens in your account. HTTP Notification particularly useful for asychronous events such as when your customer completes the payment process for Virtual Account or etc. Not all DOKU integration require HTTP Notification. Keep reading to learn more about what HTTP Notification is and when you should use them.

### What is HTTP Notification ?&#x20;

HTTP Notification is a notification that DOKU send to notify your application for certain events. Basically, you need to setup an endpoint on your side to receive the notification, which could be written in Java, PHP, Python, Node.js, or anything. The HTTP Notification endpoint has an associated URL (e.g., <https://your-domain.com/notifications/payments>).

DOKU will send the notification body in JSON format, therefore you can parse it with JSON parser. Please mind that DOKU might add new fields in the notification body in order to cover new use cases in our notification service, you are suggested to parse it in non strict format. This prevents the parser from throwing an error or exception for new fields.

### When to use HTTP Notification ?

These are various cases that DOKU will send notification to you:

1. Virtual Account Payment
2. Convenience Store Payment
3. Credit Card Payment
4. E-Money Payment
5. Direct Debit Payment
6. Paylater Payment
7. QR Payment
8. Internet Banking Payment<br>


# Setup Notification URL

To get notified by DOKU, you must setup the `Notification URL` on DOKU Back Office. For security reason, we encourage you to use `https://` URL protocol prefix.

{% hint style="warning" %}
**Important: ngrok Domain Prohibited for Notification URLs**

Please note that we no longer support URLs that use the **ngrok** domain, as they do not meet our security standards. Ensure that your Notification URL is hosted on a secure and reliable domain to maintain the integrity of your transactions.
{% endhint %}

{% hint style="info" %}
**NOTIFICATION URL MUST BE ABLE ACCESSED FROM INTERNET**

Make sure to input Notification URL that can be reached from Public Internet. DOKU will not be able to send notification to localhost, URL protected with authentication, URL behind VPN, unusual destination port, and etc.
{% endhint %}

{% hint style="info" %}
**LOCAL DEVELOPMENT**

If you are still on development process, you can utilize service like [Localhost.run](http://localhost.run/) and then put the URL to the `Notification URL` on the DOKU Back Office.
{% endhint %}

### Virtual Account SNAP <a href="#virtual-account" id="virtual-account"></a>

For Virtual Account, go to **Settings  > Under Payment Settings > Virtual Account SNAP**. You should see the Payment Method that is available to you.

<figure><img src="/files/YsE4eUYQqbDLfTHahSJz" alt=""><figcaption></figcaption></figure>

You will need to setup the `Notification URL` on each Virtual Account by clicking the **CONFIGURE** button.

### Virtual Account Non-SNAP <a href="#virtual-account" id="virtual-account"></a>

For Virtual Account, go to **Settings  > Under Payment Settings > Virtual Account**. You should see the Payment Method that is available to you.

<figure><img src="/files/Ai5Hzj87vhmEq2uKAcm1" alt=""><figcaption></figcaption></figure>

You will need to setup the `Notification URL` on each Virtual Account by clicking the **CONFIGURE** button.

### **Cards**

For Virtual Account, go to **Settings  >** Under **Payment Settings > Cards > Tab Payment Configuration.**&#x20;

<figure><img src="/files/HwGNpdwmkXNqmzvZgFOE" alt=""><figcaption></figcaption></figure>

Please add or edit in the payment notification URL on the provided box.

### Convenience Store

&#x20;For Virtual Account, go to **Settings  >** Under **Payment Settings > Convenience Store.**

<figure><img src="/files/8IwgXceAp8dLjcMnRGfe" alt=""><figcaption></figcaption></figure>

You will need to setup the `Notification URL` on each Convenience Store Payment Channel by clicking the **CONFIGURE** button.

### e-Wallet

For Virtual Account, go to **Settings  >** Under **Payment Settings > e-Wallet.**

<figure><img src="/files/5CcREb1JRiU5KmNRDzlu" alt=""><figcaption></figcaption></figure>

You will need to setup the `Notification URL` on each e-Wallet Payment Channel by clicking the **CONFIGURE** button.

### Paylater&#x20;

For Virtual Account, go to **Settings  >** Under **Payment Settings > Paylater.**&#x20;

<figure><img src="/files/FqH9Fw2cAgapOTq2YZXq" alt=""><figcaption></figcaption></figure>

You will need to setup the `Notification URL` on each Paylater Payment Channel by clicking the **CONFIGURE** button.


# HTTP Notification Sample for SNAP&#x20;

HTTP Notification sample for SNAP Payment Methods

After setting up your `Notification URL`, we will send the notification for certain events such as when the Virtual Account has been paid by your customers, etc.&#x20;

Once the customers finish the payment, DOKU will send the notification to your defined `Notification URL.`

### Virtual Account

Here is the sample notification that DOKU will send to merchant's server. For Virtual Account SNAP has same sample notification.&#x20;

The list of Virtual Account SNAP, you can find [here](/accept-payments/direct-api/snap/integration-guide/virtual-account).

{% openapi src="/files/AUFdbXiPyL51nDhr34MY" path="/v1/transfer-va/payment" method="post" %}
[Payment Notification.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FnQGwhUXSYpHnXNnr8gVY%2FPayment%20Notification.json?alt=media\&token=cc3fbba5-cbbb-4a36-b63d-0445e9901801)
{% endopenapi %}

### Direct Debit

Here is the sample notification that DOKU will send to merchant's server. For Direct Debit SNAP has same sample notification.&#x20;

The list of Direct Debit SNAP, you can find [here](/accept-payments/direct-api/snap/integration-guide/direct-debit).

{% openapi src="/files/v282JQBer9CUOaTIK0gk" path="/v1.0/debit/notify" method="post" %}
[dd-notify-snap.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FVcWNgbA2bsdEg6UwTdKt%2Fdd-notify-snap.json?alt=media\&token=d0b5dd88-56e0-416c-8b5f-78e59f0a15b8)
{% endopenapi %}

### E-wallet

The notification format for SNAP e-wallet transactions exhibits minor differences from those of other e-wallets. For further details please refer to sample notification below.&#x20;

#### 1. Binding Notification

## POST https\://{api-domain}/v1.0/debit/notify

> Binding Result Notification to Merchant

```json
{"openapi":"3.0.3","info":{"title":"Direct Debit Core System - Notify Binding to Merchant (EMONEY_OVO_SNAP)","version":"1.0.0"},"paths":{"https://{api-domain}/v1.0/debit/notify":{"post":{"summary":"Binding Result Notification to Merchant","description":null,"operationId":"notifyBindingMerchantEmoneyOvoSnap","tags":["Merchant Notification"],"parameters":[{"name":"X-PARTNER-ID","in":"header","required":true,"description":"The merchant's client ID registered with DOKU","schema":{"type":"string","maxLength":32}},{"name":"X-EXTERNAL-ID","in":"header","required":true,"description":"A unique ID generated by DOKU for each notification.\nThe merchant can use this value for idempotency checks.\n","schema":{"type":"string","maxLength":36}},{"name":"X-TIMESTAMP","in":"header","required":true,"description":"Notification send timestamp in ISO 8601 format (yyyy-MM-ddTHH:mm:ss+07:00)","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+\\-]\\d{2}:\\d{2}$"}},{"name":"X-SIGNATURE","in":"header","required":true,"description":"HMAC-SHA512 digital signature for verifying the authenticity of the notification.\nThe merchant MUST verify this signature before processing the notification.\n\n**Verification steps:**\n1. Construct `stringToSign`: `HTTP-METHOD:RELATIVE-URL:ACCESS-TOKEN:HEX(SHA256(requestBody)):TIMESTAMP`\n2. Compute HMAC-SHA512 using the merchant's `clientSecret` as the key.\n3. Compare against the value of this header.\n","schema":{"type":"string"}},{"name":"Authorization-Customer","in":"header","required":false,"description":"Customer's B2B2C access token (DOKU B2B2C token) associated with this binding session.\nPresent when the customer holds an active DOKU B2B2C token.\n","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindingNotificationRequest"}}}},"responses":{"200":{"description":"Notification successfully received and processed by the merchant.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindingNotificationResponse"}}}},"400":{"description":"Merchant could not parse or validate the notification request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindingNotificationErrorResponse"}}}},"401":{"description":"Merchant rejected the notification due to invalid or unverifiable signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindingNotificationErrorResponse"}}}},"500":{"description":"Internal server error on the merchant side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindingNotificationErrorResponse"}}}}}}}},"components":{"schemas":{"BindingNotificationRequest":{"type":"object","description":"Payload sent by DOKU to the merchant's binding notification URL","required":["originalExternalId","additionalInfo"],"properties":{"originalExternalId":{"type":"string","description":"The `X-EXTERNAL-ID` value from the original binding request submitted by the merchant.\nUsed by the merchant to correlate this notification with the original binding request.\n","maxLength":36},"additionalInfo":{"$ref":"#/components/schemas/BindingNotificationAdditionalInfo"}}},"BindingNotificationAdditionalInfo":{"type":"object","description":"Additional information about the binding result","required":["custIdMerchant","accountType","tokenId","channelId","status"],"properties":{"custIdMerchant":{"type":"string","description":"The merchant's customer ID, echoed from the original binding request"},"accountType":{"type":"string","description":"The type of acquirer account. Always `WALLET` for OVO.","enum":["WALLET"]},"tokenId":{"type":"string","description":"The DOKU token ID issued for this binding.\nUse this value as the `tokenId` in subsequent payment or balance inquiry requests.\nOnly meaningful when `status` is `SUCCESS`.\n"},"channelId":{"type":"string","description":"Identifies the acquirer and API version that processed the binding.\nFormat: `{acquirerId} {apiVersion}` — always `OVO SNAP` for this channel.\n"},"status":{"type":"string","description":"Final binding result:\n- `SUCCESS` — OTP verified; token is active and ready for payment.\n- `FAILED` — OTP failed or timed out; token has been invalidated.\n","enum":["SUCCESS","FAILED"]},"authCode":{"type":"string","description":"The session ID / OTP auth code from the binding flow.\nCorresponds to the `sessionId` of the binding session in DOKU.\n"}}},"BindingNotificationResponse":{"type":"object","description":"Expected acknowledgement from the merchant.\nDOKU only requires HTTP 200 — the response body is optional.\nIf provided, it should follow the SNAP response code format:\nHTTP Status (3) + Service Code `07` (2) + Case Code (2).\n","properties":{"responseCode":{"type":"string","description":"SNAP-format response code.\nExample: `2000700` = HTTP 200 + service `07` + case `00` (Successful).\n"},"responseMessage":{"type":"string","description":"Human-readable response message"}}},"BindingNotificationErrorResponse":{"type":"object","description":"Error acknowledgement from the merchant","properties":{"responseCode":{"type":"string","description":"SNAP-format error response code"},"responseMessage":{"type":"string","description":"Human-readable error message"}}}}}}
```

#### 2. Payment Notification

## Payment Notification to Merchant

> DOKU sends a payment transaction notification to the merchant's configured notification URL.<br>

```json
{"openapi":"3.0.3","info":{"title":"Direct Debit Core System - Notify Payment to Merchant (EMONEY)","version":"1.0.0"},"servers":[{"url":"https://{api-domain}","description":"Merchant notification URL (configured per merchant)","variables":{"merchant-notification-host":{"default":"merchant.example.com","description":"Merchant's registered notification host"}}}],"paths":{"/v1.0/debit/notify":{"post":{"summary":"Payment Notification to Merchant","description":"DOKU sends a payment transaction notification to the merchant's configured notification URL.\n","operationId":"notifyMerchantPaymentEmoneyDanaSnap","tags":["Merchant Notification"],"parameters":[{"name":"X-PARTNER-ID","in":"header","required":true,"description":"The merchant's client ID registered with DOKU","schema":{"type":"string","maxLength":36}},{"name":"X-EXTERNAL-ID","in":"header","required":true,"description":"A unique ID generated by DOKU for each notification.\nThe merchant can use this value for idempotency checks.\n","schema":{"type":"string","maxLength":32}},{"name":"X-TIMESTAMP","in":"header","required":true,"description":"Notification send timestamp in ISO 8601 format (yyyy-MM-ddTHH:mm:ss+07:00)","schema":{"type":"string"}},{"name":"X-SIGNATURE","in":"header","required":true,"description":"HMAC-SHA512 digital signature for verifying the authenticity of the notification.\nThe merchant must verify this signature before processing the notification.\n","schema":{"type":"string"}},{"name":"CHANNEL-ID","in":"header","required":false,"description":"The channel ID used. Default is \"DH\" (Direct Hosting)","schema":{"type":"string","default":"DH"}},{"name":"Authorization-Customer","in":"header","required":false,"description":"Customer B2B2C token (dokuB2b2cToken) if available from the binding process.\nOnly present if the customer has an active token.\n","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotifyPaymentRequest"}}}},"responses":{"200":{"description":"Notification successfully received and processed by the merchant.\nDOKU only requires HTTP 200 to consider the notification successful.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotifyMerchantResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotifyMerchantErrorResponse"}}}},"401":{"description":"Invalid or unverifiable signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotifyMerchantErrorResponse"}}}},"500":{"description":"Internal server error on the merchant side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotifyMerchantErrorResponse"}}}}}}}},"components":{"schemas":{"NotifyPaymentRequest":{"type":"object","description":"Payment notification body sent by DOKU to the merchant.\n","required":["originalPartnerReferenceNo","originalReferenceNo","originalExternalId","latestTransactionStatus","transactionStatusDesc","amount"],"properties":{"originalPartnerReferenceNo":{"type":"string","description":"The transaction invoice number used as the merchant's reference.\nThis value matches the `partnerReferenceNo` sent in the original payment request.\n","maxLength":64},"originalReferenceNo":{"type":"string","description":"The reference number assigned by the acquirer.\nCan be used for reconciliation purposes with the acquirer.\n","maxLength":64},"originalExternalId":{"type":"string","description":"External ID from the original payment request (the request ID sent by the merchant).","maxLength":36},"latestTransactionStatus":{"type":"string","description":"The latest transaction status as a two-digit code:\n- `00` — Success\n- `03` — Pending\n- `04` — Refunded\n- `05` — Canceled\n- `06` — Failed\n","maxLength":2},"transactionStatusDesc":{"type":"string","description":"Description of the transaction status, corresponding to `latestTransactionStatus`","maxLength":50},"amount":{"$ref":"#/components/schemas/AmountDto"},"additionalInfo":{"$ref":"#/components/schemas/PaymentAdditionalInfo"}}},"AmountDto":{"type":"object","description":"Transaction amount information","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction amount in two-decimal format (e.g. 50000.00)","maxLength":19},"currency":{"type":"string","description":"ISO 4217 currency code","maxLength":3}}},"PaymentAdditionalInfo":{"type":"object","description":"Additional information related to the payment transaction.","properties":{"channelId":{"type":"string","description":"The acquirer channel ID that processed the transaction"},"channel":{"type":"string","description":"DOKU product channel code"},"accountType":{"type":"string","description":"The acquirer account type used"},"custIdMerchant":{"type":"string","description":"The customer ID on the merchant side (merchant customer ID), if available from the token binding process"},"paymentType":{"type":"string","description":"The type of payment performed","enum":["SALE","RECURRING"]}}},"NotifyMerchantResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","description":"Response code in the format: HTTP Status Code (3 digits) + Service Code (2 digits) + Case Code (2 digits).\nThe service code for notify is `56`.\n"},"responseMessage":{"type":"string","description":"Response message"},"approvalCode":{"type":"string","description":"Approval Code"}}},"NotifyMerchantErrorResponse":{"type":"object","description":"Error response from the merchant","properties":{"responseCode":{"type":"string","description":"Error response code"},"responseMessage":{"type":"string","description":"Error message"}}}}}}
```

#### 3. Refund Notification

## Refund Notification to Merchant

> DOKU sends a refund transaction notification to the merchant's configured notification URL.<br>

```json
{"openapi":"3.0.3","info":{"title":"Direct Debit Core System - Notify Refund to Merchant (EMONEY)","version":"1.0.0"},"servers":[{"url":"https://{api-domain}","description":"Merchant notification URL (configured per merchant)","variables":{"merchant-notification-host":{"default":"merchant.example.com","description":"Merchant's registered notification host"}}}],"paths":{"/v1.0/debit/notify":{"post":{"summary":"Refund Notification to Merchant","description":"DOKU sends a refund transaction notification to the merchant's configured notification URL.\n","operationId":"notifyMerchantRefundEmoneyDanaSnap","tags":["Merchant Notification"],"parameters":[{"name":"X-PARTNER-ID","in":"header","required":true,"description":"The merchant's client ID registered with DOKU","schema":{"type":"string","maxLength":36}},{"name":"X-EXTERNAL-ID","in":"header","required":true,"description":"A unique ID generated by DOKU for each notification.\nThe merchant can use this value for idempotency checks.\n","schema":{"type":"string","maxLength":32}},{"name":"X-TIMESTAMP","in":"header","required":true,"description":"Notification send timestamp in ISO 8601 format (yyyy-MM-ddTHH:mm:ss+07:00)","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+\\-]\\d{2}:\\d{2}$"}},{"name":"X-SIGNATURE","in":"header","required":true,"description":"HMAC-SHA512 digital signature for verifying the authenticity of the notification.\nThe merchant must verify this signature before processing the notification.\n","schema":{"type":"string"}},{"name":"CHANNEL-ID","in":"header","required":false,"description":"The channel ID used. Default is \"DH\" (Direct Hosting)","schema":{"type":"string","default":"DH"}},{"name":"Authorization-Customer","in":"header","required":false,"description":"Customer B2B2C token (dokuB2b2cToken) if available from the binding process.\nOnly present if the customer has an active token.\n","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotifyRefundRequest"}}}},"responses":{"200":{"description":"Notification successfully received and processed by the merchant.\nDOKU only requires HTTP 200 to consider the notification successful.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotifyMerchantResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotifyMerchantErrorResponse"}}}},"401":{"description":"Invalid or unverifiable signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotifyMerchantErrorResponse"}}}},"500":{"description":"Internal server error on the merchant side","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotifyMerchantErrorResponse"}}}}}}}},"components":{"schemas":{"NotifyRefundRequest":{"type":"object","description":"Refund notification body sent by DOKU to the merchant.\n","required":["originalPartnerReferenceNo","originalReferenceNo","originalExternalId","latestTransactionStatus","transactionStatusDesc","amount"],"properties":{"originalPartnerReferenceNo":{"type":"string","description":"The invoice number of the original payment transaction.\nThis value matches the `partnerReferenceNo` sent in the original payment request.\n","maxLength":64},"originalReferenceNo":{"type":"string","description":"The reference number assigned by the acquirer for the original payment.\nCan be used for reconciliation purposes with acquirer.\n","maxLength":64},"originalExternalId":{"type":"string","description":"External ID from the original payment request (the request ID sent by the merchant).","maxLength":36},"latestTransactionStatus":{"type":"string","description":"The latest transaction status as a two-digit code:\n- `00` — Success\n- `03` — Pending\n- `06` — Failed\n","maxLength":2},"transactionStatusDesc":{"type":"string","description":"Human-readable description of the transaction status, corresponding to `latestTransactionStatus`","maxLength":50},"amount":{"$ref":"#/components/schemas/AmountDto"},"additionalInfo":{"$ref":"#/components/schemas/RefundAdditionalInfo"}}},"AmountDto":{"type":"object","description":"Original payment transaction amount","required":["value","currency"],"properties":{"value":{"type":"string","description":"Amount in two-decimal format (e.g. 50000.00)","maxLength":19},"currency":{"type":"string","description":"ISO 4217 currency code","maxLength":3}}},"RefundAdditionalInfo":{"type":"object","description":"Additional information related to refund transaction.","properties":{"channelId":{"type":"string","description":"The acquirer channel ID that processed the transaction"},"channel":{"type":"string","description":"DOKU product channel code"},"accountType":{"type":"string","description":"The acquirer account type used"},"custIdMerchant":{"type":"string","description":"The customer ID on the merchant side, if available from the token binding process"},"paymentType":{"type":"string","description":"The type of the original payment","enum":["SALE","RECURRING"]},"refundNo":{"type":"string","description":"The refund reference number assigned by the acquirer"},"partnerRefundNo":{"type":"string","description":"The refund number from the merchant/partner side (the `partnerRefundNo` sent in the refund request)"},"refundAmount":{"$ref":"#/components/schemas/AmountDto"}}},"NotifyMerchantResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","description":"Response code in the format: HTTP Status Code (3 digits) + Service Code (2 digits) + Case Code (2 digits).\nThe service code for notify is `56`.\n"},"responseMessage":{"type":"string","description":"Response message"},"approvalCode":{"type":"string","description":"Approval Code"}}},"NotifyMerchantErrorResponse":{"type":"object","description":"Error response from the merchant","properties":{"responseCode":{"type":"string","description":"Error response code"},"responseMessage":{"type":"string","description":"Error message"}}}}}}
```


# HTTP Notification Sample - Non SNAP

HTTP Notification Sample for Payment Method Non SNAP

After setting up your `Notification URL`, we will send the notification for certain events such as when the Virtual Account has been paid by your customers, Credit Card has been charged, Credit Card failed, and etc.

Once the customers finish the payment, DOKU will send the notification to your defined `Notification URL`.&#x20;

### Virtual Account

Here is the sample notification that DOKU will send to merchant's server :

<table data-full-width="false"><thead><tr><th>Type</th><th>Value</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr></tbody></table>

Here is the sample of notification request header :

```json
Client-Id: MCH-0001-10791114622547
Request-Id: 479b663f-5c9d-400d-8e80-3e548a8f7639
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
```

<table><thead><tr><th width="190">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Client ID you retrieved from DOKU Back Office</td></tr><tr><td><strong>Request-Id</strong></td><td>Unique random string (max 128 characters) that generated by DOKU to make sure no duplicate notification</td></tr><tr><td><strong>Request-Timestamp</strong></td><td>Time Stamp request on UTC time in ISO8601 format</td></tr><tr><td><strong>Signature</strong></td><td>Verify the Signature to ensure the Notification Authenticity coming from DOKU. Please refer to <a href="/pages/VogdJfoJtS2yXvClOsrc">this section</a></td></tr></tbody></table>

Here is the sample notification request body :

{% tabs %}
{% tab title="BCA VA" %}

```json
{
    "service": {
        "id": "VIRTUAL_ACCOUNT"
    },
    "acquirer": {
        "id": "BCA"
    },
    "channel": {
        "id": "VIRTUAL_ACCOUNT_BCA"
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2021-01-27T03:24:23Z",
        "original_request_id": "15022aab-444f-4b04-afa8-ddfce89432ec"
    },
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "virtual_account_info": {
        "virtual_account_number": "1900600000000046"
    },
    "virtual_account_payment": {
        "identifer": [
            {
                "name": "REQUEST_ID",
                "value": "7892931"
            },
            {
                "name": "REFERENCE",
                "value": "6769200"
            },
            {
                "name": "CHANNEL_TYPE",
                "value": "6010"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="Mandiri VA" %}

```json
{
    "service": {
        "id": "VIRTUAL_ACCOUNT"
    },
    "acquirer": {
        "id": "BANK_MANDIRI"
    },
    "channel": {
        "id": "VIRTUAL_ACCOUNT_BANK_MANDIRI"
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2021-01-27T07:24:50Z",
        "original_request_id": "cc682442-6c22-493e-8121-b9ef6b3fa728"
    },
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "virtual_account_info": {
        "virtual_account_number": "8889940000000213"
    },
    "virtual_account_payment": {
        "identifier": [
            {
                "name": "TRANSACTION_ID",
                "value": "8341422"
            },
            {
                "name": "CHANNEL_ID",
                "value": "001"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="BSI VA" %}

```json
{
    "service": {
        "id": "VIRTUAL_ACCOUNT"
    },
    "acquirer": {
        "id": "BANK_SYARIAH_MANDIRI"
    },
    "channel": {
        "id": "VIRTUAL_ACCOUNT_BANK_SYARIAH_MANDIRI"
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2021-01-27T06:00:20Z",
        "original_request_id": "d24a5644-6078-4249-8740-4a6dcd92df5a"
    },
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "virtual_account_info": {
        "virtual_account_number": "6059000000000205"
    },
    "virtual_account_payment": {
        "identifier": [
            {
                "name": "PAY_TERMINAL_ID",
                "value": ""
            },
            {
                "name": "BANK_REFERENCE",
                "value": "1232990188"
            },
            {
                "name": "PAY_CHANNEL",
                "value": "6019"
            }
        ]
    }
}

```

{% endtab %}

{% tab title="BRI VA " %}

```json
{
    "service": {
        "id": "VIRTUAL_ACCOUNT"
    },
    "acquirer": {
        "id": "BRI"
    },
    "channel": {
        "id": "VIRTUAL_ACCOUNT_BRI"
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2020-08-11T09:06:18Z",
        "original_request_id": "e5a8a8b8-7eab-4be3-91d8-5e2d7ab7cc25"
    },
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "virtual_account_info": {
        "virtual_account_number": "1236260000000004"
    },
    "virtual_account_payment": {
        "identifier": [
            {
                "name": "TRANSAKSI_ID",
                "value": "127503812"
            },
            {
                "name": "TERMINAL_ID",
                "value": "1"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="BNI VA" %}

```json
{
  "service": {
    "id": "VIRTUAL_ACCOUNT"
  },
  "acquirer": {
    "id": "BNI"
  },
  "channel": {
    "id": "VIRTUAL_ACCOUNT_BNI"
  },
  "order": {
    "invoice_number": "INV-1640337742",
    "amount": 20000
  },
  "virtual_account_info": {
    "virtual_account_number": "8803300000000098",
    "merchant_unique_reference": "UNIQUE_00003",
    "billing_type": "FIXED",
    "identifier":[
      {
        "name": "BILLING_NUMBER",
        "value": "3280300000000001234"
      }
    ]
  },
  "virtual_account_payment": {
    "identifier": [
      {
        "name": "TRX_ID",
        "value": "11901640337564039UNIQUE_00003"
      },
      {
        "name": "PAYMENT_NTB",
        "value": "228853"
      }
    ]
  },
  "transaction": {
    "status": "SUCCESS",
    "date": "2021-12-24T16:23:39Z",
    "original_request_id": "456b001e-adc8-4fb8-a976-95831fb61468"
  }
}
```

{% endtab %}

{% tab title="DOKU VA" %}

```json
{
    "service": {
        "id": "VIRTUAL_ACCOUNT"
    },
    "acquirer": {
        "id": "DOKU"
    },
    "channel": {
        "id": "VIRTUAL_ACCOUNT_DOKU"
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2021-01-22T07:06:28Z",
        "original_request_id": "09e0defe-a071-45b3-9feb-ac134374628c"
    },
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "virtual_account_info": {
        "virtual_account_number": "8000100000000323"
    },
    "virtual_account_payment": {
        "identifier": [
            {
                "name": "TRACE_NUMBER",
                "value": "19832"
            },
            {
                "name": "TRANSACTION_NUMBER",
                "value": "d094700e379f0fb3b543e25c77f8e4b3e068f057"
            },
            {
                "name": "HOST_REFERENCE_NUMBER",
                "value": ""
            }
        ]
    }
}
```

{% endtab %}

{% tab title="CIMB VA" %}

```json
{
    "service": {
        "id": "VIRTUAL_ACCOUNT"
    },
    "acquirer": {
        "id": "CIMB"
    },
    "channel": {
        "id": "VIRTUAL_ACCOUNT_BANK_CIMB"
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2020-08-11T09:06:18Z",
        "original_request_id": "e5a8a8b8-7eab-4be3-91d8-5e2d7ab7cc25"
    },
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "virtual_account_info": {
        "virtual_account_number": "1236260000000004"
    },
    "virtual_account_payment": {
        "identifier": [
            {
                "name": "TRANSAKSI_ID",
                "value": "127503812"
            },
            {
                "name": "TERMINAL_ID",
                "value": "1"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="PERMATA VA" %}

```json
{
    "service": {
        "id": "VIRTUAL_ACCOUNT"
    },
    "acquirer": {
        "id": "BANK_PERMATA"
    },
    "channel": {
        "id": "VIRTUAL_ACCOUNT_BANK_PERMATA"
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2020-08-11T09:06:18Z",
        "original_request_id": "e5a8a8b8-7eab-4be3-91d8-5e2d7ab7cc25"
    },
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "virtual_account_info": {
        "virtual_account_number": "1236260000000004"
    },
    "virtual_account_payment": {
        "identifier": [
            {
                "name": "TRANSAKSI_ID",
                "value": "127503812"
            },
            {
                "name": "TERMINAL_ID",
                "value": "1"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="DANAMON VA" %}

```json
{
  "acquirer": {
    "id": "BANK_DANAMON",
    "name": "Bank Danamon"
  },
  "service": {
    "id": "VIRTUAL_ACCOUNT",
    "name": "Virtual Account"
  },
  "channel": {
    "id": "VIRTUAL_ACCOUNT_BANK_DANAMON",
    "name": "Virtual Account Bank Danamon"
  },
  "order": {
    "invoice_number": "INV-1635748123946513",
    "amount": 20000
  },
  "virtual_account_info": {
    "virtual_account_number": "8922600000000063"
  },
  "virtual_account_payment": {
    "reference_number": "AFNGf6wAWrFe2LSmpfXviRXYv7nPK1LOsao9TtLC",
    "date": "20211206152845",
    "identifier": [
      {
        "name": "USER_REF_NO",
        "value": "AFNGf6wAWrFe2LSmpfXviRXYv7nPK1LOsao9TtLC"
      },
      {
        "name": "PAY_ACCOUNT",
        "value": "706913838473"
      },
      {
        "name": "PAY_BANK",
        "value": "Danamon"
      },
      {
        "name": "PAY_DESC",
        "value": "Payment Simulator for 8922600000000063"
      },
      {
        "name": "PAY_AMOUNT",
        "value": "20000"
      },
      {
        "name": "BILL_AMOUNT",
        "value": "20000"
      }
    ]
  },
  "transaction": {
    "status": "SUCCESS",
    "original_request_id": "b693d940-bd15-4b85-9d02-57844c4039e3",
    "date": "2021-12-06T08:28:45Z"
  }
}
```

{% endtab %}
{% endtabs %}

#### Virtual Account Notification Explanation&#x20;

<table><thead><tr><th>Parameter</th><th width="82">Type</th><th width="114">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>service.id</code></td><td>string</td><td>Mandatory</td><td>The service that is used for the transaction</td></tr><tr><td><code>acquirer.id</code></td><td>string</td><td>Mandatory</td><td>The acquirer that processed the transaction</td></tr><tr><td><code>channel.id</code></td><td>string</td><td>Mandatory</td><td>The channel of the transaction</td></tr><tr><td><code>transaction.status</code></td><td>string</td><td>Mandatory</td><td>The transaction status to be use to update the status on merchant side<br><em>Possible value: <code>SUCCESS</code> since VA only notify when payment is success</em></td></tr><tr><td><code>transaction.date</code></td><td>string</td><td>Mandatory</td><td>The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)</td></tr><tr><td><code>transaction.original_request_id</code></td><td>string</td><td>Mandatory</td><td>The request ID that sent when initiate the payment</td></tr><tr><td><code>order.invoice_number</code></td><td>string</td><td>Mandatory</td><td>Same as the request that merchant sent on the payment initiation</td></tr><tr><td><code>order.amount</code></td><td>number</td><td>Mandatory</td><td>Same as the request that merchant sent on the payment initiation</td></tr><tr><td><code>virtual_account_info.</code><br><code>virtual_account_number</code></td><td>string</td><td>Mandatory</td><td>The virtual account number that used for the transaction</td></tr><tr><td><code>virtual_account_payment.identifier</code></td><td>string</td><td>Optional</td><td>List of transaction identifier that coming from the acquiring. Merchant can save these data for reference</td></tr></tbody></table>

### Credit Card

Here is the sample notification that DOKU will send to merchant's server.

<table data-full-width="false"><thead><tr><th>Type</th><th>Value</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr></tbody></table>

Here is the sample notification **request header** :&#x20;

```
Client-Id: MCH-0001-10791114622547
Request-Id: 370c993c-e5ee-4dfc-9e47-0474b55c7b4b
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps
```

<table><thead><tr><th width="143">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Client ID you retrieved from DOKU Back Office</td></tr><tr><td><strong>Request-Id</strong></td><td>Unique random string (max 128 characters) that generated by DOKU to make sure no duplicate notification</td></tr><tr><td><strong>Request-Timestamp</strong></td><td>Time Stamp request on UTC time in ISO8601 format</td></tr><tr><td><strong>Signature</strong></td><td>Verify the Signature to ensure the Notification Authenticity coming from DOKU. Please refer to <a href="/pages/VogdJfoJtS2yXvClOsrc">this section</a></td></tr></tbody></table>

Here is the sample notification **request body** :&#x20;

{% tabs %}
{% tab title="Transaction" %}

```
{
  "order": {
    "invoice_number": "INV-1781838439",
    "amount": 102
  },
  "customer": {
    "name": "Anton Budiman",
    "email": "anton@doku.com"
  },
  "transaction": {
    "type": "SALE",
    "status": "SUCCESS",
    "date": "2026-06-19T03:15:26Z",
    "original_request_id": "a7b6b92b-e553-4810-8b46-945270b732ea"
  },
  "service": {
    "id": "CREDIT_CARD"
  },
  "acquirer": {
    "id": "BANK_CIMB"
  },
  "channel": {
    "id": "CREDIT_CARD",
    "name": "Credit Card"
  },
  "additional_info": {
    "origin": {
      "source": "direct",
      "system": "mid-jokul-checkout-system",
      "product": "CHECKOUT",
      "apiFormat": "JOKUL"
    },
    "line_items": [
      {
        "name": "DOKU T-Shirt",
        "price": "102",
        "quantity": 1.0
      }
    ]
  },
  "authorize_id": "16920747459243358",
  "card_payment": {
    "masked_card_number": "539371******3085",
    "approval_code": "679870",
    "response_code": "00",
    "response_message": "Approved",
    "issuer": "PT BANK CENTRAL ASIA Tbk",
    "identifier": [
      {
        "name": "Acquirer",
        "value": "BANK_CIMB"
      },
      {
        "name": "MID",
        "value": "CN910090481"
      }
    ],
    "brand": "MASTER",
    "authentication_id": "fce40e9221ed8c263f0922f9efaad7c1562f409cc260418235ac5cc0975451dd",
    "three_d_secure_status": "TRUE",
    "cardholder_name": "Anton Budiman"
  },
  "verification": {
    "status": "APPROVE",
    "reason": "Decision BIN Indonesia & 3D Secure"
  }
}
```

{% endtab %}

{% tab title="Void" %}

```
{
  "order": {
    "invoice_number": "irminsul_subscription_fee",
    "amount": 5000
  },
  "customer": {
    "name": "Nahida",
    "email": "Nahida@dokupayment.com"
  },
  "transaction": {
    "status": "VOIDED",
    "date": "2026-06-17T11:34:38Z",
    "original_request_id": "BO-258898"
  },
  "service": {
    "id": "CREDIT_CARD"
  },
  "acquirer": {
    "id": "BANK_CIMB"
  },
  "channel": {
    "id": "CREDIT_CARD"
  },
  "card_payment": {
    "masked_card_number": "455633******4805",
    "response_code": "00",
    "response_message": "Transaction Has Been Successfully Void"
  }
}
```

{% endtab %}

{% tab title="Refund" %}

```
{
  "order": {
    "invoice_number": "INV-1779245067",
    "amount": 1001
  },
  "customer": {
    "name": "Anton Budiman",
    "email": "anton@doku.com"
  },
  "transaction": {
    "status": "REFUNDED",
    "date": "2026-05-25T03:05:24Z",
    "original_request_id": "BO-34204"
  },
  "service": {
    "id": "CREDIT_CARD"
  },
  "acquirer": {
    "id": "BANK_MANDIRI"
  },
  "channel": {
    "id": "CREDIT_CARD"
  },
  "card_payment": {
    "masked_card_number": "455633******8800",
    "approval_code": "078786",
    "response_code": "00",
    "response_message": "Transaction Has Been Successfully Refund"
  }
}
```

{% endtab %}

{% tab title="Capture" %}

```
{
  "order": {
    "invoice_number": "test_capture",
    "amount": 200
  },
  "customer": {
    "name": "Gavin Berge",
    "email": "testana@gmail.com"
  },
  "transaction": {
    "type": "CAPTURE",
    "status": "SUCCESS",
    "date": "2026-07-06T07:34:55Z",
    "original_request_id": "10880"
  },
  "service": {
    "id": "CREDIT_CARD"
  },
  "acquirer": {
    "id": "BRI"
  },
  "channel": {
    "id": "CREDIT_CARD",
    "name": "Credit Card"
  },
  "additional_info": {
    "override_notification_url": "https://another.example.com/payments/notifications",
  },
  "card_payment": {
    "masked_card_number": "403203******3207",
    "approval_code": "778418",
    "response_code": "00",
    "response_message": "Approved",
    "issuer": "PT BANK RAKYAT INDONESIA (PERSERO) Tbk",
    "identifier": [
      {
        "name": "Acquirer",
        "value": "BRI"
      },
      {
        "name": "MID",
        "value": "66983733"
      }
    ],
    "brand": "VISA",
    "authentication_id": "",
    "three_d_secure_status": "FALSE"
  },
  "verification": {
    "status": "NA"
  }
}
```

{% endtab %}
{% endtabs %}

#### Credit Card Notification Explanation

<table><thead><tr><th width="271">Parameter</th><th width="112">Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.invoice_number</code></td><td>string</td><td>Mandatory</td><td>Same as the request that merchant sent on the payment initiation</td></tr><tr><td><code>order.amount</code></td><td>number</td><td>Mandatory</td><td>Same as the request that merchant sent on the payment initiation</td></tr><tr><td><code>customer.id</code></td><td>string</td><td>Mandatory</td><td>Same as the request that merchant sent on the payment initiation</td></tr><tr><td><code>customer.name</code></td><td>string</td><td>Optional</td><td>Same as the request that merchant sent on the payment initiation</td></tr><tr><td><code>customer.email</code></td><td>string</td><td>Optional</td><td>Same as the request that merchant sent on the payment initiation</td></tr><tr><td><code>transaction.type</code></td><td>string</td><td>Mandatory</td><td>Transaction Type<br>Possible value: <code>SALE, INSTALLMENT, AUTHORIZE, MOTO</code></td></tr><tr><td><code>transaction.status</code></td><td>string</td><td>Mandatory</td><td>The transaction status to be use to update the status on merchant side<br>Possible value: <code>SUCCESS, FAILED</code></td></tr><tr><td><code>transaction.date</code></td><td>string</td><td>Mandatory</td><td>The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)</td></tr><tr><td><code>transaction.original_request_id</code></td><td>string</td><td>Mandatory</td><td>The request ID that sent when initiate the payment</td></tr><tr><td><code>service.id</code></td><td>string</td><td>Mandatory</td><td>The service that is used for the transaction</td></tr><tr><td><code>acquirer.id</code></td><td>string</td><td>Mandatory</td><td>The acquirer that processed the transaction</td></tr><tr><td><code>channel.id</code></td><td>string</td><td>Mandatory</td><td>The channel of the transaction`</td></tr><tr><td><code>authorize_id</code></td><td>string</td><td>Optional</td><td>Used to capture transaction in<br><code>Authorize Capture</code> transaction</td></tr><tr><td><code>card_payment.masked_card_number</code></td><td>string</td><td>Optional</td><td>The masked card number that charged for this transaction</td></tr><tr><td><code>card_payment.approval_code</code></td><td>string</td><td>Optional</td><td>Acquirer approval code for this transaction</td></tr><tr><td><code>card_payment.response_code</code></td><td>string</td><td>Optional</td><td>DOKU / Acquirer response code</td></tr><tr><td><code>card_payment.response_message</code></td><td>string</td><td>Optional</td><td>DOKU / Acquirer response message</td></tr><tr><td><code>card_payment.issuer</code></td><td>string</td><td>Optional</td><td>Card Issuer</td></tr><tr><td><code>card_payment.brand</code></td><td>string</td><td>Optional</td><td>Card's Brand </td></tr><tr><td><code>card_payment.authentication_id</code></td><td>string</td><td>Optional</td><td>3DS's authentication ID</td></tr><tr><td><code>card_payment.three_d_secure_status</code></td><td>string</td><td>Optional</td><td>3DS's authentication result status</td></tr></tbody></table>

### Convenience Store

Here is the sample notification that DOKU will send to merchant's server.

<table data-full-width="false"><thead><tr><th>Type</th><th>Value</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr></tbody></table>

Here is the sample notification **request header** :&#x20;

```
Client-Id: MCH-0001-10791114622547
Request-Id: 370c993c-e5ee-4dfc-9e47-0474b55c7b4b
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps
```

<table><thead><tr><th width="143">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Client ID you retrieved from DOKU Back Office</td></tr><tr><td><strong>Request-Id</strong></td><td>Unique random string (max 128 characters) that generated by DOKU to make sure no duplicate notification</td></tr><tr><td><strong>Request-Timestamp</strong></td><td>Time Stamp request on UTC time in ISO8601 format</td></tr><tr><td><strong>Signature</strong></td><td>Verify the Signature to ensure the Notification Authenticity coming from DOKU. Please refer to <a href="/pages/VogdJfoJtS2yXvClOsrc">this section</a></td></tr></tbody></table>

Here is the sample notification **request body** :&#x20;

{% tabs %}
{% tab title="Alfa Group" %}

```json
{
    "service": {
        "id": "ONLINE_TO_OFFLINE"
    },
    "acquirer": {
        "id": "ALFA"
    },
    "channel": {
        "id": "ONLINE_TO_OFFLINE_ALFA"
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2021-08-12T07:06:28Z",
        "original_request_id": "5b8e438f-fac1-4103-9e0e-ebfdc38b5acb"
    },
    "order": {
        "invoice_number": "INV-20210125-0001",
        "amount": 150000
    },
    "online_to_offline_info": {
        "payment_code": "73"
    },
    "online_to_offline_payment": {
        "identifier": [
            {
                "name": "AGENT_ID",
                "value": "ALFAMART"
            },
            {
                "name": "AGENT_STORE_ID",
                "value": "store"
            },
            {
                "name": "AGENT_TRX_ID",
                "value": "1246"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="Alfa Group for Insurance" %}

```json
{
    "service": {
        "id": "ONLINE_TO_OFFLINE"
    },
    "acquirer": {
        "id": "ALFA"
    },
    "channel": {
        "id": "ONLINE_TO_OFFLINE_ALFA"
    },
    "order": {
        "invoice_number": "INV-20210125-0001",
        "amount": 150000
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2021-01-22T07:06:28Z",
        "original_request_id": "2103"
    },
    "online_to_offline_info": {
        "payment_code": "8896512345678123"
    },
    "online_to_offline_payment": {
        "identifier": [
            {
                "name": "AGENT_ID",
                "value": "100001"
            },
            {
                "name": "AGENT_STORE_ID",
                "value": "10000232"
            },
            {
                "name": "AGENT_TRX_ID",
                "value": "c1aa04bf421e5b38c3d18933e9994d3f289def65"
            }
        ]
    },
    "additional_info": {
        "insurance_info": {
            "policy_type": "Dana Pendidikan",
            "policy_number": "9090901234",
            "policy_account_name": "Andreas",
            "policy_status": "aktif",
            "bill_due_date": "21 May 2021"
        }
    }
}
```

{% endtab %}

{% tab title="Indomaret" %}

```json
{
    "service": {
        "id": "ONLINE_TO_OFFLINE"
    },
    "acquirer": {
        "id": "INDOMARET"
    },
    "channel": {
        "id": "ONLINE_TO_OFFLINE_INDOMARET"
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2021-08-12T07:06:28Z",
        "original_request_id": "5b8e438f-fac1-4103-9e0e-ebfdc38b5acb"
    },
    "order": {
        "invoice_number": "INV-20210125-0001",
        "amount": 150000
    },
    "online_to_offline_info": {
        "payment_code": "73"
    },
    "online_to_offline_payment": {
        "identifier": [
            {
                "name": "AGENT_ID",
                "value": "INDOMARET"
            },
            {
                "name": "AGENT_STORE_ID",
                "value": "store"
            },
            {
                "name": "AGENT_TRX_ID",
                "value": "1246"
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}

#### Convenience Store Notification Explanation

<table><thead><tr><th width="199">Parameter</th><th width="100">Type</th><th width="117">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>service.id</code></td><td>string</td><td>Mandatory</td><td>The service that is used for the transaction</td></tr><tr><td><code>acquirer.id</code></td><td>string</td><td>Mandatory</td><td>The acquirer that processed the transaction</td></tr><tr><td><code>channel.id</code></td><td>string</td><td>Mandatory</td><td>The channel of the transaction</td></tr><tr><td><code>transaction.status</code></td><td>string</td><td>Mandatory</td><td>The transaction status to be use to update the status on merchant side<br>Possible value: <code>SUCCESS</code> since Convenience Store only notify when payment is success</td></tr><tr><td><code>transaction.date</code></td><td>string</td><td>Mandatory</td><td>The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)</td></tr><tr><td><code>transaction.original_request_id</code></td><td>string</td><td>Mandatory</td><td>The request ID that sent when initiate the payment</td></tr><tr><td><code>order.invoice_number</code></td><td>string</td><td>Mandatory</td><td>The invoice number that sent when initate the payment</td></tr><tr><td><code>order.amount</code></td><td>string</td><td>Mandatory</td><td>The amount of the transaction</td></tr><tr><td><code>online_to_offline_info.</code><br><code>payment_code</code></td><td>string</td><td>Mandatory</td><td>The payment code number that used for the transaction</td></tr><tr><td><code>online_to_offline_payment.identifier</code></td><td>array</td><td>Optional</td><td>Same as the inquiry response</td></tr><tr><td><code>additional_info</code></td><td>json</td><td>Optional</td><td>Same as the additional_info from the request</td></tr></tbody></table>

### E-wallet

Here is the sample notification that DOKU will send to merchant's server.

<table data-full-width="false"><thead><tr><th>Type</th><th>Value</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr></tbody></table>

Here is the sample notification **request header** :&#x20;

```
Client-Id: MCH-0001-10791114622547
Request-Id: 370c993c-e5ee-4dfc-9e47-0474b55c7b4b
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps
```

<table><thead><tr><th width="143">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Client ID you retrieved from DOKU Back Office</td></tr><tr><td><strong>Request-Id</strong></td><td>Unique random string (max 128 characters) that generated by DOKU to make sure no duplicate notification</td></tr><tr><td><strong>Request-Timestamp</strong></td><td>Time Stamp request on UTC time in ISO8601 format</td></tr><tr><td><strong>Signature</strong></td><td>Verify the Signature to ensure the Notification Authenticity coming from DOKU. Please refer to <a href="/pages/VogdJfoJtS2yXvClOsrc">this section</a></td></tr></tbody></table>

Here is the sample notification **request body** :&#x20;

{% tabs %}
{% tab title="Shopeepay" %}

```json
{
    "service":{
        "id": "EMONEY"
    },
    "acquirer":{
        "id": "SHOPEE_PAY"
    },
    "channel":{
        "id": "EMONEY_SHOPEE_PAY"
    },
    "order":{
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "transaction":{
        "status": "SUCCESS",
        "date": "2021-07-09T02:06:14Z",
        "original_request_id": "24bb5232-3fe6-47a5-b0b0-d0fc3c6b5fdb"
    },
    "shopeepay_configuration":{
        "merchant_ext_id": "846609710695590",
        "store_ext_id": "99012984"
    },
    "shopeepay_payment":{
        "transaction_status": "3",
        "transaction_message": "SUCCESS",
        "identifier": [
            {
                "name": "PAYMENT_REFERENCE_ID",
                "value": "INV-20210124-0001"
            },
            {
                "name": "TRANSACTION_SN",
                "value": "5928618974087420594542231456745334310931540501886465026193020656"
            },
            {
                "name": "USER_ID_HASH",
                "value": "1933182965027045219980555801600298133716162755914500208775934992"
            }
        ]
    }
}
```

#### Shopeepay Notification Explanation

<table><thead><tr><th width="165">Parameter</th><th width="90">Type</th><th width="123">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>service.id</code></td><td>string</td><td>Mandatory</td><td>The service that is used for the transaction</td></tr><tr><td><code>acquirer.id</code></td><td>string</td><td>Mandatory</td><td>The acquirer that processed the transaction</td></tr><tr><td><code>channel.id</code></td><td>string</td><td>Mandatory</td><td>The channel of the transaction</td></tr><tr><td><code>order.invoice_number</code></td><td>string</td><td>Mandatory</td><td>The invoice number that sent when initate the payment</td></tr><tr><td><code>order.amount</code></td><td>string</td><td>Mandatory</td><td>The amount of the transaction</td></tr><tr><td><code>transaction.status</code></td><td>string</td><td>Mandatory</td><td>The transaction status to be use to update the status on merchant side<br>Possible value: <code>SUCCESS, FAILED</code></td></tr><tr><td><code>transaction.date</code></td><td>string</td><td>Mandatory</td><td>The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)</td></tr><tr><td><code>transaction.original_request_id</code></td><td>string</td><td>Mandatory</td><td>The request ID that sent when initiate the payment</td></tr><tr><td><code>shopeepay_configuration.</code><br><code>merchant_ext_id</code></td><td>string</td><td>Optional</td><td>The credential from ShopeePay</td></tr><tr><td><code>shopeepay_configuration.</code><br><code>store_ext_id</code></td><td>string</td><td>Optional </td><td>The credential from ShopeePay</td></tr><tr><td><code>shopeepay_payment.</code><br><code>transaction_status</code></td><td>string</td><td>Optional</td><td>The status code from ShopeePay<br>Possible value: <code>3</code> for success, <code>4</code> for failed</td></tr><tr><td><code>shopeepay_payment.</code><br><code>transaction_message</code></td><td>string</td><td>Optional</td><td>The status message from ShopeePay<br>Possible value: <code>SUCCESS, FAILED</code></td></tr><tr><td><code>shopeepay_payment.identifier</code></td><td>array</td><td>Optional</td><td>List of transaction identifier that coming from the acquiring. Merchant can save these data for reference</td></tr></tbody></table>
{% endtab %}

{% tab title="OVO Open API" %}
DOKU OVO Open API will publish 3 scenarios that are in the process before payment to after payment. Here are the cases that will be published :

1. [Binding](#binding)
2. [Payment](#payment)
3. [Refund](#refund)

#### Binding

```json
{
    "service":{
        "id":"EMONEY"
    },
    "acquirer":{
        "id":"OVO"
    },
    "channel":{
        "id":"EMONEY_OVO"
    },
    "customer":{
        "id":"123123123",
        "name":"Joko",
        "email":"joko@gmail.com",
        "phone":"081287458232",
        "additional_info":"Test"
    },
    "wallet": {
        "issuer": "OVO",
        "token_id": "410d3bce942991550d81f20171234df3",
        "masked_phone_number": "****0621",
        "status":"SUCCESS"
    }
}
```

#### OVO Open API - Binding Notification Explanation

<table><thead><tr><th width="195">Parameter</th><th width="82">Type</th><th width="126">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>service.id</code></td><td>string</td><td>Mandatory</td><td>The service that is used for the transaction</td></tr><tr><td><code>acquirer.id</code></td><td>string</td><td>Mandatory</td><td>The acquirer that processed the transaction</td></tr><tr><td><code>channel.id</code></td><td>string</td><td>Mandatory</td><td>The channel of the transaction</td></tr><tr><td><code>customer.id</code></td><td>string</td><td>Mandatory</td><td>Merchant customer ID</td></tr><tr><td><code>customer.name</code></td><td>string</td><td>Optional</td><td>Customer name that sent when initiate the payment</td></tr><tr><td><code>customer.email</code></td><td>string</td><td>Optional</td><td>Customer email that sent when initiate the payment</td></tr><tr><td><code>customer.phone</code></td><td>string</td><td>Optional</td><td>Customer phone that sent when initiate the payment</td></tr><tr><td><code>customer.additional_info</code></td><td>string</td><td>Mandatory</td><td>Customer additional_info that sent when initate the payment</td></tr><tr><td><code>wallet.issuer</code></td><td>string</td><td>Mandatory</td><td>Wallet issuer that receive on API Get List Token OVO Response</td></tr><tr><td><code>wallet.token_id</code></td><td>string</td><td>Mandatory</td><td>Wallet token ID that receive on API Get List Token OVO Response</td></tr><tr><td><code>wallet.masked_phone_number</code></td><td>string</td><td>Mandatory</td><td>Wallet Masked Phone Number that receive on API Get List Token OVO Response</td></tr><tr><td><code>wallet.status</code></td><td>string</td><td>Mandatory</td><td>Wallet Status</td></tr></tbody></table>

#### Payment

```json
{
    "service":{
        "id":"EMONEY"
    },
    "acquirer":{
        "id":"OVO"
    },
    "channel":{
        "id":"EMONEY_OVO"
    },
    "customer":{
        "id":"123123123",
        "name":"Joko",
        "email":"joko@gmail.com",
        "phone":"081287458232",
        "additional_info":"Test"
    },
    "order":{
        "invoice_number":"INV-20210124-0001",
        "amount":200000
    },
    "transaction":{
        "status":"SUCCESS",
        "date":"2021-06-11T02:17:59Z",
        "original_request_id":"4bb5232-3fe6-47a5-b0b0-d0fc3c6b5fdb"
    },
    "ovo_payment": {
        "ovo_id":"08227631610000",
        "cash_used": 19000,
        "point_used": 1000,
        "response_code":OVO123213,
        "response_message":Blablabla
    },
    "additional_info":{
        "message":"no additional info",
        "test": "test"
    }
}
```

#### OVO Open API - Payment Notification Explanation

| Parameter                         | Type   | Mandatory | Description                                                                  |
| --------------------------------- | ------ | --------- | ---------------------------------------------------------------------------- |
| `service.id`                      | string | Mandatory | The service that is used for the transaction                                 |
| acquirer.id                       | string | Mandatory | The acquirer that processed the transaction                                  |
| channel.id                        | string | Mandatory | The channel of the transaction                                               |
| customer.id                       | string | Mandatory | Merchant customer id                                                         |
| customer.name                     | string | Optional  | Customer name that sent when initiate the payment                            |
| customer.email                    | string | Optional  | Customer email that sent when initiate the payment                           |
| customer.phone                    | string | Optional  | Customer phone number that sent when initiate the payment                    |
| customer.additional\_info         | string | Optional  | Customer additional\_info that sent when initate the payment                 |
| order.invoice\_number             | string | Mandatory | Merchant transaction id unique per client id                                 |
| order.amount                      | string | Mandatory | Total amount in IDR                                                          |
| transaction.status                | string | Mandatory | <p>Status of transaction<br>Possible value :<code>SUCCESS, FAILED</code></p> |
| transaction.date                  | string | Mandatory | Transaction requested to Bank on UTC time in ISO8601 format                  |
| transaction.original\_request\_id | string | Mandatory | Request ID to DOKU API when generate payment / refund                        |
| transaction.message               | string | Mandatory | Transaction message                                                          |
| additional\_info.message          | string | Mandatory | Additional info message                                                      |
| additional\_info.test             | string | Mandatory | Additional info test                                                         |

#### Refund

```json
{
    "service":{
        "id":"EMONEY"
    },
    "acquirer":{
        "id":"OVO"
    },
    "channel":{
        "id":"EMONEY_OVO"
    },
    "customer":{
        "id":"123123123"
    },
    "order":{
        "invoice_number":"INV-20210124-0001"
    },
    "transaction":{
        "status":"REFUNDED",
        "date":"2021-06-11T02:17:59Z",
        "original_request_id":"4bb5232-3fe6-47a5-b0b0-d0fc3c6b5fdb"
    },
    "ovo_payment": {
        "ovo_id":"08227631610000"
    },
    "refund": {
        "id": "864271549283077864271549287589",
        "amount": 6000,
        "ovo_cash": 5000,
        "ovo_point": 1000,
        "reason": "Cancel Order",
        "response_code": OVO123213,
        "response_message": Blablabla
    },
    "additional_info":{
        "message":"no additional info",
        "test":"test"
    }
}
```

| Parameter     | Type | Mandatory | Description |
| ------------- | ---- | --------- | ----------- |
|               |      |           |             |
|               |      |           |             |
|               |      |           |             |
| {% endtab %}  |      |           |             |
| {% endtabs %} |      |           |             |

### Direct Debit

Here is the sample notification that DOKU will send to merchant's server.

<table data-full-width="false"><thead><tr><th>Type</th><th>Value</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr></tbody></table>

Here is the sample notification **request header** :&#x20;

```
Client-Id: MCH-0001-10791114622547
Request-Id: af0fa6bf-5295-42ff-9291-8dfd51976bf0
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
```

<table><thead><tr><th width="143">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Client ID you retrieved from DOKU Back Office</td></tr><tr><td><strong>Request-Id</strong></td><td>Unique random string (max 128 characters) that generated by DOKU to make sure no duplicate notification</td></tr><tr><td><strong>Request-Timestamp</strong></td><td>Time Stamp request on UTC time in ISO8601 format</td></tr><tr><td><strong>Signature</strong></td><td>Verify the Signature to ensure the Notification Authenticity coming from DOKU. Please refer to <a href="/pages/VogdJfoJtS2yXvClOsrc">this section</a></td></tr></tbody></table>

Here is the sample notification **request body** :&#x20;

```json
{
    "order": {
        "invoice_number": "INV-20210118-0001",
        "amount": 90000
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2021-02-17T16:33:26.362464",
        "original_request_id": "b6a465ea-bb65-48b2-a22b-3e8fb51cf22e"
    },
    "service": {
        "id": "DIRECT_DEBIT"
    },
    "acquirer": {
        "id": "BRI"
    },
    "channel": {
        "id": "DIRECT_DEBIT_BRI"
    },
    "card_payment": {
        "masked_card_number": "************8232",
        "response_code": "0000",
        "response_message": "SUCCESS",
        "payment_id": "510119432113"
    }
}
```

**Direct Debit Notification Explanation**

<table><thead><tr><th>Parameter</th><th width="123">Type</th><th width="139">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.invoice_number</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as the request that merchant sent on the payment initiation</td></tr><tr><td><code>order.amount</code></td><td><code>number</code></td><td>Mandatory</td><td>Same as the request that merchant sent on the payment initiation</td></tr><tr><td><code>transaction.status</code></td><td><code>string</code></td><td>Mandatory</td><td>The transaction status to be use to update the status on merchant side<br>Possible value: <code>SUCCESS, FAILED</code></td></tr><tr><td><code>transaction.date</code></td><td><code>string</code></td><td>Mandatory</td><td>The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)</td></tr><tr><td><code>transaction.original_request_id</code></td><td><code>string</code></td><td>Mandatory</td><td>The request ID that sent when initiate the payment</td></tr><tr><td><code>service.id</code></td><td><code>string</code></td><td>Mandatory</td><td>The service that is used for the transaction</td></tr><tr><td><code>acquirer.id</code></td><td><code>string</code></td><td>Mandatory</td><td>The acquirer that processed the transaction</td></tr><tr><td><code>channel.id</code></td><td><code>string</code></td><td>Mandatory</td><td>The channel of the transaction</td></tr><tr><td><code>card_payment.masked_card_number</code></td><td><code>string</code></td><td>Optional</td><td>The masked card number that charged for this transaction</td></tr><tr><td><code>card_payment.approval_code</code></td><td><code>string</code></td><td>Optional</td><td>Acquirer approval code for this transaction</td></tr><tr><td><code>card_payment.response_code</code></td><td><code>string</code></td><td>Optional</td><td>DOKU / Acquirer response code</td></tr><tr><td><code>card_payment.response_message</code></td><td><code>string</code></td><td>Optional</td><td>DOKU / Acquirer response code</td></tr></tbody></table>

### Paylater

Here is the sample notification that DOKU will send to merchant's server.

<table data-full-width="false"><thead><tr><th>Type</th><th>Value</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr></tbody></table>

Here is the sample notification **request header** :&#x20;

```
Client-Id: MCH-0001-10791114622547
Request-Id: 370c993c-e5ee-4dfc-9e47-0474b55c7b4b
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps
```

<table><thead><tr><th width="143">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Client ID you retrieved from DOKU Back Office</td></tr><tr><td><strong>Request-Id</strong></td><td>Unique random string (max 128 characters) that generated by DOKU to make sure no duplicate notification</td></tr><tr><td><strong>Request-Timestamp</strong></td><td>Time Stamp request on UTC time in ISO8601 format</td></tr><tr><td><strong>Signature</strong></td><td>Verify the Signature to ensure the Notification Authenticity coming from DOKU. Please refer to <a href="/pages/VogdJfoJtS2yXvClOsrc">this section</a></td></tr></tbody></table>

Here is the sample notification **request body** :&#x20;

```json
{
    "service": {
        "id": "PEER_TO_PEER"
    },
    "acquirer": {
        "id": "AKULAKU"
    },
    "channel": {
        "id": "PEER_TO_PEER_AKULAKU"
    },
    "order": {
        "invoice_number": "INV-20210707-0001",
        "amount": 90000
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2021-07-07T08:48:42Z",
        "original_request_id": "baec7d95-f30a-4b78-b711-6ebe0ccdf50b"
    },
    "peer_to_peer_info": {
               "virtual_account_number": "2900800000000003",
               "created_date": "20200313095850",
               "expired_date": "20200313155850",
               "status": "SUCCESS",
               "merchant_unique_reference": "60123",
               "identifier": [
                  {
                     "name": "AKULAKU_UNIQUE_REFERENCE",
                     "value": "BRN-0288-1654748429432TEST-ABC-768"    
                  },
                  {
                     "name": "ORDER_ID",
                     "value": "BRN-0288-1654748429432TEST-ABC-768"
                  }
               ]
            },
    "payment": {
        "merchant_unique_reference": "MUR-20210707-0001"
    }
}
```

Akulaku Notification Explanation

| Parameter                                                                | Type     | Mandatory | Description                                                                                                                   |
| ------------------------------------------------------------------------ | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `service.id`                                                             | `string` | Mandatory | The service that is used for the transaction                                                                                  |
| `acquirer.id`                                                            | `string` | Mandatory | The acquirer that processed the transaction                                                                                   |
| `channel.id`                                                             | `string` | Mandatory | The channel of the transaction                                                                                                |
| `order.invoice_number`                                                   | `string` | Mandatory | Same as the request that merchant sent on the payment initiation                                                              |
| `order.amount`                                                           | `number` | Mandatory | Same as the request that merchant sent on the payment initiation                                                              |
| `transaction.status`                                                     | `string` | Mandatory | <p>The transaction status to be use to update the status on merchant side<br>Possible value: <code>SUCCESS, FAILED</code></p> |
| `transaction.date`                                                       | `string` | Mandatory | The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)                                       |
| `transaction.original_request_id`                                        | `string` | Mandatory | The request ID that sent when initiate the payment                                                                            |
| <p><code>payment.</code><br><code>merchant\_unique\_reference</code></p> | `string` | Mandatory | The merchant unique reference that sent when initiate the payment                                                             |

### QRIS

Here is the sample notification that DOKU will send to the merchant's server.

| Type  | HTTP Method |
| ----- | ----------- |
| Value | Post        |

Here is the sample notification request header :

```
Client-Id: MCH-0001-10791114622547
Request-Id: 370c993c-e5ee-4dfc-9e47-0474b55c7b4b
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps
```

<table><thead><tr><th width="210.01171875">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>Client-Id</td><td>Client ID you retrieved from DOKU Back Office</td></tr><tr><td>Request-Id</td><td>Unique random string (max 128 characters) that generated by DOKU to make sure no duplicate notification</td></tr><tr><td>Request-Timestamp</td><td>Time Stamp request on UTC time in ISO8601 format</td></tr><tr><td>Signature</td><td>Verify the Signature to ensure the Notification Authenticity coming from DOKU. Please refer to this section</td></tr></tbody></table>

Here is the sample notification request body :

```json
{
  "service": {
    "id": "QRIS",
    "name": "QRIS"
  },
  "acquirer": {
    "id": "DOKU",
    "name": "DOKU"
  },
  "channel": {
    "id": "QRIS_DOKU",
    "name": "QRIS-DOKU"
  },
  "customer": {
    "doku_id": "1673637808",
    "name": "accountsnap_1747637808",
    "email": "accountsnap_1747637808@gmail.com",
    "phone": "6281747637808"
  },
  "order": {
    "invoice_number": "5ffa5675bb114404a4e426241cf05be0",
    "amount": 20000.00
  },
  "emoney_payment": {
    "account_id": "1673637808",
    "approval_code": "234604941"
  },
  "transaction": {
    "status": "SUCCESS",
    "date": "2025-06-20T04:26:26Z"
  },
  "additional_info": {
    "postalCode": "13120",
    "feeType": "1",
    "settlement": [
      {
        "bank_account_settlement_id": "SBA-0001-123123123",
        "value": 10.0,
        "type": "PERCENTAGE"
      },
      {
        "bank_account_settlement_id": "SBS-0002-321321321",
        "value": 90.0,
        "type": "PERCENTAGE"
      }
    ],
    "origin": {
      "product": "QRIS",
      "system": "snap-adapter",
      "apiFormat": "SNAP",
      "source": "DIRECT"
    }
  }
}

```

QRIS Notification Explanation:

| service.id                     | string | Mandatory | The service id that is used for the transaction                                                                                                                         |
| ------------------------------ | ------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| service.name                   | string | Mandatory | The service name that is used for the transaction                                                                                                                       |
| acquirer.id                    | string | Mandatory | The acquirer id that processed the transaction                                                                                                                          |
| acquirer.name                  | string | Mandatory | The acquirer name that processed the transaction                                                                                                                        |
| channel.id                     | string | Mandatory | The channel id of the transaction                                                                                                                                       |
| channel.name                   | string | Mandatory | The channel name of the transaction                                                                                                                                     |
| customer.doku\_id              | string | Mandatory | Customer / Merchant doku id                                                                                                                                             |
| customer.name                  | string | Mandatory | Customer / Merchant name                                                                                                                                                |
| customer.email                 | string | Mandatory | Customer / Merchant email                                                                                                                                               |
| customer.phone                 | string | Mandatory | Customer / Merchant phone                                                                                                                                               |
| order.invoice\_number          | string | Mandatory | Same as the request that merchant sent on the payment initiation                                                                                                        |
| order.amount                   | string | Mandatory | Total amount in IDR                                                                                                                                                     |
| emoney\_payment.account\_id    | string | Mandatory | Acquirer id for this transaction                                                                                                                                        |
| emoney\_payment.approval\_code | string | Mandatory | Acquirer approval code for this transaction                                                                                                                             |
| transaction.status             | string | Mandatory | <p>The transaction status to be use to update the status on merchant side</p><p>Possible value: SUCCESS since Convenience Store only notify when payment is success</p> |
| transaction.date               | string | Mandatory | The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)                                                                                 |
| additional\_info               | string | Mandatory | Same as the additional\_info from the request                                                                                                                           |
| origin.product                 | string | Mandatory | The product that processed the transaction                                                                                                                              |
| origin.system                  | string | Mandatory | The product that processed the transaction                                                                                                                              |
| origin.apiFormat               | string | Mandatory | The Api format that processed the transaction                                                                                                                           |
| origin.source                  | string | Mandatory | The source that processed the transaction                                                                                                                               |

<br>


# Best Practice

Handling HTTP Notification is crucial in order to make sure that your integration's business logic works as expected. Here are some best practices that you need to implement :

## Handling Notification Implementation <a href="#handling-notification-implementation" id="handling-notification-implementation"></a>

### **Acknowledge HTTP Notification immediately**

If your HTTP Notification endpoint performs complex logic, or makes network calls, it's possible that the endpoint would time out before DOKU sees its complete execution. Ideally, your HTTP Notification handler code (acknowledging receipt of an event by returning a 2xx status code) is separate of any other logic you do for that notification.

### **Verify HTTP Notification authenticity**

You must verify the HTTP Notification to make sure that it is coming from DOKU. To do that, you need to check the `Signature` on the Request Header that sent to you.

Before generating `Signature`, merchant need to prepare all the component required.

1. **Set Client-Id, Request-Id, Request-Timestamp.**

Use the Client-Id, Request-Id, Request-Timestamp that is placed on the Request Header.

2. **Set Request-Target**

The Request-Target is the path of merchant `Notification URL` or the `Inquiry URL`. For instance, if merchant set the `Notification URL`: `https://yourdomain.com/payments/notifications`. Therefore, the Request-Target value is `/payments/notifications`.

3. **Generate Digest**

`Digest` is the hashed of the request body. To generate the `Digest`:

Calculate SHA256 base64 hash from the JSON Body

4. **Generating Signature**

After all the `Signature` component has been set, merchant can now generate it:

* Arrange the signature components to one component and its value per line by adding  escape character. Don't add  at the end of the string. Sample of the raw format:

```
Client-Id:MCH-0001-10791114622547\nRequest-Id:cc682442-6c22-493e-8121-b9ef6b3fa728\nRequest-Timestamp:2020-08-11T08:45:42Z\nRequest-Target:/doku-virtual-account/v2/payment-code\nDigest:5WIYK2TJg6iiZ0d5v4IXSR0EkYEkYOezJIma3Ufli5s=
```

This is how merchant see :

```
Client-Id:MCH-0001-10791114622547
Request-Id:cc682442-6c22-493e-8121-b9ef6b3fa728
Request-Timestamp:2020-08-11T08:45:42Z
Request-Target:/doku-virtual-account/v2/payment-code
Digest:5WIYK2TJg6iiZ0d5v4IXSR0EkYEkYOezJIma3Ufli5s=
```

* Calculate HMAC-SHA256 base64 from all the components above using the [Secret Key from DOKU Back Office](/get-started-with-doku-api/retrieve-payment-credential)
* Put encoded value and prepend `HMACSHA256=` to the `Signature`. Sample:

```
Signature: HMACSHA256=OvIRJs/jH8BIcGsktr4d8nnYtxY6E0Uzdm9d1GVgv5s=
```

### **Update the transaction status based on the `transaction.status`**

All of the notifications that we send always have `transaction.status` parameter. The possible value is `SUCCESS` or `FAILED`. Update the transaction status on your side based on this value.

{% hint style="info" %}
**CHECKOUT IMPLEMENTATION**

Checkout User Experience is designed to increase your payment success rate, meaning that it allows your customers to change payment method if one is failed. Therefore, if you are integrating with Checkout, you must ignore the `transaction.status` `FAILED`.
{% endhint %}

### **Handle duplicate events**

HTTP Notification endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you've processed, and then not processing already-logged events.

### **Parse HTTP Notification in non-strict format**[**​**](https://dashboard.doku.com/docs/docs/http-notification/http-notification-best-practice#parse-http-notification-in-non-strict-format)

DOKU sends the notification body as JSON, please parse the JSON with a JSON parser. Always expect new fields will be added to the notification body, so parse it in a non strict format. This prevents the parser from throwing an exception for new fields. It should gracefully ignore the new fields. This allows us to extend our notification system for newer use cases without breaking old clients.


# Retry Notification

Your `Notification URL` must response with HTTP status `2xx` to confirm the transaction notification is received.&#x20;

If your URL doesn't respond with this status, we'll make 3 attempts to deliver the HTTP Notification. We'll stop retrying once we receive a response from your server or if there's still  no response.

<table><thead><tr><th width="75">No</th><th>Internal from previous attempts</th><th>Interval from original attempts</th></tr></thead><tbody><tr><td>1</td><td>30 minutes</td><td>30 minutes</td></tr><tr><td>2</td><td>5 hours 30 minutes</td><td>6 hours</td></tr><tr><td>3</td><td>11 hours 30 minutes</td><td>12 hours</td></tr></tbody></table>

### Manual Retry Notification

If you wish to do manual retry for the notification, follow the steps given below:

1. Login to DOKU Back Office
2. Go to Menu **Integration >  HTTP Notification**
3. Find the notification that you want to try, you could utilize the filter
4. Click the retry icon (plane) to resend the notification

<figure><img src="/files/MCGtYtUgqVB9hATJVgoI" alt=""><figcaption></figcaption></figure>

5. Notification successfully published!


# Override Notification URL

This is a feature that intended to override the configured `Notification URL` from API request level. When the override URL is defined on request level, then the notification will be send to the newly destined URL instead of the configured one.  To override, make sure you already configure the `Notification URL` on DOKU Back Office.

{% hint style="info" %}
**Override URL path must be the same as the configured `Notification URL` path**

For example, if the configured URL is `https://example.com/payments/notifications` , then the override URL must be `https://anotherexample.com/payments/notifications` .  As you can see that both URL contains `payments/notifications` which is the same path.
{% endhint %}

{% hint style="warning" %}
**You can't use the same domain with different path**

You can change the domain or sub-domain, but it is mandatory to make sure the override URL and the configured `Notification URL` have the same path, otherwise this features won't work.
{% endhint %}

### How To Use

When requesting payment, you have to add this parameter under the additional info on the request body.

```json
{
...
    "additional_info": {
        "override_notification_url": "https://anotherexample.com/payments/notifications"
    }
...
}
```

The `override_notification_url` parameter is used for overriding URL, you can simply fill the value with your override URL. After this, all payment notification in this specific channel will be sent to the new destined URL.&#x20;


# Signature Component


# Non-SNAP


# Signature Component from Request Header

To generate a Signature in request header, merchant need to prepare these components:

```markup
Client-Id:value
Request-Id:value
Request-Timestamp:value
Request-Target:value
Digest:value
```

#### **Component Explanation**

<table><thead><tr><th width="214">Name</th><th></th></tr></thead><tbody><tr><td>C<code>lient-id</code></td><td>Retrieved from the Request Header</td></tr><tr><td>R<code>equest-id</code></td><td>Retrieved from the Request Header</td></tr><tr><td><code>Request-Timestamp</code></td><td>Retrieved from the Request Header</td></tr><tr><td><code>Request-Target</code></td><td>The path of the endpoint that will be hitted e.g: <code>/doku-virtual-account/v2/payment-code</code>. <strong>NOTE:</strong> For the <code>HTTP Notification</code> from DOKU to merchant server, this will be the path of merchant <code>Notification URL</code>. As for the <code>Inquiry Request</code>, this will be the path of merchant <code>Inquiry URL</code></td></tr><tr><td><code>Digest</code></td><td>Encoded (base64) value of hashed (SHA-256) JSON body. This component only applied for <code>POST</code> Method.</td></tr></tbody></table>

### **Preparation**

Before generating `Signature`, merchant need to prepare all the component required.

**Set Client-Id, Request-Id, Request-Timestamp.**[**​**](https://dashboard.doku.com/docs/docs/technical-references/generate-signature#set-client-id-request-id-request-timestamp)

Use the Client-Id, Request-Id, Request-Timestamp that is placed on the Request Header.

**Set Request-Target**[**​**](https://dashboard.doku.com/docs/docs/technical-references/generate-signature#set-request-target)

The Request-Target is depending on who is sending the request:

1. **When merchant hits DOKU endpoints:** The Request-Target is the path of the DOKU API that merchant hits.\
   For instance, if merchant wants to hit DOKU VA API: `https://api.doku.com/doku-virtual-account/v2/payment-code`. Therefore, the Request-Target value is `/doku-virtual-account/v2/payment-code`.
2. **When DOKU hits merchant endpoints (HTTP Notification / Inquiry Request):** The Request-Target is the path of merchant `Notification URL` or the `Inquiry URL`.\
   For instance, if merchant set the `Notification URL`: `https://yourdomain.com/payments/notifications`. Therefore, the Request-Target value is `/payments/notifications`.

#### **Generate Digest**

`Digest` is the hashed of the request body. To generate the `Digest`:

1. Calculate SHA256 base64 hash from the JSON Body

### Generating Signature[​](https://dashboard.doku.com/docs/docs/technical-references/generate-signature#generating-signature)

After all the `Signature` component has been set, merchant can now generate it:

1. Arrange the signature components to one component and its value per line by adding  escape character. Don't add  at the end of the string. Sample of the raw format:

```html
Client-Id:MCH-0001-10791114622547\nRequest-Id:cc682442-6c22-493e-8121-b9ef6b3fa728\nRequest-Timestamp:2020-08-11T08:45:42Z\nRequest-Target:/doku-virtual-account/v2/payment-code\nDigest:5WIYK2TJg6iiZ0d5v4IXSR0EkYEkYOezJIma3Ufli5s=
```

This is how merchant see it:

```html
Client-Id:MCH-0001-10791114622547
Request-Id:cc682442-6c22-493e-8121-b9ef6b3fa728
Request-Timestamp:2020-08-11T08:45:42Z
Request-Target:/doku-virtual-account/v2/payment-code
Digest:5WIYK2TJg6iiZ0d5v4IXSR0EkYEkYOezJIma3Ufli5s=
```

2. Calculate HMAC-SHA256 base64 from all the components above using the [Secret Key from DOKU Back Office](https://dashboard.doku.com/docs/docs/getting-started/retrieve-credential)
3. Put encoded value and prepend `HMACSHA256=` to the `Signature`. Sample:

```html
Signature: HMACSHA256=OvIRJs/jH8BIcGsktr4d8nnYtxY6E0Uzdm9d1GVgv5s=
```


# Signature Componen from Response Header

To validate a signature in response header, merchant need to see and check these components.

```
Client-Id:value
Request-Id:value
Response-Timestamp:value
Request-Target:value
Digest:value
```

#### Component Explanation

| Name                 | Description                                                                                          |
| -------------------- | ---------------------------------------------------------------------------------------------------- |
| `Client-Id`          | Retrieved from the Request Header                                                                    |
| `Request-Id`         | Retrieved from the Request Header                                                                    |
| `Response-Timestamp` | Retrieved from the Response Header                                                                   |
| `Request-Target`     | The path of the endpoint that will be hitted e.g: `/doku-virtual-account/v2/payment-code`.           |
| `Digest`             | Encoded (base64) value of hashed (SHA-256) JSON body. This component only applied for `POST` Method. |

### Preparation

Before validating `Signature`, merchant need to check all the component required.

**Set Client-Id, Request-Id, Response-Timestamp.**[**​**](https://dashboard.doku.com/docs/docs/technical-references/generate-signature#set-client-id-request-id-response-timestamp)

Use the Client-Id, Request-Id, Response-Timestamp that is placed on the Response Header.

**Set Request-Target**[**​**](https://dashboard.doku.com/docs/docs/technical-references/generate-signature#set-request-target-1)

The Request-Target is depending on who is sending the request:

1. **When merchant hits DOKU endpoints:** The Request-Target is the path of the DOKU API that merchant hits.

### Validating Signature <a href="#validating-signature" id="validating-signature"></a>

After merchant send request to DOKU and generate signature in request header, DOKU will send response and generate signature in response header. Then merchant can verify this response is coming from DOKU by Signature.

1. Arrange the signature components to one component and its value per line by adding  escape character. Don't add  at the end of the string. Sample of the raw format :&#x20;

```
Client-Id:MCH-0001-10791114622547\nRequest-Id:cc682442-6c22-493e-8121-b9ef6b3fa728\Response-Timestamp:2020-08-11T08:45:42Z\nRequest-Target:/doku-virtual-account/v2/payment-code\nDigest:5WIYK2TJg6iiZ0d5v4IXSR0EkYEkYOezJIma3Ufli5s=
```

This is how merchant will see :&#x20;

```
Client-Id:MCH-0001-10791114622547
Request-Id:cc682442-6c22-493e-8121-b9ef6b3fa728
Response-Timestamp:2020-08-11T08:45:42Z
Request-Target:/doku-virtual-account/v2/payment-code
Digest:5WIYK2TJg6iiZ0d5v4IXSR0EkYEkYOezJIma3Ufli5s=
```

2. Calculate HMAC-SHA256 base64 from all the components above using the [Secret Key from DOKU Back Office](https://dashboard.doku.com/docs/docs/getting-started/retrieve-credential)
3. Put encoded value and prepend `HMACSHA256=` to the `Signature`. Sample :

```
Signature: HMACSHA256=OvIRJs/jH8BIcGsktr4d8nnYtxY6E0Uzdm9d1GVgv5s=
```

{% hint style="info" %}
INFO!

To make sure every response API from DOKU, just verify in Signature that you get from Response Header!
{% endhint %}


# Signature from API Get Method

For API that uses `GET` method such as, Check Status API, merchant don't need to generate a `Digest`.

1. Arrange the signature components to one component and its value per line by adding  escape character. Don't add  at the end of the string. Sample of the raw format:

```html
Client-Id:MCH-0001-10791114622547\nRequest-Id:d895fb53-479c-4f77-a76a-ab81b40d77cb\nRequest-Timestamp:2020-08-11T08:45:42Z\nRequest-Target:/orders/v1/status/INV-123123-12313
```

This is how merchant see it :&#x20;

```html
Client-Id:MCH-0001-10791114622547
Request-Id:d895fb53-479c-4f77-a76a-ab81b40d77cb
Request-Timestamp:2020-08-11T08:45:42Z
Request-Target:/orders/v1/status/INV-123123-12313
```

2. Calculate HMAC-SHA256 base64 from all the components above using the [Secret Key from DOKU Back Office](https://dashboard.doku.com/docs/docs/getting-started/retrieve-credential)
3. Put encoded value and prepend `HMACSHA256=` to the `Signature`.  Sample:

```html
Signature: HMACSHA256=B1cKBzk/aB1AXADCZkq135bnktxY1o02zmmdd2cVgf12=
```


# Sample Code

Here is the sample code to generate the `Signature`:

{% hint style="info" %}
**SAMPLE ONLY!**

This is just a sample code to demonstrate how to generate the Signature on different programming language. Kindly adjust the code to suited your project's structure.
{% endhint %}

{% tabs %}
{% tab title="Java" %}

<pre class="language-java"><code class="lang-java"><strong>import javax.crypto.Mac;
</strong>import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
 
public class Signature {
 
    public static final String CLIENT_ID = "Client-Id";
    public static final String REQUEST_ID = "Request-Id";
    public static final String REQUEST_TIMESTAMP = "Request-Timestamp";
    public static final String REQUEST_TARGET = "Request-Target";
    public static final String DIGEST = "Digest";
    public static final String COLON_SYMBOL = ":";
    public static final String NEW_LINE = "\n";
    
    // Generate Digest
    public static String generateDigest(String requestBody) throws NoSuchAlgorithmException {
        MessageDigest md = MessageDigest.getInstance("SHA-256");
        md.update(requestBody.getBytes(StandardCharsets.UTF_8));
        byte[] digest = md.digest();
        return Base64.getEncoder().encodeToString(digest);
    }
    
    private static String generateSignature(String clientId, String requestId, String requestTimestamp, String requestTarget, String digest, String secret) throws InvalidKeyException, NoSuchAlgorithmException {
        // Prepare Signature Component
        System.out.println("----- Component Signature -----");
        StringBuilder component = new StringBuilder();
        component.append(CLIENT_ID).append(COLON_SYMBOL).append(clientId);
        component.append(NEW_LINE);
        component.append(REQUEST_ID).append(COLON_SYMBOL).append(requestId);
        component.append(NEW_LINE);
        component.append(REQUEST_TIMESTAMP).append(COLON_SYMBOL).append(requestTimestamp);
        component.append(NEW_LINE);
        component.append(REQUEST_TARGET).append(COLON_SYMBOL).append(requestTarget);
        // If body not send when access API with HTTP method GET/DELETE
        if(digest != null &#x26;&#x26; !digest.isEmpty()) {
            component.append(NEW_LINE);
            component.append(DIGEST).append(COLON_SYMBOL).append(digest);
        }

        System.out.println(component.toString());
        System.out.println();
 
        // Calculate HMAC-SHA256 base64 from all the components above
        byte[] decodedKey = secret.getBytes();
        SecretKey originalKey = new SecretKeySpec(decodedKey, 0, decodedKey.length, "HmacSHA256");
        Mac hmacSha256 = Mac.getInstance("HmacSHA256");
        hmacSha256.init(originalKey);
        hmacSha256.update(component.toString().getBytes());
        byte[] HmacSha256DigestBytes = hmacSha256.doFinal();
        String signature = Base64.getEncoder().encodeToString(HmacSha256DigestBytes);
        // Prepend encoded result with algorithm info HMACSHA256=
        return "HMACSHA256="+signature;
    }
    
    // Sample of Usage
    public static void main(String[] args) throws NoSuchAlgorithmException, InvalidKeyException {
         String jsonBody = new JSONObject()
                          .put("order", new JSONObject()
                            .put("invoice_number", "INV-20210124-0001")
                            .put("amount", 15000)
                          )
                          .put("virtual_account_info", new JSONObject()
                            .put("expired_time", 60)
                            .put("amount", 15000)
                          )
                          .toString();
 
        // Generate Digest from JSON Body, For HTTP Method GET/DELETE don't need generate Digest
        System.out.println("----- Digest -----");
        String digest = generateDigest(jsonBody);
        System.out.println(digest);
        System.out.println();
 
        // Generate Signature
        String headerSignature = generateSignature(
                "yourClientId",
                "yourRequestId",
                "2020-10-21T03:38:28Z",
                "/request-target/goes-here", // For merchant request to DOKU, use DOKU path here. For HTTP Notification, use merchant path here
                digest, // Set empty string for this argumentes if HTTP Method is GET/DELETE
                "secret-key-from-DOKU-back-office");
 
        System.out.println("----- Header Signature -----");
        System.out.println(headerSignature);
    }
}
</code></pre>

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$clientId = "yourClientId";
$requestId = "yourRequestId";
$requestDate = "2020-10-21T03:38:28Z";
$targetPath = "/request-target/goes-here"; // For merchant request to Jokul, use Jokul path here. For HTTP Notification, use merchant path here
$secretKey = "secret-key-from-jokul-back-office";
$requestBody = array (
    'order' => array (
        'amount' => 15000,
        'invoice_number' => 'INV-20210124-0001',
    ),
    'virtual_account_info' => array (
        'expired_time' => 60,
        'reusable_status' => false,
        'info1' => 'Merchant Demo Store',
    ),
    'customer' => array (
        'name' => 'Taufik Ismail',
        'email' => 'taufik@example.com',
    ),
);

// Generate Digest
$digestValue = base64_encode(hash('sha256', json_encode($requestBody), true));
echo "Digest: " . $digestValue;
echo "\r\n\n";

// Prepare Signature Component
$componentSignature = "Client-Id:" . $clientId . "\n" . 
                      "Request-Id:" . $requestId . "\n" .
                      "Request-Timestamp:" . $requestDate . "\n" . 
                      "Request-Target:" . $targetPath . "\n" .
                      "Digest:" . $digestValue;
echo "Component Signature: \n" . $componentSignature;
echo "\r\n\n";
 
// Calculate HMAC-SHA256 base64 from all the components above
$signature = base64_encode(hash_hmac('sha256', $componentSignature, $secretKey, true));
echo "Signature: " . $signature;
echo "\r\n\n";

// Sample of Usage
$headerSignature =  "Client-Id:" . $clientId ."\n". 
                    "Request-Id:" . $requestId . "\n".
                    "Request-Timestamp:" . $requestDate ."\n".
                    // Prepend encoded result with algorithm info HMACSHA256=
                    "Signature:" . "HMACSHA256=" . $signature;
echo "your header request look like: \n".$headerSignature;
echo "\r\n\n";

```

{% endtab %}

{% tab title="Python" %}

```python
import hashlib
import hmac
import base64

# Generate Digest
def generateDigest(jsonBody):  
    return base64.b64encode(hashlib.sha256(jsonBody.encode('utf-8')).digest()).decode("utf-8")

def generateSignature(clientId, requestId, requestTimestamp, requestTarget, digest, secret):
    # Prepare Signature Component
    print("----- Signature Component -----")
    componentSignature = "Client-Id:" + clientId
    componentSignature += "\n"
    componentSignature += "Request-Id:" + requestId
    componentSignature += "\n"
    componentSignature += "Request-Timestamp:" + requestTimestamp
    componentSignature += "\n"
    componentSignature += "Request-Target:" + requestTarget
    # If body not send when access API with HTTP method GET/DELETE
    if digest:
        componentSignature += "\n"
        componentSignature += "Digest:" + digest
     
    print(componentSignature)
    message = bytes(componentSignature, 'utf-8')
    secret = bytes(secret, 'utf-8')
 
    # Calculate HMAC-SHA256 base64 from all the components above
    signature = base64.b64encode(hmac.new(secret, message, digestmod=hashlib.sha256).digest()).decode("utf-8")

    # Prepend encoded result with algorithm info HMACSHA256=
    return "HMACSHA256="+signature 

# Sample of usage

# Generate Digest from JSON Body, For HTTP Method GET/DELETE don't need generate Digest
print("----- Digest -----")
jsonBody = '{\"order\":{\"invoice_number\":\"INV-20210124-0001\",\"amount\":150000},\"virtual_account_info\":{\"expired_time\":60,\"reusable_status\":false,\"info1\":\"Merchant Demo Store\"},\"customer\":{\"name\":\"Taufik Ismail\",\"email\":\"taufik@example.com\"}}'
digest = generateDigest(jsonBody)
print(digest)
print("")

# Generate Signature
headerSignature = generateSignature(
        "yourClientId",
        "yourRequestId",
        "2020-10-21T03:38:28Z",
        "/request-target/goes-here", # For merchant request to Jokul, use Jokul path here. For HTTP Notification, use merchant path here
        digest, # Set empty string for this argumentes if HTTP Method is GET/DELETE
        "secret-key-from-jokul-back-office")
print("----- Header Signature -----")
print(headerSignature)

```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const crypto = require('crypto');
  
// Generate Digest
function generateDigest(jsonBody) {
    let jsonStringHash256 = crypto.createHash('sha256').update(jsonBody,"utf-8").digest();
    
    let bufferFromJsonStringHash256 = Buffer.from(jsonStringHash256);
    return bufferFromJsonStringHash256.toString('base64'); 
}
 
function generateSignature(clientId, requestId, requestTimestamp, requestTarget, digest, secret) {
    // Prepare Signature Component
    console.log("----- Component Signature -----")
    let componentSignature = "Client-Id:" + clientId;
    componentSignature += "\n";
    componentSignature += "Request-Id:" + requestId;
    componentSignature += "\n";
    componentSignature += "Request-Timestamp:" + requestTimestamp;
    componentSignature += "\n";
    componentSignature += "Request-Target:" + requestTarget;
    // If body not send when access API with HTTP method GET/DELETE
    if (digest) {
        componentSignature += "\n";
        componentSignature += "Digest:" + digest;
    }
 
    console.log(componentSignature.toString());
    console.log();

    // Calculate HMAC-SHA256 base64 from all the components above
    let hmac256Value = crypto.createHmac('sha256', secret)
                   .update(componentSignature.toString())
                   .digest();  
      
    let bufferFromHmac256Value = Buffer.from(hmac256Value);
    let signature = bufferFromHmac256Value.toString('base64');
    // Prepend encoded result with algorithm info HMACSHA256=
    return "HMACSHA256="+signature 
}
 
// Sample of Usage

// Generate Digest from JSON Body, For HTTP Method GET/DELETE don't need generate Digest
console.log("----- Digest -----");
let jsonBody = '{\"order\":{\"invoice_number\":\"INV-20210124-0001\",\"amount\":150000},\"virtual_account_info\":{\"expired_time\":60,\"reusable_status\":false,\"info1\":\"Merchant Demo Store\"},\"customer\":{\"name\":\"Taufik Ismail\",\"email\":\"taufik@example.com\"}}';
let digest = generateDigest(jsonBody);
console.log(digest);
console.log();
  
// Generate Header Signature
let headerSignature = generateSignature(
        "yourClientId",
        "yourRequestId",
        "2020-10-21T03:38:28Z",
        "/request-target/goes-here", // For merchant request to Jokul, use Jokul path here. For HTTP Notification, use merchant path here
        digest, // Set empty string for this argumentes if HTTP Method is GET/DELETE
        "secret-key-from-jokul-back-office")
console.log("----- Header Signature -----")
console.log(headerSignature)

```

{% endtab %}

{% tab title="Ruby" %}

<pre class="language-ruby"><code class="lang-ruby"><strong>require 'openssl'
</strong>require 'base64'
require 'digest'
 
# Generate Digest
def generateDigest(jsonBody)
    return Base64.encode64(Digest::SHA256.digest(jsonBody)).strip()
end
 
def generateSignature(clientId, requestId, requestTimestamp, requestTarget, digest, secret)
    # Prepare Signature Component
    puts "----- Component Signature -----"
    componentSignature = ("Client-Id:" + clientId")
    componentSignature.concat("\n")
    componentSignature.concat("Request-Id:" + requestId)
    componentSignature.concat("\n")
    componentSignature.concat("Request-Timestamp:" + requestTimestamp)
    componentSignature.concat("\n")
    componentSignature.concat("Request-Target:" + requestTarget)
    # If body not send when access API with HTTP method GET/DELETE
    unless digest.to_s.strip.empty?
        componentSignature.concat("\n")
        componentSignature.concat("Digest:" + digest)
    end
    puts componentSignature
    puts "\n"  

    # Calculate HMAC-SHA256 base64 from all the components above
    hash = OpenSSL::HMAC.digest("sha256", secret, componentSignature)
    signature = Base64.encode64(hash).strip()

    # Prepend encoded result with algorithm info HMACSHA256=
    return "HMACSHA256="+signature 
end
 
# Sample of Usage

# Generate Digest from JSON Body, For HTTP Method GET/DELETE don't need generate Digest
puts "----- Digest -----"
jsonBody = '{\"order\":{\"invoice_number\":\"INV-20210124-0001\",\"amount\":150000},\"virtual_account_info\":{\"expired_time\":60,\"reusable_status\":false,\"info1\":\"Merchant Demo Store\"},\"customer\":{\"name\":\"Taufik Ismail\",\"email\":\"taufik@example.com\"}}'
digest = generateDigest(jsonBody)
puts digest
puts "\n"
 
# Generate Header Signature
headerSignature = generateSignature(
        "yourClientId",
        "yourRequestId",
        "2020-10-21T03:38:28Z",
        "/request-target/goes-here", # For merchant request to Jokul, use Jokul path here. For HTTP Notification, use merchant path here
        digest, # Set empty string for this argumentes if HTTP Method is GET/DELETE
        "secret-key-from-jokul-back-office")
puts "----- Header Signature -----"
puts headerSignature

</code></pre>

{% endtab %}

{% tab title="GO" %}

```go
package main
 
import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
    "fmt"
    "strings"
)
 
const CLIENT_ID = "Client-Id"
const REQUEST_ID = "Request-Id"
const REQUEST_TIMESTAMP = "Request-Timestamp"
const REQUEST_TARGET = "Request-Target"
const DIGEST = "Digest"
const SYMBOL_COLON = ":"
 
// Generate Digest
func generateDigest(jsonBody string) string {
    converted := []byte(jsonBody)
    hasher := sha256.New()
    hasher.Write(converted)
    return (base64.StdEncoding.EncodeToString(hasher.Sum(nil)))
     
}

func generateSignature(clientId string, requestId string, requestTimestamp string, requestTarget string, digest string, secret string) string {
    // Prepare Signature Component
    fmt.Println("----- Component Signature -----")
    var componentSignature strings.Builder
    componentSignature.WriteString(CLIENT_ID + SYMBOL_COLON + clientId)
    componentSignature.WriteString("\n")
    componentSignature.WriteString(REQUEST_ID + SYMBOL_COLON + requestId)
    componentSignature.WriteString("\n")
    componentSignature.WriteString(REQUEST_TIMESTAMP + SYMBOL_COLON + requestTimestamp)
    componentSignature.WriteString("\n")
    componentSignature.WriteString(REQUEST_TARGET + SYMBOL_COLON + requestTarget) 
    componentSignature.WriteString("\n")
    componentSignature.WriteString(DIGEST + SYMBOL_COLON +digest) 
    // If body not send when access API with HTTP method GET/DELETE
    if len(digest) > 0  {
        componentSignature.WriteString("\n")
        componentSignature.WriteString(DIGEST + SYMBOL_COLON +digest)
    }
 
    fmt.Println(componentSignature.String())
    fmt.Println("")
 
    // Calculate HMAC-SHA256 base64 from all the components above
    key := []byte(secret)
    h := hmac.New(sha256.New, key)
    h.Write([]byte(componentSignature.String()))
    signature := base64.StdEncoding.EncodeToString(h.Sum(nil))
    // Prepend encoded result with algorithm info HMACSHA256=
    return "HMACSHA256="+signature
}

// Sample of Usage
func main() {
  
    // Genreate Digest from JSON Body
    var jsonBody = '{\"order\":{\"invoice_number\":\"INV-20210124-0001\",\"amount\":150000},\"virtual_account_info\":{\"expired_time\":60,\"reusable_status\":false,\"info1\":\"Merchant Demo Store\"},\"customer\":{\"name\":\"Taufik Ismail\",\"email\":\"taufik@example.com\"}}'
    digest := generateDigest(jsonBody);
    fmt.Println("----- Digest -----")
    fmt.Println(digest)
    fmt.Println("")
    
    // Generate Signature
    headerSignature := generateSignature(
        "yourClientId",
        "yourRequestId",
        "2020-10-21T03:38:28Z",
        "/request-target/goes-here", // For merchant request to DOKU, use DOKU path here. For HTTP Notification, use merchant path here
        digest, // Set empty string for this argumentes if HTTP Method is GET/DELETE
        "secret-key-from-DOKU-back-office")
 
    fmt.Println("----- Header Signature -----")    
    fmt.Println(headerSignature)
}

```

{% endtab %}
{% endtabs %}


# SNAP

### Introduction

Before you hit API on DOKU side, you need to understand how to generate a `X-Signature`. &#x20;

`X-Signature` is a security parameter that must be generated on the merchant's backend to verify the authenticity of the request.

Here is the case the `X-Signature` is used:

1. When merchant hits DOKU endpoints
   1. Merchant generate `X-Signature` in Request Header : Merchant must generate the x-signature in request header and DOKU will verify the authenticity.
   2. For Register the virtual Account you have to use Symmetric Signature. [Learn how to generate Symmetric Signature](/get-started-with-doku-api/signature-component/snap/symmetric-signature).
2. When DOKU hits merchant endpoints (HTTP Notification / Inquiry Request).\
   Merchant must also verify the `X-Signature` that DOKU sends on the request header when DOKU Notification hits merchant `Merchant domain URL`, to verify the notification request is coming from DOKU.  [Learn how to generate Symmetric Signature](/get-started-with-doku-api/signature-component/snap/symmetric-signature).

### **Signature Type**

1. **Symmetric Signature**

{% hint style="info" %}
When to use ?&#x20;

For  transaction request such as Create VA, Account Binding, OTP Verification, Check Balance Inquiry, Payment, Refund, Account Unbinding,  and Transfer Bank
{% endhint %}

2. **Asymmetric Signature**

{% hint style="info" %}
When to use ?&#x20;

For Get Token B2B and Get Token B2B2C
{% endhint %}

***


# Symmetric Signature

## Symmetric Signature

### **Preparation**

Before generating `Signature`, merchant need to prepare all the component required.

**Component Explanation**

| Name           | Description                                                                                                                                                                                                                                                                                                                                                                        |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientSecret` | <p>Retrieved from the DOKU Dashboard. <br>Find this through Integration > API Keys > Secret Key <img src="/files/8CbDcHmhvuqLFQmrvhhR" alt=""></p>                                                                                                                                                                                                                                 |
| `HTTPMethod`   | The HTTP method that client use to hit the API                                                                                                                                                                                                                                                                                                                                     |
|                |                                                                                                                                                                                                                                                                                                                                                                                    |
| `endpointURL`  | <p>The path of the endpoint that will be hitted e.g: <code>/bi-snap-va/v1/transfer-va/create-va</code><br><br><strong>NOTE:</strong> For the <code>HTTP Notification</code> from DOKU to merchant server, this will be the path of merchant <code>Notification URL</code>. As for the <code>Inquiry Request</code>, this will be the path of merchant <code>Inquiry URL</code></p> |
| `AccessToken`  | Result of get token B2B ( without Bearer )                                                                                                                                                                                                                                                                                                                                         |
| `Timestamp`    | Same with `X-TIMESTAMP`                                                                                                                                                                                                                                                                                                                                                            |
| `stringToSign` | `HTTPMethod +”:“+ EndpointUrl +":"+ AccessToken +":“+ Lowercase(HexEncode(SHA256(minify(RequestBody))))+ ":“ + TimeStamp`                                                                                                                                                                                                                                                          |

**How to generate stringToSign Component**

1. Minify request Body&#x20;

<table><thead><tr><th>Before</th><th>After</th></tr></thead><tbody><tr><td><p></p><pre class="language-json"><code class="lang-json">{
   "partnerServiceId":"  088899",
   "customerNo":"12345678901234567890",
   "virtualAccountNo":"  08889912345678901234567890",
   "virtualAccountName":"Jokul Doe",
   "virtualAccountEmail":"jokul@email.com",
   "virtualAccountPhone":"6281828384858",
   "trxId":"abcdefgh1234",
   "totalAmount":{
      "value":"12345678.00",
      "currency":"IDR"
   }
}
</code></pre></td><td><p></p><pre class="language-json"><code class="lang-json">{"partnerServiceId":"  088899","customerNo":"12345678901234567890","virtualAccountNo":"  08889912345678901234567890","virtualAccountName":"Jokul Doe","virtualAccountEmail":"jokul@email.com","virtualAccountPhone":"6281828384858","trxId":"abcdefgh1234","totalAmount":{"value":"12345678.00","currency":"IDR"}}
</code></pre></td></tr></tbody></table>

2. Calculate the result of {minify-request-body}  using SHA-256

The result will be like this :&#x20;

```json
3274fab8dac896837b106a16da2a974e7e65142dcecb4b768ef0294102838977
```

3. Hexencode the result of {SHA-256(minify-request-body)}

The result will be like this :&#x20;

3274fab8dac896837b106a16da2a974e7e65142dcecb4b768ef0294102838977

4. Set the result of hexencode{SHA-256(minify-request-body)} to Lowercase [**​**](https://dashboard.doku.com/docs/docs/technical-references/generate-signature#set-client-id-request-id-request-timestamp)

#### Generating StringtoSign

This is the formula for generating the string to Sign :&#x20;

`HTTPMethod +”:“+ EndpointUrl +":"+ AccessToken +":“+ Lowercase(HexEncode(SHA256(minify(RequestBody))))+ ":“ + TimeStamp`

This is the sample of stringToSign = `__TEC2O1iVBszTBTkrZhCujPRwY1TUiMTVpx67lMaH3-COIKKIKvAFvZMvbKjH6fJhVKFFBJgVNtD-k4p_k4NQwQtHjy_gldtUNWJD9kRoLCloo32r6h2RAwi1JiwaBqPWsf7v9_ELfVA23vH8Ojn0jFzfNESeffOkJ8LjlH5zawuChHNZSq9eg6o0w_jrrdlLnhMKJRYl4x09da8GLR4_dKnR8pZiUB58GCDydPYEyt5CIlyYwBMF8VCUx4OPg-gFNh9nc0gGPLNLr7pjFXl-o16wDtRRFakMT_yc3fSo1oEZnulBGzFQOIQLP1k4dD2vDg:170acce306af96d970c7af8698a815939ee5ba5f0b1db4d6ce91fc625b86021e:2024-03-26T16:01:41+07:00`

{% hint style="info" %}
What is `endpointURL` ?&#x20;

`endpointURL` means Request Target.&#x20;

The Request-Target is depending on who is sending the request:

1. **When merchant hits DOKU endpoints:** The Request-Target is the path of the DOKU API that merchant hits.\
   For instance, if merchant wants to hit DOKU VA API: `https://api.doku.com/`bi-snap-va/v1/transfer-va/create-va. Therefore, the Request-Target value is  /bi-snap-va/v1/transfer-va/create-va
2. **When DOKU hits merchant endpoints (HTTP Notification / Inquiry Request):** The Request-Target is the path of merchant `Notification URL` or the `Inquiry URL`.\
   For instance, if merchant set the `Notification URL`: `https://yourdomain.com/payments/notifications`. Therefore, the Request-Target value is `/payments/notifications`.
   {% endhint %}

### Generate Signature :&#x20;

After all the `stringToSign` component has been set,  merchant can now generate the signature :&#x20;

1. Calculate the result of `(clientSecret , stringToSign)` using `HMAC_512`&#x20;

   Ex : `qd2m9ot+cfq48qJ68+8IYdfkNDMA2hhecM2XegsnZ1Z5Fur9zii8BVm6cI7g1gyhL5/+OFZqAO8Kp0XPMdipfg==`
2. Put the value to each API in X-Signature component in Request Header


# Asymmetric Signature

{% hint style="warning" %}
Please Note&#x20;

stringToSign component for Get Token and Transactional will be different!

1. For Get Token = `stringToSign` = `client_ID + “|” + X- TIMESTAMP`
2. For Transactional = `stringToSign` = `HTTPMethod +":"+ EndpointUrl +":"+ Lowercase(HexEncode(SHA256(minify(RequestBody)))) + ":" + TimeStamp`
   {% endhint %}

### **Preparation**

Before generating `Signature`, merchant need to prepare all the component required.

| Name           | Description                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `privateKey`   | <p>Merchant privateKey <br>How to generate : </p><ol><li>generate private key RSA : <em>openssl genrsa -out private.key 2048</em></li><li>set passphrase your private key RSA : <em>openssl pkcs8 -topk8 -inform PEM -outform PEM -in private.key -out pkcs8.key -v1 PBE-SHA1-3DES</em></li><li>generate public key RSA : <em>openssl rsa -in private.key -outform PEM -pubout -out public.pem</em></li></ol> |
| `HTTPMethod`   | The HTTP method that client use to hit the API                                                                                                                                                                                                                                                                                                                                                                |
| `endpointURL`  | <p>The path of the endpoint that will be hitted e.g:  <code>/bi-snap-va/v1/transfer-va/create-va</code><br><br><strong>NOTE:</strong> For the <code>HTTP Notification</code> from DOKU to merchant server, this will be the path of merchant <code>Notification URL</code>. As for the <code>Inquiry Request</code>, this will be the path of merchant <code>Inquiry URL</code></p>                           |
| `Timestamp`    | Same with `X-TIMESTAMP`                                                                                                                                                                                                                                                                                                                                                                                       |
| `stringToSign` | `HTTPMethod +":"+ EndpointUrl +":"+ Lowercase(HexEncode(SHA256(minify(RequestBody)))) + ":" + TimeStamp`                                                                                                                                                                                                                                                                                                      |

**Set stringToSign Component**

1. Minify request Body&#x20;

<table><thead><tr><th>Before</th><th>After</th></tr></thead><tbody><tr><td><p></p><pre class="language-json"><code class="lang-json">{
   "partnerServiceId":"  088899",
   "customerNo":"12345678901234567890",
   "virtualAccountNo":"  08889912345678901234567890",
   "virtualAccountName":"Jokul Doe",
   "virtualAccountEmail":"jokul@email.com",
   "virtualAccountPhone":"6281828384858",
   "trxId":"abcdefgh1234",
   "totalAmount":{
      "value":"12345678.00",
      "currency":"IDR"
   }
}
</code></pre></td><td><p></p><pre class="language-json"><code class="lang-json">{"partnerServiceId":"  088899","customerNo":"12345678901234567890","virtualAccountNo":"  08889912345678901234567890","virtualAccountName":"Jokul Doe","virtualAccountEmail":"jokul@email.com","virtualAccountPhone":"6281828384858","trxId":"abcdefgh1234","totalAmount":{"value":"12345678.00","currency":"IDR"}}
</code></pre></td></tr></tbody></table>

2. Calculate the result of {minify-request-body}  using SHA-256

The result will be like this :&#x20;

```json
3274fab8dac896837b106a16da2a974e7e65142dcecb4b768ef0294102838977
```

3. Hexencode the result of {SHA-256(minify-request-body)}

The result will be like this :&#x20;

3274fab8dac896837b106a16da2a974e7e65142dcecb4b768ef0294102838977

4. Set the result of hexencode{SHA-256(minify-request-body)} to Lowercase [**​**](https://dashboard.doku.com/docs/docs/technical-references/generate-signature#set-client-id-request-id-request-timestamp)

#### Generating StringtoSign

This is the formula for generating the string to Sign :&#x20;

`HTTPMethod +”:“+ EndpointUrl +":“+ Lowercase(HexEncode(SHA256(minify(RequestBody)))) + ":“ + TimeStamp`

{% hint style="info" %}
What is `endpointURL` ?&#x20;

`endpointURL` means Request Target.&#x20;

The Request-Target is depending on who is sending the request:

1. **When merchant hits DOKU endpoints:** The Request-Target is the path of the DOKU API that merchant hits.\
   For instance, if merchant wants to hit DOKU VA API: `https://api.doku.com/`bi-snap-va/v1/transfer-va/create-va. Therefore, the Request-Target value is  /bi-snap-va/v1/transfer-va/create-va
2. **When DOKU hits merchant endpoints (HTTP Notification / Inquiry Request):** The Request-Target is the path of merchant `Notification URL` or the `Inquiry URL`.\
   For instance, if merchant set the `Notification URL`: `https://yourdomain.com/payments/notifications`. Therefore, the Request-Target value is `/payments/notifications`.
   {% endhint %}

### Generate Signature :&#x20;

After all the `stringToSign` component has been set,  merchant can now generate the signature :&#x20;

1. Calculate the result of `(privateKey , stringToSign)` using *SHA256withRSA*&#x20;

   Ex : `qd2m9ot+cfq48qJ68+8IYdfkNDMA2hhecM2XegsnZ1Z5Fur9zii8BVm6cI7g1gyhL5/+OFZqAO8Kp0XPMdipfg==`
2. Put the value to each API in X-Signature component in Request Header


# Response Code

Welcome to the Response Code page. Here, you will find a comprehensive list of response codes generated during transaction processes. Use these codes to troubleshoot and optimize your payment workflows with ease and precision.


# HTTP Status and Case Code

Successful responses are indicated with a 200-series HTTP code and a JSON-based payload containing the object(s) requested, created, modified, or deleted along with an expression of the server’s interpretation of your request.&#x20;

Error responses are served with a non-200-series HTTP code. Different error and case codes indicate different reasons for an error.

## 1. Virtual Account

<table><thead><tr><th>HTTP Status Code</th><th width="114">Case Code</th><th>Response Message</th><th>Description</th></tr></thead><tbody><tr><td>400XX</td><td>00</td><td>Bad Request</td><td>General request failed error, including message parsing failed.</td></tr><tr><td>400XX</td><td>01</td><td>Invalid Field Format {field name}</td><td>Invalid format</td></tr><tr><td>400XX</td><td>02</td><td>Invalid Mandatory Field {field name}</td><td>Missing or invalid format on mandatory field</td></tr><tr><td>401XX</td><td>00</td><td>Unauthorized. [reason]</td><td>General unauthorized error (No Interface Def, API is Invalid, Oauth Failed, Verify Client Secret Fail, Client Forbidden Access API, Unknown Client, Key not Found)</td></tr><tr><td>401XX</td><td>01</td><td>Invalid Token ( B2B )</td><td>Token found in request is invalid (Access Token Not Exist, Access Token Expiry)</td></tr><tr><td>401XX</td><td>03</td><td>Token Not Found (B2B</td><td>Token not found in the system. This occurs on any API that requires token as input parameter</td></tr></tbody></table>

## 2. Credit Card

{% hint style="info" %}
Apart from Acquirer's Response Code, There's also response code generated by DOKU in case if transaction failed due to any validation before being processed to acquirer
{% endhint %}

{% tabs %}
{% tab title="Acquirer Response Code" %}

<table><thead><tr><th width="123">ECode</th><th width="538">Description</th><th width="334">Category</th></tr></thead><tbody><tr><td>00</td><td>Approved or completed successfully</td><td>Issuer approved</td></tr><tr><td>01</td><td>Refer to card issuer, Contact card issuer</td><td>Generic response codes</td></tr><tr><td>02</td><td>Refer to card issuer - Special conditions</td><td>Generic response codes</td></tr><tr><td>03</td><td>Invalid merchant</td><td>Issuer cannot approve at this time</td></tr><tr><td>04</td><td>Pick up card (no fraud)</td><td>Issuer will never approve</td></tr><tr><td>05</td><td>Do not honor</td><td>Generic response codes</td></tr><tr><td>06</td><td>Error (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>07</td><td>Pickup card, special conditions (applies for VISA)</td><td>Issuer will never approve</td></tr><tr><td>08</td><td>Honor with ID (applies for VISA)</td><td>Issuer approved</td></tr><tr><td>10</td><td>Partial value approved</td><td>Generic response codes</td></tr><tr><td>11</td><td>Approved V.I.P (applies for MASTERCARD)</td><td>Issuer approved</td></tr><tr><td>12</td><td>Invalid transaction</td><td>Issuer will never approve</td></tr><tr><td>13</td><td>Invalid value/amount</td><td>Generic response codes</td></tr><tr><td>14</td><td>Invalid card number</td><td>Issuer will never approve</td></tr><tr><td>15</td><td>No such issuer</td><td>Issuer will never approve</td></tr><tr><td>19</td><td>Re-enter transaction (applies for VISA)</td><td>Issuer cannot approve at this time</td></tr><tr><td>21</td><td>No action taken (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>25</td><td>Unable to locate record on file (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>28</td><td>File is temporarily unavailable (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>30</td><td>Format error (applies for MASTERCARD)</td><td>Generic response codes</td></tr><tr><td>39</td><td>No credit account (applies for VISA)</td><td>Issuer cannot approve at this time</td></tr><tr><td>41</td><td>Lost card - pick up</td><td>Issuer will never approve</td></tr><tr><td>43</td><td>Stolen card - pick up</td><td>Issuer will never approve</td></tr><tr><td>46</td><td>Closed Account (applies for VISA)</td><td>Issuer will never approve</td></tr><tr><td>51</td><td>Insufficient funds</td><td>Issuer cannot approve at this time</td></tr><tr><td>52</td><td>No checking account (applies for VISA)</td><td>Issuer cannot approve at this time</td></tr><tr><td>53</td><td>No savings account (applies for VISA)</td><td>Issuer cannot approve at this time</td></tr><tr><td>54</td><td>Expired card</td><td>Issuer cannot approve based on details provided</td></tr><tr><td>55</td><td>Incorrect PIN</td><td>Issuer cannot approve based on details provided</td></tr><tr><td>57</td><td>Transaction not permitted to cardholder</td><td>Issuer will never approve</td></tr><tr><td>58</td><td>Transaction not permitted to terminal</td><td>Generic response codes</td></tr><tr><td>59</td><td>Suspected fraud</td><td>Issuer cannot approve at this time</td></tr><tr><td>61</td><td>Exceeds withdrawal amount limits</td><td>Issuer cannot approve at this time</td></tr><tr><td>62</td><td>Restricted card</td><td>Issuer cannot approve at this time</td></tr><tr><td>63</td><td>Security Violation</td><td>Issuer cannot approve based on details provided</td></tr><tr><td>64</td><td>Transaction does not fulfill AML requirement (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>65</td><td>Exceeds withdrawal frequency limit</td><td>Issuer cannot approve at this time</td></tr><tr><td>70</td><td>Contact Card Issuer (applies for MASTERCARD)</td><td>Issuer cannot approve at this time</td></tr><tr><td>70</td><td>PIN data required (applies for VISA)</td><td>Issuer cannot approve based on details provided</td></tr><tr><td>71</td><td>PIN not changed (applies for MASTERCARD)</td><td>Issuer cannot approve at this time</td></tr><tr><td>74</td><td>Different value than that used for PIN encryption errors</td><td>Generic response codes</td></tr><tr><td>75</td><td>Allowable PIN tries exceeded</td><td>Issuer cannot approve at this time</td></tr><tr><td>76</td><td>Invalid/nonexistent “To Account” specified (applies for MASTERCARD)</td><td>Generic response codes</td></tr><tr><td>76</td><td>Unsolicited reversal (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>77</td><td>Invalid/nonexistent “From Account” specified (applies for MASTERCARD)</td><td>Generic response codes</td></tr><tr><td>78</td><td>Blocked card, first time card usage (applies for VISA)</td><td>Issuer cannot approve at this time</td></tr><tr><td>78</td><td>Invalid/nonexistent account specified (applies for MASTERCARD)</td><td>Generic response codes</td></tr><tr><td>79</td><td>Life Cycle (applies for MASTERCARD)</td><td>Generic response codes</td></tr><tr><td>79</td><td>Already reversed by Switch (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>80</td><td>Credit issuer unavailable (applies for MASTERCARD)</td><td>Generic response codes</td></tr><tr><td>80</td><td>No financial impact (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>81</td><td>Domestic Debit Transaction Not Allowed (applies for MASTERCARD)</td><td>Generic response codes</td></tr><tr><td>81</td><td>Cryptographic error found in PIN (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>82</td><td>Negative CAM, dCVV, iCVV, or CVV results (applies for VISA)</td><td>Issuer cannot approve based on details provided</td></tr><tr><td>82</td><td>Policy (applies for MASTERCARD)</td><td>Generic response codes</td></tr><tr><td>83</td><td>Fraud/Security (applies for MASTERCARD)</td><td>Generic response codes</td></tr><tr><td>84</td><td>Invalid Authorization Life Cycle (applies for MASTERCARD)</td><td>Generic response codes</td></tr><tr><td>85</td><td>No reason to decline</td><td>Issuer approved</td></tr><tr><td>86</td><td>Cannot verify PIN</td><td>Issuer cannot approve at this time</td></tr><tr><td>87</td><td>Purchase amount only, no cash back allowed (applies for MASTERCARD)</td><td>Issuer approved</td></tr><tr><td>88</td><td>Cryptographic failure (applies for MASTERCARD)</td><td>Generic response codes</td></tr><tr><td>89</td><td>Unacceptable PIN (applies for MASTERCARD)</td><td>Generic response codes</td></tr><tr><td>89</td><td>Ineligible to receive financial position information (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>90</td><td>Cutoff is in progress (applies for MASTERCARD)</td><td>Generic response codes</td></tr><tr><td>91</td><td>Issuer or switch is inoperative</td><td>Issuer cannot approve at this time</td></tr><tr><td>92</td><td>Destination cannot be found for routing</td><td>Generic response codes</td></tr><tr><td>93</td><td>Transaction cannot be completed - violation of law (applies for VISA)</td><td>Issuer cannot approve at this time</td></tr><tr><td>94</td><td>Duplicate transmission / invoice</td><td>Generic response codes</td></tr><tr><td>96</td><td>System malfunction</td><td>Issuer cannot approve at this time</td></tr><tr><td>RJ</td><td>Decision Black List CC</td><td>Issuer cannot approve based on details provided</td></tr><tr><td>DA</td><td>Declined Authentication</td><td>Issuer cannot approve at this time</td></tr><tr><td>TO</td><td>Timeout</td><td>Issuer cannot approve at this time</td></tr><tr><td>1A</td><td>Authentication required (applies for VISA)</td><td>Issuer cannot approve based on details provided</td></tr><tr><td>6P</td><td>Verification data failed (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>B1</td><td>Surcharge amount not permitted (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>B2</td><td>Surcharge amount not supported by debit network issuer (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>N0</td><td>Force STIP (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>N3</td><td>Cash service not available (applies for VISA)</td><td>Issuer cannot approve at this time</td></tr><tr><td>N4</td><td>Cash request exceeds issuer or approved limit (applies for VISA)</td><td>Issuer cannot approve at this time</td></tr><tr><td>N5</td><td>Ineligible for resubmission (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>N7</td><td>Decline for CVV2 failure (applies for VISA)</td><td>Issuer cannot approve based on details provided</td></tr><tr><td>N8</td><td>Transaction amount exceeds preauthorized approval amount (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>P5</td><td>Denied PIN unblock (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>P6</td><td>Denied PIN change (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>Q1</td><td>Card Authentication failed (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>R0</td><td>Stop Payment Order (applies for VISA)</td><td>Issuer will never approve</td></tr><tr><td>R1</td><td>Revocation of authorization order (applies for VISA)</td><td>Issuer will never approve</td></tr><tr><td>R2</td><td>Transaction does not qualify for Visa PIN (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>R3</td><td>Revocation of all authorizations order (applies for VISA)</td><td>Issuer will never approve</td></tr><tr><td>Z3</td><td>Unable to go online (applies for VISA)</td><td>Generic response codes</td></tr><tr><td>1Z</td><td>Authorization System or issuer system inoperative (applies for MASTERCARD)</td><td>Generic response codes</td></tr></tbody></table>
{% endtab %}

{% tab title="DOKU Error Code" %}

<table><thead><tr><th width="226">Error Code</th><th width="538">Description</th></tr></thead><tbody><tr><td>INVALID_PARAMETER</td><td>One or more parameter may be invalid in format, length, or missing</td></tr><tr><td>INVALID_BIN_NUMBER</td><td>BIN Number(first 6 or 8 digit of card number)  is invalid </td></tr><tr><td>INVALID_TOKEN</td><td>Token is Invalid</td></tr><tr><td>MID_TID_NOT_EXIST</td><td>DOKU cannot route the transaction to any of the MID owned by merchant due to any routing rule or MID limitation given the Cards number.</td></tr><tr><td>PAYMENT_FAILED</td><td>Generic Error Code</td></tr><tr><td>THREE_D_SECURE_ENROLLMENT_FAILED</td><td>Check 3DS failed during card enrollment process</td></tr><tr><td>THREE_D_SECURE_AUTHENTICATION_FAILED</td><td>Check 3DS failed during card authentication process</td></tr><tr><td>BLOCKED_ECI</td><td>Check 3DS Process completed but resulted in forbidden ECI (not 02 or 5)</td></tr><tr><td>MERCHANT_INSTALLMENT_NOT_EXIST</td><td>Merchant doesnt have installment Compatible MID to process given card.</td></tr><tr><td>FRAUD_DETECTED</td><td>Payment Rejected because of Suspected Fraud</td></tr><tr><td>MERCHANT_NOT_ALLOWED</td><td>Merchant might be suspended or Inactive</td></tr><tr><td>CARD_NUMBER_COUNTRY_IS_BLOCKED</td><td>Card's issuer country is blocked, to enable the card's country origin please consult to DOKU team</td></tr><tr><td>AMOUNT_CAPTURE_EXCEED_AUTHORIZE</td><td>Capture amount is higher than authorized amount</td></tr><tr><td>AUTHORIZATION_FAILED</td><td>Generic Response Code</td></tr><tr><td>CARD_NUMBER_BRAND_IS_BLOCKED</td><td>Card's Brand is not allowed due to MID's support limitation or Blocking Rule (eg. can't do transaction using AMEX brand)</td></tr><tr><td>CARD_NUMBER_BIN_IS_BLOCKED</td><td>Card BIN number is blocked</td></tr><tr><td>TIME_OUT</td><td>Timeout</td></tr><tr><td>BIN_NOT_ALLOWED_BY_MERCHANT</td><td>BIN is blocked by merchant's bin blocking rule</td></tr><tr><td>MID_ROUTING_NOT_FOUND</td><td>MID Routing process cannot found compatible MID to process the given card</td></tr><tr><td>ACQUIRER_NOT_FOUND</td><td>Acquirer not found (for installment transaction)</td></tr><tr><td>MERCHANT_NOT_FOUND</td><td>Merchant not found</td></tr><tr><td>SETTLEMENT_IS_ON_GOING</td><td>Unable process the transaction due to pending settlement in progress</td></tr><tr><td>DECRYPTION_CREDIT_CARD_DATA_FAILED</td><td>Decryption Credit Card Data Is Failed</td></tr><tr><td>ENCRYPTION_CREDIT_CARD_DATA_FAILED</td><td>Encryption Credit Card Data Is Failed</td></tr><tr><td>UPDATE_TRANSACTION_FAILED</td><td>Update Transaction is Failed</td></tr><tr><td>CREATE_TRANSACTION_FAILED</td><td>Create Transaction is Failed</td></tr><tr><td>TRANSACTION_NOT_FOUND</td><td>Transaction Is Not Found</td></tr><tr><td>DATA_NOT_FOUND</td><td>Data Not Found</td></tr><tr><td>DATA_DECRYPTION_FAILED</td><td>Failed on Data Decryption</td></tr><tr><td>CVV_NOT_AVAILABLE</td><td>This Transaction should bring CVV</td></tr><tr><td>CURENCY_MISMATCH</td><td>Currency is Mismatch</td></tr><tr><td>NOT_ALLOWED_VERES</td><td>Veres is Not Allowed</td></tr><tr><td>NOT_ALLOWED_AUTHRES</td><td>AuthRes is Not Allowed</td></tr></tbody></table>
{% endtab %}

{% tab title="DOKU JS Response Code" %}
The possible response code returned by embedded DOKU JS for each API called by the JS Script&#x20;

#### /collect-card-data

| HTTP Status     | Condition                         | Error Code                       | Response Structure                                                                                                                                 |
| --------------- | --------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200 OK          | 3D Secure authentication required | -                                | `{ "message": "<msg>", "session_id": "<id>", "requires_action": true, "action_url": "<3ds_url>", "authentication_id": "<auth_id>" }`               |
| 200 OK          | Non-3DS payment successful        | -                                | `{ "message": "<success_msg>", "session_id": "<id>", "requires_action": true, "action_url": "<callback_url>" }`                                    |
| 200 OK          | Non-3DS payment failed            | -                                | `{ "message": "<failed_msg>", "session_id": "<id>", "requires_action": false, "action_url": "<failed_url>" }`                                      |
| 400 Bad Request | Session ID not found              | `DATA_NOT_FOUND`                 | `{ "error": { "code": "DATA_NOT_FOUND", "message": "Invalid Session Id", "type": "Data Not Found" } }`                                             |
| 400 Bad Request | Failed to decrypt card data       | `INVALID_PARAMETER`              | `{ "error": { "code": "INVALID_PARAMETER", "message": "Failed Decrypt Credit Card Data", "type": "Invalid Parameter" } }`                          |
| 400 Bad Request | Validation error                  | `INVALID_PARAMETER`              | `{ "error": { "code": "INVALID_PARAMETER", "message": "<validation_details>", "type": "Invalid Parameter" } }`                                     |
| 400 Bad Request | Card BIN blocked                  | `CARD_NUMBER_BIN_IS_BLOCKED`     | `{ "error": { "code": "CARD_NUMBER_BIN_IS_BLOCKED", "message": "Card Number Bin Is Blocked", "type": "Card Number Bin Is Blocked" } }`             |
| 400 Bad Request | Card country blocked              | `CARD_NUMBER_COUNTRY_IS_BLOCKED` | `{ "error": { "code": "CARD_NUMBER_COUNTRY_IS_BLOCKED", "message": "Card Number Country Is Blocked", "type": "Card Number Country Is Blocked" } }` |
| 400 Bad Request | Merchant blocking rule triggered  | `MERCHANT_BLOCKING`              | `{ "error": { "code": "MERCHANT_BLOCKING", "message": "Blocking By Merchant", "type": "Blocking By Merchant" } }`                                  |

| HTTP Status      | Condition                     | Error Code                       | Response Structure                                                                                                                                  |
| ---------------- | ----------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200 OK           | Payment charge successful     | -                                | `{ "callback_url": "<merchant_callback_url>" }`                                                                                                     |
| 200 OK           | Payment charge failed         | -                                | `{ "callback_url": "<merchant_failed_url>" }`                                                                                                       |
| 400 Bad Request  | Session not found             | `DATA_NOT_FOUND`                 | `{ "error": { "code": "DATA_NOT_FOUND", "message": "PreTransactionPool Not Found", "type": "Data Not Found" } }`                                    |
| 400 Bad Request  | Invalid authentication ID     | `FAILED_GET_THREE_D_SECURE_DATA` | `{ "error": { "code": "FAILED_GET_THREE_D_SECURE_DATA", "message": "Invalid Authentication Id", "type": "Failed Get Three D Secure Data" } }`       |
| 400 Bad Request  | 3DS data not found            | `FAILED_GET_THREE_D_SECURE_DATA` | `{ "error": { "code": "FAILED_GET_THREE_D_SECURE_DATA", "message": "<error_details>", "type": "Failed Get Three D Secure Data" } }`                 |
| 500 Server Error | JSON mapping/processing error | `MESSAGE_PROCESSING_ERROR`       | `{ "error": { "code": "MESSAGE_PROCESSING_ERROR", "message": "Failed To Mapping Request to Charge Payment", "type": "Message Processing Error" } }` |
| 500 Server Error | Data decryption error         | `MESSAGE_PROCESSING_ERROR`       | `{ "error": { "code": "MESSAGE_PROCESSING_ERROR", "message": "Failed Decryption Data", "type": "Message Processing Error" } }`                      |

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Category Guide**

1. **Issuer will never approve** : This subset of decline codes indicates there is no circumstance in which the issuer will approve.

   **Recommended action: do not try again.**
2. **Issuer cannot approve at this time** : This subset of decline codes indicates the issuer may approve, but cannot do so at that time.

   **Recommended action: try again later.**
3. **Issuer cannot approve based on details provided** : This subset of codes indicates the issuer cannot approve based on the details provided.

   **Recommended action: provide updated or additional information.**
4. **Generic response codes** : and other decline codes not listed, many of which are not explained by the issuers, fall in this category and re-attempt is allowed.

   **Recommended action: try again later**
   {% endhint %}

## 3. e-Wallet

{% tabs %}
{% tab title="ShopeePay" %}

<table><thead><tr><th width="186">HTTP Status Code</th><th width="117">Case Code</th><th>Error Message</th></tr></thead><tbody><tr><td>400XX</td><td>00</td><td>Bad Request</td></tr><tr><td>400XX</td><td>01</td><td>Invalid Field Format {{param}} </td></tr><tr><td>400XX</td><td>02</td><td>Invalid Mandatory Field {{param}}</td></tr><tr><td>401XX</td><td>00</td><td>Unauthorized {param}</td></tr><tr><td>401XX</td><td>01</td><td>Invalid Token B2B</td></tr><tr><td>401XX</td><td>02</td><td>Invalid customer Token</td></tr><tr><td>401XX</td><td>03</td><td>Token not found B2B</td></tr><tr><td>401XX</td><td>04</td><td>Customer token not found</td></tr><tr><td>403XX</td><td>00</td><td>Transacction Expired</td></tr><tr><td>403XX</td><td>01</td><td>Feature Not Allowed</td></tr><tr><td>403XX</td><td>02</td><td>Exceeds Transaction Amount Limit</td></tr><tr><td>403XX</td><td>03</td><td>Suspected Fraud</td></tr><tr><td>403XX</td><td>04</td><td>Activity Count Limit Exceeded</td></tr><tr><td>403XX</td><td>05</td><td>Do Not Honor"</td></tr><tr><td>403XX</td><td>06</td><td>Feature Not Allowed At This Time</td></tr><tr><td>403XX</td><td>07</td><td>Card Blocked</td></tr><tr><td>403XX</td><td>08</td><td>Card Expired</td></tr><tr><td>403XX</td><td>09</td><td>Dormant Account</td></tr><tr><td>403XX</td><td>10</td><td>Need To Set Token Limit</td></tr><tr><td>403XX</td><td>11</td><td>OTP Blocked</td></tr><tr><td>403XX</td><td>12</td><td>OTP Lifetime Expired</td></tr><tr><td>403XX</td><td>13</td><td>OTP Sent To Cardholder</td></tr><tr><td>403XX</td><td>14</td><td>Insufficient Funds</td></tr><tr><td>403XX</td><td>15</td><td>Transaction Not Permitted.</td></tr><tr><td>403XX</td><td>16</td><td>Suspend Transaction</td></tr><tr><td>403XX</td><td>17</td><td>Token Limit Exceeded</td></tr><tr><td>403XX</td><td>18</td><td>Inactive Card/Account/Customer</td></tr><tr><td>403XX</td><td>19</td><td>Merchant Blacklisted</td></tr><tr><td>403XX</td><td>20</td><td>Merchant Limit Exceed</td></tr><tr><td>403XX</td><td>21</td><td>Set Limit Not Allowed</td></tr><tr><td>403XX</td><td>22</td><td>Token Limit Invalid</td></tr><tr><td>403XX</td><td>23</td><td>Account Limit Exceed</td></tr><tr><td>404XX</td><td>00</td><td>Invalid Transaction Status</td></tr><tr><td>404XX</td><td>01</td><td>Transaction Not Found</td></tr><tr><td>404XX</td><td>02</td><td>Invalid Routing</td></tr><tr><td>404XX</td><td>03</td><td>Bank Not Supported By Switch</td></tr><tr><td>404XX</td><td>04</td><td>Transaction Cancelled</td></tr><tr><td>404XX</td><td>05</td><td>Merchant Is Not Registered For Card Registration Services</td></tr><tr><td>404XX</td><td>06</td><td>Need To Request OTP</td></tr><tr><td>404XX</td><td>07</td><td>Journey Not Found</td></tr><tr><td>404XX</td><td>08</td><td>Invalid Merchant</td></tr><tr><td>404XX</td><td>09</td><td>No Issuer</td></tr><tr><td>404XX</td><td>10</td><td>Invalid API Transition</td></tr><tr><td>404XX</td><td>11</td><td>Invalid Card/Account/Customer [info]/Virtual Account</td></tr><tr><td>404XX</td><td>12</td><td>Invalid Bill/Virtual Account</td></tr><tr><td>404XX</td><td>13</td><td>Invalid Amount</td></tr><tr><td>404XX</td><td>14</td><td>Paid Bill</td></tr><tr><td>404XX</td><td>15</td><td>Invalid OTP</td></tr><tr><td>404XX</td><td>16</td><td>Partner Not Found</td></tr><tr><td>404XX</td><td>17</td><td>Invalid Terminal</td></tr><tr><td>404XX</td><td>18</td><td>Inconsistent Request</td></tr><tr><td>404XX</td><td>19</td><td>Invalid Bill/Virtual Account</td></tr><tr><td>405XX</td><td>00</td><td>Requested Function Is Not Supported</td></tr><tr><td>405XX</td><td>01</td><td>Requested Operation Is Not Allowed</td></tr><tr><td>409XX</td><td>00</td><td>Conflict</td></tr><tr><td>409XX</td><td>01</td><td>Duplicate partnerReferenceNo</td></tr><tr><td>429XX</td><td>00</td><td>Too Many Requests</td></tr><tr><td>500XX</td><td>00</td><td>General Error</td></tr><tr><td>500XX</td><td>01</td><td>Internal Server Error</td></tr><tr><td>500XX</td><td>02</td><td>External Server Error</td></tr><tr><td>504XX</td><td>00</td><td>Timeout</td></tr></tbody></table>

{% endtab %}

{% tab title="DANA" %}

<table><thead><tr><th width="196">HTTP Status Code</th><th width="139">Case Code</th><th>Error Message</th></tr></thead><tbody><tr><td>200XX</td><td>00</td><td>Successful</td></tr><tr><td>202XX</td><td>00</td><td>Request In Progress</td></tr><tr><td>400XX</td><td>00</td><td><p> </p><p>Bad Request<br></p></td></tr><tr><td>400XX</td><td>01</td><td>Invalid Field Format {field name}</td></tr><tr><td>400XX</td><td>02</td><td>Invalid Mandatory Field {field name}</td></tr><tr><td>401XX</td><td>00</td><td>Unauthorized. [reason]</td></tr><tr><td>401XX</td><td>01</td><td>Invalid Token (B2B)</td></tr><tr><td>401XX</td><td>02</td><td><p></p><p>Invalid Customer Token</p></td></tr><tr><td>401XX</td><td>04</td><td>Customer Token Not Found</td></tr><tr><td>403XX</td><td>02</td><td>Exceeds Transaction Amount Limit</td></tr><tr><td>403XX</td><td>05</td><td>Do Not Honor</td></tr><tr><td>403XX</td><td>14</td><td>Insufficient Funds</td></tr><tr><td>403XX</td><td>15</td><td>Transaction Not Permitted.[reason]</td></tr><tr><td>404XX</td><td>00</td><td>Invalid Transaction Status</td></tr><tr><td>404XX</td><td>01</td><td> Transaction Not Found</td></tr><tr><td>404XX</td><td>08</td><td>Invalid Merchant</td></tr><tr><td>404XX</td><td>12</td><td>Invalid Bill/Virtual Account [Reason]</td></tr><tr><td>404XX</td><td>13</td><td>Invalid Amount</td></tr><tr><td>404XX</td><td>18</td><td>Inconsistent Request</td></tr><tr><td>429XX</td><td>00</td><td>Too Many Requests</td></tr><tr><td>500XX</td><td>00</td><td>General Error</td></tr><tr><td>500XX</td><td>01</td><td>Internal Server Error</td></tr></tbody></table>
{% endtab %}

{% tab title="OVO" %}

<table><thead><tr><th width="189">HTTP Status Code</th><th width="129">Case Code</th><th>Error Message</th></tr></thead><tbody><tr><td>200XX</td><td>00</td><td>Successful</td></tr><tr><td>202XX</td><td>00</td><td>Request In Progress</td></tr><tr><td>400XX</td><td>00</td><td><p> </p><p>Bad Request<br></p></td></tr><tr><td>400XX</td><td>01</td><td>Invalid Field Format {field name}</td></tr><tr><td>400XX</td><td>02</td><td>Invalid Mandatory Field {field name}</td></tr><tr><td>401XX</td><td>00</td><td>Unauthorized. [reason]</td></tr><tr><td>401XX</td><td>01</td><td>Invalid Token (B2B)</td></tr><tr><td>401XX</td><td>02</td><td><p></p><p>Invalid Customer Token</p></td></tr><tr><td>401XX</td><td>04</td><td>Customer Token Not Found</td></tr><tr><td>403XX</td><td>02</td><td>Exceeds Transaction Amount Limit</td></tr><tr><td>403XX</td><td>05</td><td>Do Not Honor</td></tr><tr><td>403XX</td><td>14</td><td>Insufficient Funds</td></tr><tr><td>403XX</td><td>15</td><td>Transaction Not Permitted.[reason]</td></tr><tr><td>404XX</td><td>00</td><td>Invalid Transaction Status</td></tr><tr><td>404XX</td><td>01</td><td> Transaction Not Found</td></tr><tr><td>404XX</td><td>08</td><td>Invalid Merchant</td></tr><tr><td>404XX</td><td>12</td><td>Invalid Bill/Virtual Account [Reason]</td></tr><tr><td>404XX</td><td>13</td><td>Invalid Amount</td></tr><tr><td>404XX</td><td>18</td><td>Inconsistent Request</td></tr><tr><td>429XX</td><td>00</td><td>Too Many Requests</td></tr><tr><td>500XX</td><td>00</td><td>General Error</td></tr><tr><td>500XX</td><td>01</td><td>Internal Server Error</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## 4. Direct Debit

{% tabs %}
{% tab title="Allobank" %}

<table><thead><tr><th width="210">HTTP Status Code</th><th width="121">Case Code</th><th>Error Message</th></tr></thead><tbody><tr><td>200XX</td><td>00</td><td>Successful</td></tr><tr><td>400XX</td><td>00</td><td><p> </p><p>Bad Request<br></p></td></tr><tr><td>400XX</td><td>01</td><td>Invalid Field Format {field name}</td></tr><tr><td>400XX</td><td>02</td><td>Invalid Mandatory Field {field name}</td></tr><tr><td>401XX</td><td>00</td><td>Unauthorized. [reason]</td></tr><tr><td>401XX</td><td>01</td><td>Invalid Token (B2B)</td></tr><tr><td>401XX</td><td>02</td><td><p></p><p>Invalid Customer Token</p></td></tr><tr><td>401XX</td><td>04</td><td>Customer Token Not Found</td></tr><tr><td>403XX</td><td>02</td><td>Exceeds Transaction Amount Limit</td></tr><tr><td>403XX</td><td>05</td><td>Do Not Honor</td></tr><tr><td>403XX</td><td>14</td><td>Insufficient Funds</td></tr><tr><td>403XX</td><td>15</td><td>Transaction Not Permitted.[reason]</td></tr><tr><td>404XX</td><td>00</td><td>Invalid Transaction Status</td></tr><tr><td>404XX</td><td>01</td><td>Transaction Not Found</td></tr><tr><td>404XX</td><td>08</td><td>Invalid Merchant</td></tr><tr><td>404XX</td><td>12</td><td>Invalid Bill/Virtual Account [Reason]</td></tr><tr><td>404XX</td><td>13</td><td>Invalid Amount</td></tr><tr><td>404XX</td><td>18</td><td>Inconsistent Request</td></tr><tr><td>429XX</td><td>00</td><td>Too Many Requests</td></tr><tr><td>500XX</td><td>00</td><td>General Error</td></tr><tr><td>500XX</td><td>01</td><td>Internal Server Error</td></tr></tbody></table>
{% endtab %}

{% tab title="CIMB" %}

<table><thead><tr><th width="196">HTTP Status Code</th><th width="136">Case Code</th><th>Error Message</th></tr></thead><tbody><tr><td>200XX</td><td>00</td><td>Successful</td></tr><tr><td>400XX</td><td>00</td><td><p> </p><p>Bad Request<br></p></td></tr><tr><td>400XX</td><td>01</td><td>Invalid Field Format {field name}</td></tr><tr><td>400XX</td><td>02</td><td>Invalid Mandatory Field {field name}</td></tr><tr><td>401XX</td><td>00</td><td>Unauthorized. [reason]</td></tr><tr><td>401XX</td><td>01</td><td>Invalid Token (B2B)</td></tr><tr><td>401XX</td><td>02</td><td><p></p><p>Invalid Customer Token</p></td></tr><tr><td>401XX</td><td>04</td><td>Customer Token Not Found</td></tr><tr><td>403XX</td><td>02</td><td>Exceeds Transaction Amount Limit</td></tr><tr><td>403XX</td><td>05</td><td>Do Not Honor</td></tr><tr><td>403XX</td><td>14</td><td>Insufficient Funds</td></tr><tr><td>403XX</td><td>15</td><td>Transaction Not Permitted.[reason]</td></tr><tr><td>404XX</td><td>00</td><td>Invalid Transaction Status</td></tr><tr><td>404XX</td><td>01</td><td> Transaction Not Found</td></tr><tr><td>404XX</td><td>08</td><td>Invalid Merchant</td></tr><tr><td>404XX</td><td>12</td><td>Invalid Bill/Virtual Account [Reason]</td></tr><tr><td>404XX</td><td>13</td><td>Invalid Amount</td></tr><tr><td>404XX</td><td>18</td><td>Inconsistent Request</td></tr><tr><td>429XX</td><td>00</td><td>Too Many Requests</td></tr><tr><td>500XX</td><td>00</td><td>General Error</td></tr><tr><td>500XX</td><td>01</td><td>Internal Server Error</td></tr></tbody></table>
{% endtab %}

{% tab title="BRI" %}

| HTTP Status Code | Case Code | Error Message                          |
| ---------------- | --------- | -------------------------------------- |
| 200XX            | 00        | Successful                             |
| 400XX            | 00        | <p> </p><p>Bad Request<br></p>         |
| 400XX            | 01        | Invalid Field Format {field name}      |
| 400XX            | 02        | Invalid Mandatory Field {field name}   |
| 401XX            | 00        | Unauthorized. \[reason]                |
| 401XX            | 01        | Invalid Token (B2B)                    |
| 401XX            | 02        | <p></p><p>Invalid Customer Token</p>   |
| 401XX            | 04        | Customer Token Not Found               |
| 403XX            | 02        | Exceeds Transaction Amount Limit       |
| 403XX            | 05        | Do Not Honor                           |
| 403XX            | 14        | Insufficient Funds                     |
| 403XX            | 15        | Transaction Not Permitted.\[reason]    |
| 404XX            | 00        | Invalid Transaction Status             |
| 404XX            | 01        | Transaction Not Found                  |
| 404XX            | 08        | Invalid Merchant                       |
| 404XX            | 12        | Invalid Bill/Virtual Account \[Reason] |
| 404XX            | 13        | Invalid Amount                         |
| 404XX            | 18        | Inconsistent Request                   |
| 429XX            | 00        | Too Many Requests                      |
| 500XX            | 00        | General Error                          |
| 500XX            | 01        | Internal Server Error                  |
| {% endtab %}     |           |                                        |
| {% endtabs %}    |           |                                        |

## 5. QRIS

{% tabs %}
{% tab title="Generate QR" %}

| HTTP Status Code | Case Code | Error Messages                          |
| ---------------- | --------- | --------------------------------------- |
| 200XX            | 00        | Request has been processed successfully |
| 400XX            | 01        | Invalid Field Format (name\_field)      |
| 400XX            | 02        | Invalid Mandatory Field (name\_field)   |
| 401XX            | 00        | Unauthorized . Signature Not Match      |
| 401XX            | 00        | Unauthorized . Unknown Client           |
| 401XX            | 01        | Access Token Invalid (B2B)              |
| 404XX            | 08        | Invalid Merchant                        |
| 404XX            | 18        | Inconsistent Request                    |
| 409XX            | 00        | Conflict                                |
| {% endtab %}     |           |                                         |

{% tab title="Decode QR" %}

| HTTP Status Code | Case Code | Error Messages                          |
| ---------------- | --------- | --------------------------------------- |
| 200XX            | 00        | Request has been processed successfully |
| 400XX            | 00        | Parsing Error                           |
| 400XX            | 01        | Invalid Field Format (name\_field)      |
| 400XX            | 02        | Invalid Mandatory Field (name\_field)   |
| 401XX            | 00        | Unauthorized . Signature Not Match      |
| 401XX            | 00        | Unauthorized . Unknown Client           |
| 401XX            | 01        | Access Token Invalid (B2B)              |
| 409XX            | 00        | Conflict                                |
| {% endtab %}     |           |                                         |

{% tab title="Payment QR" %}

| HTTP Status Code | Case Code | Error Messages                          |
| ---------------- | --------- | --------------------------------------- |
| 200XX            | 00        | Request has been processed successfully |
| 400XX            | 00        | Parsing Error                           |
| 400XX            | 01        | Invalid Field Format (name\_field)      |
| 400XX            | 02        | Invalid Mandatory Field (name\_field)   |
| 400XX            | 01        | Amount not match                        |
| 400XX            | 01        | feeAmount not match                     |
| 401XX            | 00        | Unauthorized . Signature Not Match      |
| 401XX            | 00        | Unauthorized . Unknown Client           |
| 401XX            | 01        | Access Token Invalid (B2B)              |
| 409XX            | 00        | Conflict                                |
| {% endtab %}     |           |                                         |

{% tab title="Query QR" %}

| HTTP Status Code | Case Code | Error Messages                          |
| ---------------- | --------- | --------------------------------------- |
| 200XX            | 00        | Request has been processed successfully |
| 404XX            | 01        | Transaction Not Found                   |
| 400XX            | 01        | Invalid Field Format (name\_field)      |
| 400XX            | 02        | Invalid Mandatory Field (name\_field)   |
| 401XX            | 00        | Unauthorized . Signature Not Match      |
| 401XX            | 00        | Unauthorized . Unknown Client           |
| 401XX            | 01        | Access Token Invalid (B2B)              |
| 409XX            | 00        | Conflict                                |
| {% endtab %}     |           |                                         |

{% tab title="Refund QR" %}

| HTTP Status Code | Case Code | Error Messages                          |
| ---------------- | --------- | --------------------------------------- |
| 200XX            | 00        | Request has been processed successfully |
| 403XX            | 15        | Transaction Not Permitted               |
| 404XX            | 01        | Transaction Not Found                   |
| 400XX            | 01        | Invalid Field Format (name\_field)      |
| 400XX            | 02        | Invalid Mandatory Field (name\_field)   |
| 403XX            | 02        | Exceeds Transaction Amount Limit        |
| 401XX            | 00        | Unauthorized . Signature Not Match      |
| 401XX            | 00        | Unauthorized . Unknown Client           |
| 401XX            | 01        | Access Token Invalid (B2B)              |
| 405XX            | 00        | Requested Function Is Not Supported     |
| 409XX            | 00        | Conflict                                |
| {% endtab %}     |           |                                         |
| {% endtabs %}    |           |                                         |

## 6. Kirim DOKU

{% tabs %}
{% tab title="Account Inquiry" %}

| HTTP Code | Response Code | Response Message                                      | Description                                                                                                                                                                                                                                                              | Status  |
| --------- | ------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| 200       | 2004200       | Successful                                            | Successful                                                                                                                                                                                                                                                               | Success |
| 400       | 4004200       | Bad Request                                           | General request failed error, including message parsing failed.                                                                                                                                                                                                          | Failed  |
| 400       | 4004201       | Invalid Field Format {Field}                          | <p>Invalid format.</p><p>For example caused by:</p><ol><li>Invalid currency code</li><li>Amount is filled with non numerical values</li><li>etc</li></ol>                                                                                                                | Failed  |
| 400       | 4004202       | Invalid Mandatory Field {Field}                       | <p>Missing mandatory fields.</p><p>For example caused by:</p><ol><li>Field amount does not exist in the request</li><li>Field senderCountryCode does not exist in the request</li><li>Field beneficiaryAccountNumber does not exist in the request</li><li>etc</li></ol> | Failed  |
| 401       | 4014200       | Unauthorized. \[reason]                               | <p>General unauthorized error.</p><p>E.g. invalid X-SIGNATURE, X-TIMESTAMP, X-PARTNER-ID, X-EXTERNAL-ID, or Authorization.</p>                                                                                                                                           | Failed  |
| 401       | 4014201       | Invalid Token (B2B)                                   | Token found in request in invalid                                                                                                                                                                                                                                        | Failed  |
| 403       | 4034201       | Feature Not Allowed \[reason]                         | E.g. Forex setting has not been set                                                                                                                                                                                                                                      | Failed  |
| 403       | 4034202       | Exceeds Transaction Amount Limit                      | Contact the administrator. Check the range of amount in sub channel, or fee settings.                                                                                                                                                                                    | Failed  |
| 403       | 4034206       | Feature Not Allowed At This Time                      | Ongoing cut off time                                                                                                                                                                                                                                                     | Failed  |
| 404       | 4044200       | Invalid Transaction Status                            | Invalid transaction status                                                                                                                                                                                                                                               | Failed  |
| 404       | 4044202       | Invalid Routing                                       | Invalid routing                                                                                                                                                                                                                                                          | Failed  |
| 404       | 4044203       | Bank Not Supported By Switch                          | Contact the administrator. Check sub channel or route bank settings.                                                                                                                                                                                                     | Failed  |
| 404       | 4044208       | Invalid Merchant                                      | <p>May be caused by:</p><ul><li>The partner does not exist or is no longer active.</li><li>Agent key not found</li></ul>                                                                                                                                                 | Failed  |
| 404       | 4044211       | Invalid Card/Account/Customer \[info]/Virtual Account | Beneficiary account numbers may be invalid, inactive, or not found.                                                                                                                                                                                                      | Failed  |
| 404       | 4044212       | Invalid Bill/Virtual Account                          | The bill is blocked/suspended/not found                                                                                                                                                                                                                                  | Failed  |
| 404       | 4044219       | Invalid Bill/Virtual Account                          | The bill is expired (VA Payment)                                                                                                                                                                                                                                         | Failed  |
| 409       | 4094200       | Conflict                                              | Cannot use the same X-EXTERNAL-ID in the same day                                                                                                                                                                                                                        | Failed  |
| 429       | 4294200       | Too Many Requests                                     | Caused by beneficiary account number has failed inquiry 4 times in the past 2 hours.                                                                                                                                                                                     | Failed  |
| 500       | 5004200       | General Error                                         | Contact the administrator. Check partner settings in the back office. E.g. forex settings                                                                                                                                                                                | Failed  |
| 500       | 5004201       | Internal Server Error                                 | Unknown internal server failure. Please retry the inquiry process.                                                                                                                                                                                                       | Failed  |
| 500       | 5004202       | External Server Error                                 | E.g. system failure                                                                                                                                                                                                                                                      | Failed  |
| 504       | 5044200       | Timeout                                               | Timeou                                                                                                                                                                                                                                                                   | Failed  |

{% endtab %}

{% tab title="Balance Inquiry" %}

| HTTP Code    | Response Code | Response Message        | Description                                                                                                                    | Status  |
| ------------ | ------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------- |
| 200          | 2001100       | Successful              | Successful                                                                                                                     | Success |
| 401          | 4011100       | Unauthorized. \[reason] | <p>General unauthorized error.</p><p>E.g. invalid X-SIGNATURE, X-TIMESTAMP, X-PARTNER-ID, X-EXTERNAL-ID, or Authorization.</p> | Failed  |
| 401          | 4011101       | Invalid Token (B2B)     | Token found in request in invalid                                                                                              | Failed  |
| 500          | 5001100       | General Error           | General Error                                                                                                                  | Failed  |
| {% endtab %} |               |                         |                                                                                                                                |         |

{% tab title="Transfer Bank" %}

| HTTP Code    | Response Code | Response Message                                      | Description                                                                                                                                                                                                                                                                                                                                                                    | Status                                                        |
| ------------ | ------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
| 200          | 2004300       | Successful                                            | <p>Successful.</p><p>Transaction is successfully processed. Labeled with PAID in the dashboard.</p><p><br></p><p>Treat transactions with this status as success.</p>                                                                                                                                                                                                           | Success                                                       |
| 202          | 2024300       | Transaction still on process                          | <p>Timeout (pending) transaction. Status will be changed after reconciliation (T+1 working days). Labeled with UNPAID in the dashboard.</p><p><br></p><p>Do not treat transactions with this status as success or failure.</p>                                                                                                                                                 | Pending                                                       |
| 400          | 4004300       | Bad Request                                           | General request failed error including message parsing failed                                                                                                                                                                                                                                                                                                                  | Failed                                                        |
| 400          | 4004301       | Invalid Field Format {field name}                     | <p>Invalid format</p><p>For example caused by:</p><ol><li>Invalid currency code</li><li>Amount is filled with non numerical values</li><li>etc</li></ol>                                                                                                                                                                                                                       | Failed                                                        |
| 400          | 4004302       | Invalid Mandatory Field {field name}                  | <p>Missing or invalid format on mandatory field</p><p>For example caused by:</p><ol><li>Field amount does not exist in the request</li><li>Field senderCountryCode does not exist in the request</li><li>Field beneficiaryAccountNumber does not exist in the request</li><li>etc</li></ol>                                                                                    | Failed                                                        |
| 401          | 4014300       | Unauthorized. \[reason]                               | <p>General unauthorized error.</p><p>E.g. invalid X-SIGNATURE, X-TIMESTAMP, X-PARTNER-ID, X-EXTERNAL-ID, or Authorization.</p>                                                                                                                                                                                                                                                 | <p>Request API Failed </p><p>(not the transaction status)</p> |
| 401          | 4014301       | Invalid Token (B2B)                                   | Token found in request in invalid                                                                                                                                                                                                                                                                                                                                              | <p>Request API Failed</p><p>(not the transaction status)</p>  |
| 403          | 4034300       | Transaction Expired                                   | Session ID expires after 30 days                                                                                                                                                                                                                                                                                                                                               | Failed                                                        |
| 403          | 4034301       | Feature Not Allowed                                   | E.g. the merchant is not allowed to call Direct Debit APIs                                                                                                                                                                                                                                                                                                                     | Failed                                                        |
| 403          | 4034302       | Exceeds Transaction Amount Limit                      | Exceeds the transaction amount limit                                                                                                                                                                                                                                                                                                                                           | Failed                                                        |
| 403          | 4034303       | Suspected Fraud                                       | <p>Transaction with high risk. Caused by several reasons:</p><ol><li>Multiple transfers to the same beneficiary within the last 60 seconds.</li><li>Multiple transfers to the same beneficiary up to IDR 500 million/day or 50 times/day.</li><li>Multiple transfers to the same beneficiary up to IDR 1 billion/month or 200 times/month.</li><li>Banned customers.</li></ol> | Failed                                                        |
| 403          | 4034304       | Activity Count Limit Exceeded                         | Too many request                                                                                                                                                                                                                                                                                                                                                               | Failed                                                        |
| 403          | 4034305       | Do Not Honor                                          | Account or user status is abnormal                                                                                                                                                                                                                                                                                                                                             | Failed                                                        |
| 403          | 4034306       | At This Time                                          | Ongoing cut off time                                                                                                                                                                                                                                                                                                                                                           | Failed                                                        |
| 403          | 4034309       | Dormant Account                                       | The account is dormant                                                                                                                                                                                                                                                                                                                                                         | Failed                                                        |
| 403          | 4034314       | Insufficient Funds                                    | Insufficient funds                                                                                                                                                                                                                                                                                                                                                             | Failed                                                        |
| 403          | 4034315       | Transaction Not Permitted                             | Transaction is not permitted                                                                                                                                                                                                                                                                                                                                                   | Failed                                                        |
| 403          | 4034316       | Suspend Transaction                                   | Suspend transaction                                                                                                                                                                                                                                                                                                                                                            | Failed                                                        |
| 403          | 4034318       | Inactive Card/Account/Customer                        | Indicates inactive account                                                                                                                                                                                                                                                                                                                                                     | Failed                                                        |
| 403          | 4034319       | Merchant Blacklisted                                  | Merchant is suspended from calling any APIs                                                                                                                                                                                                                                                                                                                                    | Failed                                                        |
| 404          | 4044301       | Transaction Not Found                                 | Transaction not found                                                                                                                                                                                                                                                                                                                                                          | Failed                                                        |
| 404          | 4044302       | Invalid Routing                                       | Invalid routing                                                                                                                                                                                                                                                                                                                                                                | Failed                                                        |
| 404          | 4044303       | Bank Not Supported By Switch                          | Contact the administrator. Check sub channel or route bank settings.                                                                                                                                                                                                                                                                                                           | Failed                                                        |
| 404          | 4044308       | Invalid Merchant                                      | <p>May be caused by:</p><ul><li>The partner does not exist or is no longer active.</li><li>Agent key not found</li></ul>                                                                                                                                                                                                                                                       | Failed                                                        |
| 404          | 4044311       | Invalid Card/Account/Customer \[info]/Virtual Account | Beneficiary account numbers may be invalid, inactive, or not found.                                                                                                                                                                                                                                                                                                            | Failed                                                        |
| 404          | 4044312       | Invalid Bill/Virtual Account                          | The bill is blocked/suspended/not found                                                                                                                                                                                                                                                                                                                                        | Failed                                                        |
| 404          | 4044313       | Invalid Amount                                        | The amount doesn’t match with what supposed to                                                                                                                                                                                                                                                                                                                                 | Failed                                                        |
| 404          | 4044314       | Paid Bill                                             | The bill has been paid (Payment VA)                                                                                                                                                                                                                                                                                                                                            | Failed                                                        |
| 404          | 4044318       | Inconsistent Request                                  | Inconsistent request parameter found for the same partner reference number/transaction ID                                                                                                                                                                                                                                                                                      | Failed                                                        |
| 404          | 4044319       | Invalid Bill/Virtual Account                          | The bill is expired (Payment VA)                                                                                                                                                                                                                                                                                                                                               | Failed                                                        |
| 409          | 4094300       | Conflict                                              | Cannot use the same X-EXTERNAL-ID in the same day                                                                                                                                                                                                                                                                                                                              | Failed                                                        |
| 409          | 4094301       | Duplicate partnerReferenceNo                          | Transaction has previously been processed indicates the same partnerReferenceNo already success                                                                                                                                                                                                                                                                                | Failed                                                        |
| 409          | 4094302       | Transaction Has Been Processed                        | Transaction has previously been processed indicates the same SessionId                                                                                                                                                                                                                                                                                                         | Failed                                                        |
| 500          | 5004300       | General Error                                         | Contact the administrator. Check partner settings in the back office. E.g. forex settings                                                                                                                                                                                                                                                                                      | Pending                                                       |
| 500          | 5004301       | Internal Server Error                                 | Unknown internal server failure. Please retry the inquiry process.                                                                                                                                                                                                                                                                                                             | Pending                                                       |
| 500          | 5004302       | External Server Error                                 | E.g. system failure                                                                                                                                                                                                                                                                                                                                                            | Pending                                                       |
| 504          | 5044300       | Timeout                                               | Timeout                                                                                                                                                                                                                                                                                                                                                                        | Pending                                                       |
| {% endtab %} |               |                                                       |                                                                                                                                                                                                                                                                                                                                                                                |                                                               |

{% tab title="Check Status" %}

| HTTP Code     | Response Code | Response Message        | Description                                                                                                                    |
| ------------- | ------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 200           | 2005300       | Successful              | Successful                                                                                                                     |
| 401           | 4015300       | Unauthorized. \[reason] | <p>General unauthorized error.</p><p>E.g. invalid X-SIGNATURE, X-TIMESTAMP, X-PARTNER-ID, X-EXTERNAL-ID, or Authorization.</p> |
| 401           | 4015301       | Invalid Token (B2B)     | Token found in request in invalid                                                                                              |
| 404           | 4045301       | Transaction Not Found   | Invalid referenceNo or sessionId                                                                                               |
| 500           | 5005300       | General Error           | General Error                                                                                                                  |
| {% endtab %}  |               |                         |                                                                                                                                |
| {% endtabs %} |               |                         |                                                                                                                                |


# Check Status API


# Non-SNAP

To get the status of a transaction, you can send a request to DOKU Check Status API. It will response with the transaction status. This method requires the transaction `order.invoice_number` (or `Request-Id`) as the identifier.

{% hint style="danger" %}
**Hit Check status after 60 seconds after payment completion!**

To get the status for the transaction, please ensure your application is already hit after 60 seconds after payment completion.
{% endhint %}

### Transaction Status Mapping[​](https://dashboard.doku.com/docs/docs/technical-references/status-mapping#transaction-status-mapping) <a href="#api-request" id="api-request"></a>

Here is the list of status that DOKU will provide for the `transaction.status`:

| Name       | Description                                       | Final Status | Merchant Action                                                         | Applicable for Channels                                                              |
| ---------- | ------------------------------------------------- | ------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `PENDING`  | Transaction is waiting to be paid by the customer | NO           | Wait for HTTP Notification or Call Check Status API to get final status | `VIRTUAL_ACCOUNT`, `ONLINE_TO_OFFLINE`, `CREDIT_CARD_AUTHORIZE`, `PAYLATER, EWALLET` |
| `SUCCESS`  | Transaction is paid by the customer               | YES          | -                                                                       | All Channels                                                                         |
| `FAILED`   | Transaction is failed to be paid                  | NO           | Generate new payment request to DOKU                                    | `VIRTUAL_ACCOUNT`,`CREDIT_CARD`, `DIRECT_DEBIT`, `E_MONEY`, `PAYLATER`               |
| `EXPIRED`  | Transaction due date is exceeded                  | YES          | Generate new payment request to DOKU                                    | `VIRTUAL_ACCOUNT`, `ONLINE_TO_OFFLINE` , `PAYLATER`                                  |
| `REFUNDED` | Transaction fund is refunded to merchant          | YES          | -                                                                       | `CREDIT CARD`, `EMONEY`, `PAYLATER`                                                  |
| `TIMEOUT`  | Transaction is timeout                            | NO           | Call Check Status API to get final status                               | `E_MONEY`                                                                            |
| `REDIRECT` | Transaction is waiting for acquirer verification  | NO           | Wait for HTTP Notification or Call Check Status API to get final status | `CREDIT_CARD`                                                                        |

### API Request <a href="#api-request" id="api-request"></a>

| Type                          | Value                                                                                  |
| ----------------------------- | -------------------------------------------------------------------------------------- |
| **HTTP Method**               | GET                                                                                    |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/orders/v1/status/{{order.invoice_number OR Request-Id}}` |
| **API endpoint (Production)** | `https://api.doku.com/orders/v1/status/{{order.invoice_number OR Request-Id}}`         |

Here is the sample of notification request header:

```
Client-Id: MCH-0001-10791114622547
Request-Id: e71fe02a-bfef-4af9-a6f6-2cf1f03b00e7
Request-Timestamp: 2020-11-18T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
```

#### Request Header Explanation

<table><thead><tr><th width="199">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>client-id</code></strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong><code>request-id</code></strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong><code>request-timestamp</code></strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong><code>signature</code></strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="https://dashboard.doku.com/docs/docs/technical-references/generate-signature">this section</a> to generate the signature</td></tr></tbody></table>

**Signature Generation for GET Method**

For GET Method, you don't need to generate a Digest. Learn more on this section.

### API Response <a href="#api-response" id="api-response"></a>

The response will be similar to HTTP notification. Some parameters might not be presented in certain status cases, please check our Postman Collection to try it out yourself.

### Virtual Account

The response will be similar to HTTP notification. Some parameters might not be presented in certain status cases, please check our Postman Collection to try it out yourself.

* BCA VA
* Mandiri VA
* BSI VA
* DOKU VA
* BRI VA
* CIMB VA
* Permata VA
* BNI VA

{% tabs %}
{% tab title="BCA VA" %}

```json
{
    "service": {
        "id": "VIRTUAL_ACCOUNT"
    },
    "acquirer": {
        "id": "BCA"
    },
    "channel": {
        "id": "VIRTUAL_ACCOUNT_BCA"
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2021-01-27T03:24:23Z",
        "original_request_id": "15022aab-444f-4b04-afa8-ddfce89432ec"
    },
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "virtual_account_info": {
        "virtual_account_number": "1900600000000046"
    },
    "virtual_account_payment": {
        "identifer": [
            {
                "name": "REQUEST_ID",
                "value": "7892931"
            },
            {
                "name": "REFERENCE",
                "value": "6769200"
            },
            {
                "name": "CHANNEL_TYPE",
                "value": "6010"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="Mandiri VA" %}

```json
{
    "service": {
        "id": "VIRTUAL_ACCOUNT"
    },
    "acquirer": {
        "id": "BANK_MANDIRI"
    },
    "channel": {
        "id": "VIRTUAL_ACCOUNT_BANK_MANDIRI"
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2021-01-27T07:24:50Z",
        "original_request_id": "cc682442-6c22-493e-8121-b9ef6b3fa728"
    },
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "virtual_account_info": {
        "virtual_account_number": "8889940000000213"
    },
    "virtual_account_payment": {
        "identifier": [
            {
                "name": "TRANSACTION_ID",
                "value": "8341422"
            },
            {
                "name": "CHANNEL_ID",
                "value": "001"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="BSI VA" %}

```json
{
    "service": {
        "id": "VIRTUAL_ACCOUNT"
    },
    "acquirer": {
        "id": "BANK_SYARIAH_MANDIRI"
    },
    "channel": {
        "id": "VIRTUAL_ACCOUNT_BANK_SYARIAH_MANDIRI"
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2021-01-27T06:00:20Z",
        "original_request_id": "d24a5644-6078-4249-8740-4a6dcd92df5a"
    },
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "virtual_account_info": {
        "virtual_account_number": "6059000000000205"
    },
    "virtual_account_payment": {
        "identifier": [
            {
                "name": "PAY_TERMINAL_ID",
                "value": ""
            },
            {
                "name": "BANK_REFERENCE",
                "value": "1232990188"
            },
            {
                "name": "PAY_CHANNEL",
                "value": "6019"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="DOKU VA" %}

```json
{
    "service": {
        "id": "VIRTUAL_ACCOUNT"
    },
    "acquirer": {
        "id": "DOKU"
    },
    "channel": {
        "id": "VIRTUAL_ACCOUNT_DOKU"
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2021-01-22T07:06:28Z",
        "original_request_id": "09e0defe-a071-45b3-9feb-ac134374628c"
    },
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "virtual_account_info": {
        "virtual_account_number": "8000100000000323"
    },
    "virtual_account_payment": {
        "identifier": [
            {
                "name": "TRACE_NUMBER",
                "value": "19832"
            },
            {
                "name": "TRANSACTION_NUMBER",
                "value": "d094700e379f0fb3b543e25c77f8e4b3e068f057"
            },
            {
                "name": "HOST_REFERENCE_NUMBER",
                "value": ""
            }
        ]
    }
}
```

{% endtab %}

{% tab title="BRI VA" %}

```json
{
    "service": {
        "id": "VIRTUAL_ACCOUNT"
    },
    "acquirer": {
        "id": "BRI"
    },
    "channel": {
        "id": "VIRTUAL_ACCOUNT_BRI"
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2020-08-11T09:06:18Z",
        "original_request_id": "e5a8a8b8-7eab-4be3-91d8-5e2d7ab7cc25"
    },
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "virtual_account_info": {
        "virtual_account_number": "1236260000000004"
    },
    "virtual_account_payment": {
        "identifier": [
            {
                "name": "TRANSAKSI_ID",
                "value": "127503812"
            },
            {
                "name": "TERMINAL_ID",
                "value": "1"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="CIMB VA" %}

```json
{
    "service": {
        "id": "VIRTUAL_ACCOUNT"
    },
    "acquirer": {
        "id": "CIMB"
    },
    "channel": {
        "id": "VIRTUAL_ACCOUNT_BANK_CIMB"
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2020-08-11T09:06:18Z",
        "original_request_id": "e5a8a8b8-7eab-4be3-91d8-5e2d7ab7cc25"
    },
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "virtual_account_info": {
        "virtual_account_number": "1236260000000004"
    },
    "virtual_account_payment": {
        "identifier": [
            {
                "name": "TRANSAKSI_ID",
                "value": "127503812"
            },
            {
                "name": "TERMINAL_ID",
                "value": "1"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="Permata VA" %}

```json
{
    "service": {
        "id": "VIRTUAL_ACCOUNT"
    },
    "acquirer": {
        "id": "BANK_PERMATA"
    },
    "channel": {
        "id": "VIRTUAL_ACCOUNT_BANK_PERMATA"
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2020-08-11T09:06:18Z",
        "original_request_id": "e5a8a8b8-7eab-4be3-91d8-5e2d7ab7cc25"
    },
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "virtual_account_info": {
        "virtual_account_number": "1236260000000004"
    },
    "virtual_account_payment": {
        "identifier": [
            {
                "name": "TRANSAKSI_ID",
                "value": "127503812"
            },
            {
                "name": "TERMINAL_ID",
                "value": "1"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="BNI VA" %}

```json
{
    "order": {
        "invoice_number": "INV-1649674900",
        "amount": 20000
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2022-04-11T11:30:01Z",
        "original_request_id": "f1f95a6e-f2bf-4714-89c1-4f67a059c1f1"
    },
    "service": {
        "id": "VIRTUAL_ACCOUNT"
    },
    "acquirer": {
        "id": "BNI"
    },
    "channel": {
        "id": "VIRTUAL_ACCOUNT_BNI"
    },
    "virtual_account_info": {
        "virtual_account_number": "8803300000000388",
        "created_date": "20220411183001",
        "expired_date": "20220411190140",
        "reusable_status": false
    },
    "virtual_account_payment": {
        "identifier": [
            {
                "name": "TRX_ID",
                "value": "02871649035257909UNIQUE_00002"
            },
            {
                "name": "PAYMENT_NTB",
                "value": "577437"
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="VA Notification Explanation" %}

<table><thead><tr><th width="204.24609375">Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>service.id</code></td><td>string</td><td>Mandatory</td><td>The service that is used for the transaction</td></tr><tr><td><code>acquirer.id</code></td><td>string</td><td>Mandatory</td><td>The acquirer that processed the transaction</td></tr><tr><td><code>channel.id</code></td><td>string</td><td>Mandatory</td><td>The channel of the transaction</td></tr><tr><td><code>transaction.status</code></td><td>string</td><td>Mandatory</td><td>The transaction status to be use to update the status on merchant side<br>Possible value: <code>PENDING</code>, <code>SUCCESS</code>, <code>EXPIRED</code>, <code>FAILED</code></td></tr><tr><td><code>transaction.date</code></td><td>string</td><td>Optional</td><td>The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)</td></tr><tr><td><code>transaction.original_request_id</code></td><td>string</td><td>Mandatory</td><td>The request ID that sent when initiate the payment</td></tr><tr><td><code>order.invoice_number</code></td><td>string</td><td>Mandatory</td><td>The invoice number that sent when initate the payment</td></tr><tr><td><code>order.amount</code></td><td>string</td><td>Mandatory</td><td>The amount of the transaction</td></tr><tr><td><code>virtual_account_info.</code><br><code>virtual_account_number</code></td><td>string</td><td>Optional</td><td>The virtual account number that used for the transaction</td></tr><tr><td><code>virtual_account_info.</code><br><code>created_date</code></td><td>string</td><td>Optional</td><td>Date time of VA generated with the format of <code>yyyyMMddHHmmss</code>.</td></tr><tr><td><code>virtual_account_info.</code><br><code>expired_date</code></td><td>string</td><td>Optional</td><td>Date time of VA generated with the format of <code>yyyyMMddHHmmss</code>.</td></tr><tr><td><code>virtual_account_info.</code><br><code>reusable_status</code></td><td>string</td><td>Optional</td><td>Reusable status when initiate the payment</td></tr><tr><td><code>virtual_account_payment.identifier</code></td><td>array</td><td>Optional</td><td>List of transaction identifier that coming from the acquiring. Merchant can save these data for reference</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

### Convenience store

* Alfa
* Indomaret

The response will be similar to HTTP notification. Some parameters might not be presented in certain status cases, please check our Postman Collection to try it yourself.

{% tabs %}
{% tab title="Alfa" %}

```json
{
    "order": {
        "invoice_number": "INV-67220100000",
        "amount": 120000
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2021-12-29T02:37:35Z",
        "original_request_id": "INV-67220100000"
    },
    "service": {
        "id": "ONLINE_TO_OFFLINE"
    },
    "acquirer": {
        "id": "ALFA"
    },
    "channel": {
        "id": "ONLINE_TO_OFFLINE_ALFA"
    },
    "online_to_offline_info": {
        "created_date": "20211229093735",
        "expired_date": "20211229100732",
        "reusable_status": "false"
    },
    "online_to_offline_payment": {
        "identifier": [
            {
                "name": "AGENT_ID",
                "value": "ALFAMART"
            },
            {
                "name": "AGENT_STORE_ID",
                "value": "store"
            },
            {
                "name": "AGENT_TRX_ID",
                "value": "505045001763766906"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="Indomaret" %}

```json
{
    "order": {
        "invoice_number": "INV-1640746942",
        "amount": 150000
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2021-12-28T20:03:37Z",
        "original_request_id": "91c65738-4148-4862-8147-009728097e17"
    },
    "service": {
        "id": "ONLINE_TO_OFFLINE"
    },
    "acquirer": {
        "id": "INDOMARET"
    },
    "channel": {
        "id": "ONLINE_TO_OFFLINE_INDOMARET"
    },
    "online_to_offline_info": {
        "created_date": "20211229030337",
        "expired_date": "20211229040224",
        "reusable_status": false
    },
    "online_to_offline_payment": {
        "identifier": [
            {
                "name": "AGENT_ID",
                "value": "s0337180"
            },
            {
                "name": "MESSAGE_ID",
                "value": "messageId0337180"
            },
            {
                "name": "TRACKING_REF",
                "value": "tracking0337180"
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Alfa" %}
Alfa O2O Notification Explanation

| Parameter                                | Type     | Mandatory | Description                                                                                                                                                      |
| ---------------------------------------- | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`                   | `string` | Mandatory | The invoice number that sent when initate the payment                                                                                                            |
| `order.amount`                           | `string` | Mandatory | The amount of the transaction                                                                                                                                    |
| `transaction.status`                     | `string` | Mandatory | <p>The transaction status to be use to update the status on merchant side<br>Possible value: <code>SUCCESS</code>, <code>FAILED</code>, <code>TIMEOUT</code></p> |
| `transaction.date`                       | `string` | Mandatory | The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)                                                                          |
| `transaction.original_request_id`        | `string` | Mandatory | The request ID that sent when initiate the payment                                                                                                               |
| `service.id`                             | `string` | Mandatory | The service that is used for the transaction                                                                                                                     |
| `acquirer.id`                            | `string` | Mandatory | The acquirer that processed the transaction                                                                                                                      |
| `channel.id`                             | `string` | Mandatory | The channel of the transaction                                                                                                                                   |
| `jdm.journey_id`                         | `string` | Mandatory | Journey id for transaction                                                                                                                                       |
| `online_to_offline_info.created_date`    | `string` | Mandatory | Created date for Transaction                                                                                                                                     |
| `online_to_offline_info.expired_date`    | `string` | Mandatory | Expired date for Transaction                                                                                                                                     |
| `online_to_offline_info.reusable_status` | `string` | Mandatory | Reusable status for Payment Code                                                                                                                                 |
| `online_to_offline_payment.identifier`   | `array`  | Mandatory | Identifier for Transaction                                                                                                                                       |
| {% endtab %}                             |          |           |                                                                                                                                                                  |

{% tab title="Indomaret" %}
Indomaret O2O Notification Explanation

| Parameter                                | Type     | Mandatory | Description                                                                                                                                                      |
| ---------------------------------------- | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`                   | `string` | Mandatory | The invoice number that sent when initate the payment                                                                                                            |
| `order.amount`                           | `string` | Mandatory | The amount of the transaction                                                                                                                                    |
| `transaction.status`                     | `string` | Mandatory | <p>The transaction status to be use to update the status on merchant side<br>Possible value: <code>SUCCESS</code>, <code>FAILED</code>, <code>TIMEOUT</code></p> |
| `transaction.date`                       | `string` | Mandatory | The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)                                                                          |
| `transaction.original_request_id`        | `string` | Mandatory | The request ID that sent when initiate the payment                                                                                                               |
| `service.id`                             | `string` | Mandatory | The service that is used for the transaction                                                                                                                     |
| `acquirer.id`                            | `string` | Mandatory | The acquirer that processed the transaction                                                                                                                      |
| `channel.id`                             | `string` | Mandatory | The channel of the transaction                                                                                                                                   |
| `jdm.journey_id`                         | `string` | Mandatory | Journey id for transaction                                                                                                                                       |
| `online_to_offline_info.created_date`    | `string` | Mandatory | Created date for Transaction                                                                                                                                     |
| `online_to_offline_info.expired_date`    | `string` | Mandatory | Expired date for Transaction                                                                                                                                     |
| `online_to_offline_info.reusable_status` | `string` | Mandatory | Reusable status for Payment Code                                                                                                                                 |
| `online_to_offline_payment.identifier`   | `array`  | Mandatory | Identifier for Transaction                                                                                                                                       |
| {% endtab %}                             |          |           |                                                                                                                                                                  |
| {% endtabs %}                            |          |           |                                                                                                                                                                  |

### e-Wallet

* DANA
* ShopeePay
* DOKU e-Wallet
* OVO Push Payment
* OVO Recurring
* Link Aja

The response will be similar to HTTP notification. Some parameters might not be presented in certain status cases, please check our Postman Collection to try it yourself.

{% tabs %}
{% tab title="DANA" %}

```json
{
    "order": {
        "invoice_number": "INV-1724393502",
        "amount": 1.00
    },
    "transaction": {
        "status": "SUCCESS",
        "type": "SALE",
        "date": "2024-08-23T06:11:52Z",
        "original_request_id": "3348ca8d-f82b-41ce-aeb1-5d7efe8cf309",
        "service_code": "54"
    },
    "acquirer": {
        "id": "DANA",
        "name": "DANA Snap Direct Debit"
    },
    "channel": {
        "id": "EMONEY_DANA"
    },
    "additional_info": {
        "supportDeepLinkCheckoutUrl": "false",
        "origin": {
            "product": "CHECKOUT",
            "source": "direct",
            "system": "mid-jokul-checkout-system",
            "apiFormat": "JOKUL"
        },
        "line_items": [
            {
                "name": "Very Long Name Which Is Very Loooooong",
                "price": "1",
                "quantity": 1.0
            }
        ],
        "orderTitle": "INV-1724393502",
        "account": {
            "accountNo": "http://doku.com/",
            "accountName": "http://doku.com/"
        },
        "channelId": "http://doku.com/"
    },
    "emoney_payment": {
        "status": "PENDING",
        "date": "20240823131152",
        "approval_code": "v6GZT6pvyHh1basLKudYvkQbpVSs6dvvtbFijLdinbyBSgGdEpCsWmMdgsuYVoT7",
        "response_code": "2005400",
        "response_message": "Success"
    },
    "emoney_configuration": {
        "sub_merchant_id": "test"
    }
}
```

{% endtab %}

{% tab title="ShopeePay" %}

```json
{
    "order": {
        "invoice_number": "INV-testCheckStatusShopeepay",
        "amount": 80003
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2024-08-23T04:34:58Z",
        "original_request_id": "e9dacd5d-3a63-4776-ac4a-fec9eb4b71a6"
    },
    "acquirer": {
        "id": "SHOPEE_PAY",
        "name": "Shopee Pay"
    },
    "channel": {
        "id": "EMONEY_SHOPEE_PAY"
    },
    "additional_info": {
        "origin": {
            "source": "direct",
            "system": "mid-jokul-checkout-system",
            "product": "CHECKOUT",
            "apiFormat": "JOKUL"
        },
        "line_items": [
            {
                "sku": "FF01",
                "url": "http://item-url.domain/",
                "name": "Fresh flowers",
                "type": "ABC",
                "price": "40003",
                "category": "others",
                "quantity": 1.0,
                "image_url": "http://image-url.domain/"
            },
            {
                "sku": "T01",
                "url": "http://item-url.domain/",
                "name": "T-shirt",
                "type": "ABC",
                "price": "40000",
                "category": "others",
                "quantity": 1.0,
                "image_url": "http://image-url.domain/"
            }
        ],
        "allow_tenor": [
            0.0,
            3.0,
            6.0,
            12.0
        ],
        "doku_wallet_notify_url": "https://dw-notification.merchantdomain"
    },
    "shopeepay_payment": {
        "status": "SUCCESS",
        "date": "20240823113458",
        "identifier": [
            {
                "name": "PAYMENT_REFERENCE_ID",
                "value": "INV-testCheckStatusDANA"
            },
            {
                "name": "TRANSACTION_SN",
                "value": "7803086338142291260544613762532053068807260727842944261355953953"
            },
            {
                "name": "USER_ID_HASH",
                "value": "0272317754971626181110118654850459524546253866569833098069226095"
            }
        ]
    },
    "shopeepay_configuration": {
        "merchant_ext_id": "BRN-0234-1681288290275",
        "payment_return_url": "https://dashboard.doku.com/docs",
        "store_ext_id": "BRN-0234-1681288290275"
    }
}
```

{% endtab %}

{% tab title="OVO Push Payment" %}

```json
{
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2021-08-24T06:55:37Z",
        "original_request_id": "6503362"
    },
    "service": {
        "id": "EMONEY"
    },
    "acquirer": {
        "id": "OVO"
    },
    "channel": {
        "id": "EMONEY_OVO"
    },
    "ovo_payment": {
        "status": "SUCCESS",
        "date": "20210824135537",
        "batch_number": 195,
        "trace_number": 6503362,
        "reference_number": 10,
        "approval_code": "4318514",
        "response_code": "00",
        "cash_used": 150000,
        "cash_balance": 9850000,
        "ovo_points_used": 0,
        "ovo_points_balance": 10000000,
        "ovo_points_earned": 0
    },
    "ovo_configuration": {
        "merchant_id": "123456",
        "tid": "4562019",
        "mid": "Doku20191241234",
        "store_code": "Doku2019"
    },
    "ovo_info": {
        "ovo_account_name": "testing Doku",
        "ovo_id": "081211111111"
    }
}
```

{% endtab %}

{% tab title="OVO Recurring" %}

```json
Coming Soon
```

{% endtab %}

{% tab title="Link Aja" %}

```json
Coming Soon
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="DANA" %}

| Parameter                              | Type     | Mandatory   | Description                                                                                                                                         |
| -------------------------------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`                 | `string` | Mandatory   | Same as the request that merchant sent on the payment initiation                                                                                    |
| `order.amount`                         | `number` | Mandatory   | Same as the request that merchant sent on the payment initiation                                                                                    |
| `transaction.status`                   | `string` | Mandatory   | <p>The transaction status to be use to update the status on merchant side<br>Possible value: <code>SUCCESS, FAILED, PENDING,REFUNDED</code></p>     |
| `transaction.date`                     | `string` | Mandatory   | The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)                                                             |
| `transaction.service_code`             | string   | Optional    | Service Code                                                                                                                                        |
| `transaction.type`                     | `string` | Conditional | <p>Type for DANA transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>SALE</code></p> |
| `transaction.original_request_id`      | `string` | Mandatory   | The request ID that sent when initiate the payment                                                                                                  |
| `service.id`                           | `string` | Mandatory   | The service that is used for the transaction                                                                                                        |
| `acquirer.id`                          | `string` | Conditional | <p>The acquirer that processed the transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS.<br></p>                              |
| `channel.id`                           | `string` | Mandatory   | The channel of the transaction                                                                                                                      |
| `additional_info`                      | array    | Optional    |                                                                                                                                                     |
| `emoney_payment.status`                | `string` | Optional    | Status of the Payment                                                                                                                               |
| `emoney_payment.date`                  | `string` | Optional    | Date of the order                                                                                                                                   |
| `emoney_payment.approval_code`         | `string` | Optional    | Approval Code from DOKU                                                                                                                             |
| `emoney_payment.response_code`         | `string` | Optional    | Response code for the order                                                                                                                         |
| `emoney_payment.response_message`      | `string` | Optional    | Response message for the Order                                                                                                                      |
| `emoney_configuration.sub_merchant.id` | `string` | Optional    | Sub merchant ID                                                                                                                                     |
| {% endtab %}                           |          |             |                                                                                                                                                     |

{% tab title="Shopeepay" %}

| Parameter                                    | Type     | Mandatory   | Description                                                                                                                                         |
| -------------------------------------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`                       | `string` | Mandatory   | Same as the request that merchant sent on the payment initiation                                                                                    |
| `order.amount`                               | `number` | Mandatory   | Same as the request that merchant sent on the payment initiation                                                                                    |
| `transaction.status`                         | `string` | Mandatory   | <p>The transaction status to be use to update the status on merchant side<br>Possible value: <code>SUCCESS, FAILED, PENDING,REFUNDED</code></p>     |
| `transaction.date`                           | `string` | Mandatory   | The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)                                                             |
| `transaction.service_code`                   | string   | Optional    | Service Code                                                                                                                                        |
| `transaction.type`                           | `string` | Conditional | <p>Type for DANA transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>SALE</code></p> |
| `transaction.original_request_id`            | `string` | Mandatory   | The request ID that sent when initiate the payment                                                                                                  |
| `service.id`                                 | `string` | Mandatory   | The service that is used for the transaction                                                                                                        |
| `acquirer.id`                                | `string` | Conditional | <p>The acquirer that processed the transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS.<br></p>                              |
| `channel.id`                                 | `string` | Mandatory   | The channel of the transaction                                                                                                                      |
| `additional_info`                            | array    | Optional    |                                                                                                                                                     |
| `shopeepay_payment.status`                   | `string` | Optional    | Status of the Payment                                                                                                                               |
| `shopeepay_payment.date`                     | `string` | Optional    | Date of the order                                                                                                                                   |
| `shopeepay_payment.identifier`               | `string` | Optional    | Identifier for ShopeePay                                                                                                                            |
| `shopeepay_configuration.merchant_ext_id`    | `string` | Optional    | Merchant Ext Id                                                                                                                                     |
| `shopeepay_configuration.payment_return_url` | `string` | Optional    | Payment return URL                                                                                                                                  |
| `shopeepay_configuration.store_ext_id`       | `string` | Optional    | Store ext id                                                                                                                                        |
| {% endtab %}                                 |          |             |                                                                                                                                                     |

{% tab title="DOKU e-Wallet" %}

```
Coming Soon
```

{% endtab %}

{% tab title="OVO Push Payment" %}
OVO E-Money Check Status Explanation

| Parameter                         | Type     | Mandatory | Description                                                                                                                                                      |
| --------------------------------- | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`            | `string` | Mandatory | The invoice number that sent when initate the payment                                                                                                            |
| `order.amount`                    | `string` | Mandatory | The amount of the transaction                                                                                                                                    |
| `transaction.status`              | `string` | Mandatory | <p>The transaction status to be use to update the status on merchant side<br>Possible value: <code>SUCCESS</code>, <code>FAILED</code>, <code>TIMEOUT</code></p> |
| `transaction.date`                | `string` | Mandatory | The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)                                                                          |
| `transaction.original_request_id` | `string` | Mandatory | The request ID that sent when initiate the payment                                                                                                               |
| `service.id`                      | `string` | Mandatory | The service that is used for the transaction                                                                                                                     |
| `acquirer.id`                     | `string` | Mandatory | The acquirer that processed the transaction                                                                                                                      |
| `channel.id`                      | `string` | Mandatory | The channel of the transaction                                                                                                                                   |
| `ovo_payment.status`              | `string` | Mandatory | Payment status generated by DOKU                                                                                                                                 |
| `ovo_payment.date`                | `string` | Mandatory | Payment date generated by DOKU with the format of yyyyMMddHHmmss UTC+7 time                                                                                      |
| `ovo_payment.batch_number`        | `number` | Mandatory | Batch number of transaction for settlement. Value increment on daily basis, except if the Reference Number already reached maximum value                         |
| `ovo_payment.trace_number`        | `number` | Mandatory | <p>Generated by OVO<br>Max length: <code>6</code></p>                                                                                                            |
| `ovo_payment.reference_number`    | `number` | Mandatory | <p>Transaction ID for every transaction generated by OVO. Increment for each Push to Pay Transaction<br>Maximum value: <code>999999</code></p>                   |
| `ovo_payment.approval_code`       | `string` | Mandatory | Generated by OVO                                                                                                                                                 |
| `ovo_payment.response_code`       | `string` | Mandatory | Generated by OVO. Please refer to the section below for the `response_code` mapping                                                                              |
| `ovo_payment.cash_used`           | `number` | Optional  | OVO Cash that being charged for the transaction                                                                                                                  |
| `ovo_payment.cash_balance`        | `number` | Optional  | OVO Cash remaining balance after the transaction                                                                                                                 |
| `ovo_payment.ovo_points_used`     | `number` | Optional  | OVO Points that being charged for the transaction                                                                                                                |
| `ovo_payment.ovo_points_balance`  | `number` | Optional  | OVO Points remaining balance after the transaction                                                                                                               |
| `ovo_payment.ovo_points_earned`   | `number` | Optional  | OVO Points earned after the transaction                                                                                                                          |
| `ovo_configuration.merchant_id`   | `string` | Optional  | <p>Merchant ID by OVO<br>Allowed chars: <code>numeric</code><br>Max length: <code>7</code></p>                                                                   |
| `ovo_configuration.tid`           | `string` | Optional  | <p>TID by OVO<br>Allowed chars: <code>numeric</code><br>Max length: <code>8</code></p>                                                                           |
| `ovo_configuration.mid`           | `string` | Optional  | <p>MID by OVO<br>Allowed chars: <code>alphabetic, numeric</code><br>Max length: <code>15</code></p>                                                              |
| `ovo_configuration.store_code`    | `string` | Optional  | <p>Store code by OVO Allowed chars: <code>alphabetic, numeric</code><br>Max length: <code>15</code></p>                                                          |
| `ovo_info.ovo_account_name`       | `string` | Optional  | Name of the OVO customer                                                                                                                                         |
| `ovo_info.ovo_id`                 | `string` | Mandatory | ID for OVO phone number to do payment                                                                                                                            |
| {% endtab %}                      |          |           |                                                                                                                                                                  |

{% tab title="OVO Recurring" %}

```
Coming Soon
```

{% endtab %}

{% tab title="Link Aja" %}

```
Coming Soon
```

{% endtab %}
{% endtabs %}

### Direct Debit

{% tabs %}
{% tab title="BRI" %}

```json
{
    "order": {
        "amount": 500000,
        "invoice_number":"INV-20210217-0003"
    },
    "channel":{
        "id":"DIRECT_DEBIT_BRI"
    },
    "service":{
        "id":"DIRECT_DEBIT"
    },
    "acquirer":{
        "id":"BRI"
    },
    "transaction":{
        "date":"2021-02-17T09:50:17.235078",
        "status":"SUCCESS",
        "original_request_id":"20210217095009645"
    },
    "card_payment":{
        "payment_id":"432828221538",
        "response_code":"0000",
        "response_message":"SUCCESS",
        "masked_card_number":"************8232"
    }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="BRI" %}
Direct Debit Notification Explanation

| Parameter                         | Type     | Mandatory | Description                                                                                                                   |
| --------------------------------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`            | `string` | Mandatory | Same as the request that merchant sent on the payment initiation                                                              |
| `order.amount`                    | `number` | Mandatory | Same as the request that merchant sent on the payment initiation                                                              |
| `transaction.status`              | `string` | Mandatory | <p>The transaction status to be use to update the status on merchant side<br>Possible value: <code>SUCCESS, FAILED</code></p> |
| `transaction.date`                | `string` | Mandatory | The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)                                       |
| `transaction.original_request_id` | `string` | Mandatory | The request ID that sent when initiate the payment                                                                            |
| `service.id`                      | `string` | Mandatory | The service that is used for the transaction                                                                                  |
| `acquirer.id`                     | `string` | Mandatory | The acquirer that processed the transaction                                                                                   |
| `channel.id`                      | `string` | Mandatory | The channel of the transaction                                                                                                |
| `card_payment.masked_card_number` | `string` | Optional  | The masked card number that charged for this transaction                                                                      |
| `card_payment.payment_id`         | `string` | Optional  | The token that will be use for this transaction                                                                               |
| `card_payment.response_code`      | `string` | Optional  | <p>DOKU / Acquirer response code<br>Possible value: see here</p>                                                              |
| `card_payment.response_message`   | `string` | Optional  | <p>DOKU / Acquirer response code<br>Possible value: see here</p>                                                              |
| {% endtab %}                      |          |           |                                                                                                                               |
| {% endtabs %}                     |          |           |                                                                                                                               |

### Cards

The response will be similar to HTTP notification. Some parameters might not be presented in certain status cases, please check our Postman Collection to try it yourself.

{% tabs %}
{% tab title="Sale" %}

```json
{
    "order": {
        "invoice_number": "INV-1781838439",
        "amount": 102,
        "currency": "IDR"
    },
    "transaction": {
        "status": "SUCCESS",
        "type": "SALE",
        "date": "2026-06-19T03:15:26Z",
        "original_request_id": "a7b6b92b-e553-4810-8b46-945270b732ea"
    },
    "service": {
        "id": "CREDIT_CARD"
    },
    "acquirer": {
        "id": "BANK_CIMB",
        "name": "PT BANK CIMB NIAGA Tbk"
    },
    "channel": {
        "id": "CREDIT_CARD"
    },
    "additional_info": {
        "origin": {
            "product": "CHECKOUT",
            "system": "mid-jokul-checkout-system",
            "api_format": "JOKUL",
            "source": "direct"
        },
        "line_items": [
            {
                "quantity": 1.0,
                "price": "102",
                "name": "DOKU T-Shirt"
            }
        ]
    },
    "card_payment": {
        "card_masked": "539371******3085",
        "approval_code": "679870",
        "response_code": "00",
        "response_message": "Approved",
        "type": "SALE",
        "acquiring_off_us_status": "TRUE",
        "request_id": "a7b6b92b-e553-4810-8b46-945270b732ea",
        "card_type": "Debit",
        "card_holder_name": "Anton Budiman",
        "three_dsecure_status": "TRUE",
        "issuer": "PT BANK CENTRAL ASIA Tbk",
        "transaction_status": "SUCCESS",
        "brand": "MASTER",
        "date": "2026-06-19T03:15:26Z",
        "identifier": [
            {
                "name": "Acquirer",
                "value": "BANK_CIMB"
            },
            {
                "name": "MID",
                "value": "CN910090481"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="Recurring" %}

```json
{
    "order": {
        "invoice_number": "INV-1645668870",
        "amount": 90000
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2022-02-24T02:15:05Z",
        "type": "RECURRING",
        "original_request_id": "091773eb-a482-408d-949d-73281d91f610"
    },
    "service": {
        "id": "CREDIT_CARD"
    },
    "acquirer": {
        "id": "BANK_MANDIRI"
    },
    "channel": {
        "id": "CREDIT_CARD"
    },
    "card_payment": {
        "card_masked": "461700*******6656",
        "approval_code": "194462",
        "response_code": "00",
        "response_message": "PAYMENT APPROVED",
        "type": "RECURRING",
        "acquiring_off_us_status": "FALSE",
        "request_id": "091773eb-a482-408d-949d-73281d91f610",
        "card_type": "Debit",
        "three_dsecure_status": "TRUE",
        "issuer": "PT. BANK MANDIRI (PERSERO), Tbk",
        "transaction_status": "SUCCESS",
        "brand": "VISA",
        "date": "2022-02-24T02:15:05Z"

    }
}
```

{% endtab %}

{% tab title="Authorize" %}

```json
{
    "order": {
        "invoice_number": "INV-1645668870",
        "amount": 90000
    },
    "transaction": {
        "status": "PENDING",
        "date": "2022-02-24T02:15:05Z",
        "type": "AUTHORIZE",
        "original_request_id": "091773eb-a482-408d-949d-73281d91f610"
    },
    "service": {
        "id": "CREDIT_CARD"
    },
    "acquirer": {
        "id": "BANK_MANDIRI"
    },
    "channel": {
        "id": "CREDIT_CARD"
    },
    "card_payment": {
        "card_masked": "461700*******6656",
        "approval_code": "194462",
        "response_code": "00",
        "response_message": "PAYMENT APPROVED",
        "type": "AUTHORIZE",
        "acquiring_off_us_status": "FALSE",
        "request_id": "091773eb-a482-408d-949d-73281d91f610",
        "card_type": "Debit",
        "three_dsecure_status": "TRUE",
        "issuer": "PT. BANK MANDIRI (PERSERO), Tbk",
        "transaction_status": "SUCCESS",
        "brand": "VISA",
        "date": "2022-02-24T02:15:05Z",
        "authorize_id": "16837980314548456",
        "authentication_id": "baf706e020fa7cf89be687dbac665f1657def6629331716555974ff926013acb",

    }
}
```

{% endtab %}

{% tab title="Capture" %}

```json
{
    "order": {
        "invoice_number": "INV-1645668870",
        "amount": 90000
    },
    "transaction": {
        "status": "SUCCESS",
        "date": "2022-02-24T02:15:05Z",
        "type": "CAPTURE",
        "original_request_id": "091773eb-a482-408d-949d-73281d91f610"
    },
    "service": {
        "id": "CREDIT_CARD"
    },
    "acquirer": {
        "id": "BANK_MANDIRI"
    },
    "channel": {
        "id": "CREDIT_CARD"
    },
    "card_payment": {
        "card_masked": "461700*******6656",
        "approval_code": "194462",
        "response_code": "00",
        "response_message": "PAYMENT APPROVED",
        "type": "CAPTURE",
        "acquiring_off_us_status": "FALSE",
        "request_id": "091773eb-a482-408d-949d-73281d91f610",
        "card_type": "Debit",
        "three_dsecure_status": "TRUE",
        "issuer": "PT. BANK MANDIRI (PERSERO), Tbk",
        "transaction_status": "SUCCESS",
        "brand": "VISA",
        "date": "2022-02-24T02:15:05Z"
        "authorize_id": "16837980314548456",
    }
}
```

{% endtab %}

{% tab title="Full Refund" %}

```jsonc
{
    "order": {
        "invoice_number": "INV-1779354118",
        "amount": 101,
        "currency": "IDR"
    },
    "transaction": {
        "status": "REFUNDED",
        "type": "FULL_REFUND",
        "date": "2026-05-25T03:04:40Z",
        "original_request_id": "BO-20011"
    },
    "service": {
        "id": "CREDIT_CARD"
    },
    "acquirer": {
        "id": "BANK_MANDIRI",
        "name": "PT BANK MANDIRI (PERSERO) Tbk"
    },
    "channel": {
        "id": "CREDIT_CARD"
    },
    "card_payment": {
        "card_masked": "455633******8800",
        "approval_code": "041877",
        "response_code": "00",
        "response_message": "Transaction Has Been Successfully Refund",
        "type": "FULL_REFUND",
        "acquiring_off_us_status": "TRUE",
        "request_id": "BO-20011",
        "card_type": "Credit",
        "three_dsecure_status": "FALSE",
        "issuer": "PT BANK CENTRAL ASIA Tbk",
        "transaction_status": "SUCCESS",
        "brand": "VISA",
        "date": "2026-05-25T03:04:40Z",
        "identifier": [
            {
                "name": "MID",
                "value": "71000212170"
            },
            {
                "name": "Acquirer",
                "value": "BANK_MANDIRI"
            },
            {
                "name": "TID",
                "value": "73023702"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="Partial Refund" %}

```json
{
    "order": {
        "invoice_number": "cybersource_authorize_visa_off_us_014",
        "amount": 1000,
        "currency": "IDR"
    },
    "transaction": {
        "status": "PARTIAL_REFUNDED",
        "type": "PARTIAL_REFUND",
        "date": "2025-08-14T08:12:35Z",
        "original_request_id": "BO-796109",
        "amount": "500"
    },
    "service": {
        "id": "CREDIT_CARD"
    },
    "acquirer": {
        "id": "BNI",
        "name": "PT BANK NEGARA INDONESIA (PERSERO) Tbk"
    },
    "channel": {
        "id": "CREDIT_CARD"
    },
    "card_payment": {
        "card_masked": "455633******4805",
        "response_message": "Transaction Has Been Successfully Refund",
        "type": "PARTIAL_REFUND",
        "acquiring_off_us_status": "TRUE",
        "request_id": "BO-796109",
        "card_type": "Credit",
        "three_dsecure_status": "FALSE",
        "issuer": "PT BANK CENTRAL ASIA Tbk",
        "transaction_status": "SUCCESS",
        "brand": "VISA",
        "date": "2025-08-14T08:12:35Z",
        "identifier": [
            {
                "name": "MID",
                "value": "018033035"
            },
            {
                "name": "TID",
                "value": "01803503"
            }
        ]
    },
    "refund": {
        "amount": "500"
    }
}
```

{% endtab %}

{% tab title="Void" %}

```json
{
    "order": {
        "invoice_number": "domain_expansion_unlimited_void",
        "amount": 1000,
        "currency": "IDR"
    },
    "transaction": {
        "status": "VOIDED",
        "type": "VOID",
        "date": "2025-08-15T04:43:20Z",
        "original_request_id": "BO-571414",
        "amount": "1000"
    },
    "service": {
        "id": "CREDIT_CARD"
    },
    "acquirer": {
        "id": "BNI",
        "name": "PT BANK NEGARA INDONESIA (PERSERO) Tbk"
    },
    "channel": {
        "id": "CREDIT_CARD"
    },
    "card_payment": {
        "card_masked": "557692******0398",
        "response_message": "Transaction Has Been Successfully Void",
        "type": "VOID",
        "acquiring_off_us_status": "TRUE",
        "request_id": "BO-571414",
        "card_type": "Debit",
        "three_dsecure_status": "FALSE",
        "issuer": "PT BANK CIMB NIAGA Tbk",
        "transaction_status": "SUCCESS",
        "brand": "MASTER",
        "date": "2025-08-15T04:43:20Z",
        "identifier": [
            {
                "name": "MID",
                "value": "018033035"
            },
            {
                "name": "TID",
                "value": "01803503"
            }
        ]
    },
    "refund": {
        "amount": "1000"
    }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Sale" %}

| Parameter                              | Type     | Mandatory   | Description                                                                                                                                                                                                                                                                                 |
| -------------------------------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`                 | `string` | Mandatory   | Same as the request that merchant sent on the payment initiation                                                                                                                                                                                                                            |
| `order.amount`                         | `number` | Mandatory   | Same as the request that merchant sent on the payment initiation                                                                                                                                                                                                                            |
| `order.currency`                       | `string` | Mandatory   |                                                                                                                                                                                                                                                                                             |
| `transaction.status`                   | `string` | Mandatory   | <p>The transaction status to be use to update the status on merchant side<br>Possible value: <code>FAILED</code>, <br><code>PARTIAL\_REFUNDED</code>, <br><code>PENDING</code>, <br><code>REDIRECT</code>, <br><code>REFUNDED</code>, <br><code>SUCCESS</code>, <br><code>VOIDED</code></p> |
| `transaction.date`                     | `string` | Mandatory   | The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)                                                                                                                                                                                                     |
| `transaction.type`                     | `string` | Conditional | <p>Type for Credit Card Transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>SALE, INSTALLMENT, MOTO, AUTHORIZE, CAPTURE, RECURRING, REFUND</code></p>                                                                        |
| `transaction.original_request_id`      | `string` | Mandatory   | The request ID that sent when initiate the payment                                                                                                                                                                                                                                          |
| `service.id`                           | `string` | Mandatory   | The service that is used for the transaction                                                                                                                                                                                                                                                |
| `acquirer.id`                          | `string` | Conditional | <p>The acquirer that processed the transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS.<br></p>                                                                                                                                                                      |
| `channel.id`                           | `string` | Mandatory   | The channel of the transaction                                                                                                                                                                                                                                                              |
| `card_payment.card_masked`             | `string` | Conditional | <p>The masked card number that charged for this transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                               |
| `card_payment.approval_code`           | `string` | Conditional | <p>Acquirer approval code for this transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                            |
| `card_payment.response_code`           | `string` | Conditional | <p>Acquirer response code.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                 |
| `card_payment.response_message`        | `string` | Conditional | <p>Acquirer response code<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                  |
| `card_payment.type`                    | `string` | Conditional | <p>Type for Credit Card Transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>SALE, INSTALLMENT, MOTO, AUTHORIZE, CAPTURE, RECURRING, REFUND</code></p>                                                                        |
| `card_payment.acquiring_off_us_status` | `string` | Mandatory   | <p>Payment acquiring\_off\_us\_status<br>Possible value: <code>true, false</code></p>                                                                                                                                                                                                       |
| `card_payment.request_id`              | `string` | Mandatory   | Request ID for transaction                                                                                                                                                                                                                                                                  |
| `card_payment.card_type`               | `string` | Conditional | <p>Card type.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>CREDIT, DEBIT</code></p>                                                                                                                                                |
| `card_payment.three_dsecure_status`    | `string` | Optional    | <p>Three dsecure status<br>Possible value: <code>TRUE, FALSE</code></p>                                                                                                                                                                                                                     |
| `card_payment.issuer`                  | `string` | Conditional | <p>Card issuer.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                            |
| `card_payment.transaction_status`      | `string` | Mandatory   | <p>Transaction status<br>Possible value: <code>SUCCESS, FAILED, PENDING</code></p>                                                                                                                                                                                                          |
| `card_payment.brand`                   | `string` | Conditional | <p>Card brand.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                             |
| `card_payment.date`                    | `string` | Optional    | Transaction card date                                                                                                                                                                                                                                                                       |
| `card_payment.authorize_id`            | `string` | Optional    | Transaction authorize ID                                                                                                                                                                                                                                                                    |
| `card_payment.authentication_id`       | `string` | Optional    | Transaction authentication ID                                                                                                                                                                                                                                                               |
| additionalInfo                         | `object` | Optional    | Object that you pass through in additional\_info during payment will be forwarded here, and some other additional object from DOKU                                                                                                                                                          |
| {% endtab %}                           |          |             |                                                                                                                                                                                                                                                                                             |

{% tab title="Recurring" %}

| Parameter                              | Type     | Mandatory   | Description                                                                                                                                                                                                                                                                                 |
| -------------------------------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`                 | `string` | Mandatory   | Same as the request that merchant sent on the payment initiation                                                                                                                                                                                                                            |
| `order.amount`                         | `number` | Mandatory   | Same as the request that merchant sent on the payment initiation                                                                                                                                                                                                                            |
| `order.currency`                       | `string` | Mandatory   |                                                                                                                                                                                                                                                                                             |
| `transaction.status`                   | `string` | Mandatory   | <p>The transaction status to be use to update the status on merchant side<br>Possible value: <code>FAILED</code>, <br><code>PARTIAL\_REFUNDED</code>, <br><code>PENDING</code>, <br><code>REDIRECT</code>, <br><code>REFUNDED</code>, <br><code>SUCCESS</code>, <br><code>VOIDED</code></p> |
| `transaction.date`                     | `string` | Mandatory   | The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)                                                                                                                                                                                                     |
| `transaction.type`                     | `string` | Conditional | <p>Type for Credit Card Transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>SALE, INSTALLMENT, MOTO, AUTHORIZE, CAPTURE, RECURRING, REFUND</code></p>                                                                        |
| `transaction.original_request_id`      | `string` | Mandatory   | The request ID that sent when initiate the payment                                                                                                                                                                                                                                          |
| `service.id`                           | `string` | Mandatory   | The service that is used for the transaction                                                                                                                                                                                                                                                |
| `acquirer.id`                          | `string` | Conditional | <p>The acquirer that processed the transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS.<br></p>                                                                                                                                                                      |
| `channel.id`                           | `string` | Mandatory   | The channel of the transaction                                                                                                                                                                                                                                                              |
| `card_payment.card_masked`             | `string` | Conditional | <p>The masked card number that charged for this transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                               |
| `card_payment.approval_code`           | `string` | Conditional | <p>Acquirer approval code for this transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                            |
| `card_payment.response_code`           | `string` | Conditional | <p>Acquirer response code.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                 |
| `card_payment.response_message`        | `string` | Conditional | <p>Acquirer response code<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                  |
| `card_payment.type`                    | `string` | Conditional | <p>Type for Credit Card Transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>SALE, INSTALLMENT, MOTO, AUTHORIZE, CAPTURE, RECURRING, REFUND</code></p>                                                                        |
| `card_payment.acquiring_off_us_status` | `string` | Mandatory   | <p>Payment acquiring\_off\_us\_status<br>Possible value: <code>true, false</code></p>                                                                                                                                                                                                       |
| `card_payment.request_id`              | `string` | Mandatory   | Request ID for transaction                                                                                                                                                                                                                                                                  |
| `card_payment.card_type`               | `string` | Conditional | <p>Card type.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>CREDIT, DEBIT</code></p>                                                                                                                                                |
| `card_payment.three_dsecure_status`    | `string` | Optional    | <p>Three dsecure status<br>Possible value: <code>TRUE, FALSE</code></p>                                                                                                                                                                                                                     |
| `card_payment.issuer`                  | `string` | Conditional | <p>Card issuer.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                            |
| `card_payment.transaction_status`      | `string` | Mandatory   | <p>Transaction status<br>Possible value: <code>SUCCESS, FAILED, PENDING</code></p>                                                                                                                                                                                                          |
| `card_payment.brand`                   | `string` | Conditional | <p>Card brand.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                             |
| `card_payment.date`                    | `string` | Optional    | Transaction card date                                                                                                                                                                                                                                                                       |
| `card_payment.authorize_id`            | `string` | Optional    | Transaction authorize ID, needed to Capture the transaction                                                                                                                                                                                                                                 |
| `card_payment.authentication_id`       | `string` | Optional    | Transaction authentication ID, needed to charge the transaction if Host-to-Host API is used.                                                                                                                                                                                                |
| {% endtab %}                           |          |             |                                                                                                                                                                                                                                                                                             |

{% tab title="Authorize" %}

| Parameter                              | Type     | Mandatory   | Description                                                                                                                                                                                                                                                                                 |
| -------------------------------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`                 | `string` | Mandatory   | Same as the request that merchant sent on the payment initiation                                                                                                                                                                                                                            |
| `order.amount`                         | `number` | Mandatory   | Same as the request that merchant sent on the payment initiation                                                                                                                                                                                                                            |
| `order.currency`                       | `string` | Mandatory   |                                                                                                                                                                                                                                                                                             |
| `transaction.status`                   | `string` | Mandatory   | <p>The transaction status to be use to update the status on merchant side<br>Possible value: <code>FAILED</code>, <br><code>PARTIAL\_REFUNDED</code>, <br><code>PENDING</code>, <br><code>REDIRECT</code>, <br><code>REFUNDED</code>, <br><code>SUCCESS</code>, <br><code>VOIDED</code></p> |
| `transaction.date`                     | `string` | Mandatory   | The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)                                                                                                                                                                                                     |
| `transaction.type`                     | `string` | Conditional | <p>Type for Credit Card Transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>SALE, INSTALLMENT, MOTO, AUTHORIZE, CAPTURE, RECURRING, REFUND</code></p>                                                                        |
| `transaction.original_request_id`      | `string` | Mandatory   | The request ID that sent when initiate the payment                                                                                                                                                                                                                                          |
| `service.id`                           | `string` | Mandatory   | The service that is used for the transaction                                                                                                                                                                                                                                                |
| `acquirer.id`                          | `string` | Conditional | <p>The acquirer that processed the transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS.<br></p>                                                                                                                                                                      |
| `channel.id`                           | `string` | Mandatory   | The channel of the transaction                                                                                                                                                                                                                                                              |
| `card_payment.card_masked`             | `string` | Conditional | <p>The masked card number that charged for this transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                               |
| `card_payment.approval_code`           | `string` | Conditional | <p>Acquirer approval code for this transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                            |
| `card_payment.response_code`           | `string` | Conditional | <p>Acquirer response code.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                 |
| `card_payment.response_message`        | `string` | Conditional | <p>Acquirer response code<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                  |
| `card_payment.type`                    | `string` | Conditional | <p>Type for Credit Card Transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>SALE, INSTALLMENT, MOTO, AUTHORIZE, CAPTURE, RECURRING, REFUND</code></p>                                                                        |
| `card_payment.acquiring_off_us_status` | `string` | Mandatory   | <p>Payment acquiring\_off\_us\_status<br>Possible value: <code>true, false</code></p>                                                                                                                                                                                                       |
| `card_payment.request_id`              | `string` | Mandatory   | Request ID for transaction                                                                                                                                                                                                                                                                  |
| `card_payment.card_type`               | `string` | Conditional | <p>Card type.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>CREDIT, DEBIT</code></p>                                                                                                                                                |
| `card_payment.three_dsecure_status`    | `string` | Optional    | <p>Three dsecure status<br>Possible value: <code>TRUE, FALSE</code></p>                                                                                                                                                                                                                     |
| `card_payment.issuer`                  | `string` | Conditional | <p>Card issuer.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                            |
| `card_payment.transaction_status`      | `string` | Mandatory   | <p>Transaction status<br>Possible value: <code>SUCCESS, FAILED, PENDING</code></p>                                                                                                                                                                                                          |
| `card_payment.brand`                   | `string` | Conditional | <p>Card brand.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                             |
| `card_payment.date`                    | `string` | Optional    | Transaction card date                                                                                                                                                                                                                                                                       |
| `card_payment.authorize_id`            | `string` | Optional    | Transaction authorize ID                                                                                                                                                                                                                                                                    |
| `card_payment.authentication_id`       | `string` | Optional    | Transaction authentication ID                                                                                                                                                                                                                                                               |
| {% endtab %}                           |          |             |                                                                                                                                                                                                                                                                                             |

{% tab title="Capture" %}

| Parameter                              | Type     | Mandatory   | Description                                                                                                                                                                                                                                                                                 |
| -------------------------------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`                 | `string` | Mandatory   | Same as the request that merchant sent on the payment initiation                                                                                                                                                                                                                            |
| `order.amount`                         | `number` | Mandatory   | Same as the request that merchant sent on the payment initiation                                                                                                                                                                                                                            |
| `transaction.status`                   | `string` | Mandatory   | <p>The transaction status to be use to update the status on merchant side<br>Possible value: <code>FAILED</code>, <br><code>PARTIAL\_REFUNDED</code>, <br><code>PENDING</code>, <br><code>REDIRECT</code>, <br><code>REFUNDED</code>, <br><code>SUCCESS</code>, <br><code>VOIDED</code></p> |
| `transaction.date`                     | `string` | Mandatory   | The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)                                                                                                                                                                                                     |
| `transaction.type`                     | `string` | Conditional | <p>Type for Credit Card Transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>SALE, INSTALLMENT, MOTO, AUTHORIZE, CAPTURE, RECURRING, REFUND</code></p>                                                                        |
| `transaction.original_request_id`      | `string` | Mandatory   | The request ID that sent when initiate the payment                                                                                                                                                                                                                                          |
| `service.id`                           | `string` | Mandatory   | The service that is used for the transaction                                                                                                                                                                                                                                                |
| `acquirer.id`                          | `string` | Conditional | <p>The acquirer that processed the transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS.<br></p>                                                                                                                                                                      |
| `channel.id`                           | `string` | Mandatory   | The channel of the transaction                                                                                                                                                                                                                                                              |
| `card_payment.card_masked`             | `string` | Conditional | <p>The masked card number that charged for this transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                               |
| `card_payment.approval_code`           | `string` | Conditional | <p>Acquirer approval code for this transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                            |
| `card_payment.response_code`           | `string` | Conditional | <p>Acquirer response code.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                 |
| `card_payment.response_message`        | `string` | Conditional | <p>Acquirer response code<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                  |
| `card_payment.type`                    | `string` | Conditional | <p>Type for Credit Card Transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>SALE, INSTALLMENT, MOTO, AUTHORIZE, CAPTURE, RECURRING, REFUND</code></p>                                                                        |
| `card_payment.acquiring_off_us_status` | `string` | Mandatory   | <p>Payment acquiring\_off\_us\_status<br>Possible value: <code>true, false</code></p>                                                                                                                                                                                                       |
| `card_payment.request_id`              | `string` | Mandatory   | Request ID for transaction                                                                                                                                                                                                                                                                  |
| `card_payment.card_type`               | `string` | Conditional | <p>Card type.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>CREDIT, DEBIT</code></p>                                                                                                                                                |
| `card_payment.three_dsecure_status`    | `string` | Optional    | <p>Three dsecure status<br>Possible value: <code>TRUE, FALSE</code></p>                                                                                                                                                                                                                     |
| `card_payment.issuer`                  | `string` | Conditional | <p>Card issuer.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                            |
| `card_payment.transaction_status`      | `string` | Mandatory   | <p>Transaction status<br>Possible value: <code>SUCCESS, FAILED, PENDING</code></p>                                                                                                                                                                                                          |
| `card_payment.brand`                   | `string` | Conditional | <p>Card brand.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                             |
| `card_payment.date`                    | `string` | Optional    | Transaction card date                                                                                                                                                                                                                                                                       |
| `card_payment.authorize_id`            | `string` | Optional    | Transaction authorize ID                                                                                                                                                                                                                                                                    |
| `card_payment.authentication_id`       | `string` | Optional    | Transaction authentication ID                                                                                                                                                                                                                                                               |
| {% endtab %}                           |          |             |                                                                                                                                                                                                                                                                                             |

{% tab title="Full Refund" %}

| Parameter                              | Type     | Mandatory   | Description                                                                                                                                                                                                                                                                                 |
| -------------------------------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`                 | `string` | Mandatory   | Same as the request that merchant sent on the payment initiation                                                                                                                                                                                                                            |
| `order.amount`                         | `number` | Mandatory   | Same as the request that merchant sent on the payment initiation                                                                                                                                                                                                                            |
| `order.currency`                       | `string` | Mandatory   |                                                                                                                                                                                                                                                                                             |
| `transaction.status`                   | `string` | Mandatory   | <p>The transaction status to be use to update the status on merchant side<br>Possible value: <code>FAILED</code>, <br><code>PARTIAL\_REFUNDED</code>, <br><code>PENDING</code>, <br><code>REDIRECT</code>, <br><code>REFUNDED</code>, <br><code>SUCCESS</code>, <br><code>VOIDED</code></p> |
| `transaction.date`                     | `string` | Mandatory   | The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)                                                                                                                                                                                                     |
| `transaction.type`                     | `string` | Conditional | <p>Type for Credit Card Transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>SALE, INSTALLMENT, MOTO, AUTHORIZE, CAPTURE, RECURRING, REFUND</code></p>                                                                        |
| `transaction.original_request_id`      | `string` | Mandatory   | The request ID that sent when initiate the payment                                                                                                                                                                                                                                          |
| `service.id`                           | `string` | Mandatory   | The service that is used for the transaction                                                                                                                                                                                                                                                |
| `acquirer.id`                          | `string` | Conditional | <p>The acquirer that processed the transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS.<br></p>                                                                                                                                                                      |
| `channel.id`                           | `string` | Mandatory   | The channel of the transaction                                                                                                                                                                                                                                                              |
| `card_payment.card_masked`             | `string` | Conditional | <p>The masked card number that charged for this transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                               |
| `card_payment.approval_code`           | `string` | Conditional | <p>Acquirer approval code for this transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                            |
| `card_payment.response_code`           | `string` | Conditional | <p>Acquirer response code.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                 |
| `card_payment.response_message`        | `string` | Conditional | <p>Acquirer response code<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                  |
| `card_payment.type`                    | `string` | Conditional | <p>Type for Credit Card Transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>SALE, INSTALLMENT, MOTO, AUTHORIZE, CAPTURE, RECURRING, REFUND</code></p>                                                                        |
| `card_payment.acquiring_off_us_status` | `string` | Mandatory   | <p>Payment acquiring\_off\_us\_status<br>Possible value: <code>true, false</code></p>                                                                                                                                                                                                       |
| `card_payment.request_id`              | `string` | Mandatory   | Request ID for transaction                                                                                                                                                                                                                                                                  |
| `card_payment.card_type`               | `string` | Conditional | <p>Card type.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>CREDIT, DEBIT</code></p>                                                                                                                                                |
| `card_payment.three_dsecure_status`    | `string` | Optional    | <p>Three dsecure status<br>Possible value: <code>TRUE, FALSE</code></p>                                                                                                                                                                                                                     |
| `card_payment.issuer`                  | `string` | Conditional | <p>Card issuer.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                            |
| `card_payment.transaction_status`      | `string` | Mandatory   | <p>Transaction status<br>Possible value: <code>SUCCESS, FAILED, PENDING</code></p>                                                                                                                                                                                                          |
| `card_payment.brand`                   | `string` | Conditional | <p>Card brand.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                             |
| `card_payment.date`                    | `string` | Optional    | Transaction card date                                                                                                                                                                                                                                                                       |
| `card_payment.authorize_id`            | `string` | Optional    | Transaction authorize ID                                                                                                                                                                                                                                                                    |
| `card_payment.authentication_id`       | `string` | Optional    | Transaction authentication ID                                                                                                                                                                                                                                                               |
| {% endtab %}                           |          |             |                                                                                                                                                                                                                                                                                             |

{% tab title="Partial Refund" %}

| Parameter                              | Type     | Mandatory   | Description                                                                                                                                                                                                                                                                                 |
| -------------------------------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`                 | `string` | Mandatory   | Same as the request that merchant sent on the payment initiation                                                                                                                                                                                                                            |
| `order.amount`                         | `number` | Mandatory   | Same as the request that merchant sent on the payment initiation                                                                                                                                                                                                                            |
| `order.currency`                       | `string` | Mandatory   |                                                                                                                                                                                                                                                                                             |
| `transaction.status`                   | `string` | Mandatory   | <p>The transaction status to be use to update the status on merchant side<br>Possible value: <code>FAILED</code>, <br><code>PARTIAL\_REFUNDED</code>, <br><code>PENDING</code>, <br><code>REDIRECT</code>, <br><code>REFUNDED</code>, <br><code>SUCCESS</code>, <br><code>VOIDED</code></p> |
| `transaction.date`                     | `string` | Mandatory   | The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)                                                                                                                                                                                                     |
| `transaction.type`                     | `string` | Conditional | <p>Type for Credit Card Transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>SALE, INSTALLMENT, MOTO, AUTHORIZE, CAPTURE, RECURRING, REFUND</code></p>                                                                        |
| `transaction.original_request_id`      | `string` | Mandatory   | The request ID that sent when initiate the payment                                                                                                                                                                                                                                          |
| `service.id`                           | `string` | Mandatory   | The service that is used for the transaction                                                                                                                                                                                                                                                |
| `acquirer.id`                          | `string` | Conditional | <p>The acquirer that processed the transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS.<br></p>                                                                                                                                                                      |
| `channel.id`                           | `string` | Mandatory   | The channel of the transaction                                                                                                                                                                                                                                                              |
| `card_payment.card_masked`             | `string` | Conditional | <p>The masked card number that charged for this transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                               |
| `card_payment.approval_code`           | `string` | Conditional | <p>Acquirer approval code for this transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                            |
| `card_payment.response_code`           | `string` | Conditional | <p>Acquirer response code.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                 |
| `card_payment.response_message`        | `string` | Conditional | <p>Acquirer response code<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                  |
| `card_payment.type`                    | `string` | Conditional | <p>Type for Credit Card Transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>SALE, INSTALLMENT, MOTO, AUTHORIZE, CAPTURE, RECURRING, REFUND</code></p>                                                                        |
| `card_payment.acquiring_off_us_status` | `string` | Mandatory   | <p>Payment acquiring\_off\_us\_status<br>Possible value: <code>true, false</code></p>                                                                                                                                                                                                       |
| `card_payment.request_id`              | `string` | Mandatory   | Request ID for transaction                                                                                                                                                                                                                                                                  |
| `card_payment.card_type`               | `string` | Conditional | <p>Card type.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>CREDIT, DEBIT</code></p>                                                                                                                                                |
| `card_payment.three_dsecure_status`    | `string` | Optional    | <p>Three dsecure status<br>Possible value: <code>TRUE, FALSE</code></p>                                                                                                                                                                                                                     |
| `card_payment.issuer`                  | `string` | Conditional | <p>Card issuer.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                            |
| `card_payment.transaction_status`      | `string` | Mandatory   | <p>Transaction status<br>Possible value: <code>SUCCESS, FAILED, PENDING</code></p>                                                                                                                                                                                                          |
| `card_payment.brand`                   | `string` | Conditional | <p>Card brand.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                             |
| `card_payment.date`                    | `string` | Optional    | Transaction card date                                                                                                                                                                                                                                                                       |
| `card_payment.authorize_id`            | `string` | Optional    | Transaction authorize ID                                                                                                                                                                                                                                                                    |
| `card_payment.authentication_id`       | `string` | Optional    | Transaction authentication ID                                                                                                                                                                                                                                                               |
| {% endtab %}                           |          |             |                                                                                                                                                                                                                                                                                             |

{% tab title="Void" %}

| Parameter                              | Type     | Mandatory   | Description                                                                                                                                                                                                                                                                                 |
| -------------------------------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`                 | `string` | Mandatory   | Same as the request that merchant sent on the payment initiation                                                                                                                                                                                                                            |
| `order.amount`                         | `number` | Mandatory   | Same as the request that merchant sent on the payment initiation                                                                                                                                                                                                                            |
| `order.currency`                       | `string` | Mandatory   |                                                                                                                                                                                                                                                                                             |
| `transaction.status`                   | `string` | Mandatory   | <p>The transaction status to be use to update the status on merchant side<br>Possible value: <code>FAILED</code>, <br><code>PARTIAL\_REFUNDED</code>, <br><code>PENDING</code>, <br><code>REDIRECT</code>, <br><code>REFUNDED</code>, <br><code>SUCCESS</code>, <br><code>VOIDED</code></p> |
| `transaction.date`                     | `string` | Mandatory   | The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)                                                                                                                                                                                                     |
| `transaction.type`                     | `string` | Conditional | <p>Type for Credit Card Transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>SALE, INSTALLMENT, MOTO, AUTHORIZE, CAPTURE, RECURRING, REFUND</code></p>                                                                        |
| `transaction.original_request_id`      | `string` | Mandatory   | The request ID that sent when initiate the payment                                                                                                                                                                                                                                          |
| `service.id`                           | `string` | Mandatory   | The service that is used for the transaction                                                                                                                                                                                                                                                |
| `acquirer.id`                          | `string` | Conditional | <p>The acquirer that processed the transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS.<br></p>                                                                                                                                                                      |
| `channel.id`                           | `string` | Mandatory   | The channel of the transaction                                                                                                                                                                                                                                                              |
| `card_payment.card_masked`             | `string` | Conditional | <p>The masked card number that charged for this transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                               |
| `card_payment.approval_code`           | `string` | Conditional | <p>Acquirer approval code for this transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                            |
| `card_payment.response_code`           | `string` | Conditional | <p>Acquirer response code.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                 |
| `card_payment.response_message`        | `string` | Conditional | <p>Acquirer response code<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                  |
| `card_payment.type`                    | `string` | Conditional | <p>Type for Credit Card Transaction.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>SALE, INSTALLMENT, MOTO, AUTHORIZE, CAPTURE, RECURRING, REFUND</code></p>                                                                        |
| `card_payment.acquiring_off_us_status` | `string` | Mandatory   | <p>Payment acquiring\_off\_us\_status<br>Possible value: <code>true, false</code></p>                                                                                                                                                                                                       |
| `card_payment.request_id`              | `string` | Mandatory   | Request ID for transaction                                                                                                                                                                                                                                                                  |
| `card_payment.card_type`               | `string` | Conditional | <p>Card type.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br><br>Possible value: <code>CREDIT, DEBIT</code></p>                                                                                                                                                |
| `card_payment.three_dsecure_status`    | `string` | Optional    | <p>Three dsecure status<br>Possible value: <code>TRUE, FALSE</code></p>                                                                                                                                                                                                                     |
| `card_payment.issuer`                  | `string` | Conditional | <p>Card issuer.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                            |
| `card_payment.transaction_status`      | `string` | Mandatory   | <p>Transaction status<br>Possible value: <code>SUCCESS, FAILED, PENDING</code></p>                                                                                                                                                                                                          |
| `card_payment.brand`                   | `string` | Conditional | <p>Card brand.<br>Mandatory if <code>transaction.status</code> value SUCCESS or FAILED.<br></p>                                                                                                                                                                                             |
| `card_payment.date`                    | `string` | Optional    | Transaction card date                                                                                                                                                                                                                                                                       |
| `card_payment.authorize_id`            | `string` | Optional    | Transaction authorize ID                                                                                                                                                                                                                                                                    |
| `card_payment.authentication_id`       | `string` | Optional    | Transaction authentication ID                                                                                                                                                                                                                                                               |
| {% endtab %}                           |          |             |                                                                                                                                                                                                                                                                                             |
| {% endtabs %}                          |          |             |                                                                                                                                                                                                                                                                                             |

### Paylater

The response will be similar to HTTP notification. Some parameters might not be presented in certain status cases, please check our Postman Collection to try it yourself.

{% tabs %}
{% tab title="Akulaku" %}

```json
{
    "order": {
        "invoice_number": "invoice-000001014123sdd4",
        "amount": 110000
    },
    "transaction": {
        "status": "PENDING",
        "date": "2024-07-12T06:47:40Z",
        "original_request_id": "93337206-946b-4949-b0c9-15cd04556e09"
    },
    "service": {
        "id": "PEER_TO_PEER"
    },
    "acquirer": {
        "id": "AKULAKU",
        "name": "Akulaku"
    },
    "channel": {
        "id": "PEER_TO_PEER_AKULAKU"
    },
    "peer_to_peer_payment": {
        "status": "PENDING",
        "date": "2024-07-12T06:47:40Z",
        "identifier": [
            {
                "name": "merchant_unique_reference",
                "value": "TEST-ABC-000104"
            },
            {
                "name": "akulaku_unique_reference",
                "value": "MCH-0008-1218873017641TEST-ABC-000104"
            },
            {
                "name": "order_id",
                "value": "MCH-0008-1218873017641TEST-ABC-000104"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="Kredivo" %}

```json
{
    "order": {
        "invoice_number": "invoice-000001014123sdd4",
        "amount": 110000
    },
    "transaction": {
        "status": "PENDING",
        "date": "2024-07-12T06:47:40Z",
        "original_request_id": "93337206-946b-4949-b0c9-15cd04556e09"
    },
    "service": {
        "id": "PEER_TO_PEER"
    },
    "acquirer": {
        "id": "KREDIVO",
        "name": "Kredivo"
    },
    "channel": {
        "id": "PEER_TO_PEER_KREDIVO"
    },
    "peer_to_peer_payment": {
        "status": "PENDING",
        "date": "2024-07-12T06:47:40Z",
        "identifier": [
            {
                "name": "merchant_unique_reference",
                "value": "TEST-ABC-000104"
            },
            {
                "name": "kredivo_unique_reference",
                "value": "MCH-0008-1218873017641TEST-ABC-000104"
            },
            {
                "name": "order_id",
                "value": "MCH-0008-1218873017641TEST-ABC-000104"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="Indodana" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "order": {
        "invoice_number": "invoice-000001014123sdd4",
        "amount": 110000
    },
    "transaction": {
        "status": "PENDING",
        "date": "2024-07-12T06:47:40Z",
        "original_request_id": "93337206-946b-4949-b0c9-15cd04556e09"
    },
    "service": {
        "id": "PEER_TO_PEER"
    },
    "acquirer": {
        "id": "INDODANA",
        "name": "Indodana"
    },
    "channel": {
        "id": "PEER_TO_PEER_INDODANA"
    },
    "peer_to_peer_payment": {
        "status": "PENDING",
        "date": "2024-07-12T06:47:40Z",
        "identifier": [
            {
                "name": "merchant_unique_reference",
                "value": "TEST-ABC-000104"
            },
            {
                "name": "indodana_unique_reference",
                "value": "MCH-0008-1218873017641TEST-ABC-000104"
            },
            {
                "name": "order_id",
                "value": "MCH-0008-1218873017641TEST-ABC-000104"
            }
        ]
    }
}
</code></pre>

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Akulaku" %}

| Parameter                                                                | Type     | Mandatory | Description                                                                                                                    |
| ------------------------------------------------------------------------ | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `service.id`                                                             | `string` | Mandatory | The service that is used for the transaction                                                                                   |
| `acquirer.id`                                                            | `string` | Mandatory | The acquirer that processed the transaction                                                                                    |
| `channel.id`                                                             | `string` | Mandatory | The channel of the transaction                                                                                                 |
| `order.invoice_number`                                                   | `string` | Mandatory | Same as the request that merchant sent on the payment initiation                                                               |
| `order.amount`                                                           | `number` | Mandatory | Same as the request that merchant sent on the payment initiation                                                               |
| `transaction.status`                                                     | `string` | Mandatory | <p>The transaction status to be use to update the status on merchant side<br>Possible value: <code>SUCCESS, PENDING</code></p> |
| `transaction.date`                                                       | `string` | Mandatory | The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)                                        |
| `transaction.original_request_id`                                        | `string` | Mandatory | The request ID that sent when initiate the payment                                                                             |
| <p><code>payment.</code><br><code>merchant\_unique\_reference</code></p> | `string` | Mandatory | The merchant unique reference that sent when initiate the payment                                                              |
| {% endtab %}                                                             |          |           |                                                                                                                                |

{% tab title="Kredivo" %}

| Parameter                                                                | Type     | Mandatory | Description                                                                                                                    |
| ------------------------------------------------------------------------ | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `service.id`                                                             | `string` | Mandatory | The service that is used for the transaction                                                                                   |
| `acquirer.id`                                                            | `string` | Mandatory | The acquirer that processed the transaction                                                                                    |
| `channel.id`                                                             | `string` | Mandatory | The channel of the transaction                                                                                                 |
| `order.invoice_number`                                                   | `string` | Mandatory | Same as the request that merchant sent on the payment initiation                                                               |
| `order.amount`                                                           | `number` | Mandatory | Same as the request that merchant sent on the payment initiation                                                               |
| `transaction.status`                                                     | `string` | Mandatory | <p>The transaction status to be use to update the status on merchant side<br>Possible value: <code>SUCCESS, PENDING</code></p> |
| `transaction.date`                                                       | `string` | Mandatory | The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)                                        |
| `transaction.original_request_id`                                        | `string` | Mandatory | The request ID that sent when initiate the payment                                                                             |
| <p><code>payment.</code><br><code>merchant\_unique\_reference</code></p> | `string` | Mandatory | The merchant unique reference that sent when initiate the payment                                                              |
| {% endtab %}                                                             |          |           |                                                                                                                                |

{% tab title="Indodana" %}
Response Explanation

| Parameter                                                                | Type     | Mandatory | Description                                                                                                                    |
| ------------------------------------------------------------------------ | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `service.id`                                                             | `string` | Mandatory | The service that is used for the transaction                                                                                   |
| `acquirer.id`                                                            | `string` | Mandatory | The acquirer that processed the transaction                                                                                    |
| `channel.id`                                                             | `string` | Mandatory | The channel of the transaction                                                                                                 |
| `order.invoice_number`                                                   | `string` | Mandatory | Same as the request that merchant sent on the payment initiation                                                               |
| `order.amount`                                                           | `number` | Mandatory | Same as the request that merchant sent on the payment initiation                                                               |
| `transaction.status`                                                     | `string` | Mandatory | <p>The transaction status to be use to update the status on merchant side<br>Possible value: <code>SUCCESS, PENDING</code></p> |
| `transaction.date`                                                       | `string` | Mandatory | The date when the transaction is completed by the customer in ISO 8601 format (UTC + 0)                                        |
| `transaction.original_request_id`                                        | `string` | Mandatory | The request ID that sent when initiate the payment                                                                             |
| <p><code>payment.</code><br><code>merchant\_unique\_reference</code></p> | `string` | Mandatory | The merchant unique reference that sent when initiate the payment                                                              |
| {% endtab %}                                                             |          |           |                                                                                                                                |
| {% endtabs %}                                                            |          |           |                                                                                                                                |


# SNAP

To get the status of a transaction, you can send a request to DOKU Check Status API. It will response with the transaction status.

{% hint style="warning" %}
**HIT CHECK STATUS AFTER 60 SECONDS AFTER PAYMENT COMPLETION!**

To get the status for the transaction, please ensure your application is already hit after 60 seconds after payment completion.
{% endhint %}

## Virtual Account

### API Request&#x20;

#### Endpoint

<table><thead><tr><th width="248">Type</th><th>Value</th></tr></thead><tbody><tr><td><strong>HTTP Method</strong></td><td>POST</td></tr><tr><td><strong>API endpoint (Sandbox)</strong></td><td><code>https://api-sandbox.doku.com/orders/v1.0/transfer-va/status</code></td></tr><tr><td><strong>API endpoint (Production)</strong></td><td><code>https://api.doku.com/orders/v1.0/transfer-va/status</code></td></tr></tbody></table>

Here is the sample of Check Status request header  :

```json
X-TIMESTAMP: 2020-12-21T14:56:11+07:00
X-SIGNATURE: ieNOENDdN4MnectGytx5UvmOfASZ2oGWMCJ8gVqkw3tB98ofgY9cbxSeY4IYoYeoKs+0QP4h8BTBhemlfeXp1w==
X-PARTNER-ID: 82150823919040624621823174737537
X-EXTERNAL-ID: 41807553358950093184162180797837
Authorization: bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a"
Content type: application/ json
```

#### Request Header Explanation

<table><thead><tr><th>Parameter</th><th width="123">Data Type	</th><th width="116">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><strong>X-TIMESTAMP</strong></td><td>string</td><td>Mandatory</td><td>Client's current local time with format :<br><code>YYYY-MM-DDTHH:mm:ssZD</code></td></tr><tr><td><strong>X-SIGNATURE</strong></td><td>string</td><td>Mandatory</td><td>Represents signature of a request. Identify Signature Type used Value:<br>1. Symmetric Signature with Get Token (Default)<br><code>HMAC_SHA512 (clientSecret, stringToSign)</code> with formula <code>stringToSign = HTTPMethod +”:“+ EndpointUrl +":"+ AccessToken +":“+ Lowercase(HexEncode(SHA-256(minify(RequestBody))))+ ":“ + TimeStamp</code><br>Notes :<br>1. The full URL endpoint includes all parameters in the associated URL<br>2. For the <code>minify(Request Body)</code> parameter, if there is no Request Body then an empty string is used.</td></tr><tr><td><strong>X-PARTNER-ID</strong></td><td>string</td><td>Mandatory</td><td>Client ID for merchant that generated by DOKU</td></tr><tr><td><strong>X-EXTERNAL-ID</strong></td><td>string</td><td>Mandatory</td><td>Reference number that should be unique in the same day or to be known as Request ID</td></tr><tr><td><strong>Authorization</strong></td><td>string</td><td>Mandatory</td><td>Represents access_token of a request; Keyword starts with “Bearer ” followed by access_token (e.g. <code>Bearer eyJraWQiOi...Jzc29zIiwiY</code>)</td></tr><tr><td><strong>Content type</strong></td><td>string</td><td>Mandatory</td><td>The media type of the resource (e.g. application/json)</td></tr></tbody></table>

#### Request Body

Here is the sample of request body to get status of VA number:

```json
{
   "partnerServiceId":"  088899",
   "customerNo":12345678901234567890,
   "virtualAccountNo":"  08889912345678901234567890",
   "inquiryRequestId":"abcdef-123456-abcdef",
   "paymentRequestId":"abcdef-123456-abcdef",
   "additionalInfo":{
   
   }
}
```

| Parameter          | Type         | Mandatory   | Description                                                                                                                     |
| ------------------ | ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `partnerServiceId` | string (8)   | Mandatory   | Derivative of X-PARTNER-ID , similar to company code, 8 digit left padding space                                                |
| `customerNo`       | string (20)  | Mandatory   | Unique number (up to 20 digits)                                                                                                 |
| `virtualAccountNo` | string (28)  | Mandatory   | partnerServiceId (8 digit left padding space) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo |
| `inquiryRequestId` | string (128) | Conditional | Unique identifier from Inquiry. If not send, will return array of transaction based on **virtualAccountNo**                     |
| `paymentRequestId` | string (128) | Optional    | Unique identifier for this Payment from PJP. Mandatory if Payment happened.                                                     |
| `additionalInfo`   | string       | Optional    | Additional info                                                                                                                 |

### API Response

#### Response Body

The response will be similar to HTTP notification. Some parameters might not be presented in certain status cases, please check our Postman Collection to try it yourself.

{% tabs %}
{% tab title="BRI" %}

```json
{
    "responseCode": "2002600",
    "responseMessage": "Successful",
    "virtualAccountData": {
        "paymentFlagReason": {
            "english": "Pending",
            "indonesia": "Belum Terbayar"
        },
        "partnerServiceId": "   12345",
        "customerNo": "70020000342",
        "virtualAccountNo": "   1234570020000342",
        "paidAmount": {
            "value": "200000.00",
            "currency": "IDR"
        },
        "billDetails": [
            {
                "billAmount": {
                    "value": "200000.00",
                    "currency": "IDR"
                }
            }
        ]
    },
    "additionalInfo": {
        "acquirer": {
            "id": "BRI"
        },
        "trxId": "Testjess12345"
    }
}
```

{% endtab %}

{% tab title="BNI" %}

```json
{
    "responseCode": "2002600",
    "responseMessage": "Successful",
    "virtualAccountData": {
        "paymentFlagReason": {
            "english": "Pending",
            "indonesia": "Belum Terbayar"
        },
        "partnerServiceId": "   12345",
        "customerNo": "70020000342",
        "virtualAccountNo": "   1234570020000342",
        "paidAmount": {
            "value": "200000.00",
            "currency": "IDR"
        },
        "billDetails": [
            {
                "billAmount": {
                    "value": "200000.00",
                    "currency": "IDR"
                }
            }
        ]
    },
    "additionalInfo": {
        "acquirer": {
            "id": "BNI"
        },
        "trxId": "Testjess12345"
    }
}
```

{% endtab %}

{% tab title="BNC" %}

```json
{
    "responseCode": "2002600",
    "responseMessage": "Successful",
    "virtualAccountData": {
        "paymentFlagReason": {
            "english": "Pending",
            "indonesia": "Belum Terbayar"
        },
        "partnerServiceId": "   12345",
        "customerNo": "70020000342",
        "virtualAccountNo": "   1234570020000342",
        "paidAmount": {
            "value": "200000.00",
            "currency": "IDR"
        },
        "billDetails": [
            {
                "billAmount": {
                    "value": "200000.00",
                    "currency": "IDR"
                }
            }
        ]
    },
    "additionalInfo": {
        "acquirer": {
            "id": "BNC"
        },
        "trxId": "Testjess12345"
    }
}
```

{% endtab %}

{% tab title="BTN" %}

```json
{
    "responseCode": "2002600",
    "responseMessage": "Successful",
    "virtualAccountData": {
        "paymentFlagReason": {
            "english": "Pending",
            "indonesia": "Belum Terbayar"
        },
        "partnerServiceId": "   12345",
        "customerNo": "70020000342",
        "virtualAccountNo": "   1234570020000342",
        "paidAmount": {
            "value": "200000.00",
            "currency": "IDR"
        },
        "billDetails": [
            {
                "billAmount": {
                    "value": "200000.00",
                    "currency": "IDR"
                }
            }
        ]
    },
    "additionalInfo": {
        "acquirer": {
            "id": "BTN"
        },
        "trxId": "Testjess12345"
    }
}
```

{% endtab %}

{% tab title="Danamon" %}

```json
{
    "responseCode": "2002600",
    "responseMessage": "Successful",
    "virtualAccountData": {
        "paymentFlagReason": {
            "english": "Pending",
            "indonesia": "Belum Terbayar"
        },
        "partnerServiceId": "   12345",
        "customerNo": "70020000342",
        "virtualAccountNo": "   1234570020000342",
        "paidAmount": {
            "value": "200000.00",
            "currency": "IDR"
        },
        "billDetails": [
            {
                "billAmount": {
                    "value": "200000.00",
                    "currency": "IDR"
                }
            }
        ]
    },
    "additionalInfo": {
        "acquirer": {
            "id": "DANAMON"
        },
        "trxId": "Testjess12345"
    }
}
```

{% endtab %}

{% tab title="Mandiri" %}

```json
{
    "responseCode": "2002600",
    "responseMessage": "Successful",
    "virtualAccountData": {
        "paymentFlagReason": {
            "english": "Pending",
            "indonesia": "Belum Terbayar"
        },
        "partnerServiceId": "   12345",
        "customerNo": "70020000342",
        "virtualAccountNo": "   1234570020000342",
        "paidAmount": {
            "value": "200000.00",
            "currency": "IDR"
        },
        "billDetails": [
            {
                "billAmount": {
                    "value": "200000.00",
                    "currency": "IDR"
                }
            }
        ]
    },
    "additionalInfo": {
        "acquirer": {
            "id": "MANDIRI"
        },
        "trxId": "Testjess12345"
    }
}
```

{% endtab %}

{% tab title="Permata" %}

```json
{
    "responseCode": "2002600",
    "responseMessage": "Successful",
    "virtualAccountData": {
        "paymentFlagReason": {
            "english": "Pending",
            "indonesia": "Belum Terbayar"
        },
        "partnerServiceId": "   12345",
        "customerNo": "70020000342",
        "virtualAccountNo": "   1234570020000342",
        "paidAmount": {
            "value": "200000.00",
            "currency": "IDR"
        },
        "billDetails": [
            {
                "billAmount": {
                    "value": "200000.00",
                    "currency": "IDR"
                }
            }
        ]
    },
    "additionalInfo": {
        "acquirer": {
            "id": "PERMATA"
        },
        "trxId": "Testjess12345"
    }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="BRI" %}

<table><thead><tr><th>Parameter</th><th width="174">Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>responseCode</code></td><td>String (7)</td><td>Mandatory</td><td>Response Code</td></tr><tr><td><code>responseMessage</code></td><td>String (150)</td><td>Mandatory</td><td>Response Description</td></tr><tr><td><code>virtualAccountData.paymentFlagReason</code></td><td>String (200)</td><td>Optional</td><td>Reason for Payment Status multi language</td></tr><tr><td><code>virtualAccountData.partnerServiceId</code></td><td>String</td><td>Mandatory</td><td>Derivative of X-PARTNER-ID , similar to company code,</td></tr><tr><td><code>virtualAccountData.customerNo</code></td><td>String</td><td>Mandatory</td><td>Unique number</td></tr><tr><td><code>virtualAccountData.virtualAccountNo</code></td><td>String</td><td>Mandatory</td><td>partnerServiceId (8 digit left padding space) + customerNo (up to 20 digits)</td></tr><tr><td><code>virtualAccountData.inquiryRequestId</code></td><td>String</td><td>Conditional</td><td>Unique identifier from Inquiry</td></tr><tr><td><code>virtualAccountData.paymentRequestId</code></td><td>String</td><td>Conditional</td><td>Unique identifier for this Payment from PJP. Mandatory if Payment happened.</td></tr><tr><td><code>virtualAccountData.paidAmount</code></td><td>Object</td><td>Mandatory</td><td>Paid Amount with 2 decimal</td></tr><tr><td><code>virtualAccountData.paidAmount.billDetails</code></td><td>Object</td><td>Mandatory</td><td>Transaction Amount.</td></tr><tr><td><code>additionalInfo</code></td><td>Object</td><td>Mandatory</td><td>Additional Info</td></tr></tbody></table>
{% endtab %}

{% tab title="BNI" %}

| Parameter                                   | Type         | Mandatory   | Description                                                                  |
| ------------------------------------------- | ------------ | ----------- | ---------------------------------------------------------------------------- |
| `responseCode`                              | String (7)   | Mandatory   | Response Code                                                                |
| `responseMessage`                           | String (150) | Mandatory   | Response Description                                                         |
| `virtualAccountData.paymentFlagReason`      | String (200) | Optional    | Reason for Payment Status multi language                                     |
| `virtualAccountData.partnerServiceId`       | String       | Mandatory   | Derivative of X-PARTNER-ID , similar to company code,                        |
| `virtualAccountData.customerNo`             | String       | Mandatory   | Unique number                                                                |
| `virtualAccountData.virtualAccountNo`       | String       | Mandatory   | partnerServiceId (8 digit left padding space) + customerNo (up to 20 digits) |
| `virtualAccountData.inquiryRequestId`       | String       | Conditional | Unique identifier from Inquiry                                               |
| `virtualAccountData.paymentRequestId`       | String       | Conditional | Unique identifier for this Payment from PJP. Mandatory if Payment happened.  |
| `virtualAccountData.paidAmount`             | Object       | Mandatory   | Paid Amount with 2 decimal                                                   |
| `virtualAccountData.paidAmount.billDetails` | Object       | Mandatory   | Transaction Amount.                                                          |
| `additionalInfo`                            | Object       | Mandatory   | Additional Info                                                              |
| {% endtab %}                                |              |             |                                                                              |

{% tab title="BNC" %}

| Parameter                                   | Type         | Mandatory   | Description                                                                  |
| ------------------------------------------- | ------------ | ----------- | ---------------------------------------------------------------------------- |
| `responseCode`                              | String (7)   | Mandatory   | Response Code                                                                |
| `responseMessage`                           | String (150) | Mandatory   | Response Description                                                         |
| `virtualAccountData.paymentFlagReason`      | String (200) | Optional    | Reason for Payment Status multi language                                     |
| `virtualAccountData.partnerServiceId`       | String       | Mandatory   | Derivative of X-PARTNER-ID , similar to company code,                        |
| `virtualAccountData.customerNo`             | String       | Mandatory   | Unique number                                                                |
| `virtualAccountData.virtualAccountNo`       | String       | Mandatory   | partnerServiceId (8 digit left padding space) + customerNo (up to 20 digits) |
| `virtualAccountData.inquiryRequestId`       | String       | Conditional | Unique identifier from Inquiry                                               |
| `virtualAccountData.paymentRequestId`       | String       | Conditional | Unique identifier for this Payment from PJP. Mandatory if Payment happened.  |
| `virtualAccountData.paidAmount`             | Object       | Mandatory   | Paid Amount with 2 decimal                                                   |
| `virtualAccountData.paidAmount.billDetails` | Object       | Mandatory   | Transaction Amount.                                                          |
| `additionalInfo`                            | Object       | Mandatory   | Additional Info                                                              |
| {% endtab %}                                |              |             |                                                                              |

{% tab title="BTN" %}

| Parameter                                   | Type         | Mandatory   | Description                                                                  |
| ------------------------------------------- | ------------ | ----------- | ---------------------------------------------------------------------------- |
| `responseCode`                              | String (7)   | Mandatory   | Response Code                                                                |
| `responseMessage`                           | String (150) | Mandatory   | Response Description                                                         |
| `virtualAccountData.paymentFlagReason`      | String (200) | Optional    | Reason for Payment Status multi language                                     |
| `virtualAccountData.partnerServiceId`       | String       | Mandatory   | Derivative of X-PARTNER-ID , similar to company code,                        |
| `virtualAccountData.customerNo`             | String       | Mandatory   | Unique number                                                                |
| `virtualAccountData.virtualAccountNo`       | String       | Mandatory   | partnerServiceId (8 digit left padding space) + customerNo (up to 20 digits) |
| `virtualAccountData.inquiryRequestId`       | String       | Conditional | Unique identifier from Inquiry                                               |
| `virtualAccountData.paymentRequestId`       | String       | Conditional | Unique identifier for this Payment from PJP. Mandatory if Payment happened.  |
| `virtualAccountData.paidAmount`             | Object       | Mandatory   | Paid Amount with 2 decimal                                                   |
| `virtualAccountData.paidAmount.billDetails` | Object       | Mandatory   | Transaction Amount.                                                          |
| `additionalInfo`                            | Object       | Mandatory   | Additional Info                                                              |
| {% endtab %}                                |              |             |                                                                              |

{% tab title="Danamon" %}

| Parameter                                   | Type         | Mandatory   | Description                                                                  |
| ------------------------------------------- | ------------ | ----------- | ---------------------------------------------------------------------------- |
| `responseCode`                              | String (7)   | Mandatory   | Response Code                                                                |
| `responseMessage`                           | String (150) | Mandatory   | Response Description                                                         |
| `virtualAccountData.paymentFlagReason`      | String (200) | Optional    | Reason for Payment Status multi language                                     |
| `virtualAccountData.partnerServiceId`       | String       | Mandatory   | Derivative of X-PARTNER-ID , similar to company code,                        |
| `virtualAccountData.customerNo`             | String       | Mandatory   | Unique number                                                                |
| `virtualAccountData.virtualAccountNo`       | String       | Mandatory   | partnerServiceId (8 digit left padding space) + customerNo (up to 20 digits) |
| `virtualAccountData.inquiryRequestId`       | String       | Conditional | Unique identifier from Inquiry                                               |
| `virtualAccountData.paymentRequestId`       | String       | Conditional | Unique identifier for this Payment from PJP. Mandatory if Payment happened.  |
| `virtualAccountData.paidAmount`             | Object       | Mandatory   | Paid Amount with 2 decimal                                                   |
| `virtualAccountData.paidAmount.billDetails` | Object       | Mandatory   | Transaction Amount.                                                          |
| `additionalInfo`                            | Object       | Mandatory   | Additional Info                                                              |
| {% endtab %}                                |              |             |                                                                              |

{% tab title="Mandiri" %}

| Parameter                                   | Type         | Mandatory   | Description                                                                  |
| ------------------------------------------- | ------------ | ----------- | ---------------------------------------------------------------------------- |
| `responseCode`                              | String (7)   | Mandatory   | Response Code                                                                |
| `responseMessage`                           | String (150) | Mandatory   | Response Description                                                         |
| `virtualAccountData.paymentFlagReason`      | String (200) | Optional    | Reason for Payment Status multi language                                     |
| `virtualAccountData.partnerServiceId`       | String       | Mandatory   | Derivative of X-PARTNER-ID , similar to company code,                        |
| `virtualAccountData.customerNo`             | String       | Mandatory   | Unique number                                                                |
| `virtualAccountData.virtualAccountNo`       | String       | Mandatory   | partnerServiceId (8 digit left padding space) + customerNo (up to 20 digits) |
| `virtualAccountData.inquiryRequestId`       | String       | Conditional | Unique identifier from Inquiry                                               |
| `virtualAccountData.paymentRequestId`       | String       | Conditional | Unique identifier for this Payment from PJP. Mandatory if Payment happened.  |
| `virtualAccountData.paidAmount`             | Object       | Mandatory   | Paid Amount with 2 decimal                                                   |
| `virtualAccountData.paidAmount.billDetails` | Object       | Mandatory   | Transaction Amount.                                                          |
| `additionalInfo`                            | Object       | Mandatory   | Additional Info                                                              |
| {% endtab %}                                |              |             |                                                                              |

{% tab title="Permata" %}

| Parameter                                   | Type         | Mandatory   | Description                                                                  |
| ------------------------------------------- | ------------ | ----------- | ---------------------------------------------------------------------------- |
| `responseCode`                              | String (7)   | Mandatory   | Response Code                                                                |
| `responseMessage`                           | String (150) | Mandatory   | Response Description                                                         |
| `virtualAccountData.paymentFlagReason`      | String (200) | Optional    | Reason for Payment Status multi language                                     |
| `virtualAccountData.partnerServiceId`       | String       | Mandatory   | Derivative of X-PARTNER-ID , similar to company code,                        |
| `virtualAccountData.customerNo`             | String       | Mandatory   | Unique number                                                                |
| `virtualAccountData.virtualAccountNo`       | String       | Mandatory   | partnerServiceId (8 digit left padding space) + customerNo (up to 20 digits) |
| `virtualAccountData.inquiryRequestId`       | String       | Conditional | Unique identifier from Inquiry                                               |
| `virtualAccountData.paymentRequestId`       | String       | Conditional | Unique identifier for this Payment from PJP. Mandatory if Payment happened.  |
| `virtualAccountData.paidAmount`             | Object       | Mandatory   | Paid Amount with 2 decimal                                                   |
| `virtualAccountData.paidAmount.billDetails` | Object       | Mandatory   | Transaction Amount.                                                          |
| `additionalInfo`                            | Object       | Mandatory   | Additional Info                                                              |
| {% endtab %}                                |              |             |                                                                              |
| {% endtabs %}                               |              |             |                                                                              |

## Direct Debit

### API Request&#x20;

#### Endpoint

<table><thead><tr><th width="248">Type</th><th>Value</th></tr></thead><tbody><tr><td><strong>HTTP Method</strong></td><td>POST</td></tr><tr><td><strong>API endpoint (Sandbox)</strong></td><td><code>https://api-sandbox.doku.com/orders/v1.0/debit/status</code></td></tr><tr><td><strong>API endpoint (Production)</strong></td><td><code>https://api.doku.com/orders/v1.0/debit/status</code></td></tr></tbody></table>

Here is the sample of Check Status request header  :

```json
X-TIMESTAMP: 2020-12-21T14:56:11+07:00
X-SIGNATURE: ieNOENDdN4MnectGytx5UvmOfASZ2oGWMCJ8gVqkw3tB98ofgY9cbxSeY4IYoYeoKs+0QP4h8BTBhemlfeXp1w==
X-PARTNER-ID: 82150823919040624621823174737537
X-EXTERNAL-ID: 41807553358950093184162180797837
Authorization: bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a"
Content type: application/ json
```

#### Request Header Explanation

<table><thead><tr><th>Parameter</th><th width="123">Data Type	</th><th width="116">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><strong>X-TIMESTAMP</strong></td><td>string</td><td>Mandatory</td><td>Client's current local time with format :<br><code>YYYY-MM-DDTHH:mm:ssZD</code></td></tr><tr><td><strong>X-SIGNATURE</strong></td><td>string</td><td>Mandatory</td><td>Represents signature of a request. Identify Signature Type used Value:<br>1. Symmetric Signature with Get Token (Default)<br><code>HMAC_SHA512 (clientSecret, stringToSign)</code> with formula <code>stringToSign = HTTPMethod +”:“+ EndpointUrl +":"+ AccessToken +":“+ Lowercase(HexEncode(SHA-256(minify(RequestBody))))+ ":“ + TimeStamp</code><br>Notes :<br>1. The full URL endpoint includes all parameters in the associated URL<br>2. For the <code>minify(Request Body)</code> parameter, if there is no Request Body then an empty string is used.</td></tr><tr><td><strong>X-PARTNER-ID</strong></td><td>string</td><td>Mandatory</td><td>Client ID for merchant that generated by DOKU</td></tr><tr><td><strong>X-EXTERNAL-ID</strong></td><td>string</td><td>Mandatory</td><td>Reference number that should be unique in the same day or to be known as Request ID</td></tr><tr><td><strong>Authorization</strong></td><td>string</td><td>Mandatory</td><td>Represents access_token of a request; Keyword starts with “Bearer ” followed by access_token (e.g. <code>Bearer eyJraWQiOi...Jzc29zIiwiY</code>)</td></tr><tr><td><strong>Content type</strong></td><td>string</td><td>Mandatory</td><td>The media type of the resource (e.g. application/json)</td></tr></tbody></table>

#### Request Body

Here is the sample of request body to get status of Direct Debit :&#x20;

```json
{
   "originalPartnerReferenceNo":"2020102900000000000001",
   "originalReferenceNo":"2020102977770000000009",
   "originalExternalId":"30443786930722726463280097920912",
   "serviceCode":"55",
   "transactionDate":"2020-12-21T14:56:11+07:00",
   "amount":{
      "value":"12345678.00",
      "currency":"IDR"
   },
   "merchantId":"23489182303312",
   "subMerchantId":"23489182303312",
   "externalStoreId":"183908924912387",
   "additionalInfo":{
      "deviceId":"12345679237",
      "channel":"mobilephone"
   }
}
```

| Parameter                  | Type   | Mandatory | Description                                                |
| -------------------------- | ------ | --------- | ---------------------------------------------------------- |
| originalPartnerReferenceNo | string | Optional  | Original transaction identifier on service consumer system |
| originalReferenceNo        | string | Optional  | Original transaction identifier on service provider system |
| originalExternalId         | string | Optional  | Original External-ID on header message                     |
| serviceCode                | string | Mandatory | API type indicator. Use : 55 for Check Status API          |
| transactionDate            | string | Optional  | transaction date : ISO 8601                                |
| amount                     | object | Optional  | Value and Currency                                         |
| merchantId                 | string | Optional  | Merchant identifier that is unique per each merchant       |
| subMerchantId              | string | Optional  | Sub merchant ID                                            |
| externalStoreId            | string | Optional  | External Store ID for merchant                             |
| additionalInfo             | object | Optional  | Additional information                                     |

### API Response

#### Response Body

The response will be similar to HTTP notification. Some parameters might not be presented in certain status cases, please check our Postman Collection to try it yourself.

{% tabs %}
{% tab title="BRI" %}

```json
{
   "responseCode":"2005500",
   "responseMessage":"Request has been processed successfully",
   "originalPartnerReferenceNo":"2020102900000000000001",
   "originalReferenceNo":"2020102977770000000009",
   "approvalCode":"201039000200",
   "originalExternalId":"30443786930722726463280097920912",
   "serviceCode":"55",
   "latestTransactionStatus":"00",
   "transactionStatusDesc":"success",
   "originalResponseCode":"2005500",
   "originalResponseMessage":"Request has been processed successfully",
   "sessionId":"883737GHY8839",
   "requestID":"3763773",
   "refundHistory":[
      {
         "refundNo":"96194816941239812",
         "partnerReferenceNo":"239850918204981205970",
         "refundAmount":{
            "value":"12345678.00",
            "currency":"IDR"
         },
         "refundStatus":"00",
         "refundDate":"2020-12-23T07:44:16+07:00",
         "reason":"Customer Complain"
      },
      {
         "refundNo":"96194123981251341",
         "partnerReferenceNo":"2398509123131981205970",
         "refundAmount":{
            "value":"112345678.00",
            "currency":"IDR"
         },
         "refundStatus":"00",
         "refundDate":"2020-12-23T07:54:16+07:00",
         "reason":"Customer Complain"
      }
   ],
   "transAmount":{
      "value":"112345678.00",
      "currency":"IDR"
   },
   "feeAmount":{
      "value":"112345678.00",
      "currency":"IDR"
   },
   "paidTime":"2020-12-21T14:56:11+07:00",
   "additionalInfo":{
      "deviceId":"12345679237",
      "channel":"mobilephone"
   }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="BRI" %}

| Parameter                  | Type         | Mandatory   | Description                                                                                                                                                                                                                 |
| -------------------------- | ------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `responseCode`             | String (7)   | Mandatory   | Response Code                                                                                                                                                                                                               |
| `responseMessage`          | String (150) | Mandatory   | Response Description                                                                                                                                                                                                        |
| originalReferenceNo        | String (200) | Conditional | Original transaction identifier on service provider system.                                                                                                                                                                 |
| originalPartnerReferenceNo | String       | Optional    | Original transaction identifier on service consumer system                                                                                                                                                                  |
| approvalCode               | String       | Optional    | Unique number                                                                                                                                                                                                               |
| originalExternalId         | String       | Optional    | Original External-ID on header message                                                                                                                                                                                      |
| serviceCode                | String       | Mandatory   | Transaction type indicator (service code of the original transaction request)                                                                                                                                               |
| latestTransactionStatus    | String       | Mandatory   | <p>Unique identifier for this Payment from PJP. Mandatory if Payment happened. <br><br>00 = Success<br>01 = Initiated<br>02 = Paying<br>03 = Pending<br>04 = Refunded<br>05 = Canceled<br>06 = Failed<br>07 = Not Found</p> |
| transactionStatusDesc      | String       | Optional    | Description status transaction                                                                                                                                                                                              |
| originalResponseCode       | String       | Optional    | Response code                                                                                                                                                                                                               |
| originalResponseMessage    | String       | Optional    | Response description                                                                                                                                                                                                        |
| sessionId                  | String       | Optional    | Transaction invoice ID                                                                                                                                                                                                      |
| requestID                  | String       | Optional    | Transaction request ID                                                                                                                                                                                                      |
| refundNo                   | String       | Conditional | Transaction Identifier on Service Provider System                                                                                                                                                                           |
| partnerRefundNo            | String       | Conditional | ReferenceNumber from PJP AIS for the refund.                                                                                                                                                                                |
| refundAmount               | object       | Optional    | Net amount of the refund                                                                                                                                                                                                    |
| refundStatus               | String       | Conditional | <p>00 = Success<br>03 = Pending<br>04 = Failed</p>                                                                                                                                                                          |
| refundDate                 | String       | Conditional | <p>(ISO 8601) <br>Transaction date : dd-MM-yyyy ( Mandatory )<br><br>HH:mm:Ss ( Optional )</p>                                                                                                                              |
| reason                     | String       | Optional    | Refund reason.                                                                                                                                                                                                              |
| transAmount                | object       | Optional    | Transaction amount that will be paid using this payment method If it's IDR then value includes 2 decimal digits.                                                                                                            |
| feeAmount                  | String       | Optional    | Fee amount that will be paid using this payment method If it's IDR then value includes 2 decimal digits.                                                                                                                    |
| paidTime                   | String       | Conditional | transaction date : ISO 8601                                                                                                                                                                                                 |
| additionalInfo             | object       | Mandatory   | Additional information                                                                                                                                                                                                      |
| {% endtab %}               |              |             |                                                                                                                                                                                                                             |
| {% endtabs %}              |              |             |                                                                                                                                                                                                                             |

## E-Wallet

### API Request&#x20;

#### Endpoint

<table><thead><tr><th width="248">Type</th><th>Value</th></tr></thead><tbody><tr><td><strong>HTTP Method</strong></td><td>POST</td></tr><tr><td><strong>API endpoint (Sandbox)</strong></td><td><code>https://api-sandbox.doku.com/orders/v1.0/debit/status</code></td></tr><tr><td><strong>API endpoint (Production)</strong></td><td><code>https://api.doku.com/orders/v1.0/debit/status</code></td></tr></tbody></table>

Here is the sample of Check Status request header  :

```json
X-TIMESTAMP: 2020-12-21T14:56:11+07:00
X-SIGNATURE: ieNOENDdN4MnectGytx5UvmOfASZ2oGWMCJ8gVqkw3tB98ofgY9cbxSeY4IYoYeoKs+0QP4h8BTBhemlfeXp1w==
X-PARTNER-ID: 82150823919040624621823174737537
X-EXTERNAL-ID: 41807553358950093184162180797837
Authorization: bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a"
Content type: application/ json
```

#### Request Header Explanation

<table><thead><tr><th>Parameter</th><th width="123">Data Type	</th><th width="116">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><strong>X-TIMESTAMP</strong></td><td>string</td><td>Mandatory</td><td>Client's current local time with format :<br><code>YYYY-MM-DDTHH:mm:ssZD</code></td></tr><tr><td><strong>X-SIGNATURE</strong></td><td>string</td><td>Mandatory</td><td>Represents signature of a request. Identify Signature Type used Value:<br>1. Symmetric Signature with Get Token (Default)<br><code>HMAC_SHA512 (clientSecret, stringToSign)</code> with formula <code>stringToSign = HTTPMethod +”:“+ EndpointUrl +":"+ AccessToken +":“+ Lowercase(HexEncode(SHA-256(minify(RequestBody))))+ ":“ + TimeStamp</code><br>Notes :<br>1. The full URL endpoint includes all parameters in the associated URL<br>2. For the <code>minify(Request Body)</code> parameter, if there is no Request Body then an empty string is used.</td></tr><tr><td><strong>X-PARTNER-ID</strong></td><td>string</td><td>Mandatory</td><td>Client ID for merchant that generated by DOKU</td></tr><tr><td><strong>X-EXTERNAL-ID</strong></td><td>string</td><td>Mandatory</td><td>Reference number that should be unique in the same day or to be known as Request ID</td></tr><tr><td><strong>Authorization</strong></td><td>string</td><td>Mandatory</td><td>Represents access_token of a request; Keyword starts with “Bearer ” followed by access_token (e.g. <code>Bearer eyJraWQiOi...Jzc29zIiwiY</code>)</td></tr><tr><td><strong>Content type</strong></td><td>string</td><td>Mandatory</td><td>The media type of the resource (e.g. application/json)</td></tr></tbody></table>

#### Request Body

Here is the sample of request body to get status of E-Wallet :&#x20;

```json
{
   "originalPartnerReferenceNo":"INV_SHOPEE_202407250004",
   "serviceCode":"55",
   "transactionDate":"2020-12-21T14:56:11+07:00",
   "amount":{
      "value":"2000.00",
      "currency":"IDR"
   },
   "merchantId":"23489182303312",
   "subMerchantId":"23489182303312",
   "externalStoreId":"183908924912387",
   "additionalInfo":{
      "deviceId":"12345679237",
      "channel":"mobilephone"
   }
}
```

| Parameter                  | Type   | Mandatory | Description                                                |
| -------------------------- | ------ | --------- | ---------------------------------------------------------- |
| originalPartnerReferenceNo | string | Optional  | Original transaction identifier on service consumer system |
| originalReferenceNo        | string | Optional  | Original transaction identifier on service provider system |
| originalExternalId         | string | Optional  | Original External-ID on header message                     |
| serviceCode                | string | Mandatory | API type indicator. Use : 55 for Check Status API          |
| transactionDate            | string | Optional  | transaction date : ISO 8601                                |
| amount                     | object | Optional  | Value and Currency                                         |
| merchantId                 | string | Optional  | Merchant identifier that is unique per each merchant       |
| subMerchantId              | string | Optional  | Sub merchant ID                                            |
| externalStoreId            | string | Optional  | External Store ID for merchant                             |
| additionalInfo             | object | Optional  | Additional information                                     |

### API Response

* **OVO Open API Sale**
* **OVO Open API Recurring**
* **ShopeePay**
* **DANA**

#### Response Body

The response will be similar to HTTP notification. Some parameters might not be presented in certain status cases, please check our Postman Collection to try it yourself.

#### **OVO Open API Sale**

{% tabs %}
{% tab title="Pending" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>   "responseCode":"2005500",
   "responseMessage":"Successful",
   "originalPartnerReferenceNo":"2020102900000000000001",
   "originalReferenceNo":"2020102977770000000009",
   "originalExternalId":"30443786930722726463280097920912",
   "serviceCode":"55",
   "latestTransactionStatus":"03",
   "transactionStatusDesc":"PENDING",
   "originalResponseCode":"2005503",
   "originalResponseMessage":"Request has been processed successfully",
   "paidTime":"2020-12-21T14:56:11+07:00",
   "transAmount":{
      "value":"112345678.00",
      "currency":"IDR"
   },
   "additionalInfo":{
      "acquirer": {
         "id" : "OVO SNAP Direct Debit"
      }
   }
}
</code></pre>

{% endtab %}

{% tab title="Success Payment" %}

```json
{
   "responseCode":"2005500",
   "responseMessage":"Successful",
   "originalPartnerReferenceNo":"2020102900000000000001",
   "originalReferenceNo":"2020102977770000000009",
   "originalExternalId":"30443786930722726463280097920912",
   "serviceCode":"55",
   "latestTransactionStatus":"00",
   "transactionStatusDesc":"SUCCESS",
   "originalResponseCode":"2005503",
   "originalResponseMessage":"Request has been processed successfully",
   "paidTime":"2020-12-21T14:56:11+07:00",
   "transAmount":{
      "value":"112345678.00",
      "currency":"IDR"
   },
   "additionalInfo":{
      "acquirer": {
         "id" : "OVO SNAP Direct Debit"
      }
   }
}
```

{% endtab %}

{% tab title="Refund" %}

```json
{
    "responseCode": "2005500",
    "responseMessage": "Successful",
    "originalPartnerReferenceNo": "INV_SHOPEE_20260701002",
    "originalReferenceNo": "C3fl1d4sNn",
    "originalExternalId": "693036698",
    "serviceCode": "55",
    "latestTransactionStatus": "04",
    "transactionStatusDesc": "REFUNDED",
    "originalResponseCode": "2005400",
    "originalResponseMessage": "Successful",
    "paidTime": "2025-07-01T11:40:54+07:00",
    "transAmount": {
        "value": "500000.00",
        "currency": "IDR"
    },
    "refundHistory": [
        {
            "refundNo": "REFUND_NO_SdvDY8",
            "partnerReferenceNo": "INV_SHOPEE_20260701002",
            "refundAmount": {
                "value": "10000.00",
                "currency": "IDR"
            },
            "refundStatus": "00",
            "refundDate": "2025-07-01T11:50:53+07:00",
            "partnerRefundNo": "RFN_SHOPEE_20260701002_1"
        }
    ],
    "additionalInfo": {
        "acquirer": {
            "id": "OVO SNAP Direct Debit"
        }
    }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Pending" %}

| Parameter                    | Type         | Mandatory   | Description                                                                                                                                                                                                                 |
| ---------------------------- | ------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `responseCode`               | String (7)   | Mandatory   | Response Code                                                                                                                                                                                                               |
| `responseMessage`            | String (150) | Mandatory   | Response Description                                                                                                                                                                                                        |
| `originalReferenceNo`        | String (200) | Conditional | Original transaction identifier on service provider system.                                                                                                                                                                 |
| `originalPartnerReferenceNo` | String       | Optional    | Original transaction identifier on service consumer system                                                                                                                                                                  |
| `originalExternalId`         | String       | Optional    | Original External-ID on header message                                                                                                                                                                                      |
| `serviceCode`                | String       | Mandatory   | Transaction type indicator 55                                                                                                                                                                                               |
| `latestTransactionStatus`    | String       | Mandatory   | <p>Unique identifier for this Payment from PJP. Mandatory if Payment happened. <br><br>00 = Success<br>01 = Initiated<br>02 = Paying<br>03 = Pending<br>04 = Refunded<br>05 = Canceled<br>06 = Failed<br>07 = Not Found</p> |
| `transactionStatusDesc`      | String       | Optional    | Description status transaction                                                                                                                                                                                              |
| `originalResponseCode`       | String       | Optional    | Response code                                                                                                                                                                                                               |
| `originalResponseMessage`    | String       | Optional    | Response description                                                                                                                                                                                                        |
| `transAmount`                | object       | Optional    | Transaction amount that will be paid using this payment method If it's IDR then value includes 2 decimal digits.                                                                                                            |
| `paidTime`                   | String       | Conditional | transaction date : ISO 8601                                                                                                                                                                                                 |
| `additionalInfo`             | object       | Mandatory   | Additional information                                                                                                                                                                                                      |
| {% endtab %}                 |              |             |                                                                                                                                                                                                                             |

{% tab title="Success Payment" %}

| Parameter                    | Type         | Mandatory   | Description                                                                                                                                                                                                                 |
| ---------------------------- | ------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `responseCode`               | String (7)   | Mandatory   | Response Code                                                                                                                                                                                                               |
| `responseMessage`            | String (150) | Mandatory   | Response Description                                                                                                                                                                                                        |
| `originalReferenceNo`        | String (200) | Conditional | Original transaction identifier on service provider system.                                                                                                                                                                 |
| `originalPartnerReferenceNo` | String       | Optional    | Original transaction identifier on service consumer system                                                                                                                                                                  |
| `originalExternalId`         | String       | Optional    | Original External-ID on header message                                                                                                                                                                                      |
| `serviceCode`                | String       | Mandatory   | Transaction type indicator 55                                                                                                                                                                                               |
| `latestTransactionStatus`    | String       | Mandatory   | <p>Unique identifier for this Payment from PJP. Mandatory if Payment happened. <br><br>00 = Success<br>01 = Initiated<br>02 = Paying<br>03 = Pending<br>04 = Refunded<br>05 = Canceled<br>06 = Failed<br>07 = Not Found</p> |
| `transactionStatusDesc`      | String       | Optional    | Description status transaction                                                                                                                                                                                              |
| `originalResponseCode`       | String       | Optional    | Response code                                                                                                                                                                                                               |
| `originalResponseMessage`    | String       | Optional    | Response description                                                                                                                                                                                                        |
| `transAmount`                | object       | Optional    | Transaction amount that will be paid using this payment method If it's IDR then value includes 2 decimal digits.                                                                                                            |
| `paidTime`                   | String       | Conditional | transaction date : ISO 8601                                                                                                                                                                                                 |
| `additionalInfo`             | object       | Mandatory   | Additional information                                                                                                                                                                                                      |
| {% endtab %}                 |              |             |                                                                                                                                                                                                                             |

{% tab title="Refund" %}

| Parameter                    | Type         | Mandatory   | Description                                                                                                                                                                                                                 |
| ---------------------------- | ------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `responseCode`               | String (7)   | Mandatory   | Response Code                                                                                                                                                                                                               |
| `responseMessage`            | String (150) | Mandatory   | Response Description                                                                                                                                                                                                        |
| `originalReferenceNo`        | String (200) | Conditional | Original transaction identifier on service provider system.                                                                                                                                                                 |
| `originalPartnerReferenceNo` | String       | Optional    | Original transaction identifier on service consumer system                                                                                                                                                                  |
| `approvalCode`               | String       | Optional    | Unique number                                                                                                                                                                                                               |
| `originalExternalId`         | String       | Optional    | Original External-ID on header message                                                                                                                                                                                      |
| `serviceCode`                | String       | Mandatory   | Transaction type indicator (service code of the original transaction request)                                                                                                                                               |
| `latestTransactionStatus`    | String       | Mandatory   | <p>Unique identifier for this Payment from PJP. Mandatory if Payment happened. <br><br>00 = Success<br>01 = Initiated<br>02 = Paying<br>03 = Pending<br>04 = Refunded<br>05 = Canceled<br>06 = Failed<br>07 = Not Found</p> |
| `transactionStatusDesc`      | String       | Optional    | Description status transaction                                                                                                                                                                                              |
| `originalResponseCode`       | String       | Optional    | Response code                                                                                                                                                                                                               |
| `originalResponseMessage`    | String       | Optional    | Response description                                                                                                                                                                                                        |
| `refundNo`                   | String       | Conditional | Transaction Identifier on Service Provider System                                                                                                                                                                           |
| `partnerReferenceNo`         | String       | Conditional | ReferenceNumber from PJP AIS for the refund.                                                                                                                                                                                |
| `refundAmount`               | object       | Optional    | Net amount of the refund                                                                                                                                                                                                    |
| `refundStatus`               | String       | Conditional | 00 = Success                                                                                                                                                                                                                |
| `refundDate`                 | String       | Conditional | <p>(ISO 8601) <br>Transaction date : dd-MM-yyyy ( Mandatory )<br><br>HH:mm:Ss ( Optional )</p>                                                                                                                              |
| `reason`                     | String       | Optional    | Refund reason.                                                                                                                                                                                                              |
| `transAmount`                | object       | Optional    | Transaction amount that will be paid using this payment method If it's IDR then value includes 2 decimal digits.                                                                                                            |
| `paidTime`                   | String       | Conditional | transaction date : ISO 8601                                                                                                                                                                                                 |
| `additionalInfo`             | object       | Mandatory   | Additional information                                                                                                                                                                                                      |
| {% endtab %}                 |              |             |                                                                                                                                                                                                                             |
| {% endtabs %}                |              |             |                                                                                                                                                                                                                             |

#### **OVO Open API Recurring**

{% tabs %}
{% tab title="Success Payment" %}

```json
{
   "responseCode":"2005500",
   "responseMessage":"Successful",
   "originalPartnerReferenceNo":"2020102900000000000001",
   "originalReferenceNo":"2020102977770000000009",
   "originalExternalId":"30443786930722726463280097920912",
   "serviceCode":"55",
   "latestTransactionStatus":"00",
   "transactionStatusDesc":"SUCCESS",
   "originalResponseCode":"2005500",
   "originalResponseMessage":"Request has been processed successfully",
   "paidTime":"2020-12-21T14:56:11+07:00",
   "transAmount":{
      "value":"112345678.00",
      "currency":"IDR"
   },
   "additionalInfo":{
      "acquirer": {
         "id" : "OVO SNAP Direct Debit"
      }
   }
}
```

{% endtab %}

{% tab title="Refund" %}

```json
{
    "responseCode": "2005500",
    "responseMessage": "Successful",
    "originalPartnerReferenceNo": "INV_SHOPEE_20260701002",
    "originalReferenceNo": "C3fl1d4sNn",
    "originalExternalId": "693036698",
    "serviceCode": "55",
    "latestTransactionStatus": "04",
    "transactionStatusDesc": "REFUNDED",
    "originalResponseCode": "2005400",
    "originalResponseMessage": "Successful",
    "paidTime": "2025-07-01T11:40:54+07:00",
    "transAmount": {
        "value": "500000.00",
        "currency": "IDR"
    },
    "refundHistory": [
        {
            "refundNo": "REFUND_NO_SdvDY8",
            "partnerReferenceNo": "INV_SHOPEE_20260701002",
            "refundAmount": {
                "value": "10000.00",
                "currency": "IDR"
            },
            "refundStatus": "00",
            "refundDate": "2025-07-01T11:50:53+07:00",
            "partnerRefundNo": "RFN_SHOPEE_20260701002_1"
        }
    ],
    "additionalInfo": {
        "acquirer": {
            "id": "OVO SNAP Direct Debit"
        }
    }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Success Payment" %}

| Parameter                    | Type         | Mandatory   | Description                                                                                                                                                                                                                 |
| ---------------------------- | ------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `responseCode`               | String (7)   | Mandatory   | Response Code                                                                                                                                                                                                               |
| `responseMessage`            | String (150) | Mandatory   | Response Description                                                                                                                                                                                                        |
| `originalReferenceNo`        | String (200) | Conditional | Original transaction identifier on service provider system.                                                                                                                                                                 |
| `originalPartnerReferenceNo` | String       | Optional    | Original transaction identifier on service consumer system                                                                                                                                                                  |
| `originalExternalId`         | String       | Optional    | Original External-ID on header message                                                                                                                                                                                      |
| `serviceCode`                | String       | Mandatory   | Transaction type indicator 55                                                                                                                                                                                               |
| `latestTransactionStatus`    | String       | Mandatory   | <p>Unique identifier for this Payment from PJP. Mandatory if Payment happened. <br><br>00 = Success<br>01 = Initiated<br>02 = Paying<br>03 = Pending<br>04 = Refunded<br>05 = Canceled<br>06 = Failed<br>07 = Not Found</p> |
| `transactionStatusDesc`      | String       | Optional    | Description status transaction                                                                                                                                                                                              |
| `originalResponseCode`       | String       | Optional    | Response code                                                                                                                                                                                                               |
| `originalResponseMessage`    | String       | Optional    | Response description                                                                                                                                                                                                        |
| `transAmount`                | object       | Optional    | Transaction amount that will be paid using this payment method If it's IDR then value includes 2 decimal digits.                                                                                                            |
| `paidTime`                   | String       | Conditional | transaction date : ISO 8601                                                                                                                                                                                                 |
| `additionalInfo`             | object       | Mandatory   | Additional information                                                                                                                                                                                                      |
| {% endtab %}                 |              |             |                                                                                                                                                                                                                             |

{% tab title="Refund" %}

| Parameter                    | Type         | Mandatory   | Description                                                                                                                                                                                                                 |
| ---------------------------- | ------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `responseCode`               | String (7)   | Mandatory   | Response Code                                                                                                                                                                                                               |
| `responseMessage`            | String (150) | Mandatory   | Response Description                                                                                                                                                                                                        |
| `originalReferenceNo`        | String (200) | Conditional | Original transaction identifier on service provider system.                                                                                                                                                                 |
| `originalPartnerReferenceNo` | String       | Optional    | Original transaction identifier on service consumer system                                                                                                                                                                  |
| `approvalCode`               | String       | Optional    | Unique number                                                                                                                                                                                                               |
| `originalExternalId`         | String       | Optional    | Original External-ID on header message                                                                                                                                                                                      |
| `serviceCode`                | String       | Mandatory   | Transaction type indicator (service code of the original transaction request)                                                                                                                                               |
| `latestTransactionStatus`    | String       | Mandatory   | <p>Unique identifier for this Payment from PJP. Mandatory if Payment happened. <br><br>00 = Success<br>01 = Initiated<br>02 = Paying<br>03 = Pending<br>04 = Refunded<br>05 = Canceled<br>06 = Failed<br>07 = Not Found</p> |
| `transactionStatusDesc`      | String       | Optional    | Description status transaction                                                                                                                                                                                              |
| `originalResponseCode`       | String       | Optional    | Response code                                                                                                                                                                                                               |
| `originalResponseMessage`    | String       | Optional    | Response description                                                                                                                                                                                                        |
| `refundNo`                   | String       | Conditional | Transaction Identifier on Service Provider System                                                                                                                                                                           |
| `partnerReferenceNo`         | String       | Conditional | ReferenceNumber from PJP AIS for the refund.                                                                                                                                                                                |
| `refundAmount`               | object       | Optional    | Net amount of the refund                                                                                                                                                                                                    |
| `refundStatus`               | String       | Conditional | 00 = Success                                                                                                                                                                                                                |
| `refundDate`                 | String       | Conditional | <p>(ISO 8601) <br>Transaction date : dd-MM-yyyy ( Mandatory )<br><br>HH:mm:Ss ( Optional )</p>                                                                                                                              |
| `reason`                     | String       | Optional    | Refund reason.                                                                                                                                                                                                              |
| `transAmount`                | object       | Optional    | Transaction amount that will be paid using this payment method If it's IDR then value includes 2 decimal digits.                                                                                                            |
| `paidTime`                   | String       | Conditional | transaction date : ISO 8601                                                                                                                                                                                                 |
| `additionalInfo`             | object       | Mandatory   | Additional information                                                                                                                                                                                                      |
| {% endtab %}                 |              |             |                                                                                                                                                                                                                             |
| {% endtabs %}                |              |             |                                                                                                                                                                                                                             |

#### **ShopeePay**

{% tabs %}
{% tab title="Pending" %}

```json
{
    "responseCode": "2005500",
    "responseMessage": "Successful",
    "originalPartnerReferenceNo": "INV_SHOPEE_20231130115650",
    "originalExternalId": "UAT_20231130115650143",
    "serviceCode": "54",
    "latestTransactionStatus": "03",
    "transactionStatusDesc": "PENDING",
    "originalResponseCode": "2005400",
    "originalResponseMessage": "Successful",
    "paidTime": "2023-11-30 11:56:50",
    "transAmount": {
        "value": "100000.00",
        "currency": "IDR"
    },
    "additionalInfo": {
        "acquirer": {
            "id": "SHOPEE_PAY"
        }
    }
}
```

{% endtab %}

{% tab title="Success" %}

```json
{
    "responseCode": "2005500",
    "responseMessage": "Successful",
    "originalPartnerReferenceNo": "INV_SHOPEE_20231130115650",
    "originalReferenceNo": "h0v9Z34vyX",
    "originalExternalId": "UAT_20231130115650143",
    "serviceCode": "54",
    "latestTransactionStatus": "00",
    "transactionStatusDesc": "SUCCESS",
    "originalResponseCode": "2005400",
    "originalResponseMessage": "Successful",
    "paidTime": "2023-11-30 11:59:31",
    "transAmount": {
        "value": "100000.00",
        "currency": "IDR"
    },
    "additionalInfo": {
        "acquirer": {
            "id": "SHOPEE_PAY"
        }
    }
}
```

{% endtab %}

{% tab title="Refund" %}

```json
{
    "responseCode": "2005500",
    "responseMessage": "Successful",
    "originalPartnerReferenceNo": "INV_SHOPEE_20260701002",
    "originalReferenceNo": "C3fl1d4sNn",
    "originalExternalId": "693036698",
    "serviceCode": "55",
    "latestTransactionStatus": "04",
    "transactionStatusDesc": "REFUNDED",
    "originalResponseCode": "2005400",
    "originalResponseMessage": "Successful",
    "paidTime": "2025-07-01T11:40:54+07:00",
    "transAmount": {
        "value": "500000.00",
        "currency": "IDR"
    },
    "refundHistory": [
        {
            "refundNo": "REFUND_NO_SdvDY8",
            "partnerReferenceNo": "INV_SHOPEE_20260701002",
            "refundAmount": {
                "value": "10000.00",
                "currency": "IDR"
            },
            "refundStatus": "00",
            "refundDate": "2025-07-01T11:50:53+07:00",
            "partnerRefundNo": "RFN_SHOPEE_20260701002_1"
        }
    ],
    "additionalInfo": {
        "acquirer": {
            "id": "SHOPEE_PAY"
        }
    }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Pending" %}

| Parameter                    | Type         | Mandatory   | Description                                                                                                                                                                                                                 |
| ---------------------------- | ------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `responseCode`               | String (7)   | Mandatory   | Response Code                                                                                                                                                                                                               |
| `responseMessage`            | String (150) | Mandatory   | Response Description                                                                                                                                                                                                        |
| `originalReferenceNo`        | String (200) | Conditional | Original transaction identifier on service provider system.                                                                                                                                                                 |
| `originalPartnerReferenceNo` | String       | Optional    | Original transaction identifier on service consumer system                                                                                                                                                                  |
| `originalExternalId`         | String       | Optional    | Original External-ID on header message                                                                                                                                                                                      |
| `serviceCode`                | String       | Mandatory   | Transaction type indicator 55                                                                                                                                                                                               |
| `latestTransactionStatus`    | String       | Mandatory   | <p>Unique identifier for this Payment from PJP. Mandatory if Payment happened. <br><br>00 = Success<br>01 = Initiated<br>02 = Paying<br>03 = Pending<br>04 = Refunded<br>05 = Canceled<br>06 = Failed<br>07 = Not Found</p> |
| `transactionStatusDesc`      | String       | Optional    | Description status transaction                                                                                                                                                                                              |
| `originalResponseCode`       | String       | Optional    | Response code                                                                                                                                                                                                               |
| `originalResponseMessage`    | String       | Optional    | Response description                                                                                                                                                                                                        |
| `transAmount`                | object       | Optional    | Transaction amount that will be paid using this payment method If it's IDR then value includes 2 decimal digits.                                                                                                            |
| `paidTime`                   | String       | Conditional | transaction date : ISO 8601                                                                                                                                                                                                 |
| `additionalInfo`             | object       | Mandatory   | Additional information                                                                                                                                                                                                      |
| {% endtab %}                 |              |             |                                                                                                                                                                                                                             |

{% tab title="Success" %}

| Parameter                    | Type         | Mandatory   | Description                                                                                                                                                                                                                 |
| ---------------------------- | ------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `responseCode`               | String (7)   | Mandatory   | Response Code                                                                                                                                                                                                               |
| `responseMessage`            | String (150) | Mandatory   | Response Description                                                                                                                                                                                                        |
| `originalReferenceNo`        | String (200) | Conditional | Original transaction identifier on service provider system.                                                                                                                                                                 |
| `originalPartnerReferenceNo` | String       | Optional    | Original transaction identifier on service consumer system                                                                                                                                                                  |
| `originalExternalId`         | String       | Optional    | Original External-ID on header message                                                                                                                                                                                      |
| `serviceCode`                | String       | Mandatory   | Transaction type indicator 55                                                                                                                                                                                               |
| `latestTransactionStatus`    | String       | Mandatory   | <p>Unique identifier for this Payment from PJP. Mandatory if Payment happened. <br><br>00 = Success<br>01 = Initiated<br>02 = Paying<br>03 = Pending<br>04 = Refunded<br>05 = Canceled<br>06 = Failed<br>07 = Not Found</p> |
| `transactionStatusDesc`      | String       | Optional    | Description status transaction                                                                                                                                                                                              |
| `originalResponseCode`       | String       | Optional    | Response code                                                                                                                                                                                                               |
| `originalResponseMessage`    | String       | Optional    | Response description                                                                                                                                                                                                        |
| `transAmount`                | object       | Optional    | Transaction amount that will be paid using this payment method If it's IDR then value includes 2 decimal digits.                                                                                                            |
| `paidTime`                   | String       | Conditional | transaction date : ISO 8601                                                                                                                                                                                                 |
| `additionalInfo`             | object       | Mandatory   | Additional information                                                                                                                                                                                                      |
| {% endtab %}                 |              |             |                                                                                                                                                                                                                             |

{% tab title="Refund" %}

| Parameter                    | Type         | Mandatory   | Description                                                                                                                                                                                                                 |
| ---------------------------- | ------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `responseCode`               | String (7)   | Mandatory   | Response Code                                                                                                                                                                                                               |
| `responseMessage`            | String (150) | Mandatory   | Response Description                                                                                                                                                                                                        |
| `originalReferenceNo`        | String (200) | Conditional | Original transaction identifier on service provider system.                                                                                                                                                                 |
| `originalPartnerReferenceNo` | String       | Optional    | Original transaction identifier on service consumer system                                                                                                                                                                  |
| `originalExternalId`         | String       | Optional    | Original External-ID on header message                                                                                                                                                                                      |
| `serviceCode`                | String       | Mandatory   | Transaction type indicator 55                                                                                                                                                                                               |
| `latestTransactionStatus`    | String       | Mandatory   | <p>Unique identifier for this Payment from PJP. Mandatory if Payment happened. <br><br>00 = Success<br>01 = Initiated<br>02 = Paying<br>03 = Pending<br>04 = Refunded<br>05 = Canceled<br>06 = Failed<br>07 = Not Found</p> |
| `transactionStatusDesc`      | String       | Optional    | Description status transaction                                                                                                                                                                                              |
| `originalResponseCode`       | String       | Optional    | Response code                                                                                                                                                                                                               |
| `originalResponseMessage`    | String       | Optional    | Response description                                                                                                                                                                                                        |
| `transAmount`                | object       | Optional    | Transaction amount that will be paid using this payment method If it's IDR then value includes 2 decimal digits.                                                                                                            |
| `paidTime`                   | String       | Conditional | transaction date : ISO 8601                                                                                                                                                                                                 |
| `additionalInfo`             | object       | Mandatory   | Additional information                                                                                                                                                                                                      |
| {% endtab %}                 |              |             |                                                                                                                                                                                                                             |
| {% endtabs %}                |              |             |                                                                                                                                                                                                                             |

#### **DANA**

{% tabs %}
{% tab title="Pending" %}

```json
{
    "responseCode": "2005500",
    "responseMessage": "Successful",
    "originalPartnerReferenceNo": "INV20240711007",
    "originalReferenceNo": "rarPxBRuvdByoOnbmUrQqtVyz6UdgUgik2M0yyR98l10EeadmVnnq62pVMPCMR8W",
    "originalExternalId": "307350227",
    "serviceCode": "55",
    "latestTransactionStatus": "03",
    "transactionStatusDesc": "PENDING",
    "originalResponseCode": "2005400",
    "originalResponseMessage": "Successful",
    "paidTime": "2024-07-11T14:23:55+07:00",
    "transAmount": {
        "value": "1.00",
        "currency": "IDR"
    },
    "additionalInfo": {
        "acquirer": {
            "id": "DANA Snap Direct Debit"
        }
    }
}
```

{% endtab %}

{% tab title="Success" %}

```json
{
    "responseCode": "2005500",
    "responseMessage": "Successful",
    "originalPartnerReferenceNo": "INV20240723006",
    "originalReferenceNo": "20240723111212800110166234101713965",
    "originalExternalId": "209469647",
    "serviceCode": "55",
    "latestTransactionStatus": "00",
    "transactionStatusDesc": "SUCCESS",
    "originalResponseCode": "2005400",
    "originalResponseMessage": "Successful",
    "paidTime": "2024-07-23T16:55:29+07:00",
    "transAmount": {
        "value": "1.00",
        "currency": "IDR"
    },
    "additionalInfo": {
        "acquirer": {
            "id": "DANA Snap Direct Debit"
        }
    }
}
```

{% endtab %}

{% tab title="Refund" %}

```json
{
    "responseCode": "2005500",
    "responseMessage": "Successful",
    "originalPartnerReferenceNo": "INV_SHOPEE_20260701002",
    "originalReferenceNo": "C3fl1d4sNn",
    "originalExternalId": "693036698",
    "serviceCode": "55",
    "latestTransactionStatus": "04",
    "transactionStatusDesc": "REFUNDED",
    "originalResponseCode": "2005400",
    "originalResponseMessage": "Successful",
    "paidTime": "2025-07-01T11:40:54+07:00",
    "transAmount": {
        "value": "500000.00",
        "currency": "IDR"
    },
    "refundHistory": [
        {
            "refundNo": "REFUND_NO_SdvDY8",
            "partnerReferenceNo": "INV_SHOPEE_20260701002",
            "refundAmount": {
                "value": "10000.00",
                "currency": "IDR"
            },
            "refundStatus": "00",
            "refundDate": "2025-07-01T11:50:53+07:00",
            "partnerRefundNo": "RFN_SHOPEE_20260701002_1"
        }
    ],
    "additionalInfo": {
        "acquirer": {
            "id": "DANA Snap Direct Debit"
        }
    }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Pending" %}

| Parameter                    | Type         | Mandatory   | Description                                                                                                                                                                                                                 |
| ---------------------------- | ------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `responseCode`               | String (7)   | Mandatory   | Response Code                                                                                                                                                                                                               |
| `responseMessage`            | String (150) | Mandatory   | Response Description                                                                                                                                                                                                        |
| `originalReferenceNo`        | String (200) | Conditional | Original transaction identifier on service provider system.                                                                                                                                                                 |
| `originalPartnerReferenceNo` | String       | Optional    | Original transaction identifier on service consumer system                                                                                                                                                                  |
| `originalExternalId`         | String       | Optional    | Original External-ID on header message                                                                                                                                                                                      |
| `serviceCode`                | String       | Mandatory   | Transaction type indicator 55                                                                                                                                                                                               |
| `latestTransactionStatus`    | String       | Mandatory   | <p>Unique identifier for this Payment from PJP. Mandatory if Payment happened. <br><br>00 = Success<br>01 = Initiated<br>02 = Paying<br>03 = Pending<br>04 = Refunded<br>05 = Canceled<br>06 = Failed<br>07 = Not Found</p> |
| `transactionStatusDesc`      | String       | Optional    | Description status transaction                                                                                                                                                                                              |
| `originalResponseCode`       | String       | Optional    | Response code                                                                                                                                                                                                               |
| `originalResponseMessage`    | String       | Optional    | Response description                                                                                                                                                                                                        |
| `transAmount`                | object       | Optional    | Transaction amount that will be paid using this payment method If it's IDR then value includes 2 decimal digits.                                                                                                            |
| `paidTime`                   | String       | Conditional | transaction date : ISO 8601                                                                                                                                                                                                 |
| `additionalInfo`             | object       | Mandatory   | Additional information                                                                                                                                                                                                      |
| {% endtab %}                 |              |             |                                                                                                                                                                                                                             |

{% tab title="Success" %}

| Parameter                          | Type         | Mandatory   | Description                                                                                                                                                                                                                 |
| ---------------------------------- | ------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `responseCode`                     | String (7)   | Mandatory   | Response Code                                                                                                                                                                                                               |
| `responseMessage`                  | String (150) | Mandatory   | Response Description                                                                                                                                                                                                        |
| `originalReferenceNo`              | String (200) | Conditional | Original transaction identifier on service provider system.                                                                                                                                                                 |
| `originalPartnerReferenceNo`       | String       | Optional    | Original transaction identifier on service consumer system                                                                                                                                                                  |
| `originalExternalId`               | String       | Optional    | Original External-ID on header message                                                                                                                                                                                      |
| `serviceCode`                      | String       | Mandatory   | Transaction type indicator 55                                                                                                                                                                                               |
| `latestTransactionStatus`          | String       | Mandatory   | <p>Unique identifier for this Payment from PJP. Mandatory if Payment happened. <br><br>00 = Success<br>01 = Initiated<br>02 = Paying<br>03 = Pending<br>04 = Refunded<br>05 = Canceled<br>06 = Failed<br>07 = Not Found</p> |
| `transactionStatusDesc`            | String       | Optional    | Description status transaction                                                                                                                                                                                              |
| `originalResponseCode`             | String       | Optional    | Response code                                                                                                                                                                                                               |
| `originalResponseMessage`          | String       | Optional    | Response description                                                                                                                                                                                                        |
| `transAmount`                      | object       | Optional    | Transaction amount that will be paid using this payment method If it's IDR then value includes 2 decimal digits.                                                                                                            |
| `refundHistory.refundNo`           | string       | Optional    | Transaction Identifier on Service Provider System                                                                                                                                                                           |
| `refundHistory.partnerReferenceNo` | string       | Mandatory   | Transaction Identifier No                                                                                                                                                                                                   |
| `refundAmount`                     | object       | Mandatory   | Refund Amount                                                                                                                                                                                                               |
| `refundStatus`                     | string       | Mandatory   | Refund Status                                                                                                                                                                                                               |
| `refundDate`                       | string       | Optional    | Refund Date                                                                                                                                                                                                                 |
| `paidTime`                         | String       | Conditional | transaction date : ISO 8601                                                                                                                                                                                                 |
| `additionalInfo`                   | object       | Mandatory   | Additional information                                                                                                                                                                                                      |
| {% endtab %}                       |              |             |                                                                                                                                                                                                                             |

{% tab title="Refund" %}

| Parameter                    | Type         | Mandatory   | Description                                                                                                                                                                                                                 |
| ---------------------------- | ------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `responseCode`               | String (7)   | Mandatory   | Response Code                                                                                                                                                                                                               |
| `responseMessage`            | String (150) | Mandatory   | Response Description                                                                                                                                                                                                        |
| `originalReferenceNo`        | String (200) | Conditional | Original transaction identifier on service provider system.                                                                                                                                                                 |
| `originalPartnerReferenceNo` | String       | Optional    | Original transaction identifier on service consumer system                                                                                                                                                                  |
| `originalExternalId`         | String       | Optional    | Original External-ID on header message                                                                                                                                                                                      |
| `serviceCode`                | String       | Mandatory   | Transaction type indicator 55                                                                                                                                                                                               |
| `latestTransactionStatus`    | String       | Mandatory   | <p>Unique identifier for this Payment from PJP. Mandatory if Payment happened. <br><br>00 = Success<br>01 = Initiated<br>02 = Paying<br>03 = Pending<br>04 = Refunded<br>05 = Canceled<br>06 = Failed<br>07 = Not Found</p> |
| `transactionStatusDesc`      | String       | Optional    | Description status transaction                                                                                                                                                                                              |
| `originalResponseCode`       | String       | Optional    | Response code                                                                                                                                                                                                               |
| `originalResponseMessage`    | String       | Optional    | Response description                                                                                                                                                                                                        |
| `transAmount`                | object       | Optional    | Transaction amount that will be paid using this payment method If it's IDR then value includes 2 decimal digits.                                                                                                            |
| `paidTime`                   | String       | Conditional | transaction date : ISO 8601                                                                                                                                                                                                 |
| `additionalInfo`             | object       | Mandatory   | Additional information                                                                                                                                                                                                      |
| {% endtab %}                 |              |             |                                                                                                                                                                                                                             |
| {% endtabs %}                |              |             |                                                                                                                                                                                                                             |


# Retrieve Payment Credential

To communicate with any DOKU API, make sure you have Client ID and Secret Key.

Follow the outlined steps to obtain the Client ID and Secret Key.

1. Login to your DOKU Dashboard.
2. On the Dashboard, go to Integrations > API Keys.&#x20;

   *API Keys* page is displayed.

<figure><img src="/files/SmXafueCt7Kz4EEbXZZc" alt=""><figcaption><p>API Keys Page Dashboard</p></figcaption></figure>

### **Save your payment credential**

You can save it in your device or anywhere you think is safe. Also, you can visit this page later if you need to see your payment credential.

{% hint style="info" %}
**CAUTION**

Please keep your Client ID and Secret Key confidential, especially your Production Client ID and Secret Key. It is your payment credential to accept payments.
{% endhint %}

### What's Next ?&#x20;

You now can start integrating with DOKU. You can choose which integration type that suits your business needs.


# DOKU Checkout

Checkout is a payment service that allows you as DOKU merchants to use our payment system, where DOKU's payment page pops up on your website after checkout. This is the easiest and the quickest way to integrate with DOKU without any hassles that suitable for every business needs from small businesses to enterprises.

With a single integration, Checkout allows you to accept payments from various DOKU payment channels. Here is the overview on how Checkout works :

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td></td><td>Your customers check out their orders on your checkout page</td><td></td><td><a href="/files/61AU0BaSvIu9f2kjsj0d">/files/61AU0BaSvIu9f2kjsj0d</a></td></tr><tr><td></td><td>DOKU Checkout payment page will pops up and your customer can choose their preferred payment methods</td><td></td><td><a href="/files/FGa8h2NG24MOrcGNKpPv">/files/FGa8h2NG24MOrcGNKpPv</a></td></tr><tr><td></td><td>Once your customer proceed the payment, you can redirect them to your defined page</td><td></td><td><a href="/files/fkQE3PhAMp6oPSiivKOC">/files/fkQE3PhAMp6oPSiivKOC</a></td></tr></tbody></table>

[<mark style="background-color:blue;">**Try DOKU Checkout Demo!**</mark> ](https://sandbox.doku.com/demo/checkout-api)

Furthermore, you may explore our developer tools like Libraries & Plugins or Postman Collections, aiming to accelerate the integration process with DOKU Checkout Page.


# Integration Guide

## Preparation for New Merchant&#x20;

There some step need to be prepared if you want to integrate with DOKU Checkout Page :

### User Registration

In this section, DOKU Dashboard sandbox environment is used to integration process to our Checkout page. Sandbox is use for testing purpose where you can explore our features without making any real payments. In DOKU, it is very easy to get Sandbox access and explore our products. You can create the account by following the steps [here](/get-started-with-doku-api/user-registration).

[**Retrieving API Keys**](/get-started-with-doku-api/retrieve-payment-credential)

Make sure you already have Client ID & Secret Key to continue this section. Please refer to this [section](/get-started-with-doku-api/retrieve-payment-credential).

### Integration Steps

Here is the overview of how to integrate with Checkout:

1. [Backend Integration to initiate payment](/accept-payments/doku-checkout/integration-guide/backend-integration)
2. [Frontend Integration to display DOKU Checkout Page](/accept-payments/doku-checkout/integration-guide/frontend-integration)
3. [Create payment simulation](/accept-payments/doku-checkout/integration-guide/simulate-payment-and-notification)
4. [Acknowledge payment result](/accept-payments/doku-checkout/integration-guide/simulate-payment-and-notification)

<figure><img src="/files/mnidfBhvnzRsP5JJseTS" alt=""><figcaption></figcaption></figure>


# Backend Integration

### Backend Integration to initiate payment[​](https://dashboard.doku.com/docs/docs/jokul-checkout/jokul-checkout-integration/#1-obtain-paymenturl-on-backend) <a href="#id-1-obtain-paymenturl-on-backend" id="id-1-obtain-paymenturl-on-backend"></a>

To obtain the `payment.url`, you will need to hit this API through your Backend :&#x20;

### Endpoint

<table><thead><tr><th width="241">Type</th><th>Value</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API endpoint (sandbox)</td><td><a href="https://api-sandbox.doku.com/checkout/v1/payment">https://api-sandbox.doku.com/checkout/v1/payment</a></td></tr><tr><td>API endpoint (production)</td><td><a href="https://api.doku.com/checkout/v1/payment">https://api.doku.com/checkout/v1/payment</a></td></tr></tbody></table>

***

### Request&#x20;

Here is the sample of request header to obtain `payment.url`:

```
Client-Id: MCH-0001-10791114622547
Request-Id: fdb69f47-96da-499d-acec-7cdc318ab2fe
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
```

### Request Header Explanation <a href="#id-1-obtain-paymenturl-on-backend" id="id-1-obtain-paymenturl-on-backend"></a>

<table><thead><tr><th width="167">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>client-id</code></strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong><code>request-id</code></strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong><code>request-timestamp</code></strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong><code>signature</code></strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="/pages/VogdJfoJtS2yXvClOsrc">this section</a> to generate the signature</td></tr></tbody></table>

Here is the sample of request body to obtain `payment.url`, you can send a simple request for a basic payment page and you can send the parameter according to your needs : &#x20;

{% tabs %}
{% tab title="Basic Request" %}

```json
{
    "order": {
        "amount": 20000,
        "invoice_number": "INV-20210231-0001"
    },
    "payment": {
        "payment_due_date": 60
    }
}
```

<table><thead><tr><th>Body Parameter</th><th width="122">Type</th><th>Mandatory</th><th valign="bottom">Description</th></tr></thead><tbody><tr><td><code>order.amount</code></td><td><code>number</code></td><td>Mandatory</td><td valign="bottom">In IDR Currency and without decimal<br>Max length: <code>12</code></td></tr><tr><td><code>order.invoice_number</code></td><td><code>string</code></td><td>Mandatory</td><td valign="bottom">Generated by merchant to identify the order. Max length: <code>64</code><br><strong>Notes:</strong> If you have Credit Card channel activated, the maximum length is <code>30</code> chars due to the acquirer's requirements<br><br>If you are using KKI, all the symbols are not allowed. Ensure you do not put any symbol on Invoice number value.</td></tr><tr><td><code>payment.payment_due_date</code></td><td><code>number</code></td><td>Optional</td><td valign="bottom">The payment due date of the checkout page in minutes. Default : 60 minutes. Max Length: 6</td></tr></tbody></table>

This basic request only could be implement for selected payment method, such as : &#x20;

1. Virtual Account
2. Credit Card
3. QRIS&#x20;
4. Convenience Store
5. E-money (OVO and Linkaja)
   {% endtab %}

{% tab title="Full Request" %}

```json
{
"order": {
  "amount": 80000,
  "invoice_number": "INV-{{$timestamp}}",
  "currency": "IDR",
  "callback_url": "http://merchantcallbackurl.domain/",
  "callback_url_cancel": "https://merchantcallbackurl-cancel.domain",
  "callback_url_result": "https://merchantcallbackurl-cancel.domain",
  "language":"EN",
  "auto_redirect":true,
  "disable_retry_payment" :true,
  "recover_abandoned_cart": true,
  "expired_recovered_cart":2,
  "line_items": [
    {
        "id":"001",
        "name":"Fresh flowers",
        "quantity":1,
        "price":40000,
        "sku": "FF01",
        "category": "gift-and-flowers",
        "url": "http://item-url.domain/",
        "image_url":"http://image-url.domain/",
        "type":"ABC"
    },
    {
        "id":"002",
        "name":"T-shirt",
        "quantity":1,
        "price":40000,
        "sku": "T01",
        "category": "clothing",
        "url": "http://item-url.domain/",
        "image_url":"http://image-url.domain/",
        "type":"ABC"
    }
  ]
},
  "payment": {
      "payment_due_date": 60,
      "type" : "SALE",
      "payment_method_types": [
          "VIRTUAL_ACCOUNT_BCA",
          "VIRTUAL_ACCOUNT_BANK_MANDIRI",
          "VIRTUAL_ACCOUNT_BANK_SYARIAH_MANDIRI",
          "VIRTUAL_ACCOUNT_DOKU",
          "VIRTUAL_ACCOUNT_BRI",
          "VIRTUAL_ACCOUNT_BNI",
          "VIRTUAL_ACCOUNT_BANK_PERMATA",
          "VIRTUAL_ACCOUNT_BANK_CIMB",
          "VIRTUAL_ACCOUNT_BANK_DANAMON",
          "VIRTUAL_ACCOUNT_BNC",
          "VIRTUAL_ACCOUNT_BTN",
          "ONLINE_TO_OFFLINE_ALFA",
          "CREDIT_CARD",
          "DIRECT_DEBIT_BRI",
          "EMONEY_SHOPEEPAY",
          "EMONEY_OVO",
          "EMONEY_DANA",
          "QRIS",
          "PEER_TO_PEER_AKULAKU",
          "PEER_TO_PEER_KREDIVO",
          "PEER_TO_PEER_INDODANA"
      ]
  },
  "customer":{
      "id":"JC-01",
      "name":"Service",
      "last_name":"Experience",
      "phone":"628121212121",
      "email": "sxp@example.com",
      "address":"Jalan DOKU no 15",
      "postcode":"120129",
      "state":"Jakarta",
      "city":"Jakarta Selatan",
      "country":"ID"
},
"shipping_address":{
  "first_name":"Service",
  "last_name":"Experience",
  "address":"Jalan DOKU no 15",
  "city":"Jakarta",
  "postal_code":"11923",
  "phone":"628121212121",
  "country_code":"IDN"
},
"billing_address":{
  "first_name":"Service",
  "last_name":"Experience",
  "address":"Jalan DOKU no 15",
  "city":"Jakarta",
  "postal_code":"11923",
  "phone":"628121212121",
  "country_code":"IDN"
},
"additional_info":{
  "allow_tenor" : [0,3,6,12],
  "doku_wallet_notify_url" : "https://dw-notification.merchantdomain",
  "override_notification_url": "https://another.example.com/payments/notifications"
}
}
```

**Request Body Explanation**

<table><thead><tr><th width="187">Body Parameter</th><th>Description</th></tr></thead><tbody><tr><td><a href="#order-object">order</a></td><td>Information about the order items.</td></tr><tr><td><a href="#payment-object">payment</a></td><td>Information about payment relation.</td></tr><tr><td><a href="#customer-object">customer</a></td><td>Specific information regarding the customer.</td></tr><tr><td><a href="#shipping-address-object">shipping_address</a></td><td>Specific information regarding the shipping address. Some payment methods are required to send this parameter.</td></tr><tr><td><a href="#billing-address-object">billing_address</a></td><td>Specific information regarding the billing address. There is payment method that required to send this parameter.</td></tr><tr><td><a href="#additional-info-object">additional_info</a></td><td>Some additional information parameter in order to fulfill non-mandatory parameters</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

#### Order object

```json
{
"order": {
  "amount": 80000,
  "invoice_number": "INV-{{$timestamp}}",
  "currency": "IDR",
  "callback_url": "http://merchantcallbackurl.domain/",
  "callback_url_cancel": "https://merchantcallbackurl-cancel.domain",
  "callback_url_result": "https://merchantcallbackurl-cancel.domain",
  "language":"EN",
  "auto_redirect":true,
  "disable_retry_payment" :true,
  "recover_abandoned_cart":true,
  "expired_recovered_cart":2,
  "line_items": [
    {
        "id":"001",
        "name":"Fresh flowers",
        "quantity":1,
        "price":40000,
        "sku": "FF01",
        "category": "gift-and-flowers",
        "url": "http://item-url.domain/",
        "image_url":"http://image-url.domain/",
        "type":"ABC"
    },
    {
        "id":"002",
        "name":"T-shirt",
        "quantity":1,
        "price":40000,
        "sku": "T01",
        "category": "clothing",
        "url": "http://item-url.domain/",
        "image_url":"http://image-url.domain/",
        "type":"ABC"
    }
  ]
}
```

<table><thead><tr><th>Body Parameter</th><th width="110">Type`</th><th width="151">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.amount</code></td><td>number</td><td>Mandatory</td><td>Order amount in IDR currency and without decimal. <br>Max length: <code>12</code></td></tr><tr><td><code>order.invoice_number</code></td><td>string</td><td>Mandatory</td><td><p>Unique identifier generated by merchant to identify the order.</p><p>Max length: <code>64</code>, except credit card which 30 chars only <br><br>If you are using KKI, all the symbols are not allowed. Ensure you do not put any symbol on Invoice number value.</p></td></tr><tr><td><code>order.currency</code></td><td>string</td><td>Optional</td><td>3 alphabetic currency code ISO 4217<br>Min-max Length: <code>3</code><br>Default value: <code>IDR</code></td></tr><tr><td><code>order.callback_url</code></td><td>string</td><td>Conditional,<br>Mandatory for Payment Methods : <strong>Jenius</strong>.</td><td>The "Back to Merchant" button is configured using the URL provided in <code>callback_url</code>. If only <code>callback_url</code> is set, it will apply to the "Back to Merchant" button on both the main page and the result page. However, if the merchant also sets <code>callback_url_result</code>, then <code>callback_url</code> will only affect the "Back to Merchant" button on the main page, while <code>callback_url_result</code> will specifically affect the button on the result page.</td></tr><tr><td><code>order.callback_url_cancel</code></td><td>string</td><td>Conditional,<br>Currently only available for payment methods : <strong>Indodana</strong></td><td>The URL specified for merchant redirection in the event of order cancellation.</td></tr><tr><td><code>order.callback_url_result</code></td><td>string</td><td>Optional</td><td>The URL designated for button "Back to merchant" in result page. </td></tr><tr><td><code>order.language</code></td><td>string</td><td>Optional</td><td>Default language shown when redirect to checkout page<br>Max length: <code>2</code></td></tr><tr><td><code>order.auto_redirect</code></td><td>boolean</td><td>Mandatory</td><td>When set to <strong>true</strong>, the transaction result page redirects to the callback URL; otherwise, it redirects to the payment result page.</td></tr><tr><td><code>order.disable_retry_payment</code></td><td>boolean</td><td>Conditional,<br>Only applied for payment methods : <code>Credit Card</code>, <code>DOKU Wallet</code>, <code>Akulaku</code>, <code>OVO</code>, <code>ShopeePay</code></td><td>This condition is applicable only when the merchant sends this parameter with a "true" value. If the merchant does not include this parameter, sends a "false" value, or if the customer fails to complete the payment, the result page will be displayed in the Checkout. From there, the customer can retry payment or modify their payment options if multiple channels are available.</td></tr><tr><td><code>order.recover_abandoned_cart</code></td><td>boolean</td><td>Conditional, only applicable for VA, O2O, and Credit Card</td><td>If you bring this parameter and set as <code>true</code>, your customer can recover their order than has been expired as long as the <code>expired_recover_cart</code> is not due yet.</td></tr><tr><td><code>order.expired_recovered_cart</code></td><td>number</td><td>Conditional, only applicable for VA, O2O, and Credit Card</td><td>This is the expired time of the order that is already recovered. The expired time's max length is 44640 minutes.</td></tr><tr><td><code>order.line_items.id</code></td><td>string</td><td>Conditional<br>Mandatory for Payment Methods : <strong>Akulaku, Kredivo, Indodana, Allobank</strong></td><td>Item ID of the item in this transaction.<br>Max Length: <code>64</code><br><br><code>Note :</code><br>If you are using KKI, all the symbols are not allowed. Ensure you do not put any symbol on Invoice number value.</td></tr><tr><td><code>order.line_items.name</code></td><td>string</td><td>Conditional,<br>Mandatory for Payment Methods : <strong>Jenius</strong>, <strong>Kredivo, Indodana, KKI, Akulaku, Allobank</strong></td><td>Name of the product item.<br>Max Length: <code>255</code><br><br><code>Note</code> <br>If you are using KKI, all the symbols are not allowed. Ensure you do not put any symbol.</td></tr><tr><td><code>order.line_items.price</code></td><td>number</td><td>Conditional, <br>Mandatory for Payment Methods : <strong>Jenius</strong>, <strong>Kredivo, Akulaku, Indodana, KKI, Allobank</strong></td><td>Price of the product item. Total price and quantity must match with the <code>order.amount</code>.<br><br><code>Note</code> <br>If you are using KKI, all the symbols are not allowed. Ensure you do not put any symbol.</td></tr><tr><td><code>order.line_items.quantity</code></td><td>number</td><td>Conditional,<br>Mandatory for Payment Methods : <strong>Jenius</strong>, <strong>Kredivo, Akulaku, Indodana, KKI, Allobank</strong></td><td>Quantity of the product item.<br><br><code>Note</code> <br>If you are using KKI, all the symbols are not allowed. Ensure you do not put any symbol.</td></tr><tr><td><code>order.line_items.sku</code></td><td>string</td><td>Conditional.<br>Mandatory for Payment Methods : <strong>Akulaku</strong>, <strong>Kredivo, Indodana</strong>.</td><td>SKU of the product item. </td></tr><tr><td><code>order.line_items.category</code></td><td>string</td><td>Conditional,<br>Mandatory for Payment Methods : <strong>Akulaku</strong>, <strong>Kredivo, Indodana</strong>.</td><td>Category of the product item. For Indodana, the category should be based on these <a href="#list-category">list</a>.</td></tr><tr><td><code>order.line_items.url</code></td><td>string</td><td>Conditional,<br>Mandatory for Payment Methods : <strong>Kredivo</strong> </td><td>URL to the product item on merchant site. </td></tr><tr><td><code>order.line_items.image_url</code></td><td>string</td><td>Conditional,<br>Mandatory for Payment Methods : <strong>Indodana</strong></td><td>URL the image of the product item on merchant site.</td></tr><tr><td><code>order.line_items.type</code></td><td>string</td><td>Conditional,<br>Mandatory for Payment Methods : <strong>Indodana, Kredivo</strong></td><td>Type of the item in this transaction.</td></tr></tbody></table>

#### Payment Object

```json
"payment": {
      "payment_due_date": 60,
      "type" : "SALE/INSTALLMENT/AUTHORIZE",
      "payment_method_types": [
          "VIRTUAL_ACCOUNT_BCA",
          "VIRTUAL_ACCOUNT_BANK_MANDIRI",
          "VIRTUAL_ACCOUNT_BANK_SYARIAH_MANDIRI",
          "VIRTUAL_ACCOUNT_DOKU",
          "VIRTUAL_ACCOUNT_BRI",
          "VIRTUAL_ACCOUNT_BNI",
          "VIRTUAL_ACCOUNT_BANK_PERMATA",
          "VIRTUAL_ACCOUNT_BANK_CIMB",
          "VIRTUAL_ACCOUNT_BANK_DANAMON",
          "ONLINE_TO_OFFLINE_ALFA",
          "CREDIT_CARD",
          "DIRECT_DEBIT_BRI",
          "EMONEY_SHOPEEPAY",
          "EMONEY_OVO",
          "QRIS",
          "PEER_TO_PEER_AKULAKU",
          "PEER_TO_PEER_KREDIVO",
          "PEER_TO_PEER_INDODANA"
      ]
  }
```

<table><thead><tr><th>Body parameter</th><th width="96">Type</th><th width="113">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>payment.payment_method_types</code></td><td>array</td><td>optional</td><td>Payment method that will shown to users in Checkout Page. <br>If you wish to showcase all available payment methods, simply omit sending this parameter, and all options will be visible. Alternatively, if you prefer to direct users to a specific payment method, include this parameter and specify the desired payment method by filling in its corresponding value.<br>The value are listed <a href="/pages/l39mDXwAt00KZ95yAsyE">here</a>.</td></tr><tr><td><code>payment.type</code></td><td>string</td><td>Optional</td><td><strong>Possible Value :</strong>  <br><code>"SALE", "INSTALLMENT", "AUTHORIZE"</code><br><br>If you set the type as Authorize, the status will be stated as <strong>On Hold.</strong> <br>The status will change, if the customer do payment. <br><br>Only applicable in Credit Card.</td></tr><tr><td><code>payment.payment_due_date</code></td><td>number</td><td>optional</td><td>The payment due date of the checkout page in minutes. Default : 60 minutes. Max Length: 6</td></tr></tbody></table>

#### Customer Object

```json
"customer":{
      "id":"JC-01",
      "name":"Service",
      "last_name":"Experience",
      "phone":"628121212121",
      "email": "sxp@example.com",
      "address":"Jalan DOKU no 15",
      "postcode":"120129",
      "state":"Jakarta",
      "city":"Jakarta Selatan",
      "country":"ID"
}
```

<table><thead><tr><th width="203">Body parameter</th><th width="96">Type</th><th width="128">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>customer.id</code></td><td>string</td><td>Conditional, mandatory to enable tokenized payments (BRI Direct Debit, Allobank, Credit Card tokenization) and Akulaku Paylater.</td><td>Unique customer identifier generated by merchant.<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>50</code></td></tr><tr><td><code>customer.name</code></td><td>string</td><td>Conditional,<br>mandatory for payment methods <strong>Jenius, Akulaku, Indodana, Kredivo</strong></td><td>Customer name.<br><br>Allowed chars: <code>alphabetic</code><br>Max Length: <code>255</code></td></tr><tr><td><code>customer.last_name</code></td><td>string</td><td>Optional</td><td>Customer last name.<br>Max Length: <code>16</code></td></tr><tr><td><code>customer.email</code></td><td>string</td><td>Conditional,<br>mandatory for payment method <strong>Indodana, Kredivo, Allobank</strong></td><td>Customer email. <br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>128</code></td></tr><tr><td><code>customer.phone</code></td><td>string</td><td>Conditional,<br>mandatory for payment method <strong>Indodana, Akulaku, Kredivo</strong></td><td>Customer phone number. Format: <code>{calling_code}{phone_number}</code>.<br>Example: 6281122334455<br>Max Length: <code>16</code></td></tr><tr><td><code>customer.address</code></td><td>string</td><td>Conditional, <br>mandatory for payment method <strong>Akulaku</strong></td><td>Customer address.<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>400</code></td></tr><tr><td><code>customer.postcode</code></td><td>string</td><td>Conditional,<br>mandatory for payment method <strong>Akulaku</strong></td><td>Customer address' post code</td></tr><tr><td><code>customer.state</code></td><td>string</td><td>Conditional,<br>mandatory for payment method <strong>Akulaku</strong></td><td>Customer state or province. </td></tr><tr><td><code>customer.city</code></td><td>string</td><td>Conditional,<br>mandatory for payment method <strong>Akulaku</strong></td><td>Customer address' city</td></tr><tr><td><code>customer.country</code></td><td>string</td><td>Optional</td><td>2 alphabetic country code ISO 3166-1<br>Allowed chars: <code>alphabetic</code><br>Min-max Length: <code>2</code></td></tr></tbody></table>

#### Shipping Address Object

```json
"shipping_address":{
  "first_name":"Service",
  "last_name":"Experience",
  "address":"Jalan DOKU no 15",
  "city":"Jakarta",
  "postal_code":"11923",
  "phone":"081312345678",
  "country_code":"IDN"
}
```

<table><thead><tr><th>Body Parameter</th><th width="104">Type</th><th width="199">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>shipping_address.first_name</code></td><td>string</td><td>Conditional,<br>mandatory for payment method <strong>Kredivo and Indodana</strong></td><td>Customer's first name used as shipping address</td></tr><tr><td><code>shipping_address.last_name</code></td><td>string</td><td>Optional</td><td>Customer's last name used as shipping address.</td></tr><tr><td><code>shipping_address.address</code></td><td>string</td><td>Conditional,<br>mandatory for payment method <strong>Kredivo and Indodana</strong></td><td>Customer's address used as shipping address.</td></tr><tr><td><code>shipping_address.city</code></td><td>string</td><td>Conditional,<br>mandatory for payment method <strong>Kredivo and Indodana</strong></td><td>City of customer's shipping address.</td></tr><tr><td><code>shipping_address.postal_code</code></td><td>string</td><td>Conditional,<br>mandatory for payment method <strong>Kredivo and Indodana</strong></td><td>Postal code of customer's shipping address.</td></tr><tr><td><code>shipping_address.phone</code></td><td>string</td><td>Conditional,<br>mandatory for payment method <strong>Kredivo and Indodana</strong></td><td>Customer's phone used as shipping address.</td></tr><tr><td><code>shipping_address.country_code</code></td><td>string</td><td>Conditional,<br>mandatory for payment method <strong>Kredivo and Indodana</strong></td><td>Country of customer's shipping address.</td></tr></tbody></table>

#### Billing Address Object

```json
"billing_address":{
  "first_name":"Service",
  "last_name":"Experience",
  "address":"Jalan DOKU no 15",
  "city":"Jakarta",
  "postal_code":"11923",
  "phone":"081312345678",
  "country_code":"IDN"
}
```

<table><thead><tr><th>Body Parameter</th><th width="104">Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>billing_address.first_name</code></td><td>string</td><td>Conditional,<br>mandatory for payment method <strong>Indodana</strong></td><td>Customer's first name used as billing address</td></tr><tr><td><code>billing_address.last_name</code></td><td>string</td><td>Conditional,<br>mandatory for payment method <strong>Indodana</strong></td><td>Customer's last name used as billing address.</td></tr><tr><td><code>billing_address.address</code></td><td>string</td><td>Conditional,<br>mandatory for payment method <strong>Indodana</strong></td><td>Customer's address used as billing address.</td></tr><tr><td><code>billing_address.city</code></td><td>string</td><td>Conditional,<br>mandatory for payment method <strong>Indodana</strong></td><td>City of customer's billing address.</td></tr><tr><td><code>billing_address.postal_code</code></td><td>string</td><td>Conditional,<br>mandatory for payment method <strong>Indodana</strong></td><td>Postal code of customer's billing address.</td></tr><tr><td><code>billing_address.phone</code></td><td>string</td><td>Conditional,<br>mandatory for payment method <strong>Indodana</strong></td><td>Customer's phone used as billing address.</td></tr><tr><td><code>billing_address.country_code</code></td><td>string</td><td>Conditional,<br>mandatory for payment method <strong>Indodana</strong></td><td>Country of customer's billing address.</td></tr></tbody></table>

#### Additional Info Object

```json
"additional_info":{
  "allow_tenor" : [0,3,6,12],
  "doku_wallet_notify_url" : "https://dw-notification.merchantdomain",
  "override_notification_url": "https://another.example.com/payments/notifications"
}
```

<table><thead><tr><th>Body parameter</th><th width="80">Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>additional_info.allow_tenor</code></td><td>number</td><td>Optional</td><td>The transaction exclusively supports installment tenors as per its current configuration. The allowed values are 0,3,6,12. To hide the "no installment" option, refrain from inputting 0 (zero) in the parameter.</td></tr><tr><td><code>additional_info.doku_wallet_notify_url</code></td><td>string</td><td>Conditional, only for payment method DOKU Wallet</td><td>Notification url set in this parameter</td></tr><tr><td><code>additional_info.override_notification_url</code></td><td>string</td><td>Optional</td><td>This parameter is intended to override the configured <code>Notification URL</code> with another URL.  Click <a href="/pages/LfaJBdkpBWDjF7mwEimR">here</a> for more information.</td></tr></tbody></table>

### **Response**

**Success Response**&#x20;

<table><thead><tr><th width="152">Type</th><th>Value</th></tr></thead><tbody><tr><td>HTTP Status</td><td>200</td></tr></tbody></table>

{% tabs %}
{% tab title="Basic Response" %}

```json
{
    "message": [
        "SUCCESS"
    ],
    "response": {
        "order": {
            "amount": "20000",
            "invoice_number": "INV-20210231-0001",
            "currency": "IDR",
            "session_id": "2ebffd22d23e436895ce5c38f7ddcf86"
        },
        "payment": {
            "payment_method_types": [
                "JENIUS_PAY",
                "ONLINE_TO_OFFLINE_ALFA",
                "OCTO_CLICKS",
                "PEER_TO_PEER_KREDIVO",
                "VIRTUAL_ACCOUNT_BCA",
                "CREDIT_CARD",
                "EMONEY_OVO",
                "ONLINE_TO_OFFLINE_INDOMARET",
                "EMONEY_DOKU",
                "VIRTUAL_ACCOUNT_BANK_MANDIRI",
                "EPAY_BRI",
                "PEER_TO_PEER_INDODANA",
                "VIRTUAL_ACCOUNT_BRI",
                "EMONEY_LINKAJA",
                "EMONEY_SHOPEE_PAY",
                "VIRTUAL_ACCOUNT_BNI",
                "VIRTUAL_ACCOUNT_BANK_PERMATA",
                "VIRTUAL_ACCOUNT_DOKU",
                "VIRTUAL_ACCOUNT_BANK_CIMB",
                "VIRTUAL_ACCOUNT_BANK_DANAMON",
                "VIRTUAL_ACCOUNT_BANK_SYARIAH_MANDIRI",
                "VIRTUAL_ACCOUNT_MAYBANK",
                "DIRECT_DEBIT_CIMB",
                "EMONEY_DANA",
                "DIRECT_DEBIT_BRI",
                "DIRECT_DEBIT_ALLO",
                "PEER_TO_PEER_BRI_CERIA",
                "VIRTUAL_ACCOUNT_BNC",
                "PERMATA_NET",
                "KLIKPAY_BCA",
                "VIRTUAL_ACCOUNT_BTN",
                "DANAMON_ONLINE_BANKING",
                "VIRTUAL_ACCOUNT_SINARMAS"
            ],
            "payment_due_date": 60,
            "token_id": "2ebffd22d23e436895ce5c38f7ddcf8620244712094712362",
            "url": "https://sandbox.doku.com/checkout-link-v2/2ebffd22d23e436895ce5c38f7ddcf8620244712094712362",
            "expired_date": "20240712104711"
        },
        "additional_info": {
            "origin": {
                "product": "CHECKOUT",
                "system": "mid-jokul-checkout-system",
                "apiFormat": "JOKUL",
                "source": "direct"
            }
        },
        "uuid": 2225240712094712339107164227041411929328,
        "headers": {
            "request_id": "ed06da30-bbbc-4e90-a3c7-390c24476cb9",
            "signature": "HMACSHA256=cyoua5cA6DR5mG/4vw3ice48KjCX+CGdLdSfMumJUuo=",
            "date": "2024-07-12T02:47:11Z",
            "client_id": "BRN-0214-1714016624673"
        }
    }
}
```

{% endtab %}

{% tab title="Full Response" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "message": [
        "SUCCESS"
    ],
    "response": {
        "order": {
            "amount": "80000",
            "invoice_number": "INV-1720752332",
            "currency": "IDR",
            "session_id": "5f6304ca900144c7a4fcf802ad6c0898",
            "callback_url": "http://merchantcallbackurl.domain/",
            "callback_url_cancel": "https://merchantcallbackurl-cancel.domain",
            "callback_url_result": "https://merchantcallbackurl-cancel.domain",
            "recover_abandoned_cart":true,
            "expired_recovered_cart":2,
            "line_items": [
                {
                    "name": "Fresh flowers",
                    "quantity": 1,
                    "price": "40000",
                    "sku": "FF01",
                    "category": "gift-and-flowers",
                    "url": "http://item-url.domain/",
                    "image_url": "http://image-url.domain/",
                    "type": "ABC"
                },
                {
                    "name": "T-shirt",
                    "quantity": 1,
                    "price": "40000",
                    "sku": "T01",
                    "category": "clothing",
                    "url": "http://item-url.domain/",
                    "image_url": "http://image-url.domain/",
                    "type": "ABC"
                }
            ],
            "language": "EN",
            "disable_retry_payment": true,
            "auto_redirect": true
        },
        "payment": {
            "payment_method_types": [
                "EMONEY_OVO",
                "ONLINE_TO_OFFLINE_ALFA",
                "PEER_TO_PEER_KREDIVO",
                "VIRTUAL_ACCOUNT_BCA",
                "CREDIT_CARD",
                "VIRTUAL_ACCOUNT_BANK_MANDIRI",
                "VIRTUAL_ACCOUNT_BRI",
                "PEER_TO_PEER_INDODANA",
                "VIRTUAL_ACCOUNT_BNI",
                "VIRTUAL_ACCOUNT_BANK_PERMATA",
                "VIRTUAL_ACCOUNT_DOKU",
                "VIRTUAL_ACCOUNT_BANK_CIMB",
                "VIRTUAL_ACCOUNT_BANK_DANAMON",
                "VIRTUAL_ACCOUNT_BANK_SYARIAH_MANDIRI",
                "EMONEY_DANA",
                "DIRECT_DEBIT_BRI"
            ],
            "payment_due_date": 60,
            "token_id": "5f6304ca900144c7a4fcf802ad6c089820244512094533497",
            "url": "https://sandbox.doku.com/checkout-link-v2/5f6304ca900144c7a4fcf802ad6c089820244512094533497",
            "expired_date": "20240712104531"
        },
        "customer": {
            "id": "JC-01",
            "state": "Jakarta",
            "city": "Jakarta Selatan",
            "postcode": "120129",
            "email": "zolanda@example.com",
            "phone": "628121212121",
            "name": "Zolanda",
            "last_name": "Anggraeni",
            "address": "taman setiabudi",
            "country": "ID"
        },
        "additional_info": {
            "allow_tenor": [
                0,
                3,
                6,
                12
            ],
            "doku_wallet_notify_url": "https://dw-notification.merchantdomain/",
            "origin": {
                "product": "CHECKOUT",
                "system": "mid-jokul-checkout-system",
                "source": "direct",
                "apiFormat": "JOKUL"
            },
            "line_items": [
                {
                    "quantity": 1,
                    "price": "40000",
                    "image_url": "http://image-url.domain/",
                    "name": "Fresh flowers",
                    "sku": "FF01",
                    "category": "gift-and-flowers",
                    "type": "ABC",
                    "url": "http://item-url.domain/"
                },
                {
                    "quantity": 1,
                    "price": "40000",
                    "image_url": "http://image-url.domain/",
                    "name": "T-shirt",
                    "sku": "T01",
                    "category": "clothing",
                    "type": "ABC",
                    "url": "http://item-url.domain/"
                }
            ],
            "override_notification_url": "https://another.example.com/payments/notifications"
        },
        "uuid": 2225240712094533483107164227326411817850,
        "headers": {
            "request_id": "0521fe4d-bd69-4626-9c5c-fc484b81b8bc",
            "signature": "HMACSHA256=eT5aE//GhxqrRvx/XHdV/z2KezkyD6V3EJPHTEv4x8g=",
            "date": "2024-07-12T02:45:31Z",
            "client_id": "BRN-0214-1714016624673"
        },
        "shipping_address": {
            "address": "Jalan DOKU no 15",
            "city": "Jakarta",
            "phone": "081312345678",
            "first_name": "Joe",
            "last_name": "Doe",
            "postal_code": "11923",
            "country_code": "IDN"
        },
        "billing_address": {
            "address": "Jalan DOKU no 15",
            "city": "Jakarta",
            "phone": "081312345678",
            "first_name": "Joe",
            "last_name": "Doe",
            "postal_code": "11923",
            "country_code": "IDN"
        }
    }
}
</code></pre>

{% endtab %}
{% endtabs %}

**Response Body Explanation**

<table><thead><tr><th>Body Parameter</th><th width="104">Type</th><th width="115">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>message</code></td><td>array</td><td>Mandatory</td><td>Message will display the result of the request. If there are some errors on your request, they will be diplayed in this parameter.</td></tr><tr><td><code>response.order.amount</code></td><td>number</td><td>Mandatory</td><td>Same as the request </td></tr><tr><td><code>response.order.invoice_number</code></td><td>string</td><td>Mandatory</td><td>Same as the request </td></tr><tr><td><code>response.order.currency</code></td><td>string</td><td>Optional</td><td>Same as the request  </td></tr><tr><td><code>response.order.session_id</code></td><td>string</td><td>Optional</td><td>Unique session ID generated by DOKU</td></tr><tr><td><code>response.order.callback_url</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.order.callback_url_cancel</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.order.recover_abandoned_cart</code></td><td>boolean</td><td>Conditional</td><td>Same as the request</td></tr><tr><td><code>response.order.expired_recovered_cart</code></td><td>number</td><td>Conditional</td><td>Same as the request</td></tr><tr><td><code>response.order.line_items.name</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.order.line_items.quantity</code></td><td>number</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.order.line_items.price</code></td><td>number</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.order.line_items.sku</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.order.line_items.category</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.order.line_items.url</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.order.line_items.image_url</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.order.line_items.type</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.order.language</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.order.disable_retry_payment</code></td><td>boolean</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.order.auto_redirect</code></td><td>boolean</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.payment.payment_method_types</code></td><td>array</td><td>Optional</td><td>Payment method that will be displayed on the Checkout Page</td></tr><tr><td><code>response.payment.payment_due_date</code></td><td>number</td><td>Mandatory</td><td>Same as the request</td></tr><tr><td><code>response.payment.token_id</code></td><td>string</td><td>Mandatory</td><td>Token generated by DOKU for the Checkout Page</td></tr><tr><td><code>response.payment.url</code></td><td>string</td><td>Mandatory</td><td>Checkout page URL to display for the customer</td></tr><tr><td><code>response.payment.expired_date</code></td><td>string</td><td>Mandatory</td><td>Date time of payment page will be expired with the format of <code>yyyyMMddHHmmss</code>. The expired date uses UTC+7 time. Use this to set the expiry order on merchant side</td></tr><tr><td><code>response.customer.id</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.customer.state</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.customer.city</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.customer.postcode</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.customer.email</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.customer.phone</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.customer.name</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.customer.last_name</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.customer.address</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.customer.country</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.additional_info.allow_tenor</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.additional_info.close_redirect</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.additional_info.doku_wallet_notify_url</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.additional_info.override_notification_url</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.uuid</code></td><td>string</td><td>Optional</td><td>Unique number generated by DOKU</td></tr><tr><td><code>response.headers.requestId</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.headers.signature</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.headers.date</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.headers.clientId</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.shipping_address.address</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.shipping_address.city</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.shipping_address.phone</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.shipping_address.first_name</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.shipping_address.last_name</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.shipping_address.postal_code</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.shipping_address.country_code</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.billing_address.address</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.billing_address.city</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.billing_address.phone</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.billing_address.first_name</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.billing_address.first_name</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.billing_address.postal_code</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>response.billing_address.country_code</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr></tbody></table>

**Failed Response**

<table><thead><tr><th width="152">Type</th><th>Value</th></tr></thead><tbody><tr><td>HTTP Status</td><td>400</td></tr></tbody></table>

```json
{
    "error_messages": [
        "order.invoice_number must be filled",
        "order.amount must greater than 0"
    ]
}
```

***

#### List Category

List category can be used as reference. But this is part of payment channel Indodana with mandatory value need to set in `order.line_items.category.`

<table><thead><tr><th width="86">No</th><th>Category</th></tr></thead><tbody><tr><td>1</td><td>airlines</td></tr><tr><td>2</td><td>arts-crafts-and-collectibles</td></tr><tr><td>3</td><td>automotive</td></tr><tr><td>4</td><td>baby</td></tr><tr><td>5</td><td>beauty-and-fragrances</td></tr><tr><td>6</td><td>biller</td></tr><tr><td>7</td><td>books-and-magazines</td></tr><tr><td>8</td><td>business-to-business-including-mlm</td></tr><tr><td>9</td><td>charity-and-non-profit</td></tr><tr><td>10</td><td>clothing</td></tr><tr><td>11</td><td>community</td></tr><tr><td>12</td><td>digital-content</td></tr><tr><td>13</td><td>electronics-and-telecom</td></tr><tr><td>14</td><td>entertainment-and-media</td></tr><tr><td>15</td><td>fee</td></tr><tr><td>16</td><td>financial-services-and-products</td></tr><tr><td>17</td><td>financial-services-and-technology</td></tr><tr><td>18</td><td>food-and-beverage</td></tr><tr><td>19</td><td>food-retail-and-service</td></tr><tr><td>20</td><td>games-voucher</td></tr><tr><td>21</td><td>gifts-and-flowers</td></tr><tr><td>22</td><td>government</td></tr><tr><td>23</td><td>health-and-personal-care</td></tr><tr><td>24</td><td>home-and-garden</td></tr><tr><td>25</td><td>hotel-and-travel</td></tr><tr><td>26</td><td>insurance</td></tr><tr><td>27</td><td>marketplace</td></tr><tr><td>28</td><td>nonprofit</td></tr><tr><td>29</td><td>offline-store</td></tr><tr><td>30</td><td>others</td></tr><tr><td>31</td><td>over-the-air</td></tr><tr><td>32</td><td>overseas</td></tr><tr><td>33</td><td>pets-and-animals</td></tr><tr><td>34</td><td>property</td></tr><tr><td>35</td><td>public-services</td></tr><tr><td>36</td><td>religion-and-spirituality</td></tr><tr><td>37</td><td>retail</td></tr><tr><td>38</td><td>services</td></tr><tr><td>39</td><td>sports-and-outdoors</td></tr><tr><td>40</td><td>telco</td></tr><tr><td>41</td><td>ticketing</td></tr><tr><td>42</td><td>toys-and-hobbies</td></tr><tr><td>43</td><td>transportation</td></tr><tr><td>45</td><td>travel</td></tr><tr><td>46</td><td>vehicle-sales</td></tr><tr><td>47</td><td>vehicles-service-and-accessories</td></tr></tbody></table>


# Frontend Integration

### Frontend Integration to display DOKU Checkout Page

The aim of integrating the frontend is to present the DOKU Checkout payment page seamlessly within your website.

Once you have the `payment.url`, you can now display the payment page by embedding the DOKU Checkout JS on your HTML file.

#### DOKU Checkout js location

Simply import the `jokul-checkout-1.0.0.js` and then call the `loadJokulCheckout()` with the `payment.url:`

<table><thead><tr><th width="144">Type</th><th>Value</th></tr></thead><tbody><tr><td>JS (sandbox)</td><td><a href="https://sandbox.doku.com/jokul-checkout-js/v1/jokul-checkout-1.0.0.js">https://sandbox.doku.com/jokul-checkout-js/v1/jokul-checkout-1.0.0.js</a></td></tr><tr><td>JS (production)</td><td><a href="https://jokul.doku.com/jokul-checkout-js/v1/jokul-checkout-1.0.0.js">https://jokul.doku.com/jokul-checkout-js/v1/jokul-checkout-1.0.0.js</a></td></tr></tbody></table>

{% hint style="info" %}
**VIEWPORT**

The `viewport` on the `<head>` tag is important to ensure that the payment page is load correctly.
{% endhint %}

```html
<html>
    <head>
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <script src="https://sandbox.doku.com/jokul-checkout-js/v1/jokul-checkout-1.0.0.js"></script>
    </head>
    <body>
        <button id="checkout-button">Checkout Now</button>

        <script type="text/javascript">
        var checkoutButton = document.getElementById('checkout-button');
        // Example: the payment page will show when the button is clicked
        checkoutButton.addEventListener('click', function () {
            loadJokulCheckout('https://jokul.doku.com/checkout/link/SU5WFDferd561dfasfasdfae123c20200510090550775'); // Replace it with the response.payment.url you retrieved from the response
        });
        </script>
    </body>
</html>
```

There are 2 approaches for integrating the DOKU Checkout page into your web/app interface.&#x20;

1. Redirect customer to a new page.

   Use the `payment.url`value **without** importing the JS file
2. Present it as modal overlay (pop-up mode)

   Kindly importing the JS file as the sample attached above

<figure><img src="/files/ZKPmxR4l4ZL3ck0N7o7d" alt=""><figcaption><p>Pop up mode integration</p></figcaption></figure>


# Simulate payment and Notification

### Create payment simulation

Create a test payment to make sure that the DOKU Checkout has been successfully integrated. Simply initiate the payment from your page and then make the payment from our Simulator.

* [Click here to access our payment simulator](https://sandbox.doku.com/integration/simulator/)

After the payment is completed, your customers will be redirected to `callback_url` that defined in the request.

### Acknowledge payment result <a href="#id-4-acknowledge-payment-result" id="id-4-acknowledge-payment-result"></a>

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`. Learn how to handle the notification from DOKU [here](/get-started-with-doku-api/notification).&#x20;


# Supported Payment Methods

{% hint style="info" %}
PROTIPS!\
You can define the payment method that will be shown in the payment page through the DOKU Back Office or by inputing the array list of payment method in the `payment.payment_method_types`. If you send only one payment method, then your customer will redirected directly to defined payment method.
{% endhint %}

There are several payment methods that support our DOKU Checkout Page :

### Virtual Account

The following channels are supported for payment method type Virtual Account&#x20;

<table><thead><tr><th width="246">Payment Method </th><th width="489">Value</th></tr></thead><tbody><tr><td>BCA VA</td><td><code>VIRTUAL_ACCOUNT_BCA</code></td></tr><tr><td>Bank Mandiri VA</td><td><code>VIRTUAL_ACCOUNT_BANK_MANDIRI</code></td></tr><tr><td>Bank Syariah Indonesia VA</td><td><code>VIRTUAL_ACCOUNT_BANK_SYARIAH_MANDIRI</code></td></tr><tr><td>BRI VA</td><td><code>VIRTUAL_ACCOUNT_BRI</code></td></tr><tr><td>BNI VA</td><td><code>VIRTUAL_ACCOUNT_BNI</code></td></tr><tr><td>DOKU VA</td><td><code>VIRTUAL_ACCOUNT_DOKU</code></td></tr><tr><td>PERMATA VA</td><td><code>VIRTUAL_ACCOUNT_BANK_PERMATA</code></td></tr><tr><td>CIMB VA</td><td><code>VIRTUAL_ACCOUNT_BANK_CIMB</code></td></tr><tr><td>Danamon VA</td><td><code>VIRTUAL_ACCOUNT_BANK_DANAMON</code></td></tr><tr><td>BTN VA</td><td><code>VIRTUAL_ACCOUNT_BTN</code></td></tr><tr><td>BNC VA</td><td><code>VIRTUAL_ACCOUNT_BNC</code></td></tr><tr><td>BSS VA</td><td><code>VIRTUAL_ACCOUNT_BSS</code></td></tr><tr><td>BJB VA</td><td><code>VIRTUAL_ACCOUNT_BJB</code></td></tr><tr><td>Sinarmas VA</td><td><code>VIRTUAL_ACCOUNT_Sinarmas</code></td></tr></tbody></table>

### Credit Card

<table><thead><tr><th width="230">Payment Method </th><th width="161">Value</th></tr></thead><tbody><tr><td>Credit Card</td><td><code>CREDIT_CARD</code></td></tr><tr><td>Google Pay</td><td><code>GOOGLE_PAY</code></td></tr></tbody></table>

{% hint style="info" %}

#### Credit Cards With Google Pay

DOKU offers your customers another way to pay with Credit Cards through Google Pay, allowing them to complete purchases instantly using the cards already saved to their Google account. By removing the need to manually input card details or billing addresses, you provide a frictionless, biometric-authenticated checkout that captures sales in seconds. For more information about Google Pay please refer to this [section](/accept-payments/doku-checkout/additional-feature/google-pay-tm)
{% endhint %}

### Convenience Store

<table><thead><tr><th width="356">Payment Method </th><th width="327">Value</th></tr></thead><tbody><tr><td>Alfa Group (Alfamart, Alfamidi, Dan+Dan)</td><td><code>ONLINE_TO_OFFLINE_ALFA</code></td></tr><tr><td>Indomaret</td><td><code>ONLINE_TO_OFFLINE_INDOMARET</code></td></tr></tbody></table>

### QRIS Payment&#x20;

<table><thead><tr><th width="362">Payment Method </th><th width="334">Value</th></tr></thead><tbody><tr><td>QRIS</td><td><code>QRIS</code></td></tr></tbody></table>

### E-wallet

<table><thead><tr><th width="355">Payment Method </th><th width="304">Value</th></tr></thead><tbody><tr><td>OVO</td><td><code>EMONEY_OVO</code></td></tr><tr><td>SHOPEE PAY</td><td><code>EMONEY_SHOPEE_PAY</code></td></tr><tr><td>DOKU WALLET</td><td><code>EMONEY_DOKU</code></td></tr><tr><td>LINKAJA</td><td><code>EMONEY_LINKAJA</code></td></tr><tr><td>DANA</td><td><code>EMONEY_DANA</code></td></tr></tbody></table>

{% hint style="info" %}

#### DANA With Google Pay

DOKU offers your customers another way to pay by leveraging their DANA balances, allowing them to complete purchases instantly using the funds already sitting in their digital wallet. For more information about Google Pay please refer to this [section](/accept-payments/doku-checkout/additional-feature/google-pay-tm)
{% endhint %}

### Paylater&#x20;

<table><thead><tr><th width="358">Payment Method </th><th width="337">Value</th></tr></thead><tbody><tr><td>AKULAKU</td><td><code>PEER_TO_PEER_AKULAKU</code></td></tr><tr><td>KREDIVO</td><td><code>PEER_TO_PEER_KREDIVO</code></td></tr><tr><td>INDODANA</td><td><code>PEER_TO_PEER_INDODANA</code></td></tr></tbody></table>

### Direct Debit&#x20;

<table><thead><tr><th width="361">Payment Method </th><th width="400">Value</th></tr></thead><tbody><tr><td>Direct Debit BRI</td><td><code>DIRECT_DEBIT_BRI</code></td></tr></tbody></table>

### Digital Banking

<table><thead><tr><th width="360">Payment Method </th><th width="281">Value</th></tr></thead><tbody><tr><td>JENIUS PAY</td><td><code>JENIUS_PAY</code></td></tr></tbody></table>

### Kartu Kredit Indonesia

<table><thead><tr><th width="360">Payment Method </th><th width="281">Value</th></tr></thead><tbody><tr><td>KKI</td><td><pre><code>KARTU_KREDIT_INDONESIA
</code></pre></td></tr></tbody></table>


# Collect Customer Information

Enable your checkout page to collect additional customer information, such as Name, Phone numbers, or Address directly within the payment flow. Activated via the request body when creating a checkout session.&#x20;

***

### Overview

By default, the checkout page collects only the payment details required to complete a transaction. Merchants can extend this by enabling `collect_customer` in the creation request. When enabled, the configured fields appear as a form step inside the checkout flow before payment is processed.

### How to Enable Customer Data Collection

Pass the `collect_customer` object inside your Request Body to Checkout Page

```json
...
"collect_customer": {
    "name": true,
    "email" : true,
    "phone" : true,
    "address" : true
  }
...
```

<table><thead><tr><th>Body Parameter</th><th width="122">Type</th><th>Mandatory</th><th valign="bottom">Description</th></tr></thead><tbody><tr><td><code>collect_customer.name</code></td><td><code>boolean</code></td><td>Optional</td><td valign="bottom">When set to <code>true</code>, a name input field is displayed on the checkout page, prompting the customer to enter their full name before proceeding to payment.</td></tr><tr><td><code>collect_customer.email</code></td><td><code>boolean</code></td><td>Optional</td><td valign="bottom">When set to <code>true</code>, an email input field is displayed on the checkout page. The collected email can be used for payment confirmation and receipt delivery.</td></tr><tr><td><code>collect_customer.phone</code></td><td><code>boolean</code></td><td>Optional</td><td valign="bottom">When set to <code>true</code>, a phone number input field is displayed on the checkout page. Useful for merchants who require contact information for order updates or delivery coordination.</td></tr><tr><td><code>collect_customer.address</code></td><td><code>boolean</code></td><td>Optional</td><td valign="bottom">When set to <code>true</code>, an address input field is displayed on the checkout page. Recommended for merchants with physical goods delivery that need a shipping destination at the point of payment.</td></tr></tbody></table>

### How The Checkout Preview

{% columns %}
{% column width="50%" %}

### Before

<figure><img src="/files/9otp0gUF7MtVwc59sjOS" alt="" width="563"><figcaption></figcaption></figure>
{% endcolumn %}

{% column width="50%" %}

### After

<figure><img src="/files/SNE4q7HnMHeEz4TWZWW1" alt="" width="563"><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}


# Order Status for Checkout Page

### 1. Order Status on Checkout Report

Merchant can check their status order from DOKU Dashboard on Menu **Report > Checkout Orders.**

<figure><img src="/files/kpjPXyKz1c90sF4h3k3F" alt=""><figcaption><p>Checkout Report </p></figcaption></figure>

<table><thead><tr><th width="176">Status Order</th><th>Description</th></tr></thead><tbody><tr><td><mark style="color:yellow;"><strong>Pending</strong></mark> </td><td>Pending status reflects state when merchant do initiate payment, and the customer still not do the payment within the payment due date time</td></tr><tr><td><mark style="color:green;"><strong>Success</strong></mark></td><td>Success status shows that customer successfully paid the transaction and faced a success result page</td></tr><tr><td><mark style="color:red;"><strong>Expired</strong></mark></td><td>Expired status will appear if the order is not paid within the specified payment due date</td></tr></tbody></table>

### 2. Order Status on Check Status API

{% hint style="warning" %}
Only merchant who registered from December 2024 can implemented this, contact our support team to activate this for existing merchant
{% endhint %}

{% hint style="success" %}
The Check Status API now returns the **checkout order status**, even when the payment channel has not yet published its transaction status.

Previously, the API only returned data after the payment channel created a transaction record. As a result, when a customer generated a checkout order and selected a payment method (for example ShopeePay), the Check Status API could return **`Not Found`** until the payment channel published the `PENDING` status.

With this features, the API will return the **order-level status** once the checkout order is generated.
{% endhint %}

| Scenario                                          | Previous Behavior                                   | Current Behavior                                                                         |
| ------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Customer generates checkout and selects ShopeePay | Check Status returns **Not Found**                  | Check Status returns `order.status = ORDER_GENERATE`                                     |
| Customer completes payment with ShopeePay         | Check Status returns `transaction.status = SUCCESS` | Check Status returns `order.status = ORDER_GENERATED` and `transaction.status = SUCCESS` |

> This features allows merchants to **track the checkout order earlier**, even before the payment channel publishes the transaction status.

#### API Response

{% tabs %}
{% tab title="Before Choose Channel" %}

```json
{
    "order": {
        "invoice_number": "INV-5489910000093492",
        "amount": 120000,
        "status": "ORDER_GENERATED" /“ORDER_EXPIRED"/"ORDER_RECOVERED",
        "date": "2025-07-09T02:58:30Z"
    },
    "transaction": {
        "status": "PENDING",
        "date": "2025-07-09T02:58:30Z",
        "original_request_id": "3719"
    },
    "service": {
        "id": ""
    },
    "acquirer": {
        "id": ""
    },
    "channel": {
        "id": ""
    }
}

```

{% endtab %}

{% tab title="After Choose Channel" %}

```json
{
    "order": {
        "invoice_number": "INV-548991000009310030",
        "amount": 120000.0,
        "status": "ORDER_GENERATED" / “ORDER_EXPIRED”
    },
    "transaction": {
        "status": "PENDING",
        "date": "2025-07-10T03:00:48Z",
        "original_request_id": "76392"
    },
    "service": {
        "id": "DIGITAL_BANKING"
    },
    "acquirer": {
        "id": "BTPN",
        "name": "Bank Tabungan Pensiunan Nasional"
    },
    "channel": {
        "id": "JENIUS_PAY"
    },
    "additional_info": {
        "doku_wallet_notify_url": "https://doku.com",
        "origin": {
            "product": "CHECKOUT",
            "system": "mid-jokul-checkout-system",
            "api_format": "JOKUL",
            "source": "direct"
        },
        "line_items": [
            {
                "quantity": 1.0,
                "price": "120000",
                "image_url": "http://doku.com/",
                "name": "DOKU Basic T-Shirt",
                "sku": "FashionSKU123",
                "type": "ABC",
                "category": "Fashion",
                "url": "http://doku.com/"
            }
        ]
    },
    "digital_banking_payment": {}
}

```

{% endtab %}
{% endtabs %}

<table><thead><tr><th>Body parameter</th><th width="96">Type</th><th width="113">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.status</code></td><td>array</td><td>optional</td><td>Possible Value : <code>ORDER_GENERATED</code><br><code>ORDER_EXPIRED</code><br><code>ORDER_RECOVERED</code></td></tr></tbody></table>


# Additional Feature

Discover how our advanced tokenization ensures secure, streamlined transactions, and explore the Promo Engine to maximize your savings with exclusive offers and discounts. Enhance your checkout experience with these powerful tools.


# Tokenization

### What is Tokenization ?&#x20;

Tokenization is a helpful feature that makes transactions easier. It works by connecting a user's account to future payments. Once someone enters their credit card details during their first transaction on the DOKU checkout page, that information is securely saved. Later on, when they make another payment, they can simply use the linked account, avoiding the need to enter their credit card details again.

### Supported Payment Channel

Tokenization supported by payment channel :&#x20;

* Credit Card

### How to use tokenized in Checkout Page ?&#x20;

What you need to ensure when activate tokenization is by bring parameter `customer.id` in your initial payment request.&#x20;

#### Request sample :&#x20;

```json
"customer":{
      "id":"JC-01"
}
```


# Promo on DOKU Checkout Page

How to apply promo in checkout page

<figure><img src="/files/rjFbraA7k5MF7Sn21WW1" alt=""><figcaption></figcaption></figure>

Applying a promo code during checkout allows customers to save on their purchases. Here's a **step-by-step guide** on how your customers can apply a promo code to their payment :

1. #### Setting up a Promo

   Before applying a promo code, it first needs to be set up and configured. If you haven't done this yet, please refer to our guide on how to set up a promo [here](https://docs.doku.com/enhancements/promo-engine/set-up-a-promo).
2. **View Promo List**

   To view the available promos, click on the **"See Promo"** button that is seen on the checkout page.
3. **Apply Promo**

   To apply promo to checkout orders, customer must click "apply". The discount amount will be shown. Customers can proceed with the payment by entering their payment credentials, such as a credit card number or any other relevant information required for their chosen payment method.
4. **Complete the Payment**

   Customer can finalize the payment and enjoy promo!!


# Google Pay™

DOKU now supports Google Pay™as a streamlined payment option for your customers. By incorporating this into your checkout experience, you allow users to complete transactions quickly using the cards saved to their Google accounts, reducing friction and increasing conversion rates.

{% hint style="info" %}
All merchants are required to follow the  [Google Pay APIs Acceptable Use Policy](https://payments.developers.google.com/terms/aup) and [Google Pay API Terms of Service](https://payments.developers.google.com/terms/sellertos).
{% endhint %}


# Integration Guide

### 1. Activate Google Pay™&#x20;

As a Google Pay-supported Payment Service Provider (PSP), DOKU manages the Google Pay integration on your behalf, including production access and compliance with Google Pay's brand and technical requirements. **There is no additional development effort required from your side.**

To enable Google Pay in production, simply activate it through your DOKU Dashboard by following the steps below:

1. Log in to your **DOKU Dashboard** at <https://dashboard.doku.com/bo/dashboard>

<figure><img src="/files/A30KtwO6wWOJOcEbYs4m" alt=""><figcaption></figcaption></figure>

2. Navigate to **Settings → Service**&#x20;

<figure><img src="/files/lWEd2dE1sZjKMqwcDSX9" alt=""><figcaption></figcaption></figure>

3. Click **Add Service and** Enable **Cards** and/or **DANA** as your payment method (Prerequisites to activate Google Pay)

<figure><img src="/files/ETyhib420MorUk45UBbZ" alt=""><figcaption></figcaption></figure>

4. Once your Card or DANA channel activated on DOKU, you can activate Google Pay by go to same menu **Add Service** > Find **Google Pay under Financial Services > Others Tab > Enable Google Pay**

   <figure><img src="/files/LRZO8WBkHZyGZN3Ts8V6" alt=""><figcaption></figcaption></figure>
5. Once activated, the Google Pay button will automatically appear on your DOKU Checkout Page for eligible customers

{% hint style="warning" %}
The Google Pay button will only be displayed to customers whose devices meet Google Pay's eligibility requirements (e.g., Android device with a linked card or DANA account on their Google Account).
{% endhint %}

For a complete overview of how Google Pay works, refer to the [Google Pay Web Developer Documentation](https://developers.google.com/pay/api/web/overview)&#x20;

### 2. Publish your integration through DOKU Checkout Page

{% hint style="info" %}
DOKU only provides a Hosted method. DOKU handles both the UI and backend logic, managing the entire payment flow once the user is redirected to their checkout URL.
{% endhint %}

{% tabs %}
{% tab title="Checkout Page" %}
{% stepper %}
{% step %}

### Follow this [Guidance](https://developers.doku.com/accept-payments/doku-checkout/integration-guide/backend-integration#basic-request) to generate Checkout URL

<figure><img src="/files/Wv4sCFVUrKxIrY5edc1l" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Receive the Checkout URL from API Response

{% endstep %}

{% step %}

### Your customer can then access the link and will be directed to the checkout page

<figure><img src="/files/7IctvrmWCzULrd982fOS" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Click Checkout with Google Pay and a pop up will show up then click "Pay"

<figure><img src="/files/565uhxkUWb2Bhzh0Qfq3" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="Payment Link" %}
{% stepper %}
{% step %}

### Go to generate payment link and click "Create Payment Link"

<figure><img src="/files/G3y5XWnW9wtRDzNgM99P" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Fill the necessary details and click "Create Payment Link"

<figure><img src="/files/xoGGtf2tBGpsc623IO8P" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### A payment link will be created

<figure><img src="/files/ZhT3VxIhjinECxCX20Jb" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Your customer can then access the link and will be directed to the checkout page

<figure><img src="/files/7IctvrmWCzULrd982fOS" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Click Checkout with Google Pay and a pop up will show up then click "Pay"

<figure><img src="/files/565uhxkUWb2Bhzh0Qfq3" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
To ensure your integration meets all of Google Pay's requirements, please review the [Google Pay Integration Checklist](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist).
{% endhint %}


# Additional Feature and Information

### 1. Google Pay™ With DANA Balances

By enabling both DANA and the Google Pay API, you offer customers a streamlined 'One-Tap' checkout. This integration allows users to pay with their DANA balance directly through the Google Pay interface whenever DANA is selected as the payment method

As a prerequisite, the customer must have their DANA account already linked as a payment method within their Google Account settings.

### 2. Google Pay Supported Card Types

Our integration with Google Pay currently supports only the PAN\_ONLY card credential method.\
In this method, the Primary Account Number (PAN) is used for communication between Google Pay, DOKU, and the card networks, instead of a network token.

The PAN obtained from Google Pay is then processed through the standard 3DS authentication flow, which is applicable across all supported countries depending on your merchant configuration on our Back Office.

### 3. Activate 3DS Support For Non Google Payment Methods

We support 3DS authentication for Google Pay PAN\_ONLY transactions. When a customer selects Google Pay on our Hosted Checkout Page, they can either enter their card details manually or choose a card previously saved in their Google account.

For PAN\_ONLY credentials, Google Pay returns the card details to DOKU in encrypted form for each transaction. DOKU then decrypts and uses these credentials to initiate the 3DS verification process, followed by payment authorization with the acquirer

### 4. Brand Guidelines

As DOKU manages the entire Hosted Checkout UI on your behalf, **you are not required to implement or customize the Google Pay button yourself.**&#x20;

DOKU ensures full compliance with [Google Pay Brand Guidelines](https://developers.google.com/pay/api/web/guides/brand-guidelines) on your behalf.&#x20;


# Track Campaign Source on Google Analytics

DOKU Checkout now supports the ability to track campaign sources through Google Analytics (GA). This feature allows merchants to attribute transactions to specific marketing campaigns by passing UTM.

By leveraging this feature, you can:

* Identify which campaigns drive conversions
* Improve marketing strategy based on performance data
* Track customer behavior through your Google Analytics account

***

### How it Works ?

When generating a checkout order, you can pass Google Analytics UTM parameters in the request. These parameters will be stored and sent during the transaction process, enabling you to track attribution data in your analytics tools.

#### Request sample :&#x20;

<pre class="language-json"><code class="lang-json"><strong>"additional_info": {
</strong>        "google_config": {
            "campaign_name": "test_name_2",
            "campaign_source": "test_source_2",
            "campaign_medium": "test_medium_2",
            "debug_mode": true
        },
    }
</code></pre>

| Body Paramater                  | Type    | Mandatory | Description                                                                                                 |
| ------------------------------- | ------- | --------- | ----------------------------------------------------------------------------------------------------------- |
| `google_config.campaign_name`   | String  | Optional  | The name of the marketing campaign (e.g., `"ramadhan_sale"`). Used to group campaign results.               |
| `google_config.campaign_source` | String  | Optional  | The source of the traffic (e.g., `"google"`, `"instagram"`). Identifies where the user came from.           |
| `google_config.campaign_medium` | String  | Optional  | The medium used in the campaign (e.g., `"cpc"`, `"email"`, `"referral"`).                                   |
| `google_config.debug_mode`      | Boolean | Optional  | Set to `true` to enable debug mode, which will log campaign tracking behavior for troubleshooting purposes. |


# Expired Notification

You can receive notification for EXPIRED status. DOKU will notify automatically once the status of order changed to EXPIRED.

### 1. Expired URL Configuration

1. Go to Menu Settings
2. Open Checkout Appearance
3. Click Tab Expired Settings
4. You will see this page :&#x20;

<figure><img src="/files/ZJu3SGU5AhLVMFjW3X9B" alt=""><figcaption></figcaption></figure>

5. Activate the Expired Notification and input the URL on the field

### 2. Monitoring the order status

1. Go to Menu Settings
2. Open HTTP Notification Report
3. You will see the status of Expired here

<figure><img src="/files/PyyN5EC93lXzk2DB1Sxd" alt=""><figcaption></figcaption></figure>

4. You can download the file by click the "Download File" button

<figure><img src="/files/0xkLEsHyLx5v8TZxHkj2" alt=""><figcaption></figcaption></figure>

5. You can retry the notification by click Resend Notification


# Cancel Order API

The **Cancel Order API** allows merchants to cancel an **unpaid checkout order** before the checkout URL expires. Once cancelled, the checkout session becomes invalid and the customer will no longer be able to complete the payment.

This API helps merchants manage order changes and maintain accurate order status in their systems.

## Overview

Use Case :&#x20;

Merchants may need to cancel a checkout order when:

* The **customer changes their order**
* The **merchant needs to update inventory**
* The **merchant wants to invalidate an existing checkout link**
* The **merchant does not want to wait for the checkout URL to expire**

***

## Supported Payment Channels

| Channel               | Support | Notes                         |
| --------------------- | ------- | ----------------------------- |
| Bank Transfer         | ✅       | (exclude BTN, BNC, BPD, OCBC) |
| QRIS                  | ✅       | -                             |
| Convenience Store     | ❌       | -                             |
| Cards                 | ❌       | -                             |
| eWallet               | ❌       | -                             |
| Direct Debit          | ❌       | -                             |
| Paylater              | ❌       | -                             |
| Karu Kredit Indonesia | ❌       | -                             |
| Digital Banking       | ❌       | -                             |

{% hint style="danger" %}
Transactions that are already **paid or expired cannot be cancelled**.
{% endhint %}

***

## Activation

This feature is **not enabled by default**.

{% hint style="warning" %}
Merchants must request activation from the **DOKU Team**.
{% endhint %}

***

## How to Use

#### API Endpoint

| Type                      | Value                                                    |
| ------------------------- | -------------------------------------------------------- |
| HTTP Method               | POST                                                     |
| API Endpoint (Sandbox)    | <https://api-sandbox.doku.com/checkout/v3/cancellations> |
| API Endpoint (Production) | <https://api.doku.com/checkout/v3/cancellations>         |

### Request Header

Here is the sample of request header to cancel the order

```
Client-Id: MCH-0001-10791114622547
Request-Id: fdb69f47-96da-499d-acec-7cdc318ab2fe
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
```

<table><thead><tr><th width="167">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>client-id</code></strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong><code>request-id</code></strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong><code>request-timestamp</code></strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong><code>signature</code></strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="/pages/VogdJfoJtS2yXvClOsrc">this section</a> to generate the signature</td></tr></tbody></table>

Here is the sample of request body to cancel the order :&#x20;

```json
{
"order": {
  "invoice_number": "PTR-JessicaTest"
},
  "payment": {
      "original_request_id": "7a38dc09-0fa5-4637-9b57-12ac2c61d90a"
  },
"note": "cancel order"
}
```

<table><thead><tr><th>Body Parameter</th><th width="122">Type</th><th>Mandatory</th><th valign="bottom">Description</th></tr></thead><tbody><tr><td><code>order.invoice_number</code></td><td><code>string</code></td><td>Mandatory</td><td valign="bottom">Using the invoice number that used to generate the URL</td></tr><tr><td><code>payment.original_request_id</code></td><td><code>string</code></td><td>Mandatory</td><td valign="bottom">Using the original request id that used to generate the URL</td></tr><tr><td><code>note</code></td><td><code>string</code></td><td>Mandatory</td><td valign="bottom">Send the note for sync the data</td></tr></tbody></table>

## Monitor the Order

Cancelled orders will appear in the **Checkout Order Report** with the status: `CANCELLED`

<figure><img src="/files/2dZh2CnGZh16uSkY8He9" alt=""><figcaption></figcaption></figure>


# Last Used Payment Channels

**Overview**

Last Used Payment Channel feature automatically displays a customer's most recently used payment channel on the Checkout Page. Instead of requiring returning customers to scroll through the full list of available channels, this feature surfaces their previous choice for a faster, more convenient checkout experience.

This feature is best suited for merchants with a high volume of repeat/returning customers.

**How to Activate**

1. Log in to the **DOKU Dashboard**
2. Navigate to the Checkout Page settings
3. Locate the **Last Used Payment Channel** feature
4. Toggle the feature **ON**

<figure><img src="/files/H1Ru9hE1weNlk0xjgQMt" alt=""><figcaption></figcaption></figure>

*Note: Activation is required before the feature can function, even if `customer.id` is sent via API, the feature will not display if it hasn't been activated on the Dashboard.*

**How to Integrate**

Once activated, merchants need to pass the customer identifier in the API request:

**Required parameter:**

| Parameter     | Type   | Description                                                                         |
| ------------- | ------ | ----------------------------------------------------------------------------------- |
| `customer.id` | String | Unique identifier for the customer, used to look up their last used payment channel |

**Example request:**

json

```json
{
  "customer": {
    "id": "CUST-00123"
  }
}
```

**How It Works**

1. Merchant sends `customer.id` in the checkout API request
2. DOKU looks up the customer's transaction history
3. If a previous successful payment channel is found, it is automatically shown/prioritized on the Checkout Page
4. If no history is found (e.g., first-time customer), the Checkout Page displays the default channel list as usual

**FAQ**

**Q: What happens if the customer used multiple channels before?**\
A: Only the most recent successfully used channel is shown.

**Q: Does this work without activating on the Dashboard?**\
A: No. The feature must be activated on the Dashboard even if `customer.id` is sent via API.

**Q: Is `customer.id` required for all merchants, even those not using this feature?**\
A: No, `customer.id` is only needed if the merchant wants to enable this feature.


# Checkout Settings

**For a seamless and brand-consistent invoicing experience, we recommend configuring your payment page settings before issuing your first invoice.** Access the dedicated Checkout Settings section within your DOKU Dashboard nor API requests to personalize your invoices in a variety of ways.

### Use your preferred Payment Method

You can configure your preferred payment method that will appear on your Checkout Page. Please make sure that the payment method service already active by following this [section](https://docs.doku.com/get-started/manage-business/activate-services).

1. **Specify Payment Method via Dashboard**

   You can choose which payment method that will be show and the order.&#x20;

   1. Login to DOKU Dashboard
   2. Go to **Setting > Checkout Page > Payment Method Settings Tab**&#x20;
   3. Click on your chosen payment method by tick on the checkbox
   4. Drag the line icon to set the payment method order
   5. Click **save**

      <figure><img src="/files/a7Q0lFVxS5tPMw2bT7R8" alt=""><figcaption></figcaption></figure>
2. **Specify Payment Method via API Request**

   DOKU allows you to customize your payment experience by setting your preferred payment methods based on API requests. This comes in handy in several situations:

   * **Controlling the payment method appearance:** You can choose which payment methods appear on your website and map the certain payment method. This gives you the greater control over the user interface and branding.&#x20;
   * **Offering targeted payment options:** You can tailor the available payment methods to specific customer segments or purchase types. For example, you might offer faster checkout options for high-value orders or display local payment methods for international customers.

{% hint style="info" %}
**Note:** You don't need to create multiple DOKU client IDs to achieve these customizations. The API request approach provides a flexible and efficient way to manage your preferred payment methods.
{% endhint %}

```json
"payment": {
      "payment_method_types": [
          "VIRTUAL_ACCOUNT_BCA",
          "VIRTUAL_ACCOUNT_BANK_MANDIRI",
          "VIRTUAL_ACCOUNT_BANK_SYARIAH_MANDIRI",
          "VIRTUAL_ACCOUNT_DOKU",
          "VIRTUAL_ACCOUNT_BRI",
          "VIRTUAL_ACCOUNT_BNI",
          "VIRTUAL_ACCOUNT_BANK_PERMATA",
          "VIRTUAL_ACCOUNT_BANK_CIMB",
          "VIRTUAL_ACCOUNT_BANK_DANAMON",
          "ONLINE_TO_OFFLINE_ALFA",
          "CREDIT_CARD",
          "DIRECT_DEBIT_BRI",
          "EMONEY_SHOPEE_PAY",
          "EMONEY_OVO",
          "QRIS",
          "PEER_TO_PEER_AKULAKU",
          "PEER_TO_PEER_KREDIVO",
          "PEER_TO_PEER_INDODANA"
      ]
```

> For details of supported payment methods, please refer to this [section](/accept-payments/doku-checkout/supported-payment-methods)

The payment method appearance **priority takes place on payment method setup by API request**. So in case your API request is like below,&#x20;

```json
"payment": {
      "payment_method_types": [
          "VIRTUAL_ACCOUNT_BCA",
          "VIRTUAL_ACCOUNT_BANK_MANDIRI"
          ]
```

and the payment method you checked is **more** than the payment method above, then what will appear on the checkout page is the payment method that you entered in the API request (provided that the checkout page status is active on the dashboard).

<figure><img src="/files/TEePKVktM7fntrJwzPYE" alt="" width="297"><figcaption></figcaption></figure>

### Custom Expiry Time

1. **Custom order payment due date via Dashboard**

   You can set the default of order payment due date (expiry time) via DOKU Dashboard, by following step below.

   1. Login to DOKU Dashboard
   2. Go to **Setting > Checkout Page > Payment Method Settings Tab**&#x20;
   3. Go to due date section, input your preferred due date (in hours and minutes)
   4. Click **save**

   <figure><img src="/files/5ws81gTJZJsRmYIAAbB4" alt=""><figcaption><p>Expiry time on Dashboard</p></figcaption></figure>
2. **Custom order payment due date via API Request**

   You also could set the payment due date from API request, this refer to **each** order created.&#x20;

```json
"payment": {
      "payment_due_date": 60
}
```

If you are not put the parameter`payment_due_date`on your API request and Dashboard, the payment\_due\_date will automatically set by default in 60 minutes

### Custom Result Page URL

Use this feature if you want to set a custom result URL for customers to be redirected to after generating a payment code or making a payment.&#x20;

By default, DOKU will redirect the customer to DOKU success page. But you can override that configuration by specifying `callbacks.url` parameter. This will allow you to have specific redirect for each specific payment.

### Customize Interface of Checkout Page

DOKU Checkout integrates seamlessly with your website or app, letting you personalize the checkout experience with your brand elements. Upload your logo, choose from a range of header styles, and set your preferred language to create a familiar and cohesive checkout flow that builds trust and boosts conversions.

You could set the DOKU checkout interface via DOKU Dashboard, by follow these step :&#x20;

* Login to DOKU Dashboard
* Go to **Setting > Checkout Page > Interface Settings**
* Adjust your company **logo**
* Set your checkout **default language**
* Adjust **checkout interface** by your preferred color, luckily you can compare the desktop and mobile view!
* Click **save!**

<figure><img src="/files/J0ovn9IQdZPV1gC8gcFL" alt=""><figcaption><p>Change logo &#x26; default language</p></figcaption></figure>

<figure><img src="/files/kw6fbCYVa7okNZHwcF1q" alt=""><figcaption><p>Adjust Checkout Interface</p></figcaption></figure>

### Credit card installment - show tenor based on preference

{% hint style="info" %}
**Note:** Regarding credit card installment settings, merchants need to register their MID with their acquirer for full functionality. For detailed information on MID registration, please refer to this section.
{% endhint %}

**Use case :**

**If you only want to display general installment options for all acquirers (not specific to individual acquirers), you can do so through the API request.**&#x20;

For example, even though BCA offers 3, 6, and 12-month installments, you can choose to show only 3 and 6 months in your interface.

The sample request is :&#x20;

```json
"additional_info":{
  "allow_tenor" : [3,6]
}
```


# Direct API

Create your own payment page from scratch!

Here is Direct API, where we guide you through seamlessly integrating your system with the DOKU API. This comprehensive resource is designed to empower you, ensuring that your systems communicate effortlessly.&#x20;

This direct system-to-system interaction opens the door for you to customize and tailor the experience to align perfectly with your brand, providing a unique and branded touchpoint for your customers. Embrace the freedom to personalize and enhance your customer interactions through our user-friendly API integration. Let's embark on this journey together, creating a bespoke experience that reflects your brand identity.

{% hint style="info" %}
Tips for you!&#x20;

If you prefer not to start from scratch with individual each channels or build your own Payment Page, DOKU offers a seamless solution for you.&#x20;

Connect to [DOKU Checkout](/accept-payments/doku-checkout)  – an API tool that allows you to integrate once and effortlessly accept a multitude of payments and use our Payment Page. Simplify your workflow, enhance efficiency, and enjoy the convenience of managing diverse payments through a single integration. Connect to DOKU Checkout for a hassle-free and comprehensive payment solution.
{% endhint %}


# Non-SNAP

Do you want to customize your own payment page? DOKU provides REST API that you can use to directly integrate with us. The integration is very simple and we also provide code library in various programming languages to help you integrate.

Simply choose which payment channels that you want to integrate and follow through:


# Card

DOKU provides various payment channels. One of the most used is Credit Card. By using this payment channel, your customers can pay their order with their credit card or any online transaction capable debit card. DOKU has partenered with various banks and principals (Visa, MasterCard, JCB, Amex) to provide a secure and seamless payment experience for your customers.

***

#### Integration Option

You can integrate credit card in two ways based on the PCI DSS compliance:

* Non-PCI DSS certified merchant is allowed to integrate through [Direct Payment Page API](/accept-payments/direct-api/non-snap/card/payment-page-integration-guide), or through our [Checkout Page](/accept-payments/doku-checkout), where we will process customer's card information securely for you
* If you are  PCI DSS certified, you can integrate through  [H2H (Host to Host) API](/accept-payments/direct-api/non-snap/card/host-to-host-integration-guide)&#x20;

#### **What is PCI DSS?**

The Payment Card Industry Data Security Standard (PCI DSS) is an information security standard for organizations that handle branded credit cards from the major card schemes. The PCI Standard is mandated by the card brands but administered by the Payment Card Industry Security Standards Council.

#### **Supported Payment Type**

| Payment Type      | Description                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SALE              | This is a single transaction where the authorization (approval of funds) and capture (deduction from the card) happen at the same time. It’s common for retail purchases where funds are immediately processed.                                                                                                                                                                   |
| Authorize Capture | This involves two steps. First, the **authorization** checks if funds are available and reserves them but doesn’t immediately deduct them. Later, a **capture** request completes the transaction and deducts the funds. Often used for services where a final amount might not be determined upfront, like hotels or rentals.                                                    |
| Installment       | Allows cardholders to split the payment over a series of periodic payments (e.g., monthly) instead of paying the entire amount upfront. It’s a way to make larger purchases more manageable and is generally arranged in collaboration with the acquiring bank.                                                                                                                   |
| MOTO              | <p>This is a type of transaction where the card is not physically present, typically used in orders taken over the phone or by mail. Merchants manually enter the card details into the system. each MOTO transaction is generally independent </p><p><code>Only available with Host-To-Host Integration</code> </p>                                                              |
| Recurring         | <p>Designed for ongoing services (like subscriptions), where the card is automatically charged at regular intervals (e.g., monthly). It requires the cardholder’s consent for ongoing billing and doesn’t need their card information every time. each recurring transaction is identified by the billing number<br><code>Only available with Host-To-Host Integration</code></p> |

***

Learn more how to start accept payments with Credit Card:

* [Payment Page Integration (for Non PCI DSS compliance)](/accept-payments/direct-api/non-snap/card/payment-page-integration-guide)


# Payment Page Integration Guide

If you are non-PCI DSS compliance, you can use this type of integration to ensure that the Cards data of the customer is securely processed by DOKU.

***

### Integration steps <a href="#integration-steps" id="integration-steps"></a>

Here is the overview of how to integrate with Cards channel:

1. Generate payment URL (Cards payment page)
2. Display payment URL (Cards payment page)
3. Create test payment
4. Acknowledge payment result

<figure><img src="/files/SeftSkxs2UpB8zplNRzC" alt=""><figcaption><p>Cards Transaction Flow</p></figcaption></figure>

***

#### 1. Generate payment URL (Card payment page) <a href="#id-1-generate-payment-url-credit-card-payment-page" id="id-1-generate-payment-url-credit-card-payment-page"></a>

To generate a payment URL, you will need to hit this API through your backend:

**API Request**

| Type                          | Value                                                      |
| ----------------------------- | ---------------------------------------------------------- |
| **HTTP Method**               | POST                                                       |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/credit-card/v1/payment-page` |
| **API endpoint (Production)** | `https://api.doku.com/credit-card/v1/payment-page`         |

Here is the sample of request header to generate the payment URL:

<pre><code><strong>Client-Id: MCH-0001-10791114622547
</strong>Request-Id: b266c265-3d61-4708-9860-c0d5b9a98f8c
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
</code></pre>

<table><thead><tr><th width="199">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>client-id</code></strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong><code>request-id</code></strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong><code>request-timestamp</code></strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong><code>signature</code></strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="https://developers.doku.com/getting-started-with-doku-api/signature-component/non-snap/signature-component-from-request-header">this section</a> to generate the signature</td></tr></tbody></table>

Here is the sample request body to generate payment URL:

{% tabs %}
{% tab title="Sale" %}

```json
{
  "order": {
    "invoice_number": "INV-20210118-0001",
    "amount": 90000,
    "line_items": [
      {
        "name": "T-Shirt Red",
        "price": 30000,
        "quantity": 2
      },
      {
        "name": "Polo Navy",
        "price": 30000,
        "quantity": 1
      }
    ],
    "callback_url": "https://merchant.com/success-url",
    "failed_url": "https://merchant.com/failed-url",
    "auto_redirect": false,
    "descriptor": "Test Descriptor"
  },
  "customer": {
    "id": "CUST-0001",
    "name": "Jotaro Kujo",
    "email": "jotaro_kujo@example.com",
    "phone": "6285694566147",
    "address": "Menara Mulia Lantai 8",
    "country": "ID"
  },
  "payment": {
    "type": "SALE"
  },
  "override_configuration": {
    "themes": {
      "language": "EN",
      "background_color": "1B1F3B",
      "font_color": "F5F5F5",
      "button_background_color": "D4AF37",
      "button_font_color": "1B1F3B"
    }
  }
}
```

{% endtab %}

{% tab title="Authorize-Capture" %}

```json
{
  "order": {
    "invoice_number": "INV-20210118-0001",
    "amount": 90000,
    "line_items": [
      {
        "name": "T-Shirt Red",
        "price": 30000,
        "quantity": 2
      },
      {
        "name": "Polo Navy",
        "price": 30000,
        "quantity": 1
      }
    ],
    "callback_url": "https://merchant.com/success-url",
    "failed_url": "https://merchant.com/failed-url",
    "auto_redirect": true,
    "descriptor": "Test Descriptor"
  },
  "customer": {
    "id": "CUST-0001",
    "name": "Haruhi Suzumiya",
    "email": "Haruhi@example.com",
    "phone": "6285694566147",
    "address": "Menara Mulia Lantai 8",
    "country": "ID"
  },
  "payment": {
    "type": "AUTHORIZE"
  },
  "override_configuration": {
    "themes": {
      "language": "EN",
      "background_color": "FFF8C6",
      "font_color": "1E2A44",
      "button_background_color": "FFD400",
      "button_font_color": "1E2A44"
    }
  }
}
```

{% endtab %}

{% tab title="Installment" %}

```json
{
  "order": {
    "invoice_number": "INV-20210118-0001",
    "amount": 90000,
    "line_items": [
      {
        "name": "T-Shirt Red",
        "price": 30000,
        "quantity": 2
      },
      {
        "name": "Polo Navy",
        "price": 30000,
        "quantity": 1
      }
    ],
    "callback_url": "https://merchant.com/success-url",
    "failed_url": "https://merchant.com/failed-url",
    "auto_redirect": false,
    "descriptor": "Test Descriptor"
  },
  "customer": {
    "id": "CUST-0001",
    "name": "Roxy Greyrat",
    "email": "roxy_greyrat@example.com",
    "phone": "6285694566147",
    "address": "Menara Mulia Lantai 8",
    "country": "ID"
  },
  "payment": {
    "type": "INSTALLMENT",
    "acquirer": "BRI",
    "tenor": 3
  },
  "override_configuration": {
    "themes": {
      "language": "EN",
      "background_color": "EEF3F8",
      "font_color": "243B5A",
      "button_background_color": "3F5F8A",
      "button_font_color": "FFFFFF"
    }
  },
  "additional_info": {
    "override_notification_url": "https://another.example.com/payments/notifications",
    "disclaimer": {
      "id": "Testing",
      "en": "testing englis"
    }
  }
}
```

{% endtab %}
{% endtabs %}

#### Request body Explanation

<table><thead><tr><th width="196">Body Parameter</th><th>Type`</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.amount</code></td><td>number</td><td>Mandatory</td><td>In IDR Currency and without decimal</td></tr><tr><td><code>order.invoice_number</code></td><td>string</td><td>Mandatory</td><td>Generated by merchant to identify the order<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code><br><code>(30 If you have Mandiri Acquirer)</code></td></tr><tr><td><code>order.callback_url</code></td><td>string</td><td>Conditional</td><td>Merchant URL that will redirected to after the order success. Mandatory if merchant set <code>order.auto_redirect</code> to <code>true</code><br>Allowed chars: <code>alphabetic, numeric, special chars</code></td></tr><tr><td><code>order.failed_url</code></td><td>string</td><td>Conditional</td><td>Merchant URL that will redirected to after the order failed. If not set, then will redirect to <code>callback_url</code><br>Allowed chars: <code>alphabetic, numeric, special chars</code></td></tr><tr><td><code>order.auto_redirect</code></td><td>string</td><td>Mandatory</td><td>Redirection to defined <code>callback_url</code> after payment process completed<br>Possible value: <code>true, false</code><br>Default value: <code>false</code></td></tr><tr><td><code>order.line_items.name</code></td><td>string</td><td>Optional</td><td>Name of the product item.<br>Max Length: <code>255</code></td></tr><tr><td><code>order.line_items.price</code></td><td>number</td><td>Conditional</td><td>Price of the product item. Total price and quantity must match with the <code>order.amount</code>.</td></tr><tr><td><code>order.line_items.quantity</code></td><td>number</td><td>Conditional</td><td>Quantity of the product item.</td></tr><tr><td><code>order.descriptor</code></td><td>string</td><td>Optional</td><td>Custom string to be printed on Customer's billing statement history on issuing side, Please contact DOKU team to manually configure this feature first<br>Max length: <code>22</code> <code>need to be activated, please consult DOKU team first</code></td></tr><tr><td><code>card.token</code></td><td>string</td><td>optional</td><td>Card token generated by DOKU. If you sent this, then the customer's Card will be pre-filled in the Card Number field.</td></tr><tr><td><code>card.save</code></td><td>boolean</td><td>Optional</td><td>Set <code>true</code> if you want to force customer to save the card token for the next payment</td></tr><tr><td><code>customer.id</code></td><td>string</td><td>Conditional</td><td>Unique customer identifier generated by merchant. Mandatory if merchant wants to use tokenization feature.</td></tr><tr><td><code>customer.name</code></td><td>string</td><td>Recommended</td><td>Customer Name</td></tr><tr><td><code>customer.email</code></td><td>string</td><td>Conditional</td><td>Customer email.<br>Mandatory if <code>customer phone</code> value blank.<br>Bringing the proper email will improve Credit Card Approval Rate<br><strong><code>DO NOT SEND STATIC/DUMMY VALUE</code></strong></td></tr><tr><td><code>customer.phone</code></td><td>string</td><td>Conditional</td><td>Customer phone number. Format: <code>{calling_code}{phone_number}</code>. Example: 6281122334455.<br>Mandatory if <code>customer email</code> value blank.<br>One of them must be filled in between <code>customer email</code> and <code>customer phone</code></td></tr><tr><td><code>customer.address</code></td><td>string</td><td>Optional</td><td>Customer address</td></tr><tr><td><code>customer.country</code></td><td>string</td><td>Optional</td><td>2 alphabetic country code ISO 3166-1</td></tr><tr><td><code>override_configuration.themes.</code><br><code>language</code></td><td>string</td><td>Optional</td><td>Default language that will be displayed on the Payment Page<br>Possible value: English <code>EN</code>, Indonesia <code>ID</code><br>Default: English <code>EN</code></td></tr><tr><td><code>override_configuration.themes.</code><br><code>background_color</code></td><td>string</td><td>Optional</td><td>HEX color code for the payment page background color. Example: <code>FFFFFF</code><br>Default: Light gray <code>F5F8FB</code></td></tr><tr><td><code>override_configuration.themes.</code><br><code>font_color</code></td><td>string</td><td>Optional</td><td>HEX color code for the payment page font color. Example: <code>000000</code><br>Default: Soft black <code>1A1A1A</code></td></tr><tr><td><code>override_configuration.themes.</code><br><code>button_background_color</code></td><td>string</td><td>Optional</td><td>HEX color code for the payment page button background color. Example: <code>000000</code><br>Default: Red <code>E1251B</code></td></tr><tr><td><code>override_configuration.themes.</code><br><code>button_font_color</code></td><td>string</td><td>Optional</td><td>HEX color code for the payment page button font color. Example: <code>FFFFFF</code><br>Default: White <code>FFFFFF</code></td></tr><tr><td><code>override_configuration.promo[].</code><br><code>bin</code></td><td>string</td><td>Optional</td><td>BIN that will get the promo<br><code>Please consult with Issuer Bank or DOKU team, some BIN are 6 and some are 8 Digit</code></td></tr><tr><td><code>override_configuration.promo[].</code><br><code>discount_amount</code></td><td>number</td><td>Optional</td><td>Promo Discount if BIN input matched<br>(final amount = <code>order.amount</code> - <code>override_configuration.promo[].discount_amount</code>)</td></tr><tr><td><code>override_configuration.allow_bin</code></td><td>number</td><td>Optional</td><td>Transaction only accept BIN listed here <br><code>Please consult with Issuer Bank or DOKU team, some BIN are 6 and some are 8 Digit</code></td></tr><tr><td><code>override_configuration.allow_tenor</code></td><td>number</td><td>Optional</td><td>Transaction only accept installment tenor listed here</td></tr><tr><td><code>additional_info.override_notification_url</code></td><td>string</td><td>Optional</td><td>This parameter is intended to override the configured <code>Notification URL</code> with another URL.  Click <a href="/pages/LfaJBdkpBWDjF7mwEimR">here</a> for more information.</td></tr><tr><td><code>additional_info.disclaimer</code></td><td>object</td><td>Optional</td><td>Bring this if you want to customer to opt-in customer has agreed to the payment disclaimer</td></tr><tr><td><code>additional_info.disclaimer.id</code></td><td>object</td><td>Optional</td><td>disclaimer message in Indonesian</td></tr><tr><td><code>additional_info.disclaimer.en</code></td><td>object</td><td>v</td><td>disclaimer message in English(default)</td></tr><tr><td><code>payment.type</code></td><td>string</td><td>Conditional</td><td>Bring this if you have more than 1 type of Cards payment type to specify how you want this transaction to be processed (Possible Values : <code>INSTALLMENT</code>, <code>AUTHORIZE</code>, <code>SALE</code>)</td></tr><tr><td><code>payment.auto_capture</code></td><td>string</td><td>Optional</td><td>Brings this if the payment type is 'authorize' but you wish to capture the transaction right away as if it was a SALE transaction <br><br><code>eg : "auto_capture"=:true</code></td></tr><tr><td><code>payment.acquirer</code></td><td>string</td><td>Conditional</td><td>Becomes mandatory if transaction type is <code>INSTALLMENT</code>, to specify to which acquirer you want this transaction to be processed to (Possible Values: <code>BNI</code>, <code>BRI</code>, <code>BANK_CIMB</code>, <code>BANK_MANDIRI</code>, <code>BCA, BANK_PERMATA, DANAMON, BUKOPIN, HSBC, OCBC_NISP</code>)</td></tr><tr><td><code>payment.tenor</code></td><td>number</td><td>Conditional</td><td>Becomes mandatory if transaction type is <code>INSTALLMENT</code>, to specify which tenor you want this transaction to be processed with</td></tr></tbody></table>

{% hint style="info" %}
**Payment Type**

* **Sale**: A transaction where funds are immediately transferred from the customer's account to the merchant's account.
* **Authorize-Capture**: A two-step transaction where funds are first reserved (authorized) and later transferred (captured) from the customer's account to the merchant's account. Capture can be done via [Capture API ](#additional-features)or via Back Office [Dashboard Transaction Report](https://dashboard.doku.com/bo/report/transactions)
* **Installment**: A transaction where the total amount is split into multiple smaller payments over a specified period.
* **MOTO (Mail Order/Telephone Order)**: A transaction where payment does not require CVV or OTP, suitable for subscription payment type, must use [Host-to-Host API](/accept-payments/direct-api/non-snap/card/host-to-host-integration-guide)
* **Recurring**: A transaction where payment does not require CVV or OTP, suitable for subscription payment type, with the latest specification more secure compared to **MOTO,** must use [Host-to-Host ](/accept-payments/direct-api/non-snap/card/host-to-host-integration-guide)API

{% endhint %}

{% hint style="info" %}
**Integration Type**

Currently for Integration through[ DOKU JS Integration](/accept-payments/direct-api/non-snap/card/doku-js-integration-guide), payment type must be either 'SALE' or 'AUTHORIZE'
{% endhint %}

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

Here is the sample response header:

```
Client-Id: MCH-0001-10791114622547
Request-Id: b266c265-3d61-4708-9860-c0d5b9a98f8c
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
```

<table><thead><tr><th width="199">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>client-id</code></strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong><code>request-id</code></strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong><code>request-timestamp</code></strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong><code>signature</code></strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="https://developers.doku.com/getting-started-with-doku-api/signature-component/non-snap/signature-component-from-request-header">this section</a> to generate the signature</td></tr></tbody></table>

Here is the sample of response body:

```json
{
    "order": {
        "invoice_number": "INV-20210118-0001",
        "line_items": [
            {
                "name": "T-Shirt Red",
                "price": 30000,
                "quantity": 2
            },
            {
                "name": "Polo Navy",
                "price": 30000,
                "quantity": 1
            }
        ]
    },
    "credit_card_payment_page": {
        "url": "https://sandbox.doku.com/wt-frontend-transaction/dynamic-payment-page?signature=OVVQVUZ6T3FKYzQ3YUp6RDlFU09UY1dnNlRNc2czbXFTUCtEblVPOEVORT0=&clientId=MCH-0001-10791114622547&invoiceNumber=INV-20210118-0001&requestId=8quQyK39l4aM5cCml0Yy"
    },
    "credit_card_js": {
     "session_id": "ps_sit_1761107459919_Dv7nPW51NX"
     },
    "additional_info": {
        "override_notification_url": "https://another.example.com/payments/notifications"
    }
}
```

Here is the sample of **failed** response body:

```
{
    "errors": {
        "code": "INVALID_PARAMETER",
        "message": "Invalid Total Amount And Line Items",
        "type": "Invalid Parameter"
    }
}
```

#### Response Body Explanation

<table><thead><tr><th>Body Parameter</th><th width="122">Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.invoice_number</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as the request</td></tr><tr><td><code>order.line_items.name</code></td><td><code>string</code></td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>order.line_items.price</code></td><td><code>number</code></td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>order.line_items.quantity</code></td><td>number</td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>credit_card_payment_page.url</code></td><td>string</td><td>Mandatory</td><td>Cards Payment Page URL generated by DOKU that merchant displays to the customer</td></tr><tr><td><code>credit_card_js.session_id</code></td><td>string</td><td>Conditional</td><td>Identifier for <a href="/pages/1rAmc0FE0o80zkS2g8eH">DOKU JS integration</a>, will be returned for merchant who uses DOKU JS feature</td></tr><tr><td><code>additional_info.override_notification_url</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr></tbody></table>

{% hint style="info" %}
**INFO**

DOKU provides risk assessment for card transactions, your customer data sent to us will help manage your risk of every transaction.
{% endhint %}

***

#### 2. Display payment URL (Cards payment page) <a href="#id-2-display-payment-url-credit-card-payment-page" id="id-2-display-payment-url-credit-card-payment-page"></a>

You can display the payment URL as an iFrame or as a dedicated page to your customer by using `credit_card_payment_page.url`  the retrieved from API Response. Here is the sample of Cards on the iFrame:

<figure><img src="/files/LYheHoWVPPETJJv08aUC" alt=""><figcaption></figcaption></figure>

***

#### 3. Creating Test Payment <a href="#id-3-creating-test-payment" id="id-3-creating-test-payment"></a>

You can try the payment with various Cards listed here:

* [Test Credit Card List](https://sandbox.doku.com/integration/simulator/credit-card)

***

#### 4. Acknowledge payment result <a href="#id-4-acknowledge-payment-result" id="id-4-acknowledge-payment-result"></a>

After the payment is made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`. Learn how to handle the notification from DOKU:

* [Handling HTTP Notification](https://developers.doku.com/getting-started-with-doku-api/notification)

***

{% hint style="info" %}
**INFO**

You can check the list of possible response code and how to handle them[ here](/get-started-with-doku-api/response-code/http-status-and-case-code)&#x20;
{% endhint %}

### Authorize Capture <a href="#additional-features" id="additional-features"></a>

If you bring `payment.type ='AUTHORIZATION'` you need to capture the transaction within 7 days to have the amount actually transferred to your settlement balance or the transaction will be automatically released.

After you get the `payment.authorize_id`in notification HTTP, then your backend must trigger the API Charge to DOKU:

**API Request**

| Type                          | Value                                              |
| ----------------------------- | -------------------------------------------------- |
| **HTTP Method**               | POST                                               |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/credit-card/capture` |
| **API endpoint (Production)** | `https://api.doku.com/credit-card/capture`         |

Here is the sample of request header to capture the transaction:

```
Client-Id: MCH-0001-10791114622547
Request-Id: 071a6a32-6785-4011-833d-d2c2049cf744
Request-Timestamp: 2021-08-24T08:46:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

<table><thead><tr><th width="199">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>client-id</code></strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong><code>request-id</code></strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong><code>request-timestamp</code></strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong><code>signature</code></strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="https://developers.doku.com/getting-started-with-doku-api/signature-component/non-snap/signature-component-from-request-header">this section</a> to generate the signature</td></tr></tbody></table>

Here is the sample request body to capture the transaction:

```json
{
    "payment": {
        "authorize_id": "12312391719112",
        "capture_amount": 90000
    }
}
```

Request Body Explanation

| Parameter                | Type     | Mandatory | Description                                                                                                                                            |
| ------------------------ | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `payment.authorize_id`   | `string` | Mandatory | Authorize ID from the Charge API Response / [HTTP Notification](/get-started-with-doku-api/notification/http-notification-sample-non-snap#credit-card) |
| `payment.capture_amount` | `string` | Optional  | The value of transactions which will be paid by the customer. If undefined, capture full transaction.                                                  |

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

Here is the sample response header:

```
Client-Id: MCH-0001-10791114622547
Request-Id: b266c265-3d61-4708-9860-c0d5b9a98f8c
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
```

<table><thead><tr><th width="199">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>client-id</code></strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong><code>request-id</code></strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong><code>request-timestamp</code></strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong><code>signature</code></strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="https://developers.doku.com/getting-started-with-doku-api/signature-component/non-snap/signature-component-from-request-header">this section</a> to generate the signature</td></tr></tbody></table>

Here is the sample of response body:

```json
{
    "order": {
        "invoice_number": "INV-20210118-0001",
        "amount": 90000
    },
    "customer": {
        "id": "CUST-0001"
    },
    "payment": {
        "type": "CAPTURE",
        "identifier": [
           {
              "name": "Acquirer",
              "value": "Mandiri"
           },
           {
              "name": "MID",
              "value": "71003372992"
           },
           {
              "name": "TID",
              "value": "73120903"
           }
        ],
        "request_id": "20201026193843836",
        "authorize_id": "12312391719112",
        "response_code": "01",
        "response_message": "sukses transaksi",
        "eci": "05",
        "status": "SUCCESS",
        "approval_code": "123123"
    },
    "three_dsecure": {
        "authentication_id": "eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e"
    },
    "card": {
        "masked": "557338*******101",
        "type": "CREDIT",
        "issuer": "Bank Mandiri",
        "brand": "MASTER",
        "token": "243591d7e49f45109961581718c3ef82"
    }
}
```

Response Body Explanation

| Parameter                         | Type     | Mandatory | Description                                                                        |
| --------------------------------- | -------- | --------- | ---------------------------------------------------------------------------------- |
| `order.invoice_number`            | `string` | Mandatory | Same as the request                                                                |
| `order.amount`                    | `number` | Mandatory | Same as the request                                                                |
| `customer.id`                     | `string` | Optional  | Same as the request                                                                |
| `payment.type`                    | `string` | Mandatory | Same as the request                                                                |
| `payment.identifier.name`         | `string` | Mandatory | Additional payment info name                                                       |
| `payment.identifier.value`        | `string` | Mandatory | Additional payment info value                                                      |
| `payment.request_id`              | `string` | Mandatory | Request ID sent on merchant's request header                                       |
| `payment.authorize_id`            | `string` | Mandatory | Authorize ID for authorize transaction. Mandatory if `payment.type` is `AUTHORIZE` |
| `payment.response_code`           | `string` | Mandatory | Reponse code generated by DOKU / Acquirer                                          |
| `payment.response_message`        | `string` | Mandatory | Response message generated by DOKU / Acquirer                                      |
| `payment.status`                  | `string` | Mandatory | <p>Payment status<br>Possible value: <code>SUCCESS, FAILED, PENDING</code></p>     |
| `payment.eci`                     | `string` | Mandatory | ECI for this transaction                                                           |
| `payment.approval_code`           | `string` | Optional  | Approval code for success transaction generated by acquirer                        |
| `three_dsecure.authentication_id` | `string` | Mandatory | Same as the request                                                                |
| `card.masked`                     | `string` | Optional  | Card masked number                                                                 |
| `card.type`                       | `string` | Mandatory | <p>Card type<br>Possible value: <code>CREDIT, DEBIT</code></p>                     |
| `card.issuer`                     | `string` | Mandatory | Card issuer                                                                        |
| `card.brand`                      | `string` | Mandatory | <p>Principal brand<br><code>VISA, MASTER, JCB, AMEX</code></p>                     |
| `card.token`                      | `string` | Optional  | Card token generated by DOKU if `card.save` is `true`                              |

***

### Installment <a href="#installment" id="installment"></a>

{% hint style="info" %}
**Installment ON US**

BCA, Bank Mandiri, BNI only allow for ON US Installment. You must request an Installment MID from each respective acquirer.

**Installment OFF US**

Bukopin, Danamon, Permata, HSBC, OCBC allows OFF US Installment. you must have at least one SALE MID.
{% endhint %}

You can activate installment features on [Service Activation page ](https://dashboard.doku.com/bo/business-account/service) to let your customers pay in terms, you will receive full payment ahead and issuer Bank will charge the customer each month depending on tenor and amount of the transaction.

There are minimal transaction amounts for each installment (depending on the issuer) and you can see the details in the installment configuration page.

{% hint style="success" %}
**Testing Installment Payment**

If you wish to try installment, make sure that you specific bank dummy credit card presented [here](https://sandbox.doku.com/integration/simulator/credit-card) and make sure that your transaction amount is equal to more than the minimum transaction required
{% endhint %}

***

#### Split Settlement <a href="#split-settlement" id="split-settlement"></a>

If you are a platform or a marketplace, you can use this feature to settle the funds to your sellers or partners programmatically, save many operational efforts.

* [Settlement](/accept-payments/finance-and-settlement/split-settlement)

***

### What's next? <a href="#whats-next" id="whats-next"></a>

Make a test payment in the Sandbox environment using the dummy credit card that we have prepared to ensure that your application has been successfully integrated.

* [Click here to see the dummy card list for testing](https://sandbox.doku.com/integration/simulator/credit-card)


# Host-To-Host Integration Guide

## Host to Host Integration Guide

{% hint style="info" %}
You can only use this Integration if you are either&#x20;

* PCI DSS Certified Merchant, sending Card Number for each transaction

or&#x20;

* You have previously tokenized a card using our Payment Integration Guide or DOKU Checkout, sending Token for each transaction[​](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#sale-integration-steps)
  {% endhint %}

<details>

<summary>DOKU Direct - Credit Card H2H Sequence Diagram</summary>

<figure><img src="/files/lgDpZ2Wdev3NzHSh5JAN" alt=""><figcaption></figcaption></figure>

</details>

Here is the overview of how to integrate process transaction using H2H API:

1. Prepare credit card form input / [Get token list **(Optional)**](/accept-payments/direct-api/non-snap/card/tokenization)
2. Hit Check 3DS to Get 3DS authentication ID and 3DS URL **(Conditional)**
3. Hit API Charge
4. Acknowledge payment result

{% hint style="info" %}
Get Token List is **Optional**, only needed if you utilize DOKU's tokenization feature where you can send token instead of cards number to avoid security risk by sending sensitive data

Check 3DS Process is **Conditional,** it is required for payment type **SALE, AUTHORIZE, INSTALLMENT** but not required for **MOTO & RECURRING,** you may skip this process and proceed to Charge API&#x20;
{% endhint %}

### Check 3D Secure <a href="#sale-integration-steps" id="sale-integration-steps"></a>

3D Secure (3DS) is an authentication protocol used in online credit card transactions to enhance security and reduce fraud. It requires the cardholder to complete an additional verification step with their issuing bank before the transaction is approved. This process helps confirm that the legitimate cardholder is making the purchase.

**API Request**[**​**](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#api-request)

| Type                          | Value                                                           |
| ----------------------------- | --------------------------------------------------------------- |
| **HTTP Method**               | POST                                                            |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/credit-card/check-three-d-secure` |
| **API endpoint (Production)** | `https://api.doku.com/credit-card/check-three-d-secure`         |

Here is the sample of request header to get 3DS authentication:

```
Client-Id: MCH-0001-10791114622547
Request-Id: 6d0bffbd-9246-455e-a1f1-44c1f76ad589
Request-Timestamp: 2021-08-24T08:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

Request Header Explanation

| Parameter             | Description                                                                                                                                                                                                                                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client-Id**         | Client ID retrieved from DOKU Back Office                                                                                                                                                                                                                                                                                                         |
| **Request-Id**        | Unique random string (max 128 characters) generated from merchant side to protect duplicate request                                                                                                                                                                                                                                               |
| **Request-Timestamp** | Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z                                                                                     |
| **Signature**         | Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to [this section](https://developers.doku.com/get-started-with-doku-api/signature-component/non-snap/signature-component-from-request-header) to generate the signature |

Here is the sample request body to get 3DS authentication:

```json
{
    "order": {
        "amount": 90000,  
        "invoice_number": "test_invoice"
    },
    "card": {
        "token": "243591d7e49f45109961581718c3ef82", //just bring ONE, either token or number
        "number": "4512490000000907", //just bring ONE, either token or number
        "expiry": "1230"
    },
    "payment": {
        "type": "SALE"
    },
    "three_dsecure": {
        "callback_url_success": "https://www.merchant.com/success",
        "callback_url_failed": "https://www.merchant.com/failed"
    }
}
```

Request Body Explanation

| Parameter                            | Type      | Mandatory   | Description                                                                                                                                                                                                                                            |
| ------------------------------------ | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `order.amount`                       | `number`  | Mandatory   | <p>In IDR Currency and without decimal<br>Allowed chars: <code>numeric</code><br>Max length: <code>12</code></p>                                                                                                                                       |
| `order.invoice_number`               | string    | Optional    | <p>Invoice number of the transaction, if brought use consistent invoice number during charge as well<br><strong>Recommended to bring</strong><br>Max length: <code>64</code><br><code>30 for mandiri</code></p>                                        |
| `card.token`                         | `string`  | Conditional | <p>Card token generated by DOKU, can be used if you already activate tokenization</p><p><code>either card.token or card.number must be sent</code></p>                                                                                                 |
| `card.number`                        | `string`  | Conditional | Card numbe printed on card `either card.token or card.number must be sent`                                                                                                                                                                             |
| `card.expiry`                        | `string`  | Conditional | <p>Card expiry date, can be optional if you sent <code>card.token</code><br>Format: <code>MMYY</code></p>                                                                                                                                              |
| `payment.type`                       | `string`  | Conditional | Bring this if you have more than 1 type of Cards payment type to specify how you want this transaction to be processed (Possible Values : `INSTALLMENT`, `AUTHORIZE`, `SALE`)                                                                          |
| `payment.acquirer`                   | `string`  | Conditional | Becomes mandatory if transaction type is `INSTALLMENT`, to specify to which acquirer you want this transaction to be processed to (Possible Values: `BNI`, `BRI`, `BANK_CIMB`, `BANK_MANDIRI`, `BCA, BANK_PERMATA, DANAMON, BUKOPIN, HSBC, OCBC_NISP`) |
| `payment.tenor`                      | `numeric` | Conditional | Becomes mandatory if transaction type is `INSTALLMENT`, to specify which tenor you want this transaction to be processed with                                                                                                                          |
| `three_dsecure.callback_url_success` | `string`  | Mandatory   | After 3DS process success, customer will be redirected to this page                                                                                                                                                                                    |
| `three_dsecure.callback_url_failed`  | `string`  | Mandatory   | If 3DS process failed, customer will be redirected to this page                                                                                                                                                                                        |

**API Response**[**​**](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#api-response)

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

Here is the sample response header:

```
Client-Id: MCH-0001-10791114622547
Request-Id: b266c265-3d61-4708-9860-c0d5b9a98f8c
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
```

Response Header Explanation

| **Client-Id**          | Same as the request                                           |
| ---------------------- | ------------------------------------------------------------- |
| **Request-Id**         | Same as the request                                           |
| **Response-Timestamp** | Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU |
| **Signature**          | Signature generated by DOKU based on the response body        |

Here is the sample of successful response body:

```json
{
    "order": {
        "amount": 90000
    },
    "three_dsecure": {
        "authentication_id": "eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e",
        "authentication_url": "https://doku.3ds.com?authenticationId=eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e",
        "three_ds_version": "2.0"
    }
}
```

Here is the sample of **failed** response body:

```json
{
    "error": {
        "code": "INVALID_PARAMETER",
        "message": "Card Number Length must be 15, 16 or 19 Digits",
        "type": "Invalid Parameter"
    }
}
```

Response Body Explanation

| Parameter                          | Type     | Mandatory | Description                                                                      |
| ---------------------------------- | -------- | --------- | -------------------------------------------------------------------------------- |
| `order.amount`                     | `number` | Mandatory | Same as the request                                                              |
| `three_dsecure.authentication_id`  | `string` | Mandatory | 3DS process ID to use on API Charge                                              |
| `three_dsecure.authentication_url` | `string` | Optional  | 3DS page that need to be opened by customer                                      |
| `three_dsecure.three_ds_version`   | `string` | Optional  | 3DS Version used to authenticate, value would be something like "2.x" or "2.x.x" |

[​](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#3-hit-api-charge)

### Charge API

After the customer is redirected to the 3DS success page, then your backend must trigger the API Charge to DOKU:

**API Request**[**​**](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#api-request)

| Type                          | Value                                             |
| ----------------------------- | ------------------------------------------------- |
| **HTTP Method**               | POST                                              |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/credit-card/charge` |
| **API endpoint (Production)** | `https://api.doku.com/credit-card/charge`         |

Here is the sample of request header to charge the transaction:

```
Client-Id: MCH-0001-10791114622547
Request-Id: b154c582-4501-436a-8012-0346f2a46b47
Request-Timestamp: 2021-08-24T08:46:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

Request Header Explanation

| Parameter             | Description                                                                                                                                                                                                                                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client-Id**         | Client ID retrieved from DOKU Back Office                                                                                                                                                                                                                                                                                                         |
| **Request-Id**        | Unique random string (max 128 characters) generated from merchant side to protect duplicate request                                                                                                                                                                                                                                               |
| **Request-Timestamp** | Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z                                                                                     |
| **Signature**         | Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to [this section](https://developers.doku.com/get-started-with-doku-api/signature-component/non-snap/signature-component-from-request-header) to generate the signature |

Here is the sample request body to charge the transaction:

```json
{
    "order": {
        "invoice_number": "INV-20210118-0001",
        "amount": 90000,
        "descriptor": "directSALE123456789",
        "line_items": [
            {
                "name": "T-Shirt Red",
                "price": 30000,
                "quantity": 2
            },
            {
                "name": "Polo Navy",
                "price": 30000,
                "quantity": 1
            },
        ]
    },
    "customer": {
        "id": "CUST-0001",
        "name": "Alisa Mikhailovna",
        "email": "alisa_mikhailovna@gmail.com",
        "phone": "6285694566147",
        "address": "Menara Mulia Lantai 8",
        "country": "ID"
    },
    "three_dsecure": {
        "authentication_id": "eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e"
    },
    "payment": {
        "type": "SALE", // SALE/AUTHORIZE/INSTALLMENT/MOTO/RECURRING
        "tenor": "12", //Conditional, delete if type != INSTALLMENT
        "plan_id": "1232131" //Conditional, delete if type != INSTALLMENT
    },
    "card": {
        "token": "243591d7e49f45109961581718c3ef82",
        "number": "4512490000000907", //just bring ONE, either token or number
        "expiry": "1230",
        "cvv": "123",
        "save": true
    }
}
```

{% hint style="info" %}
If you have your own 3DS Authenticator processor you can use our MPI (Merchant Plug-in) Feature by sending additional Authentication object like example below, note that this feature is not available for all merchant, please consult with DOKU team first.
{% endhint %}

```json
{
  "customer": {
    "name": "Char Aznable",
    "email": "char@gmail.com",
    "phone": "085313588532",
    "country": "ID",
    "address": "Side 6"
  },
  "order": {
    "invoice_number": "VHRJ6W4NMMTCPK52",
    "descriptor": "testdescriptor",
    "line_items": [
      {
        "name": "potato",
        "price": 8325000,
        "quantity": 1
      }
    ],
    "amount": 8325000
  },
  "payment": {
    "type": "SALE"
  },
  "card": {
    "number": "4512490000000907",
    "cvv": "322",
    "expiry": "0228",
    "save": false
  },
  "authentication": {
        "version": "3DS2",
        "3ds": {
            "eci": "02",
            "cavv": "Y2FyZGluYWxjb21tZXJjZWF1dGg=",
            "ds_transaction_id": "52ced05a-38bd-4c35-9aa2-f5df60cbb6c7",
            "status": "Y",
            "xid" : "251008095048818"
        }
  }
}
```

Request Body Explanation

<table><thead><tr><th width="301">Parameter</th><th>Type</th><th width="118.5999755859375">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.amount</code></td><td><code>number</code></td><td>Mandatory</td><td>In IDR Currency and without decimal<br>Allowed chars: <code>numeric</code><br>Max length: <code>12</code></td></tr><tr><td><code>order.invoice_number</code></td><td><code>string</code></td><td>Mandatory</td><td>Invoice number of the transaction, if brought use consistent invoice number during charge as well<br><strong>Recommended to bring</strong><br>Max length: <code>64</code><br><code>30 for Acquirer Mandiri</code></td></tr><tr><td><code>order.descriptor</code></td><td><code>String</code></td><td>Optional</td><td>Custom string to be printed on Customer's billing statement <br><br>Max length: <code>22</code><br><code>need to be activated, please consult DOKU team first</code></td></tr><tr><td><code>order.line_items.name</code></td><td><code>string</code></td><td>Optional</td><td>Name of the product item<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>255</code></td></tr><tr><td><code>order.line_items.price</code></td><td><code>number</code></td><td>Optional</td><td>Price of the product item. Total price and quantity must match with the <code>order.amount</code><br>Allowed chars: <code>numeric</code><br>Max Length: <code>12</code></td></tr><tr><td><code>order.line_items.quantity</code></td><td><code>number</code></td><td>Optional</td><td>Quantity of the product item<br>Allowed chars: <code>numeric</code><br>Max Length: <code>4</code></td></tr><tr><td><code>customer.id</code></td><td><code>string</code></td><td>Conditional</td><td>Unique customer identifier generated by merchant. Mandatory if merchant wants to use tokenization feature.<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>50</code></td></tr><tr><td><code>customer.name</code></td><td><code>string</code></td><td>Optional</td><td>Customer name<br>Allowed chars: <code>alphabetic</code><br>Max Length: <code>255</code></td></tr><tr><td><code>customer.email</code></td><td><code>string</code></td><td>Optional</td><td><p>Customer email<br>Allowed chars: <code>alphabetic, numeric, special chars</code></p><p></p><p><strong><code>DO NOT SEND STATIC/DUMMY VALUE</code></strong></p><p><br>Max Length: <code>128</code></p></td></tr><tr><td><code>customer.phone</code></td><td><code>string</code></td><td>Optional</td><td>Customer phone number. Format: <code>{calling_code}{phone_number}</code>. Example: 6281122334455<br>Allowed chars: <code>numeric</code><br>Max Length: <code>16</code></td></tr><tr><td><code>customer.address</code></td><td><code>string</code></td><td>Optional</td><td>Customer address<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>400</code></td></tr><tr><td><code>customer.country</code></td><td><code>string</code></td><td>Optional</td><td>2 alphabetic country code ISO 3166-1<br>Allowed chars: <code>alphabetic</code><br>Min-max Length: <code>2</code></td></tr><tr><td><code>three_dsecure.authentication_id</code></td><td><code>string</code></td><td>Conditional</td><td>Mandatory if 3DS transaction, Obtained from Check 3DS API</td></tr><tr><td><code>authentication.version</code></td><td><code>string</code></td><td>Optional</td><td>version of the 3ds authentication<br><br>example: 3DS2</td></tr><tr><td><code>authentication.3ds.eci</code></td><td><code>string</code></td><td>Optional</td><td><p>a ECI code provided by a indicating the outcome of the authentication attempt, bring for MPI 3DS</p><p></p><p>Allowed chars: <code>numeric</code></p><p>Min-max Length: <code>2</code></p></td></tr><tr><td><code>authentication.3ds.xid</code></td><td><code>string</code></td><td>Optional</td><td><p>a unique identifier associated with a specific transaction in the 3D Secure (3DS) authentication process, bring for MPI 3DS</p><p></p><p>Allowed chars: <code>numeric</code></p><p>Min-max Length: <code>20</code></p></td></tr><tr><td><code>authentication.3ds.cavv</code></td><td><code>string</code></td><td>Optional</td><td><p>a cryptographic value that links the issuer's authentication, bring for MPI 3DS</p><p></p><p>Allowed chars: <code>alphanumeric</code></p><p>Min-max Length: <code>1024</code></p></td></tr><tr><td><code>authentication.3ds.status</code></td><td><code>string</code></td><td>Optional</td><td><p>outcome of the 3D Secure (3DS) authentication process, Y/N</p><p></p><p>Allowed chars: <code>alphabhetic</code></p><p>Min-max Length: <code>1</code></p></td></tr><tr><td><code>authentication.3ds.ds_transaction_id</code></td><td><code>string</code></td><td>Optional</td><td><p>outcome of the 3D Secure (3DS) authentication process, Y/N</p><p></p><p>Allowed chars: <code>alpabethic, numberic, symbols</code></p><p>Min-max Length: <code>128</code></p></td></tr><tr><td><code>payment.type</code></td><td><code>string</code></td><td>Mandatory</td><td>Payment type<br>Possible value :<code>SALE, A MOTO,AUTHJORIZE,</code>      </td></tr><tr><td><code>payment.plan_id</code></td><td><code>string</code></td><td>Optional</td><td>Promotion ID from the bank for merchant</td></tr><tr><td><code>card.token</code></td><td><code>string</code></td><td>Optional</td><td>Card token generated by DOKU, for 3ds transaction please bring <code>three_dsecure.authentication_id</code> only</td></tr><tr><td><code>card.number</code></td><td><code>string</code></td><td>Mandatory</td><td>Card number, can be optional if you sent <code>card.token</code></td></tr><tr><td><code>card.expiry</code></td><td><code>string</code></td><td>Mandatory</td><td>Card expiry date, can be optional if you sent <code>card.token</code><br>Format: <code>MMYY</code></td></tr><tr><td><code>card.cvv</code></td><td><code>string</code></td><td>Mandatory</td><td>Card CVV, Optional if <code>payment.type</code> is <code>MOTO</code></td></tr><tr><td><code>card.save</code></td><td><code>boolean</code></td><td>Optional</td><td>Set <code>true</code> if you want to force customer to save the card token for the next payment<br>Possible value: <code>true, false</code><br>Default value: <code>false</code></td></tr></tbody></table>

**API Response**[**​**](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#api-response)

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

Here is the sample response header:

```
Client-Id: MCH-0001-10791114622547
Request-Id: b266c265-3d61-4708-9860-c0d5b9a98f8c
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
```

Response Header Explanation

| Parameter              | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| **Client-Id**          | Same as the request                                           |
| **Request-Id**         | Same as the request                                           |
| **Response-Timestamp** | Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU |
| **Signature**          | Signature generated by DOKU based on the response body        |

Here is the sample of response body:

```
{
    "order": {
        "invoice_number": "INV-20210118-0001",
        "amount": 90000
    {
     "customer": {
       "name": "Nadeshiko Kagamihara",
       "email": "nadeshiko.kamigahara@yuru.com",
       "phone": "085313588532",
       "country": "ID",
       "address": "Kofu"
  },
    "payment": {
        "type": "SALE",
        "identifier": [
           {
              "name": "Acquirer",
              "value": "Mandiri"
           },
           {
              "name": "MID",
              "value": "71003372992"
           },
           {
              "name": "TID",
              "value": "73120903"
           }
        ],
        "request_id": "20201026193843836",
        "authorize_id": "",
        "response_code": "00",
        "response_message": "Approved",
        "eci": "05",
        "status": "SUCCESS",
        "approval_code": "123123"
    },
    "three_dsecure": {
        "authentication_id": "eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e"
    },
    "card": {
        "masked": "557338*******101",
        "type": "CREDIT",
        "issuer": "Bank Mandiri",
        "brand": "MASTER",
        "token": "243591d7e49f45109961581718c3ef82"
    }
}
```

Here is the sample of response body: - **Rejected by Banks**

```
{
    "additional_info": "",
    "order": {
        "invoice_number": "test_51_insuffiient_amount",
        "amount": 300000.00
    },
    "payment": {
        "type": "SALE",
        "identifier": [
            {
                "name": "MID",
                "value": "018033035"
            },
            {
                "name": "TID",
                "value": "01803503"
            }
        ],
        "request_id": "42091",
        "response_code": "51",
        "response_message": "DECLINED",
        "status": "FAILED",
        "eci": "02"
    },
    "card": {
        "masked": "557692******0398",
        "type": "Debit",
        "issuer": "PT BANK CIMB NIAGA Tbk",
        "brand": "MASTER"
    },
    "error": {
        "code": "PAYMENT_FAILED",
        "message": "DECLINED",
        "type": "PAYMENT_FAILED"
    },
    "verification": {
        "status": "APPROVE",
        "reason": "Decision BIN Indonesia & 3D Secure"
    }
}
```

Here is the sample of response body: - **Invalid Parameters**

```
{
    "error": {
        "code": "INVALID_PARAMETER",
        "message": "Invalid Authentication Id",
        "type": "Invalid Parameter"
    }
}
```

Response Body Explanation

| Parameter                         | Type     | Mandatory   | Description                                                                                |
| --------------------------------- | -------- | ----------- | ------------------------------------------------------------------------------------------ |
| `order.invoice_number`            | `string` | Mandatory   | Same as the request                                                                        |
| `order.amount`                    | `number` | Mandatory   | Same as the request                                                                        |
| `customer.id`                     | `string` | Optional    | Same as the request                                                                        |
| `payment.type`                    | `string` | Mandatory   | Same as the request                                                                        |
| `payment.identifier.name`         | `string` | Mandatory   | Additional payment info name                                                               |
| `payment.identifier.value`        | `string` | Mandatory   | Additional payment info value                                                              |
| `payment.request_id`              | `string` | Mandatory   | Request ID sent on merchant's request header                                               |
| `payment.authorize_id`            | `string` | Conditional | Authorize ID for authorize-capture transaction. Mandatory if `payment.type` is `AUTHORIZE` |
| `payment.response_code`           | `string` | Mandatory   | Reponse code generated by DOKU / Acquirer                                                  |
| `payment.response_message`        | `string` | Mandatory   | Response message generated by DOKU / Acquirer                                              |
| `payment.status`                  | `string` | Mandatory   | <p>Payment status<br>Possible value: <code>SUCCESS, FAILED, PENDING</code></p>             |
| `payment.eci`                     | `string` | Mandatory   | ECI for this transaction                                                                   |
| `payment.approval_code`           | `string` | Optional    | Approval code for success transaction generated by acquirer                                |
| `three_dsecure.authentication_id` | `string` | Mandatory   | Same as the request                                                                        |
| `card.masked`                     | `string` | Optional    | Card masked number                                                                         |
| `card.type`                       | `string` | Mandatory   | <p>Card type<br>Possible value: <code>CREDIT, DEBIT</code></p>                             |
| `card.issuer`                     | `string` | Mandatory   | Card issuer                                                                                |
| `card.brand`                      | `string` | Mandatory   | <p>Principal brand<br><code>VISA, MASTER, JCB, AMEX</code></p>                             |
| `card.token`                      | `string` | Optional    | Card token generated by DOKU if `card.save` is `true`                                      |

***

{% hint style="info" %}
**INFO**

You can check the list of possible response code and how to handle them [here](/get-started-with-doku-api/response-code/http-status-and-case-code)
{% endhint %}

#### 4. Acknowledge payment result[​](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#4-acknowledge-payment-result) <a href="#id-4-acknowledge-payment-result" id="id-4-acknowledge-payment-result"></a>

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`. Learn how to handle the notification from DOKU:

* [Handling DOKU HTTP Notification](https://dashboard.doku.com/docs/docs/http-notification/overview)

***

### MOTO & Recurring Payment Type [​](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#sale-integration-steps) <a href="#moto-recurring-integration-step" id="moto-recurring-integration-step"></a>

Here is the overview of how to integrate MOTO & Recurring payment type:

1. Prepare credit card form input / Get token list  (Optional)
2. Hit API Charge
3. Acknowledge payment result

<details>

<summary>Doku Direct - Credit Card H2H MOTO Sequence Diagram</summary>

<figure><img src="/files/zTClsfASbTQuiiJoEG4d" alt=""><figcaption></figcaption></figure>

</details>

#### 1. Prepare credit card form input / Get token list (Optional)[​](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#1-prepare-credit-card-form-input--get-token-list-1) <a href="#id-1-prepare-credit-card-form-input--get-token-list-1" id="id-1-prepare-credit-card-form-input--get-token-list-1"></a>

You can create credit card form input on your end, so that your customer can input their credit card number, expiry date, and CVV.

If you save the card token from DOKU side, you can use Get Token List show the saved card of your customers.

***

#### 2. Hit API Charge[​](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#2-hit-api-charge) <a href="#id-2-hit-api-charge" id="id-2-hit-api-charge"></a>

After the customer input the credit card, then your backend must trigger the API Charge to DOKU:

**API Request**[**​**](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#api-request)

| Type                          | Value                                             |
| ----------------------------- | ------------------------------------------------- |
| **HTTP Method**               | POST                                              |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/credit-card/charge` |
| **API endpoint (Production)** | `https://api.doku.com/credit-card/charge`         |

Here is the sample of request header to charge the transaction:

```
Client-Id: MCH-0001-10791114622547
Request-Id: b154c582-4501-436a-8012-0346f2a46b47
Request-Timestamp: 2021-08-24T08:46:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

Request Header Explanation

| Parameter             | Description                                                                                                                                                                                                                                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client-Id**         | Client ID retrieved from DOKU Back Office                                                                                                                                                                                                                                                                                                         |
| **Request-Id**        | Unique random string (max 128 characters) generated from merchant side to protect duplicate request                                                                                                                                                                                                                                               |
| **Request-Timestamp** | Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z                                                                                     |
| **Signature**         | Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to [this section](https://developers.doku.com/get-started-with-doku-api/signature-component/non-snap/signature-component-from-request-header) to generate the signature |

Here is the sample request body for MOTO transaction:

```json
{
    "order": {
        "invoice_number": "INV-20210118-0001",
        "amount": 90000,
        "descriptor":"descriptortest",
        "line_items": [
            {
                "name": "T-Shirt Red",
                "price": 30000,
                "quantity": 2
            },
            {
                "name": "Polo Navy",
                "price": 30000,
                "quantity": 1
            }
        ]
    },
    "customer": {
        "id": "CUST-0001",
        "name": "Togawa Sakiko",
        "email": "togawa_sakiko@togawagroup.com",
        "phone": "6285694566147",
        "address": "Menara Mulia Lantai 8",
        "country": "ID"
    },
    "payment": {
        "type": "MOTO"
    },
    "card": {
        "token": "243591d7e49f45109961581718c3ef82",
        "number": "4512490000000907", // just bring ONE, either token or number
        "expiry": "1225", //optional if token used
        "save": true
    }
}
```

Here is the sample request body for 1st Recurring transaction:

```json
{
  "customer": {
    "name": "Kaoruko Waguri",
    "email": "kaoru@kikyou.com",
    "phone": "62215150555",
    "country": "ID",
    "address": "JakartaJakarta"
  },
  "additional_info": {
    "hold_settlement": true,
    "migration_process": true
  },
  "order": {
    "invoice_number": "invoice_recurring_1",
    "line_items": [
      {
        "name": "Payment Billing",
        "price": 1144917,
        "quantity": 1
      }
    ],
    "amount": 1144917
  },
  "payment": {
    "type": "RECURRING"
  },
  "card": {
        "token": "243591d7e49f45109961581718c3ef82",
  },
  "billing": {
    "amount_variability": "FIXED",
    "billing_number": "tuition-fee-kikyou-waguri",
    "number_of_payments": 1,
    "payment_frequency": "MONTHLY"
  }
}
```

Here is the sample request body for 2nd Recurring transaction:

```json
{
  "customer": {
    "name": "Kaoruko Waguri",
    "email": "kaoru@kikyouacademy.com",
    "phone": "62215150555",
    "country": "ID",
    "address": "JakartaJakarta"
  },
  "additional_info": {
    "hold_settlement": true,
    "migration_process": true
  },
  "order": {
    "invoice_number": "invoice_recurring_2",
    "line_items": [
      {
        "name": "Payment Billing",
        "price": 1144917,
        "quantity": 1
      }
    ],
    "amount": 1144917
  },
  "payment": {
    "type": "RECURRING"
  },
  "card": {
        "token": "243591d7e49f45109961581718c3ef82",
  },
  "billing": {
    "amount_variability": "FIXED",
    "billing_number": "tuition-fee-kikyou-waguri",
    "billing_transaction_id":"2023112911562800003688",
    "number_of_payments": 2,
    "payment_frequency": "MONTHLY"
  }
}
```

{% hint style="info" %}
if needed billing.billing\_transaction\_id will be returned by DOKU in the API Response in the 1st Payment

If returned, Merchant must save the value and send it in billing.billing\_transaction\_id  in the request body for the 2nd transaction and onwards
{% endhint %}

Request Body Explanation

<table><thead><tr><th width="237">Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.amount</code></td><td><code>number</code></td><td>Mandatory</td><td>In IDR Currency and without decimal<br>Allowed chars: <code>numeric</code><br>Max length: <code>12</code></td></tr><tr><td><code>order.invoice_number</code></td><td><code>string</code></td><td>Mandatory</td><td>Generated by merchant to identify the order<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code><br><code>30 for Acquirer Mandiri</code> </td></tr><tr><td><code>order.descriptor</code></td><td><code>string</code></td><td>Optional</td><td>Custom string to be printed on Customer's billing statement <br><br>Max length: <code>22</code><br><code>need to be activated, please consult DOKU team first</code></td></tr><tr><td><code>order.line_items.name</code></td><td><code>string</code></td><td>Optional</td><td>Name of the product item<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>255</code></td></tr><tr><td><code>order.line_items.price</code></td><td><code>number</code></td><td>Optional</td><td>Price of the product item. Total price and quantity must match with the <code>order.amount</code><br>Allowed chars: <code>numeric</code><br>Max Length: <code>12</code></td></tr><tr><td><code>order.line_items.quantity</code></td><td><code>number</code></td><td>Optional</td><td>Quantity of the product item<br>Allowed chars: <code>numeric</code><br>Max Length: <code>4</code></td></tr><tr><td><code>customer.id</code></td><td><code>string</code></td><td>Conditional</td><td>Unique customer identifier generated by merchant. Mandatory if merchant wants to use tokenization feature.<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>50</code></td></tr><tr><td><code>customer.name</code></td><td><code>string</code></td><td>Optional</td><td>Customer name<br>Allowed chars: <code>alphabetic</code><br>Max Length: <code>255</code></td></tr><tr><td><code>customer.email</code></td><td><code>string</code></td><td>Optional</td><td>Customer email<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>128</code></td></tr><tr><td><code>customer.phone</code></td><td><code>string</code></td><td>Optional</td><td>Customer phone number. Format: <code>{calling_code}{phone_number}</code>. Example: 6281122334455<br>Allowed chars: <code>numeric</code><br>Max Length: <code>16</code></td></tr><tr><td><code>customer.address</code></td><td><code>string</code></td><td>Optional</td><td>Customer address<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>400</code></td></tr><tr><td><code>customer.country</code></td><td><code>string</code></td><td>Optional</td><td>2 alphabetic country code ISO 3166-1<br>Allowed chars: <code>alphabetic</code><br>Min-max Length: <code>2</code></td></tr><tr><td><code>payment.type</code></td><td><code>string</code></td><td>Mandatory</td><td>Payment type<br>Possible value: <code>SALE, AUTHORIZE, INSTALLMENT,  MOTO, RECURRING</code></td></tr><tr><td><code>card.token</code></td><td><code>string</code></td><td>Conditional</td><td>Token generated by DOKU<br><code>Either card.token or card.number is mandatory (only 1 needed)</code></td></tr><tr><td><code>card.number</code></td><td><code>string</code></td><td>Conditional</td><td>Card number (PAN) <br><code>Either card.token or card.number is mandatory (only 1 needed)</code></td></tr><tr><td><code>card.expiry</code></td><td><code>string</code></td><td>Conditional</td><td>Card expiry date, not needed if you sent <code>card.token</code><br>Format: <code>MMYY</code></td></tr><tr><td><code>card.save</code></td><td><code>boolean</code></td><td>Optional</td><td>Set <code>true</code> if you  are using <code>card.number and</code>want to tokenize the card for the next payment<br>Possible value: <code>true, false</code><br>Default value: <code>false</code></td></tr><tr><td><code>billing.</code>amount_variability</td><td><code>string</code></td><td>Conditional</td><td><p>Indicates if all the payments within the agreement use the same amount or if the amount differs between the payments.</p><p>Possible value<br><code>FIXED, VARIABLE</code><br>Default value: <code>false</code><br></p></td></tr><tr><td><code>billing.billing_number</code></td><td><code>string</code></td><td>Conditional</td><td>Unique identifier of the billing transaction<br>Max Length: <code>23</code></td></tr><tr><td><code>billing.number_of_payment</code></td><td><code>number</code></td><td>Conditional</td><td>The current number of payment paid for the billing number</td></tr><tr><td><code>billing.payment_frequency</code></td><td><code>string</code></td><td>Conditional</td><td>The frequency of the payments within the series as agreed with the payer under your agreement with them.<br>Possible value<br><code>MONTHLY, DAILY,WEEKLY,YEARLY,OTHER</code>   </td></tr><tr><td><code>billing.billing_transaction_id</code></td><td><code>string</code></td><td>Conditional</td><td>Only applicable for Mandiri Acquirer<br><br>Unique identifier of the billing transaction, <strong>If DOKU returned this  on 1st payment response  need to be forwarded from second payment onward, otherwise optional</strong><br>Max Length: <code>100</code></td></tr></tbody></table>

**API Response**[**​**](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#api-response)

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

Here is the sample response header:

```
Client-Id: MCH-0001-10791114622547
Request-Id: b266c265-3d61-4708-9860-c0d5b9a98f8c
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
```

Response Header Explanation

| **Client-Id**          | Same as the request                                           |
| ---------------------- | ------------------------------------------------------------- |
| **Request-Id**         | Same as the request                                           |
| **Response-Timestamp** | Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU |
| **Signature**          | Signature generated by DOKU based on the response body        |

Here is the sample of **MOTO** response body:

```json
{
    "order": {
        "invoice_number": "INV-20210118-0001",
        "amount": 90000
    },
    "customer": {
        "id": "CUST-0001"
    },
    "payment": {
        "type": "MOTO",
        "identifier": [
           {
              "name": "Acquirer",
              "value": "Mandiri"
           },
           {
              "name": "MID",
              "value": "71003372992"
           },
           {
              "name": "TID",
              "value": "73120903"
           }
        ],
        "request_id": "20201026193843836",
        "authorize_id": "",
        "response_code": "00",
        "response_message": "Approved",
        "eci": "",
        "status": "SUCCESS",
        "approval_code": "123123"
    },
    "card": {
        "masked": "557338*******101",
        "type": "CREDIT",
        "issuer": "Bank Mandiri",
        "brand": "MASTER",
        "token": "243591d7e49f45109961581718c3ef82"
    }
}
```

Here is the sample of **Recurring** response body:

```json
{
    "additional_info": "",
    "order": {
        "invoice_number": "invoice_recurring_1",
        "amount": 9500
    },
    "payment": {
        "type": "RECURRING",
        "identifier": [
            {
                "name": "MID",
                "value": "71000537322"
            },
            {
                "name": "Acquirer",
                "value": "BANK_MANDIRI"
            },
            {
                "name": "TID",
                "value": "73013571"
            }
        ],
        "request_id": "82464",
        "response_code": "00",
        "response_message": "PAYMENT APPROVED",
        "status": "SUCCESS",
        "eci": "",
        "approval_code": "908680"
    },
    "card": {
        "masked": "413719******9000",
        "type": "Credit",
        "issuer": "PT. BANK MANDIRI (PERSERO), Tbk",
        "brand": "VISA"
    },
    "verification": {
        "status": "REVIEW",
        "reason": "Decision No Rules Triggered"
    },
    "billing": {
        "billing_number": "tuition-fee-kikyou-waguri",
        "number_of_payments": 1,
        "billing_transaction_id": "2023112911562800003688",
        "amount_variability": "FIXED",
        "payment_frequency": "MONTHLY"
    }
}
```

Response Body Explanation

<table><thead><tr><th width="218">Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.invoice_number</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as the request</td></tr><tr><td><code>order.amount</code></td><td><code>number</code></td><td>Mandatory</td><td>Same as the request</td></tr><tr><td><code>customer.id</code></td><td><code>string</code></td><td>Optional</td><td>Same as the request</td></tr><tr><td><code>payment.type</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as the request</td></tr><tr><td><code>payment.identifier.name</code></td><td><code>string</code></td><td>Mandatory</td><td>Additional payment info name</td></tr><tr><td><code>payment.identifier.value</code></td><td><code>string</code></td><td>Mandatory</td><td>Additional payment info value</td></tr><tr><td><code>payment.request_id</code></td><td><code>string</code></td><td>Mandatory</td><td>Request ID sent on merchant's request header</td></tr><tr><td><code>payment.authorize_id</code></td><td><code>string</code></td><td>Optional</td><td>Authorize ID for authorize transaction. Mandatory if <code>payment.type</code> is <code>AUTHORIZE</code></td></tr><tr><td><code>payment.response_code</code></td><td><code>string</code></td><td>Mandatory</td><td>Reponse code generated by DOKU / Acquirer</td></tr><tr><td><code>payment.response_message</code></td><td><code>string</code></td><td>Mandatory</td><td>Response message generated by DOKU / Acquirer</td></tr><tr><td><code>payment.status</code></td><td><code>string</code></td><td>Mandatory</td><td>Payment status<br>Possible value: <code>SUCCESS, FAILED, PENDING</code></td></tr><tr><td><code>payment.eci</code></td><td><code>string</code></td><td>Mandatory</td><td>ECI for this transaction</td></tr><tr><td><code>payment.approval_code</code></td><td><code>string</code></td><td>Optional</td><td>Approval code for success transaction generated by acquirer</td></tr><tr><td><code>card.masked</code></td><td><code>string</code></td><td>Optional</td><td>Card masked number</td></tr><tr><td><code>card.type</code></td><td><code>string</code></td><td>Mandatory</td><td>Card type<br>Possible value: <code>CREDIT, DEBIT</code></td></tr><tr><td><code>card.issuer</code></td><td><code>string</code></td><td>Mandatory</td><td>Card issuer</td></tr><tr><td><code>card.brand</code></td><td><code>string</code></td><td>Mandatory</td><td>Principal brand<br><code>VISA, MASTER, JCB, AMEX</code></td></tr><tr><td><code>card.token</code></td><td><code>string</code></td><td>Optional</td><td>Card token generated by DOKU if <code>card.save</code> is <code>true</code></td></tr><tr><td><code>billing.billing_number</code></td><td><code>string</code></td><td>Conditional</td><td>Unique identifier of the billing transaction<br>Max Length: <code>23</code></td></tr><tr><td><code>billing.number_of_payment</code></td><td><code>number</code></td><td>Conditional</td><td>The current number of payment paid for the billing number</td></tr><tr><td><code>billing.billing_transaction_id</code></td><td><code>string</code></td><td>Conditional</td><td>Only applicable for Mandiri Acquirer<br><br>Unique identifier of the billing transaction, <strong>If DOKU returned this  on 1st payment response  need to be forwarded from second payment onward, otherwise optional</strong><br>Max Length: <code>100</code></td></tr><tr><td><code>billing.</code>amount_variability</td><td><code>string</code></td><td>Conditional</td><td>Same as request</td></tr><tr><td><code>billing.</code>payment_frequency</td><td><code>string</code></td><td>Conditional</td><td>Same as request</td></tr></tbody></table>

#### 3. Acknowledge payment result[​](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#3-acknowledge-payment-result) <a href="#id-3-acknowledge-payment-result" id="id-3-acknowledge-payment-result"></a>

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`. Learn how to handle the notification from DOKU:

* [Handling DOKU HTTP Notification](https://dashboard.doku.com/docs/docs/http-notification/overview)

***

### Authorize Capture Payment Type[​](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#sale-integration-steps)[​](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#authorize-capture-integration-steps) <a href="#authorize-capture-integration-steps" id="authorize-capture-integration-steps"></a>

Here is the overview of how to integrate AUTHORIZE CAPTURE payment:

1. Prepare credit card form input / Get token list
2. Get 3DS authentication ID and 3DS URL
3. Hit API Charge
4. Hit API Capture
5. Acknowledge payment result

<details>

<summary>DOKU Direct - Credit Card H2H AUTH CAP Sequence Diagram</summary>

<figure><img src="/files/lgDpZ2Wdev3NzHSh5JAN" alt=""><figcaption></figcaption></figure>

</details>

***

#### 1. Prepare credit card form input / Get token list[​](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#1-prepare-credit-card-form-input--get-token-list-2) <a href="#id-1-prepare-credit-card-form-input--get-token-list-2" id="id-1-prepare-credit-card-form-input--get-token-list-2"></a>

You can create credit card form input on your end, so that your customer can input their credit card number, expiry date, and CVV.

If you save the card token from DOKU side, you can use [Tokenization](https://dashboard.doku.com/docs/docs/jokul-direct/tokenization/jokul-token-overview) to show the saved card of your customers.

***

#### 2. Get 3DS authentication ID and 3DS URL[​](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#2-get-3ds-authentication-id-and-3ds-url-1) <a href="#id-2-get-3ds-authentication-id-and-3ds-url-1" id="id-2-get-3ds-authentication-id-and-3ds-url-1"></a>

To get 3DS authentication, you will need to hit this API through your backend:

**API Request**[**​**](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#api-request)

| Type                          | Value                                                           |
| ----------------------------- | --------------------------------------------------------------- |
| **HTTP Method**               | POST                                                            |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/credit-card/check-three-d-secure` |
| **API endpoint (Production)** | `https://api.doku.com/credit-card/check-three-d-secure`         |

Here is the sample of request header to get 3DS authentication:

```
Client-Id: MCH-0001-10791114622547
Request-Id: 6d0bffbd-9246-455e-a1f1-44c1f76ad589
Request-Timestamp: 2021-08-24T08:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

Request Header Explanation

| Parameter             | Description                                                                                                                                                                                                                                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client-Id**         | Client ID retrieved from DOKU Back Office                                                                                                                                                                                                                                                                                                         |
| **Request-Id**        | Unique random string (max 128 characters) generated from merchant side to protect duplicate request                                                                                                                                                                                                                                               |
| **Request-Timestamp** | Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z                                                                                     |
| **Signature**         | Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to [this section](https://developers.doku.com/get-started-with-doku-api/signature-component/non-snap/signature-component-from-request-header) to generate the signature |

Here is the sample request body to get 3DS authentication:

```json
{
    "order": {
        "amount": 90000
    },
    "card": {
        "token": "243591d7e49f45109961581718c3ef82",
        "number": "4512490000000907", //just bring ONE, either token or number
        "expiry": "1230" //optional if token brought
    },
    "three_dsecure": {
        "callback_url_success": "https://www.merchant.com/success",
        "callback_url_failed": "https://www.merchant.com/failed"
    }
}
```

Request Body Explanation

| Parameter                            | Type     | Mandatory | Description                                                                                                      |
| ------------------------------------ | -------- | --------- | ---------------------------------------------------------------------------------------------------------------- |
| `order.amount`                       | `number` | Mandatory | <p>In IDR Currency and without decimal<br>Allowed chars: <code>numeric</code><br>Max length: <code>12</code></p> |
| `card.token`                         | `string` | Optional  | Card token generated by DOKU, can be used if you already activate tokenization                                   |
| `card.number`                        | `string` | Mandatory | Card number, can be optional if you sent `card.token`                                                            |
| `card.expiry`                        | `string` | Mandatory | <p>Card expiry date, can be optional if you sent <code>card.token</code><br>Format: <code>MMYY</code></p>        |
| `three_dsecure.callback_url_success` | `string` | Mandatory | After 3DS process success, customer will be redirected to this page                                              |
| `three_dsecure.callback_url_failed`  | `string` | Mandatory | If 3DS process failed, customer will be redirected to this page                                                  |

**API Response**[**​**](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#api-response)

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

Here is the sample response header:

```
Client-Id: MCH-0001-10791114622547
Request-Id: b266c265-3d61-4708-9860-c0d5b9a98f8c
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
```

Response Header Explanation

| **Client-Id**          | Same as the request                                           |
| ---------------------- | ------------------------------------------------------------- |
| **Request-Id**         | Same as the request                                           |
| **Response-Timestamp** | Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU |
| **Signature**          | Signature generated by DOKU based on the response body        |

Here is the sample of **Successful** response body:

```json
{
    "order": {
        "amount": 90000
    },
    "three_dsecure": {
        "authentication_id": "eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e",
        "authentication_url": "https://doku.3ds.com?authenticationId=eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e",
        "three_ds_version": "2.0"
    }
}
```

Here is the sample of **failed** response body:

```json
{
    "error": {
        "code": "INVALID_PARAMETER",
        "message": "Card Number Length must be 15, 16 or 19 Digits",
        "type": "Invalid Parameter"
    }
}
```

Response Body

| Parameter                          | Type     | Mandatory | Description                                                                      |
| ---------------------------------- | -------- | --------- | -------------------------------------------------------------------------------- |
| `order.amount`                     | `number` | Mandatory | Same as the request                                                              |
| `three_dsecure.authentication_id`  | `string` | Mandatory | 3DS process ID to use on API Charge                                              |
| `three_dsecure.authentication_url` | `string` | Optional  | 3DS page that need to be opened by customer                                      |
| `three_dsecure.three_ds_version`   | `string` | Optional  | 3DS Version used to authenticate, value would be something like "2.x" or "2.x.x" |

#### 3. Hit API Charge[​](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#3-hit-api-charge-1) <a href="#id-3-hit-api-charge-1" id="id-3-hit-api-charge-1"></a>

After the customer is redirected to the 3DS success page, then your backend must trigger the API Charge to DOKU:

**API Request**[**​**](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#api-request)

| Type                          | Value                                             |
| ----------------------------- | ------------------------------------------------- |
| **HTTP Method**               | POST                                              |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/credit-card/charge` |
| **API endpoint (Production)** | `https://api.doku.com/credit-card/charge`         |

Here is the sample of request header to charge the transaction:

```
Client-Id: MCH-0001-10791114622547
Request-Id: b154c582-4501-436a-8012-0346f2a46b47
Request-Timestamp: 2021-08-24T08:46:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

Request Header Explanation

| Parameter             | Description                                                                                                                                                                                                                                                                                         |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client-Id**         | Client ID retrieved from DOKU Back Office                                                                                                                                                                                                                                                           |
| **Request-Id**        | Unique random string (max 128 characters) generated from merchant side to protect duplicate request                                                                                                                                                                                                 |
| **Request-Timestamp** | Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z                                       |
| **Signature**         | Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to [this section](https://dashboard.doku.com/docs/docs/technical-references/generate-signature) to generate the signature |

Here is the sample request body to charge the transaction:

```json
{
    "order": {
        "invoice_number": "INV-20210118-0001",
        "amount": 90000,
        "line_items": [
            {
                "name": "T-Shirt Red",
                "price": 30000,
                "quantity": 2
            },
            {
                "name": "Polo Navy",
                "price": 30000,
                "quantity": 1
            }
        ]
    },
    "customer": {
        "id": "CUST-0001",
        "name": "Arthuria Pendragon",
        "email": "arthuria_pendragon@example.com",
        "phone": "6285694566147",
        "address": "Menara Mulia Lantai 8",
        "country": "ID"
    },
    "three_dsecure": {
        "authentication_id": "eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e"
    },
    "payment": {
        "type": "AUTHORIZE",
        "plan_id": "1232131"
    },
    "card": {
        "token": "243591d7e49f45109961581718c3ef82",
        "number": "5573381011111101", //just bring ONE, either token or card
        "expiry": "1225", //optional if token brought
        "cvv": "123",
        "save": true
    }
}
```

Request Body Explanation

| Parameter                                | Type      | Mandatory   | Description                                                                                                                                                                                                               |
| ---------------------------------------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.amount`                           | `number`  | Mandatory   | <p>In IDR Currency and without decimal<br>Allowed chars: <code>numeric</code><br>Max length: <code>12</code></p>                                                                                                          |
| `order.invoice_number`                   | `string`  | Mandatory   | <p>Generated by merchant to identify the order<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code><br><code>30 for Acquirer Mandiri</code></p>                               |
| `order.line_items.name`                  | `string`  | Optional    | <p>Name of the product item<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>255</code></p>                                                                                         |
| `order.line_items.price`                 | `number`  | Optional    | <p>Price of the product item. Total price and quantity must match with the <code>order.amount</code><br>Allowed chars: <code>numeric</code><br>Max Length: <code>12</code></p>                                            |
| `order.line_items.quantity`              | `number`  | Optional    | <p>Quantity of the product item<br>Allowed chars: <code>numeric</code><br>Max Length: <code>4</code></p>                                                                                                                  |
| `customer.id`                            | `string`  | Conditional | <p>Unique customer identifier generated by merchant. Mandatory if merchant wants to use tokenization feature.<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>50</code></p>        |
| `customer.name`                          | `string`  | Optional    | <p>Customer name<br>Allowed chars: <code>alphabetic</code><br>Max Length: <code>255</code></p>                                                                                                                            |
| `customer.email`                         | `string`  | Optional    | <p>Customer email<br>Allowed chars: <code>alphabetic, numeric, special chars</code></p><p></p><p><strong><code>DO NOT SEND STATIC/DUMMY VALUE</code></strong></p><p><br>Max Length: <code>128</code></p>                  |
| `customer.phone`                         | `string`  | Optional    | <p>Customer phone number. Format: <code>{calling\_code}{phone\_number}</code>. Example: 6281122334455<br>Allowed chars: <code>numeric</code><br>Max Length: <code>16</code></p>                                           |
| `customer.address`                       | `string`  | Optional    | <p>Customer address<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>400</code></p>                                                                                                 |
| `customer.country`                       | `string`  | Optional    | <p>2 alphabetic country code ISO 3166-1<br>Allowed chars: <code>alphabetic</code><br>Min-max Length: <code>2</code></p>                                                                                                   |
| `three_dsecure.authentication_id`        | `string`  | Conditional | Mandatory if 3DS transaction, Obtained from Check 3DS API                                                                                                                                                                 |
| `authentication.threeDS.eci`             | `string`  | Optional    | <p>a code provided by a indicating the outcome of the authentication attempt, bring for MPI 3DS</p><p></p><p>Allowed chars: <code>numeric</code></p><p>Min-max Length: <code>2</code></p>                                 |
| `authentication.threeDS.xid`             | `string`  | Optional    | <p>a unique identifier associated with a specific transaction in the 3D Secure (3DS) authentication process, bring for MPI 3DS</p><p></p><p>Allowed chars: <code>numeric</code></p><p>Min-max Length: <code>20</code></p> |
| `authentication.threeDS.cavv`            | `string`  | Optional    | <p>a cryptographic value that links the issuer's authentication, bring for MPI 3DS</p><p></p><p>Allowed chars: <code>alphanumeric</code></p><p>Min-max Length: <code>1024</code></p>                                      |
| `authentication.threeDS.status`          | `string`  | Optional    | <p>outcome of the 3D Secure (3DS) authentication process, Y/N</p><p></p><p>Allowed chars: <code>alphabhetic</code></p><p>Min-max Length: <code>1</code></p>                                                               |
| `authentication.threeDS.dsTransactionId` | `string`  | Optional    | <p>outcome of the 3D Secure (3DS) authentication process, Y/N</p><p></p><p>Allowed chars: <code>alpabethic, numberic, symbols</code></p><p>Min-max Length: <code>128</code></p>                                           |
| `payment.type`                           | `string`  | Mandatory   | <p>Payment type<br>Possible value: <code>SALE, MOTO, AUTHORIZE</code></p>                                                                                                                                                 |
| `payment.plan_id`                        | `string`  | Optional    | Promotion ID from the bank for merchant                                                                                                                                                                                   |
| `card.token`                             | `string`  | Optional    | Card token generated by DOKU, for 3ds transaction please bring `three_dsecure.authentication_id` only                                                                                                                     |
| `card.number`                            | `string`  | Mandatory   | Card number, can be optional if you sent `card.token`                                                                                                                                                                     |
| `card.expiry`                            | `string`  | Mandatory   | <p>Card expiry date, can be optional if you sent <code>card.token</code><br>Format: <code>MMYY</code></p>                                                                                                                 |
| `card.cvv`                               | `string`  | Mandatory   | Card CVV, Optional if `payment.type` is `MOTO`                                                                                                                                                                            |
| `card.save`                              | `boolean` | Optional    | <p>Set <code>true</code> if you want to force customer to save the card token for the next payment<br>Possible value: <code>true, false</code><br>Default value: <code>false</code></p>                                   |

**API Response**[**​**](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#api-response)

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

Here is the sample response header:

```
Client-Id: MCH-0001-10791114622547
Request-Id: b266c265-3d61-4708-9860-c0d5b9a98f8c
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
```

Response Header Explanation

| **Client-Id**          | Same as the request                                           |
| ---------------------- | ------------------------------------------------------------- |
| **Request-Id**         | Same as the request                                           |
| **Response-Timestamp** | Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU |
| **Signature**          | Signature generated by DOKU based on the response body        |

Here is the sample of response body:

```json
{
    "order": {
        "invoice_number": "INV-20210118-0001",
        "amount": 90000
    },
    "customer": {
        "id": "CUST-0001"
    },
    "payment": {
        "type": "AUTHORIZE",
        "identifier": [
           {
              "name": "Acquirer",
              "value": "Mandiri"
           },
           {
              "name": "MID",
              "value": "71003372992"
           },
           {
              "name": "TID",
              "value": "73120903"
           }
        ],
        "request_id": "20201026193843836",
        "authorize_id": "12312391719112",
        "response_code": "00",
        "response_message": "Approved",
        "eci": "02",
        "status": "SUCCESS",
        "approval_code": "123123"
    },
    "three_dsecure": {
        "authentication_id": "eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e"
    },
    "card": {
        "masked": "557338*******101",
        "type": "CREDIT",
        "issuer": "Bank Mandiri",
        "brand": "MASTER",
        "token": "243591d7e49f45109961581718c3ef82"
    }
}
```

Response Body Explanation

| Parameter                         | Type     | Mandatory | Description                                                                        |
| --------------------------------- | -------- | --------- | ---------------------------------------------------------------------------------- |
| `order.invoice_number`            | `string` | Mandatory | Same as the request                                                                |
| `order.amount`                    | `number` | Mandatory | Same as the request                                                                |
| `customer.id`                     | `string` | Optional  | Same as the request                                                                |
| `payment.type`                    | `string` | Mandatory | Same as the request                                                                |
| `payment.identifier.name`         | `string` | Mandatory | Additional payment info name                                                       |
| `payment.identifier.value`        | `string` | Mandatory | Additional payment info value                                                      |
| `payment.request_id`              | `string` | Mandatory | Request ID sent on merchant's request header                                       |
| `payment.authorize_id`            | `string` | Mandatory | Authorize ID for authorize transaction. Mandatory if `payment.type` is `AUTHORIZE` |
| `payment.response_code`           | `string` | Mandatory | Reponse code generated by DOKU / Acquirer                                          |
| `payment.response_message`        | `string` | Mandatory | Response message generated by DOKU / Acquirer                                      |
| `payment.status`                  | `string` | Mandatory | <p>Payment status<br>Possible value: <code>SUCCESS, FAILED, PENDING</code></p>     |
| `payment.eci`                     | `string` | Mandatory | ECI for this transaction                                                           |
| `payment.approval_code`           | `string` | Optional  | Approval code for success transaction generated by acquirer                        |
| `three_dsecure.authentication_id` | `string` | Mandatory | Same as the request                                                                |
| `card.masked`                     | `string` | Optional  | Card masked number                                                                 |
| `card.type`                       | `string` | Mandatory | <p>Card type<br>Possible value: <code>CREDIT, DEBIT</code></p>                     |
| `card.issuer`                     | `string` | Mandatory | Card issuer                                                                        |
| `card.brand`                      | `string` | Mandatory | <p>Principal brand<br><code>VISA, MASTER, JCB, AMEX</code></p>                     |
| `card.token`                      | `string` | Optional  | Card token generated by DOKU if `card.save` is `true`                              |

DOKU will also send the HTTP Notification with the `payment.authorize_id` to your defined Notification URL.

***

#### 4. Hit API Capture[​](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#4-hit-api-capture) <a href="#id-4-hit-api-capture" id="id-4-hit-api-capture"></a>

After you get the `payment.authorize_id`, then your backend must trigger the API Charge to DOKU:

**API Request**[**​**](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#api-request)

| Type                          | Value                                              |
| ----------------------------- | -------------------------------------------------- |
| **HTTP Method**               | POST                                               |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/credit-card/capture` |
| **API endpoint (Production)** | `https://api.doku.com/credit-card/capture`         |

Here is the sample of request header to capture the transaction:

```
Client-Id: MCH-0001-10791114622547
Request-Id: 071a6a32-6785-4011-833d-d2c2049cf744
Request-Timestamp: 2021-08-24T08:46:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

Request Header Explanation

| Parameter             | Description                                                                                                                                                                                                                                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client-Id**         | Client ID retrieved from DOKU Back Office                                                                                                                                                                                                                                                                                                         |
| **Request-Id**        | Unique random string (max 128 characters) generated from merchant side to protect duplicate request                                                                                                                                                                                                                                               |
| **Request-Timestamp** | Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z                                                                                     |
| **Signature**         | Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to [this section](https://developers.doku.com/get-started-with-doku-api/signature-component/non-snap/signature-component-from-request-header) to generate the signature |

Here is the sample request body to capture the transaction:

```json
{
    "payment": {
        "authorize_id": "12312391719112",
        "capture_amount": 90000
    }
}
```

Request Body Explanation

| Parameter                | Type     | Mandatory | Description                                                                                           |
| ------------------------ | -------- | --------- | ----------------------------------------------------------------------------------------------------- |
| `payment.authorize_id`   | `string` | Mandatory | Authorize ID from the Charge API Response / HTTP Notification                                         |
| `payment.capture_amount` | `string` | Optional  | The value of transactions which will be paid by the customer. If undefined, capture full transaction. |

**API Response**[**​**](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#api-response)

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

Here is the sample response header:

```
Client-Id: MCH-0001-10791114622547
Request-Id: b266c265-3d61-4708-9860-c0d5b9a98f8c
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
```

Response Header Explanation

| **Client-Id**          | Same as the request                                           |
| ---------------------- | ------------------------------------------------------------- |
| **Request-Id**         | Same as the request                                           |
| **Response-Timestamp** | Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU |
| **Signature**          | Signature generated by DOKU based on the response body        |

Here is the sample of response body:

```json
{
    "order": {
        "invoice_number": "INV-20210118-0001",
        "amount": 90000
    },
    "customer": {
        "id": "CUST-0001"
    },
    "payment": {
        "type": "CAPTURE",
        "identifier": [
           {
              "name": "Acquirer",
              "value": "Mandiri"
           },
           {
              "name": "MID",
              "value": "71003372992"
           },
           {
              "name": "TID",
              "value": "73120903"
           }
        ],
        "request_id": "20201026193843836",
        "authorize_id": "12312391719112",
        "response_code": "01",
        "response_message": "Approved",
        "eci": "",
        "status": "SUCCESS",
        "approval_code": "123123"
    },
    "three_dsecure": {
        "authentication_id": "eb7e72313b491cd73ea10c6354bc96900f08b3e50e66cf3df2fe29580d6ff84e"
    },
    "card": {
        "masked": "557338*******101",
        "type": "CREDIT",
        "issuer": "Bank Mandiri",
        "brand": "MASTER",
        "token": "243591d7e49f45109961581718c3ef82"
    }
}
```

Response Body Explanation

| Parameter                         | Type     | Mandatory | Description                                                                        |
| --------------------------------- | -------- | --------- | ---------------------------------------------------------------------------------- |
| `order.invoice_number`            | `string` | Mandatory | Same as the request                                                                |
| `order.amount`                    | `number` | Mandatory | Same as the request                                                                |
| `customer.id`                     | `string` | Optional  | Same as the request                                                                |
| `payment.type`                    | `string` | Mandatory | Same as the request                                                                |
| `payment.identifier.name`         | `string` | Mandatory | Additional payment info name                                                       |
| `payment.identifier.value`        | `string` | Mandatory | Additional payment info value                                                      |
| `payment.request_id`              | `string` | Mandatory | Request ID sent on merchant's request header                                       |
| `payment.authorize_id`            | `string` | Mandatory | Authorize ID for authorize transaction. Mandatory if `payment.type` is `AUTHORIZE` |
| `payment.response_code`           | `string` | Mandatory | Reponse code generated by DOKU / Acquirer                                          |
| `payment.response_message`        | `string` | Mandatory | Response message generated by DOKU / Acquirer                                      |
| `payment.status`                  | `string` | Mandatory | <p>Payment status<br>Possible value: <code>SUCCESS, FAILED, PENDING</code></p>     |
| `payment.eci`                     | `string` | Mandatory | ECI for this transaction                                                           |
| `payment.approval_code`           | `string` | Optional  | Approval code for success transaction generated by acquirer                        |
| `three_dsecure.authentication_id` | `string` | Mandatory | Same as request, obtained from three                                               |
| `card.masked`                     | `string` | Optional  | Card masked number                                                                 |
| `card.type`                       | `string` | Mandatory | <p>Card type<br>Possible value: <code>CREDIT, DEBIT</code></p>                     |
| `card.issuer`                     | `string` | Mandatory | Card issuer                                                                        |
| `card.brand`                      | `string` | Mandatory | <p>Principal brand<br><code>VISA, MASTER, JCB, AMEX</code></p>                     |
| `card.token`                      | `string` | Optional  | Card token generated by DOKU if `card.save` is `true`                              |

#### 5. Acknowledge payment result[​](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#5-acknowledge-payment-result) <a href="#id-5-acknowledge-payment-result" id="id-5-acknowledge-payment-result"></a>

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`. Learn how to handle the notification from DOKU:

* [Handling DOKU HTTP Notification](https://dashboard.doku.com/docs/docs/http-notification/overview)

### List of Error Code[​](https://dashboard.doku.com/docs/docs/jokul-direct/credit-card/credit-card-host-to-host-guide#list-of-error-code) <a href="#list-of-error-code" id="list-of-error-code"></a>

If something happens, you can see the following error code to find out what error is happening :

| API                  | Error message                                                                    | Error Code                             | HTTP Status Code | Explanation                                                  |
| -------------------- | -------------------------------------------------------------------------------- | -------------------------------------- | ---------------- | ------------------------------------------------------------ |
| Check-three-d-secure | Invalid Client-Id                                                                | `invalid_client_id`                    | 400              | Invalid Client ID                                            |
| Check-three-d-secure | Header Client-Id is required                                                     | `invalid_header_request`               | 400              | empty client id                                              |
| Check-three-d-secure | Invalid Header Signature                                                         | `invalid_signature`                    | 400              | Payment charge with invalid signature                        |
| Check-three-d-secure | Invalid CC Number LENGTH                                                         | `INVALID_PARAMETER`                    | 400              | Invalid CC Number LENGTH                                     |
| Check-three-d-secure | Luhn Validation                                                                  | `INVALID_PARAMETER`                    | 400              | Card number not valid                                        |
| Check-three-d-secure | Expiry Date Validation                                                           | `INVALID_PARAMETER`                    | 400              | Invalid expiry date 2525                                     |
| Check-three-d-secure | This field is required.,This merchant does not have three d secure configuration | `INVALID_PARAMETER`                    | 400              | invalid configuration / haven't 3ds mid                      |
| Check-three-d-secure | This card is not support three d secure                                          | `THREE_D_SECURE_AUTHENTICATION_FAILED` | 400              | card not support 3ds / cannot connect to mpi                 |
| Charge               | Invalid Client-Id                                                                | `invalid_client_id`                    | 400              | Invalid Client ID                                            |
| Charge               | empty client id                                                                  | `invalid_header_request`               | 400              | empty client id                                              |
| Charge               | size must be between 1 and 128                                                   | `invalid_header_request`               | 400              | Payment charge with client id length more than max           |
| Charge               | Invalid format Header Request-Timestamp                                          | `invalid_header_request`               | 400              | Payment charge with invalid format request timestamp         |
| Charge               | Header Request-Timestamp is not in +- 10 second of now                           | `invalid_header_request`               | 400              | Payment charge with request timestamp < now                  |
| Charge               | Header Request-Timestamp is not in +- 10 second of now                           | `invalid_header_request`               | 400              | Payment charge with request timestamp > now                  |
| Charge               | Invalid Header Signature                                                         | `invalid_signature`                    | 400              | Payment charge with invalid signature                        |
| Charge               | Invalid Header Signature                                                         | `invalid_signature`                    | 400              | Payment charge using signature has been used                 |
| Charge               | Invalid Format Email                                                             | `INVALID_PARAMETER`                    | 400              | Payment charge with invalid format email                     |
| Charge               | Invalid amount                                                                   | `INVALID_PARAMETER`                    | 400              | Payment charge with amount contain comma                     |
| Charge               | Invalid amount                                                                   | `INVALID_PARAMETER`                    | 400              | Payment charge with amount contain dot                       |
| Charge               | Expiry Date Validation                                                           | `INVALID_PARAMETER`                    | 400              | Payment charge with format expiry is YYMM                    |
| Charge               | Expiry Date Validation                                                           | `INVALID_PARAMETER`                    | 400              | Payment charge with expiry date is expired                   |
| Charge               | Invalid AuthenticationId.                                                        | `INVALID_PARAMETER`                    | 400              | invalid authentication\_id                                   |
| Charge               | Country Is Not Exists                                                            | `INVALID_PARAMETER`                    | 400              | Payment charge with invalid country                          |
| Charge               | Invalid CC Number LENGTH                                                         | `INVALID_PARAMETER`                    | 400              | Invalid CC Number LENGTH                                     |
| Charge               | Luhn Validation                                                                  | `INVALID_PARAMETER`                    | 400              | Card number not valid                                        |
| Charge               | REQUEST ID IS NOT VALID                                                          | `INVALID_PARAMETER`                    | 400              | Payment charge with request id has been used for transaction |
| Charge               | Unauthorized Transaction                                                         | `MID_TID_NOT_EXIST`                    | 400              | Payment charge sale using card rejected                      |
| Charge               | Invalid Authentication Id                                                        | `INVALID_PARAMETER`                    | 400              | Invalid Authentication Id                                    |
| Charge               | Invalid Authentication Id                                                        | `INVALID_PARAMETER`                    | 400              | Different amount check 3ds & charge                          |
| Charge               | Invalid Authentication Id                                                        | `INVALID_PARAMETER`                    | 400              | Three D Secure Process Not Yet Done (Not yet send OTP)       |
| Charge               | Line item 1 quantity must be not empty                                           | `INVALID_PARAMETER`                    | 400              | Invalid line item (quantity is null)                         |
| Charge               | Your transaction is detected to be concurrent, please create another transaction | `DOUBLE_REQUEST_DETECTED`              | 400              | Concurent Request                                            |
| Charge               | Conflict                                                                         | `INVALID_PARAMETER`                    | 409              | duplicate request with same request body                     |
| Charge               | Precondition failed                                                              | `INVALID_PARAMETER`                    | 412              | duplicate request with different request body                |
| Capture              | Invalid Client-Id                                                                | `invalid_client_id`                    | 400              | Invalid Client ID                                            |
| Capture              | Header Client-Id is required                                                     | `invalid_header_request`               | 400              | empty client id                                              |
| Capture              | Invalid Header Signature                                                         | `invalid_signature`                    | 400              | Payment charge with invalid signature                        |
| Capture              | Authorize Id Must Not Be Blank                                                   | `INVALID_PARAMETER`                    | 400              | authorize\_id is null                                        |
| Capture              | Failed Get Transaction                                                           | `TRANSACTION_NOT_FOUND`                | 400              | Invalid authorize\_id                                        |
| Capture              | Conflict                                                                         | `INVALID_PARAMETER`                    | 409              | duplicate request with same request body                     |
| Capture              | Precondition failed                                                              | `INVALID_PARAMETER`                    | 412              | duplicate request with different request body                |


# DOKU JS Integration Guide

### What is DOKU JS ?&#x20;

The **DOKU JS Integration** feature enables non-PCI DSS certified merchants to securely collect customer card details for online transactions by embedding a Javascript into their HTML files while still having the freedom to manages how their checkoutpage will looks like. **PCI DSS compliance is needed before activating this feature please contact DOKU team first.**

### Integration steps

Understanding the complete payment flow from merchant perspective:

{% hint style="info" %}
**Prerequisites:**

* **Create session\_id from your backend:** Call POST [/request-payment-page to get payment URL](/accept-payments/direct-api/non-snap/card/payment-page-integration-guide) and get session ID
* A valid DOKU payment session ID from your backend
* Basic HTML/JavaScript knowledge
* Web server or local development environment
  {% endhint %}

<figure><img src="/files/KIJOsQ9xhhPqYTXemfv5" alt=""><figcaption><p>DOKU JS Transaction Flow</p></figcaption></figure>

#### Example HTML Files

```
<!DOCTYPE html>
<html>
<head>
    <title>DOKU Payment Integration</title>
    <!-- Step 1: Include the SDK -->
    <script src="https://sandbox.doku.com/card-session/card-session-1.0.0.js"></script>
</head>
<body>
    <form id="payment-form">
        <input type="text" id="sessionId" placeholder="Payment Session ID" required />
        <input type="text" id="cardNumber" placeholder="Card Number" required />
        <input type="text" id="expiryMonth" placeholder="MM" required />
        <input type="text" id="expiryYear" placeholder="YY" required />
        <input type="text" id="cvv" placeholder="CVV" required />
        <input type="text" id="firstName" placeholder="First Name" required />
        <input type="text" id="lastName" placeholder="Last Name" required />
        <button type="submit">Pay Now</button>
    </form>

    <script>
        // Step 2: Initialize SDK
        PG.init();

        // Step 3: Handle form submission
        document.getElementById('payment-form').addEventListener('submit', function(e) {
            e.preventDefault();

            const cardData = {
                session_id: document.getElementById('sessionId').value.trim(),
                card_number: document.getElementById('cardNumber').value.replace(/\s/g, ''),
                expiry_month: document.getElementById('expiryMonth').value.trim(),
                expiry_year: document.getElementById('expiryYear').value.trim(),
                cvv: document.getElementById('cvv').value.trim(),
                card_holder_first_name: document.getElementById('firstName').value.trim(),
                card_holder_last_name: document.getElementById('lastName').value.trim()
            };

            // Step 4: Submit payment
            PG.payment.collectCardData(cardData, function(error, response) {
                if (error) {
                    alert('Payment failed: ' + error.message);
                } else {
                    alert('Payment successful!');
                    console.log('Payment response:', response);
                }
            });
        });
    </script>
</body>
</html>
```

#### Step 1: Include the SDK

Add the SDK script to your HTML page according to your environment:

```
<!-- For sandbox/testing environment -->
<script src="https://sandbox.doku.com/card-session/card-session-1.0.4.js"></script>

<!-- For production environment -->
<script src="https://app.doku.com/card-session/card-session-1.0.4.js"></script>
```

{% hint style="warning" %}
**⚠️ Important:**

1. Each SDK URL is environment-specific. Always use sandbox URL for testing and production URL for live payments. Never use sandbox SDK in production!
2. HTML ID must be the same as stated in this documentation
3. **Note:** Place this in your \<head> section or before the closing \</body> tag.
   {% endhint %}

#### Step 2: Create Your Payment Form

Create a form with the required input fields:

```
<form id="credit-card-form">
    <!-- Session ID (obtained from your backend) -->
    <div class="form-group">
        <label for="paymentSessionId">Session ID</label>
        <input type="text" id="paymentSessionId" name="payment-session-id" required />
    </div>

    <!-- Card Information -->
    <div class="form-group">
        <label for="cardNumber">Card Number</label>
        <input type="text" id="cardNumber" name="card-number" required />
    </div>

    <div class="form-group">
        <label for="expiryMonth">Expiry Month (MM)</label>
        <input type="text" id="expiryMonth" name="expiry-month" placeholder="12" required />
    </div>

    <div class="form-group">
        <label for="expiryYear">Expiry Year (YY)</label>
        <input type="text" id="expiryYear" name="expiry-year" placeholder="27" required />
    </div>

    <div class="form-group">
        <label for="cvv">CVV</label>
        <input type="text" id="cvv" name="cvv" required />
    </div>

    <!-- Cardholder Information -->
    <div class="form-group">
        <label for="firstName">First Name</label>
        <input type="text" id="firstName" name="first-name" required />
    </div>

    <div class="form-group">
        <label for="lastName">Last Name</label>
        <input type="text" id="lastName" name="last-name" required />
    </div>
</form>
```

{% hint style="info" %}
ID must be the same as stated in this documentation
{% endhint %}

#### Step 3: Initialize the SDK

Add this script to initialize the SDK:

```
// Initialize the Payment Gateway SDK
PG.init();

```

Place this after the SDK script is loaded, preferably in a tag at the bottom of your page.

#### Step 4: Handle Form Submission

Capture the form submission and send the payment data to DOKU:

```
const form = document.getElementById('credit-card-form');

form.addEventListener('submit', function(e) {
    e.preventDefault();
    submitPayment();
});

function submitPayment() {
    // Collect card data from form
    const cardData = {
        session_id: document.getElementById('paymentSessionId').value.trim(),
        card_number: document.getElementById('cardNumber').value.replace(/\s/g, ''),
        expiry_month: document.getElementById('expiryMonth').value.trim(),
        expiry_year: document.getElementById('expiryYear').value.trim(),
        cvv: document.getElementById('cvv').value.trim(),
        card_holder_first_name: document.getElementById('firstName').value.trim(),
        card_holder_last_name: document.getElementById('lastName').value.trim(),
    };

    // Submit to DOKU
    PG.payment.collectCardData(cardData, function(error, response) {
        console.log('Payment response:', response);
        console.log('Payment error:', error);

        if (error) {
            // Handle error
            alert('Payment failed: ' + error.message);
            // You can show error message to user or redirect to error page
        } else {
            // Handle success
            alert('Payment successful!');
            // You can redirect to success page or show confirmation
            // window.location.href = '/payment-success';
        }
    });
}
```

### API References

#### PG.init()

Initialize the Payment Gateway SDK. Call this once when the page loads.

```
PG.init();
```

**Parameters:** None

**Returns:** void

#### PG.payment.collectCardData(cardData, callback)

Submit card data for payment processing.

```
PG.payment.collectCardData(cardData, callback);
```

**Required Parameters (cardData object):**

| Field                                                                            | Type   | Description                     | Example                                  |
| -------------------------------------------------------------------------------- | ------ | ------------------------------- | ---------------------------------------- |
| `session_id` <mark style="background-color:red;">**REQUIRED**</mark>             | string | Payment session ID from backend | "ps\_sandbox\_1762256259630\_lRDnbpJT3c" |
| `card_number` <mark style="background-color:red;">**REQUIRED**</mark>            | string | Card number (no spaces)         | "4512490000000907"                       |
| `expiry_month` <mark style="background-color:red;">**REQUIRED**</mark>           | string | Card expiry month (MM)          | "12"                                     |
| `expiry_year` <mark style="background-color:red;">**REQUIRED**</mark>            | string | Card expiry year (YY or YYYY)   | "27" or "2027"                           |
| `cvv` <mark style="background-color:red;">**REQUIRED**</mark>                    | string | Card CVV/CVV2 code              | "123"                                    |
| `card_holder_first_name` <mark style="background-color:red;">**REQUIRED**</mark> | string | Cardholder first name           | "John"                                   |
| `card_holder_last_name` <mark style="background-color:red;">**REQUIRED**</mark>  | string | Cardholder last name            | "Doe"                                    |

#### **Callback Function:**

```
function callback(error, response) {
    if (error) {
        // Error handling
        console.error(error.message);
    } else {
        // Success handling
        console.log(response);
    }
}
```

**Callback Parameters:**

> * `error`: Error object if payment fails (null on success)
>   * `error.message`: Error message string
> * `response`: Response object if payment succeeds (null on error)
>   * Contains payment result data

### Troubleshooting

#### Common Issues

<details>

<summary><strong>1. SDK Not Loaded</strong></summary>

**Error:** `PG is not defined`

**Solution:** Make sure the SDK script is loaded before your code:

```
<script src="https://sandbox.doku.com/card-session/card-session-1.0.0.js"></script>
<script>
    // Your code here
    PG.init();
</script>
```

</details>

<details>

<summary><strong>2. Invalid Session ID</strong></summary>

**Error:** `Invalid session ID`

**Solution:** Ensure you're getting a valid payment session ID from your backend API.

</details>

<details>

<summary><strong>3. Card Validation Errors</strong></summary>

**Error:** `Invalid card number`

**Solution:**

* Remove all spaces from card number
* Verify the card number is valid
* Use test cards in sandbox environment

</details>

<details>

<summary><strong>4. Network Errors</strong></summary>

**Error:** `Network request failed`

**Solution:**

* Check your internet connection
* Verify the SDK URL is correct for your environment
* Check browser console for CORS errors

</details>

<details>

<summary><strong>5. Form Not Submitting</strong></summary>

**Issue:** Clicking submit button does nothing

**Solution:**

* Ensure `e.preventDefault()` is called in the submit handler
* Check browser console for JavaScript errors
* Verify all required fields have values

</details>

#### Debug Mode

Enable console logging to debug issues:

```
PG.payment.collectCardData(cardData, function(error, response) {
    console.log('Card Data:', cardData);
    console.log('Error:', error);
    console.log('Response:', response);

    // Your handling code
});
```

### Security Best Practices

#### 1. Never Store Card Data

Never save card numbers, CVV, or sensitive data in your database or logs. The SDK handles secure transmission of card data to DOKU's servers.

#### 2. Use HTTPS

Always serve your payment page over HTTPS to ensure encrypted communication between the user's browser and your server.

#### 3. Validate Input

Validate user input on both client and server side to prevent malicious data submission and improve user experience.

#### 4. Session Management

Generate payment session IDs server-side with proper authentication. Never expose your API credentials on the client side.

#### 5. Anti-Clickjacking Protection

**What is Clickjacking?** Clickjacking is an attack where a malicious actor tricks users into clicking on hidden elements by overlaying transparent layers on your payment page.

Protect your payment integration by implementing these defense mechanisms:

**JavaScript Frame-Breaker**

Add this script to prevent your payment page from being loaded in unauthorized iframes:

```
<script type="text/javascript">
  // Anti-clickjacking frame-breaker
  if (self === top) {
    // Page is not in an iframe - safe to proceed
    var antiClickjack = document.getElementById("antiClickjack");
    if (antiClickjack) {
      antiClickjack.parentNode.removeChild(antiClickjack);
    }
  } else {
    // Page is in an iframe - redirect to legitimate location
    top.location = self.location;
  }
</script>
```

Add this style in your page `<head>` to hide content until the frame-breaker runs:

```
<style id="antiClickjack">
  body { display: none !important; }
</style>
```

**X-Frame-Options HTTP Header**

Configure your web server to send the X-Frame-Options header to prevent framing:

**Apache (.htaccess or httpd.conf):**

```
Header always set X-Frame-Options "DENY"
# Or to allow same-origin framing only:
# Header always set X-Frame-Options "SAMEORIGIN"
```

**Nginx:**

```
add_header X-Frame-Options "DENY" always;
# Or to allow same-origin framing only:
# add_header X-Frame-Options "SAMEORIGIN" always;
```

**Node.js/Express:**

```
app.use((req, res, next) => {
  res.setHeader('X-Frame-Options', 'DENY');
  next();
});
```

**Content-Security-Policy Header**

Implement CSP with `frame-ancestors` directive for more granular control:

**Apache:**

```
Header always set Content-Security-Policy "frame-ancestors 'none'"
# Or to allow specific domains:
# Header always set Content-Security-Policy "frame-ancestors 'self' https://trusted-domain.com"
```

**Nginx:**

```
add_header Content-Security-Policy "frame-ancestors 'none'" always;
# Or to allow specific domains:
# add_header Content-Security-Policy "frame-ancestors 'self' https://trusted-domain.com" always;
```

**Node.js/Express:**

```
app.use((req, res, next) => {
  res.setHeader('Content-Security-Policy', "frame-ancestors 'none'");
  next();
});
```

**Best Practice: Defense in Depth**

**Implement multiple layers of clickjacking protection for maximum security:**

* JavaScript frame-breaker (client-side)
* X-Frame-Options header (HTTP-level)
* Content-Security-Policy header (modern standard)

**Reference:** [OWASP Clickjacking Defense Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Clickjacking_Defense_Cheat_Sheet.html)

#### 6. PCI Compliance

The SDK handles card data securely, but ensure your implementation follows PCI DSS guidelines. This includes:

* Never logging sensitive card data
* Implementing proper access controls
* Regular security assessments
* Secure coding practices

### Next Steps

1. Test the integration in sandbox environment
2. Implement proper error handling
3. Add form validation
4. Style your payment form
5. Set up production environment
6. Implement server-side payment verification


# Refund

You can request void or refund using this API, or via the [Dashboard](https://dashboard.doku.com/bo/report/transactions) .

{% hint style="info" %}
**Refund Information**

1. If you are using **Cards Aggregator** service, you can process Void or Refund.
2. If you are using **Cards Direct** service, please consult with your acquiring bank through sales to learn more about whether your credential (MID) supports online refund or not, otherwise refund will be processed manually.
3. Refund can be processed partially and multiple times as long as the total amount from original transaction hasnt been reached
   {% endhint %}

To request a refund, you will need to hit this API through your backend:

**API Request**

| Type                          | Value                                                          |
| ----------------------------- | -------------------------------------------------------------- |
| **HTTP Method**               | POST                                                           |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/cancellation/credit-card/refund` |
| **API endpoint (Production)** | `https://api.doku.com/cancellation/credit-card/refund`         |

Here is the sample of request header to generate payment URL:

```
Client-Id: MCH-0001-10791114622547
Request-Id: 6cc9f8b1-d83d-4c24-b853-a3223f43a744
Request-Timestamp: 2020-08-12T09:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

Request Header Explanation

| Parameter             | Description                                                                                                                                                                                                                                                                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client-Id**         | Client ID retrieved from DOKU Back Office                                                                                                                                                                                                                                                                                                             |
| **Request-Id**        | Unique random string (max 128 characters) generated from merchant side to protect duplicate request                                                                                                                                                                                                                                                   |
| **Request-Timestamp** | Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z                                                                                         |
| **Signature**         | Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to [this section](https://developers.doku.com/getting-started-with-doku-api/signature-component/non-snap/signature-component-from-request-header) to generate the signature |

Here is the sample request body to request a refund:

```json
{
    "order": {
        "invoice_number": "INV-20210118-0001"
    },
    "payment": {
        "original_request_id": "b266c265-3d61-4708-9860-c0d5b9a98f8c"
    },
    "refund": {
        "amount": 90000
    }
}
```

Request Body Explanation

| Parameter                     | Type     | Mandatory | Description                                                               |
| ----------------------------- | -------- | --------- | ------------------------------------------------------------------------- |
| `order.invoice_number`        | `string` | Mandatory | Invoice number of the transaction that being refunded                     |
| `payment.original_request_id` | `string` | Mandatory | Request ID from payment initiation of the transaction that being refunded |
| `refund.amount`               | `number` | Mandatory | Transaction amount that wants to be refunded                              |

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

Here is the sample response header:

```
Client-Id: MCH-0001-10791114622547
Request-Id: 6cc9f8b1-d83d-4c24-b853-a3223f43a744
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
```

Response Header Explanation

| Parameter              | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| **Client-Id**          | Same as the request                                           |
| **Request-Id**         | Same as the request                                           |
| **Response-Timestamp** | Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU |
| **Signature**          | Signature generated by DOKU based on the response body        |

Here is the sample of successful response body:

```
{
    "order": {
        "invoice_number": "INV-20210118-0001"
    },
    "payment": {
        "original_request_id": "b266c265-3d61-4708-9860-c0d5b9a98f8c"
    },
    "refund": {
        "amount": 90000,
        "type": "FULL_REFUND",
        "status": "SUCCESS",
        "message": "Approved",
        "approval_code": "12321"
    }
}
```

Here is the sample of **failed** response body:

```json
{
    "order": {
        "invoice_number": "saweran_rest_api_2"
    },
    "payment": {
        "original_request_id": "5450"
    },
    "refund": {
        "amount": 20000,
        "reason": "REFUND TEST",
        "type": "FULL_REFUND",
        "status": "FAILED"
    },
    "error": {
        "code": "PAYMENT_FAILED",
        "message": "Total Refund amount is Bigger than Original Transaction",
        "type": "Payment Failed"
    }
}
```

Response Body Explanation

| Parameter                     | Type     | Mandatory | Description                                                                                                                                                    |
| ----------------------------- | -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`        | `string` | Mandatory | Same as the request                                                                                                                                            |
| `payment.original_request_id` | `string` | Mandatory | Same as the request                                                                                                                                            |
| `refund.amount`               | `number` | Mandatory | Same as the request                                                                                                                                            |
| `refund.type`                 | `string` | Mandatory | <p>Refund type based on the transaction<br>Possible value: <code>VOID, PARTIAL\_REFUND, FULL\_REFUND, MANUAL\_PARTIAL\_REFUND, MANUAL\_FULL\_REFUND</code></p> |
| `refund.status`               | `string` | Mandatory | <p>Refund status<br>Possible value: <code>SUCCESS, FAILED</code></p>                                                                                           |
| `refund.message`              | `string` | Optional  | Refund message description                                                                                                                                     |
| `refund.approval_code`        | `string` | Optional  | Acquiring approval code for the refund transaction if the `refund.status` = `SUCCESS`                                                                          |

{% hint style="info" %}
**Refund Type**

**Online Refund**

Amount will be returned automatically by system to customer's balance

* **VOID**: If the funds has not settled to your bank account. The `refund.amount` must equal to `order.amount`, otherwise will fail
* **PARTIAL\_REFUND**: If the funds has settled to your bank account, and the `refund.amount` is less than `order.amount`
* **FULL\_REFUND**: If the funds has settled to your bank account, and the `refund.amount` is equal to `order.amount`

**Manual Refund**

Amount will be processed manually by DOKU's Refund Ops, may take several days to process

* **MANUAL\_PARTIAL\_REFUND**: If the funds has settled to your bank account, and the `refund.amount` is less than `order.amount`
* **MANUAL\_FULL\_REFUND**: If the funds has settled to your bank account, and the `refund.amount` is equal to `order.amount`

{% endhint %}


# Tokenization

Want to make your checkout experience faster? You can combine this integration with the Tokenization, so the next time your customers purchase, they don't need to input the credit card anymore.

* Tokenization

### Get Token List

If you've previously made payment and you or your customer choose to save the credit card info\
You may use this Get Token List API show the saved card of your customers.\
this API can be used to obtain token from other payment method such as OVO, BRI Direct Debit, Allobank, etc that also uses tokenization feature.

| Type                          | Value                                                    |
| ----------------------------- | -------------------------------------------------------- |
| **HTTP Method**               | POST                                                     |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/tokenization/v2/get-token` |
| **API endpoint (Production)** | `https://api.doku.com/tokenization/v2/get-token`         |

## Get Token List

> Returns all active tokens for a customer.<br>

```json
{"openapi":"3.1.0","info":{"title":"Tokenization Core System — Get Token","version":"1.0.0"},"servers":[{"url":"http://localhost:8080","description":"Local"}],"paths":{"/tokenization/v2/get-token":{"post":{"operationId":"tokenizationV3GetTokenPost","summary":"Get Token List","description":"Returns all active tokens for a customer.\n","tags":["Token Management"],"parameters":[{"name":"Client-Id","in":"header","required":true,"description":"Merchant client identifier issued by DOKU","schema":{"type":"string"}},{"name":"Accept","in":"header","required":true,"description":"Must be `application/json`","schema":{"type":"string","default":"application/json"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTokenRequest"}}}},"responses":{"200":{"description":"Token list retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTokenResponse"}}}},"400":{"description":"Bad request.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDTO"}}}},"500":{"description":"Internal server error — e.g., decryption failure or downstream service error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDTO"}}}}}}}},"components":{"schemas":{"GetTokenRequest":{"type":"object","required":["customer"],"properties":{"customer":{"type":"object","required":["id"],"description":"Customer identification","properties":{"id":{"type":"string","description":"Merchant customer identifier. Must not be blank."}}},"channel":{"type":"object","description":"Optional channel filter. Omit to return tokens across all channels.","properties":{"id":{"type":"string","enum":["CREDIT_CARD","DIRECT_DEBIT","EMONEY","KARTU_KREDIT_INDONESIA"],"description":"Payment channel identifier"}}},"issuer":{"type":"object","description":"Optional issuer filter.","properties":{"id":{"type":"string","description":"Issuer identifier (e.g., bank code or e-wallet name)"}}}}},"GetTokenResponse":{"type":"object","description":"List of active tokens for the customer","properties":{"customer":{"type":"object","description":"Echoes back the resolved customer identifier","properties":{"id":{"type":"string","description":"Merchant customer identifier"}}},"tokens":{"type":"array","description":"List of active tokens. Each item is one of:\n- `TokenCC` — for `CREDIT_CARD` channel\n- `Token` — for `DIRECT_DEBIT`, `EMONEY`, and `KARTU_KREDIT_INDONESIA` channels\n","items":{"oneOf":[{"$ref":"#/components/schemas/TokenCC"},{"$ref":"#/components/schemas/Token"}]}}}},"TokenCC":{"type":"object","description":"Credit card network token. Always returned for CREDIT_CARD channel.\n`metadata` is null when VTS metadata is not available for this token.\nFields with null values are omitted from the response (`@JsonInclude(NON_NULL)`).\n","properties":{"id":{"type":"string","description":"Token identifier (Visa network token value stored as gateway token ID)"},"masked_account":{"type":"string","description":"Masked PAN. First 6 and last 4 digits visible, middle masked (e.g., `411111xxxxxx1111`)."},"metadata":{"nullable":true,"description":"VTS card metadata. Null when VTS has not enrolled this PAN or metadata retrieval failed.\nContains VTS provisioned token IDs, card display metadata (colors, issuer contact), and PAN status.\n","allOf":[{"$ref":"#/components/schemas/VtsCardMetadata"}]},"card":{"$ref":"#/components/schemas/TokenCCCard"}}},"VtsCardMetadata":{"type":"object","description":"Subset of VTS GetCardMetadata response stored against the token","properties":{"vPanEnrollmentID":{"type":"string","description":"VTS PAN enrollment identifier"},"status":{"type":"string","description":"Overall VTS enrollment status for this PAN"},"paymentInstrument":{"type":"object","description":"Payment instrument details from VTS","properties":{"last4":{"type":"string","description":"Last 4 digits of the PAN"},"expirationDate":{"type":"object","properties":{"month":{"type":"string"},"year":{"type":"string"}}},"paymentAccountReference":{"type":"string","description":"Payment Account Reference (PAR)"}}},"tokens":{"type":"array","description":"VTS provisioned token entries for this PAN","items":{"type":"object","properties":{"vProvisionedTokenID":{"type":"string","description":"VTS Provisioned Token ID"},"tokenStatus":{"type":"string","description":"VTS token status (e.g., ACTIVE, INACTIVE, SUSPENDED)"}}}},"cardMetaData":{"type":"object","description":"Card display metadata (branding colors, issuer contact information)","properties":{"backgroundColor":{"type":"string"},"foregroundColor":{"type":"string"},"labelColor":{"type":"string"},"contactWebsite":{"type":"string"},"contactEmail":{"type":"string"},"contactNumber":{"type":"string"},"contactName":{"type":"string"},"shortDescription":{"type":"string"}}}}},"TokenCCCard":{"type":"object","description":"Card details attached to a credit card token","properties":{"name":{"type":"string","description":"Cardholder name"},"expiry":{"type":"string","description":"Masked expiry date. Month is visible, year is masked (e.g., `12/**`)."},"bin":{"type":"string","description":"Bank Identification Number — first 6–8 digits of the PAN"},"brand":{"type":"string","description":"Card network brand"},"issuer":{"type":"string","description":"Card-issuing bank name"},"country":{"type":"string","description":"Card country code (ISO 3166-1 alpha-2)"},"encrypted_expiry":{"type":"string","description":"AU-Sec encrypted expiry date (original encrypted value from provisioning)"},"hashed_card_number":{"type":"string","description":"HMAC-SHA512 of the plaintext card number, keyed with merchant-specific secret. Empty string if hashing fails."},"payer_account_id":{"type":"string","description":"Same value as `hashed_card_number`. Used as the VTS Payer Account ID."}}},"Token":{"type":"object","description":"Token for non-credit-card channels (DIRECT_DEBIT, EMONEY, KARTU_KREDIT_INDONESIA).\n- `auth_code` is present only for DIRECT_DEBIT.\n- `encrypted_card_number` is present only for KARTU_KREDIT_INDONESIA.\nFields with null values are omitted from the response (`@JsonInclude(NON_NULL)`).\n","properties":{"id":{"type":"string","description":"Token identifier (SHA-512 hash stored as the gateway token)"},"masked_account":{"type":"string","description":"Masked account number. Format depends on channel:\n- DIRECT_DEBIT / EMONEY: first 6 digits visible, last 4 visible, middle masked (e.g., `123456xxxxxx7890`)\n- KARTU_KREDIT_INDONESIA: same masking pattern\n"},"auth_code":{"type":"string","nullable":true,"description":"Authorization code — 40-character string. Present for DIRECT_DEBIT only."},"encrypted_card_number":{"type":"string","nullable":true,"description":"AU-Sec encrypted card number. Present for KARTU_KREDIT_INDONESIA only."}}},"ErrorDTO":{"type":"object","description":"Standard error response envelope","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code:\n- `INVALID_PARAMETER` — request validation failure (blank customer.id, invalid channel)\n- `data_not_found` — merchant / customer / tokens not found\n- `INTERNAL_SERVICE_ERROR` — decryption or downstream service failure\n"},"type":{"type":"string","description":"Error category returned by the service"},"message":{"type":"string","description":"Human-readable error message"}}}}}}}}
```

### Unbind Token

If you want to unbind the token, you can use the delete tokenization API below :

**API Request**

| Type                          | Value                                                       |
| ----------------------------- | ----------------------------------------------------------- |
| **HTTP Method**               | POST                                                        |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com`/tokenization/v2/delete-token |
| **API endpoint (Production)** | `https://api.doku.com`/tokenization/v2/delete-token         |

Here is the sample of request header to capture the transaction:

```
Client-Id: MCH-0001-10791114622547
Request-Id: 071a6a32-6785-4011-833d-d2c2049cf744
Request-Timestamp: 2021-08-24T08:46:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

Request Header Explanation

| Parameter             | Description                                                                                                                                                                                                                                                                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client-Id**         | Client ID retrieved from DOKU Back Office                                                                                                                                                                                                                                                                                                             |
| **Request-Id**        | Unique random string (max 128 characters) generated from merchant side to protect duplicate request                                                                                                                                                                                                                                                   |
| **Request-Timestamp** | Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z                                                                                         |
| **Signature**         | Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to [this section](https://developers.doku.com/getting-started-with-doku-api/signature-component/non-snap/signature-component-from-request-header) to generate the signature |

Here is the sample request body to unbind the token:

```
{
  "token": {
    "id": "gateway-token"
  }
}
```

Request Body Explanation

| Parameter  | Type     | Mandatory | Description                            |
| ---------- | -------- | --------- | -------------------------------------- |
| `token.id` | `string` | Mandatory | Token ID that want to unbind or delete |

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

Here is the sample response header:

```
Client-Id: MCH-0001-10791114622547
Request-Id: b266c265-3d61-4708-9860-c0d5b9a98f8c
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
```

Response Header Explanation

| Parameter              | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| **Client-Id**          | Same as the request                                           |
| **Request-Id**         | Same as the request                                           |
| **Response-Timestamp** | Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU |
| **Signature**          | Signature generated by DOKU based on the response body        |

Here is the sample of response body:

```json
{
  "token": {
    "id": "gateway-token",
    "status": "INACTIVE"
  }
}
```

Response Body Explanation

| Parameter      | Type     | Mandatory | Description                                                           |
| -------------- | -------- | --------- | --------------------------------------------------------------------- |
| `token.id`     | `string` | Mandatory | Token ID that want to unbind or delete                                |
| `token.status` | `string` | Mandatory | <p>Delete Process Status<br>Possible Value: <code>INACTIVE</code></p> |

{% hint style="info" %}
**Info**

To make sure the token has been unbinded, you can hit API Get token List.
{% endhint %}


# Mastercard Automatic Billing Updater (ABU) Integration Guide

ABU is a service that allows you as DOKU merchants to inquire about the validity or changes in Customer's Cards Information. This service is open to PCI DSS merchants only

Every year, Approximately 30% of recurring card transactions fail because of expired cards or changed card information, With ABU integration, ABU allows you to get updated card information from your Customers who use the MasterCard Brand Credit Cards, thus increasing your business's success rate for recurring Cards transaction. Here is the overview of how ABU works :&#x20;

1. Upload File card registration via ABU SFTP&#x20;
2. Receive the result file in the Result ABU SFTP Folder
3. Update expired/changed cards&#x20;
4. Send payment using direct API or Batch Upload with the updated cards

## Preparation for New Merchant&#x20;

There some steps need to be prepared if you want to integrate with DOKU Checkout Page :

### User Registration

In this section, DOKU Dashboard sandbox environment is used to integrate process to our ABU page. Sandbox is use for testing purpose where you can explore our features without making any real Cards. In DOKU, it is very easy to get Sandbox access and explore our products. You can create the account by following the steps

Go to Account > Service > Add Service > Financial Services > Cards Mastercard ABU

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td></td><td>Go to Account > Service > Add Service in DOKU Dashboard <a href="https://dashboard.doku.com/">https://dashboard.doku.com/</a></td><td></td><td><a href="/files/Ua0UBctuQOqrigTpOLnP">/files/Ua0UBctuQOqrigTpOLnP</a></td></tr><tr><td></td><td>Scroll down to Financial Services > Cards , choose Mastercard Automatic Billing Updater and click Activate</td><td></td><td><a href="/files/ArJCROlg3w0dNcILFAuw">/files/ArJCROlg3w0dNcILFAuw</a></td></tr></tbody></table>

The activation will be processed after passing several layer of security check in DOKU, kindly wait or you can occasionally ask our Sales team regarding the Update


# Backend Integration

***

## Setup&#x20;

You can start by downloading your private and public keys to encrypt file and you also have to setup a notification URL so that DOKU can send a notification that the file being processed is completed.&#x20;

<figure><img src="/files/40FVeQWwj72ZXNa4JXze" alt=""><figcaption></figcaption></figure>

Integration Steps

* Upload File card registration via ABU SFTP  Folder
* Hit API Notification to DOKU
* Consume Notification from DOKU
* Download the result file from DOKU Result Folder

<figure><img src="/files/K94XEWotxGKenzznG9us" alt=""><figcaption><p>DOKU Automatic Billing Updater Flow Diagram</p></figcaption></figure>

### Access&#x20;

DOKU will create user access for merchants to Read & Write in SFTP DOKU according to the environment. Merchants will send their IP for  DOKU Whitelist.

<figure><img src="https://lh7-us.googleusercontent.com/docsz/AD_4nXdRahv71H_zDjQLjw_NIjHHLFBO-PysGsEpIbsOyl76UvVy07MAW_jSQFoNN9cKnUG18ldjRDT8LWv90Hv-cTtXXQwXOZQ-Wc4xAFBFSCBKQ9dyMQ_gdjwD6AjFC-VfLFQ-QhuluAvliVzBogeWDdo5HJkzX4fKJgghQMv7Vg?key=vg0lJoiTVHqzGlT4QARvVQ" alt=""><figcaption></figcaption></figure>

### Encryption Procedure

Encryption Procedure

1. Merchants generate random String with length 32 digit Alfa Numeric as SALT.
2. Merchants encrypt plain card data using AES 256 Key Size, Chiper ECB, pkcs5 padding with SALT to Base64 encoded format. <https://www.devglan.com/online-tools/aes-encryption-decryption>
3. Merchants encrypt the SALT using a DOKU RSA Public Key 2048 bit - No Padding to Base64 encoded format. <https://www.devglan.com/online-tools/rsa-encryption-decryption>
4. Merchants put the data on file (txt format) with content format : {Length\_Of\_Encrypted\_SALT}+{Encrypted\_SALT}+{Encrypted\_Plain\_Card\_Data}
   * {Length\_Of\_Encrypted\_SALT} : add padding left with "0", so there will be 4 digits (ex : 0344).
   * {Encrypted\_SALT} : in Base64 format.
   * {Encrypted\_Plain\_Card\_Data} : in Base64 format.
5. The txt file data ready to put on DOKU SFTP ./download/ folder

### Decryption Procedure

1. Get the length of the Encrypted SALT:
   * Extract the first 4 digits from the data. These 4 digits represent the length of the encrypted SALT.
   * Cast this value into an integer, which will tell you how long the encrypted SALT is.
2. Extract the Encrypted SALT:
   * Use the length obtained in Step 1.
   * Extract a substring from the data starting at index 4. This substring runs from index 4 to (index 4 + the length of the encrypted SALT)&#x20;
3. Decrypt the Encrypted SALT:
   * Use Merchant RSA Private Key 2048 bit - No Padding decryption to decrypt the extracted Encrypted SALT value.
4. Extract the Encrypted Data:
   * Now, get the remaining part of the card data, starting from index (4 + length of the Encrypted SALT) to the end of the data. This is the encrypted card data.
5. Decrypt the Encrypted Data:
   * Use AES 256 with SALT obtained from step 3 to decrypt the encrypted card data.

### Folder

<figure><img src="https://lh7-us.googleusercontent.com/docsz/AD_4nXchFZshMBN2eaiW5SX0XNO8DW7_OcBuebSzo-akHB06hyf1qrWtthSgA6lfbB3h-T06Zp5UVFCese0wrs39ex5ONOC4KYJ3D-4SypL2b6AtTBBGip4bFFiNX6KNeLfwBgSwLIR9ExmYe-pGp9jNSIAIS-fQAXUSlWgNFNKGGQ?key=vg0lJoiTVHqzGlT4QARvVQ" alt=""><figcaption></figcaption></figure>

### SFTP File

In this document will explain in details how to create file for transaction using SFTP. File Upload

Before putting the file in SFTP, we first need to set up the file itself. You will need to create it in TXT Format.

**Example .TXT File :**

```json
D000001999128616DOKU0001  5XXXXNNNNNNNNNNN   YYMMAAAAA00001
D000001999128616DOKU0002  5XXXXNNNNNNNNNNN   YYMMAAAAA00002
```

### File Explanation <a href="#id-1-obtain-paymenturl-on-backend" id="id-1-obtain-paymenturl-on-backend"></a>

<table><thead><tr><th width="167">Field Name</th><th>Length</th><th width="40">Type</th><th>Position</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>detail-identifier</code></strong></td><td>1</td><td>AN</td><td>1</td><td>Value 'D'</td></tr><tr><td><strong><code>merchant-id</code></strong></td><td>15</td><td>AN</td><td>2-16</td><td>Valid merchant ID or Payment Facilitator ID</td></tr><tr><td><strong><code>merchant-request-identifier-1</code></strong></td><td>10</td><td>AN</td><td>17-26</td><td>Tracking number for merchant, <strong>must be unique per batch file</strong></td></tr><tr><td><strong><code>PAN number</code></strong></td><td>19</td><td>N</td><td>27-45</td><td>Old PAN Number</td></tr><tr><td><strong><code>Expiry Date</code></strong></td><td>4</td><td>N</td><td>46-49</td><td>YYMM Format</td></tr><tr><td><strong><code>merchant-request-identifier-2</code></strong></td><td>20</td><td>AN</td><td>50-69</td><td>Tracking number for merchant</td></tr><tr><td><strong><code>filler</code></strong></td><td>20</td><td>AN</td><td>70-89</td><td>Blank spaces</td></tr></tbody></table>

### File Report

After transaction finish DOKU will generate report in TXT format, like Example below. Merchant can get the data in to folder “upload”.

```
D000000000000002AAAA0001  5185515000000334   5185515000000334   22122212VALID AAAAA00001          V                   
D000000000000002AAAA0002  5185693000000115   5185693000000115   22122212VALID AAAAA00002          V                   
D000000000000002AAAA0003  4005550010538560   5410221000000112   11052212UPDATEAAAAA00003                              
```

<table><thead><tr><th width="167">Field Name</th><th>Length</th><th width="68">Type</th><th>Position</th><th>Description</th></tr></thead><tbody><tr><td><strong>detail-identifier</strong></td><td>1</td><td>AN</td><td>1</td><td>Value 'D'</td></tr><tr><td><strong>merchant-id</strong></td><td>15</td><td>AN</td><td>2-16</td><td>Valid merchant ID or Payment Facilitator ID</td></tr><tr><td><strong>merchant-request-identifier-1</strong></td><td>10</td><td>AN</td><td>17-26</td><td>Tracking number for merchant</td></tr><tr><td><strong>Old PAN Number</strong></td><td>19</td><td>AN</td><td>27-45</td><td>Old PAN Number</td></tr><tr><td><strong>New PAN Number</strong></td><td>19</td><td>AN</td><td>46-64</td><td>New PAN Number</td></tr><tr><td><strong>Old Expiry Date</strong></td><td>4</td><td>N</td><td>65-68</td><td>YYMM Format</td></tr><tr><td><strong>New Expiry Date</strong></td><td>4</td><td>AN</td><td>69-72</td><td>YYMM Format</td></tr><tr><td><strong>Reason Identifier</strong></td><td>6</td><td>AN</td><td>73-78</td><td>Contains one of the following values for account requests that had a match: • UPDATE—Match made; update data provided (includes issuer Reason Codes R, B, and P) • CONTAC—Match made; account closed (includes Issuer Reason Code C) • EXPIRY—Match made; expiration date changed (includes Issuer Reason Code E) • VALID—No updates were found but the account is valid. • UNKNWN—The account number could not be found in the ABU database. (See the Response Indicator for further explanation.) </td></tr><tr><td><strong>merchant-request-identifier-2</strong></td><td>20</td><td>AN</td><td>79-98</td><td>Tracking number for merchant</td></tr><tr><td><strong>response indicator</strong></td><td>1</td><td>A</td><td>99</td><td>ABU Validation Response Indicator (displayed only when the Reason Identifier is VALID or UNKNWN) • V—matches the account as reported by the issuer • P—No match, participating BIN/ issuer • N—No match, non-participating BIN/issuer</td></tr><tr><td><strong>filler</strong></td><td>19</td><td>AN</td><td>100-118</td><td>Blank Spaces</td></tr></tbody></table>

## Merchant Notification

### Notification API

### Request&#x20;

Here is the sample of request header to notify DOKU

```json
Client-Id: MCH-0001-10791114622547
Request-Id: fdb69f47-96da-499d-acec-7cdc318ab2fe
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
```

### Request Header Explanation <a href="#id-1-obtain-paymenturl-on-backend" id="id-1-obtain-paymenturl-on-backend"></a>

<table><thead><tr><th width="167">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>client-id</code></strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong><code>request-id</code></strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong><code>request-timestamp</code></strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong><code>signature</code></strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="https://dashboard.doku.com/docs/docs/technical-references/generate-signature">this section</a> to generate the signature</td></tr></tbody></table>

### Merchant Notify to DOKU

After merchants put file data in SFTP, merchants will trigger DOKU to get data file in SFTP with this API.<br>

**Format: REST API (JSON)**

| Type                          | Value                                     |
| ----------------------------- | ----------------------------------------- |
| **HTTP Method**               | POST                                      |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/abu/notify` |
| **API endpoint (Production)** | `https://api.doku.com/abu/notify`         |

#### Request Body

| Parameter  | Data Type   | Type      | Description                                         |
| ---------- | ----------- | --------- | --------------------------------------------------- |
| file\_name | String(128) | Mandatory | File name merchant put in DOKU sftp download folder |

Example Request:

```json
{
  "file_name": "example.txt"
}
```

#### Response Body

| name          | String (128)            | Mandatory           | File name                   |
| ------------- | ----------------------- | ------------------- | --------------------------- |
| status        | String (128)            | Mandatory           | IN\_PROCESS response        |
| error.code    | <p>String (128)<br></p> | <p><br>Optional</p> | <p><br>Response Code</p>    |
| error.message | <p>String (128)<br></p> | <p>Optional<br></p> | <p>Response Message<br></p> |
| error.type    | <p>String (128)<br></p> | <p>Optional<br></p> | <p><br>Error Type</p>       |

**Example Response  Success:**

Http status code: 201

```json
{
  "name": "example.txt",
  "status": "IN_PROCESS"
}
```

**List of error message**

| invalid header signature     | invalid\_signature  | 400 | Invalid Signature                                   |
| ---------------------------- | ------------------- | --- | --------------------------------------------------- |
| idempotent request           | idempotent\_request | 400 | Double request with same request id under 20 second |
| file\_name must not be empty | invalid\_parameter  | 400 | Not input object file\_name                         |
| File not found in SFTP       | not\_found          | 404 | File not found in DOKU sftp download folder         |

### DOKU Notify to Merchant

After DOKU create report in SFTP, DOKU will notify merchant to get report.

Guide how to handle payment notification can refer to: <https://jokul.doku.com/docs/docs/http-notification/overview>

#### Request

Format: REST API (JSON)

| service.id         | <p><br>string</p>    | Mandatory | Batch Upload Service          |
| ------------------ | -------------------- | --------- | ----------------------------- |
| batch\_file.name   | <p>string<br></p>    | Mandatory | Batch file Upload name        |
| batch\_file.status | <p><br>string</p>    | Mandatory | Status of processed file Done |
| batch\_file.date   | <p><br>timestamp</p> | Mandatory | Date file finish processed    |

Example :

```json
{
  "service": {
    "id": "ABU"
  },
  "abu_file": {
    "name": "example.txt",
    "status": "DONE",
    "message": "SUCCESS",
    "date": "2021-07-29T13:52:53Z"
  }
}
```


# e-Wallet

DOKU provides various payment channels. One of the most used by our merchants is E-Money. By using this payment channels, your customer can pay their order through e-money applications. DOKU has partnered with various e-money providers to help you provide many payment options for your customers.

***

### Payment channel supported <a href="#payment-channel-supported" id="payment-channel-supported"></a>

We have partnered with various e-money to provide you many options:

| Name             | Current Version |
| ---------------- | --------------- |
| DOKU Wallet      | `v1`            |
| OVO Push Payment | `v1`            |
| ShopeePay        | `v2`            |
| LinkAja          | `v2`            |

***

### What's next? <a href="#whats-next" id="whats-next"></a>

You can learn more about how to integrate to each payment channels you wish by clicking the menu on the sidebar.


# Overview

DOKU provides various payment channels. One of the most used by our merchants is E-Money. By using this payment channels, your customer can pay their order through e-money applications. DOKU has partnered with various e-money providers to help you provide many payment options for your customers.

***

### Payment channel supported <a href="#payment-channel-supported" id="payment-channel-supported"></a>

We have partnered with various e-money to provide you many options:

| Name         | Current Version |
| ------------ | --------------- |
| DOKU Wallet  | `v1`            |
| OVO          | `v1`            |
| OVO Open API | `v2`            |
| ShopeePay    | `v2`            |

***

### What's next? <a href="#whats-next" id="whats-next"></a>

You can learn more about how to integrate to each payment channels you wish by clicking the menu on the sidebar.


# OVO Push Payment

OVO Push Payment API Explanation

DOKU has partnered with various e-money providers and one of them is OVO to provide E-Money Payment. Learn more about how DOKU can help you integrate with OVO here.

### Integration Steps

Here is the overview of how to integrate with OVO:

1. Request push payment
2. Wait for 70s for the API response (wait customer to pay via OVO application)
3. Receive the response with the transaction status

#### OVO Push Payment Sequence Diagram

<figure><img src="/files/Z0WgAgmjCeDLMFUQFZoU" alt=""><figcaption></figcaption></figure>

#### 1. Request push payment[​](https://dashboard.doku.com/docs/docs/jokul-direct/e-money/ovo-guide#1-request-push-payment) <a href="#id-1-request-push-payment" id="id-1-request-push-payment"></a>

To request push payment, you will need to hit this API through your Backend :

**API Request**

| Type                          | Value                                                |
| ----------------------------- | ---------------------------------------------------- |
| HTTP Method                   | POST                                                 |
| **API endpoint (Sandbox)**    | <https://api-sandbox.doku.com/ovo-emoney/v1/payment> |
| **API endpoint (Production)** | <https://api.doku.com/ovo-emoney/v1/payment>         |

Here is the sample of request body to make the push payment :

```json
{
    "client": {
        "id":"MCH-0001-10791114622547"
    },
    "order": {
        "invoice_number":"INV-20210115-0001",
        "amount": 10000
    },
    "ovo_info": {
        "ovo_id": "081211111111"
    },
    "security":{
        "check_sum":"c3cad18f3fcac29d44165fa6b7a01b09e305d1e75caec163181cf5101b91e18e"
    }
}
```

> **What is security.check\_sum?**
>
> `security.check_sum` is a security parameter that needs to be generated on your Backend and placed to your request body to ensure that the request is coming from you. To generate CheckSum, simply append the value of `order.amount`, `client.id`, `order.invoice_number`, `ovo_info.ovo_id`, `your secret key` and then hash it with SHA256 function.
>
> ```
> sha256(order.amount + client.id + order.invoice_number + ovo_info.ovo_id + your-secret-key)
> ```
>
> From the request body sample above and assuming your secret key is `SK-9sCrJ1kdYUJAYlsJKlqz`, here is what you need to do to generate the CheckSum:
>
> ```
> sha256(10000MCH-0001-10791114622547MINV20201231468081211111111SK-9sCrJ1kdYUJAYlsJKlqz)
> ```

**Request Body Explanation**

<table><thead><tr><th width="193">Parameter</th><th width="80">Type</th><th width="127">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>client.id</code></td><td>string</td><td>Mandatory</td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><code>order.invoice_number</code></td><td>string</td><td>Mandatory</td><td>Generated by merchant to identify the order and must unique per request<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code></td></tr><tr><td><code>order.amount</code></td><td>number</td><td>Mandatory</td><td>In IDR Currency and without decimal.<br>Max length: <code>12</code></td></tr><tr><td><code>ovo_info.ovo_id</code></td><td>string</td><td>Mandatory</td><td>Phone number of the OVO Customer. Allowed chars: <code>numeric</code></td></tr><tr><td><code>security.check_sum</code></td><td>string</td><td>Mandatory</td><td>Security parameter that must be generated by merchant to validate the request<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code></td></tr></tbody></table>

#### 2. Wait for 70s for the API Response (wait customer to pay via OVO application)[​](https://dashboard.doku.com/docs/docs/jokul-direct/e-money/ovo-guide#2-wait-for-70s-for-the-api-response-wait-customer-to-pay-via-ovo-application)

{% hint style="info" %}
**`70S` TIMEOUT**

The timeout from OVO is `70 seconds` so there will be proper time for your customers to complete the payment process on their OVO application.
{% endhint %}

Please wait for `70s` for the API response because we need to wait your customers make the payment through their OVO application, you will receive an API response that you can parse to handle your business logic.

#### 3. Receive the response with the transaction status[​](https://dashboard.doku.com/docs/docs/jokul-direct/e-money/ovo-guide#3-receive-the-response-with-the-transaction-status) <a href="#id-3-receive-the-response-with-the-transaction-status" id="id-3-receive-the-response-with-the-transaction-status"></a>

If the customer make the payment through their OVO Application. You wil get the following API response :&#x20;

```json
{
    "client": {
        "id": "MCH-0001-10791114622547"
    },
    "order": {
        "invoice_number": "INV-20210115-0001",
        "amount": 10000
    },
    "ovo_info": {
        "ovo_id": "081211111111",
        "ovo_account_name": "Anton Budiman"
    },
    "ovo_configuration": {
        "merchant_id": "00000179",
        "store_code": "000000000000179",
        "mid": "000000000000179",
        "tid": "00000179"
    },
    "ovo_payment": {
        "date": "20201014162928",
        "batch_number": 4,
        "trace_number": 987654,
        "reference_number": 38,
        "approval_code": "19832",
        "response_code": "00",
        "cash_used": 10000,
        "cash_balance": 90000,
        "ovo_points_used": 0,
        "ovo_points_balance": 100000,
        "ovo_points_earned": 0,
        "status": "SUCCESS"
    },
    "security": {
        "check_sum": "5df88427628952ac65fee1d01aa163cdd26a1cf806c7e80d770fa307db180930"
    }
}
```

**Response Body Explanation**

<table><thead><tr><th width="243">Parameter</th><th width="97">Type</th><th width="116">Mandatory </th><th>Description</th></tr></thead><tbody><tr><td><code>client_id</code></td><td>string</td><td>Mandatory</td><td>Same as the request</td></tr><tr><td><code>order.invoice_number</code></td><td>string</td><td>Mandatory</td><td>Same as the request</td></tr><tr><td><code>order.amount</code></td><td>number</td><td>Mandatory</td><td>Same as the request</td></tr><tr><td><code>ovo_info.ovo_id</code></td><td>string</td><td>Mandatory</td><td>Same as the request</td></tr><tr><td><code>ovo_info.ovo_account_name</code></td><td>string</td><td>Mandatory</td><td>Name of the OVO customer</td></tr><tr><td><code>ovo_configuration.merchant_id</code></td><td>string</td><td>Mandatory</td><td>Merchant ID by OVO<br>Allowed chars: <code>numeric</code><br>Max length: <code>7</code></td></tr><tr><td><code>ovo_configuration.store_code</code></td><td>string</td><td>Mandatory</td><td>Store code by OVO. Allowed chars: <code>alphabetic, numeric</code><br>Max length: <code>15</code></td></tr><tr><td><code>ovo_configuration.mid</code></td><td>string</td><td>Mandatory</td><td>MID by OVO.<br>Allowed chars: <code>alphabetic, numeric</code><br>Max length: <code>15</code></td></tr><tr><td><code>ovo_configuration.tid</code></td><td>string</td><td>Mandatory</td><td>TID by OVO<br>Allowed chars: <code>numeric</code><br>Max length: <code>8</code></td></tr><tr><td><code>ovo_payment.date</code></td><td>string</td><td>Mandatory</td><td>Payment date generated by DOKU with the format of <code>yyyyMMddHHmmss</code> UTC+7 time</td></tr><tr><td><code>ovo_payment.batch_number</code></td><td>number</td><td>Mandatory</td><td>Batch number of transaction for settlement. Value increment on daily basis, except if the Reference Number already reached maximum value</td></tr><tr><td><code>ovo_payment.trace_number</code></td><td>number</td><td>Mandatory</td><td>Generated by OVO<br>Max length: <code>6</code></td></tr><tr><td><code>ovo_payment.reference_number</code></td><td>number</td><td>Mandatory</td><td>Transaction ID for every transaction generated by OVO. Increment for each Push to Pay Transaction<br>Maximum value: <code>999999</code></td></tr><tr><td><code>ovo_payment.approval_code</code></td><td>string</td><td>Mandatory</td><td>Generated by OVO</td></tr><tr><td><code>ovo_payment.response_code</code></td><td>string</td><td>Mandatory</td><td>Generated by OVO. Please refer to the section below for the <code>response_code</code> mapping</td></tr><tr><td><code>ovo_payment.cash_used</code></td><td>number</td><td>Mandatory</td><td>OVO Cash that being charged for the transaction</td></tr><tr><td><code>ovo_payment.cash_balance</code></td><td>number</td><td>Mandatory</td><td>OVO Cash remaining balance after the transaction</td></tr><tr><td><code>ovo_payment.ovo_points_used</code></td><td>number</td><td>Mandatory</td><td>OVO Points that being charged for the transaction</td></tr><tr><td><code>ovo_payment.ovo_points_balance</code></td><td>number</td><td>Mandatory</td><td>OVO Points remaining balance after the transaction</td></tr><tr><td><code>vo_payment.ovo_points_earned</code></td><td>number</td><td>Mandatory</td><td>OVO Points earned after the transaction</td></tr><tr><td><code>ovo_payment.status</code></td><td>string</td><td>Mandatory</td><td>Payment status generated by DOKU<br>Possible value: <code>SUCCESS</code>, <code>FAILED</code>, <code>TIMEOUT</code></td></tr><tr><td><code>security.check_sum</code></td><td>string</td><td>Mandatory</td><td>Security parameter that validated by DOKU</td></tr></tbody></table>

### OVO Response Code Mapping

<table><thead><tr><th width="97">Code</th><th width="204">Name</th><th>Description</th></tr></thead><tbody><tr><td>00</td><td>Success / Approved</td><td>Success / Approved Transaction</td></tr><tr><td>13</td><td>Invalid Amount</td><td>Amount is missing ( less than Rp 1 )</td></tr><tr><td>14</td><td>Invalid Mobile Number / OVO ID</td><td>Phone number / OVO ID not found in OVO System</td></tr><tr><td>17</td><td>Transaction Decline</td><td>OVO User canceled payment using OVO Apps</td></tr><tr><td>25</td><td>Transaction Not Found</td><td>Payment status not found when called by Check Payment Status API</td></tr><tr><td>26</td><td>Transaction Failed</td><td>Failed push payment confirmation to OVO Apps</td></tr><tr><td>40</td><td>Transaction Failed</td><td>General Error from OVO, please check to OVO</td></tr><tr><td>54</td><td>Transaction Expired (More than 7 days)</td><td>Transaction details already expired when API check payment status called</td></tr><tr><td>56</td><td>Card Blocked. Please call 1500696</td><td>Card is blocked, unable to process card transaction</td></tr><tr><td>58</td><td>Transaction Not Allowed</td><td>Transaction module not registered in OVO Systems</td></tr><tr><td>61</td><td>Exceed Transaction Limit</td><td>Transaction module not registered in OVO Systems</td></tr><tr><td>63</td><td>Secutiry Violation</td><td>Authentication Failed</td></tr><tr><td>64</td><td>Account Blocked. Please call 1500696</td><td>Account is blocked, unable to process transaction</td></tr><tr><td>65</td><td>Transaction Failed</td><td>Limit transaction exceeded, limit on count or amount</td></tr><tr><td>67</td><td>Below Transaction Limit</td><td>The transaction amount is less than the minimum payment</td></tr><tr><td>68</td><td>Transaction Pending / Timeout</td><td>OVO Wallet late to give respond to OVO JPOS</td></tr><tr><td>73</td><td>Transaction has been reversed</td><td>Transaction has been reversed by API Reversal Push to Pay in Check Payment Status API</td></tr><tr><td>94</td><td>Duplicate request params</td><td>Duplication on merchant invoice or reference number</td></tr><tr><td>96</td><td>Invalid Processing Code</td><td>Invalid Processing Code inputted during Call API Check Payment Status</td></tr><tr><td>ER</td><td>System Failure</td><td>There is an error in OVO Systems, Credentials not found in OVO Systems</td></tr><tr><td>EB</td><td>Terminal Blocked</td><td>TID and/or MID not registered in OVO Systems</td></tr><tr><td>TO</td><td>Timeout</td><td>Request has expired due to invalid usage of unix timestamp (5 minutes max.)</td></tr><tr><td>BR</td><td>Bad request</td><td>Incorrect JSON Format setup</td></tr><tr><td>BR</td><td>Invalid format request</td><td>Invalid store code, empty storecode, or invalid appsource</td></tr><tr><td>-</td><td>No response</td><td>User did not give any response within the remaining time to finish the transaction</td></tr></tbody></table>

### What's next?[​](https://dashboard.doku.com/docs/docs/jokul-direct/e-money/ovo-guide#whats-next) <a href="#whats-next" id="whats-next"></a>

You can test your payment through our Payment Simulator. Here is the steps to simulate the OVO payment:

1. Go to the [OVO Payment Simulator](https://sandbox.doku.com/integration/simulator/ovo/inquiry)
2. Copy one of the Active phone number on the OVO Payment Simulator to the `ovo_info.ovo_id` in your request body
3. Copy the `order.invoice_number` that you will be hitting and paste it to the OVO Payment Simulator
4. Hit the API and while the API is waiting for response, go to the OVO Payment Simulator
5. Click the Inquiry button and you should see the Payment details
6. Choose which payment you wish, OVO Cash or OVO Points
7. Click the Pay Now button
8. You should receive the API response

Learn more [here](https://dashboard.doku.com/docs/docs/technical-references/payment-testing).

[<br>](https://dashboard.doku.com/docs/docs/jokul-direct/e-money/doku-wallet-guide)


# LinkAja

DOKU has partnered with various e-money providers and one of them is Link Aja to provide E-Money Payment. Learn more about how DOKU can help you integrate with Link Aja here.

***

### Integration steps <a href="#integration-steps" id="integration-steps"></a>

Here is the overview of how to integrate with Link Aja:

1. Generate request
2. Complete payment in Link Aja App
3. Acknowledge payment result

#### Link Aja Sequence Diagram

<figure><img src="/files/qoIBLo8vZFE7OP0mH292" alt=""><figcaption></figcaption></figure>

***

#### 1. Generate Request <a href="#id-1-generate-request" id="id-1-generate-request"></a>

To generate request, you will need to hit this API through your Backend :

**API Request**

| Type                          | Value                                                                  |
| ----------------------------- | ---------------------------------------------------------------------- |
| **HTTP Method**               | POST                                                                   |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/linkaja-emoney/v2/ServiceRequestPayment` |
| **API endpoint (Production)** | `https://api.doku.com/linkaja-emoney/v2 /ServiceRequestPayment`        |

Here is the sample of request header to create an order:

```
Client-Id: OCO-0203-1676104296656
Request-Id: 24bb5232-3fe6-47a5-b0b0-d0fc3c6b5fdb
Request-Timestamp: 2023-06-08T08:50:00Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
```

#### Request Header Explanation

<table><thead><tr><th width="207">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong>Request-Id</strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong>Request-Timestamp</strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong>Signature</strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="/pages/9uXtc55i3bhjXaqAJZOx">this section</a> to generate the signature</td></tr></tbody></table>

Here is a sample of request body to create an order:

```json
{
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000,
        "callback_url": "https://merchant.com/return-url",
        "line_items": [
             {
               "name":" Roti",
               "price": 10000,
               "quantity": 1
             } 
        ]
    },
    "customer": {
            "name": "Jessica Tessalonika",
            "email": "example@doku.com",
            "phone" : "081112345678"
    },
    "additional_info": {
        "override_notification_url": "https://another.example.com/payments/notifications"
    }
}
```

**Request Body Explanation**

<table><thead><tr><th>Parameter</th><th width="97">Type</th><th width="125">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.invoice_number</code></td><td>string</td><td>Mandatory</td><td>Merchant's designated transaction invoice number<br>Allowed chars: <code>alphabetic, numeric, special chars</code></td></tr><tr><td><code>order.amount</code></td><td>number</td><td>Mandatory</td><td>Transaction amount<br>Allowed chars: <code>numeric</code></td></tr><tr><td><code>order.callback_url</code></td><td>string</td><td>Mandatory</td><td>Merchant URL that will redirected to after the order completed</td></tr><tr><td><code>order.line_items</code></td><td>string</td><td>Mandatory</td><td>Information about customer's basket (item's name, price, and quantities)</td></tr><tr><td><code>customer.name</code></td><td>string</td><td>Optional</td><td>Information about customer's name</td></tr><tr><td><code>customer.email</code></td><td>string</td><td>Optional</td><td>Information about customer's email</td></tr><tr><td><code>customer.phone</code></td><td>number</td><td>Optional</td><td>Information about customer's phone</td></tr><tr><td><code>additional_info.override_notification_url</code></td><td>string</td><td>Optional</td><td>This parameter is intended to override the configured Notification URL with another URL. Click <a href="/pages/LfaJBdkpBWDjF7mwEimR">here</a> for more information.</td></tr></tbody></table>

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

```
Client-Id: MCH-0001-10791114622547
Request-Id: 24bb5232-3fe6-47a5-b0b0-d0fc3c6b5fdb
Response-Timestamp: 2021-07-09T02:05:14Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

#### Response Header Explanation

<table><thead><tr><th width="207">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Same as the request</td></tr><tr><td><strong>Request-Id</strong></td><td>Same as the request</td></tr><tr><td><strong>Request-Timestamp</strong></td><td>Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU</td></tr><tr><td><strong>Signature</strong></td><td>Signature generated by DOKU based on the response body</td></tr></tbody></table>

Here is the sample of response body:

```json
{
"order": {
        "invoice_number": "LINKAJA23052595",
        "amount": "10000.00"
    },
    "emoney_configuration": {
        "identifier": [
            {
                "name": "TERMINAL_ID",
                "value": "e2etest"
            } 
        ]
    },
    "emoney_payment": {
        "redirect_method_http": "POST",
        "redirect_url_http": "https://api-uat.doku.com/doku/simulator/v1/linkaja/redirectPostToPost",
        "redirect_parameter": [
            {
                "name": "Message",
                "value": 
                "cXAwdzcvd3VEeDlRTzl0V1g1NGZyMmpQbFBPMDQxaHpyclNLazdlV09PTUZ1Z1lJaDlscjU1QmZNS2VPTTNiOGpFY3Mzbmp1dStqUjRWL3FaTGRsekVQWVF3YWRRUVQ2UzZsQkFRSzl2ek1zbERWQWtEY01EV0xpaTYrcnRYVUJmSkYvc0tXbGpRWXFCMHVMVHpKMXZTRSt2eTY5K2lOQ3k4aFdCTTBUc2ZGaTlYaWdQZ1JGZ2VjWTNaUlBNT0JCaTNnUzdhMitrNkRlY2hZMWh1R2xpQWtLMTlrLzIyWkxLWnNxQXZTU1VkdllqV0FmeGtqVTVzUjM3ZUIvSE9mag=="
            } 
        ],
        "status": "PENDING"
    },
    "additional_info": {
        "override_notification_url": "https://another.example.com/payments/notifications"
    }
}
```

#### Response Body Explanation <a href="#id-2-complete-payment-in-link-aja" id="id-2-complete-payment-in-link-aja"></a>

<table><thead><tr><th>Parameter</th><th width="97">Type</th><th width="125">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.invoice_number</code></td><td>string</td><td>Mandatory</td><td>Same as the request</td></tr><tr><td><code>order.amount</code></td><td>number</td><td>Mandatory</td><td>Same as the request</td></tr><tr><td>emoney_configuration.identifier</td><td>string</td><td>Mandatory</td><td>Merchant identifier by Link Aja<br>Max length: <code>15</code><br>Allowed chars: <code>alphabetic, numeric</code></td></tr><tr><td>emoney_payment.redirect_method_http</td><td>string</td><td>Mandatory</td><td>HTTP redirect method by Link Aja<br>Max length: <code>8</code><br>Allowed chars: <code>alphabetic, numeric</code></td></tr><tr><td>emoney_payment.redirect_url_http</td><td>string</td><td>Mandatory</td><td>Merchant's redirect URL</td></tr><tr><td>emoney_payment.status</td><td>string</td><td>Mandatory</td><td>Status of the create order request<br>Possible value: <code>PENDING</code>, <code>SUCCESS</code>.</td></tr><tr><td>emoney_payment.parameter</td><td>string</td><td>Mandatory</td><td>Custom message</td></tr><tr><td><code>additional_info.override_notification_url</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr></tbody></table>

#### 2. Complete Payment in Link Aja <a href="#id-2-complete-payment-in-link-aja" id="id-2-complete-payment-in-link-aja"></a>

After the customer completed the payment, they will be redirected to the defined redirect.url that you set on the API request.

#### 3. Acknowledge payment result <a href="#id-3-acknowledge-payment-result" id="id-3-acknowledge-payment-result"></a>

DOKU will send **HTTP Notification** to your defined `Notification URL`. Learn how to handle the notification from DOKU:

* [Handling DOKU HTTP Notification](/get-started-with-doku-api/notification/http-notification-sample-non-snap)

***


# Paylater

DOKU provides various payment channels. One of them is Paylater Providers which is growing very fast these days. By using this payment channels, your customer can complete the payment and pay the tranasction later.


# Akulaku

DOKU has partnered with various Paylater Providers and one of them is Akulaku to provide Buy Now Pay Later. Learn more about how DOKU can help you integrate with Akulaku here.

***

### Integration steps <a href="#integration-steps" id="integration-steps"></a>

Here is the overview of how to integrate with Akulaku:

1. Obtain `payment.url` by generating order
2. Display Akulaku payment page to customer
3. Acknowledge payment result

<figure><img src="/files/wnx6q1O4qc8rXvmgtllV" alt=""><figcaption><p>Akulaku</p></figcaption></figure>

***

#### 1. Obtain `payment.url` by generating order <a href="#id-1-obtain-paymenturl-by-generating-order" id="id-1-obtain-paymenturl-by-generating-order"></a>

To generate order, you will need to hit this API through your Backend:

**API Request**

| Type                          | Value                                                                 |
| ----------------------------- | --------------------------------------------------------------------- |
| **HTTP Method**               | POST                                                                  |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/akulaku-peer-to-peer/v2/generate-order` |
| **API endpoint (Production)** | `https://api.doku.com/akulaku-peer-to-peer/v2/generate-order`         |

Here is the sample of request header to generate order:

```
Client-Id: MCH-0001-10791114622547
Request-Id: baec7d95-f30a-4b78-b711-6ebe0ccdf50b
Request-Timestamp: 2021-07-07T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
```

Request Header Explanation

| Parameter             | Description                                                                                                                                                                                                                                                                                         |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client-Id**         | Client ID retrieved from DOKU Back Office                                                                                                                                                                                                                                                           |
| **Request-Id**        | Unique random string (max 128 characters) generated from merchant side to protect duplicate request                                                                                                                                                                                                 |
| **Request-Timestamp** | Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z                                       |
| **Signature**         | Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to [this section](https://dashboard.doku.com/docs/docs/technical-references/generate-signature) to generate the signature |

Here is the sample request body to generate order:

```json
{
    "order": {
        "invoice_number": "INV-20210707-0001",
        "amount": 90000,
        "line_items": [
            {
                "name": "T-Shirt Red",
                "price": 30000,
                "quantity": 2,
                "sku": "1002",
                "category": "Shirt"
            },
            {
                "name": "Polo Navy",
                "price": 30000,
                "quantity": 1,
                "sku": "1001",
                "category": "Shirt"
            }
        ],
        "callback_url": "https://merchant.com/return-url"
    },
    "payment": {
        "merchant_unique_reference": "MUR-20210707-0001"
    },
    "customer": {
        "id": "CUST-0001",
        "name": "Anton Budiman",
        "phone": "6285694566147",
        "address": "Menara Mulia Lantai 8",
        "city": "Jakarta Selatan",
        "state": "DKI Jakarta",
        "postcode": "120129"
    },
    "additional_info": {
        "override_notification_url": "https://another.example.com/payments/notifications"
    }
}
```

Request Body Explanation

| Parameter                                   | Type     | Mandatory | Description                                                                                                                                                                                                    |
| ------------------------------------------- | -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`                      | `string` | Mandatory | <p>Generated by merchant to identify the order and must unique per request<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code></p>                                |
| `order.amount`                              | `number` | Mandatory | <p>In IDR currency and without decimal<br>Allowed chars: <code>numeric</code><br>Max length: <code>12</code></p>                                                                                               |
| `order.line_items.name`                     | `string` | Mandatory | <p>Name of the product item<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>255</code></p>                                                                              |
| `order.line_items.price`                    | `number` | Mandatory | <p>Price of the product item. Total price and quantity must match with the <code>order.amount</code><br>Allowed chars: <code>numeric</code><br>Max Length: <code>12</code></p>                                 |
| `order.line_items.quantity`                 | `number` | Mandatory | <p>Quantity of the product item<br>Allowed chars: <code>numeric</code><br>Max Length: <code>4</code></p>                                                                                                       |
| `order.line_items.sku`                      | `string` | Mandatory | SKU of the item in this transaction                                                                                                                                                                            |
| `order.line_items.category`                 | `string` | Mandatory | Category of the item in this transaction                                                                                                                                                                       |
| `order.callback_url`                        | `string` | Mandatory | <p>Merchant URL that will redirected to after the order completed<br>Allowed chars: <code>alphabetic, numeric, special chars</code></p>                                                                        |
| `payment.merchant_unique_reference`         | `string` | Mandatory | <p>Unique reference number generated by merchant, can be same value as <code>order.invoice\_number</code><br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code></p> |
| `customer.id`                               | `string` | Mandatory | <p>Unique customer identifier generated by merchant<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>50</code></p>                                                       |
| `customer.name`                             | `string` | Mandatory | <p>Customer name that will be displayed on acquirer channel when do inquiry<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code></p>                               |
| `customer.phone`                            | `string` | Mandatory | <p>Customer phone number. Format: <code>{calling\_code}{phone\_number}</code>. Example: 6281122334455<br>Allowed chars: <code>numeric</code><br>Max Length: <code>16</code></p>                                |
| `customer.address`                          | `string` | Optional  | <p>Customer address<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>400</code></p>                                                                                      |
| `customer.city`                             | `string` | Optional  | <p>Customer city, (Please send the following object, even if the value is empty.)<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>64</code></p>                         |
| `customer.state`                            | `string` | Optional  | <p>Customer province, (Please send the following object, even if the value is empty.)<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>64</code></p>                     |
| `customer.postcode`                         | `number` | Optional  | <p>Customer postcode, (Please send the following object, even if the value is empty.)<br>Allowed chars: <code>numeric</code><br>Max Length: <code>64</code></p>                                                |
| `additional_info.override_notification_url` | `string` | Optional  | This parameter is intended to override the configured `Notification URL` with another URL. Click [here](/get-started-with-doku-api/notification/override-notification-url) for more information.               |

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

```
Client-Id: MCH-0001-10791114622547
Request-Id: baec7d95-f30a-4b78-b711-6ebe0ccdf50b
Response-Timestamp: 2021-07-07T08:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

Response Header Explanation

| Parameter              | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| **Client-Id**          | Same as the request                                           |
| **Request-Id**         | Same as the request                                           |
| **Response-Timestamp** | Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU |
| **Signature**          | Signature generated by DOKU based on the response body        |

Here is the sample of response body:

```json
{
    "order": {
        "invoice_number": "INV-20210707-0001",
        "amount": 90000
    },
    "payment": {
        "merchant_unique_reference": "MUR-20210707-0001",
        "url": "https://test-mall.akulaku.com/v2/openPay.html?appId=15006801&refNo=MCH%2D0022%2D2599139268305MUR%2D20210712%2D0010&sign=Gd4XpzDEaxse6aoMQzpFNIGCSednnBT5X2iF5P%2DkLswSJGFCndyCER8IfeWI7n3t4XrwNAEevO2x2wuwkN5sjw",
        "status": "PENDING",
        "identifier": [
            {
                "name": "ORDER_ID",
                "value": "1000035148"
            },
            {
                "name": "AKULAKU_UNIQUE_REFERENCE",
                "value": "MCH-0001-10791114622547MUR-20210707-0001"
            }
        ]
    },
    "additional_info": {
        "override_notification_url": "https://another.example.com/payments/notifications"
    }
}
```

Response Body Explanation

| Parameter                                   | Type     | Mandatory | Description                                                                                                                                                                                                                                                                                   |
| ------------------------------------------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`                      | `string` | Mandatory | Same as the request                                                                                                                                                                                                                                                                           |
| `order.amount`                              | `number` | Mandatory | Same as the request                                                                                                                                                                                                                                                                           |
| `payment.merchant_unique_reference`         | `string` | Mandatory | Same as the request                                                                                                                                                                                                                                                                           |
| `payment.url`                               | `string` | Mandatory | Akulaku payment page URL to display for the customer                                                                                                                                                                                                                                          |
| `payment.status`                            | `string` | Mandatory | <p>The current payment status<br>Possible value:<br><code>PENDING</code>: continue redirect the customer to <code>payment.url</code>.<br><code>FAILED</code>: Retry generate order with different <code>order.invoice\_number</code> and <code>payment.merchant\_unique\_reference</code></p> |
| `payment.identifier`                        | `array`  | Optional  | List of transaction identifier that coming from the acquiring. Merchant can save these data for reference                                                                                                                                                                                     |
| `additional_info.override_notification_url` | `string` | Optional  | Same as the request                                                                                                                                                                                                                                                                           |

#### 2. Display Akulaku payment page to customer <a href="#id-2-display-akulaku-payment-page-to-customer" id="id-2-display-akulaku-payment-page-to-customer"></a>

Once you have the `payment.url`, you can now display the payment page by redirecting your customer to the Akulaku payment page.

After the customer completed the payment, they will be redirected to the defined `order.callback_url` that you set on the API request.

***

#### 3. Acknowledge payment result <a href="#id-3-acknowledge-payment-result" id="id-3-acknowledge-payment-result"></a>

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`. Learn how to handle the notification from DOKU:

* [Handling DOKU HTTP Notification](/get-started-with-doku-api/notification/http-notification-sample-for-snap)

***

### Additional features <a href="#additional-features" id="additional-features"></a>

We provide various additional features to suited your needs. Learn more here.

#### Cancel Order <a href="#cancel-order" id="cancel-order"></a>

If you wish to cancel your order request, you can do that by hitting the API with `POST` method:

**API Request**

| Type                          | Value                                                         |
| ----------------------------- | ------------------------------------------------------------- |
| **HTTP Method**               | POST                                                          |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/akulaku-peer-to-peer/v2/cancel` |
| **API endpoint (Production)** | `https://api.doku.com/akulaku-peer-to-peer/v2/cancel`         |

Here is the sample of request header to Cancel Order:

```
Client-Id: MCH-0001-10791114622547
Request-Id: 2dc5985e-adaa-4f82-b126-b09e9006da14
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
```

Request Header Explanation

| Parameter             | Description                                                                                                                                                                                                                                                                                         |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client-Id**         | Client ID retrieved from DOKU Back Office                                                                                                                                                                                                                                                           |
| **Request-Id**        | Unique random string (max 128 characters) generated from merchant side to protect duplicate request                                                                                                                                                                                                 |
| **Request-Timestamp** | Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z                                       |
| **Signature**         | Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to [this section](https://dashboard.doku.com/docs/docs/technical-references/generate-signature) to generate the signature |

Here is the sample of request body to Cancel Order:

```json
{
    "order": {
        "invoice_number": "MINV20201231468"
    },
    "payment": {
        "merchant_unique_reference": "ABC0001",
        "identifier": [
        {
             "name": "AKULAKU_UNIQUE_REFERENCE",
             "value": "MCH-12345678ABC0001"
        },
        {
             "name": "ORDER_ID",
             "value": "893102"
        }
        ]
    }
}
```

Request Body Explanation

| Parameter                                     | Type     | Mandatory                       | Description                                                                                                              |
| --------------------------------------------- | -------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `order.invoice_number`                        | `string` | Same as the generate VA request |                                                                                                                          |
| `payment.merchant_unique_reference`           | `string` | Mandatory                       | Unique reference number of merchant's order. generated by merchant. Please note, this reference is `unique` per request. |
| `payment.identifier`                          | `object` | Optional                        | Key Value pairing data                                                                                                   |
| `payment.identifier.AKULAKU_UNIQUE_REFERENCE` | `string` | Optional                        | Get from generate order response body                                                                                    |
| `payment.identifier.ORDER_ID`                 | `string` | Optional                        | Get from generate order response body                                                                                    |

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

```
Client-Id: MCH-0001-10791114622547
Request-Id: 09e0defe-a071-45b3-9feb-ac134374628c
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

Response Header Explanation

| Parameter              | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| **Client-Id**          | Same as the request                                           |
| **Request-Id**         | Same as the request                                           |
| **Response-Timestamp** | Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU |
| **Signature**          | Signature generated by DOKU based on the response body        |

Here is the sample of response body:

```
{
    "order": {
        "invoice_number": "MINV20201231468",
        "amount": 100000
    },
    "payment": {
        "status": "CANCELLED",
        "date": "2020-08-11T08:50:02Z",
        "merchant_unique_reference": "ABC0001",
        "identifier": [
        {
             "name": "AKULAKU_UNIQUE_REFERENCE",
             "value": "MCH-12345678ABC0001"
        },
        {
             "name": "ORDER_ID",
             "value": "893102"
        }
        ]
    },
    "cancel": {
        "status": "SUCCESS",
        "date": "2020-08-11T08:50:02Z"
    },
    "error":{
        "message": "Order Not Found"
    }
}
```

Response Body Explanation

| Parameter                           | Type     | Mandatory | Description                                                                                                                                                                          |
| ----------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `order.invoice_number`              | `string` | Mandatory | Same as the request                                                                                                                                                                  |
| \`order.amount                      | `number` | Mandatory | Same as the request                                                                                                                                                                  |
| `payment.status`                    | `string` | Mandatory | <p>Status of the payment.<br><br>Possible Value:<br>1. <code>SUCCESS</code> = If Akulaku approved payment request<br>2. <code>FAILED</code> = If Akulaku reject payment request.</p> |
| `payment.date`                      | `string` | Mandatory | Date time of Akulaku will be expired with the format of `yyyyMMddHHmmss`. The expired date uses UTC+7 time. Use this to set the expiry order on merchant side                        |
| `payment.merchant_unique_reference` | `object` | Mandatory | Unique reference number of merchant's order. generated by merchant. Please note, this reference is `unique` per request.                                                             |
| `cancel.status`                     | `string` | Mandatory | <p>Status of Cancel.<br><br>Possible Value:<br>1. <code>SUCCESS</code> = If Cancellation success<br>2. <code>FAILED</code> = If Cancellation failed.</p>                             |
| `cancel.date`                       | `string` | Mandatory | Date time of Order Akulaku already cancel.                                                                                                                                           |

#### Refund Order <a href="#refund-order" id="refund-order"></a>

You can request refund using this API.

To request a refund, you will need to hit this API through your backend:

**API Request**

| Type                          | Value                                                         |
| ----------------------------- | ------------------------------------------------------------- |
| **HTTP Method**               | POST                                                          |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/akulaku-peer-to-peer/v2/refund` |
| **API endpoint (Production)** | `https://api.doku.com/akulaku-peer-to-peer/v2/refund`         |

Here is the sample of request header to generate payment URL:

```
Client-Id: MCH-0001-10791114622547
Request-Id: 6cc9f8b1-d83d-4c24-b853-a3223f43a744
Request-Timestamp: 2020-08-12T09:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

Request Header Explanation

| Parameter             | Description                                                                                                                                                                                                                                                                                         |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client-Id**         | Client ID retrieved from DOKU Back Office                                                                                                                                                                                                                                                           |
| **Request-Id**        | Unique random string (max 128 characters) generated from merchant side to protect duplicate request                                                                                                                                                                                                 |
| **Request-Timestamp** | Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z                                       |
| **Signature**         | Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to [this section](https://dashboard.doku.com/docs/docs/technical-references/generate-signature) to generate the signature |

Here is the sample request body to request a refund:

```json
{
   "order":{
      "invoice_number":"invoice-00000101123"
   },
   "payment":{
      "merchant_unique_reference":"REFUND-ABC-0001045",
      "identifier":[
         {
                "name": "ORDER_ID",
                "value": "1000043205"
            },
            {
                "name": "AKULAKU_UNIQUE_REFERENCE",
                "value": "MCH-0001-10791114622547REFUND-ABC-0001045"
            }
      ]
   },
   "refund":{
      "merchant_unique_reference":"XYZ-006456"
   }
}
```

Request Body Explanation

| Parameter                           | Type     | Mandatory | Description                                                                             |
| ----------------------------------- | -------- | --------- | --------------------------------------------------------------------------------------- |
| `order.invoice_number`              | `string` | Mandatory | Invoice number of the transaction that being refunded, same as the invoice when payment |
| `payment.merchant_unique_reference` | `string` | Mandatory | Same as the request                                                                     |
| `payment.identifier`                | `array`  | Mandatory | Key Value pairing data                                                                  |
| `refund.merchant_unique_reference`  | `string` | Mandatory | unique reference no of merchant’s order refund, generated by merchant (new)             |

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

Here is the sample response header:

```
Client-Id: MCH-0001-10791114622547
Request-Id: 6cc9f8b1-d83d-4c24-b853-a3223f43a744
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=1jap2tpgvWt83tG4J7IhEwUrwmMt71OaIk0oL0e6sPM=
```

Response Header Explanation

| Parameter              | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| **Client-Id**          | Same as the request                                           |
| **Request-Id**         | Same as the request                                           |
| **Response-Timestamp** | Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU |
| **Signature**          | Signature generated by DOKU based on the response body        |

Here is the sample of response body:

```json
{
    "order": {
        "invoice_number": "invoice-00000101123",
        "amount": 110000
    },
    "payment": {
        "date": "2021-12-27T05:47:39Z",
        "status": "REFUNDED",
        "merchant_unique_reference": "REFUND-ABC-0001045",
        "identifier": [
            {
                "name": "AKULAKU_UNIQUE_REFERENCE",
                "value": "MCH-0001-10791114622547REFUND-ABC-0001045"
            },
            {
                "name": "ORDER_ID",
                "value": "1000043205"
            }
        ]
    },
    "refund": {
        "date": "2021-12-27T05:57:06Z",
        "status": "SUCCESS",
        "merchant_unique_reference": "XYZ-006456",
        "identifier": [
            {
                "name": "AKULAKU_UNIQUE_REFERENCE",
                "value": "REF-MCH-0001-10791114622547XYZ-006456"
            }
        ]
    }
}
```

Response Body Explanation

| Parameter                           | Type     | Mandatory | Description                                                                                                                                                                                                                                                                      |
| ----------------------------------- | -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`              | `string` | Mandatory | Same as the request                                                                                                                                                                                                                                                              |
| `order.amount`                      | `number` | Mandatory | Same as the request                                                                                                                                                                                                                                                              |
| `payment.date`                      | `string` | Mandatory | Time Stamp response on UTC time in ISO8601 format                                                                                                                                                                                                                                |
| `payment.status`                    | `string` | Mandatory | <p>Status of the payment<br><br>a. <code>REFUNDED</code> = Refund request success / already request<br>b. <code>FAILED</code> = Transaction already failed<br>c. <code>CANCELED</code> = Transaction already canceled<br>d. <code>PENDING</code> = Transaction still pending</p> |
| `payment.merchant_unique_reference` | `string` | Mandatory | Same as the request payment                                                                                                                                                                                                                                                      |
| `payment.identifier`                | `array`  | Optional  | Key Value pairing data                                                                                                                                                                                                                                                           |
| `refund.date`                       | `string` | Mandatory | Time Stamp response on UTC time in ISO8601 format                                                                                                                                                                                                                                |
| `refund.status`                     | `string` | Mandatory | <p>Refund status<br>Possible value: <code>SUCCESS, FAILED</code></p>                                                                                                                                                                                                             |
| `refund.merchant_unique_reference`  | `string` | Optional  | Same as the request refund                                                                                                                                                                                                                                                       |
| `refund.identifier`                 | `array`  | Optional  | Key Value Pairing Data                                                                                                                                                                                                                                                           |

{% hint style="info" %}
**Refund Type**

Currently, Akulaku only accepts refund requests with Full Amount type.
{% endhint %}

***

#### Split Settlement <a href="#split-settlement" id="split-settlement"></a>

If you are a platform or a marketplace, you can use this feature to settle the funds to your sellers or partners programmatically, save many operational efforts.

* [Settlement](#split-settlement)


# Kredivo

DOKU has partenered with various Paylater Providers and one of them is Kredivo to provide Buy Now Pay Later. Learn more about how DOKU can help you integrate with Kredivo here.

***

#### Integration steps <a href="#integration-steps" id="integration-steps"></a>

Here is the overview of how to integrate with Kredivo :

1. Obtain `payment.url` by generating order
2. Display Kredivo payment page to customer
3. Acknowledge payment result

<figure><img src="/files/dghk3fCi8OQnAGqtebQl" alt=""><figcaption></figcaption></figure>

#### 1. Obtain `payment.url` by generating order <a href="#id-1-obtain-paymenturl-by-generating-order" id="id-1-obtain-paymenturl-by-generating-order"></a>

To generate order, you will need to hit this API through your Backend:

**API Request**

| Type                          | Value                                                                 |
| ----------------------------- | --------------------------------------------------------------------- |
| **HTTP Method**               | POST                                                                  |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/kredivo-peer-to-peer/v2/generate-order` |
| **API endpoint (Production)** | `https://api.doku.com/kredivo-peer-to-peer/v2/generate-order`         |

Here is the sample of request header to generate order:

```
Client-Id: MCH-0001-10791114622547
Request-Id: baec7d95-f30a-4b78-b711-6ebe0ccdf50b
Request-Timestamp: 2021-07-07T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
```

Request Header Explanation

| Parameter             | Description                                                                                                                                                                                                                                                                                         |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client-Id**         | Client ID retrieved from DOKU Back Office                                                                                                                                                                                                                                                           |
| **Request-Id**        | Unique random string (max 128 characters) generated from merchant side to protect duplicate request                                                                                                                                                                                                 |
| **Request-Timestamp** | Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z                                       |
| **Signature**         | Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to [this section](https://dashboard.doku.com/docs/docs/technical-references/generate-signature) to generate the signature |

Here is the sample request body to generate order:

```json
{
  "order": {
    "invoice_number": "Test-Devex-002-jesj123",
    "line_items": [
      {
        "name": "AyamA",
        "price": 30000,
        "quantity": 1,
        "id": "1008",
        "type": "ELECTRONIC",
        "url": "https://merchant.com/product_1002/a",
        "image_url": "https://merchant.com/product_1002/image/a",
        "parent_type": "SELLER",
        "parent_id": "SELLER01"
      },
      {
        "name": "AyamB",
        "price": 10000,
        "quantity": 4,
        "id": "1009",
        "type": "ELECTRONIC",
        "url": "https://merchant.com/product_1002/b",
        "image_url": "https://merchant.com/product_1002/image/b",
        "parent_type": "SELLER",
        "parent_id": "SELLER02"
      }
    ],
    "amount": 70000,
    "callback_url": "https://merchant.com/cancel-url",
    "callback_url_cancel": "https://merchant.com/cancel-url"
  },
  "peer_to_peer_info": {
    "expired_time": 60,
    "merchant_unique_reference": "MURQ001-Test-Devex002-jes-123"
  },
  "sellers": [
    {
      "id": "SELLER",
      "name": "Sunrise",
      "email": "sunrise@gmail.com",
      "url": "https://onlineshop/seller/sunrise",
      "address": {
        "first_name": "Irfan",
        "last_name": "Sutandro",
        "address": "Jalan Tentara Pelajar no 4",
        "city": "Jakarta Utara",
        "postal_code": "12960",
        "phone": "08123456789",
        "country_code": "IDN"
      }
    },
    {
      "id": "SELLERB",
      "name": "SunriseB",
      "email": "sunriseb@gmail.com",
      "url": "https://onlineshop/seller/sunriseb",
      "address": {
        "first_name": "IrfanB",
        "last_name": "SutandroB",
        "address": "Jalan Tentara Pelajar no 4B",
        "city": "Jakarta UtaraB",
        "postal_code": "129601",
        "phone": "081234567892902",
        "country_code": "IDN"
      }
    }
  ],
  "customer": {
    "first_name": "andreas",
    "last_name": "dharmawan",
    "phone": "081398154809",
    "email": "andreas@email.com"
  },
  "billing_address": {
    "first_name": "andreas",
    "last_name": "dharmawan",
    "address": "Jalan Teknologi Indonesia No. 25",
    "city": "Jakarta",
    "postal_code": "12960",
    "phone": "081513114262",
    "country_code": "IDN"
  },
  "shipping_address": {
    "first_name": "andreas",
    "last_name": "dharmawan",
    "address": "Jalan Teknologi Indonesia No.25",
    "city": "Jakarta",
    "postal_code": "12960",
    "phone": "081513114262",
    "country_code": "IDN"
  },
  "additional_info": {
    "override_notification_url": "https://another.example.com/payments/notifications"
  }
}
```

Request Body Explanation

| Parameter                                     | Type      | Mandatory | Description                                                                                                                                                                                      |
| --------------------------------------------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `order.invoice_number`                        | `string`  | Mandatory | <p>Generated by merchant to identify the order and must unique per request<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code></p>                  |
| `order.line_items.name`                       | `string`  | Mandatory | <p>Name of the product item<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>255</code></p>                                                                |
| `order.line_items.price`                      | `double`  | Mandatory | <p>Price of the product item. Total price and quantity must be match with the <code>order.amount</code><br>Allowed chars: <code>numeric</code><br>Max Length: <code>12</code></p>                |
| `order.line_items.quantity`                   | `integer` | Mandatory | <p>Quantity of the product item<br>Allowed chars: <code>numeric</code><br>Max Length: <code>4</code></p>                                                                                         |
| `order.line_items.id`                         | `string`  | Mandatory | Item ID No/SKU number on this transaction (new)                                                                                                                                                  |
| `order.line_items.type`                       | `string`  | Mandatory | Type / Category of the item in this transaction.                                                                                                                                                 |
| `order.line_items.url`                        | `string`  | Mandatory | URL to the product item on merchant site                                                                                                                                                         |
| `order.line_items.image_url`                  | `string`  | Optional  | URL to the product item image                                                                                                                                                                    |
| `order.line_items.parent_type`                | `string`  | Optional  | You can assign the fee to either SELLER or ITEM. If not specified, this will be tied to transaction level                                                                                        |
| `order.line_items.parent_id`                  | `string`  | Optional  | This is either the seller Id or item Id                                                                                                                                                          |
| `order.amount`                                | `double`  | Mandatory | <p>In IDR currency and without decimal<br>Allowed chars: <code>numeric</code><br>Max length: <code>12</code></p>                                                                                 |
| `order.callback_url`                          | `string`  | Mandatory | <p>Merchant URL that will redirected to after the order completed<br>Allowed chars: <code>alphabetic, numeric, special chars</code></p>                                                          |
| `order.callback_url_cancel`                   | `string`  | Optional  | <p>URI that the customer is sent to if the customer chooses to cancel the Kredivo payment before completion<br>Allowed chars: <code>alphabetic, numeric, special chars</code></p>                |
| `peer_to_peer_info.expired_time`              | `number`  | Optional  | <p>Order expiration time in minutes format<br>Allowed chars: <code>numeric</code><br>Maximum length: <code>5</code><br>Default value: <code>1440</code></p>                                      |
| `peer_to_peer_info.merchant_unique_reference` | `string`  | Mandatory | Unique reference number generated by merchant, used as order id in acquirer api.                                                                                                                 |
| `sellers.id`                                  | `string`  | Optional  | Seller's ID                                                                                                                                                                                      |
| `sellers.name`                                | `string`  | Optional  | Seller's name                                                                                                                                                                                    |
| `sellers.email`                               | `string`  | Optional  | Seller's email                                                                                                                                                                                   |
| `sellers.url`                                 | `string`  | Optional  | Seller's URL                                                                                                                                                                                     |
| `sellers.legal_id`                            | `string`  | Optional  | Seller's Legal ID ( KTP, SIM or Passport Number)                                                                                                                                                 |
| `sellers.address.first_name`                  | `string`  | Optional  | Seller's first name                                                                                                                                                                              |
| `sellers.address.last_name`                   | `number`  | Optional  | Seller's last name                                                                                                                                                                               |
| `sellers.address.address`                     | `string`  | Optional  | Seller's address                                                                                                                                                                                 |
| `sellers.address.city`                        | `string`  | Optional  | Seller's address city                                                                                                                                                                            |
| `sellers.address.postal_code`                 | `string`  | Optional  | Seller's address postal code.                                                                                                                                                                    |
| `sellers.address.phone`                       | `string`  | Optional  | Seller's phone                                                                                                                                                                                   |
| `sellers.address.country_code`                | `string`  | Optional  | Seller's country code. ISO 3166-1 alpha-3                                                                                                                                                        |
| `customer.first_name`                         | `string`  | Mandatory | <p>Customer's first name<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>255</code></p>                                                                   |
| `customer.last_name`                          | `string`  | Optional  | <p>Customer's last name<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>255</code></p>                                                                    |
| `customer.phone`                              | `string`  | Mandatory | <p>Customer phone number. Format: <code>{calling\_code}{phone\_number}</code>. Example: 6281122334455<br>Allowed chars: <code>numeric</code><br>Max Length: <code>16</code></p>                  |
| `customer.email`                              | `string`  | Mandatory | <p>Customer address<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>400</code></p>                                                                        |
| `billing_address.first_name`                  | `string`  | Optional  | Billing address of the customer/shopper. Customer's first name                                                                                                                                   |
| `billing_address.last_name`                   | `string`  | Optional  | Billing address of the customer/shopper. Customer's last name                                                                                                                                    |
| `billing_address.address`                     | `string`  | Optional  | Billing address of the customer/shopper. Customer's address                                                                                                                                      |
| `billing_address.city`                        | `string`  | Optional  | Billing address of the customer/shopper. Customer's city                                                                                                                                         |
| `billing_address.postal_code`                 | `string`  | Optional  | Billing address of the customer/shopper. Customer's postal code                                                                                                                                  |
| `billing_address.phone`                       | `string`  | Optional  | Billing address of the customer/shopper. Customer's phone                                                                                                                                        |
| `billing_address.country_code`                | `string`  | Optional  | Billing address of the customer/shopper. Customer's country code                                                                                                                                 |
| `shipping_address.first_name`                 | `string`  | Mandatory | Shipping address of the customer/shopper. Shipping is required for goods (excluding ticket/voucher). Customer's first name                                                                       |
| `shipping_address.last_name`                  | `number`  | Optional  | Shipping address of the customer/shopper. Customer's last name                                                                                                                                   |
| `shipping_address.address`                    | `string`  | Mandatory | Shipping address of the customer/shopper. Customer's address                                                                                                                                     |
| `shipping_address.city`                       | `number`  | Mandatory | Shipping address of the customer/shopper. Customer's city                                                                                                                                        |
| `shipping_address.postal_code`                | `string`  | Mandatory | Shipping address of the customer/shopper. Customer's postal code                                                                                                                                 |
| `shipping_address.phone`                      | `number`  | Mandatory | Shipping address of the customer/shopper. Customer's phone                                                                                                                                       |
| `shipping_address.country_code`               | `string`  | Mandatory | Shipping address of the customer/shopper. Customer's country code                                                                                                                                |
| `additional_info.override_notification_url`   | `string`  | Optional  | This parameter is intended to override the configured `Notification URL` with another URL. Click [here](/get-started-with-doku-api/notification/override-notification-url) for more information. |

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

```
Client-Id: MCH-0001-10791114622547
Request-Id: baec7d95-f30a-4b78-b711-6ebe0ccdf50b
Response-Timestamp: 2021-07-07T08:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

Response Header Explanation

| Parameter              | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| **Client-Id**          | Same as the request                                           |
| **Request-Id**         | Same as the request                                           |
| **Response-Timestamp** | Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU |
| **Signature**          | Signature generated by DOKU based on the response body        |

Here is the sample of response body:

```json
{
    "order": {
        "amount": 70000,
        "invoice_number": "Test-Devex-002-jesj123"
    },
    "payment": {
        "status": "PENDING",
        "url": "https://pay-sandbox.kredivo.com/signIn?tk=d8e9f2a5-7abb-4696-9872-963b15c1c937"
    },
    "peer_to_peer_info": {
        "identifier": [
            {
                "value": "05521636616142675MURQ001-Test-Devex002-jes-123",
                "name": "KREDIVO_ORDER_ID"
            }
        ],
        "created_date": "20220328120315",
        "expired_date": "20220328130315",
        "created_date_utc": "2022-03-28T12:03:15Z",
        "expired_date_utc": "2022-03-28T13:03:15Z",
        "merchant_unique_reference": "MURQ001-Test-Devex002-jes-123"
    },
    "additional_info": {
        "override_notification_url": "https://another.example.com/payments/notifications"
    }
}
```

Response Body Explanation

| Parameter                                     | Type     | Mandatory   | Description                                                                                                                                                                                                                                                                                   |
| --------------------------------------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`                        | `string` | Mandatory   | Same as the request                                                                                                                                                                                                                                                                           |
| `order.amount`                                | `number` | Mandatory   | Same as the request                                                                                                                                                                                                                                                                           |
| `payment.status`                              | `string` | Mandatory   | <p>The current payment status<br>Possible value:<br><code>PENDING</code>: continue redirect the customer to <code>payment.url</code>.<br><code>FAILED</code>: Retry generate order with different <code>order.invoice\_number</code> and <code>payment.merchant\_unique\_reference</code></p> |
| `payment.url`                                 | `string` | Optional    | Kredivo payment page URL to display for the customer                                                                                                                                                                                                                                          |
| `peer_to_peer_info.identifier`                | `object` | Optional    | List of transaction identifier that coming from the acquiring. Merchant can save these data for reference                                                                                                                                                                                     |
| `peer_to_peer_info.created_date`              | `string` | Conditional | Date time of URL generated with the format of yyyyMMddHHmmss.                                                                                                                                                                                                                                 |
| `peer_to_peer_info.expired_date`              | `string` | Conditional | Date time of URL EXPIRED with the format of yyyyMMddHHmmss.                                                                                                                                                                                                                                   |
| `peer_to_peer_info.created_date_utc`          | `string` | Conditional | Date time of URL generated with the format of yyyyMMddHHmmss. The generated date uses UTC+7 time.                                                                                                                                                                                             |
| `peer_to_peer_info.expired_date_utc`          | `string` | Conditional | Date time of URL will be expired in UTC. Use this to set the expiry order on merchant side                                                                                                                                                                                                    |
| `peer_to_peer_info.merchant_unique_reference` | `string` | Conditional | Same as the request                                                                                                                                                                                                                                                                           |
| `additional_info.override_notification_url`   | `string` | Optional    | Same as the request                                                                                                                                                                                                                                                                           |

#### 2. Display Kredivo payment page to customer <a href="#id-2-display-kredivo-payment-page-to-customer" id="id-2-display-kredivo-payment-page-to-customer"></a>

Once you have the `payment.url`, you can now display the payment page by redirecting your customer to the Kredivo payment page.

After the customer completed the payment, they will be redirected to the defined `order.callback_url` that you set on the API request.

***

#### 3. Acknowledge payment result <a href="#id-3-acknowledge-payment-result" id="id-3-acknowledge-payment-result"></a>

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`. Learn how to handle the notification from DOKU:

* [Handling DOKU HTTP Notification](/get-started-with-doku-api/notification/http-notification-sample-for-snap)

***


# Indodana

DOKU has partenered with various Paylater Providers and one of them is Indodana to provide Buy Now Pay Later. Learn more about how DOKU can help you integrate with Indodana here.

***

### Integration steps <a href="#integration-steps" id="integration-steps"></a>

Here is the overview of how to integrate with Indodana:

1. Obtain `payment.url` by generating order
2. Display Indodana payment page to customer
3. Acknowledge payment result

<figure><img src="/files/o9ZvaugNvqXZRmuYmx6A" alt=""><figcaption></figcaption></figure>

***

#### 1. Obtain `payment.url` by generating order <a href="#id-1-obtain-paymenturl-by-generating-order" id="id-1-obtain-paymenturl-by-generating-order"></a>

## Generate Order / Obtain payment.url

> Creates an order and generates the payment page URL for Indodana Paylater. Merchants redirect customers to this URL to complete the payment.

```json
{"openapi":"3.0.3","info":{"title":"DOKU Indodana Paylater API","version":"2.0.0"},"servers":[{"url":"https://api-sandbox.doku.com","description":"Sandbox Environment"},{"url":"https://api.doku.com","description":"Production Environment"}],"paths":{"/indodana-peer-to-peer/v2/generate-order":{"post":{"summary":"Generate Order / Obtain payment.url","description":"Creates an order and generates the payment page URL for Indodana Paylater. Merchants redirect customers to this URL to complete the payment.","operationId":"generateOrder","parameters":[{"name":"Client-Id","in":"header","required":true,"schema":{"type":"string"},"description":"Client ID retrieved from DOKU Back Office"},{"name":"Request-Id","in":"header","required":true,"schema":{"type":"string"},"description":"Unique random string (max 128 characters) generated from merchant side to protect duplicate request"},{"name":"Request-Timestamp","in":"header","required":true,"schema":{"type":"string","format":"date-time"},"description":"Timestamp request on UTC time in ISO8601 UTC+0 format (e.g. yyyy-MM-ddTHH:mm:ssZ)"},{"name":"Signature","in":"header","required":true,"schema":{"type":"string"},"description":"HMAC-SHA256 signature generated using Merchant Client Secret"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateOrderRequest"}}}},"responses":{"200":{"description":"SUCCESS","headers":{"Client-Id":{"schema":{"type":"string"},"description":"Same as the request"},"Request-Id":{"schema":{"type":"string"},"description":"Same as the request"},"Response-Timestamp":{"schema":{"type":"string","format":"date-time"},"description":"Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU"},"Signature":{"schema":{"type":"string"},"description":"Signature generated by DOKU based on the response body"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateOrderResponse"}}}}}}}},"components":{"schemas":{"GenerateOrderRequest":{"type":"object","required":["order","peer_to_peer_info","customer","billing_address"],"properties":{"order":{"$ref":"#/components/schemas/OrderRequest"},"peer_to_peer_info":{"$ref":"#/components/schemas/PeerToPeerInfoRequest"},"customer":{"$ref":"#/components/schemas/Customer"},"billing_address":{"$ref":"#/components/schemas/Address"},"shipping_address":{"$ref":"#/components/schemas/Address"},"additional_info":{"$ref":"#/components/schemas/AdditionalInfo"}}},"OrderRequest":{"type":"object","required":["invoice_number","amount","line_items","callback_url_cancel"],"properties":{"invoice_number":{"type":"string","maxLength":64,"description":"Generated by merchant to identify the order and must be unique per request. Allowed chars: alphabetic, numeric, special chars."},"amount":{"type":"integer","description":"In IDR currency and without decimal. Allowed chars: numeric. Max length: 16."},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"callback_url":{"type":"string","maxLength":256,"description":"Merchant URL that the customer will be redirected to after the order is completed."},"callback_url_cancel":{"type":"string","maxLength":256,"description":"Merchant URL that the customer will be redirected to if the order is cancelled."}}},"LineItem":{"type":"object","required":["name","price","quantity","id","category"],"properties":{"name":{"type":"string","maxLength":128,"description":"Name of the product item."},"price":{"type":"number","description":"Price of the product item. Total price and quantity must match with the order.amount. Max length 16.2."},"quantity":{"type":"integer","description":"Quantity of the product item. Max length 8."},"id":{"type":"string","maxLength":64,"description":"SKU/item ID of the item in this transaction."},"category":{"type":"string","description":"Category of the item in this transaction.","enum":["airlines","arts-crafts-and-collectibles","automotive","baby","beauty-and-fragrances","biller","books-and-magazines","business-to-business-including-mlm","charity-and-non-profit","clothing","community","digital-content","electronics-and-telecom","entertainment-and-media","financial-services-and-products","financial-services-and-technology","food-and-beverage","food-retail-and-service","games-voucher","gifts-and-flowers","government","health-and-personal-care","home-and-garden","hotel-and-travel","insurance","marketplace","nonprofit","offline-store","others","over-the-air","overseas","pets-and-animals","property","public-services","religion-and-spirituality","retail","services","sports-and-outdoors","telco","ticketing","toys-and-hobbies","transportation","travel","vehicle-sales","vehicles-service-and-accessories"]},"url":{"type":"string","maxLength":256,"description":"URL of the product in the merchant site/platform."},"image_url":{"type":"string","maxLength":256,"description":"URL of the image of the product in the merchant site/platform."},"type":{"type":"string","description":"Type of the item in this transaction."}}},"PeerToPeerInfoRequest":{"type":"object","required":["merchant_unique_reference"],"properties":{"expired_time":{"type":"integer","description":"Order expired time in minutes. Max length: 5."},"merchant_unique_reference":{"type":"string","description":"Unique reference number generated by merchant."}}},"Customer":{"type":"object","required":["first_name","email","phone"],"properties":{"first_name":{"type":"string","maxLength":16,"description":"Customer first name."},"last_name":{"type":"string","maxLength":16,"description":"Customer last name."},"email":{"type":"string","format":"email","description":"Customer email address."},"phone":{"type":"string","maxLength":16,"description":"Customer phone number. Format: {calling_code}{phone_number} without '+' prefix. Example: 6281122334455"}}},"Address":{"type":"object","required":["first_name","address","city","postal_code","phone","country_code"],"properties":{"first_name":{"type":"string","description":"Address first name."},"last_name":{"type":"string","description":"Address last name."},"address":{"type":"string","description":"Address details of the customer/shopper."},"city":{"type":"string","description":"City of the address."},"postal_code":{"type":"string","description":"Postal code of the address."},"phone":{"type":"string","description":"Phone number for the address."},"country_code":{"type":"string","description":"Three-letter ISO country code (e.g., IDN)."}}},"AdditionalInfo":{"type":"object","properties":{"override_notification_url":{"type":"string","format":"uri","description":"This parameter overrides the default Notification URL configured in DOKU Back Office."}}},"GenerateOrderResponse":{"type":"object","required":["order","payment","peer_to_peer_info"],"properties":{"order":{"type":"object","required":["amount","invoice_number"],"properties":{"amount":{"type":"integer","description":"Same as the request."},"invoice_number":{"type":"string","description":"Same as the request."}}},"payment":{"type":"object","required":["status","url"],"properties":{"status":{"type":"string","enum":["PENDING","FAILED"],"description":"The current payment status."},"url":{"type":"string","format":"uri","description":"Indodana payment page URL to display to the customer."}}},"peer_to_peer_info":{"$ref":"#/components/schemas/PeerToPeerInfoResponse"},"additional_info":{"$ref":"#/components/schemas/AdditionalInfo"}}},"PeerToPeerInfoResponse":{"type":"object","required":["merchant_unique_reference"],"properties":{"identifier":{"type":"array","description":"List of transaction identifiers coming from acquiring. Merchant can save these for reference.","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"merchant_unique_reference":{"type":"string","description":"Same as the request."},"created_date":{"type":"string","description":"Date time of Indodana order generation with the format yyyyMMddHHmmss."},"expired_date":{"type":"string","description":"Date time of Indodana order expiration with the format yyyyMMddHHmmss."},"created_date_utc":{"type":"string","format":"date-time","description":"Date time of Indodana order generation in UTC format."},"expired_date_utc":{"type":"string","format":"date-time","description":"Date time of Indodana order expiration in UTC format."}}}}}}
```

#### 2. Display Indodana payment page to customer <a href="#id-2-display-indodana-payment-page-to-customer" id="id-2-display-indodana-payment-page-to-customer"></a>

Once you have the `payment.url`, you can now display the payment page by redirecting your customer to the Indodana payment page.

After the customer completed the payment, they will be redirected to the defined `order.callback_url` that you set on the API request.

***

#### 3. Acknowledge payment result <a href="#id-3-acknowledge-payment-result" id="id-3-acknowledge-payment-result"></a>

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`. Learn how to handle the notification from DOKU:

* [Handling DOKU HTTP Notification](/get-started-with-doku-api/notification/http-notification-sample-for-snap)

***

### Additional features <a href="#additional-features" id="additional-features"></a>

We provide various additional features to suited your needs. Learn more here.

## Refund Order / Void Transaction

> Refunds a transaction that has been completed using Indodana Paylater.

```json
{"openapi":"3.0.3","info":{"title":"DOKU Indodana Paylater API","version":"2.0.0"},"servers":[{"url":"https://api-sandbox.doku.com","description":"Sandbox Environment"},{"url":"https://api.doku.com","description":"Production Environment"}],"paths":{"/indodana-peer-to-peer/v2/refund":{"post":{"summary":"Refund Order / Void Transaction","description":"Refunds a transaction that has been completed using Indodana Paylater.","operationId":"refundOrder","parameters":[{"name":"Client-Id","in":"header","required":true,"schema":{"type":"string"},"description":"Client ID retrieved from DOKU Back Office"},{"name":"Request-Id","in":"header","required":true,"schema":{"type":"string"},"description":"Unique random string (max 128 characters) generated from merchant side to protect duplicate request"},{"name":"Request-Timestamp","in":"header","required":true,"schema":{"type":"string","format":"date-time"},"description":"Timestamp request on UTC time in ISO8601 UTC+0 format"},{"name":"Signature","in":"header","required":true,"schema":{"type":"string"},"description":"HMAC-SHA256 signature generated using Merchant Client Secret"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}}}},"responses":{"200":{"description":"SUCCESS","headers":{"Client-Id":{"schema":{"type":"string"},"description":"Same as the request"},"Request-Id":{"schema":{"type":"string"},"description":"Same as the request"},"Response-Timestamp":{"schema":{"type":"string","format":"date-time"},"description":"Response timestamp in ISO 8601 format"},"Signature":{"schema":{"type":"string"},"description":"HMAC SHA256 signature for response authentication"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundResponse"}}}}}}}},"components":{"schemas":{"RefundRequest":{"type":"object","required":["order","peer_to_peer_info","payment","refund"],"properties":{"order":{"type":"object","required":["invoice_number"],"properties":{"invoice_number":{"type":"string","description":"The invoice number of the order to refund."}}},"peer_to_peer_info":{"type":"object","required":["merchant_unique_reference","identifier"],"properties":{"merchant_unique_reference":{"type":"string","description":"The unique reference number of the original order generated by the merchant."},"identifier":{"type":"array","items":{"$ref":"#/components/schemas/Identifier"}}}},"payment":{"type":"object","required":["identifier"],"properties":{"identifier":{"type":"array","items":{"$ref":"#/components/schemas/Identifier"}}}},"refund":{"type":"object","required":["merchant_unique_reference","amount","reason","cancelled_by"],"properties":{"merchant_unique_reference":{"type":"string","description":"A unique reference number generated by the merchant for this refund request."},"amount":{"type":"integer","description":"The refund amount."},"reason":{"type":"string","description":"The reason for the refund."},"cancelled_by":{"type":"string","description":"Name of the person/role requesting the refund."}}}}},"Identifier":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string","description":"Identifier key name."},"value":{"type":"string","description":"Identifier value."}}},"RefundResponse":{"type":"object","required":["order","payment","refund","transaction","peer_to_peer_info"],"properties":{"order":{"type":"object","required":["amount","invoice_number"],"properties":{"amount":{"type":"integer","description":"Refunded amount."},"invoice_number":{"type":"string","description":"Invoice number of the order."}}},"payment":{"type":"object","required":["status","identifier"],"properties":{"status":{"type":"string","description":"Payment refund status."},"identifier":{"type":"array","items":{"$ref":"#/components/schemas/Identifier"}}}},"refund":{"type":"object","required":["status","amount","reason","identifier","merchant_unique_reference","cancelled_by"],"properties":{"status":{"type":"string","description":"Status of the refund request."},"amount":{"type":"integer","description":"Refunded amount."},"reason":{"type":"string","description":"Reason for the refund."},"identifier":{"type":"array","items":{"$ref":"#/components/schemas/Identifier"}},"merchant_unique_reference":{"type":"string","description":"Refund unique reference."},"cancelled_by":{"type":"string","description":"Name of the person/role requesting the refund."}}},"transaction":{"type":"object","required":["status","date","original_request_id"],"properties":{"status":{"type":"string","description":"Transaction status."},"date":{"type":"string","format":"date-time","description":"Timestamp of the transaction update."},"original_request_id":{"type":"string","description":"Request ID of the original transaction."}}},"peer_to_peer_info":{"type":"object","required":["status","identifier","merchant_unique_reference"],"properties":{"status":{"type":"string","description":"P2P status."},"identifier":{"type":"array","items":{"$ref":"#/components/schemas/Identifier"}},"merchant_unique_reference":{"type":"string","description":"P2P unique reference."}}}}}}}}
```

#### Split Settlement <a href="#split-settlement" id="split-settlement"></a>

If you are a platform or a marketplace, you can use this feature to settle the funds to your sellers or partners programmatically, save many operational efforts.

* [Settlement](#split-settlement)


# Digital Banking

DOKU provides various payment channels. One of them is Digital Banking which is growing very fast these days.


# Jenius Pay

DOKU has partenered with various Internet Banking and one of them is Jenius Pay. Learn more about how DOKU can help you integrate with Jenius Pay here.

***

### Integration steps <a href="#integration-steps" id="integration-steps"></a>

Here is the overview of how to integrate with Jenius pay :

1. Generate request
2. Complete Payment in Jenius App
3. Acknowledge payment result

<figure><img src="/files/MHYAYipyObxHHCBcaXtS" alt=""><figcaption><p>Jenius Pay</p></figcaption></figure>

***

#### 1. Generate request <a href="#id-1-generate-request" id="id-1-generate-request"></a>

To generate request, you will need to hit this API through your Backend:

**API Request**

| Type                          | Value                                                                          |
| ----------------------------- | ------------------------------------------------------------------------------ |
| **HTTP Method**               | POST                                                                           |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/jenius-digital-banking/v2/ServiceRequestPayment` |
| **API endpoint (Production)** | `https://api.doku.com/jenius-digital-banking/v2/ServiceRequestPayment`         |

Here is the sample of request header to generate order:

```
Client-Id: MCH-0001-10791114622547
Request-Id: baec7d95-f30a-4b78-b711-6ebe0ccdf50b
Request-Timestamp: 2021-07-07T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
```

Request Header Explanation

| Parameter             | Description                                                                                                                                                                                                                                                                                         |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client-Id**         | Client ID retrieved from DOKU Back Office                                                                                                                                                                                                                                                           |
| **Request-Id**        | Unique random string (max 128 characters) generated from merchant side to protect duplicate request                                                                                                                                                                                                 |
| **Request-Timestamp** | Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z                                       |
| **Signature**         | Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to [this section](https://dashboard.doku.com/docs/docs/technical-references/generate-signature) to generate the signature |

Here is the sample request body to generate order:

```json
{
"order": {
        "invoice_number": "DOKU202212345828",
        "amount": "50000",
        "line_items": [
            {
                "name": "Ayam",
                "price": 40000,
                "quantity": 1
            },
            {
                "name": "Roti",
                "price": 10000,
                "quantity": 1
            }
        ]
    },
    "additional_info": {
        "override_notification_url": "https://another.example.com/payments/notifications"
    },
    "customer": {
        "name": "Astari",
        "email": "Astari@doku.com",
        "phone": "081288910205"
    },
    "redirect_url": "https://test.com/redirect",
    "jenius_info": {
        "cash_tag": "$admin"
    }
}
```

Request Body Explanation

| Parameter                                   | Type     | Mandatory | Description                                                                                                                                                                                                   |
| ------------------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`                      | `string` | Mandatory | <p>Generated by merchant to identify the order and must unique per request. Must be same with Request-ID<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code></p> |
| `order.amount`                              | `string` | Mandatory | <p>In IDR currency and without decimal<br>Allowed chars: <code>numeric</code><br>Max length: <code>12</code></p>                                                                                              |
| `order.line_items.name`                     | `string` | Mandatory | <p>Name of the product item<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>255</code></p>                                                                             |
| `order.line_items.price`                    | `number` | Mandatory | <p>Price of the product item. Total price and quantity must match with the <code>order.amount</code><br>Allowed chars: <code>numeric</code><br>Max Length: <code>12</code></p>                                |
| `order.line_items.quantity`                 | `number` | Mandatory | <p>Quantity of the product item<br>Allowed chars: <code>numeric</code><br>Max Length: <code>4</code></p>                                                                                                      |
| `additional_info.override_notification_url` | `string` | Optional  | This parameter is intended to override the configured `Notification URL` with another URL. Click [here](/get-started-with-doku-api/notification/override-notification-url) for more information.              |
| `customer.name`                             | `string` | Mandatory | <p>Customer name that will be displayed on acquirer channel when do inquiry<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code></p>                              |
| `customer.phone`                            | `string` | Mandatory | <p>Customer phone number. Format: <code>{calling\_code}{phone\_number}</code>. Example: 6281122334455<br>Allowed chars: <code>numeric</code><br>Max Length: <code>16</code></p>                               |
| `customer.email`                            | `string` | Optional  | <p>Customer address<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>400</code></p>                                                                                     |
| `redirect_url`                              | `string` | Mandatory | <p>Merchant URL that will redirected to after the order completed<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>512</code></p>                                       |
| `jenius_info.cash_tag`                      | `string` | Mandatory | <p>Unique identifier for customer to pay<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max Length: <code>30</code></p>                                                                 |

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

```
Client-Id: MCH-0001-10791114622547
Request-Id: baec7d95-f30a-4b78-b711-6ebe0ccdf50b
Response-Timestamp: 2021-07-07T08:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

Response Header Explanation

| Parameter              | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| **Client-Id**          | Same as the request                                           |
| **Request-Id**         | Same as the request                                           |
| **Response-Timestamp** | Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU |
| **Signature**          | Signature generated by DOKU based on the response body        |

Here is the sample of response body:

```json
{
    "order": {
        "invoice_number": "DOKU202212345828",
        "amount": "50000"
    },
    "internet_banking_payment": {
        "status": "SUCCESS"
    },
    "additional_info": {
        "override_notification_url": "https://another.example.com/payments/notifications"
    }
}
```

Response Body Explanation

| Parameter                                   | Type     | Mandatory | Description                                                                                 |
| ------------------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------- |
| `order.invoice_number`                      | `string` | Mandatory | Same as the request                                                                         |
| `order.amount`                              | `string` | Mandatory | Same as the request                                                                         |
| `internet_banking_payment.status`           | `string` | Mandatory | <p>Transaction Status.<br>Possible Value: <code>Pending, Success, Failed, Refund</code></p> |
| `additional_info.override_notification_url` | `string` | Optional  | Same as the request                                                                         |

#### 2. Complete Payment in Jenius App <a href="#id-2-complete-payment-in-jenius-app" id="id-2-complete-payment-in-jenius-app"></a>

After the customer completed the payment, they will be redirected to the defined `redirect.url` that you set on the API request.

***

#### 3. Acknowledge payment result <a href="#id-3-acknowledge-payment-result" id="id-3-acknowledge-payment-result"></a>

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`. Learn how to handle the notification from DOKU:

* [Handling DOKU HTTP Notification](/get-started-with-doku-api/notification/http-notification-sample-for-snap)

***

### Additional features <a href="#additional-features" id="additional-features"></a>

We provide various additional features to suited your needs. Learn more here.

#### Refund Order <a href="#refund-order" id="refund-order"></a>

If you wish to refund your order request, you can do that by hitting the API with `POST` method:

**API Request**

| Type                          | Value                                                                         |
| ----------------------------- | ----------------------------------------------------------------------------- |
| **HTTP Method**               | POST                                                                          |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/jenius-digital-banking/v2/ServiceRequestRefund` |
| **API endpoint (Production)** | `https://api.doku.com/jenius-digital-banking/v2/ServiceRequestRefund`         |

Here is the sample of request header to Refund Order:

```
Client-Id: MCH-0001-10791114622547
Request-Id: 2dc5985e-adaa-4f82-b126-b09e9006da14
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
```

Request Header Explanation

| Parameter             | Description                                                                                                                                                                                                                                                                                         |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client-Id**         | Client ID retrieved from DOKU Back Office                                                                                                                                                                                                                                                           |
| **Request-Id**        | Unique random string (max 128 characters) generated from merchant side to protect duplicate request                                                                                                                                                                                                 |
| **Request-Timestamp** | Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z                                       |
| **Signature**         | Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to [this section](https://dashboard.doku.com/docs/docs/technical-references/generate-signature) to generate the signature |

Here is the sample of request body to Refund Order:

```
{
    "order": {
        "invoice_number": "DOKU22022062000",
        "amount": "61000",
        "reason": "Cancel Order"
    }
}
```

Request Body Explanation

| Parameter              | Type     | Mandatory                    | Description     |
| ---------------------- | -------- | ---------------------------- | --------------- |
| `order.invoice_number` | `string` | Same as the generate request |                 |
| `order.amount`         | `string` | Same as the generate request |                 |
| `reason`               | `string` | Mandatory                    | Refund's Reason |

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

```
Client-Id: MCH-0001-10791114622547
Request-Id: 09e0defe-a071-45b3-9feb-ac134374628c
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

Response Header Explanation

| Parameter              | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| **Client-Id**          | Same as the request                                           |
| **Request-Id**         | Same as the request                                           |
| **Response-Timestamp** | Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU |
| **Signature**          | Signature generated by DOKU based on the response body        |

Here is the sample of response body:

```
{
    "order": {
        "invoice_number": "DOKU202212345828",
        "amount": "61000"
    },
    "internet_banking_payment": {
        "status": "SUCCESS"
    }
}
```

Response Body Explanation

| Parameter                         | Type     | Mandatory | Description                                                                                                                                                                            |
| --------------------------------- | -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.invoice_number`            | `string` | Mandatory | Same as the request                                                                                                                                                                    |
| \`order.amount                    | `string` | Mandatory | Same as the request                                                                                                                                                                    |
| `internet_banking_payment.status` | `string` | Mandatory | <p>Status of the refund.<br><br>Possible Value:<br>1. <code>SUCCESS</code> = If Jenius Pay approved refund request<br>2. <code>FAILED</code> = If Jenius Pay reject refund request</p> |

#### Split Settlement <a href="#doku-fin---split-settlement" id="doku-fin---split-settlement"></a>

If you are a platform or a marketplace, you can use this feature to settle the funds to your sellers or partners programmatically, save many operational efforts.

* [Settlement](#doku-fin---split-settlement)


# Convenience Store

DOKU provides various payment channels. One of the most used by our merchants is Online to Offline. By using this payment channels, your customer can pay their order through offline counters and DOKU will notify you once the payment is completed by your customer. DOKU has partnered with various partners to help you provide many payment options for your customers.

### Partnerships Model <a href="#partnerships-model" id="partnerships-model"></a>

Each user may have different needs for the business and the way they receive funds. DOKU has 2 types of models for accepting payments, namely the Aggregator Model and the Direct Model. For full details, you can check the details here.

The following is a list of models in receiving your funds for each bank via Online to Offline.

| Name      | Aggregator | Direct |
| --------- | ---------- | ------ |
| Alfa O2O  | ✅          | ✅      |
| Indomaret | ❌          | ✅      |

***

### Features for Online to Offline <a href="#features-for-online-to-offline" id="features-for-online-to-offline"></a>

**Payment Code Component**

{% hint style="info" %}
**PAYMENT CODE COMPONENT**&#x20;

Payment Code which is displayed to customer, contains two parts.\
**The first part** is the company code (BIN) and **the second part** is unique payment code.
{% endhint %}

There are 2 types of general features that can be used with Online to Offline:

1. **Register**: The payment code will be registered to DOKU and Acquirer will inquiry to our side when the customer make payment at the acquirer channel (Alfa Group, etc.)

| Features Type                          | Description                                                                                                                                                                                                                                               |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DOKU Generated Payment Code (DGPC)     | <p>Merchants don’t need to generate payment code, just need to request from DOKU and DOKU will send a unique payment code.<br>Component Payment Code : <code>BIN</code> and <code>Unique payment code</code>. Suitable for e-commerce business model.</p> |
| Merchant Generated Payment Code (MGPC) | <p>Merchants can generate payment codes with their own rules, and send the code to DOKU and customers will use it for payment.<br>Component Payment Code : <code>BIN</code> and <code>Unique payment code</code>. Suitable for top up business model.</p> |

2. **Direct Inquiry (DIPC)**: The payment code is registered on merchant side and DOKU will forward Acquirer inquiry request to merchant side when the customer make payment at the acquirer channel (Alfa Group, etc.). Component Payment Code : `BIN` and `Unique Payment Code`.

{% hint style="info" %}
**One transaction can't use 2 or 3 features at the same time.**

By default, DOKU will register your business with Doku Generate Payment Code feature which means BIN for payment code will be generated by DOKU side. But there is no limit for you to be able to use 2 features at the same time. **What it can't do is that 1 transaction uses 2 features at the same time.**
{% endhint %}

{% hint style="success" %}
**Get the BIN**

If you want to use MGPC or DIPC, then please contact the care team to get a BIN as a component for the payment code.
{% endhint %}

***

### Billing Type <a href="#billing-type" id="billing-type"></a>

Billing type is a type of feature used by merchants to determine the method of payment for their customers when they are in Inquiry. In case, the customer can input the amount according to their expected amount or the customer can also pay according to the amount that has been determined by the merchant.

{% hint style="info" %}
**NOTE**

Online to Offline only supports `FIX BILL`
{% endhint %}

***

### BIN Rules <a href="#bin-rules" id="bin-rules"></a>

In accordance with the explanation regarding the payment code Component, BIN is one of the components to create a payment code. So, here's an explanation regarding BIN rules and adapt them to your needs.

{% hint style="info" %}
**NOTE**

These rules only apply to Aggregator Partnership Models, which means merchants use DOKU's BIN.
{% endhint %}

{% tabs %}
{% tab title="Alfa Group" %}

| Partnership Model | BIN Type       | Description                                                                                                                | VA Number Component                                                       | Feature                                                       |
| ----------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Aggregator        | DOKU General   | DOKU's BIN in Acquirer, that DOKU provide for merchants to use                                                             | DOKU General BIN (1 digit) + DOKU Generated Payment Code (max : 19 digit) | DOKU Generated Payment Code (DGPC)                            |
| Aggregator        | DOKU Exclusive | DOKU's BIN in Acquirer, that DOKU provides only for 1 merchant to use. Please contact sales team to get DOKU Exclusive BIN | DOKU Exclusive BIN (starting from 6 digit) + Free Digit (max. 14 digit)   | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |
| Direct            | Direct         | Merchant’s Acquirer BIN. Please contact sales team to get Direct BIN from Acquirer                                         | Merchant’s Acquirer BIN (5 digit) + Free Digit (max. 20 digit)            | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |
| {% endtab %}      |                |                                                                                                                            |                                                                           |                                                               |

{% tab title="Indomaret" %}

| Partnership Model | BIN Type | Description                                                                        | VA Number Component                                            | Feature |
| ----------------- | -------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------- |
| Direct            | Direct   | Merchant’s Acquirer BIN. Please contact sales team to get Direct BIN from Acquirer | Merchant’s Acquirer BIN (5 digit) + Free Digit (max. 20 digit) |         |
| {% endtab %}      |          |                                                                                    |                                                                |         |
| {% endtabs %}     |          |                                                                                    |                                                                |         |

***

### Reusable Status <a href="#reusable-status" id="reusable-status"></a>

Reusable Status is a parameter in API to indicate if Payment Code can be paid more than once, set this to true if merchants wish to enable it.

Here is a reusable status explanation. Set this value in the API, to implement reusable status.

| Value   | Description                             |
| ------- | --------------------------------------- |
| `true`  | Payment Code can be paid more than once |
| `false` | Payment Code can only be paid once      |

{% hint style="info" %}
By default, DOKU will set the value to `false`, if you don't send this parameter on request.
{% endhint %}

***

### Integration steps <a href="#integration-steps" id="integration-steps"></a>

Here is the overview of how to integrate with O2O:

1. Generate payment code
2. Display payment code
3. Acknowledge payment result

#### Direct API - O2O Sequence Diagram

<figure><img src="/files/SCQW5l4ukc0k5DsAWTap" alt=""><figcaption></figcaption></figure>

***

#### 1. Generate payment code <a href="#id-1-generate-payment-code" id="id-1-generate-payment-code"></a>

To generate payment code, you will need to hit this API through your Backend:

**API Request**

| Type                          | Value                                                                    |
| ----------------------------- | ------------------------------------------------------------------------ |
| **HTTP Method**               | POST                                                                     |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/{{channel-name}}/{{version}}/payment-code` |
| **API endpoint (Production)** | `https://api.doku.com/{{channel-name}}/{{version}}/payment-code`         |

You need to change the `{{channel-name}}` and `{{version}}` accordingly based on what payment channel you wish. Here is the list:

| Name       | `{{channel-name}}`            | Current Version |
| ---------- | ----------------------------- | --------------- |
| Alfa Group | `alfa-online-to-offline`      | `v2`            |
| Indomaret  | `indomaret-online-to-offline` | `v2`            |

Every object naming in our O2O APIs are standarized and have their own customization to ensure easy integration. Therefore, you can learn more about how to integrate to each of them by clicking the link above.

***

#### 2. Display payment code <a href="#id-2-display-payment-code" id="id-2-display-payment-code"></a>

You can display the payment code to your customer by using `online_to_offline_info.payment_code` that you retrieved from the API response.

***

#### 3. Acknowledge payment result <a href="#id-3-acknowledge-payment-result" id="id-3-acknowledge-payment-result"></a>

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`. Learn how to handle the notification from DOKU:

* [Handling DOKU HTTP Notification](/get-started-with-doku-api/notification/http-notification-sample-for-snap)

***

### What's next? <a href="#whats-next" id="whats-next"></a>

You can learn more about how to integrate to each payment channels you wish by clicking the menu on the sidebar.


# Alfa Group

DOKU has partnered with various partners and one of them is Alfa Group (Alfamart, Alfaexpress, Alfamidi, Lawson, Dan+Dan) to provide O2O Payment. Learn more about how DOKU can help you integrate with Alfa Group here.

***

## Integration methods <a href="#integration-methods" id="integration-methods"></a>

There are two methods to integrate with Alfa Group:

1. **Register**: The payment code will be registered to DOKU and Alfa will inquiry to our side when the customer make payment at the Alfa Store
   1. **DOKU Generated Payment Code (DGPC)**: The payment code is generated by DOKU. Suitable for e-commerce business model.
   2. **Merchant Generated Payment Code (MGPC)**: The payment code is generated by Merchant. Suitable for top up business model.
2. **Direct Inquiry (DIPC)**: The payment code is registered on merchant side and DOKU will forward Alfa inquiry request to merchant side when the customer make payment at the Alfa store

## Integration steps <a href="#integration-steps" id="integration-steps"></a>

{% tabs %}
{% tab title="DOKU Generate Payment Code" %}
Here is the overview of how to integrate with Online to Offline:

1. Generate payment code
2. Display payment code
3. Acknowledge payment result

<figure><img src="/files/LvLKuzotVyrBCtqUVaUR" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/SjJEJIgMRIyfV7Ia2BB0" alt=""><figcaption></figcaption></figure>

#### 1. Generate payment code <a href="#id-1-generate-payment-code" id="id-1-generate-payment-code"></a>

To generate payment code, you will need to hit this API through your Backend:

**API Request**

| Type                          | Value                                                               |
| ----------------------------- | ------------------------------------------------------------------- |
| **HTTP Method**               | POST                                                                |
| **API endpoint (Sandbox)**    | `https://api-sandbox.doku.com/alfa-virtual-account/v2/payment-code` |
| **API endpoint (Production)** | `https://api.doku.com/alfa-virtual-account/v2/payment-code`         |

Here is the sample of request header to generate payment code:

```
Client-Id: MCH-0001-10791114622547
Request-Id: d24a5644-6078-4249-8740-4a6dcd92df5a
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
```

<table><thead><tr><th width="199">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>client-id</code></strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong><code>request-id</code></strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong><code>request-timestamp</code></strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong><code>signature</code></strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="https://dashboard.doku.com/docs/docs/technical-references/generate-signature">this section</a> to generate the signature</td></tr></tbody></table>

Here is the sample of request body to generate payment code:

```json
{
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "online_to_offline_info": {
        "expired_time": 60,
        "reusable_status": false,
        "info": "Merchant Demo Store"
    },
    "customer": {
        "name": "Anton Budiman",
        "email": "anton@example.com"
    },
    "additional_info": {
        "override_notification_url": "https://another.example.com/payments/notifications"
    }
}
```

**Request Body Explanation**

| Parameter                                   | Type     | Mandatory | Description                                                                                                                                                                                      |
| ------------------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `order.invoice_number`                      | `string` | Mandatory | <p>Generated by merchant to identify the order and must unique per request<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code></p>                  |
| `order.amount`                              | `number` | Mandatory | <p>In IDR currency and without decimal. Alfa only supports <code>Close Amount</code><br>Allowed chars: <code>numeric</code><br>Max length: <code>12</code></p>                                   |
| `online_to_offline_info.expired_time`       | `number` | Optional  | <p>Payment code expiration time in minutes format<br>Allowed chars: <code>numeric</code><br>Maximum length: <code>5</code><br>Default value: <code>60</code></p>                                 |
| `online_to_offline_info.reusable_status`    | `number` | Mandatory | <p>For payment code that can be paid more than once, set this to <code>true</code><br>Possible value: <code>true</code> <code>false</code></p>                                                   |
| `online_to_offline_info.info`               | `string` | Optional  | <p>Additional info that will be display on the Alfa POS when customer do inquiry<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>30</code></p>            |
| `customer.name`                             | `string` | Mandatory | <p>Customer name that will be displayed on acquirer channel when do inquiry<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code></p>                 |
| `customer.email`                            | `string` | Optional  | <p>Customer email<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>128</code></p>                                                                          |
| `additional_info.override_notification_url` | `string` | Optional  | This parameter is intended to override the configured `Notification URL` with another URL. Click [here](/get-started-with-doku-api/notification/override-notification-url) for more information. |

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

```
Client-Id: MCH-0001-10791114622547
Request-Id: d24a5644-6078-4249-8740-4a6dcd92df5a
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

<table><thead><tr><th width="199">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>client-id</code></strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong><code>request-id</code></strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong><code>request-timestamp</code></strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong><code>signature</code></strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="https://dashboard.doku.com/docs/docs/technical-references/generate-signature">this section</a> to generate the signature</td></tr></tbody></table>

Here is the sample of response body:

```json
{
    "order": {
        "invoice_number": "INV-20210124-0001"
    },
    "online_to_offline_info": {
        "payment_code": "6059000000000205",
        "how_to_pay_page": "https://sandbox.doku.com/how-to-pay/v2/alfa-online-to-offline/6059000000000205",
        "how_to_pay_api": "https://api-sandbox.doku.com/alfa-online-to-offline/v2/how-to-pay-api/6059000000000205",
        "created_date": "20210331115005",
        "expired_date": "20210331125005",
        "created_date_utc": "2021-03-31T04:50:05Z",
        "expired_date_utc": "2021-03-31T05:50:05Z"
    },
    "additional_info": {
        "override_notification_url": "https://another.example.com/payments/notifications"
    }
}
```

#### Response Body Explanation

<table><thead><tr><th>Parameter</th><th width="121">Type</th><th width="116">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.invoice_number</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as the request</td></tr><tr><td><code>online_to_offline_info.</code><br><code>payment_code</code></td><td><code>string</code></td><td>Mandatory</td><td>Generated by DOKU that will be used by customer for doing a payment through Alfa store</td></tr><tr><td><code>online_to_offline_info.how_to_pay_page</code></td><td><code>string</code></td><td>Optional</td><td>Page URL that merchant can use to display how customer can complete the payment process through Alfa store</td></tr><tr><td><code>online_to_offline_info.how_to_pay_api</code></td><td><code>string</code></td><td>Optional</td><td>URL that merchant can parse to display customized how customer can complete the payment process through Alfa store</td></tr><tr><td><code>online_to_offline_info.created_date</code></td><td><code>string</code></td><td>Conditional</td><td>Date time of payment code generated with the format of <code>yyyyMMddHHmmss</code>. The created date uses UTC+7 time</td></tr><tr><td><code>online_to_offline_info.expired_date</code></td><td><code>string</code></td><td>Conditional</td><td>Date time of payment code will be expired with the format of <code>yyyyMMddHHmmss</code>. The expired date uses UTC+7 time. Use this to set the expiry order on merchant side</td></tr><tr><td><code>online_to_offline_info.created_date_utc</code></td><td><code>string</code></td><td>Conditional</td><td>Date time of payment code generated in UTC format</td></tr><tr><td><code>online_to_offline_info.expired_date_utc</code></td><td><code>string</code></td><td>Conditional</td><td>Date time of payment code will be expired in UTC. Use this to set the expiry order on merchant side</td></tr><tr><td><code>additional_info.override_notification_url</code></td><td><code>string</code></td><td>Optional</td><td>Same as the request</td></tr></tbody></table>

{% hint style="info" %}
**PRO TIPS**

You can also show payment instruction link to your customer by using `online_to_offline_info.how_to_pay_page`. If you wish to customize the UI for the payment instruction, you can use the `online_to_offline_info.how_to_pay_api`.
{% endhint %}

#### 2. Display payment code <a href="#id-2-display-payment-code" id="id-2-display-payment-code"></a>

You can display the payment code to your customer by using `online_to_offline_info.payment_code` that you retrieved from the API response.

#### 3. Acknowledge payment result <a href="#id-3-acknowledge-payment-result" id="id-3-acknowledge-payment-result"></a>

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`. Learn how to handle the notification from DOKU:

* [Handling DOKU HTTP Notification](/get-started-with-doku-api/notification/http-notification-sample-non-snap)
  {% endtab %}

{% tab title="Merchant Generate Payment Code" %}
Here is the overview of how to integrate with Online to Offline:

1. Generate payment code
2. Display payment code
3. Acknowledge payment result

<figure><img src="/files/anMCIac0YJxY0t0L8ear" alt=""><figcaption></figcaption></figure>

#### 1. Generate payment code <a href="#id-1-generate-payment-code" id="id-1-generate-payment-code"></a>

To generate payment code, you will need to hit this API through your Backend:

**API Request**

| Type                          | Value                                                                          |
| ----------------------------- | ------------------------------------------------------------------------------ |
| **HTTP Method**               | POST                                                                           |
| **API endpoint (Sandbox)**    | <https://api-sandbox.doku.com/alfa-online-to-offline/v2/merchant-payment-code> |
| **API endpoint (Production)** | <https://api.doku.com/alfa-online-to-offline/v2/merchant-payment-code>         |

Here is the sample of request header to generate payment code:

```
Client-Id: MCH-0001-10791114622547
Request-Id: d24a5644-6078-4249-8740-4a6dcd92df5a
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
```

<table><thead><tr><th width="199">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>client-id</code></strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong><code>request-id</code></strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong><code>request-timestamp</code></strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong><code>signature</code></strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="https://dashboard.doku.com/docs/docs/technical-references/generate-signature">this section</a> to generate the signature</td></tr></tbody></table>

Here is the sample of request body to generate payment code:

```
{
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "online_to_offline_info": {
        "payment_code": "1900600000000046",
        "expired_time": 60,
        "reusable_status": false,
        "info": "Merchant Demo Store",
    },
    "customer": {
        "name": "Anton Budiman",
        "email": "anton@example.com"
    }
}
```

#### Request Body Explanation

<table><thead><tr><th>Parameter</th><th width="104">Type</th><th width="128">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.invoice_number</code></td><td><code>string</code></td><td>Mandatory</td><td>Generated by merchant to identify the order and must unique per request<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code></td></tr><tr><td><code>order.amount</code></td><td><code>number</code></td><td>Mandatory</td><td>In IDR currency and without decimal. Alfa only supports <code>Close Amount</code><br>Allowed chars: <code>numeric</code><br>Max length: <code>12</code></td></tr><tr><td><code>online_to_offline_info.</code><br><code>payment_code</code></td><td><code>string</code></td><td>Mandatory</td><td>Generated by Merchant that will be used by customer for doing a payment through Alfa store<br>Max Length: <code>20</code></td></tr><tr><td><code>online_to_offline_info.expired_time</code></td><td><code>number</code></td><td>Optional</td><td>Payment code expiration time in minutes format<br>Allowed chars: <code>numeric</code><br>Maximum length: <code>5</code><br>Default value: <code>60</code></td></tr><tr><td><code>online_to_offline_info.reusable_status</code></td><td><code>number</code></td><td>Mandatory</td><td>For payment code that can be paid more than once, set this to <code>true</code><br>Possible value: <code>true</code> <code>false</code></td></tr><tr><td><code>online_to_offline_info.info</code></td><td><code>string</code></td><td>Optional</td><td>Additional info that will be display on the Alfa POS when customer do inquiry<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>30</code></td></tr><tr><td><code>customer.name</code></td><td><code>string</code></td><td>Mandatory</td><td>Customer name that will be displayed on Alfa POS when do inquiry<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code></td></tr><tr><td><code>customer.email</code></td><td><code>string</code></td><td>Optional</td><td>Customer email<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>128</code></td></tr></tbody></table>

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

```
Client-Id: MCH-0001-10791114622547
Request-Id: d24a5644-6078-4249-8740-4a6dcd92df5a
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

<table><thead><tr><th width="199">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>client-id</code></strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong><code>request-id</code></strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong><code>request-timestamp</code></strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong><code>signature</code></strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="https://dashboard.doku.com/docs/docs/technical-references/generate-signature">this section</a> to generate the signature</td></tr></tbody></table>

Here is the sample of response body:

```
{
    "order": {
        "invoice_number": "INV-20210124-0001"
    },
    "online_to_offline_info": {
        "payment_code": "1900600000000046",
        "how_to_pay_page": "https://sandbox.doku.com/how-to-pay/v1/alfa-online-to-offline/1900600000000046",
        "how_to_pay_api": "https://sandbox.doku.com/alfa-online-to-offline/v1/how-to-pay-api/1900600000000046",
        "created_date": "20200313095850",
        "expired_date": "20200313155850",
        "created_date_utc": "2020-03-31T09:58:50Z",
        "expired_date_utc": "2020-03-31T15:58:50Z"
    }
}
```

Response Body Explanation

Response Body Explanation

<table><thead><tr><th width="228">Parameter</th><th width="100">Type</th><th width="119">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.invoice_number</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as the request</td></tr><tr><td><code>online_to_offline_info.</code><br><code>payment</code></td><td><code>string</code></td><td>Mandatory</td><td>Generated by DOKU that will be used by customer for doing a payment through Alfa store</td></tr><tr><td><code>online_to_offline_info.how_to_pay_page</code></td><td><code>string</code></td><td>Optional</td><td>Page URL that merchant can use to display how customer can complete the payment process through Alfa store</td></tr><tr><td><code>online_to_offline_info.how_to_pay_api</code></td><td><code>string</code></td><td>Optional</td><td>URL that merchant can parse to display customized how customer can complete the payment process through Alfa store</td></tr><tr><td><code>online_to_offline_info.created_date</code></td><td><code>string</code></td><td>Conditional</td><td>Date time of payment code generated with the format of <code>yyyyMMddHHmmss</code>. The created date uses UTC+7 time</td></tr><tr><td><code>online_to_offline_info.expired_date</code></td><td><code>string</code></td><td>Conditional</td><td>Date time of payment code will be expired with the format of <code>yyyyMMddHHmmss</code>. The expired date uses UTC+7 time. Use this to set the expiry order on merchant side</td></tr><tr><td><code>online_to_offline_info.created_date_utc</code></td><td><code>string</code></td><td>Conditional</td><td>Date time of payment code generated in UTC format</td></tr><tr><td><code>online_to_offline_info.expired_date_utc</code></td><td><code>string</code></td><td>Conditional</td><td>Date time of payment code will be expired in UTC. Use this to set the expiry order on merchant side</td></tr></tbody></table>

{% hint style="info" %}
**PRO TIPS**

You can also show payment instruction link to your customer by using `online_to_offline_info.how_to_pay_page`. If you wish to customize the UI for the payment instruction, you can use the `online_to_offline_info.how_to_pay_api`.
{% endhint %}

#### 2. Display payment code <a href="#id-2-display-payment-code" id="id-2-display-payment-code"></a>

You can display the payment code to your customer by using `online_to_offline_info.payment_code` that you retrieved from the API response.

#### 3. Acknowledge payment result <a href="#id-3-acknowledge-payment-result" id="id-3-acknowledge-payment-result"></a>

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`. Learn how to handle the notification from DOKU:

* [Handling DOKU HTTP Notification](/get-started-with-doku-api/notification/http-notification-sample-non-snap)
  {% endtab %}

{% tab title="Direct Inquiry" %}
Here is the overview of how to integrate with Alfa Group:

1. Setup `Inquiry URL`
2. Generate payment code
3. Receive inquiry request from DOKU
4. Acknowledge payment result

<figure><img src="/files/JvFoiMiGWB2JOWpgjdUf" alt=""><figcaption></figcaption></figure>

1. **Setup Inquiry URL**

To receive the inquiry request from DOKU. You must set your `Inquiry URL` to DOKU. Please contact our team for the setup.

Please inform the `Inquiry URL` for Sandbox environment and Production environment.

2. **Generate Payment Code**

Generate payment is done in your system. The payment code length maximum is `20` digits.

3. **Receive Inquiry Request from DOKU**

#### API Request&#x20;

DOKU will hits your `Inquiry URL` with the following API request:

| Type        | Value |
| ----------- | ----- |
| HTTP Method | POST  |

Here is the sample of request header that DOKU generated for inquiry:

```json
Client-Id: MCH-0001-10791114622547
Request-Id: d24a5644-6078-4249-8740-4a6dcd92df5a
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
```

Request Header Explanation

<table><thead><tr><th width="208">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong>Request-Id</strong></td><td>Unique random string (max 128 characters) generated from DOKU side to protect duplicate request</td></tr><tr><td><strong>Request-Timestamp</strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong>Signature</strong></td><td>Security parameter that needs to be verified on merchant Backend to ensure that the request is coming from DOKU. Please refer to <a href="https://dashboard.doku.com/docs/docs/technical-references/generate-signature">this section</a> to generate the signature</td></tr></tbody></table>

Here is the sample of request body that DOKU will send to defined `Inquiry URL`:

```json
{
    "service": {
        "id":"ONLINE_TO_OFFLINE"
    },
    "acquirer": {
        "id":"ALFA"
    },
    "channel": {
        "id":"ONLINE_TO_OFFLINE_ALFA"
    },
    "online_to_offline_info": {
        "payment_code":"8896512345678123"
    },
    "online_to_offline_inquiry": {
        "date":"2020-08-11T08:45:42Z",
        "identifier": [
        ]
    }
}
```

#### **Request Body Explanation**

| Parameter                              | Type     | Mandatory | Description                                                                                               |
| -------------------------------------- | -------- | --------- | --------------------------------------------------------------------------------------------------------- |
| `service.id`                           | `string` | Mandatory | Value: `ONLINE_TO_OFFLINE`                                                                                |
| `acquirer.id`                          | `string` | Mandatory | Value: `ALFA`                                                                                             |
| `channel.id`                           | `string` | Mandatory | Value: `ONLINE_TO_OFFLINE_ALFA`                                                                           |
| `online_to_offline_info.payment_code`  | `number` | Mandatory | Payment code that is inquired by the customer                                                             |
| `online_to_offline_inquiry.date`       | `string` | Mandatory | Timestamp request on UTC time in ISO8601 format                                                           |
| `online_to_offline_inquiry.identifier` | `array`  | Optional  | List of transaction identifier that coming from the acquiring. Merchant can save these data for reference |

**API Response**[**​**](https://dashboard.doku.com/docs/docs/jokul-direct/e-money/shopeepay-guide/#api-response)

After DOKU hits your `Inquiry URL` with the above API request, you must give the following response:

<table><thead><tr><th width="608">Type</th><th>Value</th></tr></thead><tbody><tr><td><strong>HTTP Status</strong> for <code>online_to_offline_inquiry.status</code> = <code>success</code></td><td>200</td></tr><tr><td><strong>HTTP Status</strong> for <code>online_to_offline_inquiry.status</code> = <code>decline</code></td><td>400</td></tr><tr><td><strong>HTTP Status</strong> for <code>online_to_offline_inquiry.status</code> = <code>billing_already_paid</code></td><td>400</td></tr><tr><td><strong>HTTP Status</strong> for <code>online_to_offline_inquiry.status</code> = <code>billing_was_expired</code></td><td>400</td></tr><tr><td><strong>HTTP Status</strong> for <code>online_to_offline_inquiry.status</code> = <code>billing_not_found</code></td><td>404</td></tr><tr><td><strong>HTTP Status</strong> for <code>online_to_offline_inquiry.status</code> = <code>invalid_signature</code></td><td>401</td></tr></tbody></table>

```json
Client-Id: MCH-0001-10791114622547
Request-Id: 5b8e438f-fac1-4103-9e0e-ebfdc38b5acb
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

#### Response Header Explanation

<table><thead><tr><th width="144">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Same as the request</td></tr><tr><td><strong>Request-Id</strong></td><td>Same as the request</td></tr><tr><td><strong>Response-Timestamp</strong></td><td>Timestamp Response on UTC with format ISO8601 UTC+0 from Merchant</td></tr><tr><td><strong>Signature</strong></td><td>Signature generated by Merchant based on the response body. Please refer to <a href="/pages/9uXtc55i3bhjXaqAJZOx">this section</a> to generate the signature</td></tr></tbody></table>

Here is the sample of response body:

```json
{
    "order": {
        "invoice_number":"MINV20201231468",
        "amount":150000
    },
    "online_to_offline_info": {
        "payment_code":"8896512345678123",
        "info1":"Thanks for shooping"
    },
    "online_to_offline_inquiry": {
        "status":"success"
    },
    "customer": {
        "name":"Taufik Ismail",
        "email":"taufik@doku.com"
    }
    "additional_info": {
    }
}
```

#### Response Body Explanation

<table><thead><tr><th width="248">Parameter</th><th width="111">Type</th><th width="122">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.invoice_number</code></td><td><code>string</code></td><td>Mandatory</td><td>Generated by merchant to identify the order and must unique per request<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code></td></tr><tr><td><code>order.amount</code></td><td><code>number</code></td><td>Mandatory</td><td>In IDR currency and without decimal. Alfa only supports <code>Close Amount</code><br>Allowed chars: <code>numeric</code><br>Max length: <code>12</code></td></tr><tr><td><code>online_to_offline_info.payment_code</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as the request</td></tr><tr><td><code>online_to_offline_info.info</code></td><td><code>string</code></td><td>Optional</td><td>Additional info that will be display on the Alfa POS when customer do inquiry<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>30</code></td></tr><tr><td><code>online_to_offline_inquiry.status</code></td><td><code>string</code></td><td>Mandatory</td><td>Possible value: <code>success</code>, <code>decline</code>, <code>billing_already_paid</code>, <code>billing_was_expired</code>, <code>billing_not_found</code></td></tr><tr><td><code>customer.name</code></td><td><code>string</code></td><td>Mandatory</td><td>Customer name that will be displayed on Alfa POS when do inquiry<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code></td></tr><tr><td><code>customer.email</code></td><td><code>string</code></td><td>Optional</td><td>Customer email<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>128</code></td></tr><tr><td><code>additional_info</code></td><td><code>object</code></td><td>Optional</td><td>Merchant can send additional data through this parameter and will be get the data in the HTTP Notification</td></tr></tbody></table>

#### 4. Acknowledge payment result <a href="#id-3-acknowledge-payment-result" id="id-3-acknowledge-payment-result"></a>

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`. Learn how to handle the notification from DOKU:

* [Handling DOKU HTTP Notification](/get-started-with-doku-api/notification/http-notification-sample-non-snap)
  {% endtab %}
  {% endtabs %}

***

## Additional features <a href="#additional-features" id="additional-features"></a>

We provide various additional features to suited your needs. Learn more here.

### Insurance Data <a href="#insurance-data" id="insurance-data"></a>

For insurance merchant, DOKU can show insurance data to Alfa POS and Alfa receipt by give object `additional_info.insurance_info` and also DOKU can show footer message on Alfa receipt by give `alfa_info.receipt.footer_message` to DOKU. Here is the sample:

```json
{
    ...
    "alfa_info": {
        "receipt": {
            "footer_message":"Call Center 021 555-0525"
        }
    },
    "additional_info": {
        "insurance_info": {
            "policy_type": "Dana Pendidikan",
            "policy_number": "9090901234",
            "policy_account_name": "Taufik Ismail",
            "policy_status": "aktif",
            "bill_due_date": "21 May 2021"
        }
    },
    ...
}
```

### Update and Cancel Payment Code Data <a href="#update-and-cancel-payment-code-data" id="update-and-cancel-payment-code-data"></a>

If you wish to update your payment code data such as, update the amount, update the expiry time, customer details, and etc. You can do that by hitting the API with `PATCH` method:

**API Request**

<table><thead><tr><th width="266">Type</th><th>Value</th></tr></thead><tbody><tr><td><strong>HTTP Method</strong></td><td>PATCH</td></tr><tr><td><strong>API endpoint (Sandbox)</strong></td><td><code>https://api-sandbox.doku.com/alfa-online-to-offline/v2/payment-code</code></td></tr><tr><td><strong>API endpoint (Production)</strong></td><td><code>https://api.doku.com/alfa-online-to-offline/v2/payment-code</code></td></tr></tbody></table>

Here is the sample of request header to update payment code:

```json
Client-Id: MCH-0001-10791114622547
Request-Id: 2dc5985e-adaa-4f82-b126-b09e9006da14
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
```

#### Request Header Explanation

<table><thead><tr><th width="219">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong>Request-Id</strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong>Request-Timestamp</strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong>Signature</strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="/pages/9uXtc55i3bhjXaqAJZOx">this section </a>to generate the signature</td></tr></tbody></table>

Here is the sample of request body to update payment code data:

{% hint style="info" %}
**Cancel payment code data**

To cancel a payment code, simply set `online_to_offline_info.status` to `DELETE`
{% endhint %}

```json
{
    "order": {
        "invoice_number": "INV-20210124-0001",
        "amount": 150000
    },
    "online_to_offline_info": {
        "payment_code": "6059000000000205",
        "status": "ACTIVE",
        "expired_time": 60,
        "reusable_status": false,
        "info": "Thank you for shopping"
    },
    "customer": {
        "name": "Anton Budiman",
        "email": "anton@example.com"
    }
}
```

**Request Body Explanation**

<table><thead><tr><th>Parameter</th><th width="130">Type</th><th width="151">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.invoice_number</code></td><td><code>string</code></td><td>Same as the generate payment code request</td><td></td></tr><tr><td><code>order.amount</code></td><td><code>number</code></td><td>Conditional</td><td>Set this with updated value if wished. Set this parameter to more than (>) <code>0</code>for <code>Close Amount</code><br>Allowed chars: <code>numeric</code><br>Max length: <code>12</code></td></tr><tr><td><code>online_to_offline_info.payment_code</code></td><td><code>string</code></td><td>Mandatory</td><td>The payment code that wish to be updated</td></tr><tr><td><code>online_to_offline_info.status</code></td><td><code>string</code></td><td>Mandatory</td><td>Set <code>ACTIVE</code> to update the payment code and set <code>DELETE</code> to cancel the payment code<br>Possible value: <code>ACTIVE, DELETE</code></td></tr><tr><td><code>online_to_offline_info.expired_time</code></td><td><code>number</code></td><td>Optional</td><td>Set this with updated value if wished<br>Allowed chars: <code>numeric</code><br>Maximum length: <code>5</code><br>Default value: <code>60</code></td></tr><tr><td><code>online_to_offline_info.reusable_status</code></td><td><code>number</code></td><td>Mandatory</td><td>Set this with updated value if wished<br>Possible value: <code>true</code> <code>false</code></td></tr><tr><td><code>online_to_offline_info.info</code></td><td><code>string</code></td><td>Optional</td><td>Additional info that will be display on the Alfa POS when customer do inquiry<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>30</code></td></tr><tr><td><code>customer.name</code></td><td><code>string</code></td><td>Mandatory</td><td>Set this with updated value if wished<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>40</code></td></tr><tr><td><code>customer.email</code></td><td><code>string</code></td><td>Optional</td><td>Set this with updated value if wished<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>128</code></td></tr></tbody></table>

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

```json
Client-Id: MCH-0001-10791114622547
Request-Id: 09e0defe-a071-45b3-9feb-ac134374628c
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

#### Response Header Explanation

<table><thead><tr><th width="226">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Same as the request</td></tr><tr><td><strong>Request-Id</strong></td><td>Same as the request</td></tr><tr><td><strong>Response-Timestamp</strong></td><td>Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU</td></tr><tr><td><strong>Signature</strong></td><td>Signature generated by DOKU based on the response body</td></tr></tbody></table>

Here is the sample of response body:

```json
{
    "order": {
        "invoice_number": "INV-20210124-0001"
    },
    "online_to_offline_info": {
        "payment_code": "6059000000000205",
        "created_date": "20210331115005",
        "expired_date": "20210331125005",
        "created_date_utc": "2021-03-31T04:50:05Z",
        "expired_date_utc": "2021-03-31T05:50:05Z"
    }
}
```

#### Response Body Explanation <a href="#split-settlement" id="split-settlement"></a>

<table><thead><tr><th>Parameter</th><th width="118">Type</th><th width="135">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.invoice_number</code></td><td><code>string</code></td><td>Mandatory</td><td>Same as the request</td></tr><tr><td><code>online_to_offline_info.</code><br><code>payment_code</code></td><td><code>string</code></td><td>Mandatory</td><td>Generated by DOKU that will be used by customer for doing a payment through Alfa store</td></tr><tr><td><code>online_to_offline_info.created_date</code></td><td><code>string</code></td><td>Conditional</td><td>Date time of payment code generated with the format of <code>yyyyMMddHHmmss</code>. The created date uses UTC+7 time</td></tr><tr><td><code>online_to_offline_info.expired_date</code></td><td><code>string</code></td><td>Conditional</td><td>Date time of payment code will be expired with the format of <code>yyyyMMddHHmmss</code>. The expired date uses UTC+7 time. Use this to set the expiry order on merchant side</td></tr><tr><td><code>online_to_offline_info.created_date_utc</code></td><td><code>string</code></td><td>Conditional</td><td>Date time of payment code generated in UTC format</td></tr><tr><td><code>online_to_offline_info.expired_date_utc</code></td><td><code>string</code></td><td>Conditional</td><td>Date time of payment code will be expired in UTC. Use this to set the expiry order on merchant side</td></tr></tbody></table>

#### Split Settlement <a href="#split-settlement" id="split-settlement"></a>

If you are a platform or a marketplace, you can use this feature to settle the funds to your sellers or partners programmatically, save many operational efforts.

* [Settlement](#split-settlement-1)

***

## What's next? <a href="#whats-next" id="whats-next"></a>

You can test your payment through our Payment Simulator. Learn more [here](/accept-payments/doku-checkout/integration-guide/simulate-payment-and-notification).


# Indomaret

DOKU has partnered with various partners and one of them is Indomaret to provide O2O Payment. Learn more about how DOKU can help you integrate with Indomaret here.

***

### Integration steps <a href="#integration-steps" id="integration-steps"></a>

Here is the overview of how to integrate with O2O:

1. Generate payment code
2. Display payment code
3. Acknowledge payment result

#### Direct API - O2O Sequence Diagram

<figure><img src="/files/oUwtqNLSaKoqJwUgPum6" alt=""><figcaption></figcaption></figure>

***

#### 1. Generate payment code <a href="#id-1-generate-payment-code" id="id-1-generate-payment-code"></a>

To generate payment code, you will need to hit this API through your Backend:

**API Request**

<table><thead><tr><th width="242">Type</th><th>Value</th></tr></thead><tbody><tr><td><strong>HTTP Method</strong></td><td>POST</td></tr><tr><td><strong>API endpoint (Sandbox)</strong></td><td><code>https://api-sandbox.doku.com/indomaret-online-to-offline/v2/payment-code</code></td></tr><tr><td><strong>API endpoint (Production)</strong></td><td><code>https://api.doku.com/indomaret-online-to-offline/v2/payment-code</code></td></tr></tbody></table>

Here is the sample of request header to generate payment code:

```
Client-Id: MCH-0001-10791114622547
Request-Id: 5b8e438f-fac1-4103-9e0e-ebfdc38b5acb
Request-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=vl9DBTX5KhEiXmnpOD0TSm8PYQknuHPdyHSTSc3W6Ps=
```

#### Request Header Explanation&#x20;

<table><thead><tr><th width="207">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Client ID retrieved from DOKU Back Office</td></tr><tr><td><strong>Request-Id</strong></td><td>Unique random string (max 128 characters) generated from merchant side to protect duplicate request</td></tr><tr><td><strong>Request-Timestamp</strong></td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7. Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td><strong>Signature</strong></td><td>Security parameter that needs to be generated on merchant Backend and placed to the header request to ensure that the request is coming from valid merchant. Please refer to <a href="/pages/9uXtc55i3bhjXaqAJZOx">this section</a> to generate the signature</td></tr></tbody></table>

Here is the sample of request body to generate payment code:

```json
{
    "order": {
        "invoice_number": "INV-2021002-0001",
        "amount": 150000
    },
    "online_to_offline_info": {
        "expired_time": 60,
        "reusable_status": true,
        "info": "Thanks for shopping in jokul.com"
    },
    "customer": {
        "name":"Taufik Ismail",
        "email":"taufik@doku.com"
    },
    "indomaret_info": {
        "receipt": {
            "description": "Voucher 10000",
            "footer_message": "Call 13555 for customer support"
        },
    },
    "additional_info": {
        "override_notification_url": "https://another.example.com/payments/notifications"
    }
}
```

**Request Body Explanation**

<table><thead><tr><th width="174">Parameter</th><th width="83">Type </th><th width="115">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.invoice_number</code></td><td>string</td><td>Mandatory</td><td>Generated by merchant to identify the order and must unique per request<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code></td></tr><tr><td><code>order.amount</code></td><td>number</td><td>Mandatory</td><td>In IDR currency and without decimal<br>Allowed chars: <code>numeric</code><br>Max length: <code>12</code></td></tr><tr><td><code>online_to_offline_info.</code><br><code>expired_time</code></td><td>number</td><td>Optional</td><td>Payment Code expiration time in minutes format<br>Allowed chars: <code>numeric</code><br>Maximum length: <code>8</code><br>Default value: <code>60</code></td></tr><tr><td><code>online_to_offline_info.</code><br><code>reusable_status</code></td><td>string</td><td>Mandatory</td><td>For payment code that can be paid more than once, set this to <code>true</code><br>Possible value: <code>true</code> <code>false</code></td></tr><tr><td><code>online_to_offline_info.info</code></td><td>string</td><td>Optional</td><td>Additional info that will be display on the acquirer channel when customer do inquiry<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>32</code></td></tr><tr><td><code>customer.name</code></td><td>string</td><td>Mandatory</td><td>Customer name that will be displayed on acquirer channel when do inquiry<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>64</code></td></tr><tr><td><code>customer.email</code></td><td>string</td><td>Optional</td><td>Customer email<br>Allowed chars: <code>alphabetic, numeric, special chars</code><br>Max length: <code>128</code></td></tr><tr><td><code>indomaret_info.receipt.</code><br><code>description</code></td><td>string</td><td>Mandatory</td><td>Message that will be printed on the receipt as Product Description that given to the customer<br><br>Max length: <code>128</code></td></tr><tr><td><code>indomaret_info.receipt.</code><br><code>footer_message</code></td><td>string</td><td>Optional</td><td>Message that will be printed on the receipt as footer message that given to the customer<br><br>Max length: <code>255</code></td></tr><tr><td><code>additional_info.override_notification_url</code></td><td>string</td><td>Optional</td><td>This parameter is intended to override the configured <code>Notification URL</code> with another URL. Click <a href="/pages/LfaJBdkpBWDjF7mwEimR">here</a> for more information.</td></tr></tbody></table>

**API Response**

After hitting the above API request, DOKU will give the response.

| Type            | Value   |
| --------------- | ------- |
| **HTTP Status** | 200     |
| **Result**      | SUCCESS |

```
Client-Id: MCH-0001-10791114622547
Request-Id: 5b8e438f-fac1-4103-9e0e-ebfdc38b5acb
Response-Timestamp: 2020-08-11T08:45:42Z
Signature: HMACSHA256=9UPUFzOqJc47aJzD9ESOTcWg6TMsg3mqSP+DnUO8ENE=
```

#### Response Header Explanation

<table><thead><tr><th width="207">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client-Id</strong></td><td>Same as the request</td></tr><tr><td><strong>Request-Id</strong></td><td>Same as the request</td></tr><tr><td><strong>Request-Timestamp</strong></td><td>Timestamp Response on UTC with format ISO8601 UTC+0 from DOKU</td></tr><tr><td><strong>Signature</strong></td><td>Signature generated by DOKU based on the response body</td></tr></tbody></table>

Here is the sample of response body:

```json
{
    "order": {
        "invoice_number": "INV-2021002-0001"
    },
    "online_to_offline_info": {
        "payment_code": "8888888844445555",
        "how_to_pay_page": "https://sandbox.doku.com/indomaret-online-to-offline/v2/how-to-pay-page/8888888844445555",
        "how_to_pay_api": "https://api-sandbox.doku.com/indomaret-online-to-offline/v2/how-to-pay-api/8888888844445555",
        "created_date": "20210624141049",
        "created_date_utc": "2021-06-24T07:10:49Z",
        "expired_date": "20210624151049",
        "expired_date_utc": "2021-06-24T08:10:49Z"
    },
    "additional_info": {
        "override_notification_url": "https://another.example.com/payments/notifications"
    }
}
```

**Response Body Explanation**

<table><thead><tr><th width="174">Parameter</th><th width="83">Type </th><th width="115">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>order.invoice_number</code></td><td>string</td><td>Mandatory</td><td>Same as the request</td></tr><tr><td><code>online_to_offline_info.</code><br><code>payment_code</code></td><td>string</td><td>Mandatory</td><td>Generated by DOKU that will be used by customer for doing a payment through the Indomaret Store</td></tr><tr><td><code>online_to_offline_info.created_date</code></td><td>string</td><td>Conditional</td><td>Date time of Payment Code generated with the format of <code>yyyyMMddHHmmss</code>. The created date uses UTC+7 time</td></tr><tr><td><code>online_to_offline_info.</code><br><code>expired_date</code></td><td>string</td><td>Conditional</td><td>Date time of Payment Code will be expired with the format of <code>yyyyMMddHHmmss</code>. The expired date uses UTC+7 time. Use this to set the expiry order on merchant side</td></tr><tr><td><code>online_to_offline_info.created_date_utc</code></td><td>string</td><td>Conditional</td><td>Date time of Payment Code generated in UTC format</td></tr><tr><td><code>online_to_offline_info.expired_date_utc</code></td><td>string</td><td>Conditional</td><td>Date time of Payment Code will be expired in UTC. Use this to set the expiry order on merchant side</td></tr><tr><td><code>online_to_offline_info.how_to_pay_page</code></td><td>string</td><td>Optional</td><td>Page URL that merchant can use to display how customer can complete the payment process through the Indomaret Store</td></tr><tr><td><code>online_to_offline_info.how_to_pay_api</code></td><td>string</td><td>Optional</td><td>URL that merchant can parse to display customized how customer can complete the payment process through the Indomaret Store</td></tr><tr><td><code>additional_info.override_notification_url</code></td><td>string</td><td>Optional</td><td>Same as the request</td></tr></tbody></table>

{% hint style="success" %}
**Pro Tips**

You can also show payment instruction link to your customer by using `online_to_offline_info.how_to_pay_page`. If you wish to customize the UI for the payment instruction, you can use the `online_to_offline_info.how_to_pay_api`.
{% endhint %}

***

#### 2. Display payment code <a href="#id-2-display-payment-code" id="id-2-display-payment-code"></a>

You can display the payment code to your customer by using `online_to_offline_info.payment_code` that you retrieved from the API response.

***

#### 3. Acknowledge payment result <a href="#id-3-acknowledge-payment-result" id="id-3-acknowledge-payment-result"></a>

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`. Learn how to handle the notification from DOKU:

* [Handling DOKU HTTP Notification](/get-started-with-doku-api/notification/http-notification-sample-non-snap)

***

### Additional features <a href="#additional-features" id="additional-features"></a>

We provide various additional features to suited your needs. Learn more here.

#### Split Settlement <a href="#split-settlement" id="split-settlement"></a>

If you are a platform or a marketplace, you can use this feature to settle the funds to your sellers or partners programmatically, save many operational efforts.

* Settlement

***

### What's next? <a href="#whats-next" id="whats-next"></a>

You can test your payment through our Payment Simulator. Learn more here.


# SNAP

Here is the integration steps for SNAP - Direct API :&#x20;

1. [Hit Get Token API](/accept-payments/direct-api/snap/integration-guide/get-token-api)&#x20;
2. Hit this API, according to each Payment Channel. Check on this tabs :&#x20;

{% tabs %}
{% tab title="Virtual Account" %}

* Create VA
  1. DOKU Generate Payment Code
  2. Merchant Generate Payment Code
* Direct Inquiry
  {% endtab %}

{% tab title="Direct Debit" %}

1. Account Binding

2. Check Balance Inquiry /  OTP Verification

3. Payment
   {% endtab %}
   {% endtabs %}

4. [Validate Signature](/get-started-with-doku-api/signature-component/snap/symmetric-signature)

5. [Acknowledge Payment Notification](/get-started-with-doku-api/notification/http-notification-sample-for-snap)

6. Hit Additional Feature

{% tabs %}
{% tab title="Direct Debit" %}

* Online Refund
* Account Unbinding
  {% endtab %}
  {% endtabs %}

6. [Check Status API](/get-started-with-doku-api/check-status-api/snap)


# Integration Guide

This document provides an overview of the SNAP format, which has been introduced as part of the new rules mandated by the Bank Indonesia. As a Payment Provider, understanding the technical aspects of the SNAP format is crucial for implementing compliant payment systems. This overview will help you familiarize yourself with the key concepts and requirements related to the SNAP format.

### Background[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/snap-overview/#background) <a href="#background" id="background"></a>

Bank Indonesia has recently implemented new rules to standardize payment system in Indonesia. The primary objective is to streamline payment processing, enhance security, and improve interoperability among various payment service providers.

#### Purpose of SNAP format[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/snap-overview/#purpose-of-snap-format) <a href="#purpose-of-snap-format" id="purpose-of-snap-format"></a>

The SNAP format aims to provide a uniform structure for exchanging payment information between different participants in the payment ecosystem.

### Architecture Type of API[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/snap-overview/#architecture-type-of-api) <a href="#architecture-type-of-api" id="architecture-type-of-api"></a>

The architecture type used is Representational State Transfer (REST) API.

#### Data Format[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/snap-overview/#data-format) <a href="#data-format" id="data-format"></a>

The data format used in the request body and response body is JavaScript Object Notation (JSON).

#### Character Encoding[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/snap-overview/#character-encoding) <a href="#character-encoding" id="character-encoding"></a>

The standard character encoding used is UTF-8.

#### Komponen HTTP Method[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/snap-overview/#komponen-http-method) <a href="#komponen-http-method" id="komponen-http-method"></a>

The HTTP method functions as an identifier for the action to be performed on a resource, using the commonly used HTTP verbs. The HTTP verb used is:

1. POST Request
2. GET Request
3. DELETE Request
4. PUT Request

For security considerations, the Access Token retrieval utilizes a POST request. For other services, the appropriate HTTP verb is used based on the operation type and accessed resource. The usage of HTTP methods for each service is specified in the general information table within the SNAP technical specification document.

#### Server Authorization and Authentication Method Components[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/snap-overview/#server-authorization-and-authentication-method-components) <a href="#server-authorization-and-authentication-method-components" id="server-authorization-and-authentication-method-components"></a>

The standards employed are:

1. OAuth 2.0 sesuai RFC6749
2. Bearer token sesuai RFC6750

In granting access to Service Users, the Service Provider conducts authentication to validate Service Users. The means employed are the exchanged credentials during the collaboration setup process, which include client secret and a pair of public/private keys, used in conjunction with specific cryptographic algorithms.

#### Encryption Standard Components[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/snap-overview/#encryption-standard-components) <a href="#encryption-standard-components" id="encryption-standard-components"></a>

The encryption model applied to messages involves both asymmetric and symmetric encryption, utilizing a combination of Private Key and Public Key, adhering to the following standards:

1. Standard Asymmetric Encryption Signature: SHA256withRSA dengan Private Key ( Kpriv ) dan Public Key ( Kpub ) (256 bits)
2. Standard Symmetric Encryption Signature HMAC\_SHA512 (512 bits)
3. Standard Symmetric Encryption AES-256 dengan client secret sebagai encryption key.


# Get Token API

This API will used in Request Header.

### Get Token Overview

Get Access Token is an authentication method to ensure confidentiality, system and data integrity, availability of a system, and as a fraud detection method. It is a mandatory process that is regulated and set mandatory by Bank Indonesia.

Before starting any transaction process involving virtual account, one party need to do get access token activity before hitting the API to the other (e.g merchant want to hit create VA API to DOKU, then merchant need to hit the get access token API and granted the access token.

{% hint style="info" %}
For Virtual Account use : B2B Token
{% endhint %}

{% hint style="info" %}
For Direct Debit use : B2B Token and B2C Token
{% endhint %}

{% hint style="info" %}
For e-Wallet use : B2B Token and B2C Token
{% endhint %}

In the header request, there is an object called X-SIGNATURE that needs encryption of combination signature, to learn more about the usage, you can check here [Signature from API Get Method](/get-started-with-doku-api/signature-component/non-snap/signature-from-api-get-method)


# B2B

How to generate token B2B

### API Endpoint

To get access token, you need to hit this API endpoint :&#x20;

<table><thead><tr><th>Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>73</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/authorization/v1/access-token/b2b`
</code></pre></td></tr></tbody></table>

### API Request Header to get Token

```json
X-SIGNATURE: Pxlv2IIUVdlzdUnbSQqug8YeghmKXJ7Rw5P4xBOOB/tC457UsoZXkO4S1R3oszVcjZDSh38+==
X-TIMESTAMP: 2022-10-07T14:18:39+07:00
X-CLIENT-KEY: MCH-0008-1296507211683
Content-Type: application/json
```

#### Request Header Explanation&#x20;

<table><thead><tr><th>Parameter</th><th>Data Type</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>X-Signature</td><td><p></p><pre class="language-json"><code class="lang-json"><strong>string
</strong></code></pre></td><td>Mandatory</td><td>Non-Repudiation &#x26; Integrity checking X-Signature : with asymmetric signature algorithm SHA256withRSA (Private_Key, stringToSign)<br><br><code>stringToSign = client_ID + “|” + X- TIMESTAMP</code></td></tr><tr><td>X-Timestamp</td><td><p></p><pre class="language-json"><code class="lang-json">string
</code></pre></td><td>Mandatory</td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7.<br><br>Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td>X- Client-Key</td><td><p></p><pre class="language-json"><code class="lang-json">string
</code></pre></td><td>Mandatory</td><td><ol><li>Client’s client_id (PJP Name) (given at completion registration process)</li><li>Merchant to DOKU : client_id merchant</li></ol><p></p><pre class="language-json" data-overflow="wrap"><code class="lang-json">Acquirer to DOKU : client_key given by DOKU
</code></pre><pre class="language-mdx" data-overflow="wrap"><code class="lang-mdx">DOKU to Acquirer : client_key given by acquirer.
</code></pre></td></tr><tr><td>content-type</td><td><p></p><pre class="language-json"><code class="lang-json">string
</code></pre></td><td>Mandatory</td><td>String represents indicate the media type of the resource (e.g. application/json, application/pdf)</td></tr></tbody></table>

### API Request Body

Here is the sample of request body to Get Token :&#x20;

````json
{
"grantType":"client_credentials"
}
```
````

#### Request Body Explanation

<table><thead><tr><th>Parameter</th><th>Data Type</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><p></p><pre class="language-json"><code class="lang-json">grantType
</code></pre></td><td>String</td><td>Mandatort</td><td>“client_credentials” : The client can request an access token using only its client credentials (or other supported means of authentication) when the client is requesting access to the protected resources under its control (OAuth 2.0: RFC 6749 &#x26; 6750)</td></tr></tbody></table>

### API Response Body

#### API Response Header

After hitting the above API Request, DOKU will give the response below

| Type        | Value   |
| ----------- | ------- |
| HTTP Status | 200     |
| Result      | Success |

```json
X-CLIENT-KEY: "MCH-0008-1296507211683",
X-TIMESTAMP: "2022-10-07T14:26:50+07:00"
```

<table><thead><tr><th>Parameter</th><th>Data Type</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>X-Timestamp</td><td>String</td><td>Mandatory</td><td>Client's current local time in YYYY-MM-DDTHH:mm:ssZ format</td></tr><tr><td>X-Client-Key</td><td>String</td><td>Mandatory</td><td><p>Client’s client_id (PJP Name) (given at completion registration process)</p><p></p><pre class="language-mdx"><code class="lang-mdx">Merchant to DOKU : client_id merchant.
</code></pre><pre class="language-mdx"><code class="lang-mdx">DOKU to Acquirer : client_key given by acquirer.
</code></pre><pre class="language-mdx"><code class="lang-mdx">Acquirer to DOKU : client_key given by DOKU
</code></pre></td></tr></tbody></table>

#### API Response Body

```json
{
    "responseCode": "2007300",
    "responseMessage": "Successful",
    "accessToken": "eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2NjUxMjc3OTEsIm5iZiI6MTY2NTEyNjg5MSwiaXNzIjoiRE9LVSIsImlhdCI6",
    "tokenType": "Bearer",
    "expiresIn": 900,
    "additionalInfo": ""
}
```

<table><thead><tr><th>Parameter</th><th>Data Type</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><p></p><pre class="language-json"><code class="lang-json">responseCode
</code></pre></td><td>String (6)</td><td>Mandatory</td><td><p>Response Code : </p><pre class="language-json"><code class="lang-json">HTTP status code + service code + case code
</code></pre></td></tr><tr><td><p></p><pre class="language-json"><code class="lang-json">responseMessage
</code></pre></td><td>String</td><td>Mandatory</td><td>Response Description</td></tr><tr><td><p></p><pre class="language-json"><code class="lang-json">accessToken
</code></pre></td><td>String (2048)</td><td>Mandatory</td><td>A string representing an authorization issued to the client that used to access protected resources.</td></tr><tr><td><p></p><pre class="language-json"><code class="lang-json">tokenType
</code></pre></td><td>String</td><td>Mandatory</td><td>The access token type provides the client with the information required to successfully utilize the access token to make a protected resource request (along with type-specific attributes).<br><br>Token Type Value: “Bearer”: includes the access token.<br><br>string in the request “Mac”: issuing a Message.<br><br>Authentication Code (MAC) key together with the access token that is used to sign certain components of the HTTP requests. Reference: OAuth2.0 RFC 6749 &#x26; 6750</td></tr><tr><td><p></p><pre class="language-json"><code class="lang-json">expiresIn
</code></pre></td><td>String</td><td>Mandatory</td><td>Session expiry in seconds : 900 (15 minute )</td></tr><tr><td><p></p><pre class="language-json"><code class="lang-json">additionalInfo
</code></pre></td><td>String</td><td>Optional</td><td>Additional Information</td></tr></tbody></table>

#### Error Response

For several error cases, the response appear would be like below :&#x20;

{% tabs %}
{% tab title="X-Timestamp format no valid" %}

```json
"responseCode": "4017300",
"responseMessage": "Unauthorized. Unknown Client"
```

{% endtab %}

{% tab title="Signature not valid" %}

```json
"responseCode": "4017300",
"responseMessage": "Unauthorized. Signature"
```

{% endtab %}

{% tab title="X-Client Key not authorized" %}

````json
"responseCode": "4017300",
    "responseMessage": "Unauthorized. Unknown Client"
```
````

{% endtab %}
{% endtabs %}


# B2B2C

### API Endpoint

To get access token, you need to hit this API endpoint :&#x20;

<table><thead><tr><th>Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>74</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/authorization/v1/access-token/b2b2c
</code></pre></td></tr></tbody></table>

### API Request Header to get Token

```json
X-SIGNATURE: Pxlv2IIUVdlzdUnbSQqug8YeghmKXJ7Rw5P4xBOOB/tC457UsoZXkO4S1R3oszVcjZDSh38+==
X-TIMESTAMP: 2022-10-07T14:18:39+07:00
X-CLIENT-KEY: MCH-0008-1296507211683
Content-Type: application/json
```

#### Request Header Explanation&#x20;

<table><thead><tr><th>Parameter</th><th>Data Type</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>X-Signature</td><td><p></p><pre class="language-json"><code class="lang-json"><strong>string
</strong></code></pre></td><td>Mandatory</td><td>Non-Repudiation &#x26; Integrity checking X-Signature : with asymmetric signature algorithm SHA256withRSA (Private_Key, stringToSign)<br><br><code>stringToSign = client_ID + “|” + X- TIMESTAMP</code></td></tr><tr><td>X-Timestamp</td><td><p></p><pre class="language-json"><code class="lang-json">string
</code></pre></td><td>Mandatory</td><td>Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed transaction on UTC+7 (WIB), merchant need to subtract time with 7.<br><br>Ex: to proceed transaction on September 22th 2020 at 08:51:00 WIB, the timestamp should be 2020-09-22T01:51:00Z</td></tr><tr><td>X- Client-Key</td><td><p></p><pre class="language-json"><code class="lang-json">string
</code></pre></td><td>Mandatory</td><td><ol><li>Client’s client_id (PJP Name) (given at completion registration process)</li><li>Merchant to DOKU : client_id merchant</li></ol><p></p><pre class="language-json" data-overflow="wrap"><code class="lang-json">Acquirer to DOKU : client_key given by DOKU
</code></pre><pre class="language-mdx" data-overflow="wrap"><code class="lang-mdx">DOKU to Acquirer : client_key given by acquirer.
</code></pre></td></tr><tr><td>content-type</td><td><p></p><pre class="language-json"><code class="lang-json">string
</code></pre></td><td>Mandatory</td><td>application/json</td></tr></tbody></table>

### API Request Body

Here is the sample of request body to Get Token :&#x20;

```json
{
   "grantType":"authorization_code",
   "authCode":"a6975f82-d00a-4ddc-9633-087fefb6275e",
   "refreshToken":"83a58570-6795-11ec-90d6-0242ac120003",
   "additionalInfo":{
  
   }
}
```

#### Request Body Explanation

<table><thead><tr><th>Parameter</th><th>Data Type</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><p></p><pre class="language-json"><code class="lang-json">grantType
</code></pre></td><td>String</td><td>Mandatory</td><td><p>There are 2 options for grantType </p><ol><li>authorization_code </li><li>refresh_token</li></ol><p>Use this for get token B2B2C</p></td></tr><tr><td><pre><code>authCode
</code></pre></td><td>String</td><td>Conditional</td><td>The authorization code received after the User provides the consent. Mandatory if grantType = AUTHORIZATION_CODE</td></tr><tr><td><p></p><pre class="language-mdx"><code class="lang-mdx">refreshToken
</code></pre></td><td>String</td><td>Conditional</td><td>Refresh token to get a new accessToken where the User doesn't need to provide the consent again. Mandatory if grantType = REFRESH_TOKEN. Refresh Token should be less than access token validity and will be manage by the PJP’s application to generate a new access_token</td></tr><tr><td><p></p><pre class="language-json"><code class="lang-json">additionalInfo
</code></pre></td><td>Object</td><td>Optional</td><td>Additional Information</td></tr></tbody></table>

### API Response Body

#### API Response Header

After hitting the above API Request, DOKU will give the response below

| Type        | Value   |
| ----------- | ------- |
| HTTP Status | 200     |
| Result      | Success |

```json
X-CLIENT-KEY: "MCH-0008-1296507211683",
X-TIMESTAMP: "2022-10-07T14:26:50+07:00"
```

<table><thead><tr><th>Parameter</th><th>Data Type</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>X-Timestamp</td><td>String</td><td>Mandatory</td><td>Client's current local time in YYYY-MM-DDTHH:mm:ssZ format</td></tr><tr><td>X-Client-Key</td><td>String</td><td>Mandatory</td><td><p>Client’s client_id (PJP Name) (given at completion registration process)</p><p></p><pre class="language-mdx"><code class="lang-mdx">Merchant to DOKU : client_id merchant.
</code></pre><pre class="language-mdx"><code class="lang-mdx">DOKU to Acquirer : client_key given by acquirer.
</code></pre><pre class="language-mdx"><code class="lang-mdx">Acquirer to DOKU : client_key given by DOKU
</code></pre></td></tr></tbody></table>

#### API Response Body

```json
{
   "responseCode":"2007400",
   "responseMessage":"Successful",
   "accessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIyMTFlZThiMi1hN2FlLTRhZGUtYmJlYS1mNzI3MDk3ZmQ0NmEiLCJjbGllbnRJZCI6IjZhZTk1N2M0LTI4NjMtNDcxMy1hY2NlLWJhMTJkZTYzNmNmYyIsIm5iZiI6MTYxMTQ2ODk3OCwiZXhwIjoxNjExNDY5ODc4LCJpYXQiOjE2MTE0Njg5Nzh9.KM7yz9GvuUaDR1bXwei4iO0h4e3g4o1Hct5Ie9VoBdo",
   "tokenType":"Bearer",
   "accessTokenExpiryTime":"2020-01-01T00:00:00+07:00",
   "refreshToken":"57d21fe3-ba9c-4f2d-9fde-eae669bbf80d",
   "refreshTokenExpiryTime":"2020-01-01T00:00:00+07:00",
   "additionalInfo":{
   }
}
```

<table><thead><tr><th>Parameter</th><th>Data Type</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><p></p><pre class="language-json"><code class="lang-json">responseCode
</code></pre></td><td>String (6)</td><td>Mandatory</td><td><p>Response Code : </p><pre class="language-json"><code class="lang-json">HTTP status code + service code + case code
</code></pre></td></tr><tr><td><p></p><pre class="language-json"><code class="lang-json">responseMessage
</code></pre></td><td>String</td><td>Mandatory</td><td>Response Description</td></tr><tr><td><p></p><pre class="language-json"><code class="lang-json">accessToken
</code></pre></td><td>String (2048)</td><td>Mandatory</td><td>A string representing an authorization issued to the client that used to access protected resources.</td></tr><tr><td><p></p><pre class="language-json"><code class="lang-json">tokenType
</code></pre></td><td>String</td><td>Mandatory</td><td>The access token type provides the client with the information required to successfully utilize the access token to make a protected resource request (along with type-specific attributes).<br><br>Token Type Value: “Bearer”: includes the access token.<br><br>string in the request “Mac”: issuing a Message.<br><br>Authentication Code (MAC) key together with the access token that is used to sign certain components of the HTTP requests. Reference: OAuth2.0 RFC 6749 &#x26; 6750</td></tr><tr><td><p></p><pre class="language-json"><code class="lang-json">accessTokenExpiryTime
</code></pre></td><td>String</td><td>Mandatory</td><td>Session expiry in seconds : 900 (15 minute )</td></tr><tr><td><p></p><pre class="language-json"><code class="lang-json">refreshToken
</code></pre></td><td>String</td><td>Mandatory</td><td>A random string that can be used by specific client to get a refreshed accessToken to prolong the access to the User's resources.</td></tr><tr><td><p></p><pre class="language-json"><code class="lang-json">refreshTokenExpiryTime
</code></pre></td><td>String</td><td>Mandatory</td><td>A random string that can be used by specific client to get a refreshed accessToken to prolong the access to the User's resources.</td></tr><tr><td><p></p><pre class="language-json"><code class="lang-json">additionalInfo
</code></pre></td><td>String</td><td>Optional</td><td>Additional Information</td></tr></tbody></table>

#### Error Response

For several error cases, the response appear would be like below :&#x20;

{% tabs %}
{% tab title="X-Timestamp format no valid" %}

```json
"responseCode": "4017400",
"responseMessage": "Unauthorized. Unknown Client"
```

{% endtab %}

{% tab title="Signature not valid" %}

```json
"responseCode": "4017400",
"responseMessage": "Unauthorized. Signature"
```

{% endtab %}

{% tab title="X-Client Key not authorized" %}

````json
"responseCode": "4017400",
    "responseMessage": "Unauthorized. Unknown Client"
```
````

{% endtab %}
{% endtabs %}


# Virtual Account

DOKU provides various payment channels. One of the most used by our merchants is Virtual Account. By using this payment channels, your customer can pay their order through bank transfer and DOKU will notify you once the payment is completed by your customer. DOKU has partnered with various banks to help you provide many payment options for your customers.

## Features for Virtual Account

{% hint style="info" %}
**Virtual Account Number Component**

Virtual Account number which is displayed to customer, contains two parts.\
**The first part** is the company code (BIN) and **the second part** is unique VA Number.
{% endhint %}

There are 2 types of general features that can be used with Virtual Accounts :&#x20;

1. **Register** : The VA number will be registered to DOKU and Acquirer will inquiry to our side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)

| Feature Type                             | Description                                                                                                                                                                                                                                             |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DOKU Generated Payment Code ( DGPC )     | <p>Merchants don’t need to generate payment code, just need to request from DOKU and DOKU will send a unique payment code.<br><br>Component VA Number : <code>BIN</code> and <code>Unique VA Number</code>. Suitable for e-commerce business model.</p> |
| Merchant Generated Payment Code ( MGPC ) | <p>Merchants can generate payment codes with their own rules, and send the code to DOKU and customers will use it for payment.<br><br>Component VA Number : <code>BIN</code> and <code>Unique VA Number</code>. Suitable for top up business model.</p> |

2. **Direct Inquiry ( DIPC ) :** The VA number is registered on merchant side and DOKU will forward Acquirer inquiry request to merchant side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.). Component VA Number : `BIN` and `Unique VA Number`.

{% hint style="warning" %}
**ONE TRANSACTION CAN'T USE 2 OR 3 FEATURES AT THE SAME TIME.**

By default, DOKU will register your business with Doku Generate Payment Code feature which means BIN for VA will be generated by DOKU side. But there is no limit for you to be able to use 2 features at the same time. **What it can't do is that 1 transaction uses 2 features at the same time.**
{% endhint %}

{% hint style="success" %}
**GET THE BIN**

If you want to use MGPC or DIPC, then please contact the care team to get a BIN as a component for the VA Number.
{% endhint %}

## Billing Type

Billing type is a type of feature used by merchants to determine the method of payment for their customers when they are in Inquiry. In case, the customer can input the amount according to their expected amount or the customer can also pay according to the amount that has been determined by the merchant.&#x20;

Here is a billing type and their defenition that can be implemented into virtual account transactions.

<table><thead><tr><th>Billing Type</th><th>Description</th></tr></thead><tbody><tr><td><p></p><pre class="language-json"><code class="lang-json">FIX_BILL
</code></pre></td><td>Customer can only pay the bill with the amount stated in the bill (Closed Amount / Full Payment).</td></tr><tr><td><p></p><pre class="language-json"><code class="lang-json">NO_BILL
</code></pre></td><td>Customer can pay with their amount and Virtual Account can accept payments for any nominal value.</td></tr><tr><td><p></p><pre class="language-json"><code class="lang-json">BILL_VARIABLE_AMOUNT
</code></pre></td><td>Customer can pay according to the amount they want or randomly in a predetermined range.</td></tr><tr><td><pre><code>PARTIAL_AMOUNT
</code></pre></td><td>Customer can pay according to the amount they want in a predetermined amount stated in the bill.</td></tr></tbody></table>

#### Applicable for Channel

For your information, each acquirer has its own rules. There is an Acquirer that doesn't support billing type. Here's the checklist :&#x20;

| Bank        | Fix Bill | No Bill | Bill Variable Amount | Partial Amount |
| ----------- | -------- | ------- | -------------------- | -------------- |
| BCA VA      | ✅        | ✅       | ✅                    | ❌              |
| MANDIRI VA  | ✅        | ✅       | ❌                    | ❌              |
| BRI VA      | ✅        | ✅       | ❌                    | ❌              |
| BNI VA      | ✅        | ✅       | ❌                    | ✅              |
| PERMATA VA  | ✅        | ✅       | ❌                    | ❌              |
| CIMB VA     | ✅        | ✅       | ❌                    | ✅              |
| DANAMON VA  | ✅        | ✅       | ❌                    | ✅              |
| DOKU VA     | ✅        | ✅       | ❌                    | ❌              |
| MAYBANK VA  | ✅        | ✅       | ❌                    | ❌              |
| BTN VA      | ✅        | ✅       | ❌                    | ❌              |
| BNC VA      | ✅        | ✅       | ❌                    | ❌              |
| BSS VA      | ✅        | ✅       | ❌                    | ❌              |
| BJB VA      | ✅        | ✅       | ❌                    | ❌              |
| SINARMAS VA | ✅        | ❌       | ❌                    | ❌              |

{% hint style="info" %}
BNI Only

BNI have a special rules, billing type for BNI are OPEN, FIXED, INSTALLMENT, MIN, OPEN MIN and OPEN MAX. You can see the detail, in BNI Section.
{% endhint %}

## BIN Rules

In accordance with the explanation regarding the Virtual Account Component, BIN is one of the components to create a virtual account. So, here's an explanation regarding BIN rules and adapt them to your needs.

{% hint style="info" %}
**Note**

These rules only apply to Aggregator Partnership Models, which means merchants use DOKU's BIN.
{% endhint %}

<details>

<summary><strong>BCA VA</strong></summary>

For Virtual Account That DOKU Generated(DGPC), the Length is 16 digits\
For Virtual Account That Merchant Generated(MGPC & DIPC), The Max Length is 23 digits

| Partnership Model | BIN Type       | Description                                                                                                                | VA Number Component                                                         | Feature                                                       |
| ----------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Aggregator        | DOKU General   | DOKU's BIN in Acquirer, that DOKU provide for merchants to use                                                             | DOKU General BIN (6 digit) + DOKU Generated Payment Code (10 digit)         | DOKU Generated Payment Code (DGPC)                            |
| Aggregator        | DOKU Exclusive | DOKU's BIN in Acquirer, that DOKU provides only for 1 merchant to use. Please contact sales team to get DOKU Exclusive BIN | DOKU Exclusive BIN (range. 8-9 digit) + Free Digit (max range. 15-14 digit) | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |
| Direct            | Direct         | Merchant’s Acquirer BIN. Please contact sales team to get Direct BIN from Acquirer                                         | Merchant’s Acquirer BIN (5 digit) + Free Digit (max. 18 digit)              | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |

</details>

<details>

<summary><strong>BRI VA</strong></summary>

For Virtual Account That DOKU Generated(DGPC), the Length is 16 digits\
For Virtual Account That Merchant Generated(MGPC & DIPC), The Max Length is 18 digits

| Partnership Model | BIN Type       | Description                                                                                                                | VA Number Component                                                        | Feature                                                       |
| ----------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Aggregator        | DOKU General   | DOKU's BIN in Acquirer, that DOKU provide for merchants to use                                                             | DOKU General BIN (6 digit) + DOKU Generated Payment Code (10 digit)        | DOKU Generated Payment Code (DGPC)                            |
| Aggregator        | DOKU Exclusive | DOKU's BIN in Acquirer, that DOKU provides only for 1 merchant to use. Please contact sales team to get DOKU Exclusive BIN | DOKU Exclusive BIN (range. 7-9 digit) + Free Digit (max range. 11-9 digit) | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |
| Direct            | Direct         | Merchant’s Acquirer BIN. Please contact sales team to get Direct BIN from Acquirer                                         | Merchant’s Acquirer BIN (5 digit) + Free Digit (max. 13 digit)             | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |

</details>

<details>

<summary><strong>Mandiri VA</strong></summary>

For Virtual Account That DOKU Generated(DGPC), the Length is 16 digits\
For Virtual Account That Merchant Generated(MGPC & DIPC), The Max Length is 16 digits

| Partnership Model | BIN Type       | Description                                                                                                                | VA Number Component                                                       | Feature                                                       |
| ----------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Aggregator        | DOKU General   | DOKU's BIN in Acquirer, that DOKU provide for merchants to use                                                             | DOKU General BIN (8 digit) + DOKU Generated Payment Code (8 digit)        | DOKU Generated Payment Code (DGPC)                            |
| Aggregator        | DOKU Exclusive | DOKU's BIN in Acquirer, that DOKU provides only for 1 merchant to use. Please contact sales team to get DOKU Exclusive BIN | DOKU Exclusive BIN (range. 7-9 digit) + Free Digit (max range. 9-7 digit) | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |
| Direct            | Direct         | Merchant’s Acquirer BIN. Please contact sales team to get Direct BIN from Acquirer                                         | Merchant’s Acquirer BIN (5 digit) + Free Digit (max. 11 digit)            | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |

</details>

<details>

<summary><strong>BNI VA</strong></summary>

For Virtual Account That DOKU Generated(DGPC), the Length is 16 digits\
For Virtual Account That Merchant Generated(MGPC & DIPC), The Max Length is 28 digits

| Partnership Model | BIN Type       | Description                                                                                                                | VA Number Component                                                           | Feature                                                       |
| ----------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Aggregator        | DOKU General   | DOKU's BIN in Acquirer, that DOKU provide for merchants to use                                                             | DOKU General BIN (9 digit) + DOKU Generated Payment Code (7 digit)            | DOKU Generated Payment Code (DGPC)                            |
| Aggregator        | DOKU Exclusive | DOKU's BIN in Acquirer, that DOKU provides only for 1 merchant to use. Please contact sales team to get DOKU Exclusive BIN | DOKU Exclusive BIN (range. 10-13 digit) + Free Digit (max range. 18-15 digit) | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |
| Direct            | Direct         | Merchant’s Acquirer BIN. Please contact sales team to get Direct BIN from Acquirer                                         | Merchant’s Acquirer BIN (8 digit) + Free Digit (max. 20 digit)                | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |

</details>

<details>

<summary><strong>Permata VA</strong></summary>

For Virtual Account That DOKU Generated(DGPC), the Length is 16 digits\
For Virtual Account That Merchant Generated(MGPC & DIPC), The Max Length is 16 digits

| Partnership Model | BIN Type       | Description                                                                                                                | VA Number Component                                                        | Feature                                                       |
| ----------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Aggregator        | DOKU General   | DOKU's BIN in Acquirer, that DOKU provide for merchants to use                                                             | DOKU General BIN (5 digit) + DOKU Generated Payment Code (11 digit)        | DOKU Generated Payment Code (DGPC)                            |
| Aggregator        | DOKU Exclusive | DOKU's BIN in Acquirer, that DOKU provides only for 1 merchant to use. Please contact sales team to get DOKU Exclusive BIN | DOKU Exclusive BIN (range. 6-8 digit) + Free Digit (max range. 10-8 digit) | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |
| Direct            | Direct         | Merchant’s Acquirer BIN. Please contact sales team to get Direct BIN from Acquirer                                         | Merchant’s Acquirer BIN (4 digit) + Free Digit (max. 12 digit)             | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |

</details>

<details>

<summary><strong>Danamon VA</strong></summary>

For Virtual Account That DOKU Generated(DGPC), the Length is 16 digits\
For Virtual Account That Merchant Generated(MGPC & DIPC), The Max Length is 16 digits

| Partnership Model | BIN Type       | Description                                                                                                                | VA Number Component                                                        | Feature                                                       |
| ----------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Aggregator        | DOKU General   | DOKU's BIN in Acquirer, that DOKU provide for merchants to use                                                             | DOKU General BIN (5 digit) + DOKU Generated Payment Code (11 digit)        | DOKU Generated Payment Code (DGPC)                            |
| Aggregator        | DOKU Exclusive | DOKU's BIN in Acquirer, that DOKU provides only for 1 merchant to use. Please contact sales team to get DOKU Exclusive BIN | DOKU Exclusive BIN (range. 6-8 digit) + Free Digit (max range. 10-8 digit) | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |
| Direct            | Direct         | Merchant’s Acquirer BIN. Please contact sales team to get Direct BIN from Acquirer                                         | Merchant’s Acquirer BIN (4 digit) + Free Digit (max. 12 digit)             | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |

</details>

<details>

<summary><strong>CIMB VA</strong></summary>

For Virtual Account That DOKU Generated(DGPC), the Length is 16 digits\
For Virtual Account That Merchant Generated(MGPC & DIPC), The Max Length is 16 digits

| Partnership Model | BIN Type       | Description                                                                                                                | VA Number Component                                                        | Feature                                                       |
| ----------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Aggregator        | DOKU General   | DOKU's BIN in Acquirer, that DOKU provide for merchants to use                                                             | DOKU General BIN (5 digit) + DOKU Generated Payment Code (11 digit)        | DOKU Generated Payment Code (DGPC)                            |
| Aggregator        | DOKU Exclusive | DOKU's BIN in Acquirer, that DOKU provides only for 1 merchant to use. Please contact sales team to get DOKU Exclusive BIN | DOKU Exclusive BIN (range. 6-8 digit) + Free Digit (max range. 10-8 digit) | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |
| Direct            | Direct         | Merchant’s Acquirer BIN. Please contact sales team to get Direct BIN from Acquirer                                         | Merchant’s Acquirer BIN (4 digit) + Free Digit (max. 12 digit)             | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |

</details>

<details>

<summary><strong>BTN VA</strong></summary>

For Virtual Account That DOKU Generated(DGPC), the Length is 16 digits\
For Virtual Account That Merchant Generated(MGPC & DIPC), The Max Length is 19 digits

| Partnership Model | BIN Type       | Description                                                                                                                | VA Number Component                                                         | Feature                                                       |
| ----------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Aggregator        | DOKU General   | DOKU's BIN in Acquirer, that DOKU provide for merchants to use                                                             | DOKU General BIN (6 digit) + DOKU Generated Payment Code (10 digit)         | DOKU Generated Payment Code (DGPC)                            |
| Aggregator        | DOKU Exclusive | DOKU's BIN in Acquirer, that DOKU provides only for 1 merchant to use. Please contact sales team to get DOKU Exclusive BIN | DOKU Exclusive BIN (range. 8-9 digit) + Free Digit (max range. 11-10 digit) | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |
| Direct            | Direct         | Merchant’s Acquirer BIN. Please contact sales team to get Direct BIN from Acquirer                                         | Merchant’s Acquirer BIN (5 digit) + Free Digit (max. 14 digit)              | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |

</details>

<details>

<summary><strong>DOKU VA</strong></summary>

For Virtual Account That DOKU Generated(DGPC), the Length is 16 digits\
For Virtual Account That Merchant Generated(MGPC & DIPC), The Max Length is 16 digits

| Partnership Model | BIN Type       | Description                                                                                                                | VA Number Component                                                       | Feature                                                       |
| ----------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Aggregator        | DOKU General   | DOKU's BIN in Acquirer, that DOKU provide for merchants to use                                                             | DOKU General BIN (2 digit) + DOKU Generated Payment Code (14 digit)       | DOKU Generated Payment Code (DGPC)                            |
| Aggregator        | DOKU Exclusive | DOKU's BIN in Acquirer, that DOKU provides only for 1 merchant to use. Please contact sales team to get DOKU Exclusive BIN | DOKU Exclusive BIN (range. 3-8 digit) + Free Digit (max range.13-8 digit) | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |

</details>

<details>

<summary><strong>Maybank VA</strong></summary>

For Virtual Account That DOKU Generated(DGPC), the Length is 16 digits\
For Virtual Account That Merchant Generated(MGPC & DIPC), The Max Length is 16 digits

| Partnership Model | BIN Type       | Description                                                                                                                | VA Number Component                                                       | Feature                                                       |
| ----------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Aggregator        | DOKU General   | DOKU's BIN in Acquirer, that DOKU provide for merchants to use                                                             | DOKU General BIN (6 digit) + DOKU Generated Payment Code (10 digit)       | DOKU Generated Payment Code (DGPC)                            |
| Aggregator        | DOKU Exclusive | DOKU's BIN in Acquirer, that DOKU provides only for 1 merchant to use. Please contact sales team to get DOKU Exclusive BIN | DOKU Exclusive BIN (range. 8-9 digit) + Free Digit (max range. 8-7 digit) | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |
| Direct            | Direct         | Merchant’s Acquirer BIN. Please contact sales team to get Direct BIN from Acquirer                                         | Merchant’s Acquirer BIN (5 digit) + Free Digit (max. 11 digit)            | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |

</details>

<details>

<summary><strong>BNC VA</strong></summary>

For Virtual Account That DOKU Generated(DGPC), the Length is 16 digits\
For Virtual Account That Merchant Generated(MGPC & DIPC), The Max Length is 19 digits

| Partnership Model | BIN Type       | Description                                                                                                                | VA Number Component                                                        | Feature                                                       |
| ----------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Aggregator        | DOKU General   | DOKU's BIN in Acquirer, that DOKU provide for merchants to use                                                             | DOKU General BIN (9 digit) + DOKU Generated Payment Code (7 digit)         | DOKU Generated Payment Code (DGPC)                            |
| Aggregator        | DOKU Exclusive | DOKU's BIN in Acquirer, that DOKU provides only for 1 merchant to use. Please contact sales team to get DOKU Exclusive BIN | DOKU Exclusive BIN (range.11-12 digit) + Free Digit (max range. 8-7 digit) | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |
| Direct            | Direct         | Merchant’s Acquirer BIN. Please contact sales team to get Direct BIN from Acquirer                                         | Merchant’s Acquirer BIN (8 digit) + Free Digit (max. 11 digit)             | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |

</details>

<details>

<summary><strong>BSS VA</strong></summary>

For Virtual Account That DOKU Generated(DGPC), the Length is 16 digits\
For Virtual Account That Merchant Generated(MGPC & DIPC), The Max Length is 16 digits

| Partnership Model | BIN Type       | Description                                                                                                                | VA Number Component                                                       | Feature                                                       |
| ----------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Aggregator        | DOKU General   | DOKU's BIN in Acquirer, that DOKU provide for merchants to use                                                             | DOKU General BIN (6 digit) + DOKU Generated Payment Code (10 digit)       | DOKU Generated Payment Code (DGPC)                            |
| Aggregator        | DOKU Exclusive | DOKU's BIN in Acquirer, that DOKU provides only for 1 merchant to use. Please contact sales team to get DOKU Exclusive BIN | DOKU Exclusive BIN (range. 7-9 digit) + Free Digit (max range. 9-7 digit) | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |
| Direct            | Direct         | Merchant’s Acquirer BIN. Please contact sales team to get Direct BIN from Acquirer                                         | Merchant’s Acquirer BIN (5 digit) + Free Digit (max. 11 digit)            | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |

</details>

<details>

<summary><strong>BJB VA</strong></summary>

For Virtual Account That DOKU Generated(DGPC), the Length is 20 digits\
For Virtual Account That Merchant Generated(MGPC & DIPC), The Max Length is 20 digits

| Aggregator | DOKU General   | DOKU's BIN in Acquirer, that DOKU provide for merchants to use                                                             | DOKU General BIN (6 digit) + DOKU Generated Payment Code (14 digit)         | DOKU Generated Payment Code (DGPC)                            |
| ---------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Aggregator | DOKU Exclusive | DOKU's BIN in Acquirer, that DOKU provides only for 1 merchant to use. Please contact sales team to get DOKU Exclusive BIN | DOKU Exclusive BIN (range. 7-9 digit) + Free Digit (max range. 13-11 digit) | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |
| Direct     | Direct         | Merchant’s Acquirer BIN. Please contact sales team to get Direct BIN from Acquirer                                         | Merchant’s Acquirer BIN (5 digit) + Free Digit (max. 15 digit)              | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |

</details>

<details>

<summary><strong>Sinarmas VA</strong></summary>

For Virtual Account That DOKU Generated(DGPC), the Length is 16 digits\
For Virtual Account That Merchant Generated(MGPC & DIPC), The Max Length is 17 digits

| Partnership Model | BIN Type       | Description                                                                                                                | VA Number Component                                                       | Feature                                                       |
| ----------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Aggregator        | DOKU General   | DOKU's BIN in Acquirer, that DOKU provide for merchants to use                                                             | DOKU General BIN (6 digit) + DOKU Generated Payment Code (10 digit)       | DOKU Generated Payment Code (DGPC)                            |
| Aggregator        | DOKU Exclusive | DOKU's BIN in Acquirer, that DOKU provides only for 1 merchant to use. Please contact sales team to get DOKU Exclusive BIN | DOKU Exclusive BIN (range. 7-9 digit) + Free Digit (max range. 9-7 digit) | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |
| Direct            | Direct         | Merchant’s Acquirer BIN. Please contact sales team to get Direct BIN from Acquirer                                         | Merchant’s Acquirer BIN (5 digit) + Free Digit (max. 11 digit)            | Merchant Generated Payment Code (MGPC), Direct Inquiry (DIPC) |

</details>

## Reusable Status

Reusable Status is a parameter in API to indicate if Payment Code can be paid more than once, set this to true if merchants wish to enable it.

Here is a reusable status explanation. Set this value in the API, to implement reusable status.

<table><thead><tr><th>Value</th><th>Description</th></tr></thead><tbody><tr><td><p></p><pre class="language-json"><code class="lang-json">true
</code></pre></td><td>Payment Code can be paid more than once</td></tr><tr><td><p></p><pre class="language-json"><code class="lang-json">false
</code></pre></td><td>Payment Code can only be paid once</td></tr></tbody></table>

{% hint style="info" %}
Note

By default, DOKU will set the value to `false`, if you don't send this parameter on request.
{% endhint %}

***

### What's next? <a href="#whats-next" id="whats-next"></a>

You can learn more about how to integrate to each payment channels you wish by clicking the menu on the sidebar.


# BJB Virtual Account

DOKU has partnered with various banks and one of them is BJB to provide Virtual Account Payment. Learn more about how DOKU can help you integrate with BJB Virtual Account here.

### Integration methods[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/bca-va-guide#integration-methods) <a href="#integration-methods" id="integration-methods"></a>

There are two methods to integrate with BJB VA:

1. **Create VA**: The VA number will be registered to DOKU and Acquirer will inquiry to our side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)
   1. **DOKU Generated Payment Code (DGPC)**: The VA number is generated by DOKU. Suitable for e-commerce business model.
   2. **Merchant Generated Payment Code (MGPC)**: The VA number is generated by Merchant. Suitable for top up business model.
2. **Direct Inquiry (DIPC)**: The VA number is registered on merchant side and DOKU will forward Acquirer inquiry request to merchant side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)

## Integration Steps

#### Precondition&#x20;

{% hint style="info" %}
Get Token API

As client who hit DOKU's API such as Create VA, you need to obtain an access token first. Learn how to do it in this [section](/accept-payments/direct-api/snap/integration-guide/get-token-api).&#x20;
{% endhint %}

{% hint style="info" %}
Generate Signature

`X- SIGNATURE` is a security parameter that needs to be generated on merchant's Backend to verify the request authenticity.

So, it's very crucial for merchant to generate the X-SIGNATURE. Learn how to do it in this [section](/get-started-with-doku-api/signature-component/snap)
{% endhint %}

Here is the overview of how to integrate with Virtual Account:

1. [Create Virtual Account](#id-1.-create-va)

   [a. DOKU Generate Payment Code](#a.-doku-generate-payment-code)

   [b. Merchant Generate Payment Code](#b.-merchant-generate-payment-code)

   [c. Display Virtual Account](#c.-display-virtual-account)

   [d. Acknowledge Payment Result](#d.-acknowledge-payment-result)

   [e. Hit DOKU Check Status API](#e.-hit-doku-check-status-api)

   [f. Delete Virtual Account](#f.-delete-payment-code)

   [g. Update Virtual Account](#g.-update-payment-code)

***

### 1. Create VA

To create VA, you will need to hit this API through your Backend:

#### API Endpoint

<table><thead><tr><th width="234">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>27</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va
</code></pre></td></tr></tbody></table>

Here is the sample request header, request body and response body for BJB VA&#x20;

#### a. DOKU Generate Payment Code

Check this flow diagram to get know about this method

<div align="center" data-full-width="true"><figure><img src="/files/QRd0nhEfCWjmZzOexSvn" alt=""><figcaption><p>DOKU Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="109">Type</th><th width="131">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

## DOKU Generate Payment Code

> DOKU Generate Payment Code

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - CREATE VA DGPC SNAP","version":"1.0.0"},"servers":[{"description":"Sandbox","url":"https://api-sandbox.doku.com"},{"description":"Production","url":"https://api.doku.com"}],"paths":{"/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va":{"post":{"tags":["DOKU Generate Payment Code"],"summary":"DOKU Generate Payment Code","operationId":"createVA","description":"DOKU Generate Payment Code","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM-ddTHH:mm:ssZ format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVASNAPRequest"}}},"description":"Create VA SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVASNAPResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"CreateVASNAPRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","virtualAccountTrxType","additionalInfo","totalAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"description":"Customer Name. | Mandatory | min length: 1 | max length: 255","type":"string"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"trxId":{"type":"string","description":"Invoice number in Partner system. | Mandatory | min length: 1 | max length: 64"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoCreateVARequestRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string","description":"Expiration date for Virtual Account. ISO-8601"}}},"TotalAmountRef":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | Mandatory |  min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency. | Mandatory | min length: 1 | max length: 3"}}},"AdditionalInfoCreateVARequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"virtualAccountConfig":{"$ref":"#/components/schemas/VirtualAccountConfig"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BANK_BJB"]},"VirtualAccountConfig":{"type":"object","required":["channel"],"properties":{"reusableStatus":{"type":"boolean","description":"Reusable Status For Virtual Account Transaction, value TRUE or FALSE"}}},"VirtualAccountTrxTypeRef":{"description":"Transaction ID in Partner system.  C (Closed Payment) &  O (Open Payment) | Mandatory | min length: 1 | max length: 1","type":"string"},"CreateVASNAPResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","totalAmount","additionalInfo","virtualAccountTrxType","expiredDate"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | Mandatory | min length: 1 | max length: 64"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoCreateVAResponseRef"}}}}},"AdditionalInfoCreateVAResponseRef":{"type":"object","required":["channel","howToPayApi","howToPayPage"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"howToPayPage":{"type":"string","description":"Step by step that will be used by customer for how to doing a payment | min length: 1 | max length: 256"},"howToPayApi":{"type":"string","description":"Step by step that will be used by customer for how to doing a payment. | min length: 1 | max length: 256"}}}}}}
```

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

#### b. Merchant Generate Payment Code

Check this flow diagram to get know about this method

<div data-full-width="true"><figure><img src="/files/WDqzMJbMrbkQivFtU5B9" alt=""><figcaption><p>Merchant Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th width="200">Parameter</th><th width="101">Type</th><th width="120">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtained from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

## Merchant Generate Payment Code

> Merchant Generate Payment Code

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - CREATE VA MGPC SNAP","version":"1.0.0"},"servers":[{"description":"Sandbox","url":"https://api-sandbox.doku.com"},{"description":"Production","url":"https://api.doku.com"}],"paths":{"/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va":{"post":{"tags":["Merchant Generate Payment Code"],"summary":"Merchant Generate Payment Code","operationId":"createVA","description":"Merchant Generate Payment Code","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM-ddTHH:mm:ssZ format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVASNAPRequest"}}},"description":"Create VA SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVASNAPResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"CreateVASNAPRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","virtualAccountTrxType","additionalInfo","totalAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"description":"Customer Name. | Mandatory | min length: 1 | max length: 255","type":"string"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"trxId":{"type":"string","description":"Invoice number in Partner system. | Mandatory | min length: 1 | max length: 64"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoCreateVARequestRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string","description":"Expiration date for Virtual Account. ISO-8601"}}},"TotalAmountRef":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | Mandatory |  min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency. | Mandatory | min length: 1 | max length: 3"}}},"AdditionalInfoCreateVARequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"virtualAccountConfig":{"$ref":"#/components/schemas/VirtualAccountConfig"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BANK_BJB"]},"VirtualAccountConfig":{"type":"object","properties":{"reusableStatus":{"type":"boolean","description":"Reusable Status For Virtual Account Transaction, value TRUE or FALSE"}}},"VirtualAccountTrxTypeRef":{"description":"Transaction ID in Partner system.  C (Closed Payment) &  O (Open Payment) | Mandatory | min length: 1 | max length: 1","type":"string"},"CreateVASNAPResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","totalAmount","additionalInfo","expiredDate"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | Mandatory | min length: 1 | max length: 64"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoCreateVAResponseRef"}}}}},"AdditionalInfoCreateVAResponseRef":{"type":"object","required":["channel","howToPayApi","howToPayPage"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"howToPayPage":{"type":"string","description":"Step by step that will be used by customer for how to doing a payment | min length: 1 | max length: 256"},"howToPayApi":{"type":"string","description":"Step by step that will be used by customer for how to doing a payment. | min length: 1 | max length: 256"}}}}}}
```

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

{% hint style="success" %}
**Pro Tips!**

1. You can also show payment instruction link to your customer by using `additionalInfo.howToPayPage`&#x20;
2. If you wish to customize the UI for the payment instruction, you can use the `additionalInfo.howToPayApi`
   {% endhint %}

#### c. Display Virtual Account

You can display the payment code to your customer by using `virtualAccountData.virtualAccountNo` that you retrieved from the API response.

#### d. Acknowledge payment result

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

## Payment Notification

> Payment Notification

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - Core System API","version":"1.0.0"},"servers":[{"description":"Merchant domain path url","url":"https://{merchant-domain}"}],"paths":{"/v1.2/transfer-va/payment":{"post":{"tags":["Payment Notification"],"summary":"Payment Notification","operationId":"paymentNotification","description":"Payment Notification","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationRequest"}}},"description":"Payment Notification SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"PaymentNotificationRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","totalAmount","paidAmount","channelCode"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | Mandatory | min length: 1 | max length: 64"},"channelCode":{"type":"string","description":"ChannelCOde ID in Partner system. | Optional | min length: 1 | max length: 4"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"},"paidAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"},"trxDateTime":{"type":"string","description":"DOKU's transaction date time"}}},"TotalAmountRef":{"type":"object","properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency | min length: 1 | max length: 3"}}},"AdditionalInfoRequestRef":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BANK_BJB"]},"PaymentNotificationResponse":{"type":"object","required":["responseCode","responseMessage","additionalInfo","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"additionalInfo":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","paymentRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"}}}}}}}}
```

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

#### f. Delete Payment Code

If you wish to delete your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="107">Type</th><th width="124">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

## Delete Payment Code

> Delete Payment Code

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - DELETE VA SNAP","version":"1.0.0"},"servers":[{"description":"Sandbox","url":"https://api-sandbox.doku.com"},{"description":"Production","url":"https://api.doku.com"},{"description":"UAT","url":"https://api-uat.doku.com"}],"paths":{"/virtual-accounts/bi-snap-va/v1.1/transfer-va/delete-va":{"delete":{"tags":["Delete Payment Code"],"summary":"Delete Payment Code","operationId":"deleteVA","description":"Delete Payment Code","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM-ddTHH:mm:ssZ format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteVASNAPRequest"}}},"description":"Delete VA SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteVASNAPResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"DeleteVASNAPRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","trxId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20","type":"string"},"virtualAccountNo":{"description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28","type":"string"},"trxId":{"type":"string","description":"Invoice number in Partner system. | Mandatory | min length: 1 | max length: 64"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoCreateVARequestRef"}}},"AdditionalInfoCreateVARequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BANK_BJB"]},"DeleteVASNAPResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | Mandatory | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccouantNo. | min length: 1 | max length: 28"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | min length: 1 | max length: 64"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDeleteVARef"}}}}},"AdditionalInfoDeleteVARef":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channel"},"virtualAccountConfig":{"type":"object","properties":{"status":{"type":"string","description":"Status for this VA. ACTIVE/INACTIVE | min length: 1 | max length: 20"}}}}}}}}
```

#### g. Update Payment Code

If you wish to update your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="106">Type</th><th width="125">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

## Update Payment Code

> Update Payment Code

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - UPDATE VA SNAP","version":"1.0.0"},"servers":[{"description":"Sandbox","url":"https://api-sandbox.doku.com"},{"description":"Production","url":"https://api.doku.com"},{"description":"UAT","url":"https://api-uat.doku.com"}],"paths":{"/virtual-accounts/bi-snap-va/v1.1/transfer-va/update-va":{"put":{"tags":["Update Payment Code"],"summary":"Update Payment Code","operationId":"updateVA","description":"Update Payment Code","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM-ddTHH:mm:ssZ format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVASNAPRequest"}}},"description":"Update VA SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVASNAPResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"UpdateVASNAPRequest":{"type":"object","required":["partnerServiceId","customerNo","trxId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20","type":"string"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"description":"Customer Name | min length: 1 | max length: 255","type":"string"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"trxId":{"type":"string","description":"Invoice number in Partner system. | Mandatory | min length: 1 | max length: 64"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoUpdateVARequestRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string","description":"Expiration date for Virtual Account. ISO-8601"}}},"TotalAmountRef":{"type":"object","properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency | min length: 1 | max length: 3"}}},"AdditionalInfoUpdateVARequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"virtualAccountConfig":{"type":"object","properties":{"status":{"type":"string","description":"Status for this VA. ACTIVE/INACTIVE | min length: 1 | max length: 20"}}}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BANK_BJB"]},"VirtualAccountTrxTypeRef":{"description":"Transaction ID in Partner system.  C (Closed Payment) &  O (Open Payment) | Mandatory | min length: 1 | max length: 1","type":"string"},"UpdateVASNAPResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | Mandatory | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","totalAmount","expiredDate"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | Mandatory | min length: 1 | max length: 64"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoUpdateVARequestRef"}}}}}}}}
```

***

### 2. Direct Inquiry

<table><thead><tr><th width="236">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>24</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/inquiry
</code></pre></td></tr></tbody></table>

Here is the overview of how to integrate Direct Inquiry BJB VA :&#x20;

2. [Direct Inquiry](#id-2.-direct-inquiry)

   a.  [Setup Inquiry URL on DOKU Dashboard](#a.-setup-inquiry-url-on-doku-dashboard)

   b. [Generate Payment Code on your End](#b.-generate-payment-code-on-your-end)

   c. [Receive Inquiry Request from DOKU](#c.-receive-inquiry-request-from-doku)

   d. [Acknowledge Payment Notification](#d.-acknowledge-payment-notification)

   e. [Hit DOKU Check Status API](#e.-hit-doku-check-status-api-1)

Check this flow to diagram to get know about this API :&#x20;

<div data-full-width="true"><figure><img src="/files/UFMZMMHHiaPNc6xvKFk1" alt=""><figcaption><p>Direct Inquiry</p></figcaption></figure></div>

To get Inquiry Request from DOKU,  you will need to hit this API through your Backend:

#### a. Setup Inquiry URL on DOKU Dashboard

To receive the inquiry request from DOKU. You must set your `Inquiry URL` to DOKU. Please contact our team for the setup.&#x20;

{% hint style="info" %}
Please inform the `Inquiry URL` for Sandbox environment and Production environment.
{% endhint %}

#### b. Generate Payment Code on your end

Generate payment is done in your system. The payment code length maximum is `23` digits.

#### c. Receive Inquiry Request from DOKU

Here is the sample request header, request body from DOKU

#### Request Header

<table data-full-width="false"><thead><tr><th width="192">Parameter</th><th width="122">Type</th><th width="131">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

## Direct Inquiry

> Direct Inquiry

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - CREATE VA DIPC SNAP","version":"1.0.0"},"servers":[{"description":"Merchant Domain","url":"https://{api-domain}"}],"paths":{"/v1.1/transfer-va/inquiry":{"post":{"tags":["Direct Inquiry"],"summary":"Direct Inquiry","operationId":"directInquiry","description":"Direct Inquiry","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM-ddTHH:mm:ssZ format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryRequest"}}},"description":"Direct Inquiry SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"DirectInquiryRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","trxDateInit","inquiryRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20","type":"string"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28"},"channelCode":{"description":"Channel code from bank | min length: 1 | max length: 10","type":"string"},"trxDateInit":{"type":"string","description":"Transaction date.  | Mandatory"},"language":{"description":"Language | min length: 1 | max length: 2","type":"string"},"inquiryRequestId":{"description":"Unique Inquiry request id. | Mandatory | min length: 1 | max length: 30","type":"string"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVARequestRef"}}},"AdditionalInfoDirectInquiyVARequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BANK_BJB"]},"DirectInquiryResponse":{"type":"object","required":["responseCode","responseMessage","additionalInfo","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVAResponseRef"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","inquiryRequestId","virtualAccountNo","virtualAccountName","virtualAccountTrxType","totalAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"inquiryRequestId":{"description":"Unique Inquiry request id | min length: 1 | max length: 30","type":"string"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"inquiryStatus":{"type":"string","description":"Status for this inquiry. (FAILED, SUCCESS, EXPIRED, USED, PAID, OPEN, INACTIVE, ACTIVE, REFUND) | min length: 1 | max length: 15"},"inquiryReason":{"$ref":"#/components/schemas/InquiryReasonRef"}}}}},"AdditionalInfoDirectInquiyVAResponseRef":{"type":"object","required":["channel","trxId"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"trxId":{"type":"string","description":"Invoice Number | min length: 1 | max length: 32"},"virtualAccountConfig":{"$ref":"#/components/schemas/VirtualAccountConfig"}}},"VirtualAccountConfig":{"type":"object","properties":{"reusableStatus":{"type":"boolean","description":"Reusable Status For Virtual Account Transaction, value TRUE or FALSE"}}},"TotalAmountRef":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | Mandatory |  min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency. | Mandatory | min length: 1 | max length: 3"}}},"VirtualAccountTrxTypeRef":{"description":"Transaction ID in Partner system.  C (Closed Payment) &  O (Open Payment) | Mandatory | min length: 1 | max length: 1","type":"string"},"InquiryReasonRef":{"type":"object","properties":{"english":{"type":"string","description":"Inquiry Reason in English | min length: 1 | max length: 18"},"indonesia":{"type":"string","description":"Inquiry Reason in Bahasa | min length: 1 | max length: 18"}}}}}}
```

#### d. Acknowledge payment notification

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

## Payment Notification

> Payment Notification

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - Core System API","version":"1.0.0"},"servers":[{"description":"Merchant domain path url","url":"https://{merchant-domain}"}],"paths":{"/v1.2/transfer-va/payment":{"post":{"tags":["Payment Notification"],"summary":"Payment Notification","operationId":"paymentNotification","description":"Payment Notification","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationRequest"}}},"description":"Payment Notification SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"PaymentNotificationRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","totalAmount","paidAmount","channelCode"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | Mandatory | min length: 1 | max length: 64"},"channelCode":{"type":"string","description":"ChannelCOde ID in Partner system. | Optional | min length: 1 | max length: 4"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"},"paidAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"},"trxDateTime":{"type":"string","description":"DOKU's transaction date time"}}},"TotalAmountRef":{"type":"object","properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency | min length: 1 | max length: 3"}}},"AdditionalInfoRequestRef":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BANK_BJB"]},"PaymentNotificationResponse":{"type":"object","required":["responseCode","responseMessage","additionalInfo","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"additionalInfo":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","paymentRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"}}}}}}}}
```

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

### Additional Feature

#### Open Amount&#x20;

DOKU supports open payment meaning that your customer can input their own payment amount. To use open amount, you need to set `virtualAccountTrxType` = O and you  need to send `totalAmount.value` = `0`and `totalAmount.currency` = `IDR` DOKU. Here is the sample:

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "    1899",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
      ...
    "virtualAccountTrxType": "O",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

```json
{
  ...
  "virtualAccountData": {
    "partnerServiceId": "    1899",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "O",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    ...
    },
    ...
}
```

{% endtab %}
{% endtabs %}

#### Limit Amount

DOKU supports limit amount payment meaning that your customer can input their own payment amount at the range that you defined. Limit amount only available when `virtualAccountTrxType` type is `O` and `V.`To use limit amount, you need to set `virtualAccountConfig.minAmount` >= 0 or `virtualAccountConfig.maxAmount` > 0 to DOKU.

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "    1899",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BANK_BJB",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  ...
  "virtualAccountData": {
    "partnerServiceId": "    1899",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BANK_CIMB",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
    },
}
</code></pre>

{% endtab %}
{% endtabs %}

***


# Sinarmas Virtual Account

DOKU has partnered with various banks and one of them is Sinarmas to provide Virtual Account Payment. Learn more about how DOKU can help you integrate with Sinarmas Virtual Account here.

### Integration methods[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/bca-va-guide#integration-methods) <a href="#integration-methods" id="integration-methods"></a>

There are two methods to integrate with Sinarmas VA:

1. **Create VA**: The VA number will be registered to DOKU and Acquirer will inquiry to our side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)
   1. **DOKU Generated Payment Code (DGPC)**: The VA number is generated by DOKU. Suitable for e-commerce business model.
   2. **Merchant Generated Payment Code (MGPC)**: The VA number is generated by Merchant. Suitable for top up business model.
2. **Direct Inquiry (DIPC)**: The VA number is registered on merchant side and DOKU will forward Acquirer inquiry request to merchant side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)

## Integration Steps

#### Precondition&#x20;

{% hint style="info" %}
Get Token API

As client who hit DOKU's API such as Create VA, you need to obtain an access token first. Learn how to do it in this [section](/accept-payments/direct-api/snap/integration-guide/get-token-api).&#x20;
{% endhint %}

{% hint style="info" %}
Generate Signature

`X- SIGNATURE` is a security parameter that needs to be generated on merchant's Backend to verify the request authenticity.

So, it's very crucial for merchant to generate the X-SIGNATURE. Learn how to do it in this [section](/get-started-with-doku-api/signature-component/snap)
{% endhint %}

Here is the overview of how to integrate with Virtual Account:

1. [Create Virtual Account](#id-1.-create-va)

   [a. DOKU Generate Payment Code](#a.-doku-generate-payment-code)

   [b. Merchant Generate Payment Code](#b.-merchant-generate-payment-code)

   [c. Display Virtual Account](#c.-display-virtual-account)

   [d. Acknowledge Payment Result](#d.-acknowledge-payment-result)

   [e. Hit DOKU Check Status API](#e.-hit-doku-check-status-api)

   [f. Delete Virtual Account](#f.-delete-payment-code)

   [g. Update Virtual Account](#g.-update-payment-code)

***

### 1. Create VA

To create VA, you will need to hit this API through your Backend:

#### API Endpoint

<table><thead><tr><th width="234">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>27</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va
</code></pre></td></tr></tbody></table>

Here is the sample request header, request body and response body for Sinarmas VA&#x20;

#### a. DOKU Generate Payment Code

Check this flow diagram to get know about this method

<div align="center" data-full-width="true"><figure><img src="/files/QRd0nhEfCWjmZzOexSvn" alt=""><figcaption><p>DOKU Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="109">Type</th><th width="131">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

## DOKU Generate Payment Code

> DOKU Generate Payment Code

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - CREATE VA DGPC SNAP","version":"1.0.0"},"servers":[{"description":"Sandbox","url":"https://api-sandbox.doku.com"},{"description":"Production","url":"https://api.doku.com"}],"paths":{"/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va":{"post":{"tags":["DOKU Generate Payment Code"],"summary":"DOKU Generate Payment Code","operationId":"createVA","description":"DOKU Generate Payment Code","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM-ddTHH:mm:ssZ format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVASNAPRequest"}}},"description":"Create VA SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVASNAPResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"CreateVASNAPRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","virtualAccountTrxType","additionalInfo","totalAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"description":"Customer Name. | Mandatory | min length: 1 | max length: 255","type":"string"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"trxId":{"type":"string","description":"Invoice number in Partner system. | Mandatory | min length: 1 | max length: 64"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoCreateVARequestRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string","description":"Expiration date for Virtual Account. ISO-8601"}}},"TotalAmountRef":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | Mandatory |  min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency. | Mandatory | min length: 1 | max length: 3"}}},"AdditionalInfoCreateVARequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"virtualAccountConfig":{"$ref":"#/components/schemas/VirtualAccountConfig"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_SINARMAS"]},"VirtualAccountConfig":{"type":"object","properties":{"reusableStatus":{"type":"boolean","description":"Reusable Status For Virtual Account Transaction, value TRUE or FALSE"},"minAmount":{"type":"string","description":"Minimum Amount for Payment |  min length: 1 | max length: 16.2"},"maxAmount":{"type":"string","description":"Maximum Amount for Payment |  min length: 1 | max length: 16.2"}}},"VirtualAccountTrxTypeRef":{"description":"Transaction ID in Partner system.  C (Closed Payment) &  O (Open Payment) | Mandatory | min length: 1 | max length: 1","type":"string"},"CreateVASNAPResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","totalAmount","virtualAccountTrxType","expiredDate","additionalInfo"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccouantNo. | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | Mandatory | min length: 1 | max length: 64"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoCreateVAResponseRef"}}}}},"AdditionalInfoCreateVAResponseRef":{"type":"object","required":["channel","howToPayPage","howToPayApi"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"howToPayPage":{"type":"string","description":"Step by step that will be used by customer for how to doing a payment | min length: 1 | max length: 256"},"howToPayApi":{"type":"string","description":"Step by step that will be used by customer for how to doing a payment. | min length: 1 | max length: 256"}}}}}}
```

\
[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

#### b. Merchant Generate Payment Code

Check this flow diagram to get know about this method

<div data-full-width="true"><figure><img src="/files/WDqzMJbMrbkQivFtU5B9" alt=""><figcaption><p>Merchant Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th width="200">Parameter</th><th width="101">Type</th><th width="120">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtained from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr><tr><td></td><td></td><td></td><td></td></tr></tbody></table>

## Merchant Generate Payment Code

> Merchant Generate Payment Code

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - CREATE VA MGPC SNAP","version":"1.0.0"},"servers":[{"description":"Sandbox","url":"https://api-sandbox.doku.com"},{"description":"Production","url":"https://api.doku.com"}],"paths":{"/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va":{"post":{"tags":["Merchant Generate Payment Code"],"summary":"Merchant Generate Payment Code","operationId":"createVA","description":"Merchant Generate Payment Code","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM-ddTHH:mm:ssZ format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVASNAPRequest"}}},"description":"Create VA SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVASNAPResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"CreateVASNAPRequest":{"type":"object","required":["partnerServiceId","virtualAccountName","trxId","virtualAccountTrxType","customerNo","virtualAccountNo","additionalInfo","totalAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"description":"Customer Name. | Mandatory | min length: 1 | max length: 255","type":"string"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"trxId":{"type":"string","description":"Invoice number in Partner system. | Mandatory | min length: 1 | max length: 64"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoCreateVARequestRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string","description":"Expiration date for Virtual Account. ISO-8601"}}},"TotalAmountRef":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | Mandatory |  min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency. | Mandatory | min length: 1 | max length: 3"}}},"AdditionalInfoCreateVARequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"virtualAccountConfig":{"$ref":"#/components/schemas/VirtualAccountConfig"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_SINARMAS"]},"VirtualAccountConfig":{"type":"object","properties":{"reusableStatus":{"type":"boolean","description":"Reusable Status For Virtual Account Transaction, value TRUE or FALSE"},"minAmount":{"type":"string","description":"Minimum Amount for Payment |  min length: 1 | max length: 16.2"},"maxAmount":{"type":"string","description":"Maximum Amount for Payment |  min length: 1 | max length: 16.2"}}},"VirtualAccountTrxTypeRef":{"description":"Transaction ID in Partner system.  C (Closed Payment) &  O (Open Payment) | Mandatory | min length: 1 | max length: 1","type":"string"},"CreateVASNAPResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","totalAmount","additionalInfo","virtualAccountTrxType","expiredDate"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | Mandatory | min length: 1 | max length: 64"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoCreateVAResponseRef"}}}}},"AdditionalInfoCreateVAResponseRef":{"type":"object","required":["channel","howToPayPage","howToPayApi"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"howToPayPage":{"type":"string","description":"Step by step that will be used by customer for how to doing a payment | min length: 1 | max length: 256"},"howToPayApi":{"type":"string","description":"Step by step that will be used by customer for how to doing a payment. | min length: 1 | max length: 256"}}}}}}
```

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

{% hint style="success" %}
**Pro Tips!**

1. You can also show payment instruction link to your customer by using `additionalInfo.howToPayPage`&#x20;
2. If you wish to customize the UI for the payment instruction, you can use the `additionalInfo.howToPayApi`
   {% endhint %}

#### c. Display Virtual Account

You can display the payment code to your customer by using `virtualAccountData.virtualAccountNo` that you retrieved from the API response.

#### d. Acknowledge payment result

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

## Payment Notification

> Payment Notification

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - Core System API","version":"1.0.0"},"servers":[{"description":"Merchant domain path url","url":"https://{merchant-domain}"}],"paths":{"/v1.2/transfer-va/payment":{"post":{"tags":["Payment Notification"],"summary":"Payment Notification","operationId":"paymentNotification","description":"Payment Notification","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationRequest"}}},"description":"Payment Notification SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"PaymentNotificationRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","totalAmount","paidAmount","channelCode","paymentRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | Mandatory | min length: 1 | max length: 64"},"channelCode":{"type":"string","description":"ChannelCOde ID in Partner system. | Optional | min length: 1 | max length: 4"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"},"paidAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"},"trxDateTime":{"type":"string","description":"DOKU's transaction date time"}}},"TotalAmountRef":{"type":"object","properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency | min length: 1 | max length: 3"}}},"AdditionalInfoRequestRef":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_SINARMAS"]},"PaymentNotificationResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"additionalInfo":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","paymentRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"}}}}}}}}
```

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

#### f. Delete Payment Code

If you wish to delete your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="107">Type</th><th width="124">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

## Delete Payment Code

> Delete Payment Code

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - DELETE VA SNAP","version":"1.0.0"},"servers":[{"description":"Sandbox","url":"https://api-sandbox.doku.com"},{"description":"Production","url":"https://api.doku.com"},{"description":"UAT","url":"https://api-uat.doku.com"}],"paths":{"/virtual-accounts/bi-snap-va/v1.1/transfer-va/delete-va":{"delete":{"tags":["Delete Payment Code"],"summary":"Delete Payment Code","operationId":"deleteVA","description":"Delete Payment Code","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM-ddTHH:mm:ssZ format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteVASNAPRequest"}}},"description":"Delete VA SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteVASNAPResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"DeleteVASNAPRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","trxId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20","type":"string"},"virtualAccountNo":{"description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28","type":"string"},"trxId":{"type":"string","description":"Invoice number in Partner system. | Mandatory | min length: 1 | max length: 64"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoCreateVARequestRef"}}},"AdditionalInfoCreateVARequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_SINARMAS"]},"DeleteVASNAPResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | Mandatory | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccouantNo. | min length: 1 | max length: 28"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | min length: 1 | max length: 64"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDeleteVARef"}}}}},"AdditionalInfoDeleteVARef":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channel"},"virtualAccountConfig":{"type":"object","properties":{"status":{"type":"string","description":"Status for this VA. ACTIVE/INACTIVE | min length: 1 | max length: 20"}}}}}}}}
```

#### g. Update Payment Code

If you wish to update your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="106">Type</th><th width="125">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

## Update Payment Code

> Update Payment Code

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - UPDATE VA SNAP","version":"1.0.0"},"servers":[{"description":"Sandbox","url":"https://api-sandbox.doku.com"},{"description":"Production","url":"https://api.doku.com"},{"description":"UAT","url":"https://api-uat.doku.com"}],"paths":{"/virtual-accounts/bi-snap-va/v1.1/transfer-va/update-va":{"put":{"tags":["Update Payment Code"],"summary":"Update Payment Code","operationId":"updateVA","description":"Update Payment Code","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM-ddTHH:mm:ssZ format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVASNAPRequest"}}},"description":"Update VA SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVASNAPResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"UpdateVASNAPRequest":{"type":"object","required":["partnerServiceId","customerNo","trxId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20","type":"string"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"description":"Customer Name | min length: 1 | max length: 255","type":"string"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"trxId":{"type":"string","description":"Invoice number in Partner system. | Mandatory | min length: 1 | max length: 64"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoUpdateVARequestRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string","description":"Expiration date for Virtual Account. ISO-8601"}}},"TotalAmountRef":{"type":"object","properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency | min length: 1 | max length: 3"}}},"AdditionalInfoUpdateVARequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"virtualAccountConfig":{"type":"object","properties":{"status":{"type":"string","description":"Status for this VA. ACTIVE/INACTIVE | min length: 1 | max length: 20"}}}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_SINARMAS"]},"VirtualAccountTrxTypeRef":{"description":"Transaction ID in Partner system.  C (Closed Payment) &  O (Open Payment) | Mandatory | min length: 1 | max length: 1","type":"string"},"UpdateVASNAPResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | Mandatory | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","totalAmount","expiredDate"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | Mandatory | min length: 1 | max length: 64"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoUpdateVARequestRef"}}}}}}}}
```

***

### 2. Direct Inquiry

<table><thead><tr><th width="236">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>24</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/inquiry
</code></pre></td></tr></tbody></table>

Here is the overview of how to integrate Direct Inquiry Sinarmas VA :&#x20;

2. [Direct Inquiry](#id-2.-direct-inquiry)

   a.  [Setup Inquiry URL on DOKU Dashboard](#a.-setup-inquiry-url-on-doku-dashboard)

   b. [Generate Payment Code on your End](#b.-generate-payment-code-on-your-end)

   c. [Receive Inquiry Request from DOKU](#c.-receive-inquiry-request-from-doku)

   d. [Acknowledge Payment Notification](#d.-acknowledge-payment-notification)

   e. [Hit DOKU Check Status API](#e.-hit-doku-check-status-api-1)

Check this flow to diagram to get know about this API :&#x20;

<div data-full-width="true"><figure><img src="/files/UFMZMMHHiaPNc6xvKFk1" alt=""><figcaption><p>Direct Inquiry</p></figcaption></figure></div>

To get Inquiry Request from DOKU,  you will need to hit this API through your Backend:

#### a. Setup Inquiry URL on DOKU Dashboard

To receive the inquiry request from DOKU. You must set your `Inquiry URL` to DOKU. Please contact our team for the setup.&#x20;

{% hint style="info" %}
Please inform the `Inquiry URL` for Sandbox environment and Production environment.
{% endhint %}

#### b. Generate Payment Code on your end

Generate payment is done in your system. The payment code length maximum is `23` digits.

#### c. Receive Inquiry Request from DOKU

Here is the sample request header, request body from DOKU

#### Request Header

<table data-full-width="false"><thead><tr><th width="192">Parameter</th><th width="122">Type</th><th width="131">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

## Direct Inquiry

> Direct Inquiry

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - CREATE VA DIPC SNAP","version":"1.0.0"},"servers":[{"description":"Merchant Domain","url":"https://{api-domain}"}],"paths":{"/v1.1/transfer-va/inquiry":{"post":{"tags":["Direct Inquiry"],"summary":"Direct Inquiry","operationId":"directInquiry","description":"Direct Inquiry","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM-ddTHH:mm:ssZ format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryRequest"}}},"description":"Direct Inquiry SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"DirectInquiryRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","trxDateInit","inquiryRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20","type":"string"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28"},"channelCode":{"description":"Channel code from bank | min length: 1 | max length: 4","type":"string"},"trxDateInit":{"type":"string","description":"Transaction date.  | Mandatory"},"language":{"description":"Language | min length: 1 | max length: 2","type":"string"},"inquiryRequestId":{"description":"Unique Inquiry request id. | Mandatory | min length: 1 | max length: 30","type":"string"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVARequestRef"}}},"AdditionalInfoDirectInquiyVARequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_SINARMAS"]},"DirectInquiryResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVAResponseRef"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","inquiryRequestId","virtualAccountTrxType","totalAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"inquiryRequestId":{"description":"Unique Inquiry request id | min length: 1 | max length: 30","type":"string"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"inquiryStatus":{"type":"string","description":"Status for this inquiry. (FAILED, SUCCESS, EXPIRED, USED, PAID, OPEN, INACTIVE, ACTIVE, REFUND) | min length: 1 | max length: 15"},"inquiryReason":{"$ref":"#/components/schemas/InquiryReasonRef"}}}}},"AdditionalInfoDirectInquiyVAResponseRef":{"type":"object","required":["channel","trxId"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"trxId":{"type":"string","description":"Invoice Number | Mandatory | min length: 1 | max length: 32"},"virtualAccountConfig":{"$ref":"#/components/schemas/VirtualAccountConfig"}}},"VirtualAccountConfig":{"type":"object","properties":{"reusableStatus":{"type":"boolean","description":"Reusable Status For Virtual Account Transaction, value TRUE or FALSE"}}},"TotalAmountRef":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | Mandatory |  min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency. | Mandatory | min length: 1 | max length: 3"}}},"VirtualAccountTrxTypeRef":{"description":"Transaction ID in Partner system.  C (Closed Payment) &  O (Open Payment) | Mandatory | min length: 1 | max length: 1","type":"string"},"InquiryReasonRef":{"type":"object","properties":{"english":{"type":"string","description":"Inquiry Reason in English | min length: 1 | max length: 18"},"indonesia":{"type":"string","description":"Inquiry Reason in Bahasa | min length: 1 | max length: 18"}}}}}}
```

#### d. Acknowledge payment notification

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

## Payment Notification

> Payment Notification

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - Core System API","version":"1.0.0"},"servers":[{"description":"Merchant domain path url","url":"https://{merchant-domain}"}],"paths":{"/v1.2/transfer-va/payment":{"post":{"tags":["Payment Notification"],"summary":"Payment Notification","operationId":"paymentNotification","description":"Payment Notification","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationRequest"}}},"description":"Payment Notification SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"PaymentNotificationRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","totalAmount","paidAmount","channelCode","paymentRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | Mandatory | min length: 1 | max length: 64"},"channelCode":{"type":"string","description":"ChannelCOde ID in Partner system. | Optional | min length: 1 | max length: 4"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"},"paidAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"},"trxDateTime":{"type":"string","description":"DOKU's transaction date time"}}},"TotalAmountRef":{"type":"object","properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency | min length: 1 | max length: 3"}}},"AdditionalInfoRequestRef":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_SINARMAS"]},"PaymentNotificationResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"additionalInfo":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","paymentRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"}}}}}}}}
```

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

### Additional Feature

#### Open Amount&#x20;

DOKU supports open payment meaning that your customer can input their own payment amount. To use open amount, you need to set `virtualAccountTrxType` = O and you  need to send `totalAmount.value` = `0`and `totalAmount.currency` = `IDR` DOKU. Here is the sample:

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "    1899",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
      ...
    "virtualAccountTrxType": "O",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

```json
{
  ...
  "virtualAccountData": {
    "partnerServiceId": "    1899",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "O",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    ...
    },
    ...
}
```

{% endtab %}
{% endtabs %}

#### Limit Amount

DOKU supports limit amount payment meaning that your customer can input their own payment amount at the range that you defined. Limit amount only available when `virtualAccountTrxType` type is `O` and `V.`To use limit amount, you need to set `virtualAccountConfig.minAmount` >= 0 or `virtualAccountConfig.maxAmount` > 0 to DOKU.

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "    1899",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BANK_SINARMAS",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  ...
  "virtualAccountData": {
    "partnerServiceId": "    1899",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BANK_CIMB",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
    },
}
</code></pre>

{% endtab %}
{% endtabs %}

***


# BCA Virtual Account

DOKU has partnered with various banks and one of them is BCA to provide Virtual Account Payment. Learn more about how DOKU can help you integrate with BCA Virtual Account here.

### Integration methods[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/bca-va-guide#integration-methods) <a href="#integration-methods" id="integration-methods"></a>

There are two methods to integrate with BCA VA:

1. **Create VA**: The VA number will be registered to DOKU and Acquirer will inquiry to our side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)
   1. **DOKU Generated Payment Code (DGPC)**: The VA number is generated by DOKU. Suitable for e-commerce business model.
   2. **Merchant Generated Payment Code (MGPC)**: The VA number is generated by Merchant. Suitable for top up business model.
2. **Direct Inquiry (DIPC)**: The VA number is registered on merchant side and DOKU will forward Acquirer inquiry request to merchant side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)

## Integration Steps

#### Precondition&#x20;

{% hint style="info" %}
Get Token API

As client who hit DOKU's API such as Create VA, you need to obtain an access token first. Learn how to do it in this [section](/accept-payments/direct-api/snap/integration-guide/get-token-api).&#x20;
{% endhint %}

{% hint style="info" %}
Generate Signature

`X- SIGNATURE` is a security parameter that needs to be generated on merchant's Backend to verify the request authenticity.

So, it's very crucial for merchant to generate the X-SIGNATURE. Learn how to do it in this [section](/get-started-with-doku-api/signature-component/snap)
{% endhint %}

Here is the overview of how to integrate with Virtual Account:

1. [Create Virtual Account](#id-1.-create-va)

   [a. DOKU Generate Payment Code](#a.-doku-generate-payment-code)

   [b. Merchant Generate Payment Code](#b.-merchant-generate-payment-code)

   [c. Display Virtual Account](#c.-display-virtual-account)

   [d. Acknowledge Payment Result](#d.-acknowledge-payment-result)

   [e. Hit DOKU Check Status API](#e.-hit-doku-check-status-api)

   [f. Delete Virtual Account](#f.-delete-payment-code)

   [g. Update Virtual Account](#g.-update-payment-code)

***

### 1. Create VA

To create VA, you will need to hit this API through your Backend:

#### API Endpoint

<table><thead><tr><th width="246">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>27</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va
</code></pre></td></tr></tbody></table>

Here is the sample request header, request body and response body for BCA VA&#x20;

#### a. DOKU Generate Payment Code

Check this flow diagram to get know about this method

<div align="center" data-full-width="true"><figure><img src="/files/QRd0nhEfCWjmZzOexSvn" alt=""><figcaption><p>DOKU Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="114">Type</th><th width="124">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/NyAcqHe6vG7yZSAHSaUh" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - BCA VA - DGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2Fx8fuJzekRhRZmmGttron%2FSNAP%20v1.1%20-%20BCA%20VA%20-%20DGPC.json?alt=media\&token=eef17792-ca46-4729-a537-76c99cb78d04)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

#### b. Merchant Generate Payment Code

Check this flow diagram to get know about this method

<div data-full-width="true"><figure><img src="/files/WDqzMJbMrbkQivFtU5B9" alt=""><figcaption><p>Merchant Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/VEgl5qrwSOd550JULto6" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - BCA VA - MGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F9fFU763f6AGaqdWBz1SP%2FSNAP%20v1.1%20-%20BCA%20VA%20-%20MGPC.json?alt=media\&token=226698f7-3796-44bb-b4c4-ab32fb625ab0)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

{% hint style="success" %}
**Pro Tips!**

1. You can also show payment instruction link to your customer by using `additionalInfo.howToPayPage`&#x20;
2. If you wish to customize the UI for the payment instruction, you can use the `additionalInfo.howToPayApi`
   {% endhint %}

#### c. Display Virtual Account

You can display the payment code to your customer by using `virtualAccountData.virtualAccountNo` that you retrieved from the API response.

#### d. Acknowledge payment result

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

{% openapi src="/files/81gujL93aUX8buhK2zzs" path="/v1.1/transfer-va/payment" method="post" %}
[SNAP v1.1 - BCA VA - NOTIFICATION.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FsjwGCRGxKRLQUgaT4LLB%2FSNAP%20v1.1%20-%20BCA%20VA%20-%20NOTIFICATION.json?alt=media\&token=a46319b2-76b4-45d4-9640-0867b4dc93be)
{% endopenapi %}

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

#### f. Delete Payment Code

If you wish to delete your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/FzB093xCXyicuoc1ky8u" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/delete-va" method="delete" %}
[SNAP v1.1 - BCA VA - DELETE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F9uGl6HtJlzX4taNQ0u5F%2FSNAP%20v1.1%20-%20BCA%20VA%20-%20DELETE.json?alt=media\&token=8525f80c-80e7-434c-8f69-2a5673abc626)
{% endopenapi %}

#### g. Update Payment Code

If you wish to update your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/eWqyCS6tQM5RzGwY9X5M" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/update-va" method="put" %}
[SNAP v1.1 - BCA VA - UPDATE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FeIrQsL4ceZwTcdpf4ea0%2FSNAP%20v1.1%20-%20BCA%20VA%20-%20UPDATE.json?alt=media\&token=2d3f78cc-c1aa-462c-9efc-a727083e7c83)
{% endopenapi %}

***

### 2. Direct Inquiry

<table><thead><tr><th width="235">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>24</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/inquiry
</code></pre></td></tr></tbody></table>

Here is the overview of how to integrate Direct Inquiry BCA VA :&#x20;

2. [Direct Inquiry](#id-2.-direct-inquiry)

   a.  [Setup Inquiry URL on DOKU Dashboard](#a.-setup-inquiry-url-on-doku-dashboard)

   b. [Generate Payment Code on your End](#b.-generate-payment-code-on-your-end)

   c. [Receive Inquiry Request from DOKU](#c.-receive-inquiry-request-from-doku)

   d. [Acknowledge Payment Notification](#d.-acknowledge-payment-notification)

   e. [Hit DOKU Check Status API](#e.-hit-doku-check-status-api-1)

Check this flow to diagram to get know about this API :&#x20;

<div data-full-width="true"><figure><img src="/files/UFMZMMHHiaPNc6xvKFk1" alt=""><figcaption><p>Direct Inquiry</p></figcaption></figure></div>

To get Inquiry Request from DOKU,  you will need to hit this API through your Backend:

#### a. Setup Inquiry URL on DOKU Dashboard

To receive the inquiry request from DOKU. You must set your `Inquiry URL` to DOKU. Please contact our team for the setup.&#x20;

{% hint style="info" %}
Please inform the `Inquiry URL` for Sandbox environment and Production environment.
{% endhint %}

#### b. Generate Payment Code on your end

Generate payment is done in your system. The payment code length maximum is `23` digits.

#### c. Receive Inquiry Request from DOKU

Here is the sample request header, request body from DOKU

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

## Direct Inquiry

> Direct Inquiry

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - CREATE VA DIPC SNAP","version":"1.0.0"},"tags":[],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{merchant-domain}"}],"paths":{"/v1.1/transfer-va/inquiry":{"post":{"tags":["Direct Inquiry"],"summary":"Direct Inquiry","operationId":"directInquiry","description":"Direct Inquiry","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string"},"required":true,"description":"Client's current local time in yyyy-MM-dd'T'HH:mm:ssXXX format. Sample: 2024-03-19T14:39:01+07:00"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"Channel Id for VA. Please fill with H2H (Host-To-Host)"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryRequest"}}},"description":"Direct Inquiry SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"DirectInquiryRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","trxDateInit","inquiryRequestId","additionalInfo"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20","type":"string"},"virtualAccountNo":{"description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28","type":"string"},"channelCode":{"description":"Channel code from bank | min length: 1 | max length: 10","type":"string"},"trxDateInit":{"type":"string","description":"Transaction date.  | Mandatory"},"language":{"description":"Language | min length: 1 | max length: 2","type":"string"},"inquiryRequestId":{"description":"Unique Inquiry request id. | Mandatory | min length: 1 | max length: 30","type":"string"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVARequestRef"}}},"AdditionalInfoDirectInquiyVARequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BCA"]},"DirectInquiryResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","totalAmount","virtualAccountTrxType","additionalInfo","inquiryRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20","type":"string"},"virtualAccountNo":{"description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28","type":"string"},"virtualAccountName":{"type":"string","description":"Customer Name | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string"},"inquiryStatus":{"type":"string","description":"Status for this inquiry. Refer to case_code | min length: 1 | max length: 2"},"inquiryReason":{"$ref":"#/components/schemas/InquiryReasonRef"},"inquiryRequestId":{"description":"Unique Inquiry request id | min length: 1 | max length: 30","type":"string"},"freeText":{"$ref":"#/components/schemas/FreeTextsRefs"}}},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVAResponseRef"}}},"TotalAmountRef":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | Mandatory |  min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency. | Mandatory | min length: 1 | max length: 3"}}},"VirtualAccountTrxTypeRef":{"description":"Transaction type for this transaction.  C (Closed Amount), O (Open Amount), V (Bill Variable Amount) | Mandatory | min length: 1 | max length: 1","type":"string"},"InquiryReasonRef":{"type":"object","properties":{"english":{"type":"string","description":"Inquiry Reason in English | min length: 1 | max length: 18"},"indonesia":{"type":"string","description":"Inquiry Reason in Bahasa | min length: 1 | max length: 18"}}},"FreeTextsRefs":{"type":"array","description":"Free text for additional description. | Optional | min length: 1 | max length: 64","items":{"type":"object","properties":{"english":{"type":"string"},"indonesia":{"type":"string"}}}},"AdditionalInfoDirectInquiyVAResponseRef":{"type":"object","required":["channel","trxId"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"trxId":{"type":"string","description":"Invoice Number | Optional |  min length: 1 | max length: 32"},"virtualAccountConfig":{"$ref":"#/components/schemas/VirtualAccountConfig"}}},"VirtualAccountConfig":{"type":"object","properties":{"reusableStatus":{"type":"boolean","description":"Reusable Status For Virtual Account Transaction, value TRUE or FALSE"},"minAmount":{"type":"string","description":"Minimum Amount. Minimum Amount can be use only if virtualAccountTrxType is Open Amount (O) or Bill Variable (V). With 2 decimal, format ISO 4217 | Optional |  min length: 1 | max length: 16.2"},"maxAmount":{"type":"string","description":"Maximum Amount. Maximum Amount can be use only if virtualAccountTrxType is Open Amount (O) or Bill Variable (V). With 2 decimal,format ISO 4217 | Optional |  min length: 1 | max length: 16.2"}}}}}}
```

#### d. Acknowledge payment notification

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

## Payment Notification

> Payment Notification

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - Core System API","version":"1.0.0"},"tags":[],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{merchant-domain}"}],"paths":{"/v1.1/transfer-va/payment":{"post":{"tags":["Payment Notification"],"summary":"Payment Notification","operationId":"paymentNotification","description":"Payment Notification","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string"},"required":true,"description":"Client's current local time in yyyy-MM-dd'T'HH:mm:ssXXX format. Sample: 2024-03-19T14:39:01+07:00"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"Channel Id for VA. Please fill with H2H (Host-To-Host)"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationRequest"}}},"description":"Payment Notification SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"PaymentNotificationRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","paidAmount","additionalInfo"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20","type":"string"},"virtualAccountNo":{"description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28","type":"string"},"virtualAccountName":{"type":"string","description":"Customer Name | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | Mandatory | min length: 1 | max length: 64"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"},"paidAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"},"trxDateTime":{"type":"string","description":"DOKU's transaction date time"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"}}},"TotalAmountRef":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency | min length: 1 | max length: 3"}}},"AdditionalInfoRequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"virtualAccountConfig":{"type":"object","properties":{"minAmount":{"type":"string","description":"Minimum Amount. Minimum Amount can be use only if virtualAccountTrxType is Open Amount (O) or Bill Variable (V). With 2 decimal, format ISO 4217 | Optional |  min length: 1 | max length: 16.2"},"maxAmount":{"type":"string","description":"Maximum Amount. Maximum Amount can be use only if virtualAccountTrxType is Open Amount (O) or Bill Variable (V). With 2 decimal,format ISO 4217 | Optional |  min length: 1 | max length: 16.2"}}}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BCA"]},"VirtualAccountTrxTypeRef":{"description":"Transaction type for this transaction.  C (Closed Amount), O (Open Amount), V (Bill Variable Amount) | Mandatory | min length: 1 | max length: 1","type":"string"},"PaymentNotificationResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","paymentRequestId","paidAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20","type":"string"},"virtualAccountNo":{"description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28","type":"string"},"virtualAccountName":{"type":"string","description":"Customer Name | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"},"paidAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"}}},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"}}}}}}
```

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

### Additional Feature

#### Open Amount&#x20;

DOKU supports open payment meaning that your customer can input their own payment amount. To use open amount, you need to set `virtualAccountTrxType` = O and you  need to send `totalAmount.value` = `0`and `totalAmount.currency` = `IDR` DOKU. Here is the sample:

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "   19008",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
      ...
    "virtualAccountTrxType": "O",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

```json
{
  ...
  "virtualAccountData": {
    "partnerServiceId": "   19008",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "O",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    ...
    },
    ...
}
```

{% endtab %}
{% endtabs %}

#### Bill Variable Amount&#x20;

DOKU supports bill variable amount payment meaning that you can set the amount as billing information to your customer and your customer can input their own payment amount. To use open amount, you need to set `virtualAccountTrxType` = V and you  need to send `totalAmount.value` = based on your billing amount and `totalAmount.currency` = `IDR` DOKU. Here is the sample:

{% tabs %}
{% tab title="Create VA" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "partnerServiceId": "   19008",
        ...
    "totalAmount": {
        "value": "1000000.00",
        "currency": "IDR"
      },
      ...
    "virtualAccountTrxType": "V",
    ...
}
</code></pre>

{% endtab %}

{% tab title="Direct Inquiry" %}

```json
{
  ...
  "virtualAccountData": {
    "partnerServiceId": "   19008",
    ...
    "totalAmount": {
      "value": "1000000.00",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "V",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    ...
    },
    ...
}
```

{% endtab %}
{% endtabs %}

#### Limit Amount

DOKU supports limit amount payment meaning that your customer can input their own payment amount at the range that you defined. Limit amount only available when `virtualAccountTrxType` type is `O` and `V.`To use limit amount, you need to set `virtualAccountConfig.minAmount` >= 0 or `virtualAccountConfig.maxAmount` > 0 to DOKU.

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "  888994",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BCA",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  ...
  "virtualAccountData": {
    "partnerServiceId": "   19008",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BCA",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
    },
}
</code></pre>

{% endtab %}
{% endtabs %}

***


# BRI Virtual Account

DOKU has partnered with various banks and one of them is BRI to provide Virtual Account Payment. Learn more about how DOKU can help you integrate with BRI Virtual Account here.

### Integration methods[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/bca-va-guide#integration-methods) <a href="#integration-methods" id="integration-methods"></a>

There are two methods to integrate with BRI VA:

1. **Create VA**: The VA number will be registered to DOKU and Acquirer will inquiry to our side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)
   1. **DOKU Generated Payment Code (DGPC)**: The VA number is generated by DOKU. Suitable for e-commerce business model.
   2. **Merchant Generated Payment Code (MGPC)**: The VA number is generated by Merchant. Suitable for top up business model.
2. **Direct Inquiry (DIPC)**: The VA number is registered on merchant side and DOKU will forward Acquirer inquiry request to merchant side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)

## Integration Steps

#### Precondition&#x20;

{% hint style="info" %}
Get Token API

As client who hit DOKU's API such as Create VA, you need to obtain an access token first. Learn how to do it in this [section](/accept-payments/direct-api/snap/integration-guide/get-token-api).&#x20;
{% endhint %}

{% hint style="info" %}
Generate Signature

`X- SIGNATURE` is a security parameter that needs to be generated on merchant's Backend to verify the request authenticity.

So, it's very crucial for merchant to generate the X-SIGNATURE. Learn how to do it in this [section](/get-started-with-doku-api/signature-component/snap)
{% endhint %}

Here is the overview of how to integrate with Virtual Account:

1. [Create Virtual Account](#id-1.-create-va)

   [a. DOKU Generate Payment Code](#a.-doku-generate-payment-code)

   [b. Merchant Generate Payment Code](#b.-merchant-generate-payment-code)

   [c. Display Virtual Account](#c.-display-virtual-account)

   [d. Acknowledge Payment Result](#d.-acknowledge-payment-result)

   [e. Hit DOKU Check Status API](#e.-hit-doku-check-status-api)

   [f. Delete Virtual Account](#f.-delete-payment-code)

   [g. Update Virtual Account](#g.-update-payment-code)

***

### 1. Create VA

To create VA, you will need to hit this API through your Backend:

#### API Endpoint

<table><thead><tr><th width="246">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>27</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va
</code></pre></td></tr></tbody></table>

Here is the sample request header, request body and response body for BRI VA&#x20;

#### a. DOKU Generate Payment Code

Check this flow diagram to get know about this method

<div align="center" data-full-width="true"><figure><img src="/files/QRd0nhEfCWjmZzOexSvn" alt=""><figcaption><p>DOKU Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="114">Type</th><th width="124">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/tIZw0FZAfpsPNiJk4TVx" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - BRI VA - DGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FUv3sr5FmDpDgrrIgG6wm%2FSNAP%20v1.1%20-%20BRI%20VA%20-%20DGPC.json?alt=media\&token=32bbfe6c-d4f7-48f9-aecc-913464e5cacf)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

#### b. Merchant Generate Payment Code

Check this flow diagram to get know about this method

<div data-full-width="true"><figure><img src="/files/WDqzMJbMrbkQivFtU5B9" alt=""><figcaption><p>Merchant Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/igPWLkQFM5xaU6ObV1ld" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - BRI VA - MGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FXuMfDzGs3DhEZcykgWNw%2FSNAP%20v1.1%20-%20BRI%20VA%20-%20MGPC.json?alt=media\&token=7a522abb-7d6b-4314-9671-bbb443cd2da5)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

{% hint style="success" %}
**Pro Tips!**

1. You can also show payment instruction link to your customer by using `additionalInfo.howToPayPage`&#x20;
2. If you wish to customize the UI for the payment instruction, you can use the `additionalInfo.howToPayApi`
   {% endhint %}

#### c. Display Virtual Account

You can display the payment code to your customer by using `virtualAccountData.virtualAccountNo` that you retrieved from the API response.

#### d. Acknowledge payment result

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

{% openapi src="/files/SLQyW61kt5Zo6kWppwZk" path="/v1.1/transfer-va/payment" method="post" %}
[SNAP v1.1 - BRI VA - NOTIFICATION.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FzEIUFCe0wuTmX24B4v9o%2FSNAP%20v1.1%20-%20BRI%20VA%20-%20NOTIFICATION.json?alt=media\&token=a976b5be-9d83-4804-acd9-5f731170735a)
{% endopenapi %}

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

#### f. Delete Payment Code

If you wish to delete your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/aoq2iG1ukyWh853MlTOu" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/delete-va" method="delete" %}
[SNAP v1.1 - BRI VA - DELETE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F7HBXNYAZoGOMo4UNwhbN%2FSNAP%20v1.1%20-%20BRI%20VA%20-%20DELETE.json?alt=media\&token=3bb7c510-04fb-4bd0-a8f6-084e1db48264)
{% endopenapi %}

#### g. Update Payment Code

If you wish to update your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/emUoBpGjPUE3Ymyyf1BV" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/update-va" method="put" %}
[SNAP v1.1 - BRI VA - UPDATE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2Fg6n16eVQQcpWlpKCZzUs%2FSNAP%20v1.1%20-%20BRI%20VA%20-%20UPDATE.json?alt=media\&token=9c595975-25ef-40fb-86e3-bb6ef2d8d810)
{% endopenapi %}

***

### 2. Direct Inquiry

<table><thead><tr><th width="235">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>24</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/inquiry
</code></pre></td></tr></tbody></table>

Here is the overview of how to integrate Direct Inquiry BRI VA :&#x20;

2. [Direct Inquiry](#id-2.-direct-inquiry)

   a.  [Setup Inquiry URL on DOKU Dashboard](#a.-setup-inquiry-url-on-doku-dashboard)

   b. [Generate Payment Code on your End](#b.-generate-payment-code-on-your-end)

   c. [Receive Inquiry Request from DOKU](#c.-receive-inquiry-request-from-doku)

   d. [Acknowledge Payment Notification](#d.-acknowledge-payment-notification)

   e. [Hit DOKU Check Status API](#e.-hit-doku-check-status-api-1)

Check this flow to diagram to get know about this API :&#x20;

<div data-full-width="true"><figure><img src="/files/UFMZMMHHiaPNc6xvKFk1" alt=""><figcaption><p>Direct Inquiry</p></figcaption></figure></div>

To get Inquiry Request from DOKU,  you will need to hit this API through your Backend:

#### a. Setup Inquiry URL on DOKU Dashboard

To receive the inquiry request from DOKU. You must set your `Inquiry URL` to DOKU. Please contact our team for the setup.&#x20;

{% hint style="info" %}
Please inform the `Inquiry URL` for Sandbox environment and Production environment.
{% endhint %}

#### b. Generate Payment Code on your end

Generate payment is done in your system. The payment code length maximum is `28` digits.

#### c. Receive Inquiry Request from DOKU

Here is the sample request header, request body from DOKU

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

## Direct Inquiry

> Direct Inquiry

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - CREATE VA DIPC SNAP","version":"1.0.0"},"tags":[],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{merchant-domain}"}],"paths":{"/v1.1/transfer-va/inquiry":{"post":{"tags":["Direct Inquiry"],"summary":"Direct Inquiry","operationId":"directInquiry","description":"Direct Inquiry","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string"},"required":true,"description":"Client's current local time in yyyy-MM-dd'T'HH:mm:ssXXX format. Sample: 2024-03-19T14:39:01+07:00"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"Channel Id for VA. Please fill with H2H (Host-To-Host)"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryRequest"}}},"description":"Direct Inquiry SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"DirectInquiryRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","trxDateInit","inquiryRequestId","additionalInfo"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"channelCode":{"description":"Channel code from bank | min length: 1 | max length: 10","type":"string"},"trxDateInit":{"type":"string","description":"Transaction date.  | Mandatory"},"language":{"description":"Language | min length: 1 | max length: 2","type":"string"},"inquiryRequestId":{"description":"Unique Inquiry request id. | Mandatory | min length: 1 | max length: 30","type":"string"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVARequestRef"}}},"AdditionalInfoDirectInquiyVARequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BRI"]},"DirectInquiryResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","totalAmount","virtualAccountTrxType","inquiryRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string"},"inquiryStatus":{"type":"string","description":"Status for this inquiry. Refer to case_code | min length: 1 | max length: 2"},"inquiryReason":{"$ref":"#/components/schemas/InquiryReasonRef"},"inquiryRequestId":{"description":"Unique Inquiry request id | min length: 1 | max length: 30","type":"string"},"freeText":{"$ref":"#/components/schemas/FreeTextsRefs"}}},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVAResponseRef"}}},"TotalAmountRef":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | Mandatory |  min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency. | Mandatory | min length: 1 | max length: 3"}}},"VirtualAccountTrxTypeRef":{"description":"Transaction type for this transaction.  C (Closed Amount), O (Open Amount), V (Bill Variable Amount) | Mandatory | min length: 1 | max length: 1","type":"string"},"InquiryReasonRef":{"type":"object","properties":{"english":{"type":"string","description":"Inquiry Reason in English | min length: 1 | max length: 18"},"indonesia":{"type":"string","description":"Inquiry Reason in Bahasa | min length: 1 | max length: 18"}}},"FreeTextsRefs":{"type":"array","description":"Free text for additional description. | Optional | min length: 1 | max length: 64","items":{"type":"object","properties":{"english":{"type":"string"},"indonesia":{"type":"string"}}}},"AdditionalInfoDirectInquiyVAResponseRef":{"type":"object","required":["channel","trxId"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"trxId":{"type":"string","description":"Invoice Number | Optional |  min length: 1 | max length: 32"},"virtualAccountConfig":{"$ref":"#/components/schemas/VirtualAccountConfig"}}},"VirtualAccountConfig":{"type":"object","properties":{"reusableStatus":{"type":"boolean","description":"Reusable Status For Virtual Account Transaction, value TRUE or FALSE"},"minAmount":{"type":"string","description":"Minimum Amount. Minimum Amount can be use only if virtualAccountTrxType is Open Amount (O) or Bill Variable (V). With 2 decimal, format ISO 4217 | Optional |  min length: 1 | max length: 16.2"},"maxAmount":{"type":"string","description":"Maximum Amount. Maximum Amount can be use only if virtualAccountTrxType is Open Amount (O) or Bill Variable (V). With 2 decimal,format ISO 4217 | Optional |  min length: 1 | max length: 16.2"}}}}}}
```

#### d. Acknowledge payment notification

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

## Payment Notification

> Payment Notification

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - Core System API","version":"1.0.0"},"tags":[],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{merchant-domain}"}],"paths":{"/v1.1/transfer-va/payment":{"post":{"tags":["Payment Notification"],"summary":"Payment Notification","operationId":"paymentNotification","description":"Payment Notification","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string"},"required":true,"description":"Client's current local time in yyyy-MM-dd'T'HH:mm:ssXXX format. Sample: 2024-03-19T14:39:01+07:00"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"Channel Id for VA. Please fill with H2H (Host-To-Host)"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationRequest"}}},"description":"Payment Notification SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"PaymentNotificationRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","paidAmount","additionalInfo"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | Mandatory | min length: 1 | max length: 64"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"},"paidAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"},"trxDateTime":{"type":"string","description":"DOKU's transaction date time"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"}}},"TotalAmountRef":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency | min length: 1 | max length: 3"}}},"AdditionalInfoRequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"virtualAccountConfig":{"type":"object","properties":{"minAmount":{"type":"string","description":"Minimum Amount. Minimum Amount can be use only if virtualAccountTrxType is Open Amount (O) or Bill Variable (V). With 2 decimal, format ISO 4217 | Optional |  min length: 1 | max length: 16.2"},"maxAmount":{"type":"string","description":"Maximum Amount. Maximum Amount can be use only if virtualAccountTrxType is Open Amount (O) or Bill Variable (V). With 2 decimal,format ISO 4217 | Optional |  min length: 1 | max length: 16.2"}}}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BRI"]},"VirtualAccountTrxTypeRef":{"description":"Transaction type for this transaction.  C (Closed Amount), O (Open Amount), V (Bill Variable Amount) | Mandatory | min length: 1 | max length: 1","type":"string"},"PaymentNotificationResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","paymentRequestId","paidAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"},"paidAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"}}},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"}}}}}}
```

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

### Additional Feature

#### Open Amount&#x20;

DOKU supports open payment meaning that your customer can input their own payment amount. To use open amount, you need to set `virtualAccountTrxType` = O and you  need to send `totalAmount.value` = `0`and `totalAmount.currency` = `IDR` DOKU. Here is the sample:

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "   12362",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
      ...
    "virtualAccountTrxType": "O",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

```json
{
  ...
  "virtualAccountData": {
    "partnerServiceId": "   12362",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "O",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    ...
    },
    ...
}
```

{% endtab %}
{% endtabs %}

#### Limit Amount

DOKU supports limit amount payment meaning that your customer can input their own payment amount at the range that you defined. Limit amount only available when `virtualAccountTrxType` type is `O` and `V.`To use limit amount, you need to set `virtualAccountConfig.minAmount` >= 0 or `virtualAccountConfig.maxAmount` > 0 to DOKU.

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "   12362",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BRI",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  ...
  "virtualAccountData": {
    "partnerServiceId": "   12362",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BRI",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
    },
}
</code></pre>

{% endtab %}
{% endtabs %}

***


# Mandiri Virtual Account

DOKU has partnered with various banks and one of them is Mandiri to provide Virtual Account Payment. Learn more about how DOKU can help you integrate with Mandiri Virtual Account here.

### Integration methods[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/bca-va-guide#integration-methods) <a href="#integration-methods" id="integration-methods"></a>

There are two methods to integrate with Mandiri VA:

1. **Create VA**: The VA number will be registered to DOKU and Acquirer will inquiry to our side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)
   1. **DOKU Generated Payment Code (DGPC)**: The VA number is generated by DOKU. Suitable for e-commerce business model.
   2. **Merchant Generated Payment Code (MGPC)**: The VA number is generated by Merchant. Suitable for top up business model.
2. **Direct Inquiry (DIPC)**: The VA number is registered on merchant side and DOKU will forward Acquirer inquiry request to merchant side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)

## Integration Steps

#### Precondition&#x20;

{% hint style="info" %}
Get Token API

As client who hit DOKU's API such as Create VA, you need to obtain an access token first. Learn how to do it in this [section](/accept-payments/direct-api/snap/integration-guide/get-token-api).&#x20;
{% endhint %}

{% hint style="info" %}
Generate Signature

`X- SIGNATURE` is a security parameter that needs to be generated on merchant's Backend to verify the request authenticity.

So, it's very crucial for merchant to generate the X-SIGNATURE. Learn how to do it in this [section](/get-started-with-doku-api/signature-component/snap)
{% endhint %}

Here is the overview of how to integrate with Virtual Account:

1. [Create Virtual Account](#id-1.-create-va)

   [a. DOKU Generate Payment Code](#a.-doku-generate-payment-code)

   [b. Merchant Generate Payment Code](#b.-merchant-generate-payment-code)

   [c. Display Virtual Account](#c.-display-virtual-account)

   [d. Acknowledge Payment Result](#d.-acknowledge-payment-result)

   [e. Hit DOKU Check Status API](#e.-hit-doku-check-status-api)

   [f. Delete Virtual Account](#f.-delete-payment-code)

   [g. Update Virtual Account](#g.-update-payment-code)

***

### 1. Create VA

To create VA, you will need to hit this API through your Backend:

#### API Endpoint

<table><thead><tr><th width="246">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>27</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va
</code></pre></td></tr></tbody></table>

Here is the sample request header, request body and response body for Mandiri VA&#x20;

#### a. DOKU Generate Payment Code

Check this flow diagram to get know about this method

<div align="center" data-full-width="true"><figure><img src="/files/QRd0nhEfCWjmZzOexSvn" alt=""><figcaption><p>DOKU Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="114">Type</th><th width="124">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/0ubTBJ4RHbh6SGE58rJA" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - Mandiri VA - DGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2Fy0AtQiqgDGlYU9qA3sqB%2FSNAP%20v1.1%20-%20Mandiri%20VA%20-%20DGPC.json?alt=media\&token=777cd475-b67f-4e75-ac40-0630329e413e)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

#### b. Merchant Generate Payment Code

Check this flow diagram to get know about this method

<div data-full-width="true"><figure><img src="/files/WDqzMJbMrbkQivFtU5B9" alt=""><figcaption><p>Merchant Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/dGGXAlSP9SabmklZJs5k" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - Mandiri VA - MGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FhMrabhjSfspdBds41B9u%2FSNAP%20v1.1%20-%20Mandiri%20VA%20-%20MGPC.json?alt=media\&token=1ea10a24-6103-4505-8bc0-d295159022a6)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

{% hint style="success" %}
**Pro Tips!**

1. You can also show payment instruction link to your customer by using `additionalInfo.howToPayPage`&#x20;
2. If you wish to customize the UI for the payment instruction, you can use the `additionalInfo.howToPayApi`
   {% endhint %}

#### c. Display Virtual Account

You can display the payment code to your customer by using `virtualAccountData.virtualAccountNo` that you retrieved from the API response.

#### d. Acknowledge payment result

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

{% openapi src="/files/KYNHhYJTJJ5N8QKUCF7F" path="/v1.1/transfer-va/payment" method="post" %}
[SNAP v1.1 - Mandiri VA - NOTIFICATION.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F4fgCUCCedsCwjNhr3zXj%2FSNAP%20v1.1%20-%20Mandiri%20VA%20-%20NOTIFICATION.json?alt=media\&token=e024031f-10f6-4a12-9e99-56e06568fd72)
{% endopenapi %}

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

#### f. Delete Payment Code

If you wish to delete your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/FiRU0oLShgP4HHS4o9DW" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/delete-va" method="delete" %}
[SNAP v1.1 - Mandiri VA - DELETE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FKpb4Emf1HpB7ZWoEGKTO%2FSNAP%20v1.1%20-%20Mandiri%20VA%20-%20DELETE.json?alt=media\&token=775c72ab-d459-4f2b-99d8-b1a0f6a3d3bd)
{% endopenapi %}

#### g. Update Payment Code

If you wish to update your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/yDvnuLZzYyBLkbDSdOmg" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/update-va" method="put" %}
[SNAP v1.1 - Mandiri VA - UPDATE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FPfOosw1O2qV7bgYr6FyI%2FSNAP%20v1.1%20-%20Mandiri%20VA%20-%20UPDATE.json?alt=media\&token=fe4a1ad6-956f-415a-8676-778ee7a00125)
{% endopenapi %}

***

### 2. Direct Inquiry

<table><thead><tr><th width="235">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>24</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/inquiry
</code></pre></td></tr></tbody></table>

Here is the overview of how to integrate Direct Inquiry Mandiri VA :&#x20;

2. [Direct Inquiry](#id-2.-direct-inquiry)

   a.  [Setup Inquiry URL on DOKU Dashboard](#a.-setup-inquiry-url-on-doku-dashboard)

   b. [Generate Payment Code on your End](#b.-generate-payment-code-on-your-end)

   c. [Receive Inquiry Request from DOKU](#c.-receive-inquiry-request-from-doku)

   d. [Acknowledge Payment Notification](#d.-acknowledge-payment-notification)

   e. [Hit DOKU Check Status API](#e.-hit-doku-check-status-api-1)

Check this flow to diagram to get know about this API :&#x20;

<div data-full-width="true"><figure><img src="/files/UFMZMMHHiaPNc6xvKFk1" alt=""><figcaption><p>Direct Inquiry</p></figcaption></figure></div>

To get Inquiry Request from DOKU,  you will need to hit this API through your Backend:

#### a. Setup Inquiry URL on DOKU Dashboard

To receive the inquiry request from DOKU. You must set your `Inquiry URL` to DOKU. Please contact our team for the setup.&#x20;

{% hint style="info" %}
Please inform the `Inquiry URL` for Sandbox environment and Production environment.
{% endhint %}

#### b. Generate Payment Code on your end

Generate payment is done in your system. The payment code length maximum is `23` digits.

#### c. Receive Inquiry Request from DOKU

Here is the sample request header, request body from DOKU

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

## Direct Inquiry

> Direct Inquiry

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - CREATE VA DIPC SNAP","version":"1.0.0"},"tags":[],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{merchant-domain}"}],"paths":{"/v1/transfer-va/inquiry":{"post":{"tags":["Direct Inquiry"],"summary":"Direct Inquiry","operationId":"directInquiry","description":"Direct Inquiry","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string"},"required":true,"description":"Client's current local time in yyyy-MM-dd'T'HH:mm:ssXXX format. Sample: 2024-03-19T14:39:01+07:00"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryRequest"}}},"description":"Direct Inquiry SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"DirectInquiryRequest":{"type":"object","required":["partnerServiceId","customerNo","trxDateInit","inquiryRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20","type":"string"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28"},"channelCode":{"description":"Channel code from bank | min length: 1 | max length: 10","type":"string"},"trxDateInit":{"type":"string","description":"Transaction date.  | Mandatory"},"language":{"description":"Language | min length: 1 | max length: 2","type":"string"},"inquiryRequestId":{"description":"Unique Inquiry request id. | Mandatory | min length: 1 | max length: 30","type":"string"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVARequestRef"}}},"AdditionalInfoDirectInquiyVARequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BANK_MANDIRI"]},"DirectInquiryResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","totalAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string"},"inquiryStatus":{"type":"string","description":"Status for this inquiry. Refer to case_code | min length: 1 | max length: 2"},"inquiryReason":{"$ref":"#/components/schemas/InquiryReasonRef"},"inquiryRequestId":{"description":"Unique Inquiry request id | min length: 1 | max length: 30","type":"string"}}},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVAResponseRef"}}},"TotalAmountRef":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | Mandatory |  min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency. | Mandatory | min length: 1 | max length: 3"}}},"VirtualAccountTrxTypeRef":{"description":"Transaction ID in Partner system.  1 (Closed Payment) &  2 (Open Payment) | Mandatory | min length: 1 | max length: 1","type":"string"},"InquiryReasonRef":{"type":"object","properties":{"english":{"type":"string","description":"Inquiry Reason in English | min length: 1 | max length: 18"},"indonesia":{"type":"string","description":"Inquiry Reason in Bahasa | min length: 1 | max length: 18"}}},"AdditionalInfoDirectInquiyVAResponseRef":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channel"},"virtualAccountConfig":{"$ref":"#/components/schemas/VirtualAccountConfig"}}},"VirtualAccountConfig":{"type":"object","properties":{"reusableStatus":{"type":"boolean","description":"Reusable Status For Virtual Account Transaction, value TRUE or FALSE"}}}}}}
```

#### d. Acknowledge payment notification

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

## Payment Notification

> Payment Notification

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - Core System API","version":"1.0.0"},"tags":[],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{merchant-domain}"}],"paths":{"/v1/transfer-va/payment":{"post":{"tags":["Payment Notification"],"summary":"Payment Notification","operationId":"paymentNotification","description":"Payment Notification","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string"},"required":true,"description":"Client's current local time in yyyy-MM-dd'T'HH:mm:ssXXX format. Sample: 2024-03-19T14:39:01+07:00"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationRequest"}}},"description":"Payment Notification SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"PaymentNotificationRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","totalAmount","paidAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | Mandatory | min length: 1 | max length: 64"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"},"paidAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"},"trxDateTime":{"type":"string","description":"DOKU's transaction date time"}}},"TotalAmountRef":{"type":"object","properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency | min length: 1 | max length: 3"}}},"AdditionalInfoRequestRef":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BANK_MANDIRI"]},"PaymentNotificationResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","paymentRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"}}},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"}}}}}}
```

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

### Additional Feature

#### Open Amount&#x20;

DOKU supports open payment meaning that your customer can input their own payment amount. To use open amount, you need to set `virtualAccountTrxType` = O and you  need to send `totalAmount.value` = `0`and `totalAmount.currency` = `IDR` DOKU. Here is the sample:

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "   70002",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
      ...
    "virtualAccountTrxType": "O",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

```json
{
  ...
  "virtualAccountData": {
    "partnerServiceId": "   70002",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "O",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    ...
    },
    ...
}
```

{% endtab %}
{% endtabs %}

#### Limit Amount

DOKU supports limit amount payment meaning that your customer can input their own payment amount at the range that you defined. Limit amount only available when `virtualAccountTrxType` type is `O` and `V.`To use limit amount, you need to set `virtualAccountConfig.minAmount` >= 0 or `virtualAccountConfig.maxAmount` > 0 to DOKU.

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "   70002",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BANK_MANDIRI",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  ...
  "virtualAccountData": {
    "partnerServiceId": "   70002",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BANK_MANDIRI",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
    },
}
</code></pre>

{% endtab %}
{% endtabs %}

***


# BNI Virtual Account

DOKU has partnered with various banks and one of them is BNI to provide Virtual Account Payment. Learn more about how DOKU can help you integrate with BNI Virtual Account here.

### Integration methods[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/bca-va-guide#integration-methods) <a href="#integration-methods" id="integration-methods"></a>

There are two methods to integrate with BNI VA:

1. **Create VA**: The VA number will be registered to DOKU and Acquirer will inquiry to our side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)
   1. **DOKU Generated Payment Code (DGPC)**: The VA number is generated by DOKU. Suitable for e-commerce business model.
   2. **Merchant Generated Payment Code (MGPC)**: The VA number is generated by Merchant. Suitable for top up business model.
2. **Direct Inquiry (DIPC)**: The VA number is registered on merchant side and DOKU will forward Acquirer inquiry request to merchant side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)

## Integration Steps

#### Precondition&#x20;

{% hint style="info" %}
Get Token API

As client who hit DOKU's API such as Create VA, you need to obtain an access token first. Learn how to do it in this [section](/accept-payments/direct-api/snap/integration-guide/get-token-api).&#x20;
{% endhint %}

{% hint style="info" %}
Generate Signature

`X- SIGNATURE` is a security parameter that needs to be generated on merchant's Backend to verify the request authenticity.

So, it's very crucial for merchant to generate the X-SIGNATURE. Learn how to do it in this [section](/get-started-with-doku-api/signature-component/snap)
{% endhint %}

Here is the overview of how to integrate with Virtual Account:

1. [Create Virtual Account](#id-1.-create-va)

   [a. DOKU Generate Payment Code](#a.-doku-generate-payment-code)

   [b. Merchant Generate Payment Code](#b.-merchant-generate-payment-code)

   [c. Display Virtual Account](#c.-display-virtual-account)

   [d. Acknowledge Payment Result](#d.-acknowledge-payment-result)

   [e. Hit DOKU Check Status API](#e.-hit-doku-check-status-api)

   [f. Update Virtual Account](#g.-update-payment-code)

***

### 1. Create VA

To create VA, you will need to hit this API through your Backend:

#### API Endpoint

<table><thead><tr><th width="246">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>27</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va
</code></pre></td></tr></tbody></table>

Here is the sample request header, request body and response body for BNI VA&#x20;

#### a. DOKU Generate Payment Code

Check this flow diagram to get know about this method

<div align="center" data-full-width="true"><figure><img src="/files/QRd0nhEfCWjmZzOexSvn" alt=""><figcaption><p>DOKU Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="114">Type</th><th width="124">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/M5unSq8MSU2B6u01XfYd" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - BNI VA - DGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FHlSPMIwtSxdfERGwwCSG%2FSNAP%20v1.1%20-%20BNI%20VA%20-%20DGPC.json?alt=media\&token=b9a92498-9a6e-4ae7-a3f1-06b3c9e00749)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

#### b. Merchant Generate Payment Code

Check this flow diagram to get know about this method

<div data-full-width="true"><figure><img src="/files/WDqzMJbMrbkQivFtU5B9" alt=""><figcaption><p>Merchant Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/yGw6qbvyGcytQsCAym7d" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - BNI VA - MGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F0v0WBwJVcQD7HoaFtwNr%2FSNAP%20v1.1%20-%20BNI%20VA%20-%20MGPC.json?alt=media\&token=e3a79ea9-6845-4980-abc4-0b8dcc533925)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

{% hint style="success" %}
**Pro Tips!**

1. You can also show payment instruction link to your customer by using `additionalInfo.howToPayPage`&#x20;
2. If you wish to customize the UI for the payment instruction, you can use the `additionalInfo.howToPayApi`
   {% endhint %}

#### c. Display Virtual Account

You can display the payment code to your customer by using `virtualAccountData.virtualAccountNo` that you retrieved from the API response.

#### d. Acknowledge payment result

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

{% openapi src="/files/OO0yUitbnGQNU8yZipOj" path="/v1.1/transfer-va/payment" method="post" %}
[SNAP v1.1 - BNI VA - NOTIFICATION.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2Frxf61vddWsPVKOgNG8sT%2FSNAP%20v1.1%20-%20BNI%20VA%20-%20NOTIFICATION.json?alt=media\&token=c48125d1-4738-4e5f-9a7f-008110a3c011)
{% endopenapi %}

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

#### f. Update Payment Code

If you wish to update your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/IUsiHGWTWhwuPQopQ6bh" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/update-va" method="put" %}
[SNAP v1.1 - BNI VA - UPDATE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2Fl6oc4PNMWUJEDxRyQA5g%2FSNAP%20v1.1%20-%20BNI%20VA%20-%20UPDATE.json?alt=media\&token=74617f86-a31b-4933-bd05-4ae31322d586)
{% endopenapi %}

***

### 2. Direct Inquiry

<table><thead><tr><th width="235">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>24</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/inquiry
</code></pre></td></tr></tbody></table>

Here is the overview of how to integrate Direct Inquiry BNI VA :&#x20;

2. [Direct Inquiry](#id-2.-direct-inquiry)

   a.  [Setup Inquiry URL on DOKU Dashboard](#a.-setup-inquiry-url-on-doku-dashboard)

   b. [Generate Payment Code on your End](#b.-generate-payment-code-on-your-end)

   c. [Receive Inquiry Request from DOKU](#c.-receive-inquiry-request-from-doku)

   d. [Acknowledge Payment Notification](#d.-acknowledge-payment-notification)

   e. [Hit DOKU Check Status API](#e.-hit-doku-check-status-api-1)

Check this flow to diagram to get know about this API :&#x20;

<div data-full-width="true"><figure><img src="/files/UFMZMMHHiaPNc6xvKFk1" alt=""><figcaption><p>Direct Inquiry</p></figcaption></figure></div>

To get Inquiry Request from DOKU,  you will need to hit this API through your Backend:

#### a. Setup Inquiry URL on DOKU Dashboard

To receive the inquiry request from DOKU. You must set your `Inquiry URL` to DOKU. Please contact our team for the setup.&#x20;

{% hint style="info" %}
Please inform the `Inquiry URL` for Sandbox environment and Production environment.
{% endhint %}

#### b. Generate Payment Code on your end

Generate payment is done in your system. The payment code length maximum is `23` digits.

#### c. Receive Inquiry Request from DOKU

Here is the sample request header, request body from DOKU

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

## Direct Inquiry

> Direct Inquiry

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - CREATE VA DIPC SNAP","version":"1.0.0"},"tags":[],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{merchant-domain}"}],"paths":{"/v1/transfer-va/inquiry":{"post":{"tags":["Direct Inquiry"],"summary":"Direct Inquiry","operationId":"directInquiry","description":"Direct Inquiry","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string"},"required":true,"description":"Client's current local time in yyyy-MM-dd'T'HH:mm:ssXXX format. Sample: 2024-03-19T14:39:01+07:00"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryRequest"}}},"description":"Direct Inquiry SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"DirectInquiryRequest":{"type":"object","required":["partnerServiceId","customerNo","trxDateInit","inquiryRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20","type":"string"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28"},"channelCode":{"description":"Channel code from bank | min length: 1 | max length: 10","type":"string"},"trxDateInit":{"type":"string","description":"Transaction date.  | Mandatory"},"language":{"description":"Language | min length: 1 | max length: 2","type":"string"},"inquiryRequestId":{"description":"Unique Inquiry request id. | Mandatory | min length: 1 | max length: 30","type":"string"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVARequestRef"}}},"AdditionalInfoDirectInquiyVARequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BNI"]},"DirectInquiryResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","totalAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string"},"inquiryStatus":{"type":"string","description":"Status for this inquiry. Refer to case_code | min length: 1 | max length: 2"},"inquiryReason":{"$ref":"#/components/schemas/InquiryReasonRef"},"inquiryRequestId":{"description":"Unique Inquiry request id | min length: 1 | max length: 30","type":"string"}}},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVAResponseRef"}}},"TotalAmountRef":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | Mandatory |  min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency. | Mandatory | min length: 1 | max length: 3"}}},"VirtualAccountTrxTypeRef":{"description":"Transaction ID in Partner system.  1 (Closed Payment) &  2 (Open Payment) | Mandatory | min length: 1 | max length: 1","type":"string"},"InquiryReasonRef":{"type":"object","properties":{"english":{"type":"string","description":"Inquiry Reason in English | min length: 1 | max length: 18"},"indonesia":{"type":"string","description":"Inquiry Reason in Bahasa | min length: 1 | max length: 18"}}},"AdditionalInfoDirectInquiyVAResponseRef":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channel"},"virtualAccountConfig":{"$ref":"#/components/schemas/VirtualAccountConfig"}}},"VirtualAccountConfig":{"type":"object","properties":{"reusableStatus":{"type":"boolean","description":"Reusable Status For Virtual Account Transaction, value TRUE or FALSE"}}}}}}
```

#### d. Acknowledge payment notification

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

## Payment Notification

> Payment Notification

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - Core System API","version":"1.0.0"},"tags":[],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{merchant-domain}"}],"paths":{"/v1/transfer-va/payment":{"post":{"tags":["Payment Notification"],"summary":"Payment Notification","operationId":"paymentNotification","description":"Payment Notification","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string"},"required":true,"description":"Client's current local time in yyyy-MM-dd'T'HH:mm:ssXXX format. Sample: 2024-03-19T14:39:01+07:00"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationRequest"}}},"description":"Payment Notification SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"PaymentNotificationRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","totalAmount","paidAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | Mandatory | min length: 1 | max length: 64"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"},"paidAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"},"trxDateTime":{"type":"string","description":"DOKU's transaction date time"}}},"TotalAmountRef":{"type":"object","properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency | min length: 1 | max length: 3"}}},"AdditionalInfoRequestRef":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BNI"]},"PaymentNotificationResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","paymentRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"}}},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"}}}}}}
```

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

### Additional Feature

#### Open Amount&#x20;

DOKU supports open payment meaning that your customer can input their own payment amount. To use open amount, you need to set `virtualAccountTrxType` = O and you  need to send `totalAmount.value` = `0`and `totalAmount.currency` = `IDR` DOKU. Here is the sample:

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "98829172",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
      ...
    "virtualAccountTrxType": "O",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

```json
{
  ...
  "virtualAccountData": {
    "partnerServiceId": "98829172",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "O",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    ...
    },
    ...
}
```

{% endtab %}
{% endtabs %}

#### Limit Amount

DOKU supports limit amount payment meaning that your customer can input their own payment amount at the range that you defined. Limit amount only available when `virtualAccountTrxType` type is `O` and `V.`To use limit amount, you need to set `virtualAccountConfig.minAmount` >= 0 or `virtualAccountConfig.maxAmount` > 0 to DOKU.

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "98829172",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BNI",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  ...
  "virtualAccountData": {
    "partnerServiceId": "98829172",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BNI",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
    },
}
</code></pre>

{% endtab %}
{% endtabs %}

***


# Permata Virtual Account

DOKU has partnered with various banks and one of them is Permata to provide Virtual Account Payment. Learn more about how DOKU can help you integrate with Permata Virtual Account here.

### Integration methods[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/bca-va-guide#integration-methods) <a href="#integration-methods" id="integration-methods"></a>

There are two methods to integrate with Permata VA:

1. **Create VA**: The VA number will be registered to DOKU and Acquirer will inquiry to our side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)
   1. **DOKU Generated Payment Code (DGPC)**: The VA number is generated by DOKU. Suitable for e-commerce business model.
   2. **Merchant Generated Payment Code (MGPC)**: The VA number is generated by Merchant. Suitable for top up business model.
2. **Direct Inquiry (DIPC)**: The VA number is registered on merchant side and DOKU will forward Acquirer inquiry request to merchant side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)

## Integration Steps

#### Precondition&#x20;

{% hint style="info" %}
Get Token API

As client who hit DOKU's API such as Create VA, you need to obtain an access token first. Learn how to do it in this [section](/accept-payments/direct-api/snap/integration-guide/get-token-api).&#x20;
{% endhint %}

{% hint style="info" %}
Generate Signature

`X- SIGNATURE` is a security parameter that needs to be generated on merchant's Backend to verify the request authenticity.

So, it's very crucial for merchant to generate the X-SIGNATURE. Learn how to do it in this [section](/get-started-with-doku-api/signature-component/snap)
{% endhint %}

Here is the overview of how to integrate with Virtual Account:

1. [Create Virtual Account](#id-1.-create-va)

   [a. DOKU Generate Payment Code](#a.-doku-generate-payment-code)

   [b. Merchant Generate Payment Code](#b.-merchant-generate-payment-code)

   [c. Display Virtual Account](#c.-display-virtual-account)

   [d. Acknowledge Payment Result](#d.-acknowledge-payment-result)

   [e. Hit DOKU Check Status API](#e.-hit-doku-check-status-api)

   [f. Delete Virtual Account](#f.-delete-payment-code)

   [g. Update Virtual Account](#g.-update-payment-code)

***

### 1. Create VA

To create VA, you will need to hit this API through your Backend:

#### API Endpoint

<table><thead><tr><th width="246">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>27</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va
</code></pre></td></tr></tbody></table>

Here is the sample request header, request body and response body for Permata VA&#x20;

#### a. DOKU Generate Payment Code

Check this flow diagram to get know about this method

<div align="center" data-full-width="true"><figure><img src="/files/QRd0nhEfCWjmZzOexSvn" alt=""><figcaption><p>DOKU Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="114">Type</th><th width="124">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID)</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day (request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtained from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/U6rOGD72BofdeKPJpRrG" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - PERMATA VA - DGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F1ibnwWXkUQgHqL0EFhT2%2FSNAP%20v1.1%20-%20PERMATA%20VA%20-%20DGPC.json?alt=media\&token=8bbfb81f-0261-46b9-a9cd-dda29bf79b58)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

#### b. Merchant Generate Payment Code

Check this flow diagram to get know about this method

<div data-full-width="true"><figure><img src="/files/WDqzMJbMrbkQivFtU5B9" alt=""><figcaption><p>Merchant Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID)</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day (request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtained from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/tguXvpEch7rvMR7UqZfp" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - PERMATA VA - MGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FRUDeTGqMyMYT2ypcJHNM%2FSNAP%20v1.1%20-%20PERMATA%20VA%20-%20MGPC.json?alt=media\&token=c042940b-9aa1-4e07-b603-196157baff08)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

{% hint style="success" %}
**Pro Tips!**

1. You can also show payment instruction link to your customer by using `additionalInfo.howToPayPage`&#x20;
2. If you wish to customize the UI for the payment instruction, you can use the `additionalInfo.howToPayApi`
   {% endhint %}

#### c. Display Virtual Account

You can display the payment code to your customer by using `virtualAccountData.virtualAccountNo` that you retrieved from the API response.

#### d. Acknowledge payment result

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap).

{% openapi src="/files/WLo7WoVLnZOnCZsV0nNn" path="/v1.1/transfer-va/payment" method="post" %}
[SNAP v1.1 - PERMATA VA - NOTIFICATION.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FAVeOJjan5YDGeVIjPkw9%2FSNAP%20v1.1%20-%20PERMATA%20VA%20-%20NOTIFICATION.json?alt=media\&token=030ac4ee-2743-4513-87b7-baed021e91bc)
{% endopenapi %}

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

#### f. Delete Payment Code

If you wish to delete your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/MTiwBrsTW7qMNgFU1SjG" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/delete-va" method="delete" %}
[SNAP v1.1 - PERMATA VA - DELETE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FQR554jnIDGa1TQaiFh1J%2FSNAP%20v1.1%20-%20PERMATA%20VA%20-%20DELETE.json?alt=media\&token=5cb96d9a-a621-4949-9f6a-ee31763a213b)
{% endopenapi %}

#### g. Update Payment Code

If you wish to update your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/fIfbRdf2ZZMiUbf4bYfC" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/update-va" method="put" %}
[SNAP v1.1 - PERMATA VA - UPDATE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FY64kMYnuRt0Gxv6D8xR3%2FSNAP%20v1.1%20-%20PERMATA%20VA%20-%20UPDATE.json?alt=media\&token=0b1d1ae0-a5b8-4665-b3b0-807397791d31)
{% endopenapi %}

***

### 2. Direct Inquiry

<table><thead><tr><th width="235">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>24</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/inquiry
</code></pre></td></tr></tbody></table>

Here is the overview of how to integrate Direct Inquiry Permata VA :&#x20;

2. [Direct Inquiry](#id-2.-direct-inquiry)

   a.  [Setup Inquiry URL on DOKU Dashboard](#a.-setup-inquiry-url-on-doku-dashboard)

   b. [Generate Payment Code on your End](#b.-generate-payment-code-on-your-end)

   c. [Receive Inquiry Request from DOKU](#c.-receive-inquiry-request-from-doku)

   d. [Acknowledge Payment Notification](#d.-acknowledge-payment-notification)

   e. [Hit DOKU Check Status API](#e.-hit-doku-check-status-api-1)

Check this flow to diagram to get know about this API :&#x20;

<div data-full-width="true"><figure><img src="/files/UFMZMMHHiaPNc6xvKFk1" alt=""><figcaption><p>Direct Inquiry</p></figcaption></figure></div>

To get Inquiry Request from DOKU,  you will need to hit this API through your Backend:

#### a. Setup Inquiry URL on DOKU Dashboard

To receive the inquiry request from DOKU. You must set your `Inquiry URL` to DOKU. Please contact our team for the setup.&#x20;

{% hint style="info" %}
Please inform the `Inquiry URL` for Sandbox environment and Production environment.
{% endhint %}

#### b. Generate Payment Code on your end

Generate payment is done in your system. The payment code length maximum is `28` digits.

#### c. Receive Inquiry Request from DOKU

Here is the sample request header, request body from DOKU

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/4ICWaKSyUUwQKYYM9idR" path="/v1.1/transfer-va/inquiry" method="post" %}
[SNAP v1.1 - PERMATA VA - DIPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FW8t3GbNtQsAheJDTtiCl%2FSNAP%20v1.1%20-%20PERMATA%20VA%20-%20DIPC.json?alt=media\&token=09ecc4c1-0def-4eae-b988-bbcbb0069bcb)
{% endopenapi %}

#### d. Acknowledge payment notification

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

{% openapi src="/files/b83nxaUKLKwTv4v54MeC" path="/v1.1/transfer-va/payment" method="post" %}
[SNAP v1.1 - PERMATA VA - NOTIFICATION.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FLFFfApEbZafqnRhnVyBt%2FSNAP%20v1.1%20-%20PERMATA%20VA%20-%20NOTIFICATION.json?alt=media\&token=afc06e6f-05cb-4b2e-94e3-94fd5f9fe86f)
{% endopenapi %}

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

### Additional Feature

#### Open Amount&#x20;

DOKU supports open payment meaning that your customer can input their own payment amount. To use open amount, you need to set `virtualAccountTrxType` = O and you  need to send `totalAmount.value` = `0`and `totalAmount.currency` = `IDR` DOKU. Here is the sample:

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "    8965",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
      ...
    "virtualAccountTrxType": "O",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

```json
{
  ...
  "virtualAccountData": {
    "partnerServiceId": "    8965",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "O",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    ...
    },
    ...
}
```

{% endtab %}
{% endtabs %}

#### Limit Amount

DOKU supports limit amount payment meaning that your customer can input their own payment amount at the range that you defined. Limit amount only available when `virtualAccountTrxType` type is `O` and `V.`To use limit amount, you need to set `virtualAccountConfig.minAmount` >= 0 or `virtualAccountConfig.maxAmount` > 0 to DOKU.

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "    8965",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_PERMATA",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  ...
  "virtualAccountData": {
    "partnerServiceId": "   12362",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BANK_PERMATA",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
    },
}
</code></pre>

{% endtab %}
{% endtabs %}

***


# Danamon Virtual Account

DOKU has partnered with various banks and one of them is Danamon to provide Virtual Account Payment. Learn more about how DOKU can help you integrate with Danamon Virtual Account here.

### Integration methods[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/bca-va-guide#integration-methods) <a href="#integration-methods" id="integration-methods"></a>

There are two methods to integrate with Danamon VA:

1. **Create VA**: The VA number will be registered to DOKU and Acquirer will inquiry to our side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)
   1. **DOKU Generated Payment Code (DGPC)**: The VA number is generated by DOKU. Suitable for e-commerce business model.
   2. **Merchant Generated Payment Code (MGPC)**: The VA number is generated by Merchant. Suitable for top up business model.
2. **Direct Inquiry (DIPC)**: The VA number is registered on merchant side and DOKU will forward Acquirer inquiry request to merchant side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)

## Integration Steps

#### Precondition&#x20;

{% hint style="info" %}
Get Token API

As client who hit DOKU's API such as Create VA, you need to obtain an access token first. Learn how to do it in this [section](/accept-payments/direct-api/snap/integration-guide/get-token-api).&#x20;
{% endhint %}

{% hint style="info" %}
Generate Signature

`X- SIGNATURE` is a security parameter that needs to be generated on merchant's Backend to verify the request authenticity.

So, it's very crucial for merchant to generate the X-SIGNATURE. Learn how to do it in this [section](/get-started-with-doku-api/signature-component/snap)
{% endhint %}

Here is the overview of how to integrate with Virtual Account:

1. [Create Virtual Account](#id-1.-create-va)

   [a. DOKU Generate Payment Code](#a.-doku-generate-payment-code)

   [b. Merchant Generate Payment Code](#b.-merchant-generate-payment-code)

   [c. Display Virtual Account](#c.-display-virtual-account)

   [d. Acknowledge Payment Result](#d.-acknowledge-payment-result)

   [e. Hit DOKU Check Status API](#e.-hit-doku-check-status-api)

   [f. Delete Virtual Account](#f.-delete-payment-code)

   [g. Update Virtual Account](#g.-update-payment-code)

***

### 1. Create VA

To create VA, you will need to hit this API through your Backend:

#### API Endpoint

<table><thead><tr><th width="246">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>27</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va
</code></pre></td></tr></tbody></table>

Here is the sample request header, request body and response body for Danamon VA&#x20;

#### a. DOKU Generate Payment Code

Check this flow diagram to get know about this method

<div align="center" data-full-width="true"><figure><img src="/files/QRd0nhEfCWjmZzOexSvn" alt=""><figcaption><p>DOKU Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="114">Type</th><th width="124">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID)</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day (request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtained from Get B2B Token API, refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/yMCaiccxXNMg5o68OBby" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - Danamon VA - DGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FgWVpM0F79Wuv1OTdSbe0%2FSNAP%20v1.1%20-%20Danamon%20VA%20-%20DGPC.json?alt=media\&token=bfad3edf-72a5-40de-8b29-0c5573d688bd)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

#### b. Merchant Generate Payment Code

Check this flow diagram to get know about this method

<div data-full-width="true"><figure><img src="/files/WDqzMJbMrbkQivFtU5B9" alt=""><figcaption><p>Merchant Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID)</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day (request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtained from Get B2B Token API, refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/DSiBQbrYToorXPo2uOuJ" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - Danamon VA - MGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F0k2la4B6Uc5u7o1RnofL%2FSNAP%20v1.1%20-%20Danamon%20VA%20-%20MGPC.json?alt=media\&token=0d5c1a40-3060-48dd-b788-a143b1043f49)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

{% hint style="success" %}
**Pro Tips!**

1. You can also show payment instruction link to your customer by using `additionalInfo.howToPayPage`&#x20;
2. If you wish to customize the UI for the payment instruction, you can use the `additionalInfo.howToPayApi`
   {% endhint %}

#### c. Display Virtual Account

You can display the payment code to your customer by using `virtualAccountData.virtualAccountNo` that you retrieved from the API response.

#### d. Acknowledge payment result

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

{% openapi src="/files/F85y4X4gqRROawz63u3L" path="/v1.1/transfer-va/payment" method="post" %}
[SNAP v1.1 - Danamon VA - NOTIFICATION.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FOGapIZEPWnfhnravhpoR%2FSNAP%20v1.1%20-%20Danamon%20VA%20-%20NOTIFICATION.json?alt=media\&token=538a0fb8-c9b1-4ec2-8757-5e1885b260a4)
{% endopenapi %}

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

#### f. Delete Payment Code

If you wish to delete your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/TZeo5WoExPrw5dnLvwZZ" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/delete-va" method="delete" %}
[SNAP v1.1 - Danamon VA - DELETE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2Fqt0WITvQzYj4wCiyAqtE%2FSNAP%20v1.1%20-%20Danamon%20VA%20-%20DELETE.json?alt=media\&token=55181961-997c-41d5-bc08-218f9b99b30b)
{% endopenapi %}

#### g. Update Payment Code

If you wish to update your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/lZIRhraEF6rtTDIUCPx7" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/update-va" method="put" %}
[SNAP v1.1 - Danamon VA - UPDATE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F9s4gTsQwVnoMiWd0UCMZ%2FSNAP%20v1.1%20-%20Danamon%20VA%20-%20UPDATE.json?alt=media\&token=9fe2d059-1813-4b7b-a704-1bd6bc3c9f76)
{% endopenapi %}

***

### 2. Direct Inquiry

<table><thead><tr><th width="235">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>24</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/inquiry
</code></pre></td></tr></tbody></table>

Here is the overview of how to integrate Direct Inquiry Danamon VA :&#x20;

2. [Direct Inquiry](#id-2.-direct-inquiry)

   a.  [Setup Inquiry URL on DOKU Dashboard](#a.-setup-inquiry-url-on-doku-dashboard)

   b. [Generate Payment Code on your End](#b.-generate-payment-code-on-your-end)

   c. [Receive Inquiry Request from DOKU](#c.-receive-inquiry-request-from-doku)

   d. [Acknowledge Payment Notification](#d.-acknowledge-payment-notification)

   e. [Hit DOKU Check Status API](#e.-hit-doku-check-status-api-1)

Check this flow to diagram to get know about this API :&#x20;

<div data-full-width="true"><figure><img src="/files/UFMZMMHHiaPNc6xvKFk1" alt=""><figcaption><p>Direct Inquiry</p></figcaption></figure></div>

To get Inquiry Request from DOKU,  you will need to hit this API through your Backend:

#### a. Setup Inquiry URL on DOKU Dashboard

To receive the inquiry request from DOKU. You must set your `Inquiry URL` to DOKU. Please contact our team for the setup.&#x20;

{% hint style="info" %}
Please inform the `Inquiry URL` for Sandbox environment and Production environment.
{% endhint %}

#### b. Generate Payment Code on your end

Generate payment is done in your system. The payment code length maximum is `28` digits.

#### c. Receive Inquiry Request from DOKU

Here is the sample request header, request body from DOKU

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

## Direct Inquiry

> Direct Inquiry

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - CREATE VA DIPC SNAP","version":"1.0.0"},"tags":[],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{merchant-domain}"}],"paths":{"/v1/transfer-va/inquiry":{"post":{"tags":["Direct Inquiry"],"summary":"Direct Inquiry","operationId":"directInquiry","description":"Direct Inquiry","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string"},"required":true,"description":"Client's current local time in yyyy-MM-dd'T'HH:mm:ssXXX format. Sample: 2024-03-19T14:39:01+07:00"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryRequest"}}},"description":"Direct Inquiry SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"DirectInquiryRequest":{"type":"object","required":["partnerServiceId","customerNo","trxDateInit","inquiryRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20","type":"string"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28"},"channelCode":{"description":"Channel code from bank | min length: 1 | max length: 10","type":"string"},"trxDateInit":{"type":"string","description":"Transaction date.  | Mandatory"},"language":{"description":"Language | min length: 1 | max length: 2","type":"string"},"inquiryRequestId":{"description":"Unique Inquiry request id. | Mandatory | min length: 1 | max length: 30","type":"string"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVARequestRef"}}},"AdditionalInfoDirectInquiyVARequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BANK_DANAMON"]},"DirectInquiryResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","totalAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string"},"inquiryStatus":{"type":"string","description":"Status for this inquiry. Refer to case_code | min length: 1 | max length: 2"},"inquiryReason":{"$ref":"#/components/schemas/InquiryReasonRef"},"inquiryRequestId":{"description":"Unique Inquiry request id | min length: 1 | max length: 30","type":"string"}}},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVAResponseRef"}}},"TotalAmountRef":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | Mandatory |  min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency. | Mandatory | min length: 1 | max length: 3"}}},"VirtualAccountTrxTypeRef":{"description":"Transaction ID in Partner system.  1 (Closed Payment) &  2 (Open Payment) | Mandatory | min length: 1 | max length: 1","type":"string"},"InquiryReasonRef":{"type":"object","properties":{"english":{"type":"string","description":"Inquiry Reason in English | min length: 1 | max length: 18"},"indonesia":{"type":"string","description":"Inquiry Reason in Bahasa | min length: 1 | max length: 18"}}},"AdditionalInfoDirectInquiyVAResponseRef":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channel"},"virtualAccountConfig":{"$ref":"#/components/schemas/VirtualAccountConfig"}}},"VirtualAccountConfig":{"type":"object","properties":{"reusableStatus":{"type":"boolean","description":"Reusable Status For Virtual Account Transaction, value TRUE or FALSE"}}}}}}
```

#### d. Acknowledge payment notification

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

## Payment Notification

> Payment Notification

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - Core System API","version":"1.0.0"},"tags":[],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{merchant-domain}"}],"paths":{"/v1/transfer-va/payment":{"post":{"tags":["Payment Notification"],"summary":"Payment Notification","operationId":"paymentNotification","description":"Payment Notification","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string"},"required":true,"description":"Client's current local time in yyyy-MM-dd'T'HH:mm:ssXXX format. Sample: 2024-03-19T14:39:01+07:00"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationRequest"}}},"description":"Payment Notification SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"PaymentNotificationRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","totalAmount","paidAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | Mandatory | min length: 1 | max length: 64"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"},"paidAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"},"trxDateTime":{"type":"string","description":"DOKU's transaction date time"}}},"TotalAmountRef":{"type":"object","properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency | min length: 1 | max length: 3"}}},"AdditionalInfoRequestRef":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BANK_DANAMON"]},"PaymentNotificationResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","paymentRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"}}},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"}}}}}}
```

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

### Additional Feature

#### Open Amount&#x20;

DOKU supports open payment meaning that your customer can input their own payment amount. To use open amount, you need to set `virtualAccountTrxType` = O and you  need to send `totalAmount.value` = `0`and `totalAmount.currency` = `IDR` DOKU. Here is the sample:

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "    8922",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
      ...
    "virtualAccountTrxType": "O",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

```json
{
  ...
  "virtualAccountData": {
    "partnerServiceId": "    8922",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "O",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    ...
    },
    ...
}
```

{% endtab %}
{% endtabs %}

#### Limit Amount

DOKU supports limit amount payment meaning that your customer can input their own payment amount at the range that you defined. Limit amount only available when `virtualAccountTrxType` type is `O` and `V.`To use limit amount, you need to set `virtualAccountConfig.minAmount` >= 0 or `virtualAccountConfig.maxAmount` > 0 to DOKU.

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "   8922",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_DANAMON",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  ...
  "virtualAccountData": {
    "partnerServiceId": "    8922",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_DANAMON",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
    },
}
</code></pre>

{% endtab %}
{% endtabs %}

***


# CIMB Virtual Account

DOKU has partnered with various banks and one of them is CIMB to provide Virtual Account Payment. Learn more about how DOKU can help you integrate with CIMB Virtual Account here.

### Integration methods[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/bca-va-guide#integration-methods) <a href="#integration-methods" id="integration-methods"></a>

There are two methods to integrate with CIMB VA:

1. **Create VA**: The VA number will be registered to DOKU and Acquirer will inquiry to our side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)
   1. **DOKU Generated Payment Code (DGPC)**: The VA number is generated by DOKU. Suitable for e-commerce business model.
   2. **Merchant Generated Payment Code (MGPC)**: The VA number is generated by Merchant. Suitable for top up business model.
2. **Direct Inquiry (DIPC)**: The VA number is registered on merchant side and DOKU will forward Acquirer inquiry request to merchant side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)

## Integration Steps

#### Precondition&#x20;

{% hint style="info" %}
Get Token API

As client who hit DOKU's API such as Create VA, you need to obtain an access token first. Learn how to do it in this [section](/accept-payments/direct-api/snap/integration-guide/get-token-api).&#x20;
{% endhint %}

{% hint style="info" %}
Generate Signature

`X- SIGNATURE` is a security parameter that needs to be generated on merchant's Backend to verify the request authenticity.

So, it's very crucial for merchant to generate the X-SIGNATURE. Learn how to do it in this [section](/get-started-with-doku-api/signature-component/snap)
{% endhint %}

Here is the overview of how to integrate with Virtual Account:

1. [Create Virtual Account](#id-1.-create-va)

   [a. DOKU Generate Payment Code](#a.-doku-generate-payment-code)

   [b. Merchant Generate Payment Code](#b.-merchant-generate-payment-code)

   [c. Display Virtual Account](#c.-display-virtual-account)

   [d. Acknowledge Payment Result](#d.-acknowledge-payment-result)

   [e. Hit DOKU Check Status API](#e.-hit-doku-check-status-api)

   [f. Delete Virtual Account](#f.-delete-payment-code)

   [g. Update Virtual Account](#g.-update-payment-code)

***

### 1. Create VA

To create VA, you will need to hit this API through your Backend:

#### API Endpoint

<table><thead><tr><th width="234">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>27</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va
</code></pre></td></tr></tbody></table>

Here is the sample request header, request body and response body for CIMB VA&#x20;

#### a. DOKU Generate Payment Code

Check this flow diagram to get know about this method

<div align="center" data-full-width="true"><figure><img src="/files/QRd0nhEfCWjmZzOexSvn" alt=""><figcaption><p>DOKU Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="109">Type</th><th width="131">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/3611P89YtHHD3jxePAsM" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - CIMB VA - DGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2Fzse0fefM3gH4dOjuszdV%2FSNAP%20v1.1%20-%20CIMB%20VA%20-%20DGPC.json?alt=media\&token=3fe6011f-7a24-47c7-8e40-4ae1664e4f27)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

#### b. Merchant Generate Payment Code

Check this flow diagram to get know about this method

<div data-full-width="true"><figure><img src="/files/WDqzMJbMrbkQivFtU5B9" alt=""><figcaption><p>Merchant Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th width="200">Parameter</th><th width="101">Type</th><th width="120">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtained from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/rWV4FRt51CsV3aJemgpv" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - CIMB VA - MGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FVJJpKT9UcKOQ8yjK3NpA%2FSNAP%20v1.1%20-%20CIMB%20VA%20-%20MGPC.json?alt=media\&token=72744671-31a4-4332-986c-5e9c60f7a52b)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

{% hint style="success" %}
**Pro Tips!**

1. You can also show payment instruction link to your customer by using `additionalInfo.howToPayPage`&#x20;
2. If you wish to customize the UI for the payment instruction, you can use the `additionalInfo.howToPayApi`
   {% endhint %}

#### c. Display Virtual Account

You can display the payment code to your customer by using `virtualAccountData.virtualAccountNo` that you retrieved from the API response.

#### d. Acknowledge payment result

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

{% openapi src="/files/zTIVHokbhtZBgeXymbGF" path="/v1.1/transfer-va/payment" method="post" %}
[SNAP v1.1 - CIMB VA - NOTIFICATION.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F25yPcOi3t0WkVgMjEXnm%2FSNAP%20v1.1%20-%20CIMB%20VA%20-%20NOTIFICATION.json?alt=media\&token=29b3a6bc-cdf4-430f-b0e9-828fbeb6fd3f)
{% endopenapi %}

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

#### f. Delete Payment Code

If you wish to delete your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="107">Type</th><th width="124">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/SIrSs7Tm43pld3oR96mT" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/delete-va" method="delete" %}
[SNAP v1.1 - CIMB VA - DELETE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FiTCnEQaGLKB0xW1l9VvE%2FSNAP%20v1.1%20-%20CIMB%20VA%20-%20DELETE.json?alt=media\&token=9132e115-0c9b-4ce0-b5dd-3b7c92603f2a)
{% endopenapi %}

#### g. Update Payment Code

If you wish to update your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="106">Type</th><th width="125">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/MLmwuAlDk5Bd18i4Jli8" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/update-va" method="put" %}
[SNAP v1.1 - CIMB VA - UPDATE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FGYYHp9CHgkpoeNDwJKf0%2FSNAP%20v1.1%20-%20CIMB%20VA%20-%20UPDATE.json?alt=media\&token=f6796ee6-c979-40a3-9959-63f41ebf7200)
{% endopenapi %}

***

### 2. Direct Inquiry

<table><thead><tr><th width="236">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>24</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/inquiry
</code></pre></td></tr></tbody></table>

Here is the overview of how to integrate Direct Inquiry CIMB VA :&#x20;

2. [Direct Inquiry](#id-2.-direct-inquiry)

   a.  [Setup Inquiry URL on DOKU Dashboard](#a.-setup-inquiry-url-on-doku-dashboard)

   b. [Generate Payment Code on your End](#b.-generate-payment-code-on-your-end)

   c. [Receive Inquiry Request from DOKU](#c.-receive-inquiry-request-from-doku)

   d. [Acknowledge Payment Notification](#d.-acknowledge-payment-notification)

   e. [Hit DOKU Check Status API](#e.-hit-doku-check-status-api-1)

Check this flow to diagram to get know about this API :&#x20;

<div data-full-width="true"><figure><img src="/files/UFMZMMHHiaPNc6xvKFk1" alt=""><figcaption><p>Direct Inquiry</p></figcaption></figure></div>

To get Inquiry Request from DOKU,  you will need to hit this API through your Backend:

#### a. Setup Inquiry URL on DOKU Dashboard

To receive the inquiry request from DOKU. You must set your `Inquiry URL` to DOKU. Please contact our team for the setup.&#x20;

{% hint style="info" %}
Please inform the `Inquiry URL` for Sandbox environment and Production environment.
{% endhint %}

#### b. Generate Payment Code on your end

Generate payment is done in your system. The payment code length maximum is `23` digits.

#### c. Receive Inquiry Request from DOKU

Here is the sample request header, request body from DOKU

#### Request Header

<table data-full-width="false"><thead><tr><th width="192">Parameter</th><th width="122">Type</th><th width="131">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

## Direct Inquiry

> Direct Inquiry

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - CREATE VA DIPC SNAP","version":"1.0.0"},"tags":[],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{merchant-domain}"}],"paths":{"/v1/transfer-va/inquiry":{"post":{"tags":["Direct Inquiry"],"summary":"Direct Inquiry","operationId":"directInquiry","description":"Direct Inquiry","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string"},"required":true,"description":"Client's current local time in yyyy-MM-dd'T'HH:mm:ssXXX format. Sample: 2024-03-19T14:39:01+07:00"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryRequest"}}},"description":"Direct Inquiry SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"DirectInquiryRequest":{"type":"object","required":["partnerServiceId","customerNo","trxDateInit","inquiryRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20","type":"string"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28"},"channelCode":{"description":"Channel code from bank | min length: 1 | max length: 10","type":"string"},"trxDateInit":{"type":"string","description":"Transaction date.  | Mandatory"},"language":{"description":"Language | min length: 1 | max length: 2","type":"string"},"inquiryRequestId":{"description":"Unique Inquiry request id. | Mandatory | min length: 1 | max length: 30","type":"string"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVARequestRef"}}},"AdditionalInfoDirectInquiyVARequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BANK_CIMB"]},"DirectInquiryResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","totalAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string"},"inquiryStatus":{"type":"string","description":"Status for this inquiry. Refer to case_code | min length: 1 | max length: 2"},"inquiryReason":{"$ref":"#/components/schemas/InquiryReasonRef"},"inquiryRequestId":{"description":"Unique Inquiry request id | min length: 1 | max length: 30","type":"string"}}},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVAResponseRef"}}},"TotalAmountRef":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | Mandatory |  min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency. | Mandatory | min length: 1 | max length: 3"}}},"VirtualAccountTrxTypeRef":{"description":"Transaction ID in Partner system.  1 (Closed Payment) &  2 (Open Payment) | Mandatory | min length: 1 | max length: 1","type":"string"},"InquiryReasonRef":{"type":"object","properties":{"english":{"type":"string","description":"Inquiry Reason in English | min length: 1 | max length: 18"},"indonesia":{"type":"string","description":"Inquiry Reason in Bahasa | min length: 1 | max length: 18"}}},"AdditionalInfoDirectInquiyVAResponseRef":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channel"},"virtualAccountConfig":{"$ref":"#/components/schemas/VirtualAccountConfig"}}},"VirtualAccountConfig":{"type":"object","properties":{"reusableStatus":{"type":"boolean","description":"Reusable Status For Virtual Account Transaction, value TRUE or FALSE"}}}}}}
```

#### d. Acknowledge payment notification

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

## Payment Notification

> Payment Notification

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - Core System API","version":"1.0.0"},"tags":[],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{merchant-domain}"}],"paths":{"/v1/transfer-va/payment":{"post":{"tags":["Payment Notification"],"summary":"Payment Notification","operationId":"paymentNotification","description":"Payment Notification","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string"},"required":true,"description":"Client's current local time in yyyy-MM-dd'T'HH:mm:ssXXX format. Sample: 2024-03-19T14:39:01+07:00"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationRequest"}}},"description":"Payment Notification SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"PaymentNotificationRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","totalAmount","paidAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | Mandatory | min length: 1 | max length: 64"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"},"paidAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"},"trxDateTime":{"type":"string","description":"DOKU's transaction date time"}}},"TotalAmountRef":{"type":"object","properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency | min length: 1 | max length: 3"}}},"AdditionalInfoRequestRef":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BANK_CIMB"]},"PaymentNotificationResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","paymentRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"}}}}}}}}
```

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

### Additional Feature

#### Open Amount&#x20;

DOKU supports open payment meaning that your customer can input their own payment amount. To use open amount, you need to set `virtualAccountTrxType` = O and you  need to send `totalAmount.value` = `0`and `totalAmount.currency` = `IDR` DOKU. Here is the sample:

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "    1899",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
      ...
    "virtualAccountTrxType": "O",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

```json
{
  ...
  "virtualAccountData": {
    "partnerServiceId": "    1899",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "O",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    ...
    },
    ...
}
```

{% endtab %}
{% endtabs %}

#### Limit Amount

DOKU supports limit amount payment meaning that your customer can input their own payment amount at the range that you defined. Limit amount only available when `virtualAccountTrxType` type is `O` and `V.`To use limit amount, you need to set `virtualAccountConfig.minAmount` >= 0 or `virtualAccountConfig.maxAmount` > 0 to DOKU.

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "    1899",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BANK_CIMB",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  ...
  "virtualAccountData": {
    "partnerServiceId": "    1899",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BANK_CIMB",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
    },
}
</code></pre>

{% endtab %}
{% endtabs %}

***


# BSI Virtual Account

DOKU has partnered with various banks and one of them is BSI to provide Virtual Account Payment. Learn more about how DOKU can help you integrate with BSI Virtual Account here.

### Integration methods[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/bca-va-guide#integration-methods) <a href="#integration-methods" id="integration-methods"></a>

There are two methods to integrate with BSI VA:

1. **Create VA**: The VA number will be registered to DOKU and Acquirer will inquiry to our side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)
   1. **DOKU Generated Payment Code (DGPC)**: The VA number is generated by DOKU. Suitable for e-commerce business model.
   2. **Merchant Generated Payment Code (MGPC)**: The VA number is generated by Merchant. Suitable for top up business model.
2. **Direct Inquiry (DIPC)**: The VA number is registered on merchant side and DOKU will forward Acquirer inquiry request to merchant side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)

## Integration Steps

#### Precondition&#x20;

{% hint style="info" %}
Get Token API

As client who hit DOKU's API such as Create VA, you need to obtain an access token first. Learn how to do it in this [section](/accept-payments/direct-api/snap/integration-guide/get-token-api).&#x20;
{% endhint %}

{% hint style="info" %}
Generate Signature

`X- SIGNATURE` is a security parameter that needs to be generated on merchant's Backend to verify the request authenticity.

So, it's very crucial for merchant to generate the X-SIGNATURE. Learn how to do it in this [section](/get-started-with-doku-api/signature-component/snap)
{% endhint %}

Here is the overview of how to integrate with Virtual Account:

1. [Create Virtual Account](#id-1.-create-va)

   [a. DOKU Generate Payment Code](#a.-doku-generate-payment-code)

   [b. Merchant Generate Payment Code](#b.-merchant-generate-payment-code)

   [c. Display Virtual Account](#c.-display-virtual-account)

   [d. Acknowledge Payment Result](#d.-acknowledge-payment-result)

   [e. Hit DOKU Check Status API](#e.-hit-doku-check-status-api)

   [f. Delete Virtual Account](#f.-delete-payment-code)

   [g. Update Virtual Account](#g.-update-payment-code)

***

### 1. Create VA

To create VA, you will need to hit this API through your Backend:

#### API Endpoint

<table><thead><tr><th width="243">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>27</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va
</code></pre></td></tr></tbody></table>

Here is the sample request header, request body and response body for BSI VA&#x20;

#### a. DOKU Generate Payment Code

Check this flow diagram to get know about this method

<div align="center" data-full-width="true"><figure><img src="/files/QRd0nhEfCWjmZzOexSvn" alt=""><figcaption><p>DOKU Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="124">Type</th><th width="125">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/D00ofuf39EsRgfvBDtVu" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - BSI VA - DGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FE8KKWAsE0qlkTMRPfEXl%2FSNAP%20v1.1%20-%20BSI%20VA%20-%20DGPC.json?alt=media\&token=5b58b16a-2adc-4ec8-8387-25bf68df3664)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

#### b. Merchant Generate Payment Code

Check this flow diagram to get know about this method

<div data-full-width="true"><figure><img src="/files/WDqzMJbMrbkQivFtU5B9" alt=""><figcaption><p>Merchant Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/ZWojrBdKwILu5MkESts3" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - BSI VA - MGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F6DOQHMTF1n9MxccDxy75%2FSNAP%20v1.1%20-%20BSI%20VA%20-%20MGPC.json?alt=media\&token=1a39108d-f41f-4555-b8a4-d00337890b24)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

{% hint style="success" %}
**Pro Tips!**

1. You can also show payment instruction link to your customer by using `additionalInfo.howToPayPage`&#x20;
2. If you wish to customize the UI for the payment instruction, you can use the `additionalInfo.howToPayApi`
   {% endhint %}

#### c. Display Virtual Account

You can display the payment code to your customer by using `virtualAccountData.virtualAccountNo` that you retrieved from the API response.

#### d. Acknowledge payment result

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

{% openapi src="/files/y20oSV9Y2cIotocPQEGD" path="/v1.1/transfer-va/payment" method="post" %}
[SNAP v1.1 - BSI VA - NOTIFICATION.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FdP77TF6Z955moYOol8pJ%2FSNAP%20v1.1%20-%20BSI%20VA%20-%20NOTIFICATION.json?alt=media\&token=e78371e5-643c-4522-9695-29fc4d56bcf9)
{% endopenapi %}

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

#### f. Delete Payment Code

If you wish to delete your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th width="206">Parameter</th><th width="88">Type</th><th width="127">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/IoZrkn93FlhwZO6LpvPg" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/delete-va" method="delete" %}
[SNAP v1.1 - BSI VA - DELETE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F22tgCNW2JSPG2zITSfzt%2FSNAP%20v1.1%20-%20BSI%20VA%20-%20DELETE.json?alt=media\&token=68a57171-9f12-4e2d-9319-0d1d0a133ba9)
{% endopenapi %}

#### g. Update Payment Code

If you wish to update your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th width="181">Parameter</th><th width="125">Type</th><th width="125">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/zqJyFGYeUqccvYuLtlVY" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/update-va" method="put" %}
[SNAP v1.1 - BSI VA - UPDATE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FYLHnr0vyilkhjuwn8Dl8%2FSNAP%20v1.1%20-%20BSI%20VA%20-%20UPDATE.json?alt=media\&token=fc45c1bb-74ec-4dff-93f7-3489b64263c5)
{% endopenapi %}

***

### 2. Direct Inquiry

<table><thead><tr><th width="236">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>24</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/inquiry
</code></pre></td></tr></tbody></table>

Here is the overview of how to integrate Direct Inquiry BNI VA :&#x20;

2. [Direct Inquiry](#id-2.-direct-inquiry)

   a.  [Setup Inquiry URL on DOKU Dashboard](#a.-setup-inquiry-url-on-doku-dashboard)

   b. [Generate Payment Code on your End](#b.-generate-payment-code-on-your-end)

   c. [Receive Inquiry Request from DOKU](#c.-receive-inquiry-request-from-doku)

   d. [Acknowledge Payment Notification](#d.-acknowledge-payment-notification)

   e. [Hit DOKU Check Status API](#e.-hit-doku-check-status-api-1)

Check this flow to diagram to get know about this API :&#x20;

<div data-full-width="true"><figure><img src="/files/UFMZMMHHiaPNc6xvKFk1" alt=""><figcaption><p>Direct Inquiry</p></figcaption></figure></div>

To get Inquiry Request from DOKU,  you will need to hit this API through your Backend:

#### a. Setup Inquiry URL on DOKU Dashboard

To receive the inquiry request from DOKU. You must set your `Inquiry URL` to DOKU. Please contact our team for the setup.&#x20;

{% hint style="info" %}
Please inform the `Inquiry URL` for Sandbox environment and Production environment.
{% endhint %}

#### b. Generate Payment Code on your end

Generate payment is done in your system. The payment code length maximum is `23` digits.

#### c. Receive Inquiry Request from DOKU

Here is the sample request header, request body from DOKU

#### Request Header

<table data-full-width="false"><thead><tr><th width="194">Parameter</th><th width="100">Type</th><th width="134">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

## Direct Inquiry

> Direct Inquiry

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - CREATE VA DIPC SNAP","version":"1.0.0"},"tags":[],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{merchant-domain}"}],"paths":{"/v1/transfer-va/inquiry":{"post":{"tags":["Direct Inquiry"],"summary":"Direct Inquiry","operationId":"directInquiry","description":"Direct Inquiry","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string"},"required":true,"description":"Client's current local time in yyyy-MM-dd'T'HH:mm:ssXXX format. Sample: 2024-03-19T14:39:01+07:00"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryRequest"}}},"description":"Direct Inquiry SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"DirectInquiryRequest":{"type":"object","required":["partnerServiceId","customerNo","trxDateInit","inquiryRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20","type":"string"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28"},"channelCode":{"description":"Channel code from bank | min length: 1 | max length: 10","type":"string"},"trxDateInit":{"type":"string","description":"Transaction date.  | Mandatory"},"language":{"description":"Language | min length: 1 | max length: 2","type":"string"},"inquiryRequestId":{"description":"Unique Inquiry request id. | Mandatory | min length: 1 | max length: 30","type":"string"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVARequestRef"}}},"AdditionalInfoDirectInquiyVARequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BSI"]},"DirectInquiryResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","totalAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string"},"inquiryStatus":{"type":"string","description":"Status for this inquiry. Refer to case_code | min length: 1 | max length: 2"},"inquiryReason":{"$ref":"#/components/schemas/InquiryReasonRef"},"inquiryRequestId":{"description":"Unique Inquiry request id | min length: 1 | max length: 30","type":"string"}}},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVAResponseRef"}}},"TotalAmountRef":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | Mandatory |  min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency. | Mandatory | min length: 1 | max length: 3"}}},"VirtualAccountTrxTypeRef":{"description":"Transaction ID in Partner system.  1 (Closed Payment) &  2 (Open Payment) | Mandatory | min length: 1 | max length: 1","type":"string"},"InquiryReasonRef":{"type":"object","properties":{"english":{"type":"string","description":"Inquiry Reason in English | min length: 1 | max length: 18"},"indonesia":{"type":"string","description":"Inquiry Reason in Bahasa | min length: 1 | max length: 18"}}},"AdditionalInfoDirectInquiyVAResponseRef":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channel"},"virtualAccountConfig":{"$ref":"#/components/schemas/VirtualAccountConfig"}}},"VirtualAccountConfig":{"type":"object","properties":{"reusableStatus":{"type":"boolean","description":"Reusable Status For Virtual Account Transaction, value TRUE or FALSE"}}}}}}
```

#### d. Acknowledge payment notification

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

## Payment Notification

> Payment Notification

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - Core System API","version":"1.0.0"},"tags":[],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{merchant-domain}"}],"paths":{"/v1/transfer-va/payment":{"post":{"tags":["Payment Notification"],"summary":"Payment Notification","operationId":"paymentNotification","description":"Payment Notification","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string"},"required":true,"description":"Client's current local time in yyyy-MM-dd'T'HH:mm:ssXXX format. Sample: 2024-03-19T14:39:01+07:00"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"channel Id for VA"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationRequest"}}},"description":"Payment Notification SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"PaymentNotificationRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","totalAmount","paidAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | Mandatory | min length: 1 | max length: 64"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"},"paidAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"},"trxDateTime":{"type":"string","description":"DOKU's transaction date time"}}},"TotalAmountRef":{"type":"object","properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency | min length: 1 | max length: 3"}}},"AdditionalInfoRequestRef":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BSI"]},"PaymentNotificationResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","paymentRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name. | Mandatory | min length: 1 | max length: 255"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"}}},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"}}}}}}
```

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

## Additional Feature <a href="#additional-feature" id="additional-feature"></a>

**Open Amount**

DOKU supports open payment meaning that your customer can input their own payment amount. To use open amount, you need to set `virtualAccountTrxType` = O and you need to send `totalAmount.value` = `0`and `totalAmount.currency` = `IDR` DOKU. Here is the sample :

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "    6059",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
      ...
    "virtualAccountTrxType": "O",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

```json
{
  ...
  "virtualAccountData": {
    "partnerServiceId": "    6059",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "O",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    ...
    },
    ...
}
```

{% endtab %}
{% endtabs %}

#### Limit Amount

DOKU supports limit amount payment meaning that your customer can input their own payment amount at the range that you defined. Limit amount only available when `virtualAccountTrxType` type is `O` and `V.`To use limit amount, you need to set `virtualAccountConfig.minAmount` >= 0 or `virtualAccountConfig.maxAmount` > 0 to DOKU.

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "    6059",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BSI",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  ...
  "virtualAccountData": {
    "partnerServiceId": "    6059",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BSI",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
    },
}
</code></pre>

{% endtab %}
{% endtabs %}

***


# BNC Virtual Account

DOKU has partnered with various banks and one of them is BNC to provide Virtual Account Payment. Learn more about how DOKU can help you integrate with BNC Virtual Account here.

### Integration methods[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/bca-va-guide#integration-methods) <a href="#integration-methods" id="integration-methods"></a>

There are two methods to integrate with BNC VA:

1. **Create VA**: The VA number will be registered to DOKU and Acquirer will inquiry to our side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)
   1. **DOKU Generated Payment Code (DGPC)**: The VA number is generated by DOKU. Suitable for e-commerce business model.
   2. **Merchant Generated Payment Code (MGPC)**: The VA number is generated by Merchant. Suitable for top up business model.
2. **Direct Inquiry (DIPC)**: The VA number is registered on merchant side and DOKU will forward Acquirer inquiry request to merchant side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)

## Integration Steps

#### Precondition&#x20;

{% hint style="info" %}
Get Token API

As client who hit DOKU's API such as Create VA, you need to obtain an access token first. Learn how to do it in this [section](/accept-payments/direct-api/snap/integration-guide/get-token-api).&#x20;
{% endhint %}

{% hint style="info" %}
Generate Signature

`X- SIGNATURE` is a security parameter that needs to be generated on merchant's Backend to verify the request authenticity.

So, it's very crucial for merchant to generate the X-SIGNATURE. Learn how to do it in this [section](/get-started-with-doku-api/signature-component/snap)
{% endhint %}

Here is the overview of how to integrate with Virtual Account:

1. [Create Virtual Account](#id-1.-create-va)

   [a. DOKU Generate Payment Code](#a.-doku-generate-payment-code)

   [b. Merchant Generate Payment Code](#b.-merchant-generate-payment-code)

   [c. Display Virtual Account](#c.-display-virtual-account)

   [d. Acknowledge Payment Result](#d.-acknowledge-payment-result)

   [e. Hit DOKU Check Status API](#e.-hit-doku-check-status-api)

   [f. Update Virtual Account](#g.-update-payment-code)

***

### 1. Create VA

To create VA, you will need to hit this API through your Backend:

#### API Endpoint

<table><thead><tr><th width="246">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>27</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va
</code></pre></td></tr></tbody></table>

Here is the sample request header, request body and response body for BNC VA&#x20;

#### a. DOKU Generate Payment Code

Check this flow diagram to get know about this method

<div align="center" data-full-width="true"><figure><img src="/files/QRd0nhEfCWjmZzOexSvn" alt=""><figcaption><p>DOKU Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="114">Type</th><th width="124">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/G1yamsFHs8ODfvI0uG4r" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - BNC VA - DGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FChFU511HXdxLXGb1xmlJ%2FSNAP%20v1.1%20-%20BNC%20VA%20-%20DGPC.json?alt=media\&token=7966f76e-7256-4be4-a7e5-6ef6dbf251e8)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

#### b. Merchant Generate Payment Code

Check this flow diagram to get know about this method

<div data-full-width="true"><figure><img src="/files/WDqzMJbMrbkQivFtU5B9" alt=""><figcaption><p>Merchant Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/KEI1kNVd07ukujexOvqm" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - BNC VA - MGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FIlxmCYnig6qJjl3oLW7G%2FSNAP%20v1.1%20-%20BNC%20VA%20-%20MGPC.json?alt=media\&token=c876a29c-edcc-4c36-8ea8-ff241352ea20)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

{% hint style="success" %}
**Pro Tips!**

1. You can also show payment instruction link to your customer by using `additionalInfo.howToPayPage`&#x20;
2. If you wish to customize the UI for the payment instruction, you can use the `additionalInfo.howToPayApi`
   {% endhint %}

#### c. Display Virtual Account

You can display the payment code to your customer by using `virtualAccountData.virtualAccountNo` that you retrieved from the API response.

#### d. Acknowledge payment result

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

{% openapi src="/files/4uVwXsc4F8OJQ6v3Mqqy" path="/v1.1/transfer-va/payment" method="post" %}
[SNAP v1.1 - BNC VA - NOTIFICATION.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FSjuVPZ3yeMkUrdJfsn1D%2FSNAP%20v1.1%20-%20BNC%20VA%20-%20NOTIFICATION.json?alt=media\&token=f3bd07e1-6135-466f-9e77-30e590a16b97)
{% endopenapi %}

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

#### f. Update Payment Code

If you wish to update your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/JYpzqUeHvG1rzLH2GgPL" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/update-va" method="put" %}
[SNAP v1.1 - BNC VA - UPDATE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F4x39mp0sd7EdCqTj43k3%2FSNAP%20v1.1%20-%20BNC%20VA%20-%20UPDATE.json?alt=media\&token=f93617fa-731c-4060-a19e-218d3756d874)
{% endopenapi %}

***

### 2. Direct Inquiry

<table><thead><tr><th width="235">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>24</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/inquiry
</code></pre></td></tr></tbody></table>

Here is the overview of how to integrate Direct Inquiry BNC VA :&#x20;

2. [Direct Inquiry](#id-2.-direct-inquiry)

   a.  [Setup Inquiry URL on DOKU Dashboard](#a.-setup-inquiry-url-on-doku-dashboard)

   b. [Generate Payment Code on your End](#b.-generate-payment-code-on-your-end)

   c. [Receive Inquiry Request from DOKU](#c.-receive-inquiry-request-from-doku)

   d. [Acknowledge Payment Notification](#d.-acknowledge-payment-notification)

   e. [Hit DOKU Check Status API](#e.-hit-doku-check-status-api-1)

Check this flow to diagram to get know about this API :&#x20;

<div data-full-width="true"><figure><img src="/files/UFMZMMHHiaPNc6xvKFk1" alt=""><figcaption><p>Direct Inquiry</p></figcaption></figure></div>

To get Inquiry Request from DOKU,  you will need to hit this API through your Backend:

#### a. Setup Inquiry URL on DOKU Dashboard

To receive the inquiry request from DOKU. You must set your `Inquiry URL` to DOKU. Please contact our team for the setup.&#x20;

{% hint style="info" %}
Please inform the `Inquiry URL` for Sandbox environment and Production environment.
{% endhint %}

#### b. Generate Payment Code on your end

Generate payment is done in your system. The payment code length maximum is `23` digits.

#### c. Receive Inquiry Request from DOKU

Here is the sample request header, request body from DOKU

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/d1VYuaM3IUKZPQs7k5Xa" path="/v1.1/transfer-va/inquiry" method="post" %}
[SNAP v1.1 - BNC VA - DIPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FrXi85lqizpquGD1h9jU3%2FSNAP%20v1.1%20-%20BNC%20VA%20-%20DIPC.json?alt=media\&token=a4c4c11c-de19-46e5-b40e-8de21ab0fc36)
{% endopenapi %}

#### d. Acknowledge payment notification

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

{% openapi src="/files/Jd9jvxC4s6IAzdJecBFc" path="/v1.1/transfer-va/payment" method="post" %}
[SNAP v1.1 - BNC VA - NOTIFICATION.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FgY7evrO4ZFtjL23n55YF%2FSNAP%20v1.1%20-%20BNC%20VA%20-%20NOTIFICATION.json?alt=media\&token=4f3a883d-8951-4a12-b25b-b03eab7c21f8)
{% endopenapi %}

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

### Additional Feature

#### Open Amount&#x20;

DOKU supports open payment meaning that your customer can input their own payment amount. To use open amount, you need to set `virtualAccountTrxType` = O and you  need to send `totalAmount.value` = `0`and `totalAmount.currency` = `IDR` DOKU. Here is the sample:

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "90341537",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
      ...
    "virtualAccountTrxType": "O",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

```json
{
  ...
  "virtualAccountData": {
    "partnerServiceId": "90341537",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "O",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    ...
    },
    ...
}
```

{% endtab %}
{% endtabs %}

#### Limit Amount

DOKU supports limit amount payment meaning that your customer can input their own payment amount at the range that you defined. Limit amount only available when `virtualAccountTrxType` type is `O` and `V.`To use limit amount, you need to set `virtualAccountConfig.minAmount` >= 0 or `virtualAccountConfig.maxAmount` > 0 to DOKU.

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "90341537",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BNC",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  ...
  "virtualAccountData": {
    "partnerServiceId": "90341537",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BNC",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
    },
}
</code></pre>

{% endtab %}
{% endtabs %}

***


# BTN Virtual Account

DOKU has partnered with various banks and one of them is BTN to provide Virtual Account Payment. Learn more about how DOKU can help you integrate with BTN Virtual Account here.

### Integration methods[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/bca-va-guide#integration-methods) <a href="#integration-methods" id="integration-methods"></a>

There are two methods to integrate with BTN VA:

1. **Create VA**: The VA number will be registered to DOKU and Acquirer will inquiry to our side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)
   1. **DOKU Generated Payment Code (DGPC)**: The VA number is generated by DOKU. Suitable for e-commerce business model.
   2. **Merchant Generated Payment Code (MGPC)**: The VA number is generated by Merchant. Suitable for top up business model.
2. **Direct Inquiry (DIPC)**: The VA number is registered on merchant side and DOKU will forward Acquirer inquiry request to merchant side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)

## Integration Steps

#### Precondition&#x20;

{% hint style="info" %}
Get Token API

As client who hit DOKU's API such as Create VA, you need to obtain an access token first. Learn how to do it in this [section](/accept-payments/direct-api/snap/integration-guide/get-token-api).&#x20;
{% endhint %}

{% hint style="info" %}
Generate Signature

`X- SIGNATURE` is a security parameter that needs to be generated on merchant's Backend to verify the request authenticity.

So, it's very crucial for merchant to generate the X-SIGNATURE. Learn how to do it in this [section](/get-started-with-doku-api/signature-component/snap)
{% endhint %}

Here is the overview of how to integrate with Virtual Account:

1. [Create Virtual Account](#id-1.-create-va)

   [a. DOKU Generate Payment Code](#a.-doku-generate-payment-code)

   [b. Merchant Generate Payment Code](#b.-merchant-generate-payment-code)

   [c. Display Virtual Account](#c.-display-virtual-account)

   [d. Acknowledge Payment Result](#d.-acknowledge-payment-result)

   [e. Hit DOKU Check Status API](#e.-hit-doku-check-status-api)

   [f. Delete Virtual Account](#f.-delete-payment-code)

   [g. Update Virtual Account](#g.-update-payment-code)

***

### 1. Create VA

To create VA, you will need to hit this API through your Backend:

#### API Endpoint

<table><thead><tr><th width="246">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>27</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va
</code></pre></td></tr></tbody></table>

Here is the sample request header, request body and response body for BTN VA&#x20;

#### a. DOKU Generate Payment Code

Check this flow diagram to get know about this method

<div align="center" data-full-width="true"><figure><img src="/files/QRd0nhEfCWjmZzOexSvn" alt=""><figcaption><p>DOKU Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="114">Type</th><th width="124">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/eV4ETZbD4iLoROK7vXBA" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - BTN VA - DGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F48zUnxCFeSrdrY1NQlBK%2FSNAP%20v1.1%20-%20BTN%20VA%20-%20DGPC.json?alt=media\&token=86c70180-2430-4bbb-a011-09dd5ce58eab)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

#### b. Merchant Generate Payment Code

Check this flow diagram to get know about this method

<div data-full-width="true"><figure><img src="/files/WDqzMJbMrbkQivFtU5B9" alt=""><figcaption><p>Merchant Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/uzagneDs112v8rBSx5Oy" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - BTN VA - MGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F6fHGROLDexI0Wgy681Ms%2FSNAP%20v1.1%20-%20BTN%20VA%20-%20MGPC.json?alt=media\&token=e85f5810-3cd0-459b-a370-cfa4ab4cfd12)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

{% hint style="success" %}
**Pro Tips!**

1. You can also show payment instruction link to your customer by using `additionalInfo.howToPayPage`&#x20;
2. If you wish to customize the UI for the payment instruction, you can use the `additionalInfo.howToPayApi`
   {% endhint %}

#### c. Display Virtual Account

You can display the payment code to your customer by using `virtualAccountData.virtualAccountNo` that you retrieved from the API response.

#### d. Acknowledge payment result

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

{% openapi src="/files/6h6tRbS1TEnmgsUlmfos" path="/v1.1/transfer-va/payment" method="post" %}
[SNAP v1.1 - BTN VA - NOTIFICATION.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2Fy6rIE4AqjijuPnIBb0lh%2FSNAP%20v1.1%20-%20BTN%20VA%20-%20NOTIFICATION.json?alt=media\&token=41a03a2b-6610-4c5c-aac5-931e15d01a32)
{% endopenapi %}

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

#### f. Delete Payment Code

If you wish to delete your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/xcLwbIqGZ5d3FHpH6oEp" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/delete-va" method="delete" %}
[SNAP v1.1 - BTN VA - DELETE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FEVMT8dXE0KkIVzaxScy9%2FSNAP%20v1.1%20-%20BTN%20VA%20-%20DELETE.json?alt=media\&token=00ee9573-6f36-4ffe-9024-d8e3737f6ccd)
{% endopenapi %}

#### g. Update Payment Code

If you wish to update your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/bXrUMvlcXfWOGxwoQ9qc" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/update-va" method="put" %}
[SNAP v1.1 - BTN VA - UPDATE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FajNE9D3TFDr8tecp4Yrm%2FSNAP%20v1.1%20-%20BTN%20VA%20-%20UPDATE.json?alt=media\&token=e06d674e-8476-4088-95a6-aec80c921aa9)
{% endopenapi %}

***

### 2. Direct Inquiry

<table><thead><tr><th width="235">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>24</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/inquiry
</code></pre></td></tr></tbody></table>

Here is the overview of how to integrate Direct Inquiry BTN VA :&#x20;

2. [Direct Inquiry](#id-2.-direct-inquiry)

   a.  [Setup Inquiry URL on DOKU Dashboard](#a.-setup-inquiry-url-on-doku-dashboard)

   b. [Generate Payment Code on your End](#b.-generate-payment-code-on-your-end)

   c. [Receive Inquiry Request from DOKU](#c.-receive-inquiry-request-from-doku)

   d. [Acknowledge Payment Notification](#d.-acknowledge-payment-notification)

   e. [Hit DOKU Check Status API](#e.-hit-doku-check-status-api-1)

Check this flow to diagram to get know about this API :&#x20;

<div data-full-width="true"><figure><img src="/files/UFMZMMHHiaPNc6xvKFk1" alt=""><figcaption><p>Direct Inquiry</p></figcaption></figure></div>

To get Inquiry Request from DOKU,  you will need to hit this API through your Backend:

#### a. Setup Inquiry URL on DOKU Dashboard

To receive the inquiry request from DOKU. You must set your `Inquiry URL` to DOKU. Please contact our team for the setup.&#x20;

{% hint style="info" %}
Please inform the `Inquiry URL` for Sandbox environment and Production environment.
{% endhint %}

#### b. Generate Payment Code on your end

Generate payment is done in your system. The payment code length maximum is `28` digits.

#### c. Receive Inquiry Request from DOKU

Here is the sample request header, request body from DOKU

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID )</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day ( request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtainedn from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

## Direct Inquiry

> Direct Inquiry

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - CREATE VA DIPC SNAP","version":"1.0.0"},"tags":[],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{merchant-domain}"}],"paths":{"/v1.1/transfer-va/inquiry":{"post":{"tags":["Direct Inquiry"],"summary":"Direct Inquiry","operationId":"directInquiry","description":"Direct Inquiry","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string"},"required":true,"description":"Client's current local time in yyyy-MM-dd'T'HH:mm:ssXXX format. Sample: 2024-03-19T14:39:01+07:00"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"Channel Id for VA. Please fill with H2H (Host-To-Host)"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryRequest"}}},"description":"Direct Inquiry SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInquiryResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"DirectInquiryRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","trxDateInit","inquiryRequestId","additionalInfo"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"channelCode":{"description":"Channel code from bank | min length: 1 | max length: 10","type":"string"},"trxDateInit":{"type":"string","description":"Transaction date.  | Mandatory"},"language":{"description":"Language | min length: 1 | max length: 2","type":"string"},"inquiryRequestId":{"description":"Unique Inquiry request id. | Mandatory | min length: 1 | max length: 30","type":"string"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVARequestRef"}}},"AdditionalInfoDirectInquiyVARequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BTN"]},"DirectInquiryResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","totalAmount","virtualAccountTrxType","inquiryRequestId"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"totalAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"},"expiredDate":{"type":"string"},"inquiryStatus":{"type":"string","description":"Status for this inquiry. Refer to case_code | min length: 1 | max length: 2"},"inquiryReason":{"$ref":"#/components/schemas/InquiryReasonRef"},"inquiryRequestId":{"description":"Unique Inquiry request id | min length: 1 | max length: 30","type":"string"},"freeText":{"$ref":"#/components/schemas/FreeTextsRefs"}}},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDirectInquiyVAResponseRef"}}},"TotalAmountRef":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | Mandatory |  min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency. | Mandatory | min length: 1 | max length: 3"}}},"VirtualAccountTrxTypeRef":{"description":"Transaction type for this transaction.  C (Closed Amount), O (Open Amount), V (Bill Variable Amount) | Mandatory | min length: 1 | max length: 1","type":"string"},"InquiryReasonRef":{"type":"object","properties":{"english":{"type":"string","description":"Inquiry Reason in English | min length: 1 | max length: 18"},"indonesia":{"type":"string","description":"Inquiry Reason in Bahasa | min length: 1 | max length: 18"}}},"FreeTextsRefs":{"type":"array","description":"Free text for additional description. | Optional | min length: 1 | max length: 64","items":{"type":"object","properties":{"english":{"type":"string"},"indonesia":{"type":"string"}}}},"AdditionalInfoDirectInquiyVAResponseRef":{"type":"object","required":["channel","trxId"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"trxId":{"type":"string","description":"Invoice Number | Optional |  min length: 1 | max length: 32"},"virtualAccountConfig":{"$ref":"#/components/schemas/VirtualAccountConfig"}}},"VirtualAccountConfig":{"type":"object","properties":{"reusableStatus":{"type":"boolean","description":"Reusable Status For Virtual Account Transaction, value TRUE or FALSE"},"minAmount":{"type":"string","description":"Minimum Amount. Minimum Amount can be use only if virtualAccountTrxType is Open Amount (O) or Bill Variable (V). With 2 decimal, format ISO 4217 | Optional |  min length: 1 | max length: 16.2"},"maxAmount":{"type":"string","description":"Maximum Amount. Maximum Amount can be use only if virtualAccountTrxType is Open Amount (O) or Bill Variable (V). With 2 decimal,format ISO 4217 | Optional |  min length: 1 | max length: 16.2"}}}}}}
```

#### d. Acknowledge payment notification

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap) .

## Payment Notification

> Payment Notification

```json
{"openapi":"3.0.0","info":{"title":"Virtual Account - Core System API","version":"1.0.0"},"tags":[],"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://{merchant-domain}"}],"paths":{"/v1.1/transfer-va/payment":{"post":{"tags":["Payment Notification"],"summary":"Payment Notification","operationId":"paymentNotification","description":"Payment Notification","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string"},"required":true,"description":"Client's current local time in yyyy-MM-dd'T'HH:mm:ssXXX format. Sample: 2024-03-19T14:39:01+07:00"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","required":true,"schema":{"type":"string"},"description":"Channel Id for VA. Please fill with H2H (Host-To-Host)"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationRequest"}}},"description":"Payment Notification SNAP request"},"responses":{"200":{"description":"item created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"}}}}}}}}}},"components":{"schemas":{"PaymentNotificationRequest":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","trxId","paidAmount","additionalInfo"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"trxId":{"type":"string","description":"Transaction ID in Partner system. | Mandatory | min length: 1 | max length: 64"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"},"paidAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountPhone":{"type":"string","description":"Customer Phone, Format: 62xxxxxxxxx xxxx | min length: 9 | max length: 30"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"},"trxDateTime":{"type":"string","description":"DOKU's transaction date time"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"}}},"TotalAmountRef":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency | min length: 1 | max length: 3"}}},"AdditionalInfoRequestRef":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"virtualAccountConfig":{"type":"object","properties":{"minAmount":{"type":"string","description":"Minimum Amount. Minimum Amount can be use only if virtualAccountTrxType is Open Amount (O) or Bill Variable (V). With 2 decimal, format ISO 4217 | Optional |  min length: 1 | max length: 16.2"},"maxAmount":{"type":"string","description":"Maximum Amount. Maximum Amount can be use only if virtualAccountTrxType is Open Amount (O) or Bill Variable (V). With 2 decimal,format ISO 4217 | Optional |  min length: 1 | max length: 16.2"}}}}},"Channel":{"type":"string","description":"Channel that will be apply for this VA | Mandatory | min length: 1 | max length:  30","enum":["VIRTUAL_ACCOUNT_BTN"]},"VirtualAccountTrxTypeRef":{"description":"Transaction type for this transaction.  C (Closed Amount), O (Open Amount), V (Bill Variable Amount) | Mandatory | min length: 1 | max length: 1","type":"string"},"PaymentNotificationResponse":{"type":"object","required":["responseCode","responseMessage","virtualAccountData"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/error-handling/http-status-and-case-code#id-1.-virtual-account . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"virtualAccountData":{"type":"object","required":["partnerServiceId","customerNo","virtualAccountNo","virtualAccountName","paymentRequestId","paidAmount"],"properties":{"partnerServiceId":{"type":"string","description":"similar to company code/BIN,8 digit left padding space. | Mandatory | min length: 1 | max length: 8"},"customerNo":{"type":"string","description":"Unique number (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 20"},"virtualAccountNo":{"type":"string","description":"partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). partnerServiceId + customerNo or virtualAccountNo. | Mandatory | min length: 1 | max length: 28"},"virtualAccountName":{"type":"string","description":"Customer Name | min length: 1 | max length: 255"},"virtualAccountEmail":{"type":"string","description":"Customer Email | min length: 1 | max length: 255"},"paymentRequestId":{"description":"Unique identifier generated by PJP. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId. | Mandatory | min length: 1 | max length: 30","type":"string"},"paidAmount":{"$ref":"#/components/schemas/TotalAmountRef"},"virtualAccountTrxType":{"$ref":"#/components/schemas/VirtualAccountTrxTypeRef"}}},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoRequestRef"}}}}}}
```

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

### Additional Feature

#### Open Amount&#x20;

DOKU supports open payment meaning that your customer can input their own payment amount. To use open amount, you need to set `virtualAccountTrxType` = O and you  need to send `totalAmount.value` = `0`and `totalAmount.currency` = `IDR` DOKU. Here is the sample:

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "   95962",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
      ...
    "virtualAccountTrxType": "O",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

```json
{
  ...
  "virtualAccountData": {
    "partnerServiceId": "   95962",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "O",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    ...
    },
    ...
}
```

{% endtab %}
{% endtabs %}

#### Limit Amount

DOKU supports limit amount payment meaning that your customer can input their own payment amount at the range that you defined. Limit amount only available when `virtualAccountTrxType` type is `O` and `V.`To use limit amount, you need to set `virtualAccountConfig.minAmount` >= 0 or `virtualAccountConfig.maxAmount` > 0 to DOKU.

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "   95962",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BTN",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  ...
  "virtualAccountData": {
    "partnerServiceId": "   95962",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BTN",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
    },
}
</code></pre>

{% endtab %}
{% endtabs %}

***


# BSS Virtual Account

DOKU has partnered with various banks and one of them is BSS to provide Virtual Account Payment. Learn more about how DOKU can help you integrate with BSS Virtual Account here.

### Integration methods[​](https://dashboard.doku.com/docs/docs/jokul-direct/virtual-account/bca-va-guide#integration-methods) <a href="#integration-methods" id="integration-methods"></a>

There are two methods to integrate with BSS VA:

1. **Create VA**: The VA number will be registered to DOKU and Acquirer will inquiry to our side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)
   1. **DOKU Generated Payment Code (DGPC)**: The VA number is generated by DOKU. Suitable for e-commerce business model.
   2. **Merchant Generated Payment Code (MGPC)**: The VA number is generated by Merchant. Suitable for top up business model.
2. **Direct Inquiry (DIPC)**: The VA number is registered on merchant side and DOKU will forward Acquirer inquiry request to merchant side when the customer make payment at the acquirer channel (ATM, mobile banking, internet banking, etc.)

## Integration Steps

#### Precondition&#x20;

{% hint style="info" %}
Get Token API

As client who hit DOKU's API such as Create VA, you need to obtain an access token first. Learn how to do it in this [section](/accept-payments/direct-api/snap/integration-guide/get-token-api).&#x20;
{% endhint %}

{% hint style="info" %}
Generate Signature

`X- SIGNATURE` is a security parameter that needs to be generated on merchant's Backend to verify the request authenticity.

So, it's very crucial for merchant to generate the X-SIGNATURE. Learn how to do it in this [section](/get-started-with-doku-api/signature-component/snap)
{% endhint %}

Here is the overview of how to integrate with Virtual Account:

1. [Create Virtual Account](#id-1.-create-va)

   [a. DOKU Generate Payment Code](#a.-doku-generate-payment-code)

   [b. Merchant Generate Payment Code](#b.-merchant-generate-payment-code)

   [c. Display Virtual Account](#c.-display-virtual-account)

   [d. Acknowledge Payment Result](#d.-acknowledge-payment-result)

   [e. Hit DOKU Check Status API](#e.-hit-doku-check-status-api)

   [f. Delete Virtual Account](#f.-delete-payment-code)

   [g. Update Virtual Account](#g.-update-payment-code)

***

### 1. Create VA

To create VA, you will need to hit this API through your Backend:

#### API Endpoint

<table><thead><tr><th width="246">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>27</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va
</code></pre></td></tr></tbody></table>

Here is the sample request header, request body and response body for BSS VA&#x20;

#### a. DOKU Generate Payment Code

Check this flow diagram to get know about this method

<div align="center" data-full-width="true"><figure><img src="/files/QRd0nhEfCWjmZzOexSvn" alt=""><figcaption><p>DOKU Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th width="114">Type</th><th width="124">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID)</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day (request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host )</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtained from Get B2B Token API, refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/6vNP2Adz549ihvDpd6MU" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - BSS VA - DGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FMwLnQJVmAYfqrANnvDAy%2FSNAP%20v1.1%20-%20BSS%20VA%20-%20DGPC.json?alt=media\&token=7d7d3aab-6005-4b77-bb50-012486765d1d)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

#### b. Merchant Generate Payment Code

Check this flow diagram to get know about this method

<div data-full-width="true"><figure><img src="/files/WDqzMJbMrbkQivFtU5B9" alt=""><figcaption><p>Merchant Generate Payment Code</p></figcaption></figure></div>

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID)</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day (request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtained from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/L00OODnljG1agR4yJc20" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/create-va" method="post" %}
[SNAP v1.1 - BSS VA - MGPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FW7eNHAQDdJw9Bzl9QTIt%2FSNAP%20v1.1%20-%20BSS%20VA%20-%20MGPC.json?alt=media\&token=55138a17-e514-4198-843e-19a2fe025459)
{% endopenapi %}

[Learn what are the response codes!](/get-started-with-doku-api/response-code/http-status-and-case-code)

{% hint style="success" %}
**Pro Tips!**

1. You can also show payment instruction link to your customer by using `additionalInfo.howToPayPage`&#x20;
2. If you wish to customize the UI for the payment instruction, you can use the `additionalInfo.howToPayApi`
   {% endhint %}

#### c. Display Virtual Account

You can display the payment code to your customer by using `virtualAccountData.virtualAccountNo` that you retrieved from the API response.

#### d. Acknowledge payment result

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap).

{% openapi src="/files/librbLGlhoKCspmQaXHF" path="/v1.1/transfer-va/payment" method="post" %}
[SNAP v1.1 - BSS VA - NOTIFICATION.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FE61SSOEXO3Qu2adAGegS%2FSNAP%20v1.1%20-%20BSS%20VA%20-%20NOTIFICATION.json?alt=media\&token=2564634a-3e8e-4dd5-8b77-48eb63c6ad72)
{% endopenapi %}

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

#### f. Delete Payment Code

If you wish to delete your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID)</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day (request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtained from Get B2B Token API, refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/EYiap5HktdhHqooGMzGT" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/delete-va" method="delete" %}
[SNAP v1.1 - BSS VA - DELETE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F0abceWWXSxPm4FKMp7yY%2FSNAP%20v1.1%20-%20BSS%20VA%20-%20DELETE.json?alt=media\&token=9895d55a-14cd-43d8-8b6e-7143a8f70110)
{% endopenapi %}

#### g. Update Payment Code

If you wish to update your virtual account, you can do that by hitting the API with this API :&#x20;

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID)</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day (request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtained from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/9Wlr606TRYgfyXU7YibT" path="/virtual-accounts/bi-snap-va/v1.1/transfer-va/update-va" method="put" %}
[SNAP v1.1 - BSS VA - UPDATE.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F6AbgsqufbK2Gxwc2m7xI%2FSNAP%20v1.1%20-%20BSS%20VA%20-%20UPDATE.json?alt=media\&token=cea580c2-d20a-4c7c-8696-e991fa4f2d2b)
{% endopenapi %}

***

### 2. Direct Inquiry

<table><thead><tr><th width="235">Type</th><th>Value</th></tr></thead><tbody><tr><td>Service Code</td><td>24</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Endpoint Sandbox </td><td><p></p><pre class="language-json"><code class="lang-json">https://api-sandbox.doku.com/.../
</code></pre></td></tr><tr><td>API Endpoint Production</td><td><p></p><pre class="language-json"><code class="lang-json">https://api.doku.com/..../
</code></pre></td></tr><tr><td>Path</td><td><p></p><pre class="language-json"><code class="lang-json">/virtual-accounts/bi-snap-va/v1.1/transfer-va/inquiry
</code></pre></td></tr></tbody></table>

Here is the overview of how to integrate Direct Inquiry BSS VA :&#x20;

2. [Direct Inquiry](#id-2.-direct-inquiry)

   a.  [Setup Inquiry URL on DOKU Dashboard](#a.-setup-inquiry-url-on-doku-dashboard)

   b. [Generate Payment Code on your End](#b.-generate-payment-code-on-your-end)

   c. [Receive Inquiry Request from DOKU](#c.-receive-inquiry-request-from-doku)

   d. [Acknowledge Payment Notification](#d.-acknowledge-payment-notification)

   e. [Hit DOKU Check Status API](#e.-hit-doku-check-status-api-1)

Check this flow to diagram to get know about this API :&#x20;

<div data-full-width="true"><figure><img src="/files/UFMZMMHHiaPNc6xvKFk1" alt=""><figcaption><p>Direct Inquiry</p></figcaption></figure></div>

To get Inquiry Request from DOKU,  you will need to hit this API through your Backend:

#### a. Setup Inquiry URL on DOKU Dashboard

To receive the inquiry request from DOKU. You must set your `Inquiry URL` to DOKU. Please contact our team for the setup.&#x20;

{% hint style="info" %}
Please inform the `Inquiry URL` for Sandbox environment and Production environment.
{% endhint %}

#### b. Generate Payment Code on your end

Generate payment is done in your system. The payment code length maximum is `28` digits.

#### c. Receive Inquiry Request from DOKU

Here is the sample request header, request body from DOKU

#### Request Header

<table data-full-width="false"><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>X- TIMESTAMP</td><td>String</td><td>Mandatory</td><td>Client's current local time in yyyy-MM-ddTHH:mm:ssZ format</td></tr><tr><td>X-SIGNATURE</td><td>String</td><td>Mandatory</td><td>Algorithm symmetric signature HMAC_SHA2512(clientSecret, stringToSign) <br>Refer to this <a href="/pages/vPz38WQKghmP8GPBdnKu">Docs</a></td></tr><tr><td>X-PARTNER-ID</td><td>String</td><td>Mandatory</td><td>Unique ID for a partner (Merchant Client ID)</td></tr><tr><td>X-EXTERNAL-ID</td><td>String</td><td>Mandatory</td><td>Numeric string. Reference number that should be unique in the same day (request-id)</td></tr><tr><td>CHANNEL-ID</td><td>String</td><td>Mandatory</td><td>channel ID for VA. Please fill with H2H (Host-To-Host)</td></tr><tr><td>Authorization</td><td>String</td><td>Mandatory</td><td>Bearer "access token" obtained from Get B2B Token API , refer to this <a href="/pages/BX9GP2SrqTlk0CWm4Usb">Docs</a></td></tr></tbody></table>

{% openapi src="/files/8pVG9bu0A7T4dVkGJkno" path="/v1.1/transfer-va/inquiry" method="post" %}
[SNAP v1.1 - BSS VA - DIPC.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F9Bg4kwniBKucM2LW3KsJ%2FSNAP%20v1.1%20-%20BSS%20VA%20-%20DIPC.json?alt=media\&token=b3c16169-88fc-44c9-9730-40bdb35e6490)
{% endopenapi %}

#### d. Acknowledge payment notification

After the payment is being made by your customer, DOKU will send **HTTP Notification** to your defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification/http-notification-sample-for-snap).

{% openapi src="/files/librbLGlhoKCspmQaXHF" path="/v1.1/transfer-va/payment" method="post" %}
[SNAP v1.1 - BSS VA - NOTIFICATION.json](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FE61SSOEXO3Qu2adAGegS%2FSNAP%20v1.1%20-%20BSS%20VA%20-%20NOTIFICATION.json?alt=media\&token=2564634a-3e8e-4dd5-8b77-48eb63c6ad72)
{% endopenapi %}

#### e. Hit DOKU Check Status API

If you do not receive notifications from DOKU due to some issue, you can perform an API status check on the DOKU side to determine the updated transaction status. See the detailed request and response here [Check Status API](/get-started-with-doku-api/check-status-api/snap).

***

### Additional Feature

#### Open Amount&#x20;

DOKU supports open payment meaning that your customer can input their own payment amount. To use open amount, you need to set `virtualAccountTrxType` = O and you  need to send `totalAmount.value` = `0`and `totalAmount.currency` = `IDR` DOKU. Here is the sample:

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "   92400",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
      ...
    "virtualAccountTrxType": "O",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

```json
{
  ...
  "virtualAccountData": {
    "partnerServiceId": "   92400",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "virtualAccountTrxType": "O",
    "expiredDate": "2023-01-01T10:55:00+07:00",
    ...
    },
    ...
}
```

{% endtab %}
{% endtabs %}

#### Limit Amount

DOKU supports limit amount payment meaning that your customer can input their own payment amount at the range that you defined. Limit amount only available when `virtualAccountTrxType` type is `O` and `V.`To use limit amount, you need to set `virtualAccountConfig.minAmount` >= 0 or `virtualAccountConfig.maxAmount` > 0 to DOKU.

{% tabs %}
{% tab title="Create VA" %}

```json
{
    "partnerServiceId": "   92400",
        ...
    "totalAmount": {
        "value": "0",
        "currency": "IDR"
      },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BSS",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
}
```

{% endtab %}

{% tab title="Direct Inquiry" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  ...
  "virtualAccountData": {
    "partnerServiceId": "   92400",
    ...
    "totalAmount": {
      "value": "0",
      "currency": "IDR"
    },
    "additionalInfo": {
        "channel" : "VIRTUAL_ACCOUNT_BSS",
        "virtualAccountConfig" : {
            "minAmount" : "10000.00"
            "maxAmount" : "5000000.00"
            }
        },
    "virtualAccountTrxType": "O" / "V",
    ...
    },
}
</code></pre>

{% endtab %}
{% endtabs %}

***


# E-Wallet

A digital wallet, also known as an e-wallet or mobile wallet is one of the most used payment method nowadays. E-wallet helps the customer to do the transaction easily via e-wallet mobile application.

## E-Wallet Scheme

There are 2 schemes in e-wallet method:

**a. Tokenization & Recurring Type**

Tokenization replaces customer's sensitive payment information, such as card number or account number, to be in a form of token. Tokenization type needs a token everytime payment is requested and processed, hence customer needs to input OTP and/or PIN to verify every payment.

Whereas, Recurring  allows customer to authorize merchant to charged them repeatedly on a prearranged schedule. Customer needs to input OTP and/or PIN only for the initial authorization. The scheduled payment will be processed by merchant directly to acquirer without the need of customer to input OTP and/or PIN.

Currently, e-wallet payment channel in DOKU that support Tokenization and Recurring scheme is OVO.

**b. One Time Payment Type**

One Time Payment allows a customer makes a single, non-recurring purchase of a product or service without account binding or card registration process. Customer needs to input OTP and/or PIN to verify the payment

Currently, e-wallet payment channels in DOKU that support One Time Payment scheme is DANA and ShopeePay.

## Payment Channel Supported

We have partnered with various e-wallet payment channels.

| Channel                                                                            |
| ---------------------------------------------------------------------------------- |
| [DANA](/accept-payments/direct-api/snap/integration-guide/e-wallet/dana)           |
| [OVO](/accept-payments/direct-api/snap/integration-guide/e-wallet/ovo)             |
| [ShopeePay](/accept-payments/direct-api/snap/integration-guide/e-wallet/shopeepay) |

## Request new E-Wallet Channel?&#x20;

Do you have any e-wallet channels in mind that might suits your project? Send your request [here](mailto:jokul@doku.com?subject=%5BRequest%5D%20Add%20New%20Plugin%3A%20Others)!


# DANA

DANA offers one time payment type that allow customer to make a payment without account binding/card registration process.

## Integration Steps

Overview of integration process with DANA.

1. [Payment](#1.-payment)
2. [Payment Notification](#id-2.-payment-notification)
3. [Additional Feature](#id-3.-additional-feature)

***

### 1. Payment&#x20;

Payment process using DANA doesn't require account binding. After customer creates an order and chooses DANA as payment method on merchant's platform, merchant will hit this payment API to get redirect URLs to DANA's platform for customer to complete the payment.

**API Endpoint**

<table><thead><tr><th width="176">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/payment-host-to-host</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

## POST /direct-debit/core/v1/debit/payment-host-to-host

> Payment

```json
{"openapi":"3.0.3","info":{"title":"Swagger E-Wallet SNAP DANA","version":"1.0.11"},"servers":[{"url":"https://{api-domain}"}],"paths":{"/direct-debit/core/v1/debit/payment-host-to-host":{"post":{"summary":"Payment","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"X-DEVICE-ID","schema":{"type":"string"},"description":"Device identification on which the API services are currently being accessed by the end user (customer). Can’t contain symbols"},{"in":"header","name":"X-IP-ADDRESS","schema":{"type":"string"},"description":"conditional. IP address of the end user (customer) using IPv4 format"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}}}}}},"components":{"schemas":{"PaymentRequest":{"type":"object","required":["partnerReferenceNo","amount","urlParam"],"properties":{"partnerReferenceNo":{"type":"string","description":"invoice number from partner | max: 64 | Mandatory "},"validUpTo":{"type":"string","description":"Expired time payment url | format: 2024-07-10T11:57:58+07:00 "},"pointOfInitiation":{"type":"string","description":"Point of initiation from partner | value: app/pc/mweb | max: 20"},"urlParam":{"type":"object","required":["url","type","isDeepLink"],"properties":{"url":{"type":"string","description":"URL partner for redirect back from DANA | format: www.merchant.co.id | max: 255 | Mandatory"},"type":{"type":"string","description":"Pay Return | Value should be always PAY_RETURN | Mandatory"},"isDeepLink":{"type":"string","description":"Is Merchant use deep link or not | value: Y/N | Mandatory"}}},"amount":{"$ref":"#/components/schemas/AmountObject"},"additionalInfo":{"type":"object","required":["channel"],"properties":{"channel":{"type":"string","description":"Value should be always EMONEY_DANA_SNAP | Mandatory"},"orderTitle":{"type":"string","description":"Order title from merchant"},"supportDeepLinkCheckoutUrl":{"type":"string","description":"Value 'true' for Jumpapp behaviour, 'false' for webview, false by default"}}}}},"AmountObject":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | Mandatory | min length: 1 | max length: 16.2"},"currency":{"type":"string","description":"Currency. | Mandatory | min length: 1 | max length: 3"}}},"PaymentResponse":{"type":"object","required":["responseCode","responseMessage","webRedirectUrl"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/response-code/http-status-and-case-code#id-3.-e-wallet . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Message"},"webRedirectUrl":{"type":"string","description":"Redirect URL to Merchant's page/platform for customer to input OTP/PIN"},"partnerReferenceNo":{"type":"string","description":"Invoice Number from Partner"}}}}}}
```

### 2. Payment Notification

After payment is completed, DOKU will send **HTTP Notification** to merchant's defined `Notification URL.`Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification).

### 3. Additional Feature

### **Online Refund**

This endpoint is used to create refund request for previous successful payment. Merchant can request a transaction refund to DOKU.

**API Endpoint**

<table><thead><tr><th width="181">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/refund</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Parameter without (\*) is optional/conditional

## POST /direct-debit/core/v1/debit/refund

> Refund Payment

```json
{"openapi":"3.0.3","info":{"title":"Direct Debit Core System - Refund (EMONEY_DANA_SNAP)","version":"1.0.0"},"servers":[{"url":"https://api.doku.com","description":"Base URL"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"B2B access token obtained from the Get B2B Token API (`/authorization/v1/access-token/b2b`)"}},"schemas":{"RefundRequest":{"type":"object","description":"Request body for initiating a refund on the EMONEY_DANA_SNAP channel","required":["originalPartnerReferenceNo","partnerRefundNo","refundAmount","additionalInfo"],"properties":{"originalPartnerReferenceNo":{"type":"string","description":"Invoice number of the original payment transaction to be refunded.\nThis is the `partnerReferenceNo` (invoice) from the original payment request.\n","maxLength":64},"originalExternalId":{"type":"string","description":"The `X-EXTERNAL-ID` header value from the original payment request.\nUsed to precisely locate the original transaction.\n","maxLength":36},"partnerRefundNo":{"type":"string","description":"Merchant's unique reference number for this refund.\nMust be unique per `originalPartnerReferenceNo`. Used for idempotency and reconciliation.\n","maxLength":64},"reason":{"type":"string","description":"Human-readable reason for the refund","maxLength":256},"refundAmount":{"$ref":"#/components/schemas/AmountDto"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfoDto"}}},"AmountDto":{"type":"object","description":"Transaction amount","required":["value","currency"],"properties":{"value":{"type":"string","description":"Amount in two-decimal format.\n- For a **full refund**, this must equal the original payment amount.\n- For a **partial refund**, this must be less than the original payment amount.\n  The cumulative total of all partial refunds must not exceed the original amount.\n","maxLength":19},"currency":{"type":"string","description":"ISO 4217 currency code. Must match the currency of the original payment.","maxLength":3}}},"AdditionalInfoDto":{"type":"object","required":["channel"],"properties":{"channel":{"type":"string","description":"value should be always EMONEY_DANA_SNAP"}}},"RefundResponse":{"type":"object","description":"Response body for a successful refund request","required":["responseCode","responseMessage","originalPartnerReferenceNo","originalReferenceNo","refundNo","partnerRefundNo","refundAmount","refundTime"],"properties":{"responseCode":{"type":"string","description":"Response code: HTTP Status (3) + Service Code `58` (2) + Case Code (2).\nExample: `2005800` = HTTP 200 + service `58` + case `00` (Successful).\n"},"responseMessage":{"type":"string","description":"Human-readable response message"},"originalPartnerReferenceNo":{"type":"string","description":"Invoice number of the original payment transaction, echoed from the original transaction"},"originalReferenceNo":{"type":"string","description":"DANA acquirer reference number from the original payment transaction.\nCan be used for reconciliation with DANA.\n"},"refundNo":{"type":"string","description":"Refund reference number assigned by the DANA acquirer.\nUse this for reconciliation and dispute resolution with DANA.\n"},"partnerRefundNo":{"type":"string","description":"Merchant's refund reference number, echoed from the request"},"refundAmount":{"$ref":"#/components/schemas/AmountDto"},"refundTime":{"type":"string","description":"Timestamp when the refund was completed, in ISO 8601 format (yyyy-MM-ddTHH:mm:ss+07:00)"}}},"ErrorResponse":{"type":"object","description":"Standard error response body.\nResponse code format: HTTP Status (3) + Service Code `58` (2) + Case Code (2).\n\n| Case Code | Meaning                                       |\n|-----------|-----------------------------------------------|\n| `00`      | General Error / Duplicate External ID         |\n| `01`      | Transaction Not Found / Missing Mandatory Field |\n| `15`      | Transaction Not Permitted / Duplicate Refund No |\n","properties":{"responseCode":{"type":"string","description":"Error response code"},"responseMessage":{"type":"string","description":"Error message"}}}}},"paths":{"/direct-debit/core/v1/debit/refund":{"post":{"summary":"Refund Payment","operationId":"refundEmoneyDanaSnap","tags":["Refund"],"parameters":[{"name":"X-PARTNER-ID","in":"header","required":true,"description":"Merchant's client ID registered with DOKU","schema":{"type":"string","maxLength":36}},{"name":"X-EXTERNAL-ID","in":"header","required":true,"description":"Unique reference ID for this refund request (per-day uniqueness required).\nUsed for idempotency and tracing. Numeric string.\n","schema":{"type":"string","maxLength":32}},{"name":"Authorization","in":"header","required":true,"description":"B2B access token obtained from the Get B2B Token API","schema":{"type":"string"}},{"name":"X-TIMESTAMP","in":"header","required":true,"description":"Request timestamp in ISO 8601 format (yyyy-MM-ddTHH:mm:ss+07:00)","schema":{"type":"string"}},{"name":"X-SIGNATURE","in":"header","required":true,"description":"HMAC-SHA512 symmetric signature for request integrity verification","schema":{"type":"string"}},{"name":"Authorization-Customer","in":"header","required":false,"description":"Customer B2B2C token (`dokuB2b2cToken`) obtained during the DANA binding process.\nRequired if the original payment was made using a bound DANA token.\n","schema":{"type":"string"}},{"name":"X-IP-ADDRESS","in":"header","required":false,"description":"IP address of the end customer's device","schema":{"type":"string"}},{"name":"X-DEVICE-ID","in":"header","required":false,"description":"Device ID of the end customer's device","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}}}},"responses":{"200":{"description":"Refund successfully processed by DANA.\nThe `refundNo` field contains the acquirer's refund reference number for reconciliation.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundResponse"}}}},"400":{"description":"Bad request — missing or invalid fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failure — invalid or expired B2B token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — refund amount exceeds the remaining refundable balance of the original transaction.\nThe cumulative refunded amount (including previous partial refunds) must not exceed\nthe original transaction amount.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — the original transaction referenced by `originalPartnerReferenceNo` was not found or is not in a refundable state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — duplicate `X-EXTERNAL-ID` within the same day, or `partnerRefundNo` already used for this invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error or DANA acquirer malfunction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


# i.saku

i.saku offers a one time payment type that allows customers to make a payment without account binding.

## Integration Steps

Overview of integration process with i.saku.

1. [Payment](#1.-payment)
2. [Payment Notification](#id-2.-payment-notification)
3. [Additional Feature](#id-3.-additional-feature)

***

### 1. Payment&#x20;

Payment process using i.saku doesn't require account binding. After the customer creates an order and chooses i.saku as the payment method on the merchant's platform, the merchant will hit this payment API to get a redirect URL to DOKU/i.saku payment flow for the customer to complete the payment.

**API Endpoint**

<table><thead><tr><th width="176">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v2.0/debit/payment-host-to-host</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

## POST /direct-debit/core/v2.0/debit/payment-host-to-host

> Payment

```json
{"openapi":"3.0.3","info":{"title":"Swagger E-Wallet SNAP ISAKU","version":"1.0.11"},"servers":[{"url":"https://{api-domain}"}],"paths":{"/direct-debit/core/v2.0/debit/payment-host-to-host":{"post":{"summary":"Payment","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"X-DEVICE-ID","schema":{"type":"string"},"required":true,"description":"Device identification on which the API services are currently being accessed by the end user (customer). Can’t contain symbols"},{"in":"header","name":"X-IP-ADDRESS","schema":{"type":"string"},"description":"conditional. IP address of the end user (customer) using IPv4 format"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}}}}}},"components":{"schemas":{"PaymentRequest":{"type":"object","required":["partnerReferenceNo","amount","urlParams"],"properties":{"partnerReferenceNo":{"type":"string","description":"invoice number from partner | max: 64 | Mandatory "},"validUpto":{"type":"string","description":"Expired time payment url | format: 2024-07-10T11:57:58+07:00 "},"pointOfInitiation":{"type":"string","description":"Point of initiation from partner | value: app/pc/mweb | max: 20"},"urlParams":{"type":"array","items":{"type":"object","required":["url","type","isDeepLink"],"properties":{"url":{"type":"string","description":"URL partner for redirect back from ISAKU | format: www.merchant.co.id | max: 255 | Mandatory"},"type":{"type":"string","description":"Pay Return | Value should be always PAY_RETURN | Mandatory"},"isDeepLink":{"type":"string","description":"Is Merchant use deep link or not | value: Y/N | Mandatory"}}}},"amount":{"$ref":"#/components/schemas/AmountObject"},"additionalInfo":{"type":"object","required":["channel"],"properties":{"channel":{"type":"string","description":"Value should be always EMONEY_ISAKU_SNAP | Mandatory"},"isDeepLink":{"type":"string","description":"Value 'true' for Jumpapp behaviour, 'false' for webview, false by default"},"phoneNo":{"type":"string","description":"Customer Phone Number | Value should be always PAY_RETURN | Mandatory"}}}}},"AmountObject":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | Mandatory | min value: 1 | max value: 9,999,999.00"},"currency":{"type":"string","description":"Currency. | Mandatory | min length: 1 | max length: 3"}}},"PaymentResponse":{"type":"object","required":["responseCode","responseMessage","webRedirectUrl"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/response-code/http-status-and-case-code#id-3.-e-wallet . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Message"},"webRedirectUrl":{"type":"string","description":"Redirect URL to Merchant's page/platform for customer to input OTP/PIN"},"partnerReferenceNo":{"type":"string","description":"Invoice Number from Partner"}}}}}}
```

### 2. Payment Notification

After payment is completed, DOKU will send **HTTP Notification** to merchant's defined `Notification URL.`Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification).

### 3. Additional Feature

### **Online Refund**

This endpoint is used to create a refund request for a previous successful i.saku payment. The merchant can request a transaction refund through DOKU.

<figure><img src="/files/AR1qQEyZY4tEYDpq46ps" alt="" width="563"><figcaption></figcaption></figure>

**API Endpoint**

<table><thead><tr><th width="181">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/refund</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

## POST /direct-debit/core/v1/debit/refund

> Refund

```json
{"openapi":"3.0.3","info":{"title":"Swagger E-Wallet SNAP ISAKU","version":"1.0.11"},"servers":[{"url":"https://{api-domain}"}],"paths":{"/direct-debit/core/v1/debit/refund":{"post":{"summary":"Refund","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"X-DEVICE-ID","schema":{"type":"string"},"required":true,"description":"Device identification on which the API services are currently being accessed by the end user (customer). Can’t contain symbols"},{"in":"header","name":"X-IP-ADDRESS","schema":{"type":"string"},"description":"conditional. IP address of the end user (customer) using IPv4 format"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundResponse"}}}}}}}},"components":{"schemas":{"RefundRequest":{"type":"object","required":["originalPartnerReferenceNo","amount","partnerRefundNo","additionalInfo"],"properties":{"additionalInfo":{"type":"object","required":["channel"],"properties":{"channel":{"type":"string","description":"Value should be always EMONEY_ISAKU_SNAP | Mandatory"}}},"originalPartnerReferenceNo":{"type":"string","description":"Partner Reference No from Purchase Transaction | max: 64 | Mandatory"},"originalExternalId":{"type":"string","description":"External ID from Purchase Transaction | max: 64 |"},"refundAmount":{"$ref":"#/components/schemas/AmountObject"},"reason":{"type":"string","description":"Reason for Refund | max: 255"},"partnerRefundNo":{"type":"string","description":"Partner Refund No from Partner | max: 64 | Mandatory"}}},"AmountObject":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 | Mandatory | min value: 1 | max value: 9,999,999.00"},"currency":{"type":"string","description":"Currency. | Mandatory | min length: 1 | max length: 3"}}},"RefundResponse":{"type":"object","required":["responseCode","responseMessage","refundAmount","refundTime"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/response-code/http-status-and-case-code#id-3.-e-wallet . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string"},"refundAmount":{"$ref":"#/components/schemas/AmountObject"},"refundTime":{"type":"string","description":"format: yyyy-MM-dd'T'HH:mm:ssXXX"}}}}}}
```


# OVO

OVO offers 2 payment types, which are One-Time Payment and Recurring Payment. For both payment types, tokenization must be completed first before transactions can be executed.

## Integration Steps

Overview of integration process with OVO.

1. [Account Binding](#id-1.-account-binding)
2. [Balance Inquiry](#id-2.-balance-inquiry)
3. [Payment](#id-3.-payment)&#x20;
4. [Payment Notification](#id-4.-payment-notification)
5. [Additional Feature](#id-5.-additional-feature)

***

### 1. Account Binding

Account Binding process should be done before payment can be made and processed. Merchant will send account binding request from customer to DOKU. The request includes customer's phone number that is registered to customer's OVO account.&#x20;

Each OVO account can only be bind to one customer on one merchant. Customer needs to do verification for account binding process by inputting OTP and PIN.

**Account Binding Flow**

<figure><img src="/files/3G7vi0RrZgJFPSKTo8ST" alt=""><figcaption><p>Account Binding Flow - OVO</p></figcaption></figure>

**API Endpoint**

<table><thead><tr><th width="176">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/registration-account-binding</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/gi5wxJwmLO3SoUDfns3i" path="/direct-debit/core/v1/registration-account-binding" method="post" %}
[openapi (3).yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FLGMZEespXiNIOoWmnsL7%2Fopenapi%20\(3\).yaml?alt=media\&token=a25b6424-d6b3-49d5-98ad-a0697ca30a92)
{% endopenapi %}

### 2. Balance Inquiry

After customer has bind/linked their OVO account, customer can check their account balance infirmation using Balance Inquiry. Merchant will send balance inquiry request from customer to DOKU.&#x20;

Merchant can also use balance inquiry API to check if customer has sufficient balance before invoking payment process.

**Balance Inquiry Flow**

<figure><img src="/files/NMSxj1kwb5vWyni1vAoV" alt=""><figcaption><p>Balance Inquiry Flow - OVO </p></figcaption></figure>

**API Endpoint**

<table><thead><tr><th width="176">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/balance-inquiry</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/YcoCW7eBxNhUlYbJLyUT" path="/direct-debit/core/v1/balance-inquiry" method="post" %}
[openapi (3).yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FUycHyLC1SJUAwhBGQiDp%2Fopenapi%20\(3\).yaml?alt=media\&token=12610cd8-afd0-4726-aa8f-95e6b86838ea)
{% endopenapi %}

### 3. Payment&#x20;

After customer's account is bind/linked and customer has enough balance for payment, merchant can send payment request from customer to DOKU.&#x20;

#### One Time Payment

For One-Time Payments, each transaction must be verified by the customer by entering an OTP and PIN. To enable this flow, merchants are required to include the parameter `paymentType: "SALE"` in the payment request body.

In response, the merchant will receive a `webRedirectUrl`, which should be used to redirect the customer to complete the payment by entering their OTP and PIN. Once the payment process is completed, the merchant will receive a payment notification confirming the transaction status.

#### Recurring Payment

For OVO Recurring, payments are processed on a scheduled basis. Therefore, OTP and PIN verification is not required for every transaction. Customers only need to complete the verification once during the account binding process, which grants the merchant authorization to execute subsequent scheduled payments.

To initiate this flow, merchants are required to include the parameter `paymentType: "RECURRING"` in the payment request body. In this scheme, the merchant will not receive a `webRedirectUrl`, as no customer redirection is needed. The payment request will be processed directly by the acquirer, and the merchant will receive a notification with the transaction result.

**Payment Flow**

<figure><img src="/files/bTqkDdXGjL332Qmk1eFI" alt=""><figcaption><p>One Time Payment Flow - OVO</p></figcaption></figure>

<figure><img src="/files/SWEjIR5DnkFbUEZJ73xc" alt=""><figcaption><p>Recurring Payment Flow - OVO</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="176">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/payment-host-to-host</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/xokt9LkLjY6JyVtw8gzJ" path="/direct-debit/core/v1/debit/payment-host-to-host" method="post" %}
[openapi (3).yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F0DOQzeTFV1yXf13XpUGj%2Fopenapi%20\(3\).yaml?alt=media\&token=d3f5f369-7eb3-4836-81e8-b6fd718f2add)
{% endopenapi %}

### 4. Payment Notification

After payment is completed, DOKU will send **HTTP Notification** to merchant's defined `Notification URL.`Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification).

### 5. Additional Feature

### Online Refund

This endpoint is used to create refund request for previous successful payment. Merchant can request a transaction refund to DOKU.

**Online Refund Flow**

<figure><img src="/files/9uLyS7KXEgymVT5g2AfX" alt=""><figcaption><p>Online Refund Flow - OVO</p></figcaption></figure>

#### API Endpoint&#x20;

<table><thead><tr><th width="215">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/refund</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/Y1JD5KsQFdzCDPdm0bm0" path="/direct-debit/core/v1/debit/refund" method="post" %}
[openapi (3).yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F2Sj5SX3XxvI4geY3rNBs%2Fopenapi%20\(3\).yaml?alt=media\&token=d37f878e-f005-4f40-8c8d-d47756bef225)
{% endopenapi %}

### Account Unbinding

If a registered customer no longer wants their account/card to be bind/linked and wish to remove themself from DOKU's and merchant’s system, merchant can send account unbinding request that is initiated by customer.

**Account Unbinding Flow**

<figure><img src="/files/FfET4l9sIK0ppZM13D9t" alt=""><figcaption><p>Account Unbinding Flow - OVO</p></figcaption></figure>

#### API Endpoint&#x20;

<table><thead><tr><th width="199">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/registration-account-unbinding</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/E5GBtUgclGthxrBAR6cq" path="/direct-debit/core/v1/registration-account-unbinding" method="post" %}
[openapi (3).yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2Fs4FdoS120xyJeQvlaqhR%2Fopenapi%20\(3\).yaml?alt=media\&token=17987dfc-41b3-46f8-84a7-5b9a3200c0cf)
{% endopenapi %}


# ShopeePay

## Integration Steps

Overview of integration process with ShopeePay.

1. [Payment](#1.-payment)
2. [Payment Notification](#id-2.-payment-notification)
3. [Additional Feature](#id-3.-additional-feature)

***

### 1. Payment&#x20;

Payment process using ShopeePay doesn't require account binding. After customer creates an order and chooses ShopeePay as payment method on merchant's platform, merchant will hit this payment API to get redirect URLs to ShopeePay's platform for customer to complete the payment.

Source of Fund Options for ShopeePay Payment.

There are a few source of fund options that can be used for ShopeePay payments:

* ShopeePay Wallet Balance – This is the default source of fund for all ShopeePay payments.
* ShopeePayLater – This option requires prior approval from ShopeePay. DOKU can help facilitate the application process through our Sales and Business team when the channel is activated.
  * Note: To enable ShopeePayLater as an additional source of fund (alongside ShopeePay Wallet Balance), merchants are required to implement the API Refund feature.

**API Endpoint**

<table><thead><tr><th width="176">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/payment-host-to-host</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/xyUnrXWZRaMrmRd5e6gz" path="/direct-debit/core/v1/debit/payment-host-to-host" method="post" %}
[swagger-dd-shopee (4).yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2Fo96nTx32wNxTNpIQgFof%2Fswagger-dd-shopee%20\(4\).yaml?alt=media\&token=26b264d8-d210-481d-8b7e-1b4fe0640d3a)
{% endopenapi %}

***

### 2. Payment Notification

After payment is completed, DOKU will send **HTTP Notification** to merchant's defined `Notification URL.` Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification).

***

### 3. Additional Feature

### **Online Refund**

This endpoint is used to create refund request for previous successful payment. Merchant can request a transaction refund to DOKU.

**Refund Eligibility**

* To enable ShopeePayLater as an additional source of fund (alongside ShopeePay Wallet Balance), merchants are required to implement the API Refund feature.
* Refund can only be performed for transactions with successful payment status. Refund may be full or partial, provided that the total refunded amount does not exceed the original transaction amount. Refund requests must be submitted via API.
* The refund expiration period is set at 365 days, starting from the initial payment date.&#x20;
* For transactions paid using ShopeePay Wallet Balance, the refund amount must not cause the user’s wallet balance to exceed the maximum wallet balance limit (up to IDR 2,000,000 for non-verified users and up to IDR 20,000,000 for verified users). If the user’s wallet balance has reached its maximum limit at the time of refund, the refund request will still be accepted via API but will remain in pending/processing status on ShopeePay’s side. The refund will be automatically processed once the user’s wallet balance becomes available. In this scenario, merchants do not need to resubmit the refund request.
* For transactions paid using ShopeePayLater, refund is expected to be processed in real time under normal conditions. In some edge cases where real-time processing is not successful due to system issues, merchants may contact DOKU support for further assistance and investigation.

**API Endpoint**

<table><thead><tr><th width="181">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/refund</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/6ihUnXg4J36w4vERWzWr" path="/direct-debit/core/v1/debit/refund" method="post" %}
[Swagger ShopeePay SNAP - Updated 110325 (1).yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2Ftjfh18lDa3vBAtA95A5i%2FSwagger%20ShopeePay%20SNAP%20-%20Updated%20110325%20\(1\).yaml?alt=media\&token=3827809f-c44a-4174-ba38-61f617545bdb)
{% endopenapi %}


# Direct Debit

Direct debit is an electronic payment method by connecting customer's debit card or account number as a source of fund with one registration process so the payment can take place quickly and easily.

## Direct Debit Scheme

Direct Debit payment method requires account binding or card registration before payment process can be requested and completed.&#x20;

There are 2 schemes in direct debit method:

**a. Tokenization Scheme**

Tokenization replaces customer's sensitive payment information, such as card number or account number, to be in a form of token. Tokenization needs a token everytime payment is requested and processed, hence customer needs to input OTP and/or PIN to verify every payment.

Currently, direct debit payment channels in DOKU that support Tokenization scheme are Allo Bank, BRI, and CIMB Direct Debit.

**b. Recurring Scheme**

Recurring allows customer to authorize merchant to charged them repeatedly on a prearranged schedule. Customer needs to input OTP and/or PIN only for the initial authorization. The scheduled payment will be processed by merchant directly to acquirer without the need of customer to input OTP and/or PIN.

Currently, direct debit payment channel in DOKU that support Recurring scheme is BRI Direct Debit.

## Payment Channels Supported

We have partnered with various direct debit payment channels.

| Channels                                                                                                         |
| ---------------------------------------------------------------------------------------------------------------- |
| [Allo Bank Direct Debit](/accept-payments/direct-api/snap/integration-guide/direct-debit/allo-bank-direct-debit) |
| [BRI Direct Debit](/accept-payments/direct-api/snap/integration-guide/direct-debit/bri-direct-debit)             |
| [CIMB Direct Debit](/accept-payments/direct-api/snap/integration-guide/direct-debit/cimb-direct-debit)           |

## Request New Direct Debit Channel?

Do you have any direct debit channels in mind that might suits your project? Send your request [here](mailto:jokul@doku.com?subject=%5BRequest%5D%20Add%20New%20Plugin%3A%20Others)!


# Allo Bank Direct Debit

Allo Bank direct debit offers tokenization scheme that requires customer to input OTP and/or PIN to verify every payment.

## Integration Steps

Overview of integration process with Allo Bank Direct Debit

1. [Account Binding](#account-binding)
2. [Balance Inquiry](#check-balance-inquiry)
3. [Payment](#payment)
4. [Payment Notification](#payment-notification)
5. [Additional Feature](#additional-feature)

***

### 1. Account Binding

Account Binding process should be done before payment can be made and processed. Merchant will send account binding request from customer to DOKU. The request includes customer's phone number that is registered to customer's Allo Bank account.&#x20;

Each Allo Bank account can only be bind to one customer on one merchant. Customer needs to do verification for account binding process by inputting OTP and PIN.

**Account Binding Flow**

<figure><img src="/files/4CwxfA94hbRJSYK3oQi3" alt=""><figcaption><p>Account Binding Flow - Allo Bank Direct Debit</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="170">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/registration-account-binding</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/rwEg6uB9Zl5QwoF88Ywu" path="/direct-debit/core/v1/registration-account-binding" method="post" %}
[swagger-dd-allo.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FZXLraFme3WEsG3RoU2jt%2Fswagger-dd-allo.yaml?alt=media\&token=7ffbc464-7f02-4f46-b2ff-18f4a24e2688)
{% endopenapi %}

### 2. Balance Inquiry

After customer has bind/linked their Allo Bank account, customer can check their account balance infirmation using Balance Inquiry. Merchant will send balance inquiry request from customer to DOKU. The request includes customer's token.&#x20;

Merchant can also use balance inquiry API to check if customer has sufficient balance before invoking payment process.

**Balance Inquiry Flow**

<figure><img src="/files/2dHryQHw0WwKeszjanaQ" alt=""><figcaption><p>Balance Inquiry Flow - Allo Bank Direct Debit</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="196">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/balance-inquiry</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/1eakfdJDYm2bO8m0ityQ" path="/direct-debit/core/v1/balance-inquiry" method="post" %}
[swagger-dd-allo.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FSw5xFIBVq4vPkfLDCe2d%2Fswagger-dd-allo.yaml?alt=media\&token=52ad6574-4717-4ce3-833a-d7af24a7d3c6)
{% endopenapi %}

### 3. Payment&#x20;

After customer's account is bind/linked and customer has enough balance for payment, merchant can send payment request from customer to DOKU by bringing customer's token.&#x20;

**Payment Flow**

<figure><img src="/files/X4nHOx5EeHTh5aF36dDM" alt=""><figcaption><p>Payment Flow - Allo Bank Direct Debit</p></figcaption></figure>

#### API Endpoint&#x20;

<table><thead><tr><th width="203">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/payment-host-to-host</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/splZI3LQUFCrIl1DGrqe" path="/direct-debit/core/v1/debit/payment-host-to-host" method="post" %}
[swagger-dd-allo.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FkMED0JssoESt4SguGuiD%2Fswagger-dd-allo.yaml?alt=media\&token=d82ceac4-19af-4d52-8d1e-e67eb3d690ce)
{% endopenapi %}

### 4. Payment Notification

After payment is completed, DOKU will send **HTTP Notification** to merchant's defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification).

### 5. Additional Feature

### Online Refund

This endpoint is used to create refund request for previous successful payment. Merchant can request a transaction refund to DOKU. Full refund and partial refund are available to be requested

**Online Refund Flow**

<figure><img src="/files/9uLyS7KXEgymVT5g2AfX" alt=""><figcaption><p>Online Refund Flow - Allo Bank Direct Debit</p></figcaption></figure>

#### API Endpoint&#x20;

<table><thead><tr><th width="215">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/refund</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/rbGiMBn1DE6zRKEnCsnu" path="/direct-debit/core/v1/debit/refund" method="post" %}
[swagger-dd-allo.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FVCYOKw46b3xQWjJlXHZ9%2Fswagger-dd-allo.yaml?alt=media\&token=a1acaa1a-720b-44cc-bd59-28c79392f3cd)
{% endopenapi %}

### Account Unbinding

If a registered customer no longer wants their account/card to be bind/linked and wish to remove themself from DOKU's and merchant’s system, merchant can send account unbinding request that is initiated by customer.

#### API Endpoint&#x20;

<table><thead><tr><th width="199">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/v1/registration-account-unbinding</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/rwEg6uB9Zl5QwoF88Ywu" path="/direct-debit/core/v1/registration-account-unbinding" method="post" %}
[swagger-dd-allo.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FZXLraFme3WEsG3RoU2jt%2Fswagger-dd-allo.yaml?alt=media\&token=7ffbc464-7f02-4f46-b2ff-18f4a24e2688)
{% endopenapi %}


# BRI Direct Debit

BRI offers 2 payment schemes, which are; 1) Tokenization scheme, and 2) Recurring scheme.

## Integration Steps

Overview of integration process with BRI Direct Debit

1. [Card Registration](#account-binding)
2. [OTP Verification](#otp-verification)
3. [Payment](#payment)
4. [Payment Notification](#payment-notification)
5. [Additional Feature](#additional-feature)

***

### 1. Card Registration

Card Registration process should be done before payment can be made and processed. Merchant will send card registration request from customer to DOKU. The request includes customer's card number that is registered to customer's BRI account.&#x20;

Each card/account can only registered/bind to one customer on one merchant. Customer needs to verify OTP and input PIN on BRI page.

**CBC Encryption**

To request card registration process, merchant requires to bring object cardData which value should be encrypted using CBC Algorithm.

CBC Encryption - Steps:

1. **Prepare shared key from DOKU as Secret Key**

   * Substring shared key only 16 digits
   * Example code:

   ```json
   private String getSharedKey(String sharedKey) {
       if (sharedKey.length() != 16) {
   sharedKey = sharedKey.length() > 16 ? sharedKey.substring(0, 16) : String.format("%-16s", sharedKey).replace(' ', '-');
       }
       return sharedKey;
   }
   ```
2. **Generate Initial Value (IV)**

   * Generate initial value with 16 bytes and then encode using Base 64
   * Example code:

   ```json
   byte[] iv = new byte[16];
   new SecureRandom().nextBytes(iv);
   IvParameterSpec ivParameterSpec = new IvParameterSpec(iv);
   String ivString = Base64.getEncoder().encodeToString(ivParameterSpec.getIV());
   ```
3. **Using Cipher CBC**

   * Value that will be encrypted combine with secret key generated before
   * After that encode the value using Base 64
   * Example code:

   ```json
   Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding"); //NOSONAR
   cipher.init(Cipher.ENCRYPT_MODE, key, ivParameterSpec);
   byte[] cipherText = cipher.doFinal(input.getBytes());
   String cipherString = Base64.getEncoder().encodeToString(cipherText);
   ```
4. **Combine CBC and IV**

   * Combine value CBC Cipher with IV value with separator (|)
   * Example code:

   <pre class="language-json"><code class="lang-json"><strong>String value = cipherString + "|" + ivString;
   </strong></code></pre>

Tools Using Java - Steps:

* Install JDK 17
* Go to folder
* Run with command java -jar cbc-tools.jar
* Input Value that you wish to be encrypted
* Input Key to encrypt&#x20;

Example Value:

```
{"bankCardNo":"6783","bankCardType":"D","identificationNo":"6013010111348228","identificationType":"02","email":"email@email.com","expiryDate":"0526"}
```

{% file src="/files/hIIYe2U7QDX432zkl8xy" %}
CBC Encryption Tools
{% endfile %}

**Card Registration Flow**

<figure><img src="/files/SO3BLIq4ATdTkYPRN7WQ" alt=""><figcaption><p>Card Registration Flow - BRI Direct Debit</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="184">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/registration-card-bind</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/MSY3vxegqub2HFQlFLUk" path="/direct-debit/core/v1/registration-card-bind" method="post" %}
[swagger-dd-bri.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F1XAFuFMBkwdtqHQ5iIO9%2Fswagger-dd-bri.yaml?alt=media\&token=cd5eb7eb-201a-4383-8e4c-473acbd225d2)
{% endopenapi %}

***

### 2. OTP Verification

Once customer has registered their card through the platform, merchant needs to verify the card. Merchant can hit this API to verify the OTP.&#x20;

**OTP Verification Flow**

<figure><img src="/files/dWgHn2hE8mpe9sduoJx4" alt=""><figcaption><p>OTP Verification Flow - BRI Direct Debit</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="182">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/otp-verification</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Parameter without (\*) is optional/conditional

{% openapi src="/files/7pdcS4s1CMMwZBQSBC5z" path="/direct-debit/core/v1/otp-verification" method="post" %}
[swagger-dd-bri.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FpLKl8wAHyiFtjVX7Cqxy%2Fswagger-dd-bri.yaml?alt=media\&token=bd8ac1d7-0477-41f0-b877-ce92f51a9766)
{% endopenapi %}

***

### 3. Payment&#x20;

After customer's card is registered, payment process can be requested by bringing the card token generated in card registration process. After merchant hit payment API, DOKU will deduct customer's balance.&#x20;

#### Payment - Tokenization

In tokenization scheme, every payment needs to be verified by customer with inputting OTP and/or PIN. In order to do that, merchant needs to bring parameter `paymentType : "SALE"`in payment request body.

And as the response, merchant will receive parameter `webRedirectUrl` to redirect the customer to merchant's page/platform to complete the payment by inputting OTP and/or PIN. After the payment is completed, merchant then will receive the notification.

#### Payment - Recurring

In recurring scheme, the payment process will be scheduled. Hence, verification using OTP and/or PIN is not required in every payment. Customers only need to do the verification during card registration process and it will give merchant the authorization to run scheduled payment. In order to do that, merchant needs to bring parameter `CHANNEL-ID : "H2H"` in request header and`paymentType : "RECURRING"`in payment request body.

And as the response, merchant will not receive parameter `webRedirectUrl` to redirect the customer to merchant's page/platform to complete the payment. Payment request will be directly processed by acquirer and merchant will receive the notification.

**Payment Flow**

This below payment flow is for tokenization scheme.

<figure><img src="/files/BeHbdbUNU635d0LVBTyO" alt=""><figcaption><p>Payment Flow - BRI Direct Debit - Tokenization Scheme</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="204">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/payment-host-to-host</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/S8omMmJ0nsEXGiuxQNSk" path="/direct-debit/core/v1/debit/payment-host-to-host" method="post" %}
[swagger-dd-bri.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FTGgubuuwtHMTILYzd3P9%2Fswagger-dd-bri.yaml?alt=media\&token=9adec817-0618-412e-a2c9-7c1e5816b57a)
{% endopenapi %}

***

### 4. Payment Notification

After payment is completed, DOKU will send **HTTP Notification** to merchant's defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification).

***

### 5. Additional Feature

### Online Refund

This endpoint is used to create refund request for previous successful payment. Merchant can request a transaction refund to DOKU. Full refund and partial refund are available to be requested.

**Online Refund Flow**&#x20;

<figure><img src="/files/19LtMmU2HX8P149hythn" alt=""><figcaption><p>Online Refund Flow - BRI Direct Debit</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="196">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/refund</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/D5UAq40JBNsanHPhCXoq" path="/direct-debit/core/v1/debit/refund" method="post" %}
[swagger-dd-bri.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FOhI0Ei3qPMqmoZkS1UIc%2Fswagger-dd-bri.yaml?alt=media\&token=38081cd0-ad98-4035-b75d-7baf20564a51)
{% endopenapi %}

### Card Registration Unbinding

If a registered customer no longer wants their account/card to be bind/linked and wish to remove themself from DOKU's and merchant’s system, merchant can send account unbinding request that is initiated by customer.

#### API Endpoint&#x20;

<table><thead><tr><th width="187">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/registration-card-unbind</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Parameter without (\*) is optional/conditional

## POST /direct-debit/core/v1/registration-card-unbind

> Unbinding process from Merchant

```json
{"openapi":"3.0.3","info":{"title":"Swagger Direct Debit SNAP BRI","version":"1.0.11"},"servers":[{"url":"https://{api-domain}"}],"paths":{"/direct-debit/core/v1/registration-card-unbind":{"post":{"summary":"Unbinding process from Merchant","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnbindingRequest"}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnbindingResponse"}}}}}}}},"components":{"schemas":{"UnbindingRequest":{"type":"object","properties":{"token":{"type":"string","description":"format: Value from getTokenB2B2C | max: 2048 | Mandatory"},"additionalInfo":{"type":"object","required":["channel"],"properties":{"channel":{"type":"string","description":"Value should be always DIRECT_DEBIT_BRI_SNAP | Mandatory"}}}}},"UnbindingResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/response-code/http-status-and-case-code#id-4.-direct-debit | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"}}}}}}
```


# CIMB Direct Debit

CIMB direct debit offers tokenization scheme that requires customer to input OTP and/or PIN to verify every payment.

## Integration Steps

Overview of integration process with CIMB Direct Debit.

1. [Account Binding](#account-binding)
2. [OTP Verification](#otp-verification)
3. [Payment](#payment)
4. [Payment Notification](#payment-notification)
5. [Additional Feature](#additional-feature)

***

### 1. Account Binding

Account Binding process should be done before payment can be made and processed. Merchant will send account binding request from customer to DOKU. The request includes customer's phone number that is registered to customer's CIMB account.&#x20;

Each CIMB account can only be bind to one customer on one merchant. Customer needs to do verification for account binding process by inputting OTP and PIN.

**Account Binding Flow**

<figure><img src="/files/SO3BLIq4ATdTkYPRN7WQ" alt=""><figcaption><p>Account Binding Flow - CIMB Direct Debit</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="164">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/registration-account-binding</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/rnxmMV6SJqb1nQ7U4ubV" path="/direct-debit/core/v1/registration-account-binding" method="post" %}
[swagger-dd-cimb.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FoaZjG6E2dlA3zWziRLWu%2Fswagger-dd-cimb.yaml?alt=media\&token=bd3e1cb6-3aa3-44c9-a2a7-783ac2347aff)
{% endopenapi %}

### 2. Payment&#x20;

After customer's account is bind/linked and customer has enough balance for payment, merchant can send payment request from customer to DOKU by bringing customer's token.&#x20;

**Payment Flow**

<figure><img src="/files/xzEoVqnAnovtRlGjl9aQ" alt=""><figcaption><p>Payment Flow - CIMB Direct Debit</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="176">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/payment-host-to-host</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/iG397Dhs1cKknEnB2sYC" path="/direct-debit/core/v1/debit/payment-host-to-host" method="post" %}
[swagger-dd-cimb.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FYMVUtwk7I7eHMu7pZn6P%2Fswagger-dd-cimb.yaml?alt=media\&token=df89af0b-adc4-4794-8e21-227fbbf818d2)
{% endopenapi %}

### 3. OTP Verification

Once customer has submitted their payment request along with the OTP, merchant needs to verify the payment. Merchant can hit this API to verify the OTP.&#x20;

**OTP Verification Flow**

<figure><img src="/files/dWgHn2hE8mpe9sduoJx4" alt=""><figcaption><p>OTP Verification Flow - CIMB Direct Debit</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="181">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/otp-verification</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/1cHpbRZzyZpsGkkZkP02" path="/direct-debit/core/v1/otp-verification" method="post" %}
[swagger-dd-cimb.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2Fa2lNAyKJtxpw5GljSCr5%2Fswagger-dd-cimb.yaml?alt=media\&token=59c23421-e5d3-45fc-ac3e-55eb32e3818c)
{% endopenapi %}

### 4. Payment Notification

After payment is completed, DOKU will send **HTTP Notification** to merchant's defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification).

### 5. Additional Feature

### Online Refund

This endpoint is used to create refund request for previous successful payment. Merchant can request a transaction refund to DOKU. Full refund and partial refund are available to be requested.

**Online Refund Flow**

<figure><img src="/files/19LtMmU2HX8P149hythn" alt=""><figcaption><p>Online Refund Flow - CIMB Direct Debit</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="181">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/refund</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/doE0ebC649DwswCHSJaV" path="/direct-debit/core/v1/debit/refund" method="post" %}
[swagger-dd-cimb.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FxifX9PuFGLc7XdfhueHb%2Fswagger-dd-cimb.yaml?alt=media\&token=3cf1de7f-55c6-442e-bbfa-c5fc634154f0)
{% endopenapi %}

### Account Unbinding

If a registered customer no longer wants their account/card to be bind/linked and wish to remove themself from DOKU's and merchant’s system, merchant can send account unbinding request that is initiated by customer.

#### API Endpoint&#x20;

<table><thead><tr><th width="178">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/v1/registration-account-unbinding</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional&#x20;

{% openapi src="/files/oJ7TDZAO04VxuixyyUZo" path="/direct-debit/core/v1/registration-account-unbinding" method="post" %}
[swagger-dd-cimb.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2Fk6E1l2ZgQKzmDRLsGA1v%2Fswagger-dd-cimb.yaml?alt=media\&token=d2053c91-a82c-422d-be16-546f4c36865c)
{% endopenapi %}


# Mandiri Direct Debit

Mandiri offers 2 payment schemes, which are; 1) Tokenization scheme, and 2) Recurring scheme.

## Integration Steps

Overview of integration process with Mandiri Direct Debit

1. [Card Registration](#id-1.-card-registration)
2. [OTP Verification & Request](#id-2.-otp-verification-and-request)
3. [Payment](#id-3.-payment)
4. [Payment Notification](#id-4.-payment-notification)
5. [Additional Feature](#id-5.-additional-feature)

***

### 1. Card Registration

Card Registration process should be done before payment can be made and processed. Merchant will send card registration request from customer to DOKU. The request includes customer's card number that is registered to customer's Mandiri account.&#x20;

Each card/account can only be registered/bind to one customer on one merchant. Customer needs to verify OTP and input PIN to register the card.

**CBC Encryption**

To request card registration process, merchant requires to bring object cardData which value should be encrypted using CBC Algorithm.

CBC Encryption - Steps:

1. **Prepare shared key from DOKU as Secret Key**

   * Substring shared key only 16 digits
   * Example code:

   ```json
   private String getSharedKey(String sharedKey) {
       if (sharedKey.length() != 16) {
   sharedKey = sharedKey.length() > 16 ? sharedKey.substring(0, 16) : String.format("%-16s", sharedKey).replace(' ', '-');
       }
       return sharedKey;
   }
   ```
2. **Generate Initial Value (IV)**

   * Generate initial value with 16 bytes and then encode using Base 64
   * Example code:

   ```json
   byte[] iv = new byte[16];
   new SecureRandom().nextBytes(iv);
   IvParameterSpec ivParameterSpec = new IvParameterSpec(iv);
   String ivString = Base64.getEncoder().encodeToString(ivParameterSpec.getIV());
   ```
3. **Using Cipher CBC**

   * Value that will be encrypted combine with secret key generated before
   * After that encode the value using Base 64
   * Example code:

   ```json
   Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding"); //NOSONAR
   cipher.init(Cipher.ENCRYPT_MODE, key, ivParameterSpec);
   byte[] cipherText = cipher.doFinal(input.getBytes());
   String cipherString = Base64.getEncoder().encodeToString(cipherText);
   ```
4. **Combine CBC and IV**

   * Combine value CBC Cipher with IV value with separator (|)
   * Example code:

   <pre class="language-json"><code class="lang-json"><strong>String value = cipherString + "|" + ivString;
   </strong></code></pre>

Tools Using Java - Steps:

* Install JDK 17
* Go to folder
* Run with command java -jar cbc-tools.jar
* Input Value that you wish to be encrypted
* Input Key to encrypt&#x20;

Example Value:

(It should be minified)

```
{"bankCardNo":"4097662150169210","expiryDate":"2909"}
```

{% file src="/files/hIIYe2U7QDX432zkl8xy" %}
CBC Tools for Card Encryption
{% endfile %}

**Card Registration Flow**

<figure><img src="/files/SO3BLIq4ATdTkYPRN7WQ" alt=""><figcaption><p>Card Registration Flow - Mandiri Direct Debit</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="184">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/registration-card-bind</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Parameter without (\*) is optional/conditional

## POST /direct-debit/core/v1/registration-card-bind

> Register Card for Direct Debit Mandiri SNAP

```json
{"openapi":"3.0.3","info":{"title":"Direct Debit Mandiri SNAP","version":"1.0.11"},"servers":[{"url":"https://{api-domain}"}],"paths":{"/direct-debit/core/v1/registration-card-bind":{"post":{"summary":"Register Card for Direct Debit Mandiri SNAP","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Customer's current local time in yyyy-MM- ddTHH:mm:ssTZD format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","schema":{"type":"string"},"required":false,"description":"Enum: DH/H2H (Default: DH) | Max: 3"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindingRequest"}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindingResponse"}}}}}}}},"components":{"schemas":{"BindingRequest":{"type":"object","required":["cardData","custIdMerchant","additionalInfo"],"properties":{"cardData":{"type":"string","description":"Format Object: {\n  \"bankCardNo\": \"13763689649826892\",\n  \"expiryDate\": \"0129\"\n} Encrypt using CBC Algorithm Value: encryptedValue + ivString"},"custIdMerchant":{"type":"string","description":"Customer id from merchant | Alphanumeric | max length: 64 |"},"phoneNo":{"type":"string","description":"Customer's phone number, it is recommended to use the phone number that is linked to the card | Format: 628xxxxxxxxxx | min length: 9 max length: 16 | Mandatory"},"journeyId":{"type":"string","description":"Merchant ID, value must be unique | max length: 64"},"additionalInfo":{"$ref":"#/components/schemas/AdditionalInfo"}}},"AdditionalInfo":{"type":"object","required":["channel","custIdMerchant","successRegistrationUrl","failedRegistrationUrl"],"properties":{"channel":{"type":"string","description":"Value should be always DIRECT_DEBIT_MANDIRI_SNAP | Mandatory"},"customerName":{"type":"string","description":"Customer name from merchant | max length: 70"},"email":{"type":"string","description":"Customer email from merchant | max length: 64"},"idCard":{"type":"string","description":"Customer id card from merchant | max length: 20"},"country":{"type":"string","description":"Customer country | max length: 60"},"address":{"type":"string","description":"Customer Address | max length: 255"},"dateOfBirth":{"type":"string","description":"Customer Date of Birth | format: YYYYMMDD"},"successRegistrationUrl":{"type":"string","description":"Redirect URL when binding is success"},"failedRegistrationUrl":{"type":"string","description":"Redirect URL when binding is fail"}}},"BindingResponse":{"type":"object","required":["responseCode","responseMessage","additionalInfo"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/response-code/http-status-and-case-code#id-4.-direct-debit | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"referenceNo":{"type":"string","description":"Reference Number"},"redirectUrl":{"type":"string","description":"Redirect URL to Merchant's page/platform for customer to input OTP/PIN | Will show only if CHANNEL-ID is DH"},"additionalInfo":{"type":"object","required":["custIdMerchant","status","authCode"],"properties":{"custIdMerchant":{"type":"string","description":"Customer id from merchant | max length: 64"},"status":{"type":"string","description":"Current binding status | value always be PENDING"},"authCode":{"type":"string","description":"Authentication Code from Mandiri"}}}}}}}}
```

***

### 2. OTP Verification & Request

### OTP Verification

OTP verification is needed to verify the Card Registration request and Payment request. Merchant can hit this API to verify the OTP.&#x20;

**OTP Verification Flow**

<figure><img src="/files/dWgHn2hE8mpe9sduoJx4" alt=""><figcaption><p>OTP Verification Flow (Card Registration) - Mandiri Direct Debit</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="182">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/otp-verification</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Parameter without (\*) is optional/conditional

## POST /direct-debit/core/v1/otp-verification

> OTP Verification for Direct Debit Mandiri SNAP

```json
{"openapi":"3.0.3","info":{"title":"Direct Debit Mandiri SNAP","version":"1.0.11"},"servers":[{"url":"https://{api-domain}"}],"paths":{"/direct-debit/core/v1/otp-verification":{"post":{"summary":"OTP Verification for Direct Debit Mandiri SNAP","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Customer's current local time in yyyy-MM- ddTHH:mm:ssTZD format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"Authorization-customer","schema":{"type":"string","description":"Access Token obtained from Get B2B2C Token API"},"required":true,"description":"Access Token obtained from Get B2B2C Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2c) for detailed documentation"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpVerificationRequest"}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpVerificationResponse"}}}}}}}},"components":{"schemas":{"OtpVerificationRequest":{"type":"object","required":["originalPartnerReferenceNo","otp","action"],"properties":{"originalPartnerReferenceNo":{"type":"string","description":"Partner Reference Number Payment | max: 36 | Mandatory"},"otp":{"type":"string","description":"OTP sent to customer | min: 6 max: 6 | Mandatory"},"action":{"type":"string","description":"otpPayment is for verifying Payment, otpLinkage is for verifying Card Registration | Mandatory"},"additionalInfo":{"type":"object","required":["channel","bankCardToken"],"properties":{"channel":{"type":"string","description":"Value should be always DIRECT_DEBIT_MANDIRI_SNAP | Mandatory"},"bankCardToken":{"type":"string","description":"Account token from account binding process | Mandatory"}}}}},"OtpVerificationResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/response-code/http-status-and-case-code#id-4.-direct-debit . | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"originalReferenceNo":{"type":"string","description":"Reference No from"}}}}}}
```

### OTP Request

This API is used to trigger OTP generation as part of the authentication process for both Card Registration and Payment flows. Once the OTP is successfully generated and delivered to the customer, merchant can proceed by calling the OTP Verification API to validate the OTP input.

#### API Endpoint

<table><thead><tr><th width="182">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/otp</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Parameter without (\*) is optional/conditional

## POST /direct-debit/core/v1/otp

> Request OTP

```json
{"openapi":"3.0.3","info":{"title":"Direct Debit Core System - Request OTP API","version":"1.0.0"},"servers":[{"url":"https://api.doku.com","description":"Base URL","variables":{"host":{"default":"api.doku.com","description":"Host server"}}}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token B2B"}},"schemas":{"OtpRequest":{"type":"object","description":"Request body\n","required":["otpTrxCode","journeyId"],"properties":{"otpTrxCode":{"type":"string","description":"Code indicating the OTP transaction type:\n- `01` — Card Binding/Registration process\n- `02` — Payment process\n","maxLength":2},"journeyId":{"type":"string","description":"Journey ID, value must be unique","maxLength":32},"bankCardToken":{"type":"string","description":"Registered bank card token. Mandatory equired for payment flow and Optional for binding/linkage flow."},"additionalInfo":{"type":"object","required":["channel"],"properties":{"channel":{"type":"string","description":"Value should always be DIRECT_DEBIT_MANDIRI_SNAP"}}}}},"OtpResponse":{"type":"object","description":"Response body","properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code\n"},"responseMessage":{"type":"string","description":"Response Description."},"referenceNo":{"type":"string","description":"Reference No"},"additionalInfo":{"type":"object","description":"Additional Info","additionalProperties":true}}},"OtpResponseFailed":{"type":"object","description":"Response body","properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code\n"},"responseMessage":{"type":"string","description":"Response Description."}}}}},"paths":{"/direct-debit/core/v1/otp":{"post":{"summary":"Request OTP","operationId":"requestOtp","tags":["OTP"],"parameters":[{"name":"X-PARTNER-ID","in":"header","required":true,"description":"Unique ID for a partner (DOKU'S Client ID)","schema":{"type":"string","maxLength":36}},{"name":"X-EXTERNAL-ID","in":"header","required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)","schema":{"type":"string","maxLength":32}},{"name":"Authorization","in":"header","required":true,"description":"Access Token obtained from Get B2B Token API","schema":{"type":"string"}},{"name":"X-TIMESTAMP","in":"header","required":true,"description":"Customer's current local time in yyyy-MM- ddTHH:mm:ssTZD format","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+\\-]\\d{2}:\\d{2}$"}},{"name":"X-SIGNATURE","in":"header","required":true,"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpRequest"}}}},"responses":{"200":{"description":"Request OTP successfully processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpResponse"}}}},"400":{"description":"Request not valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpResponseFailed"}}}},"401":{"description":"Failed Authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpResponseFailed"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpResponseFailed"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpResponseFailed"}}}}}}}}}
```

***

### 3. Payment&#x20;

After customer's card is registered, payment process can be requested by bringing the card token generated in card registration process. After merchant hit payment API, DOKU will deduct customer's balance.&#x20;

#### Payment - Tokenization

In tokenization scheme, every payment needs to be verified by customer with inputting OTP and/or PIN. In order to do that, merchant needs to bring parameter `paymentType : "SALE"`in payment request body.

And as the response, merchant will receive parameter `webRedirectUrl` to redirect the customer to merchant's page/platform to complete the payment by inputting OTP and/or PIN. After the payment is completed, merchant then will receive the notification.

#### Payment - Recurring

In recurring scheme, the payment process will be scheduled. Hence, verification using OTP and/or PIN is not required in every payment. Customers only need to do the verification during card registration process and it will give merchant the authorization to run scheduled payment. In order to do that, merchant needs to bring parameter `CHANNEL-ID : "H2H"` in request header and`paymentType : "RECURRING"`in payment request body.

And as the response, merchant will not receive parameter `webRedirectUrl` to redirect the customer to merchant's page/platform to complete the payment. Payment request will be directly processed by acquirer and merchant will receive the notification.

**Payment Flow**

This below payment flow is for tokenization scheme.

<figure><img src="/files/BeHbdbUNU635d0LVBTyO" alt=""><figcaption><p>Payment Flow - Mandiri Direct Debit - Tokenization Scheme</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="204">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/payment-host-to-host</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Parameter without (\*) is optional/conditional

## POST /direct-debit/core/v1/debit/payment-host-to-host

> Request Payment from Merchant for Direct Debit Mandiri SNAP

```json
{"openapi":"3.0.3","info":{"title":"Direct Debit Mandiri SNAP","version":"1.0.11"},"servers":[{"url":"https://{api-domain}"}],"paths":{"/direct-debit/core/v1/debit/payment-host-to-host":{"post":{"summary":"Request Payment from Merchant for Direct Debit Mandiri SNAP","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Customer's current local time in yyyy-MM- ddTHH:mm:ssTZD format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"CHANNEL-ID","schema":{"type":"string"},"required":false,"description":"Default value: DH(DOKU Hosted) Value: DH/H2H"},{"in":"header","name":"Authorization-customer","schema":{"type":"string","description":"Access Token obtained from B2B2C Get Token API"},"required":true,"description":"Access Token obtained from Get B2B2C Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2c) for detailed documentation"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}}}}}},"components":{"schemas":{"PaymentRequest":{"type":"object","required":["partnerReferenceNo","amount","additionalInfo"],"properties":{"partnerReferenceNo":{"type":"string","description":"Reference No From Partner | max: 64 | Mandatory"},"amount":{"$ref":"#/components/schemas/AmountObject"},"journeyId":{"type":"string","description":"Merchant ID, value must be unique | max length: 64"},"additionalInfo":{"type":"object","required":["channel","successPaymentUrl","failedPaymentUrl"],"properties":{"channel":{"type":"string","description":"Value should be always DIRECT_DEBIT_MANDIRI_SNAP | Mandatory"},"successPaymentUrl":{"type":"string","description":"Redirect Url if payment success"},"failedPaymentUrl":{"type":"string","description":"Redirect Url if payment fail"},"paymentType":{"type":"string","description":"Enum: SALE, RECURRING (Default Value SALE)"}}}}},"AmountObject":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","description":"Transaction Amount. Total Amount with 2 decimal, format ISO 4217 |  min length: 1 | max length: 16.2 | Mandatory"},"currency":{"type":"string","description":"Currency | min length: 1 | max length: 3 | Mandatory "}}},"PaymentResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/response-code/http-status-and-case-code#id-4.-direct-debit | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"webRedirectUrl":{"type":"string","description":"Redirect URL to Merchant's page/platform for customer to input OTP/PIN | Will show if CHANNEL-ID is DH or null"},"partnerReferenceNo":{"type":"string","description":"Reference No From Partner"}}}}}}
```

***

### 4. Payment Notification

After payment is completed, DOKU will send **HTTP Notification** to merchant's defined `Notification URL`.  Learn how to [handle the notification from DOKU](/get-started-with-doku-api/notification).

***

### 5. Additional Feature

### a. Refund

Currently, refund for successful Direct Debit Mandiri transactions can only be done via Manual Refund Flow.

Supported refund types via Manual refund Flow:

* Full refund
* Partial refund
* Multiple partial refunds

**Manual Refund Flow**&#x20;

<figure><img src="/files/vE8jADuQlqy9PHn3dioH" alt=""><figcaption><p>Manual Refund Flow - Mandiri Direct Debit</p></figcaption></figure>

#### Steps to Request Manual Refund

Send email to DOKU

* To: <care@doku.com>
* Cc: <refund.chargeback@doku.com>
* Subject: `[Merchant Name] Refund Manual Request – DD Mandiri SNAP`

Include in your email

* Merchant Name
* Invoice Number
* Date of Transaction
* Transaction Amount
* Refund Amount

Processing Time

* Refunds are processed within 7 working days from the date Mandiri receives the request.
* If no update after 7 working days, escalate by replying to the same email.

#### Online Refund Flow

#### API Endpoint

Parameter without (\*) is optional/conditional

### b. Card Registration Unbinding

If a registered customer no longer wants their account/card to be bind/linked and wish to remove it from DOKU's and merchant’s system, merchant can send account unbinding request that is initiated by customer.

#### API Endpoint&#x20;

<table><thead><tr><th width="187">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/registration-card-unbind</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Parameter without (\*) is optional/conditional

## POST /direct-debit/core/v1/registration-card-unbind

> Card Registration Unbinding - Direct Debit Mandiri

```json
{"openapi":"3.0.3","info":{"title":"Direct Debit Mandiri SNAP","version":"1.0.11"},"servers":[{"url":"https://{api-domain}"}],"paths":{"/direct-debit/core/v1/registration-card-unbind":{"post":{"summary":"Card Registration Unbinding - Direct Debit Mandiri","parameters":[{"in":"header","name":"X-TIMESTAMP","schema":{"type":"string","format":"utc timestamp"},"required":true,"description":"Customer's current local time in yyyy-MM- ddTHH:mm:ssTZD format"},{"in":"header","name":"X-SIGNATURE","schema":{"type":"string"},"description":"Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)","required":true},{"in":"header","name":"X-PARTNER-ID","schema":{"type":"string"},"required":true,"description":"Unique ID for a partner (DOKU'S Client ID)"},{"in":"header","name":"X-EXTERNAL-ID","schema":{"type":"string"},"required":true,"description":"Numeric String. Reference number that should be unique in the same day (request-id)"},{"in":"header","name":"Authorization","schema":{"type":"string","description":"Access Token obtained from Get B2B Token API"},"required":true,"description":"Access Token obtained from Get B2B Token API | Go to [here](https://dokucom.gitbook.io/api-reference/direct-api/get-token-api/b2b) for detailed documentation"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnbindingRequest"}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnbindingResponse"}}}}}}}},"components":{"schemas":{"UnbindingRequest":{"type":"object","properties":{"token":{"type":"string","description":"format: Value from getTokenB2B2C | max: 2048 | Mandatory"},"additionalInfo":{"type":"object","required":["channel"],"properties":{"channel":{"type":"string","description":"Value should be always DIRECT_DEBIT_MANDIRI_SNAP | Mandatory"}}}}},"UnbindingResponse":{"type":"object","required":["responseCode","responseMessage"],"properties":{"responseCode":{"type":"string","description":"Response Code with format HTTP status code + service code + case code. service code and status code refer to: https://developers.doku.com/getting-started-with-doku-api/response-code/http-status-and-case-code#id-4.-direct-debit | Mandatory | min length: 1 | max length: 7."},"responseMessage":{"type":"string","description":"Response Description. | min length: 1 | max length: 150"},"referenceNo":{"type":"string","description":"Reference Number"},"redirectUrl":{"type":"string","description":"Redirect URL to Authenticate Customer | Will show only if CHANNEL-ID is DH"}}}}}}
```


# Kartu Kredit Indonesia Cepat Secure(KKI CPTS)

## Kartu Kredit Indonesia (KKI)

Kartu Kredit Indonesia is a new payment method initiated by Bank Indonesia & Asosiasi Sistem Pembayaran Indonesia(ASPI), instead of the usual credit card scheme transaction which uses PAN, Expiry Date, CVV, it instead requires CPAN (Customer PAN), and OTT(One Time Token) and Confirmation on Issuer's App so payment request can be security authenticated and authorized.

### Issuers Channels Supported

DOKU Is one of the first-mover Acquirer partnered with BI & ASPI with multiple issuers(Banks) to enable merchant to perform payment using KKI Channel

| Supported Issuers |
| ----------------- |
| BRI               |
| Mandiri           |
| BPD Bali          |
| BJB               |
| DKI Jakarta       |

With many more coming soon and will be automatically supported when available.

#### Integration Option

You can integrate credit card in two ways based on the PCI DSS compliance:

* Non-PCI DSS certified merchant is allowed to integrate using our [Checkout Page](/accept-payments/doku-checkout), where we will process customer's card information securely for you
* If you are  PCI DSS certified, you can integrate through [ H2H (Host to Host) API ](/accept-payments/direct-api/snap/integration-guide/kartu-kredit-indonesia-cepat-secure-kki-cpts/host-to-host-integration)

#### **What is PCI DSS?**

The Payment Card Industry Data Security Standard (PCI DSS) is an information security standard for organizations that handle branded credit cards from the major card schemes. The PCI Standard is mandated by the card brands but administered by the Payment Card Industry Security Standards Council.

### Payment Type

| Payment Type                   | Description                                                                                                                                                                                                                                                      |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Single Time Payment            | <p></p><p>A single transaction where the payment is processed only once using One Time Token(OTT) Generated by Issuer</p>                                                                                                                                        |
| Payment with Binding           | In a single transaction where the payment is processed only once using a time Token(OTT) Generated by the Issuer, the CPAN will be tokenized afterward for subsequent payment                                                                                    |
| Payment with Token             | In this type, a token (a secure digital representation of the card data) is generated and used for the transaction instead of the actual CPAN This token can be used securely for subsequent transactions, as the real card data is kept safe and isn’t exposed. |
| Payment without Authentication | This transaction type skips additional authentication steps, such as PIN or OTP (One-Time Password) on the issuer's application. This type of payment needs a token &  compatible for subscription-based transaction                                             |

## Interested in KKI ?

Do you think that might KKI might suits your project? Send your request [here](mailto:jokul@doku.com?subject=%5BRequest%5D%20Add%20New%20Plugin%3A%20Others)!


# Host to Host Integration

Integration Steps

Overview of integration process with KKI Integration

1. [Payment](#id-1.-payment)
2. [Refund](#id-2.-refund)

***

### 1. Payment&#x20;

Merchant can request for payment by requesting this API

**Payment Flow**

<figure><img src="/files/OTuzPPVMunh7c8pMjses" alt=""><figcaption><p>Flow Kartu Kredit Indonesia</p></figcaption></figure>

#### API Endpoint&#x20;

<table><thead><tr><th width="203">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/payment-host-to-host</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/qm5oM9GTXh6IrjmmWXQJ" path="/direct-debit/core/v1/debit/payment-host-to-host" method="post" %}
[swagger-kki (4).yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FvBnh9ffjFDmKrWGM64YD%2Fswagger-kki%20\(4\).yaml?alt=media\&token=8001e4d2-6732-45f1-b7be-c3da736201b8)
{% endopenapi %}

{% openapi src="/files/VmP7VixcBA2P331kUYlm" path="/direct-debit/core/v1/debit/payment-host-to-host" method="post" %}
[swagger-kki (1).yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FWKLP4zm8UigYVzQ6Q1Mo%2Fswagger-kki%20\(1\).yaml?alt=media\&token=18ea8e23-c1ec-4802-9f13-6d61af9b1a01)
{% endopenapi %}

{% openapi src="/files/15iUcAdw58RNSz3TGIwj" path="/direct-debit/core/v1/debit/payment-host-to-host" method="post" %}
[swagger-kki (2).yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FlSnQawwXOA27dOCadsBI%2Fswagger-kki%20\(2\).yaml?alt=media\&token=80692911-7e98-4484-a5ab-61d809fc9e73)
{% endopenapi %}

{% openapi src="/files/1OhIldyr3zFFuVT7CKLZ" path="/direct-debit/core/v1/debit/payment-host-to-host" method="post" %}
[swagger-kki (3).yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FqNvMhQwNPFMRdMsMxmyd%2Fswagger-kki%20\(3\).yaml?alt=media\&token=f76e1d1b-8436-40ef-a9e2-88bffba5c4cd)
{% endopenapi %}

### 2. Binding

This endpoint is used to tokenize a customer's CPAN without charging any amount, compared to the payment with Tokenization API which need to charges some amount to the Customer.

## Card Binding (Card Registration)

> Registers a credit card for a customer under a merchant account.\
> \
> \*\*Flow:\*\*\
> 1\. Merchant submits the encrypted card data along with customer information.\
> 2\. The system decrypts the card data, validates it against the ALTO/KKI network, and creates an \`AcquirerToken\`.\
> 3\. On success, a \`redirectUrl\` is returned (when \`CHANNEL-ID: DH\`) pointing to the OTP verification page.\
> 4\. The customer completes OTP verification, which finalises the binding and issues a \`bankCardToken\`.\
> \
> \*\*Card Data Encryption:\*\*\
> Encrypt the \`CardDataPayload\` JSON object using AES-CBC with the merchant's \`sharedKey\`.\
> The resulting Base64-encoded ciphertext is submitted as the \`cardData\` field.<br>

```json
{"openapi":"3.0.3","info":{"title":"Direct Debit Core System - Card Binding (KARTU_KREDIT_INDONESIA)","version":"1.0.0"},"servers":[{"url":"https://api.doku.com","description":"Base URL"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"B2B access token obtained from the Get B2B Token API (`/authorization/v1/access-token/b2b`)"}},"schemas":{"CardBindingRequest":{"type":"object","description":"Request body for card binding (registration)","required":["cardData","custIdMerchant","additionalInfo"],"properties":{"partnerReferenceNo":{"type":"string","description":"Merchant's unique reference number for this binding request","maxLength":64},"cardData":{"type":"string","description":"AES-CBC encrypted JSON of the card data, Base64-encoded.\nEncrypt the `CardDataPayload` object using the merchant's `sharedKey` provided by DOKU.\nSee the `CardDataPayload` schema for the plaintext structure.\n"},"custIdMerchant":{"type":"string","description":"Merchant's unique identifier for the customer","maxLength":64,"pattern":"^[a-zA-Z0-9]+$"},"journeyId":{"type":"string","description":"Optional journey or session ID for tracking the binding flow end-to-end"},"phoneNo":{"type":"string","description":"Customer's phone number (used for OTP delivery during OTP verification step)"},"additionalInfo":{"$ref":"#/components/schemas/BindingAdditionalInfo"}}},"BindingAdditionalInfo":{"type":"object","description":"Additional information for the card binding request","required":["channel"],"properties":{"channel":{"type":"string","description":"Product channel. Must be `KARTU_KREDIT_INDONESIA` for this operation.","enum":["KARTU_KREDIT_INDONESIA"]},"customerName":{"type":"string","description":"Full name of the cardholder","maxLength":70},"email":{"type":"string","description":"Email address of the cardholder","format":"email","maxLength":254},"address":{"type":"string","description":"Cardholder's billing address","maxLength":255},"dateOfBirth":{"type":"string","description":"Cardholder's date of birth in `YYYYMMDD` format","pattern":"^\\d{8}$"},"idCard":{"type":"string","description":"National ID card number (KTP) of the cardholder"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code of the cardholder","maxLength":2},"successRegistrationUrl":{"type":"string","description":"Merchant URL to redirect to after successful OTP verification"},"failedRegistrationUrl":{"type":"string","description":"Merchant URL to redirect to after failed OTP verification"}}},"CardBindingResponse":{"type":"object","description":"Response body for a successful card binding request","properties":{"responseCode":{"type":"string","description":"Response code: HTTP Status (3) + Service Code `01` (2) + Case Code (2).\nExample: `2000100` = HTTP 200 + service `01` + case `00` (Successful).\n"},"responseMessage":{"type":"string","description":"Human-readable response message"},"referenceNo":{"type":"string","description":"DOKU-generated reference number for this binding request"},"redirectUrl":{"type":"string","description":"URL for OTP verification page hosted by DOKU.\nOnly present when `CHANNEL-ID: DH`. Merchant must redirect the customer here\nto complete the binding via OTP entry.\n"},"bankCardToken":{"type":"string","description":"Reusable token representing the bound credit card.\nPresent only after OTP verification is successfully completed (final binding state).\nUse this token for subsequent payment requests.\n"},"chargeToken":{"type":"string","description":"Charge token from the ALTO network (from the decrypted card data), if applicable"},"additionalInfo":{"$ref":"#/components/schemas/BindingResponseAdditionalInfo"}}},"BindingResponseAdditionalInfo":{"type":"object","description":"Additional information in the binding response","properties":{"custIdMerchant":{"type":"string","description":"The merchant's customer ID echoed back from the request"},"status":{"type":"string","description":"Current binding status of the token:\n- `PENDING` — OTP verification not yet completed\n- `SUCCESS` — Binding fully completed\n- `FAILED` — Binding failed\n","enum":["PENDING","SUCCESS","FAILED"]},"authCode":{"type":"string","description":"Session ID / authentication code for the OTP verification step.\nUsed internally by the redirect URL (DH) or passed to the OTP verification API (H2H).\n"}}},"ErrorResponse":{"type":"object","description":"Standard error response body.\nResponse code format: HTTP Status (3) + Service Code `01` (2) + Case Code (2).\n\n| Case Code | Meaning                                              |\n|-----------|------------------------------------------------------|\n| `00`      | General / Format Error                               |\n| `01`      | Duplicate Transaction / Duplicate Token              |\n| `02`      | Invalid OTT / External Server Error                  |\n| `03`      | Suspected Fraud                                      |\n| `04`      | Exceeds Transaction Frequency Limit                  |\n| `05`      | Do Not Honor (declined by issuer)                    |\n| `08`      | Invalid Merchant / No Card Record                    |\n| `11`      | Invalid CPAN                                         |\n| `12`      | Transaction Not Permitted / OTT Expired              |\n| `13`      | Invalid Amount                                       |\n| `14`      | Insufficient Funds                                   |\n| `15`      | Transaction Not Permitted to Terminal                |\n","properties":{"responseCode":{"type":"string","description":"Error response code"},"responseMessage":{"type":"string","description":"Human-readable error message"}}}}},"paths":{"/direct-debit/core/v1/registration-card-bind":{"post":{"summary":"Card Binding (Card Registration)","description":"Registers a credit card for a customer under a merchant account.\n\n**Flow:**\n1. Merchant submits the encrypted card data along with customer information.\n2. The system decrypts the card data, validates it against the ALTO/KKI network, and creates an `AcquirerToken`.\n3. On success, a `redirectUrl` is returned (when `CHANNEL-ID: DH`) pointing to the OTP verification page.\n4. The customer completes OTP verification, which finalises the binding and issues a `bankCardToken`.\n\n**Card Data Encryption:**\nEncrypt the `CardDataPayload` JSON object using AES-CBC with the merchant's `sharedKey`.\nThe resulting Base64-encoded ciphertext is submitted as the `cardData` field.\n","operationId":"cardBindingKKI","tags":["Binding"],"parameters":[{"name":"X-PARTNER-ID","in":"header","required":true,"description":"Merchant's client ID registered with DOKU","schema":{"type":"string","maxLength":32}},{"name":"X-EXTERNAL-ID","in":"header","required":true,"description":"Unique reference ID for this request (per-day uniqueness required).\nUsed for idempotency and tracing.\n","schema":{"type":"string","maxLength":36}},{"name":"Authorization","in":"header","required":true,"description":"B2B access token obtained from the Get B2B Token API","schema":{"type":"string"}},{"name":"X-TIMESTAMP","in":"header","required":true,"description":"Request timestamp in ISO 8601 format (yyyy-MM-ddTHH:mm:ss+07:00)","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+\\-]\\d{2}:\\d{2}$"}},{"name":"X-SIGNATURE","in":"header","required":true,"description":"HMAC-SHA512 asymmetric signature for request integrity verification","schema":{"type":"string"}},{"name":"CHANNEL-ID","in":"header","required":false,"description":"Channel identifier determining the post-registration redirect behaviour.\n- `DH` (Direct Hosting, default): returns a `redirectUrl` pointing to the DOKU-hosted OTP page.\n- `H2H` (Host-to-Host): no redirect; merchant handles the OTP flow independently.\n","schema":{"type":"string","enum":["DH","H2H"],"default":"DH"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardBindingRequest"}}}},"responses":{"200":{"description":"Card binding request accepted. The customer must complete OTP verification\nto finalise the binding. Use `redirectUrl` (DH flow) or `additionalInfo.authCode`\n(H2H flow) to proceed.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardBindingResponse"}}}},"202":{"description":"Request in progress (timeout from ALTO network; may still succeed asynchronously)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Bad request — missing or invalid fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failure — invalid token or card data decryption failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — transaction not permitted or card restrictions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — merchant, card, or transaction record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — duplicate transaction or duplicate token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error or external system malfunction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

### 3. Unbinding

This endpoint is used to unbind a previously binded token  compared to the payment with Tokenization API which need to charges some amount to the Customer.

## Card Unbinding

> Deactivates a previously bound credit card token for a customer under a merchant account.\
> \
> \*\*Flow:\*\*\
> 1\. Merchant submits the \`tokenId\` (i.e., the \`bankCardToken\` from the binding response).\
> 2\. The system locates all active tokens for the card and marks them as \`PENDING\` for deactivation.\
> 3\. The unbinding is finalised asynchronously via the ALTO/KKI network.\
> 4\. A Kafka event is published for downstream systems.\
> \
> The \`tokenId\` is the raw token value for KKI (not Base64-decoded, unlike other channels).<br>

```json
{"openapi":"3.0.3","info":{"title":"Direct Debit Core System - Card Unbinding (KARTU_KREDIT_INDONESIA)","version":"1.0.0"},"servers":[{"url":"https://api.doku.com","description":"Base URL"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"B2B access token obtained from the Get B2B Token API (`/authorization/v1/access-token/b2b`)"}},"schemas":{"CardUnbindingRequest":{"type":"object","description":"Request body for card unbinding","required":["tokenId","additionalInfo"],"properties":{"tokenId":{"type":"string","description":"The token to be deactivated. This is the `bankCardToken` value returned\nin the binding response (or from the token list).\nFor KKI, this value is used as-is (no Base64 decoding is applied).\n"},"additionalInfo":{"$ref":"#/components/schemas/UnbindingAdditionalInfo"}}},"UnbindingAdditionalInfo":{"type":"object","description":"Additional information for the unbinding request","required":["channelId"],"properties":{"channelId":{"type":"string","description":"Product channel identifier. Must be `KARTU_KREDIT_INDONESIA` for this operation.","enum":["KARTU_KREDIT_INDONESIA"]}}},"CardUnbindingResponse":{"type":"object","description":"Response body for a successful card unbinding request","properties":{"responseCode":{"type":"string","description":"Response code: HTTP Status (3) + Service Code `05` (2) + Case Code (2).\nExample: `2000500` = HTTP 200 + service `05` + case `00` (Successful).\n"},"responseMessage":{"type":"string","description":"Human-readable response message"},"referenceNo":{"type":"string","description":"DOKU-generated reference number for this unbinding request"},"additionalInfo":{"$ref":"#/components/schemas/UnbindingResponseAdditionalInfo"}}},"UnbindingResponseAdditionalInfo":{"type":"object","description":"Additional information in the unbinding response","properties":{"custIdMerchant":{"type":"string","description":"The merchant's customer ID associated with the unbound token"},"status":{"type":"string","description":"Current token status after unbinding:\n- `PENDING` — Deactivation in progress (finalised asynchronously via ALTO network)\n- `SUCCESS` — Token fully deactivated\n","enum":["PENDING","SUCCESS"]},"redirectUrl":{"type":"string","description":"Redirect URL, if applicable for the unbinding flow"}}},"ErrorResponse":{"type":"object","description":"Standard error response body.\nResponse code format: HTTP Status (3) + Service Code `05` (2) + Case Code (2).\n\n| Case Code | Meaning                                              |\n|-----------|------------------------------------------------------|\n| `00`      | General / Format Error                               |\n| `01`      | Duplicate Transaction / Duplicate Token              |\n| `02`      | Invalid OTT / External Server Error                  |\n| `03`      | Suspected Fraud                                      |\n| `04`      | Exceeds Transaction Frequency Limit                  |\n| `05`      | Do Not Honor (declined by issuer)                    |\n| `08`      | Invalid Merchant / No Card Record                    |\n| `11`      | Invalid CPAN                                         |\n| `12`      | Transaction Not Permitted / OTT Expired              |\n| `13`      | Invalid Amount                                       |\n| `14`      | Insufficient Funds                                   |\n| `15`      | Transaction Not Permitted to Terminal                |\n","properties":{"responseCode":{"type":"string","description":"Error response code"},"responseMessage":{"type":"string","description":"Human-readable error message"}}}}},"paths":{"/direct-debit/core/v1/registration-card-unbind":{"post":{"summary":"Card Unbinding","description":"Deactivates a previously bound credit card token for a customer under a merchant account.\n\n**Flow:**\n1. Merchant submits the `tokenId` (i.e., the `bankCardToken` from the binding response).\n2. The system locates all active tokens for the card and marks them as `PENDING` for deactivation.\n3. The unbinding is finalised asynchronously via the ALTO/KKI network.\n4. A Kafka event is published for downstream systems.\n\nThe `tokenId` is the raw token value for KKI (not Base64-decoded, unlike other channels).\n","operationId":"cardUnbindingKKI","tags":["Unbinding"],"parameters":[{"name":"X-PARTNER-ID","in":"header","required":true,"description":"Merchant's client ID registered with DOKU","schema":{"type":"string","maxLength":32}},{"name":"X-EXTERNAL-ID","in":"header","required":true,"description":"Unique reference ID for this request (per-day uniqueness required)","schema":{"type":"string","maxLength":36}},{"name":"Authorization","in":"header","required":true,"description":"B2B access token obtained from the Get B2B Token API","schema":{"type":"string"}},{"name":"X-TIMESTAMP","in":"header","required":true,"description":"Request timestamp in ISO 8601 format (yyyy-MM-ddTHH:mm:ss+07:00)","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}[+\\-]\\d{2}:\\d{2}$"}},{"name":"X-SIGNATURE","in":"header","required":true,"description":"HMAC-SHA512 asymmetric signature for request integrity verification","schema":{"type":"string"}},{"name":"X-IP-ADDRESS","in":"header","required":false,"description":"IP address of the end customer's device","schema":{"type":"string"}},{"name":"CHANNEL-ID","in":"header","required":false,"description":"Channel identifier. Defaults to `DH` (Direct Hosting).\n- `DH`: may return a `redirectUrl` for redirect-based unbinding flows.\n- `H2H`: host-to-host; returns a plain success response without redirect.\n","schema":{"type":"string","enum":["DH","H2H"],"default":"DH"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardUnbindingRequest"}}}},"responses":{"200":{"description":"Unbinding request accepted. The token is now in `PENDING` deactivation state.\nFinal deactivation is completed asynchronously via the ALTO/KKI network.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardUnbindingResponse"}}}},"400":{"description":"Bad request — missing or invalid fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failure — invalid B2B token or token not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — transaction not permitted for the given card/account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found — active token not found for the given merchant and token ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

### 4. Refund

### Online Refund

This endpoint is used to create refund request for previous successful payment. Merchant can request a transaction refund to DOKU. Full refund and partial refund are available to be requested

**Online Refund Flow**

<figure><img src="/files/9uLyS7KXEgymVT5g2AfX" alt=""><figcaption><p>Online Refund Flow -  KKI Refund Flow</p></figcaption></figure>

#### API Endpoint&#x20;

<table><thead><tr><th width="215">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/refund</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="/files/rbGiMBn1DE6zRKEnCsnu" path="/direct-debit/core/v1/debit/refund" method="post" %}
[swagger-dd-allo.yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FVCYOKw46b3xQWjJlXHZ9%2Fswagger-dd-allo.yaml?alt=media\&token=a1acaa1a-720b-44cc-bd59-28c79392f3cd)
{% endopenapi %}


# QRIS

QRIS (Quick Response Code Indonesian Standard) is a QR code standard developed by Bank Indonesia and Indonesian Payment System Association (ASPI) for cashless payments in Indonesia.

Overview Steps

Overview of integration process with QRIS

1. [Generate QRIS](#id-1.-generate-qris)
2. [Query QRIS](#id-2.-query-qris)
3. [Refund QRIS](#id-3.-refund-qris)
4. [Decode QRIS](#id-4.-decode-qris)
5. [Payment QRIS](#id-5.-payment-qris)
6. [Cancel QRIS](#id-6.-cancel-qris)

***

### 1. Generate QRIS

After customer creates an order and choose QRIS as the payment method, merchant will hit this API to generate QRIS that will be shown to the customer. To generate QRIS, you need to hit this API through your Backend:

#### API Endpoint

| Environment    | Endpoint                                                      |
| -------------- | ------------------------------------------------------------- |
| HTTP Method    | POST                                                          |
| API Sandbox    | [https://api-sandbox.doku.com](https://api-sandbox.doku.com/) |
| API Production | [https://api.doku.com](https://api.doku.com/)                 |
| Path           | `/snap-adapter/b2b/v1.0/qr/qr-mpm-generate`                   |

Here is the sample request header, request body and response body for generate QRIS:

## POST /snap-adapter/b2b/v1.0/qr/qr-mpm-generate

> POST Generate QRIS

```json
{"openapi":"3.0.0","info":{"title":"doku-wallet-snap-api-qris","version":"1.0.0"},"tags":[{"name":"QRIS","description":"QRIS operations B2B"}],"servers":[{"url":"https://api-sandbox.doku.com"}],"paths":{"/snap-adapter/b2b/v1.0/qr/qr-mpm-generate":{"post":{"tags":["QRIS"],"summary":"POST Generate QRIS","operationId":"qr-mpm-generate","parameters":[{"$ref":"#/components/parameters/xPartnerId"},{"$ref":"#/components/parameters/xExternalId"},{"$ref":"#/components/parameters/xTimeStamp"},{"$ref":"#/components/parameters/xSignature"},{"$ref":"#/components/parameters/authorization"},{"$ref":"#/components/parameters/channelId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateQrisRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateQrisResponse"}}}}}}}},"components":{"parameters":{"xPartnerId":{"name":"X-PARTNER-ID","in":"header","description":"Client Id for merchant that generated by DOKU","required":true,"schema":{"type":"string"}},"xExternalId":{"name":"X-EXTERNAL-ID","in":"header","description":"Numeric String. Reference number that should be unique in the same day (Request Id)","required":true,"schema":{"type":"string"}},"xTimeStamp":{"name":"X-TIMESTAMP","in":"header","description":"Client's current local time with format YYYY-MM-DDTHH:mm:ssZD","required":true,"schema":{"type":"string"}},"xSignature":{"name":"X-SIGNATURE","in":"header","description":"Symmetric Signature with Get Token (Default)HMAC_SHA512 (clientSecret, stringToSign) dengan formula stringToSign = HTTPMethod +”:“+ EndpointUrl +\":\"+ AccessToken +\":“+ Lowercase(HexEncode(SHA-256(minify(RequestBody))))+ \":“ + TimeStamp","required":true,"schema":{"type":"string"}},"authorization":{"name":"Authorization","required":true,"in":"header","description":"String starts with keyword “Bearer ” followed by token B2B (e.g. Bearer eyJraWQiOi...Jzc29zIiwiY)","schema":{"type":"string"}},"channelId":{"name":"CHANNEL-ID","in":"header","description":"Channel ID for QRIS please fill with H2H (Host-To-Host)","required":true,"schema":{"type":"string"}}},"schemas":{"GenerateQrisRequest":{"type":"object","required":["partnerReferenceNo","amount","merchantId","terminalId","additionalInfo"],"properties":{"partnerReferenceNo":{"type":"string","description":"Transaction ID from partners","maxLength":64},"amount":{"type":"object","required":["value","currency"],"description":"Detail Amount","properties":{"value":{"type":"string","pattern":"^\\d{1,16}\\.00$","description":"Net amount of the transaction. If it's IDR then the value includes 2 decimal digits. e.g. IDR 10.000,- will be placed with 10000.00 with 2 decimal"},"currency":{"type":"string","description":"Currency (ISO4217) Default “IDR”"}}},"merchantId":{"description":"Credential mall ID from DOKU","maxLength":64,"type":"string"},"terminalId":{"type":"string","maxLength":16,"minLength":3,"description":"Terminal Identification alphanumeric"},"validityPeriod":{"type":"string","description":"Expired Time QRIS using ISO 8601 Format, if not sent will use Default value 30 days"},"additionalInfo":{"type":"object","description":"Additional Information use to determine QRIS postal code & feeType, also used in order to fulfill non-mandatory parameters for QRIS Merchant","required":["postalCode","feeType"],"properties":{"postalCode":{"type":"string","maxLength":5,"description":"User postal code address Numeric"},"feeType":{"type":"string","enum":[1],"description":"Parameter to describe fee type that will be used:\n1. No Tips"}}}}},"GenerateQrisResponse":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"},"referenceNo":{"type":"string"},"partnerReferenceNo":{"type":"string"},"qrContent":{"type":"string"},"terminalId":{"type":"string"},"additionalInfo":{"type":"object","description":"Additional Information, values are based from object additionalInfo in generate qris request operation","properties":{"validityPeriod":{"type":"string"},"postalCode":{"type":"string","maxLength":5,"description":"User postal code address Numeric"},"feeType":{"type":"string","enum":[1],"description":"Parameter to describe fee type that will be used:\n1. No Tips"}}}}}}}}
```

### 2. Query QRIS

To query QRIS, you need to hit this API through your Backend:

#### API Endpoint

| Environment    | Endpoint                                                      |
| -------------- | ------------------------------------------------------------- |
| HTTP Method    | POST                                                          |
| API Sandbox    | [https://api-sandbox.doku.com](https://api-sandbox.doku.com/) |
| API Production | [https://api.doku.com](https://api.doku.com/)                 |
| Path           | `/snap-adapter/b2b/v1.0/qr/qr-mpm-query`                      |

Here is the sample request header, request body and response body for query QRIS:

## POST /snap-adapter/b2b/v1.0/qr/qr-mpm-query

> POST Query QRIS

```json
{"openapi":"3.0.0","info":{"title":"doku-wallet-snap-api-qris","version":"1.0.0"},"tags":[{"name":"QRIS","description":"QRIS operations B2B"}],"servers":[{"url":"https://api-sandbox.doku.com"}],"paths":{"/snap-adapter/b2b/v1.0/qr/qr-mpm-query":{"post":{"tags":["QRIS"],"summary":"POST Query QRIS","operationId":"qr-mpm-query","parameters":[{"$ref":"#/components/parameters/xPartnerId"},{"$ref":"#/components/parameters/xTimeStamp"},{"$ref":"#/components/parameters/xExternalId"},{"$ref":"#/components/parameters/xSignature"},{"$ref":"#/components/parameters/authorization"},{"$ref":"#/components/parameters/channelId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryQrisRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryQrisResponse"}}}}}}}},"components":{"parameters":{"xPartnerId":{"name":"X-PARTNER-ID","in":"header","description":"Client Id for merchant that generated by DOKU","required":true,"schema":{"type":"string"}},"xTimeStamp":{"name":"X-TIMESTAMP","in":"header","description":"Client's current local time with format YYYY-MM-DDTHH:mm:ssZD","required":true,"schema":{"type":"string"}},"xExternalId":{"name":"X-EXTERNAL-ID","in":"header","description":"Numeric String. Reference number that should be unique in the same day (Request Id)","required":true,"schema":{"type":"string"}},"xSignature":{"name":"X-SIGNATURE","in":"header","description":"Symmetric Signature with Get Token (Default)HMAC_SHA512 (clientSecret, stringToSign) dengan formula stringToSign = HTTPMethod +”:“+ EndpointUrl +\":\"+ AccessToken +\":“+ Lowercase(HexEncode(SHA-256(minify(RequestBody))))+ \":“ + TimeStamp","required":true,"schema":{"type":"string"}},"authorization":{"name":"Authorization","required":true,"in":"header","description":"String starts with keyword “Bearer ” followed by token B2B (e.g. Bearer eyJraWQiOi...Jzc29zIiwiY)","schema":{"type":"string"}},"channelId":{"name":"CHANNEL-ID","in":"header","description":"Channel ID for QRIS please fill with H2H (Host-To-Host)","required":true,"schema":{"type":"string"}}},"schemas":{"QueryQrisRequest":{"type":"object","required":["originalReferenceNo","originalPartnerReferenceNo","serviceCode","merchantId"],"properties":{"originalReferenceNo":{"type":"string","description":"Transaction ID from DOKU when Generate QRIS","maxLength":64},"originalPartnerReferenceNo":{"type":"string","description":"Transaction ID from partners when Generate QRIS","maxLength":64},"serviceCode":{"type":"string","maxLength":2,"description":"Unique service API “47”"},"merchantId":{"type":"string","maxLength":64,"description":"Merchant ID registered in DOKU"}}},"QueryQrisResponse":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"},"originalReferenceNo":{"maxLength":64,"type":"string"},"originalPartnerReferenceNo":{"type":"string","maxLength":64},"serviceCode":{"type":"string"},"latestTransactionStatus":{"type":"string"},"transactionStatusDesc":{"type":"string"},"paidTime":{"type":"string"},"amount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","pattern":"^\\d{1,16}\\.00$"},"currency":{"type":"string"}}},"feeAmount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","pattern":"^\\d{1,16}\\.00$"},"currency":{"type":"string"}}},"additionalInfo":{"type":"object","required":["approvalCode"],"properties":{"approvalCode":{"type":"string"},"convenienceFee":{"type":"string"},"issuerId":{"type":"string"},"issuerName":{"type":"string"},"terminalId":{"type":"string"},"customerName":{"type":"string"}}}}}}}}
```

### 3. Refund QRIS

This endpoint is used to create refund request for previous successful payment, merchant can request a transaction refund to DOKU. To refund, you need to hit this API through your Backend:

#### API Endpoint

| Environment    | Endpoint                                                      |
| -------------- | ------------------------------------------------------------- |
| HTTP Method    | POST                                                          |
| API Sandbox    | [https://api-sandbox.doku.com](https://api-sandbox.doku.com/) |
| API Production | [https://api.doku.com](https://api.doku.com/)                 |
| Path           | `/snap-adapter/b2b/v1.0/qr/qr-mpm-refund`                     |

Here is the sample request header, request body and response body for refund QRIS:

## POST /snap-adapter/b2b/v1.0/qr/qr-mpm-refund

> POST Refund QRIS

```json
{"openapi":"3.0.0","info":{"title":"doku-wallet-snap-api-qris","version":"1.0.0"},"tags":[{"name":"QRIS","description":"QRIS operations B2B"}],"servers":[{"url":"https://api-sandbox.doku.com"}],"paths":{"/snap-adapter/b2b/v1.0/qr/qr-mpm-refund":{"post":{"tags":["QRIS"],"summary":"POST Refund QRIS","operationId":"qr-mpm-refund","parameters":[{"$ref":"#/components/parameters/xPartnerId"},{"$ref":"#/components/parameters/xTimeStamp"},{"$ref":"#/components/parameters/xExternalId"},{"$ref":"#/components/parameters/xSignature"},{"$ref":"#/components/parameters/authorization"},{"$ref":"#/components/parameters/channelId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundQrisRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundQrisResponse"}}}}}}}},"components":{"parameters":{"xPartnerId":{"name":"X-PARTNER-ID","in":"header","description":"Client Id for merchant that generated by DOKU","required":true,"schema":{"type":"string"}},"xTimeStamp":{"name":"X-TIMESTAMP","in":"header","description":"Client's current local time with format YYYY-MM-DDTHH:mm:ssZD","required":true,"schema":{"type":"string"}},"xExternalId":{"name":"X-EXTERNAL-ID","in":"header","description":"Numeric String. Reference number that should be unique in the same day (Request Id)","required":true,"schema":{"type":"string"}},"xSignature":{"name":"X-SIGNATURE","in":"header","description":"Symmetric Signature with Get Token (Default)HMAC_SHA512 (clientSecret, stringToSign) dengan formula stringToSign = HTTPMethod +”:“+ EndpointUrl +\":\"+ AccessToken +\":“+ Lowercase(HexEncode(SHA-256(minify(RequestBody))))+ \":“ + TimeStamp","required":true,"schema":{"type":"string"}},"authorization":{"name":"Authorization","required":true,"in":"header","description":"String starts with keyword “Bearer ” followed by token B2B (e.g. Bearer eyJraWQiOi...Jzc29zIiwiY)","schema":{"type":"string"}},"channelId":{"name":"CHANNEL-ID","in":"header","description":"Channel ID for QRIS please fill with H2H (Host-To-Host)","required":true,"schema":{"type":"string"}}},"schemas":{"RefundQrisRequest":{"type":"object","required":["originalPartnerReferenceNo","partnerRefundNo","refundAmount","reason","additionalInfo","merchantId"],"properties":{"merchantId":{"description":"Credential mall ID from DOKU","type":"string","maxLength":64},"originalPartnerReferenceNo":{"type":"string","maxLength":64,"description":"Transaction ID from DOKU when Generate QRIS from SNAP (same as originalReferenceNo value from Generate QRIS Request)"},"originalReferenceNo":{"maxLength":64,"type":"string","description":"Original Transaction ID from DOKU from response payment QRIS / Invoice from notify QRIS"},"partnerRefundNo":{"type":"string","maxLength":64},"refundAmount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","pattern":"^\\d{1,16}\\.00$"},"currency":{"type":"string"}}},"reason":{"type":"string","maxLength":256},"additionalInfo":{"type":"object","required":["approvalCode"],"properties":{"approvalCode":{"type":"string","maxLength":32}}}}},"RefundQrisResponse":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string","maxLength":150},"originalReferenceNo":{"type":"string","maxLength":32},"originalPartnerReferenceNo":{"type":"string","maxLength":64},"refundNo":{"type":"string","maxLength":64},"partnerRefundNo":{"type":"string","maxLength":30},"refundAmount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","pattern":"^\\d{1,16}\\.00$"},"currency":{"type":"string"}}},"refundTime":{"type":"string"}}}}}}
```

### 4. Decode QRIS

To decode QRIS, you need to hit this API through your Backend:

#### API Endpoint

| Environment    | Endpoint                                                      |
| -------------- | ------------------------------------------------------------- |
| HTTP Method    | POST                                                          |
| API Sandbox    | [https://api-sandbox.doku.com](https://api-sandbox.doku.com/) |
| API Production | [https://api.doku.com](https://api.doku.com/)                 |
| Path           | `/snap-adapter/b2b/v1.0/qr/qr-mpm-decode`                     |

Here is the sample request header, request body and response body for decode QRIS:

## POST /snap-adapter/b2b/v1.0/qr/qr-mpm-decode

> POST Decode QRIS

```json
{"openapi":"3.0.0","info":{"title":"doku-wallet-snap-api-qris","version":"1.0.0"},"tags":[{"name":"QRIS-PARTNER","description":"QRIS operations B2B2C"}],"servers":[{"url":"https://api-sandbox.doku.com"}],"paths":{"/snap-adapter/b2b/v1.0/qr/qr-mpm-decode":{"post":{"tags":["QRIS-PARTNER"],"summary":"POST Decode QRIS","operationId":"qr-mpm-decode","parameters":[{"$ref":"#/components/parameters/xPartnerId"},{"$ref":"#/components/parameters/xTimeStamp"},{"$ref":"#/components/parameters/xExternalId"},{"$ref":"#/components/parameters/xSignature"},{"$ref":"#/components/parameters/authorization"},{"$ref":"#/components/parameters/channelId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecodeQrisRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecodeQrisResponse"}}}}}}}},"components":{"parameters":{"xPartnerId":{"name":"X-PARTNER-ID","in":"header","description":"Client Id for merchant that generated by DOKU","required":true,"schema":{"type":"string"}},"xTimeStamp":{"name":"X-TIMESTAMP","in":"header","description":"Client's current local time with format YYYY-MM-DDTHH:mm:ssZD","required":true,"schema":{"type":"string"}},"xExternalId":{"name":"X-EXTERNAL-ID","in":"header","description":"Numeric String. Reference number that should be unique in the same day (Request Id)","required":true,"schema":{"type":"string"}},"xSignature":{"name":"X-SIGNATURE","in":"header","description":"Symmetric Signature with Get Token (Default)HMAC_SHA512 (clientSecret, stringToSign) dengan formula stringToSign = HTTPMethod +”:“+ EndpointUrl +\":\"+ AccessToken +\":“+ Lowercase(HexEncode(SHA-256(minify(RequestBody))))+ \":“ + TimeStamp","required":true,"schema":{"type":"string"}},"authorization":{"name":"Authorization","required":true,"in":"header","description":"String starts with keyword “Bearer ” followed by token B2B (e.g. Bearer eyJraWQiOi...Jzc29zIiwiY)","schema":{"type":"string"}},"channelId":{"name":"CHANNEL-ID","in":"header","description":"Channel ID for QRIS please fill with H2H (Host-To-Host)","required":true,"schema":{"type":"string"}}},"schemas":{"DecodeQrisRequest":{"type":"object","required":["partnerReferenceNo","qrContent","scanTime"],"properties":{"partnerReferenceNo":{"type":"string","maxLength":64,"description":"Transaction ID from partners"},"qrContent":{"type":"string","maxLength":512,"description":"QRIS content. QRIS generated by DOKU or other PJSP. Can be dynamic or static QRIS."},"scanTime":{"type":"string","description":"The time when the QRIS scanned by the User, ISO 8601 Format"}}},"DecodeQrisResponse":{"type":"object","required":["responseCode","responseMessage","merchantInfos","currency","transactionAmount"],"properties":{"responseCode":{"type":"string"},"postalCode":{"type":"string"},"responseMessage":{"type":"string"},"referenceNo":{"type":"string"},"partnerReferenceNo":{"type":"string","maxLength":64},"merchantName":{"type":"string"},"transactionAmount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","pattern":"^\\d{1,16}\\.00$"},"currency":{"type":"string"}}},"merchantInfos":{"type":"array","description":"Merchant account information","items":{"required":["merchantPAN","acquirerName"],"properties":{"merchantPAN":{"type":"string","maxLength":19,"description":"Merchant PAN Mandatory if using Host to host mode"},"acquirerName":{"type":"string","maxLength":50,"description":"Merchant PAN Mandatory if using Host to host mode"}}}},"feeAmount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","pattern":"^\\d{1,16}\\.00$"},"currency":{"type":"string"}}},"additionalInfo":{"type":"object","required":["pointOfInitiationMethod","pointOfInitiationMethodDescription","feeType","feeTypeDescription"],"properties":{"pointOfInitiationMethod":{"type":"string"},"pointOfInitiationMethodDescription":{"type":"string"},"feeType":{"type":"string"},"feeTypeDescription":{"type":"string"}}}}}}}}
```

### 5. Payment QRIS

You need to hit this API through your Backend:

#### API Endpoint

| Environment    | Endpoint                                                      |
| -------------- | ------------------------------------------------------------- |
| HTTP Method    | POST                                                          |
| API Sandbox    | [https://api-sandbox.doku.com](https://api-sandbox.doku.com/) |
| API Production | [https://api.doku.com](https://api.doku.com/)                 |
| Path           | `/snap-adapter/b2b2c/v1.0/qr/qr-mpm-payment`                  |

Here is the sample request header, request body and response body for payment QRIS:

## POST /snap-adapter/b2b2c/v1.0/qr/qr-mpm-payment

> POST Payment QRIS

```json
{"openapi":"3.0.0","info":{"title":"doku-wallet-snap-api-qris","version":"1.0.0"},"tags":[{"name":"QRIS-PARTNER","description":"QRIS operations B2B2C"}],"servers":[{"url":"https://api-sandbox.doku.com"}],"paths":{"/snap-adapter/b2b2c/v1.0/qr/qr-mpm-payment":{"post":{"tags":["QRIS-PARTNER"],"summary":"POST Payment QRIS","operationId":"qr-mpm-payment","parameters":[{"$ref":"#/components/parameters/xPartnerId"},{"$ref":"#/components/parameters/xTimeStamp"},{"$ref":"#/components/parameters/xExternalId"},{"$ref":"#/components/parameters/xSignature"},{"$ref":"#/components/parameters/authorization"},{"$ref":"#/components/parameters/authorization-customer"},{"$ref":"#/components/parameters/channelId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentQrisRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentQrisResponse"}}}}}}}},"components":{"parameters":{"xPartnerId":{"name":"X-PARTNER-ID","in":"header","description":"Client Id for merchant that generated by DOKU","required":true,"schema":{"type":"string"}},"xTimeStamp":{"name":"X-TIMESTAMP","in":"header","description":"Client's current local time with format YYYY-MM-DDTHH:mm:ssZD","required":true,"schema":{"type":"string"}},"xExternalId":{"name":"X-EXTERNAL-ID","in":"header","description":"Numeric String. Reference number that should be unique in the same day (Request Id)","required":true,"schema":{"type":"string"}},"xSignature":{"name":"X-SIGNATURE","in":"header","description":"Symmetric Signature with Get Token (Default)HMAC_SHA512 (clientSecret, stringToSign) dengan formula stringToSign = HTTPMethod +”:“+ EndpointUrl +\":\"+ AccessToken +\":“+ Lowercase(HexEncode(SHA-256(minify(RequestBody))))+ \":“ + TimeStamp","required":true,"schema":{"type":"string"}},"authorization":{"name":"Authorization","required":true,"in":"header","description":"String starts with keyword “Bearer ” followed by token B2B (e.g. Bearer eyJraWQiOi...Jzc29zIiwiY)","schema":{"type":"string"}},"authorization-customer":{"name":"Authorization-Customer","in":"header","description":"String starts with keyword “Bearer ” followed by token B2B2C (e.g. Bearer eyJraWQiOi...Jzc29zIiwiY)","required":true,"schema":{"type":"string"}},"channelId":{"name":"CHANNEL-ID","in":"header","description":"Channel ID for QRIS please fill with H2H (Host-To-Host)","required":true,"schema":{"type":"string"}}},"schemas":{"PaymentQrisRequest":{"type":"object","required":["partnerReferenceNo","amount","value","currency","qrContent"],"properties":{"partnerReferenceNo":{"type":"string"},"amount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","pattern":"^\\d{1,16}\\.00$"},"currency":{"type":"string"}}},"feeAmount":{"description":"When decode response consist of fee amount then fee amount becomes required","type":"object","required":["value","currency"],"properties":{"value":{"type":"string","pattern":"^\\d{1,16}\\.00$"},"currency":{"type":"string"}}},"additionalInfo":{"type":"object","required":["qrContent"],"properties":{"qrContent":{"type":"string"}}}}},"PaymentQrisResponse":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"},"referenceNo":{"type":"string"},"partnerReferenceNo":{"type":"string"},"amount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","pattern":"^\\d{1,16}\\.00$"},"currency":{"type":"string"}}},"feeAmount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"string","pattern":"^\\d{1,16}\\.00$"},"currency":{"type":"string"}}},"additionalInfo":{"type":"object","required":["approvalCode"],"properties":{"approvalCode":{"type":"string"}}}}}}}}
```

### 6. Cancel QRIS

You need to hit this API through your Backend:

#### API Endpoint

| Environment    | Endpoint                                                      |
| -------------- | ------------------------------------------------------------- |
| HTTP Method    | POST                                                          |
| API Sandbox    | [https://api-sandbox.doku.com](https://api-sandbox.doku.com/) |
| API Production | [https://api.doku.com](https://api.doku.com/)                 |
| Path           | `/snap-adapter/b2b/v1.0/qr/qr-expire`                         |

Here is the sample request header, request body and response body for payment QRIS:

## POST /snap-adapter/b2b/v1.0/qr/qr-expire

> POST Cancel QRIS

```json
{"openapi":"3.0.0","info":{"title":"doku-wallet-snap-api-qris","version":"1.0.0"},"tags":[{"name":"QRIS","description":"QRIS operations B2B"}],"servers":[{"url":"https://api-sandbox.doku.com"}],"paths":{"/snap-adapter/b2b/v1.0/qr/qr-expire":{"post":{"tags":["QRIS"],"summary":"POST Cancel QRIS","operationId":"qr-mpm-cancel","parameters":[{"$ref":"#/components/parameters/xPartnerId"},{"$ref":"#/components/parameters/xTimeStamp"},{"$ref":"#/components/parameters/xExternalId"},{"$ref":"#/components/parameters/xSignature"},{"$ref":"#/components/parameters/authorization"},{"$ref":"#/components/parameters/channelId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QrisExpireRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QrisExpireResponse"}}}}}}}},"components":{"parameters":{"xPartnerId":{"name":"X-PARTNER-ID","in":"header","description":"Client Id for merchant that generated by DOKU","required":true,"schema":{"type":"string"}},"xTimeStamp":{"name":"X-TIMESTAMP","in":"header","description":"Client's current local time with format YYYY-MM-DDTHH:mm:ssZD","required":true,"schema":{"type":"string"}},"xExternalId":{"name":"X-EXTERNAL-ID","in":"header","description":"Numeric String. Reference number that should be unique in the same day (Request Id)","required":true,"schema":{"type":"string"}},"xSignature":{"name":"X-SIGNATURE","in":"header","description":"Symmetric Signature with Get Token (Default)HMAC_SHA512 (clientSecret, stringToSign) dengan formula stringToSign = HTTPMethod +”:“+ EndpointUrl +\":\"+ AccessToken +\":“+ Lowercase(HexEncode(SHA-256(minify(RequestBody))))+ \":“ + TimeStamp","required":true,"schema":{"type":"string"}},"authorization":{"name":"Authorization","required":true,"in":"header","description":"String starts with keyword “Bearer ” followed by token B2B (e.g. Bearer eyJraWQiOi...Jzc29zIiwiY)","schema":{"type":"string"}},"channelId":{"name":"CHANNEL-ID","in":"header","description":"Channel ID for QRIS please fill with H2H (Host-To-Host)","required":true,"schema":{"type":"string"}}},"schemas":{"QrisExpireRequest":{"type":"object","required":["partnerReferenceNo","referenceNo","merchantId"],"properties":{"partnerReferenceNo":{"type":"string","maxLength":64,"description":"Transaction ID from partners when Generate QRIS | Mandatory | min length: 1 | max length: 64 "},"referenceNo":{"type":"string","maxLength":64,"description":"Transaction ID from partners when Generate QRIS | Mandatory | min length: 1 | max length: 64 "},"merchantId":{"type":"string","maxLength":64,"description":"Credential mall ID from DOKU | Mandatory | min length: 1 | max length: 64"},"reason":{"type":"string","maxLength":128,"description":"Cancel Reason | Mandatory | min length: 1 | max length: 128"}}},"QrisExpireResponse":{"type":"object","properties":{"responseCode":{"type":"string"},"responseMessage":{"type":"string"},"partnerReferenceNo":{"type":"string","maxLength":64},"referenceNo":{"type":"string","maxLength":64},"expiredDate":{"type":"string"}}}}}}
```


# DOKU MCP Server

Set up DOKU MCP server to integrate DOKU APIs with your AI tools

{% hint style="info" %}
Learn more about DOKU MCP Server use cases [here](https://docs.doku.com/accept-payments/integration-tools/doku-mcp-server?utm_source=developers)
{% endhint %}

This guide provides end-to-end instructions for integrating with the **DOKU MCP Server**, covering system requirements, a step-by-step integration process, and detailed documentation of all available tools. Each tool is described by its purpose, recommended use cases, and relevance to common payment flows.

## Requirements

Before you start, make sure you fulfill the following requirements:

1. Become a DOKU Merchant (follow the guide [here](https://docs.doku.com/get-started/create-account?utm_source=developers))
2. Prepare an AI assistant (e.g. Visual Studio Code, Claude, or any AI assistant of your choice)

***

## Integration Guide

The steps below explain how to connect your AI assistant or agent environment to the DOKU MCP Server.&#x20;

### Step 1: Generate API Keys

You can access your **Test Mode** credentials directly at [sandbox.doku.com](https://sandbox.doku.com). For **Live Mode** production access, please [complete this request form](https://forms.doku.com/agentic-payments?utm_source=developers) so our team can assist with the necessary onboarding and verification.

### Step 2: Encode API Keys

After receiving your API key, you must convert it to Base64 format for use in the MCP `Authorization` header. Run the following command:

```
base64 <<< api_key_xxxxxxxxxx:
```

{% hint style="info" %}
**Important Note:**&#x20;

1. Do not remove the `:` separator.&#x20;
2. Save the encoded string as you’ll use it in the next step.
   {% endhint %}

### Step 3: Configure Your AI Assistant

Once you have your Base64-encoded token, configure your AI assistant or agent framework to connect to the DOKU MCP Server.

You can integrate using any of the following supported environments:

1. Visual Studio Code (MCP Extension)
2. Cursor
3. Claude Code / Claude Desktop
4. n8n
5. Python Library (MCP Client SDK)
   * LangChain
   * StrandsAgent
6. Javascript Library (MCP Client SDK)
   * LangChain

Each platform requires you to insert your Base64-encoded credentials and specify the MCP Server endpoint. Refer to the individual setup guides for platform-specific configuration steps.

<details>

<summary><strong>Visual Studio Code</strong></summary>

<figure><img src="/files/t6p1Msw2H5W2ACUAQT8w" alt=""><figcaption></figcaption></figure>

1. Open **Command Palette** and type **MCP: Open User Configuration**
2. Paste the following configuration:

```visual-basic
{
    "servers": {
        "doku-mcp-server": {
            "type": "http",
            "url": "https://api-sandbox.doku.com/doku-mcp-server/mcp",
            "headers": {
                "Client-Id": "{doku-client-id}",
                "Authorization": "Basic {base64.encode(doku_api_key:)}"
            }
        }
    }
}
```

4. Replace `{doku-client-id}` and `{base64-encoded-token}` with your values.
5. Verify by opening Command Palette → **MCP: Show Installed Servers** → select **doku-mcp-server**. If successful, you’ll see logs confirming the connection and available tools.
6. Restart your AI assistant app. In the chat window, switch to **Agent Mode**, then ask:

> *Show me the available DOKU tools*

If connected, the server will list all MCP tools (e.g., checkout, payment link, QRIS). You can then try calling a tool such as `checkout` to confirm everything works.

</details>

<details>

<summary><strong>Cursor</strong></summary>

1. Open **Settings** → **Cursor Settings**

<figure><img src="https://t9018384872.p.clickup-attachments.com/t9018384872/e940c292-4e82-4b9c-b0c7-d751d2137c85/Screenshot%202026-03-31%20at%205.36.14%E2%80%AFPM.png?authz_token=eyJhbGciOiJIUzI1NiIsImtpZCI6ImFybjphd3M6a21zOmFwLXNvdXRoZWFzdC0xOjUxNDMwODY0MTU5MjphbGlhcy9hdHRhY2htZW50cy9hdXRoLzEiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOjg5NTUwOTA2LCJleHAiOjE3Nzc1Mzg1ODAsInN1YiI6Imh0dHBzOi8vdDkwMTgzODQ4NzIucC5jbGlja3VwLWF0dGFjaG1lbnRzLmNvbS90OTAxODM4NDg3Mi9lOTQwYzI5Mi00ZTgyLTRiOWMtYjBjNy1kNzUxZDIxMzdjODUvU2NyZWVuc2hvdCUyMDIwMjYtMDMtMzElMjBhdCUyMDUuMzYuMTQlRTIlODAlQUZQTS5wbmciLCJtYXhVc2FnZSI6MSwicmFuZCI6InRRWGEifQ.kvzTWnTgeCDd2kZkVdO2f64lfFlFl4qFdJhlVEZoj54" alt=""><figcaption></figcaption></figure>

2. Open **Tools & MCP** tab

<figure><img src="https://t9018384872.p.clickup-attachments.com/t9018384872/b50922ea-7958-4be8-9e34-7692d4f47418/Screenshot%202026-03-31%20at%205.37.17%E2%80%AFPM.png?authz_token=eyJhbGciOiJIUzI1NiIsImtpZCI6ImFybjphd3M6a21zOmFwLXNvdXRoZWFzdC0xOjUxNDMwODY0MTU5MjphbGlhcy9hdHRhY2htZW50cy9hdXRoLzEiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOjg5NTUwOTA2LCJleHAiOjE3Nzc1Mzg1NzksInN1YiI6Imh0dHBzOi8vdDkwMTgzODQ4NzIucC5jbGlja3VwLWF0dGFjaG1lbnRzLmNvbS90OTAxODM4NDg3Mi9iNTA5MjJlYS03OTU4LTRiZTgtOWUzNC03NjkyZDRmNDc0MTgvU2NyZWVuc2hvdCUyMDIwMjYtMDMtMzElMjBhdCUyMDUuMzcuMTclRTIlODAlQUZQTS5wbmciLCJtYXhVc2FnZSI6MSwicmFuZCI6IlNWZ1UifQ.i3Gi5hu2hlwqJ_L0KA__jMU4jSohJ4rx7RnUGEP0Yyg" alt=""><figcaption></figcaption></figure>

3. Click **Add Custom MCP**. A new file will be opened called mcp.json, where you can paste your configuration as such:

```
{
    "mcpServers": {
        "doku-mcp-server-sandbox": {
            "url": "https://mcp.doku.com/mcp",
            "headers": {
                "client-id": "BRN-0254-1761535638886",
                "Authorization": "Basic ************"
            }
        }
    }
}
```

4. If done correctly, all tools provided by DOKU MCP Server will be visible

<figure><img src="https://t9018384872.p.clickup-attachments.com/t9018384872/33edf6d9-257e-4b62-ae44-6f5a436d6095/Screenshot%202026-03-31%20at%205.38.15%E2%80%AFPM.png?authz_token=eyJhbGciOiJIUzI1NiIsImtpZCI6ImFybjphd3M6a21zOmFwLXNvdXRoZWFzdC0xOjUxNDMwODY0MTU5MjphbGlhcy9hdHRhY2htZW50cy9hdXRoLzEiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOjg5NTUwOTA2LCJleHAiOjE3Nzc1Mzg1NzcsInN1YiI6Imh0dHBzOi8vdDkwMTgzODQ4NzIucC5jbGlja3VwLWF0dGFjaG1lbnRzLmNvbS90OTAxODM4NDg3Mi8zM2VkZjZkOS0yNTdlLTRiNjItYWU0NC02ZjVhNDM2ZDYwOTUvU2NyZWVuc2hvdCUyMDIwMjYtMDMtMzElMjBhdCUyMDUuMzguMTUlRTIlODAlQUZQTS5wbmciLCJtYXhVc2FnZSI6MSwicmFuZCI6Ill4OGMifQ.LZp_hBtw1DTMBVaj6hkIuJTmxIpq5JGbmUumgW6qHpg" alt=""><figcaption></figcaption></figure>

5. Test the tools directly on Cursor's chat interface.

<figure><img src="https://t9018384872.p.clickup-attachments.com/t9018384872/5303da86-3dcc-4407-9e54-681832476019/Screenshot%202026-04-01%20at%203.53.40%E2%80%AFPM.png?authz_token=eyJhbGciOiJIUzI1NiIsImtpZCI6ImFybjphd3M6a21zOmFwLXNvdXRoZWFzdC0xOjUxNDMwODY0MTU5MjphbGlhcy9hdHRhY2htZW50cy9hdXRoLzEiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOjg5NTUwOTA2LCJleHAiOjE3Nzc1Mzg1NzYsInN1YiI6Imh0dHBzOi8vdDkwMTgzODQ4NzIucC5jbGlja3VwLWF0dGFjaG1lbnRzLmNvbS90OTAxODM4NDg3Mi81MzAzZGE4Ni0zZGNjLTQ0MDctOWU1NC02ODE4MzI0NzYwMTkvU2NyZWVuc2hvdCUyMDIwMjYtMDQtMDElMjBhdCUyMDMuNTMuNDAlRTIlODAlQUZQTS5wbmciLCJtYXhVc2FnZSI6MSwicmFuZCI6IkFESzYifQ.FszwPici6Hagd1xADb7SyudBawBezzho5QOCA36tZSw" alt=""><figcaption></figcaption></figure>

</details>

<details>

<summary><strong>Claude Code / Claude Desktop</strong></summary>

Claude Code supports two integration methods:

1. Claude CLI
   * Recommended for direct MCP connections
2. Claude Desktop App
   * Requires a proxy because custom headers are not yet supported

***

#### Claude CLI

Claude CLI supports MCP servers over HTTP and allows sending custom headers, making it the simplest way to connect to DOKU MCP Server.

Run the following command in your terminal:

```bash
claude mcp add \
  --transport http \
  doku-mcp-server https://api-sandbox.doku.com/doku-mcp-server/mcp" \
  --header "Client-Id: Your Brand ID" \
  --header "Authorization: Your Encoded API Keys"
```

This command does the following actions:

* Registers a new MCP server named **doku-mcp-server**
* Connects via **HTTP transport**
* Sends the required authentication headers:
  * `Client-Id`
  * `Authorization: Basic <base64-encoded-api-key:>`

After running the command, Claude CLI will automatically load and list the available DOKU MCP tools.

***

#### Claude Desktop

Claude Desktop App currently does not support custom HTTP headers for MCP connections. Since the DOKU MCP Server requires headers for authentication, you must use a small Node.js proxy that:

* Connects to DOKU MCP Server over HTTP
* Injects the required headers
* Exposes the MCP server to Claude Desktop using **STDIO protocol**

**Step 1: Clone DOKU MCP Proxy**

Clone the proxy package from the following repository:

> **GitHub**: <https://github.com/PTNUSASATUINTIARTHA-DOKU/doku-mcp-proxy>

After downloading, unzip the folder to any directory of your choice.

***

**Step 2: Configure the Proxy**

Open the file:\
`doku-mcp-proxy/index.js`

Update the configuration block with your credentials:

```js
const DOKU_CONFIG = {
  url: 'https://api-sandbox.doku.com/doku-mcp-server/mcp"',
  headers: {
    'Client-Id': 'Your Brand ID',
    'Authorization': 'Your Encoded API Keys',
    'Content-Type': 'application/json',
    'Accept': 'application/json, text/event-stream'
  }
};
```

Make sure your `Authorization` value is the **Base64-encoded `<api-key>:` string**.

***

**Step 3: Install Dependencies**

Go to the proxy folder and run:

```bash
npm install
```

This installs the MCP proxy runtime dependencies.

***

**Step 4: Configure Claude Desktop**

1. Open **Claude Desktop**
2. Go to **Settings → Developer → Edit Config**
3. This opens the file: `claude_desktop_config.json`

Replace or add the following configuration:

```json
{
  "mcpServers": {
    "doku-mcp-local": {
      "command": "/your-node-path/bin/node",
      "args": [
        "/your-path-to/doku-mcp-proxy/index.js"
      ]
    }
  }
}
```

<figure><img src="https://t9018384872.p.clickup-attachments.com/t9018384872/e951fd0f-d42f-424a-b71d-81582298e6e6/Screenshot%202025-12-04%20at%203.13.16%E2%80%AFPM.png" alt=""><figcaption></figcaption></figure>

Notes:

* Replace `"/your-node-path/bin/node"` with your actual Node.js binary path\
  (For macOS with nvm it's something like `/Users/<user>/.nvm/versions/node/v18.x.x/bin/node`)
* Replace the project path with where you extracted the proxy

***

**Step 5: Restart Claude Desktop**

After restarting:

* Go to **Settings → Developer → MCP Servers**
* You should now see **doku-mcp-local** listed
* Claude Desktop will automatically load DOKU MCP tools

If everything is configured properly, you can now call DOKU MCP tools directly inside Claude Desktop.

</details>

<details>

<summary><strong>n8n</strong></summary>

<figure><img src="/files/29y111ebVOdv6pSsxw2x" alt=""><figcaption></figcaption></figure>

With n8n, you can integrate the DOKU MCP Server and expose your AI-powered agent through:

1. Web Browser / API (via n8n workflow trigger)
2. WhatsApp (using WhatsApp Business Cloud and n8n)

Both approaches allow your AI agent to call DOKU MCP tools directly from n8n workflows.

***

#### Web Browser / API

1. Go to **Settings** → **Community Nodes** (requires Admin role)
2. Click **Install**
3. Enter `n8n-nodes-doku-mcp-client` in the **NPM Package Name** field
4. Agree to the terms and conditions, and then click **Install**
5. Check that `n8n-nodes-doku-mcp-client` has been successfully installed

<figure><img src="/files/oFll8LsHnfNU3NNyImAI" alt=""><figcaption></figcaption></figure>

6. Create your workflow using a **Chat Trigger**, **AI Agent**, and an **LLM** already integrated with n8n<br>

<figure><img src="/files/6Ck99a3DqojjKHdjxRi1" alt=""><figcaption></figcaption></figure>

7. Open the **Tools** panel and select **DOKU MCP Client Tool**
8. Fill in all the required form fields
   1. Endpoint
      * Production: <https://mcp.doku.com/mcp>
      * Sandbox: <https://api-sandbox.doku.com/doku-mcp-server/mcp>
   2. Server Transport: HTTP Streamable
   3. Client ID: Your DOKU Client ID (BRN-xxxxx)
   4. API Key: Your DOKU API Key (api\_key\_xxxx)
   5. Tools to Include: Default is All, or you may specify only the DOKU MCP tools the agent should use

Once saved, your n8n workflow is fully connected to the **DOKU MCP Server**.

***

#### WhatsApp

**Step 1: Configure the WhatsApp Trigger Node**

1. Add a **WhatsApp Business Cloud Trigger** node
   * Search “WhatsApp” in the node list
2. Set the **Trigger Event** to **On messages**
3. Create the required credentials (first-time setup):
   * **Facebook App Client ID**
   * **Facebook App Client Secret**\
     Follow the steps in the official n8n documentation:\
     <https://docs.n8n.io/integrations/builtin/credentials/whatsapp/>

This node will fire whenever a new WhatsApp message is received.

***

**Step 2: Configure the AI Agent Node**

1. Add an **AI Agent** node and connect it after the WhatsApp Trigger
2. Set the prompt source to use the incoming message:
   * Change **Prompt (User Message) → Source** to **Expression**
   * Set the value to:

     ```
     {{ $json.messages[0].text.body }}
     ```

This extracts the user’s message from the WhatsApp webhook payload.

***

**Step 3: Add a Simple Memory Node**

This node allows the AI agent to remember previous messages in the same conversation.

1. Add a **Simple Memory** node
2. Connect it between the WhatsApp Trigger and AI Agent (or wherever memory is needed)
3. Set **Session ID** to uniquely identify each WhatsApp user:

   ```
   {{ $json.contacts[0].wa_id }}
   ```
4. (Optional) Adjust **Context Window Length**
   * Default: 5
   * Controls how many previous turns the AI agent will remember

***

**Step 4: Configure the WhatsApp Send Message Node**

This node sends the AI-generated reply back to the user

1. Add a **WhatsApp → Send Message** node
2. Create or select the required credentials:
   * **Access Token**
   * **Business Account ID**\
     Documentation:\
     <https://docs.n8n.io/integrations/builtin/credentials/whatsapp/>
3. Configure the message:

| Setting                    | Value                                                                                        |
| -------------------------- | -------------------------------------------------------------------------------------------- |
| **Resource**               | Message                                                                                      |
| **Operation**              | Send                                                                                         |
| **Recipient Phone Number** | <p>Expression:<br><code>{{ $('WhatsApp Trigger').item.json.contacts\[0].wa\_id }}</code></p> |
| **Text Body**              | <p>Expression:<br><code>{{ $json.output }}</code> (content generated by the AI Agent)</p>    |

</details>

<details>

<summary><strong>Python Library</strong></summary>

DOKU MCP Server can be integrated with Python using:

1. LangChain
2. StrandsAgent

Both approaches allow you to load DOKU MCP tools dynamically and let your LLM call them during reasoning.

***

#### Langchain

**Step 1: Create `requirements.txt`**

```txt
# FastAPI and server
fastapi[standard]==0.119.1
uvicorn[standard]==0.38.0

# OpenAI and LangChain
openai>=1.54.0,<2.0.0
langchain==0.3.9
langchain-openai==0.2.8
langchain-community==0.3.9
langchain-core>=0.3.21

# MCP Client SDK
mcp>=1.1.0
httpx>=0.27
httpx-sse>=0.4

# Environment variables
python-dotenv==1.0.1

# Pydantic (FastAPI dependency)
pydantic==2.12.3
```

***

**2. Create `.env`**

```bash
# OpenAI API Key
OPENAI_API_KEY=your-openai-api-key-here

# DOKU MCP Server Configuration
DOKU_MCP_URL=https://api-uat.doku.com/doku-mcp-server/mcp
DOKU_CLIENT_ID=your-client-id-here
DOKU_AUTHORIZATION=Basic your-base64-encoded-api-key:
```

Notes:\
`DOKU_AUTHORIZATION` must include the trailing colon (`:`) before Base64 encoding.

***

**Step 3: Create `main.py`**

```python
import os
from typing import Union
from contextlib import asynccontextmanager

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.tools import tool as langchain_tool
from httpx import AsyncClient

load_dotenv()

# Global MCP tools
mcp_tools = []

# DOKU MCP configuration
DOKU_URL = os.getenv("DOKU_MCP_URL")
DOKU_HEADERS = {
    "client-id": os.getenv("DOKU_CLIENT_ID"),
    "authorization": os.getenv("DOKU_AUTHORIZATION"),
    "content-type": "application/json",
    "accept": "application/json, text/event-stream"
}
PROTOCOL_VERSION = None


async def call_mcp_rpc(method: str, params: dict = None, request_id: int = 1) -> dict:
    """Call Doku MCP server via JSON-RPC."""
    headers = DOKU_HEADERS.copy()
    if PROTOCOL_VERSION:
        headers["mcp-protocol-version"] = PROTOCOL_VERSION

    payload = {
        "jsonrpc": "2.0",
        "id": request_id,
        "method": method,
        "params": params or {}
    }

    async with AsyncClient(timeout=30.0) as client:
        response = await client.post(DOKU_URL, headers=headers, json=payload)
        response.raise_for_status()
        return response.json()


@asynccontextmanager
async def lifespan(app: FastAPI):
    """Initialize MCP tools at startup."""
    global mcp_tools, PROTOCOL_VERSION
    import json

    print("=" * 60)
    print("Connecting to DOKU MCP Server…")
    print(f"URL: {DOKU_URL}")
    print("=" * 60)

    try:
        init_result = await call_mcp_rpc("initialize", {}, 0)
        PROTOCOL_VERSION = init_result["result"]["protocolVersion"]
        server_info = init_result["result"]["serverInfo"]

        print(f"✓ Connected: {server_info['name']} v{server_info['version']}")
        print(f"Protocol: {PROTOCOL_VERSION}")

        tools_result = await call_mcp_rpc("tools/list", {}, 1)
        tools_list = tools_result["result"]["tools"]

        print(f"\n✓ Loaded {len(tools_list)} tools:")

        for mcp_tool in tools_list:
            name = mcp_tool["name"]
            desc = mcp_tool.get("description", "")

            print(f"  - {name}")

            def make_tool(name: str, description: str):
                @langchain_tool(name)
                async def call_tool(tool_request: str) -> str:
                    result = await call_mcp_rpc(
                        "tools/call",
                        {"name": name, "arguments": {"toolRequest": tool_request}},
                        2
                    )
                    return json.dumps(result.get("result", {}), indent=2)

                call_tool.description = description
                return call_tool

            mcp_tools.append(make_tool(name, desc))

        print("=" * 60)

    except Exception as e:
        print(f"Error: {e}")

    yield


app = FastAPI(lifespan=lifespan)


def get_llm():
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("Missing OPENAI_API_KEY")
    return ChatOpenAI(api_key=api_key, model="gpt-3.5-turbo")


class ChatRequest(BaseModel):
    message: str
    model: str = "gpt-3.5-turbo"
    max_tokens: int = 150


class ChatResponse(BaseModel):
    response: str
    model: str
    usage: dict


@app.post("/chat", response_model=ChatResponse)
async def chat(request: ChatRequest):
    try:
        llm = get_llm()

        if mcp_tools:
            prompt = ChatPromptTemplate.from_messages([
                ("system", "You are a helpful assistant with access to DOKU MCP tools."),
                ("human", "{input}"),
                ("placeholder", "{agent_scratchpad}")
            ])

            agent = create_tool_calling_agent(llm, mcp_tools, prompt)
            executor = AgentExecutor(agent=agent, tools=mcp_tools, verbose=True)

            result = await executor.ainvoke({"input": request.message})
            output = result.get("output", "No response")
        else:
            result = await llm.ainvoke(request.message)
            output = result.content

        return ChatResponse(
            response=output,
            model=request.model,
            usage={"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
        )

    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))


if __name__ == "__main__":
    import uvicorn
    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)
```

***

**Step 4: Run Application**

1. Install Python 3.11

```bash
brew install python@3.11
```

2. Create Virtual Environment

```bash
python3.11 -m venv .venv
source .venv/bin/activate
```

3. Install Dependencies

```bash
pip install -r requirements.txt
```

4. Run FastAPI App

```bash
python main.py
```

***

**Step 5: Test Using curl**

```bash
curl -L 'localhost:8000/chat' \
  -H 'Content-Type: application/json' \
  -d '{"message": "create checkout with amount 20000"}'
```

***

#### StrandsAgent

**Step 1: Create `requirements.txt`**

```txt
# FastAPI and server
fastapi[standard]==0.119.1
uvicorn[standard]==0.38.0

# OpenAI and Strands
openai>=1.54.0,<2.0.0
strands-agents>=1.1.0

# MCP Client SDK
mcp>=1.1.0
httpx>=0.27

# Environment variables
python-dotenv==1.0.1

# Pydantic
pydantic==2.12.3
```

***

**Step 2: Create `.env`**

```bash
OPENAI_API_KEY=your-openai-api-key-here
DOKU_MCP_URL=https://api-uat.doku.com/doku-mcp-server/mcp
DOKU_CLIENT_ID=your-client-id-here
DOKU_AUTHORIZATION=Basic your-base64-encoded-api-key:
```

***

**Step 3: Create `main.py`**

```python
import os
import json
from contextlib import asynccontextmanager

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from dotenv import load_dotenv

from strands import Agent
from strands.models.openai import OpenAIModel
from strands.tools.mcp import MCPClient
from mcp.client.streamable_http import streamablehttp_client

load_dotenv()

mcp_client = None
agent = None

DOKU_URL = os.getenv("DOKU_MCP_URL")
DOKU_HEADERS = {
    "client-id": os.getenv("DOKU_CLIENT_ID"),
    "authorization": os.getenv("DOKU_AUTHORIZATION"),
    "content-type": "application/json",
    "accept": "application/json, text/event-stream"
}


@asynccontextmanager
async def lifespan(app: FastAPI):
    global mcp_client, agent

    print("=" * 60)
    print("Connecting to DOKU MCP Server (Strands)…")
    print("=" * 60)

    try:
        mcp_client = MCPClient(
            lambda: streamablehttp_client(
                url=DOKU_URL,
                headers=DOKU_HEADERS
            )
        )

        with mcp_client:
            tools = mcp_client.list_tools_sync()

            print(f"✓ Connected. Loaded {len(tools)} tools:")

            for t in tools:
                print(f"  - {t.tool_name}: {t.tool_spec.get('description', '')}")

            model = get_openai_model()
            agent = Agent(
                model=model,
                tools=tools,
                system_prompt="You are a helpful assistant with access to DOKU MCP tools."
            )

    except Exception as e:
        print(f"Error: {e}")

    yield

    mcp_client = None
    agent = None


app = FastAPI(lifespan=lifespan)


def get_openai_model():
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY is not set")

    return OpenAIModel(
        model_id="gpt-3.5-turbo",
        client_args={"api_key": api_key}
    )


class ChatRequest(BaseModel):
    message: str


class ChatResponse(BaseModel):
    response: str


@app.post("/chat", response_model=ChatResponse)
async def chat(request: ChatRequest):
    global agent, mcp_client

    if not agent or not mcp_client:
        raise HTTPException(500, "Agent not initialized")

    try:
        with mcp_client:
            tools = mcp_client.list_tools_sync()
            session_agent = Agent(
                model=get_openai_model(),
                tools=tools,
                system_prompt="You are a helpful assistant with access to DOKU MCP tools."
            )

            result = await session_agent.invoke_async(request.message)

        return ChatResponse(response=str(result))

    except Exception as e:
        raise HTTPException(500, str(e))


if __name__ == "__main__":
    import uvicorn
    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)
```

***

**Step 4: Run Application**

```bash
brew install python@3.11
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py
```

***

**Step 5: Test with curl**

```bash
curl -L 'localhost:8000/chat' \
  -H 'Content-Type: application/json' \
  -d '{"message":"create checkout with amount 20000"}'
```

</details>

<details>

<summary><strong>Javascript Library</strong></summary>

DOKU MCP Server can be integrated with Javascript (JS) using LangChain.

***

#### Langchain

**Step 1: Create  `package.json`** &#x20;

```json
{
  "name": "demo-mcp-client-langchain-js",
  "version": "1.0.0",
  "description": "LangChain JS demo with DOKU MCP server integration",
  "main": "server.js",
  "type": "module",
  "scripts": {
    "start": "node server.js",
    "dev": "node --watch server.js"
  },
  "dependencies": {
    "express": "^4.18.2",
    "dotenv": "^16.3.1",
    "axios": "^1.6.0",
    "langchain": "^0.2.0",
    "@langchain/openai": "^0.2.0",
    "@langchain/core": "^0.2.0"
  },
  "engines": {
    "node": ">=18.0.0"
  },
  "license": "MIT"
}

```

This project requires **Node.js 18+** because LangChain uses native `fetch` and modern ESM.

***

**Step 2: Create  `.env`**

```
# Environment Variables
OPENAI_API_KEY=your_openai_api_key_here
DOKU_MCP_URL=https://api-sandbox.doku.com/doku-mcp-server/mcp
DOKU_CLIENT_ID=your_doku_client_id
DOKU_AUTHORIZATION=Basic your-base64-encoded-api-key
PORT=3000
```

Notes:

* `DOKU_AUTHORIZATION` **must be** the Base64-encoded `<api-key>:` value\
  (including the trailing colon before encoding).
* Never commit `.env` to source control.

***

**Step 3: Create  `server.js`**

```js
import express from 'express';
import dotenv from 'dotenv';
import axios from 'axios';
import { ChatOpenAI } from '@langchain/openai';
import { AgentExecutor, createOpenAIFunctionsAgent } from 'langchain/agents';
import { ChatPromptTemplate } from '@langchain/core/prompts';
import { DynamicTool } from '@langchain/core/tools';

dotenv.config();

const app = express();
app.use(express.json());

// Global MCP tools
let mcpTools = [];

// MCP configuration
const DOKU_URL = process.env.DOKU_MCP_URL;
const DOKU_HEADERS = {
  'client-id': process.env.DOKU_CLIENT_ID,
  'authorization': process.env.DOKU_AUTHORIZATION,
  'content-type': 'application/json',
  'accept': 'application/json, text/event-stream'
};

let PROTOCOL_VERSION = null;

/**
 * Send a JSON-RPC request to DOKU MCP Server
 */
async function callMcpRpc(method, params = {}, requestId = 1) {
  const headers = { ...DOKU_HEADERS };
  if (PROTOCOL_VERSION) {
    headers['mcp-protocol-version'] = PROTOCOL_VERSION;
  }

  const payload = {
    jsonrpc: '2.0',
    id: requestId,
    method,
    params
  };

  try {
    const response = await axios.post(DOKU_URL, payload, {
      headers,
      timeout: 30000
    });
    return response.data;
  } catch (error) {
    throw new Error(`MCP RPC call failed: ${error.message}`);
  }
}

/**
 * Initialize MCP connection and load tool definitions
 */
async function initializeMcp() {
  console.log('='.repeat(60));
  console.log('Connecting to DOKU MCP Server...');
  console.log(`URL: ${DOKU_URL}`);
  console.log('='.repeat(60));

  try {
    // Initialize session
    const initResult = await callMcpRpc('initialize', {}, 0);

    PROTOCOL_VERSION = initResult.result.protocolVersion;
    const serverInfo = initResult.result.serverInfo;

    console.log(`✓ Connected: ${serverInfo.name} v${serverInfo.version}`);
    console.log(`  Protocol Version: ${PROTOCOL_VERSION}`);

    // Retrieve available tools
    const toolsResult = await callMcpRpc('tools/list', {}, 1);
    const toolsList = toolsResult.result.tools;

    console.log(`\n✓ Found ${toolsList.length} tools:`);

    // Convert MCP tool definitions into LangChain tools
    mcpTools = toolsList.map((mcpTool) => {
      console.log(`  - ${mcpTool.name}`);

      return new DynamicTool({
        name: mcpTool.name,
        description: mcpTool.description || '',
        func: async (toolRequest) => {
          try {
            const result = await callMcpRpc(
              'tools/call',
              { name: mcpTool.name, arguments: { toolRequest } },
              2
            );
            return JSON.stringify(result.result || {}, null, 2);
          } catch (err) {
            return `Error: ${err.message}`;
          }
        }
      });
    });

    console.log(`\n✓ Loaded ${mcpTools.length} MCP tools successfully`);
    console.log('='.repeat(60));

  } catch (error) {
    console.error(`Error initializing MCP: ${error.message}`);
  }
}

/**
 * Create OpenAI LLM client
 */
function getOpenAiClient(model = 'gpt-3.5-turbo') {
  const apiKey = process.env.OPENAI_API_KEY;
  if (!apiKey) {
    throw new Error('OPENAI_API_KEY environment variable is not set');
  }

  return new ChatOpenAI({
    openAIApiKey: apiKey,
    modelName: model,
    temperature: 0.7
  });
}

/**
 * Chat endpoint
 */
app.post('/chat', async (req, res) => {
  try {
    const { message, model = 'gpt-3.5-turbo' } = req.body;

    if (!message) {
      return res.status(400).json({ error: 'Message is required' });
    }

    const llm = getOpenAiClient(model);
    let responseText;

    // Use agent with MCP tools if available
    if (mcpTools.length > 0) {
      const prompt = ChatPromptTemplate.fromMessages([
        ['system', 'You are a helpful assistant with access to DOKU MCP tools. Use them when appropriate.'],
        ['human', '{input}'],
        ['placeholder', '{agent_scratchpad}']
      ]);

      const agent = await createOpenAIFunctionsAgent({
        llm,
        tools: mcpTools,
        prompt
      });

      const executor = new AgentExecutor({
        agent,
        tools: mcpTools,
        verbose: true
      });

      const result = await executor.invoke({ input: message });
      responseText = result.output ?? 'No response';
    } else {
      // Fallback: LLM only
      const result = await llm.invoke(message);
      responseText = result.content;
    }

    res.json({
      response: responseText,
      model
    });

  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

/**
 * Start the server
 */
const PORT = process.env.PORT || 3001;
initializeMcp().then(() => {
  app.listen(PORT, () => {
    console.log(`Server running on port ${PORT}`);
  });
});

```

</details>

***

## Tools

DOKU MCP server comes equipped with over 30 powerful tools, designed to handle every stage of the payment process:

### Checkout Payment

<table><thead><tr><th width="100">No.</th><th>Tool Name</th><th>Description</th><th>Use Case</th></tr></thead><tbody><tr><td>1</td><td>create_payment_link</td><td>Generate a payment link that can be used to accept payments without determining customer data</td><td>Customer inputting data (e.g. name, email, etc.) before proceeding to check out and selecting payment methods</td></tr><tr><td>2</td><td>create_checkout_link</td><td>Generate a checkout link that can be used to accept payments with customer data specified</td><td>Customer selecting payment methods and checking out immediately</td></tr></tbody></table>

#### Examples

1. **Payment Link**

<figure><img src="/files/0ANXhZ6syYOgeN0a6VMb" alt=""><figcaption><p>Tool: create_payment_link</p></figcaption></figure>

2. **Checkout**

<figure><img src="/files/nOuAvfJ7G1RpZ0Wl2HB4" alt=""><figcaption><p>Tool: create_checkout_link</p></figcaption></figure>

### Direct Payment

<table><thead><tr><th width="100">No.</th><th>Tool Name</th><th>Description</th><th>Use Case</th></tr></thead><tbody><tr><td>3</td><td>get_merchant_payment_methods</td><td>Retrieve a list of all payment methods activated for your merchant account</td><td>Checking which banks, cards, or wallets are active</td></tr><tr><td>4</td><td>generate_payment_virtual_account</td><td>Generate a Virtual Account number for bank transfer</td><td>Completing payments made via VA BCA</td></tr><tr><td>5</td><td>update_payment_virtual_acccount</td><td>Modify details of an existing Virtual Account</td><td>Extending deadline for an unpaid VA</td></tr><tr><td>6</td><td>delete_payment_virtual_account</td><td>Close or disable payment of an existing VA</td><td>Cancelling an unused VA number</td></tr><tr><td>7</td><td>generate_payment_qris</td><td>Generate a QRIS code for direct payments</td><td>Completing payments made via QRIS</td></tr><tr><td>8</td><td>generate_payment_card_auth</td><td>Perform 3D Secure (3DS) authentication for credit/debit cards requiring additional verification</td><td>When the card issuer mandates 3DS before charging</td></tr><tr><td>9</td><td>generate_payment_card_capture</td><td>Capture a previously authorized card transaction to complete the payment</td><td>For 2-step card flows where authorization and capture are separate</td></tr><tr><td>10</td><td>generate_payment_card_charge</td><td>Charge a card transaction after successful 3DS authentication</td><td>Complete payment after <code>card_auth</code> returns a valid 3DS ID</td></tr><tr><td>11</td><td>generate_payment_ovo_auth</td><td>Authenticate an OVO account before payment</td><td>Required step before processing an OVO transaction</td></tr><tr><td>12</td><td>generate_payment_ovo</td><td>Generate an OVO e-Wallet payment using the authCode from OVO e-Wallet authentication</td><td>Charge customers who choose OVO as a payment method</td></tr><tr><td>13</td><td>generate_payment_doku_ewallet_auth</td><td>Authenticate or bind a DOKU e-Wallet account before payment</td><td>Registering a DOKU e-Wallet user for future transactions</td></tr><tr><td>14</td><td>generate_payment_doku_ewallet</td><td>Charge a DOKU e-Wallet account after successful authentication</td><td>Completing payments made via DOKU e-Wallet</td></tr><tr><td>15</td><td>generate_payment_dana</td><td>Generate a DANA e-Wallet payment</td><td>Completing payments made via DANA</td></tr><tr><td>16</td><td>generate_payment_shopeepay</td><td>Generate a ShopeePay e-Wallet payment</td><td>Completing payments made via ShopeePay</td></tr><tr><td>17</td><td>generate_payment_akulaku</td><td>Generate an Akulaku PayLater or installment transaction</td><td>Completing payments made via Akulaku</td></tr><tr><td>18</td><td>generate_payment_kredivo</td><td>Generate a Kredivo PayLater or installment transaction</td><td>Completing payments made via Kredivo</td></tr><tr><td>19</td><td>generate_payment_alfagroup</td><td>Generate a payment code for cash payments at Alfamart/Alfamidi outlets</td><td>Completing payments on the counter at Alfa Group outlets</td></tr><tr><td>20</td><td>generate_payment_indomaret</td><td>Generate a payment code for cash payments at Indomaret outlets</td><td>Completing payments on the counter at Indomaret outlets</td></tr></tbody></table>

#### Examples

1. **Show Payment Methods**

<figure><img src="/files/4gU0CogMpBxIdctjq8mc" alt=""><figcaption><p>Tool: get_merchant_payment_methods</p></figcaption></figure>

2. **Virtual Account Payment**

<figure><img src="/files/RY3zSL0kH1alHvwRkegp" alt=""><figcaption><p>Tool: generate_payment_virtual_account</p></figcaption></figure>

### Transaction Utility

<table><thead><tr><th width="100">No.</th><th>Tool Name</th><th>Description</th><th>Use Case</th></tr></thead><tbody><tr><td>21</td><td>get_transaction_by_invoice_number</td><td>Retrieve the transaction details such as status, amount, and payment method used based on the invoice number</td><td>Tracking if an order has been paid</td></tr><tr><td>22</td><td>get_transaction_by_customer_name</td><td>Retrieve the transaction details such as status, amount, and payment method used based on the customer name</td><td>Viewing all orders from a particular customer</td></tr><tr><td>23</td><td>get_transaction_by_date_range</td><td>Retrieve the transaction details such as status, amount, and payment method used within a specified start and end date</td><td>Monthly reconciliation for accounting</td></tr></tbody></table>

### Customer Utility

<table><thead><tr><th width="100">No.</th><th>Tool Name</th><th>Description</th><th>Use Case</th></tr></thead><tbody><tr><td>24</td><td>add_customer</td><td>Create a new customer with details like name, email, and phone</td><td>Registering a new buyer before issuing an invoice</td></tr><tr><td>25</td><td>update_customer</td><td>Update existing customer details (e.g., phone, email)</td><td>Correcting customer contact info</td></tr><tr><td>26</td><td>delete_customer</td><td>Remove a customer from your records.</td><td>Cleaning inactive or duplicate customer data</td></tr><tr><td>27</td><td>get_customer_by_id</td><td>Retrieve customer details using their unique customer ID</td><td>Checking details of a returning customer</td></tr><tr><td>28</td><td>get_customer_by_name</td><td>Retrieve customer details using the customer’s full name or partial name</td><td>Finding a repeat customer without knowing their ID</td></tr><tr><td>29</td><td>get_customer_by_email</td><td>Retrieve customer details using the customer’s registered email address</td><td>Identifying a customer using their email contact</td></tr><tr><td>30</td><td>get_all_customers</td><td>Retrieve all customers linked to your merchant account</td><td>Viewing your full customer base</td></tr></tbody></table>

***

## Use Cases

With DOKU MCP, an AI chatbot can generate a QRIS payment request when a user wants to buy something, send the QR code, poll or receive webhook updates about payment status, and notify the user once paid; similarly, a virtual account flow can be generated, monitored, and confirmed via the agent. Visit [DOKU Docs](https://docs.doku.com/accept-payments/integration-tools/doku-mcp-server#use-cases) to learn how these tools may be used in practice.

<p align="center"><a href="https://docs.doku.com/accept-payments/integration-tools/doku-mcp-server#use-cases" class="button primary">Explore Use Cases</a></p>




---

[Next Page](/llms-full.txt/1)