Skip to main content

Virtual Accounts

Cash and Codes Bundle

Virtual Accounts is a bank transfer payment method in Indonesia that allows customers to complete payments by transferring funds to a unique, transaction-specific bank account number generated at checkout. After selecting bank transfer as the payment method, customers receive a Virtual Account (VA) number and can complete the payment through their bank's mobile app, internet banking, or ATM.

By integrating Virtual Accounts, merchants can collect payments securely and efficiently through Indonesia's banking network, providing a widely adopted and trusted payment alternative for Indonesian customers who rely on bank transfers.

This guide outlines the key concepts and implementation details required to integrate Virtual Accounts via API. It covers essential steps such as creating a payment request, displaying the VA number to the customer, and monitoring the payment status.

Requirements​

  • API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
  • Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters. See EBANX Direct for more info.

How it works​

Web and App Flow​

  1. The customer selects Bank Transfer (Virtual Account) as the payment method during checkout.
  2. A unique Virtual Account (VA) number is generated for the transaction, along with the amount and expiry time.
  3. The merchant displays the VA number and payment instructions to the customer.
  4. The customer completes the payment by logging into their bank app, internet banking, or visiting a bank ATM and entering the VA number.
  5. The customer confirms the bill details and completes the necessary authentication process.
  6. EBANX sends a real-time notification (webhook) to the merchant confirming the payment status.
  7. The order status is updated to "Paid" upon receiving a successful payment notification.
Payment channels

Customers can enter the VA number in their bank's mobile app, internet banking portal, or at a bank ATM.

Technical flow​

  • Request payment - Call the ws/direct endpoint with the parameters defined below.

  • Payment instructions - In response to this request, EBANX will return a voucher_url containing the Virtual Account number and payment details for the customer.

  • Customer completes the payment - The customer transfers the specified amount using the VA number. During this time, the transaction will be set on our platform with the status pending (PE).

  • Payment confirmation - Once the transaction is successful, the customer receives a confirmation on their banking app, and the merchant is updated with the transaction status.

  • EBANX notification - EBANX sends you a webhook notification confirming the successful transaction, allowing you to fulfill your customer's order.

Instructions​

Follow the steps below.

  1. Select your environment
    ​

    Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

    https://sandbox.ebanx.com/ws/direct

  2. Define your parameters
    ​

    To create a Virtual Account payment, you need to define the parameters in your request. The following tables outline the required parameters for the payment process.

    Basic parameters​

    ParameterRequirementDescription
    operationRequiredSet to request
    integration_keyRequiredYour EBANX integration key
    payment_type_codeRequiredSet to virtual-account
    countryRequiredSet to id for Indonesia

    Customer data​

    ParameterRequirementDescription
    nameRequiredCustomer name
    emailRequiredCustomer email
    phone_numberOptionalCustomer phone

    Charge parameters​

    ParameterRequirementDescription
    merchant_payment_codeRequiredUnique merchant payment code
    currency_codeRequiredSet to IDR
    amount_totalRequiredTotal amount to be charged
    bank_details.bank_codeRequiredBank code for the Virtual Account (see supported banks below)
    redirect_urlRequiredURL the customer will be redirected to after completing payment

    Supported bank codes​

    Bank CodeBank Name
    cimbCIMB Niaga
    bsiBank Syariah Indonesia
    bcaBCA
    bncBank Neo Commerce
    bniBNI
    mandiriMandiri
    briBRI
    btnBTN
    permataPermata
    danamonDanamon
    bssBank Sahabat Sampoerna
    maybankMaybank
    dokuDOKU VA
    sinarmasSinarmas
    Transaction limits

    Transaction limits vary by bank and transfer type:

    BankMin AmountMax AmountNotes
    BCAIDR 10,000IDR 50,000,000
    CIMBIDR 10,000IDR 50,000,000,000
    BNIIDR 10,001IDR 50,000,000
    BSIIDR 10,002IDR 100,000,000
    DOKU VAIDR 10,003IDR 250,000,000
    MandiriIDR 10,004IDR 300,000,000Same bank
    MandiriIDR 10,005IDR 500,000,000Interbank
    BRIIDR 10,006IDR 50,000,000,000Same bank
    BRIIDR 10,007IDR 500,000,000Interbank
    DanamonIDR 10,008IDR 2,000,000,000Same bank
    DanamonIDR 10,009IDR 200,000,000Interbank
    MaybankIDR 10,010IDR 10,000,000,000Same bank
    MaybankIDR 10,011IDR 200,000,000Interbank
    SinarmasIDR 10,012IDR 5,000,000,000Same bank
    SinarmasIDR 10,013IDR 50,000,000Interbank
    PermataIDR 10,014IDR 9,999,999,999
    BTNIDR 10,015IDR 9,999,999,999

  3. Payment request
    ​

    Once your customer selects a bank and submits a Virtual Account payment, create a payment request using the ws/direct endpoint.


    Sample request

    curl -X POST \
      --location 'https://sandbox.ebanx.com/ws/direct' \
      --header 'Content-Type: application/json' \
      --data '{
        "integration_key": "{{integration_key}}",
        "operation": "request",
        "payment": {
            "name": "John Doe",
            "email": "john.doe@example.com",
            "country": "id",
            "phone_number": "5555555555",
            "payment_type_code": "virtual-account",
            "merchant_payment_code": "{{unique_merchant_code}}",
            "currency_code": "IDR",
            "amount_total": 99.85,
            "bank_details": {
                "bank_code": "permata"
            },
            "redirect_url": "https://merchant.example.com/callback"
        }
      }'

  4. Payment successful response
    ​

    Each request returns a response similar to the example below.

    {
      "payment": {
        "hash": "59acc5f00945fa382ab051651440826da7701533249b3a475",
        "country": "id",
        "merchant_payment_code": "{{unique_merchant_code}}",
        "order_number": null,
        "status": "PE",
        "status_date": null,
        "open_date": "{{YYYY-MM-DD HH:mm:ss}}",
        "confirm_date": null,
        "transfer_date": null,
        "amount_br": "99.85",
        "amount_ext": "99.85",
        "amount_iof": "1",
        "currency_rate": "1",
        "currency_ext": "IDR",
        "due_date": "{{YYYY-MM-DD}}",
        "instalments": "1",
        "payment_type_code": "virtual-account",
        "voucher_url": "https://sandbox.ebanx.com/print/voucher?hash=59acc5f00945fa382ab051651440826da7701533249b3a475",
        "pre_approved": false,
        "capture_available": null,
        "customer": {
          "email": "john.doe@example.com",
          "name": "John Doe"
        }
      },
      "status": "SUCCESS"
    }
    At this stage, the payment will appear as pending (PE) in your
    Merchant Areachevron_right

    Timeout

    For Virtual Account payments, the timeout is 1 hour. Ensure the customer completes the payment within this time frame.

  5. Display Virtual Account number
    ​

    Redirect your customer to the URL provided in the voucher_url parameter. The page will display the Virtual Account number that the customer needs to use for the bank transfer.

    "voucher_url": "https://sandbox.ebanx.com/print/voucher?hash=59acc5f00945fa382ab051651440826da7701533249b3a475"

    Below is how the Virtual Account payment instructions page will look:

    Sandbox behavior

    When testing in sandbox, a simulator environment will be rendered to accept or decline the payment.

  6. Monitor payment for status changes
    ​

    Notifications

    Status

    • After receiving a notification that the status has changed, retrieve the payment status.

    • When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). If the customer does not complete the payment, the status will eventually change to cancelled (CA).

  7. Congratulations!
    ​

    You have successfully integrated Virtual Accounts.

    For more information, refer to the
    Direct API reference guidechevron_right

Resources​

Use the following resources when testing in your sandbox environment.

Globe Icon

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right
Mock Data Icon

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right
Warning Icon

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options: