OVO Guide

Jokul has partnered with various e-money providers and one of them is OVO to provide E-Money Payment. Learn more about how Jokul can help you integrate with OVO here.


Integration steps

Here is the overview how you integrate 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
Jokul Direct - OVO Sequence DiagramJokul Direct OVO Flow

1. Request push payment

To request push payment, you will need to hit this API through your Backend:

API Request

TypeValue
HTTP MethodPOST
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
ParameterTypeMandatoryDescription
client.idstringMandatoryClient ID retrieved from Jokul Back Office
order.invoice_numberstringMandatoryGenerated by merchant to identify the order and must unique per request
Allowed chars: alphabetic, numeric, special chars
Max length: 64
order.amountnumberMandatoryIn IDR Currency and without decimal
Allowed chars: numeric
Max length: 12
ovo_info.ovo_idstringMandatoryPhone number of the OVO Customer
Allowed chars: numeric
security.check_sumstringMandatorySecurity 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": "Taufik Ismail"
},
"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
ParameterTypeMandatoryDescription
client_idstringMandatorySame as the request
order.invoice_numberstringMandatorySame as the request
order.amountnumberMandatorySame as the request
ovo_info.ovo_idstringMandatorySame as the request
ovo_info.ovo_account_namestringMandatoryName of the OVO customer
ovo_configuration.merchant_idstringMandatoryMerchant ID by OVO
Allowed chars: numeric
Max length: 7
ovo_configuration.store_codestringMandatoryStore code by OVO Allowed chars: alphabetic, numeric
Max length: 15
ovo_configuration.midstringMandatoryMID by OVO
Allowed chars: alphabetic, numeric
Max length: 15
ovo_configuration.tidstringMandatoryTID by OVO
Allowed chars: numeric
Max length: 8
ovo_payment.datestringMandatoryPayment date generated by Jokul with the format of yyyyMMddHHmmss UTC+7 time
ovo_payment.batch_numbernumberMandatoryBatch number of transaction for settlement. Value increment on daily basis, except if the Reference Number already reached maximum value
ovo_payment.trace_numbernumberMandatoryGenerated by OVO
Max length: 6
ovo_payment.reference_numbernumberMandatoryTransaction ID for every transaction generated by OVO. Increment for each Push to Pay Transaction
Maximum value: 999999
ovo_payment.approval_codestringMandatoryGenerated by OVO
ovo_payment.response_codestringMandatoryGenerated by OVO. Please refer to the section below for the response_code mapping
ovo_payment.cash_usednumberMandatoryOVO Cash that being charged for the transaction
ovo_payment.cash_balancenumberMandatoryOVO Cash remaining balance after the transaction
ovo_payment.ovo_points_usednumberMandatoryOVO Points that being charged for the transaction
ovo_payment.ovo_points_balancenumberMandatoryOVO Points remaining balance after the transaction
ovo_payment.ovo_points_earnednumberMandatoryOVO Points earned after the transaction
ovo_payment.statusstringMandatoryPayment status generated by Jokul
Possible value: SUCCESS, FAILED, TIMEOUT
security.check_sumstringMandatorySecurity parameter that validated by Jokul

OVO Response Code Mapping

OVO Response Code Mapping
CodeNameDescription
00Success / ApprovedSuccess / Approved Transaction
14Invalid Mobile Number / OVO IDPhone number / OVO ID not found in OVO System
17Transaction DeclineOVO User canceled payment using OVO Apps
25Transaction Not FoundPayment status not found when called by Check Payment Status API
26Transaction FailedFailed push payment confirmation to OVO Apps
40Transaction FailedFailed Push Payment, Error request: Merchant invoice, batch number & reference number already used from previous transactions
54Transaction Expired (More than 7 days)Transaction details already expired when API check payment status called
56Card Blocked. Please call 1500696Card is blocked, unable to process card transaction
58Transaction Not AllowedTransaction module not registered in OVO Systems
61Exceed Transaction LimitAmount / count exceed limit, set by user
63Secutiry ViolationAuthentication Failed
64Account Blocked. Please call 1500696Account is blocked, unable to process transaction
65Transaction FailedLimit transaction exceeded, limit on count or amount
67Below Transaction LimitThe transaction amount is less than the minimum payment
68Transaction Pending / TimeoutOVO Wallet late to give respond to OVO JPOS
73Transaction has been reversedTransaction has been reversed by API Reversal Push to Pay in Check Payment Status API
96Invalid Processing CodeInvalid Processing Code inputted during Call API Check Payment Status
ERSystem FailureThere is an error in OVO Systems, Credentials not found in OVO Systems
EBTerminal BlockedTID and/or MID not registered in OVO Systems

What's next?

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
  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.