OVO Push Payment

OVO Push Payment API Explanation

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:

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

OVO Push Payment 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. 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 API response :

{
    "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
vo_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

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	Transaction module not registered in OVO Systems
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:

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.