DOKU Wallet
Overview
DOKU Wallet is a payment method to process payments by using DOKU Wallet e-wallets. Purchases can be processed by using Payment Page and Gate, payouts by using Gate.
General information
Payment method type | digital wallet payments |
---|---|
Payment instruments | digital wallets |
Countries and regions | Indonesia |
Payment currencies | IDR |
Currency conversion | on the ecommpay side; refer to your ecommpay key account manager to enable currency conversion |
Purchases | + |
Payouts | + |
Stored credentials payments | – |
Full refunds | contact ecommpay technical support |
Partial refunds | contact ecommpay technical support |
Chargebacks | – |
Notes |
|
Onboarding and access fee | Refer to your key account manager ecommpay |
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
Interfaces | Amounts, IDR | Times** | |||||||
---|---|---|---|---|---|---|---|---|---|
Payment Page | Mobile SDKs | CMS Plug-ins | Gate | Dashboard | minimum | maximum | basic | threshold | |
Purchases | + | + | – | + | – | 1.00 | 2,000,000.00 until KYC* 10,000,000.00 since KYC |
Under a minute | Refer to your ecommpay key account manager |
Payouts | – | – | – | + | – | 1.00 | 10 000 000,00 | Under 5 minutes | Refer to your ecommpay key account manager |
* KYC or Know Your Customer is the process that allows organisations to verify clients and prevent frauds.
- The basic time is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the initiator. The basic time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour (if any input from customer is required). Use the basic time to estimate when to react to the absence of payment result notifications or when to check payment status.
- The threshold time is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the initiator receives the callback with the payment result. A payment is automatically declined, if its waiting time exceeds the threshold time. For individual setting of the threshold time limit, contact ecommpay technical support.
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.
Purchase by using Payment Page
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.
Figure: Purchase sequence when using Payment Page
- Customer initiates purchase by using the web service.
- The merchant web service sends to the specified ecommpay URL the purchase request for processing the purchase by using Payment Page.
- The payment platform receives the request for processing the purchase by using Payment Page.
- The payment platform performs the initial request processing that involves validation of the required parameters and signature.
- Requested Payment Page is generated into the ecommpay payment platform as specified in the project settings and the request parameters.
- Payment Page is displayed to the customer.
- The customer selects the DOKU Wallet method from the list of other payment methods and agrees to use the method (or accepts the method already selected on Payment Page and agrees).
- The payment platform receives the purchase request for payment processing in the DOKU Wallet service.
- The payment platform performs the internal purchase request processing and sends it to the DOKU Wallet service.
- The purchase request is processed in the DOKU Wallet service.
- The DOKU Wallet service generates the data for redirecting the customer to the DOKU Wallet payment form and sends it to the payment platform.
- The payment platform sends to Payment Page the data for redirecting the customer to the DOKU Wallet payment form.
- The customer is redirected to the DOKU Wallet payment form.
- The customer completes all the payment steps required by the DOKU Wallet purchase method.
- The payment is processed in the DOKU Wallet service.
- The payment result information is displayed to the customer on the DOKU Wallet payment form. The customer initiates redirection to the result waiting page on Payment Page.
- The DOKU Wallet service sends the payment result notification to the payment platform.
- The payment platform sends the callback to the web service.
- The payment platform sends payment results to Payment Page.
- A page with the payment result information is displayed to the customer.
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:
- 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
- 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.
- If you need to have Payment Page displayed with the DOKU Wallet method selected, set the force_payment_method parameter to
doku
. - If required, you can also add any other additional parameters Payment Page supports.
- 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.
Figure: Example of a successful purchase callback
{ "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.
Figure: Example of a declined purchase callback
{ "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:
Purchase by using Gate
General information
In the DOKU Wallet method, when processing a purchase by using Gate, the merchant web service is required to do the following:
- Send a request with all the required parameters and signature to the ecommpay URL.
- Perform redirecting customer to the DOKU Wallet payment form.
- Get the callback with the payment result from the payment platform.
The following diagram provides the detailed picture of the payment processing procedure.
Figure: Purchase sequence when using Gate
- Customer initiates purchase on the merchant web service by using the DOKU Wallet method.
- The web service sends the request for processing the purchase by using Gate to the specified ecommpay URL.
- The payment platform receives the request for processing the purchase by using Gate.
- The payment platform performs the initial request processing that includes validation of the required parameters and signature.
- The payment platform sends to the web service response with request receipt confirmation and correctness check result. For more information about the response, see Response format.
- The payment platform performs the internal payment request processing and sends it to the DOKU Wallet service.
- The purchase request is processed in the DOKU Wallet service.
- The DOKU Wallet service generates the data for redirecting the customer to the DOKU Wallet form and sends it to the payment platform.
- The payment platform sends to the web service the callback that delivers the data for redirecting customer to the DOKU Wallet form.
- The customer is redirected to the DOKU Wallet payment form.
- The customer completes all the payment steps required by the DOKU Wallet method.
- The payment is processed in the DOKU Wallet service.
- The payment result information is displayed to the customer on the DOKU Wallet payment form. The customer initiates redirection to the result waiting page on Payment Page.
- The DOKU Wallet service sends the payment result notification to the payment platform.
- The payment platform sends the callback to the web service.
- The customer receives the payment result from the web service.
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:
- 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. - 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
- Object general—general request identification information:
- 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.
- 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:
- Get a callback with the redirect_data object from the payment platform.
- Generate
POST
request in the formatx-www-form-urlencoded
by using parameter values contained in the body object. - Open the full redirect URL by using
POST
method.
The following example of callback code contains the request method, required parameters, and URL.
Figure: Example of customer redirection data
"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.
Figure: Example of a successful purchase callback
{ "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.
Figure: Example of a declined purchase callback
{ "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:
Payout by using Gate
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.
Figure: Payout sequence when using Gate
- Customer initiates payout.
- The web service sends the request for processing the payout by using Gate to the specified ecommpay URL.
- The payment platform receives the request for processing the payout by using Gate.
- The payment platform performs the initial request processing that includes validation of the required parameters and signature.
- The payment platform sends to the web service response with request receipt confirmation and correctness check result. For more information about the response, see Response format.
- The payment platform performs the internal payment request processing and sends it to the DOKU Wallet service.
- The payment is processed in the DOKU Wallet service.
- The DOKU Wallet service sends the payment result notification to the payment platform.
- The payment platform sends the callback to the web service.
- The customer receives the payment result from the web service.
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:
- 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. - 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
- Object general—general request identification information:
- If required, you can also add any other additional parameters Gate supports.
The following example provides a correct payment request with all mandatory parameters:
Figure: Payout request example
{ "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.
Figure: Example of a successful payout callback
{ "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.
Figure: Example of a declined payout callback
{ "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:
Testing
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 with40000
or40400
amountsuccess
status with any other amount
When testing payouts, the final payment status is determined by the amount specified in the request:
decline
status with40000
or40400
amountsuccess
status with any other amount
Purchases by using Payment Page
To perform a test purchase by using Payment Page, do the following:
- Send a correct test request for Payment Page opening to the payment platform.
- If the
doku
method was not specified in the request—select the method on the emulator page. - Specify a random email address and a random first name in the data entry fields.
- Click the Success or Decline button (depending on the amount specified in the request).
- 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:
- Send a correct test request for purchase to the payment platform.
- Accept a callback with redirection data.
- Go to the received URL and click the Success or Decline button (depending on the amount specified in the request).
- Make sure that the test purchase confirmation page is displayed.
- 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.
Analysis of payments results
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.