OVO Guide | DOKU Jokul Technical Documentation
OVO Push Payment Guide
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:
- Request push payment
- Wait for 70s for the API response (wait customer to pay via OVO application)
- Receive the response with the transaction status
Direct API - OVO Sequence Diagram
1. Request push payment
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:
{
"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
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
client.id | string | Mandatory | Client ID retrieved from DOKU Back Office |
order.invoice_number | string | Mandatory | Generated by merchant to identify the order and must unique per request Allowed chars: alphabetic, numeric, special chars Max length: 64 |
order.amount | number | Mandatory | In IDR Currency and without decimal Allowed chars: numeric Max length: 12 |
ovo_info.ovo_id | string | Mandatory | Phone number of the OVO Customer Allowed chars: numeric |
security.check_sum | string | Mandatory | Security parameter that must be generated by merchant to validate the request Allowed chars: alphabetic, numeric, special chars Max length: 64 |
2. Wait for 70s for the API Response (wait customer to pay via OVO application)
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.
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
If the customer make the payment through their OVO Application. You wil get the following response:
API response
Here is the sample of response body:
{
"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
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
client_id | string | Mandatory | Same as the request |
order.invoice_number | string | Mandatory | Same as the request |
order.amount | number | Mandatory | Same as the request |
ovo_info.ovo_id | string | Mandatory | Same as the request |
ovo_info.ovo_account_name | string | Mandatory | Name of the OVO customer |
ovo_configuration.merchant_id | string | Mandatory | Merchant ID by OVO Allowed chars: numeric Max length: 7 |
ovo_configuration.store_code | string | Mandatory | Store code by OVO Allowed chars: alphabetic, numeric Max length: 15 |
ovo_configuration.mid | string | Mandatory | MID by OVO Allowed chars: alphabetic, numeric Max length: 15 |
ovo_configuration.tid | string | Mandatory | TID by OVO Allowed chars: numeric Max length: 8 |
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 | Generated by OVO Max length: 6 |
ovo_payment.reference_number | number | Mandatory | Transaction ID for every transaction generated by OVO. Increment for each Push to Pay Transaction Maximum value: 999999 |
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 | Mandatory | OVO Cash that being charged for the transaction |
ovo_payment.cash_balance | number | Mandatory | OVO Cash remaining balance after the transaction |
ovo_payment.ovo_points_used | number | Mandatory | OVO Points that being charged for the transaction |
ovo_payment.ovo_points_balance | number | Mandatory | OVO Points remaining balance after the transaction |
ovo_payment.ovo_points_earned | number | Mandatory | OVO Points earned after the transaction |
ovo_payment.status | string | Mandatory | Payment status generated by DOKU Possible value: SUCCESS , FAILED , TIMEOUT |
security.check_sum | string | Mandatory | Security parameter that validated by DOKU |
OVO Response Code Mapping
OVO Response Code Mapping
| Code | Name | Description |
|---|---|---|
| 00 | Success / Approved | Success / Approved Transaction |
| 13 | Invalid Amount | Amount is missing ( less than Rp 1 ) |
| 14 | Invalid Mobile Number / OVO ID | Phone number / OVO ID not found in OVO System |
| 17 | Transaction Decline | OVO User canceled payment using OVO Apps |
| 25 | Transaction Not Found | Payment status not found when called by Check Payment Status API |
| 26 | Transaction Failed | Failed push payment confirmation to OVO Apps |
| 40 | Transaction Failed | General Error from OVO, please check to OVO |
| 54 | Transaction Expired (More than 7 days) | Transaction details already expired when API check payment status called |
| 56 | Card Blocked. Please call 1500696 | Card is blocked, unable to process card transaction |
| 58 | Transaction Not Allowed | Transaction module not registered in OVO Systems |
| 61 | Exceed Transaction Limit | Amount / count exceed limit, set by user |
| 63 | Secutiry Violation | Authentication Failed |
| 64 | Account Blocked. Please call 1500696 | Account is blocked, unable to process transaction |
| 65 | Transaction Failed | Limit transaction exceeded, limit on count or amount |
| 67 | Below Transaction Limit | The transaction amount is less than the minimum payment |
| 68 | Transaction Pending / Timeout | OVO Wallet late to give respond to OVO JPOS |
| 73 | Transaction has been reversed | Transaction has been reversed by API Reversal Push to Pay in Check Payment Status API |
| 94 | Duplicate request params | Duplication on merchant invoice or reference number |
| 96 | Invalid Processing Code | Invalid Processing Code inputted during Call API Check Payment Status |
| ER | System Failure | There is an error in OVO Systems, Credentials not found in OVO Systems |
| EB | Terminal Blocked | TID and/or MID not registered in OVO Systems |
| TO | Timeout | Request has expired due to invalid usage of unix timestamp (5 minutes max.) |
| BR | Bad request | Incorrect JSON Format setup |
| BR | Invalid format request | Invalid store code, empty storecode, or invalid appsource |
| - | No response | User did not give any response within the remaining time to finish the transaction |
What's next?
You can test your payment through our Payment Simulator. Here is the steps to simulate the OVO payment:
- Go to the OVO Payment Simulator
- Copy one of the Active phone number on the OVO Payment Simulator to the
ovo_info.ovo_id
in your request body - Copy the
order.invoice_number
that you will be hitting and paste it to the OVO Payment Simulator - Hit the API and while the API is waiting for response, go to the OVO Payment Simulator
- Click the Inquiry button and you should see the Payment details
- Choose which payment you wish, OVO Cash or OVO Points
- Click the Pay Now button
- You should receive the API response
Learn more here.