DOKU Wallet

General information

Interaction diagram

Payment processing by using the DOKU Wallet payment method requires merchant's web service, one of ecommpay interfaces, and the ecommpay payment platform, as well as the DOKU Wallet service.

Operations support

* KYC or Know Your Customer is the process that allows organisations to verify clients and prevent frauds.

Processing scenarios

In the DOKU Wallet method, purchases and payouts follow different processing procedures. To perform a purchase operation, you need to redirect customer to the DOKU Wallet payment form, while to initiate a payout, you need to notify customer by using merchant's web service.

Figure: Purchase by using Payment Page

Figure: Purchase by using Gate

Figure: Payout by using Gate

The sections that follow provide detailed information about what you need to perform payments and how you can analyse the information on payments and operations.

General information

In the DOKU Wallet method, when processing a purchase by using Payment Page, the merchant web service is required to send a request with all the required parameters and signature to the ecommpay URL and get the callback with the payment result from the payment platform. When opening Payment Page, you can either allow your customer to select the DOKU Wallet method from the list of other payment methods on Payment Page or have Payment Page opened with the DOKU Wallet method selected. For more information about preselecting payment methods, see Preselecting payment methods.

The following diagram provides the detailed picture of the payment processing procedure.

The sections that follow discuss in more details the request format and the Payment Page parameters to use in the DOKU Wallet payment method and provide the information on the format of callbacks with payment results. For the general information on how to use the API, see Payment Page API Description.

Request format

There are several things you need to consider when using the DOKU Wallet method:

1. You must provide values for the basic minimum of parameters. Listed below are the parameters that are mandatory for any payment method:
   • customer_id—the unique ID of the customer within your project
   • project_id—the project ID obtained from ecommpay
   • payment_id—payment ID unique within the project
   • payment_amount—payment amount in minor units
   • payment_currency—payment currency in ISO-4217 alpha-3 format
2. It is recommended to specify the name and e-mail address of the user in the customer_first_name and customer_email additional parameters. If the request is missing the parameters, on Payment Page the additional fields are displaying to the customer to input missing data. For more details about clarification, see Submission of additional payment information.
3. If you need to have Payment Page displayed with the DOKU Wallet method selected, set the force_payment_method parameter to doku.
4. If required, you can also add any other additional parameters Payment Page supports.
5. After you specify all the parameters you need, you must create the signature for the request. For instructions on how to sign a payment request, see Signature generation and verification.

Thus, a correct payment request in the DOKU Wallet method must include project, customer and payment IDs, amount and currency of a payment in the appropriate currency, first name and email of a customer, and the signature, as shown in the following example:

EPayWidget.run(
    { payment_id: 'ID_183', 
      payment_amount: 1000000, 
      payment_currency: 'IDR', 
      project_id: 238,
      customer_id: '123',
      customer_first_name: 'Hasan',
      customer_email: 'Prasetyo@mail.com',
      signature: "hlhydUV+SmGJYhm6G47NknsqVx2TdMZrnJ9V5Ly
                      O5JuyamXS/BYQ1M2IUgBuVxa93HwzBbEjF9Veg=="
    }
)

For information about all parameters available in the DOKU Wallet method, see Parameters to pass to Payment Page.

Callback format

In the DOKU Wallet method, the callbacks that deliver purchase results use the standard format described in Callbacks.

The following is the example of a callback with an information about successful 1,000.00 IDR purchase made in the 238 project by using the 1189632633 DOKU Wallet e-wallet.

{
        "project_id": 238,
        "payment": {
            "id": "Doku_eWallet_001",
            "type": "purchase",
            "status": "success",
            "date": "2018-12-14T09:21:58+0000",
            "method": "Doku",
            "sum": {
                "amount": 100000,
                "currency": "IDR"
            },
            "description": ""
        },
        "account": {
            "number": "1189632633"
        },
        "operation": {
            "id": 6085000002263,
            "type": "sale",
            "status": "success",
            "date": "2018-12-14T09:21:58+0000",
            "created_date": "2018-12-14T09:20:39+0000",
            "request_id": "026b9dbadeb438abe796132c1db963c9650424fe-a729ea898
                                    99e9ae460d7a86c9667edc9b11eb994",
            "sum_initial": {
                "amount": 100000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 100000,
                "currency": "IDR"
            },
            "provider": {
                "id": 1162,
                "payment_id": "342205",
                "date": "2018-12-14T09:21:54+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "XFyr/D1zXj84lUZVfpbWZol9JAZLnUZoPJKPXRbOqBUpxxa/hOKm2
                            P8XOqydoyeIi7KdqrcxLFd3GxgPgUzIDg=="
    }

The following example of callback is for a payment rejected due to amount or frequency limitation.

{
        "project_id": 238,
        "payment": {
            "id": "ECT_TEST_1544793284604",
            "type": "purchase",
            "status": "decline",
            "date": "2018-12-14T13:23:50+0000",
            "method": "Doku",
            "sum": {
                "amount": 2000000000,
                "currency": "IDR"
            },
            "description": ""
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 19078000002242,
            "type": "sale",
            "status": "decline",
            "date": "2018-12-14T13:23:50+0000",
            "created_date": "2018-12-14T13:20:47+0000",
            "request_id": "b12c7232b016305896e2c73d47956b562e131640-44
                                    4c4b88f5f7468d191c0a8ac67b74dd2bc05ac9",
            "sum_initial": {
                "amount": 2000000000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 2000000000,
                "currency": "IDR"
            },
            "provider": {
                "id": 1162,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit"
        },
        "signature": "5+82BkJhEn/DG892c1vYILNYttNDkBQJAfC87oDMeySCJ8
                                KQ/CiU02oQvEZUsNbEVDN9uuQTagdL6SYe5iOzSA=="
    }

Related topics

The following topics might be useful when implementing payments by using Payment Page:

• Interaction concepts
• Signature generation and verification
• Payment models and statuses
• Information of operations performing

General information

In the DOKU Wallet method, when processing a purchase by using Gate, the merchant web service is required to do the following:

1. Send a request with all the required parameters and signature to the ecommpay URL.
2. Perform redirecting customer to the DOKU Wallet payment form.
3. Get the callback with the payment result from the payment platform.

The following diagram provides the detailed picture of the payment processing procedure.

The sections that follow discuss in more details the request format and the Gate parameters to use in the DOKU Wallet method and provide the information about formats of the data for redirecting customers and the information about the format of callbacks with payment results. For the general information on how to use the API, see API Description.

Request format

There are several things you must consider when using purchase requests in the DOKU Wallet method:

1. You perform purchases by sending the /v2/payment/wallet/doku/sale request by using POST (HTTP) method. This is an e-wallet payments request group: /v2/payment/wallet/{payment_method}/sale.
2. The following objects and parameters must be specified in any request:
   • Object general—general request identification information:
     • project_id—the project ID obtained from ecommpay
     • payment_id—payment ID unique within the project
     • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
   • Object customer—customer information:
     • id—the unique ID of the customer within your project
     • ip_address—customer IP address
   • Object payment—payment information:
     • amount—purchase amount in minor units
     • currency—purchase currency in ISO-4217 alpha-3 format
3. It is recommended to specify the name and e-mail address of the user in the customer_first_name and customer_email additional parameters. If the request is missing the parameters, the list of parameters is sent in the clarification callback. For more details, see Submission of additional payment information.
4. If required, you can also add any other additional parameters Gate supports.

Thus, a correct payment request in the DOKU Wallet method must include project, customer and payment IDs, signature, IP-address, first name and email of the customer, amount and currency of the purchase, as shown in the following example:

{
    "general": {
    "project_id": 125,
    "payment_id": "ID_184",
    "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVLhNN5e7cV+VHq3L
                        wY3T\/pOMeSaRfBaNIipTv+AWoXW\/9MTO8yJA=="
  },
  "customer": {
    "id": "123",
    "ip_address": "114.124.147.207",
    "first_name": "Riza",
    "email": "riza@mail.com"
    },
  "payment": {
    "amount": 100,
    "currency": "IDR"
  }
}

Formats of the customer redirection data

In the DOKU Wallet method, when redirecting customer to the DOKU Wallet payment form, it is required to do the following:

1. Get a callback with the redirect_data object from the payment platform.
2. Generate POST request in the format x-www-form-urlencoded by using parameter values contained in the body object.
3. Open the full redirect URL by using POST method.

The following example of callback code contains the request method, required parameters, and URL.

"redirect_data": {
            "method": "POST",
            "body": {
                "MALLID": 4038,
                "CHAINMERCHANT": "NA",
                "AMOUNT": "10000.00",
                "PURCHASEAMOUNT": "10000.00",
                "TRANSIDMERCHANT": 1447000002341,
                "PAYMENTTYPE": "SALE",
                "WORDS": "2e2d93c40d5c82f87b555502492222abcdb8c50f",
                "REQUESTDATETIME": "20181218142352",
                "CURRENCY": "360",
                "PURCHASECURRENCY": "360",
                "SESSIONID": "7d28088c",
                "NAME": "riza",
                "EMAIL": "riza@mail.com",
                "BASKET": "Sale,10000.00,1,10000.00",
                "PAYMENTCHANNEL": "41"
            },
            "encrypted": [],
            "url": "https://pay.doku.com/Suite/Receive"
        }

Format of callback with purchase results

In the DOKU Wallet method, the callbacks that deliver purchase results use the standard format described in Callbacks.

The following is the example of a callback with an information about successful 1,000.00 IDR purchase made in the 238 project by using the 1189632633 DOKU Wallet e-wallet.

{
        "project_id": 238,
        "payment": {
            "id": "Doku_eWallet_001",
            "type": "purchase",
            "status": "success",
            "date": "2018-12-14T09:21:58+0000",
            "method": "Doku",
            "sum": {
                "amount": 100000,
                "currency": "IDR"
            },
            "description": ""
        },
        "account": {
            "number": "1189632633"
        },
        "operation": {
            "id": 6085000002263,
            "type": "sale",
            "status": "success",
            "date": "2018-12-14T09:21:58+0000",
            "created_date": "2018-12-14T09:20:39+0000",
            "request_id": "026b9dbadeb438abe796132c1db963c9650424fe-a729ea898
                                    99e9ae460d7a86c9667edc9b11eb994",
            "sum_initial": {
                "amount": 100000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 100000,
                "currency": "IDR"
            },
            "provider": {
                "id": 1162,
                "payment_id": "342205",
                "date": "2018-12-14T09:21:54+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "XFyr/D1zXj84lUZVfpbWZol9JAZLnUZoPJKPXRbOqBUpxxa/hOKm2
                            P8XOqydoyeIi7KdqrcxLFd3GxgPgUzIDg=="
    }

The following example of callback is for a payment rejected due to amount or frequency limitation.

{
        "project_id": 238,
        "payment": {
            "id": "ECT_TEST_1544793284604",
            "type": "purchase",
            "status": "decline",
            "date": "2018-12-14T13:23:50+0000",
            "method": "Doku",
            "sum": {
                "amount": 2000000000,
                "currency": "IDR"
            },
            "description": ""
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 19078000002242,
            "type": "sale",
            "status": "decline",
            "date": "2018-12-14T13:23:50+0000",
            "created_date": "2018-12-14T13:20:47+0000",
            "request_id": "b12c7232b016305896e2c73d47956b562e131640-44
                                    4c4b88f5f7468d191c0a8ac67b74dd2bc05ac9",
            "sum_initial": {
                "amount": 2000000000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 2000000000,
                "currency": "IDR"
            },
            "provider": {
                "id": 1162,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit"
        },
        "signature": "5+82BkJhEn/DG892c1vYILNYttNDkBQJAfC87oDMeySCJ8
                                KQ/CiU02oQvEZUsNbEVDN9uuQTagdL6SYe5iOzSA=="
    }

Related topics

The following topics might be useful when implementing payments by using Gate:

• Interaction concepts
• Signature generation and verification
• Payment models and statuses
• Information of operations performing

General information

In the DOKU Wallet method, when processing a payout by using Gate, the merchant web service is required to send a request with all the required parameters and signature to the ecommpay URL and get the callback with the payment result from the payment platform.

The following diagrams provide the detailed picture of the payment processing procedure.

The sections that follow discuss in more details the request format and the Gate parameters to use in the DOKU Wallet method and provide the information about the format of callbacks with payment results. For the general information on how to use the API, see API Description.

Request format

There are several things you must consider when using payout requests in the DOKU Wallet method:

1. You perform purchases by sending the /v2/payment/wallet/doku/payout request by using POST (HTTP) method. This is an e-wallet payments request group /v2/payment/wallet/{payment_method}/payout.
2. The following objects and parameters must be specified in any request:
   • Object general—general request identification information:
     • project_id—the project ID obtained from ecommpay
     • payment_id—payment ID unique within the project
     • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
   • Object customer—customer information:
     • id—the ID of the customer within merchant project
     • ip_address—IP address
   • Object account—customer e-wallet information:
     • number—customer e-wallet number
     • customer_name—full customer name
   • Object payment—payout information:
     • amount—payout amount in minor currency units
     • currency—payout currency in the ISO-4217 alpha-3 format
3. If required, you can also add any other additional parameters Gate supports.

The following example provides a correct payment request with all mandatory parameters:

{
    "general": {
    "project_id": 2853,
    "payment_id": "test-002",
    "signature": "M1vT4q9c8hA8xCjEwGFSANwbxHShy2TSOI/4sKFk
                        B+9XAaq7vt3/Jkn+aJmGA4jH6bgBOp8DTf8d/XdoV+vd7Q=="
  },
  "customer": {
    "id": "payoutTest",
    "ip_address": "114.124.147.206"
  },
  "account": {
    "number": "654654654",
    "customer_name": "John Doe"
  },
  "payment": {
    "amount": 10000,
    "currency": "IDR"
  }
}

Callback format

In the DOKU Wallet method, the callbacks that deliver payout results use the standard format described in Callbacks.

The following is the example of a callback with the information about a successful 1.00 IDR payout made to DOKU wallet 1579000479 of the 1 customer in the 580 project.

{
        "project_id": 580,
        "payment": {
            "id": "ApsViaDoku-040-wallet-1",
            "type": "payout",
            "status": "success",
            "date": "2019-05-07T11:38:24+0000",
            "method": "Doku",
            "sum": {
                "amount": 100,
                "currency": "IDR"
            },
            "description": "ApsViaDokuPayoutTest.49855500 1538564115"
        },
        "account": {
            "number": "1579000479"
        },
        "customer": {
            "id": "1",
            "phone": "798454444474"
        },
        "operation": {
            "id": 31771000001833,
            "type": "payout",
            "status": "success",
            "date": "2019-05-07T11:38:24+0000",
            "created_date": "2019-05-07T11:38:14+0000",
            "request_id": "a6ce8cf365af0c33a3d7744bb48b6aac20ecfed
                            8-ea53b2d5ff4ee3dead9dcb45e8780793377c9460",
            "sum_initial": {
                "amount": 100,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "IDR"
            },
            "provider": {
                "id": 1162,
                "payment_id": "DK06282314",
                "date": "2019-05-07T18:38:19+0000",
                "auth_code": "",
                "endpoint_id": "04"
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "8xwuyUSnpfu4YVMH1qF8Zk2ILnhu21/oE4d1Ue
                7ZlLVdKkMHkUKH51zo76fAVQAiovMrU3JUTyF8UjZ8qTouKQ=="
    }

The following example of callback is for a payout rejected due to amount or frequency limitation.

{
        "project_id": 238,
        "payment": {
            "id": "ECT_TEST_1544793284604",
            "type": "purchase",
            "status": "decline",
            "date": "2018-12-14T13:23:50+0000",
            "method": "Doku",
            "sum": {
                "amount": 2000000000,
                "currency": "IDR"
            },
            "description": ""
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 19078000002242,
            "type": "sale",
            "status": "decline",
            "date": "2018-12-14T13:23:50+0000",
            "created_date": "2018-12-14T13:20:47+0000",
            "request_id": "b12c7232b016305896e2c73d47956b562e131640-44
                                    4c4b88f5f7468d191c0a8ac67b74dd2bc05ac9",
            "sum_initial": {
                "amount": 2000000000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 2000000000,
                "currency": "IDR"
            },
            "provider": {
                "id": 1162,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit"
        },
        "signature": "5+82BkJhEn/DG892c1vYILNYttNDkBQJAfC87oDMeySCJ8
                                KQ/CiU02oQvEZUsNbEVDN9uuQTagdL6SYe5iOzSA=="
    }

Related topics

The following topics might be useful when implementing payments through Gate:

• Interaction concepts
• Signature generation and verification
• Payment models and statuses
• Information of operations performing

General information

For the DOKU Wallet method the testing of purchases by using Payment Page and Gate, payouts by using Gate.

Testing can be performed within a test project, to enable and disable the testing availability, contact ecommpay technical support via support@ecommpay.com.

When performing a test payment, take into account that you must specify the identifier of the test project in the requests, the currency can be only IDR, and the interfaces of the payment forms emulator of Payment Page and DOKU Wallet differ from the production environment.

Test payments statuses

When testing purchases, the final payment status is determined by the amount specified in the request:

• decline status with 40000 or 40400 amount
• success status with any other amount

When testing payouts, the final payment status is determined by the amount specified in the request:

• decline status with 40000 or 40400 amount
• success status with any other amount

Purchases by using Payment Page

To perform a test purchase by using Payment Page, do the following:

1. Send a correct test request for Payment Page opening to the payment platform.
2. If the doku method was not specified in the request—select the method on the emulator page.
3. Specify a random email address and a random first name in the data entry fields.
4. Click the Success or Decline button (depending on the amount specified in the request).
5. Accept a callback with information about the payment result.

The full information about purchase process by using DOKU Wallet through Payment Page is provided in the section Purchase by using Payment Page.

Purchases by using Gate

To perform test purchases by using Gate, it is necessary to submit a URL for redirection to the test purchases confirmation page to ecommpay technical support (due to the peculiarities of the DOKU Wallet service one URL is used for payments with success and decline statuses), and receive a confirmation about the possibility of testing purchases. After that, do the following for every test purchase:

1. Send a correct test request for purchase to the payment platform.
2. Accept a callback with redirection data.
3. Go to the received URL and click the Success or Decline button (depending on the amount specified in the request).
4. Make sure that the test purchase confirmation page is displayed.
5. Accept a callback with information about the payment result.

The full information about purchase process by using DOKU Wallet through Gate is provided in the section Purchase by using Gate.

Payouts by using Gate

To perform a test payout by using Gate, send a correct test request to the payment platform and accept a callback with information about the payment result. The full information about payout process by using DOKU Wallet through Gate is provided in the section Payout by using Gate.

As with other payment methods ecommpay offers, when using the DOKU Wallet method, you have several options to analyse the information about payments and operations performed by using the method—alone or in conjunction with other methods.

You can load and analyse all the necessary information in Dashboard, for instance you can use the analytic panels on the Analytics tab to this end.

Also, you can export the information for further analysis by using third party analytical tools. The following options are available:

• Dashboard allows you to download reports in CSV and XLS formats—by using the tools on the Payments tab. You can perform export as a one-time download to your local computer or have payment data regularly exported and delivered to email addresses you specify.
• Data API allows you to have payment information exported in JSON format and delivered to a URL you specify. The payment information is exported by using the /operations/get queries.

If you have any further questions regarding payment data analysis, contact ecommpay technical support.