OVO Partner Integration Documentation
OVO PUSH TO PAY TECHNICAL DOCUMENTATION
version 1.7.1
Intended Audience
This guide is intended to assist software developer who want to develop applications integrated with OVO Payment systems.
To use this information, you should have access to OVO Server and you should also be familiar with the following concepts:
- RESTful web services
- HTTP/1.1
- JSON data serialization formats
- HMAC cryptography
API Operations :
- Staging :
https://app.byte-stack.net/pos - Production :
https://apigw.ovo.id/pos
Type & Processing code of transactions table
| Transaction Type | Type | Processing Code |
|---|---|---|
| Push to Pay (PTP) | 0200 | 040000 |
| Reversal Transaction | 0400 | 040000 |
| Void Transaction | 0200 | 020040 |
| Check Payment Status (PTP) | 0100 | 040000 |
| Check Payment Status (Void) | 0100 | 020040 |
| API Customer Phone Number Inquiry | 0100 | 050000 |
API Security
Headers
| Parameter Name | Description | Example |
|---|---|---|
| Content-Type | Data Serialization Format | application/json |
| app-id | Will be provided later by OVO | hypermart |
| random | Unix timestamp in seconds (10 digits) | 1468914526 |
| hmac | Follow the procedure below for HMAC creation | 8087f83ffc6a6564b8161e6dce1ee9a82dfc51 4c83de341587f16abd512fcfd6 |
How to build the HMAC Value
-
data: app-id concatenated with random and request body, e.g.
hypermart1468914526200{request body} -
key: Will be provided separately from this document, e.g.
a4f6bf89b2a85781b7c1cab997b7ee0c89be03f7ac6ef29b63a45d07253cc401 -
hmac:
hash_hmac('sha256', data, key)
For testing your HMAC generator you can use the app-id, random and key values above.
Resulting exactly the same HMAC value like the example above.
*Please make sure that time in Merchant’s server is set to GMT+7
Please find below for an example in Postman
Customer Phone Number Inquiry (Optional)
Method: POST ( raw : json )
Notes
- API phone number inquiry: Meant for checking the validity of a customer's phone number before the merchant calls the API push to pay.
-
If the phone number is not valid or not registered in OVO, OVO will send
RC:14that indicates an invalid phone number. - If the phone number is valid or registered in OVO, the partner or merchant can proceed with the payment by calling the push to pay API using the phone number.
- The maximum time limit from the OVO backend is 60 seconds. However, merchants can set the timeout for a maximum of 10 seconds.
-
Merchants can implement a logic to set a threshold on the total limit of attempts for customers using this API.
- Example: If the phone number is invalid 3 times in a row within 10 seconds, the payment request should be blocked for 5 minutes. This logic needs to be developed on the merchant's side.
Body Fields
| Parameter Name | Availability | Type | Description | Example | |
|---|---|---|---|---|---|
| type | Mandatory | N 4 | Type code of transaction. See the table of type & processing code of transactions (0100). | 0100 | |
| processingCode | Mandatory | N 6 | Type code of processing transaction. See the table of type & processing code of transactions (050000). | 050000 | |
| date | Mandatory | date | yyyy-MM-dd HH:mm:ss.SSS (ISO 8601). | 2018-11-05 13:47:20.671 | |
| tid | Mandatory | N 8 | Will be provided later by OVO. | 04770001 | |
| mid | Mandatory | AN 15 | Will be provided later by OVO. | JKTWEBOVO112516 | |
| merchantId | Mandatory | Auto Generated | Will be provided later by OVO. | 01435 | |
| storeCode | Mandatory | AN ..15 | Will be provided later by OVO. | TokoJKTBRT00001 | |
| appSource | Mandatory | A 3 | Transaction source. | POS | |
| transactionRequestData | Mandatory | Transaction request data based on TLV data ISO 8583. | |||
| phone | Mandatory | N 16 | Transaction phone number. | 65678232 | |
Sample Request
{
"type": "0100",
"processingCode": "050000",
"date": "2021-03-10 17:06:37.105",
"tid": "01820003",
"mid": "MDS00000001KRWC",
"storeCode": "453",
"merchantId": "18",
"appSource": "POS",
"transactionRequestData": {
"phone": "0800691175000"
}
}
Sample Response
{
"type": "0110",
"processingCode": "050000",
"date": "2021-03-10 17:06:37.105",
"traceNumber": 170637,
"hostTime": "170637",
"hostDate": "0310",
"responseCode": "00",
"tid": "01820003",
"mid": "MDS00000001KRWC",
"transactionRequestData": {
"phone": "0800691175000"
}
}
Push to Pay Transaction (Mandatory)
Method: POST ( raw : json )
Notes
- Reversal concept is when the Merchant didn’t receive a response to the push-to-pay request (MTI: 0210, Processing Code 040000). Merchant needs to call the API Reversal with MTI: 0400, Processing Code 040000.
- Time out of the request is set to 60s or 6000ms, please set the timeout on the merchant side to above 60s or 6000ms.
- Call API Reversal above 60s / 6000ms to identify the timeout transaction or the transaction that needs to be reversed.
- If the partner/merchant didn’t get a response from OVO after sending the Reversal request, then the merchant/partner might retry the reversal API call a maximum of 3 times with a 15-second interval. If the response is still not received, then the refund would be done manually by OVO based on reconciliation data in H+1 or complaint from the merchant/partner.
Body
| Parameter Name | Availability | Type | Description | Example | |
|---|---|---|---|---|---|
| type | Mandatory | N 4 | Type code of transaction. | See the table of type & processing code of transactions | |
| processingCode | Mandatory | N 6 | Type code of processing transaction. | See the table of type & processing code of transactions | |
| amount | Mandatory | N .8 | Total money spent for transactions. | 99999999 | |
| date | Mandatory | date | yyyy-MM-dd HH:mm:ss.SSS | 2018-11-05 13:47:20.671 | |
| referenceNumber | Mandatory | N .6 | Transaction ID for every transaction. Increment for each Push to Pay Transaction. Maximum 999999. Will be reset counting once batch number changes. | 999999 | |
| tid | Mandatory | N 8 | Will be provided later by OVO | 04770001 | |
| mid | Mandatory | AN 15 | Will be provided later by OVO | JKTWEBOVO112516 | |
| merchantId | Mandatory | Auto Generated | Will be provided later by OVO | 01435 | |
| storeCode | Mandatory | AN ..15 | Will be provided later by OVO | TokoJKTBRT00001 | |
| appSource | Mandatory | A 3 | Transaction source | POS | |
| transactionRequestData | Mandatory | Transaction request data based on TLV data ISO 8583 | |||
| batchNo | Mandatory | N .6 | Batch number of transaction for settlement. Value increment on daily basis, except if the Reference Number already reached maximum value. Maximum of Batch number is 6 digits. | 999999 | |
| phone | Mandatory | N ..16 | Phone number or Loyalty ID customers who already registered on OVO | 081212345678 / 8000917793301600 | |
| merchantInvoice | Mandatory | AN ..35 | Invoice generated by the merchant. Must be unique for each transaction. Special characters not included, only “-“ allowed. | 2018112516-CZ0001 | |
Example Request
{
"type": "0200",
"processingCode": "040000",
"amount": 20000,
"date": "2018-11-06 16:46:36.941",
"referenceNumber": "390",
"tid": "06092018",
"mid": "BookMyShow20188",
"merchantId": "10609",
"storeCode": "BookMyShow2018",
"appSource": "POS",
"transactionRequestData": {
"batchNo": "750",
"merchantInvoice": "2499010BQ3115",
"phone": "081212345678"
}
}
Example Response
{
"type": "0210",
"processingCode": "040000",
"amount": 20000,
"date": "2018-11-06 16:46:36.941",
"traceNumber": 164636,
"hostTime": "164644",
"hostDate": "1106",
"referenceNumber": 390,
"approvalCode": "760471",
"responseCode": "00",
"tid": "06092018",
"mid": "BookMyShow20188",
"transactionRequestData": {
"merchantInvoice": "2499010BQ3115",
"batchNo": "000750",
"phone": "081212345678"
},
"transactionResponseData": {
"storeAddress1": "Kempinsky",
"ovoid": "********8094",
"cashUsed": "20000",
"storeAddress2": "Hotel Indonesia ",
"ovoPointsEarned": "0",
"fullName": "Dikha Rahardian Putra",
"storeName": "BookMyShowJKT",
"ovoPointsUsed": "0",
"storeCode": "BookMyShow2018",
"paymentType": "PUSH TO PAY"
}
}
Reversal Push to Pay Transaction (Mandatory)
Method: POST ( raw : json )
Notes
- Reversal for push to pay based on push to pay request data (Merchant ID, Store Code, MID, TID, Batch Number, Reference Number & Merchant Invoice, Amount)
- Reversal concept is when the Merchant didn’t receive a response to the push to pay request (MTI: 0210, Processing Code 040000), Merchant needs to call the API Reversal with MTI: 0400
- Call API Reversal above 60s / 6000ms to identify the timeout transaction or the transaction which needs to be reversed
- If partner/merchant didn’t get a response from OVO after sending a Reversal request, the merchant/partner might retry the reversal API call a max of 3 times with an interval of 15 sec. If the response still isn't received, the refund would be done by OVO manually based on reconciliation data in H+1 or complaint from merchant/partner.
- Cut off time to reverse the transaction is at 23:59 or 11:59 PM (before transaction recap at the end of the day)
Body
| Parameter Name |
Availability |
Type |
Description |
Example |
|
|---|---|---|---|---|---|
| type | Mandatory | N 4 | Type code of transaction. | See the table of type & processing code of transactions | |
| processingCode | Mandatory | N 6 | Type code of processing transaction. | See the table of type & processing code of transactions | |
| amount | Mandatory | N .8 | Total money spent for transactions. | 99999999 | |
| date | Mandatory | date | yyyy-MM-dd HH:mm:ss.SSS | 2018-11-05 13:47:20.671 | |
| referenceNumber | Mandatory | N .6 | Transaction ID for every transaction. Increment for each Push to Pay Transaction. Maximum 999999 | 999999 | |
| tid | Mandatory | N 8 | Will be provided later by OVO | 04770001 | |
| mid | Mandatory | AN 15 | Will be provided later by OVO | JKTWEBOVO112516 | |
| merchantId | Mandatory | Auto Generated |
Will be provided later by OVO | 01435 | |
| storeCode | Mandatory | AN ..15 | Will be provided later by OVO | TokoJKTBRT00001 | |
| appSource | Mandatory | A 3 | Transaction source | POS | |
| transactionRequestData | Mandatory | Transaction request data based on TLV data ISO 8583 | |||
| batchNo | Mandatory | N .6 | Batch number of transactions for settlement. Value increment on daily basis, except if the Reference Number already reached maximum value. Maximum of Batch number is 6 digits. | 999999 | |
| merchantInvoice | Mandatory | AN ..35 | Invoice generated by the merchant. Must be unique for each transactions. Special characters not included, only “-“ allowed. | 2018112516-CZ0001 | |
*use batch number, merchant invoice and reference number from previous push to pay transactions
Example Request
{
"type": "0400",
"processingCode": "040000",
"amount": 100700,
"date": "2018-06-11 16:58:26.000",
"referenceNumber": "11704",
"tid": "43380001",
"mid": "Jneheadq0000001",
"merchantId": "4338",
"storeCode": "jnehq001",
"appSource": "POS",
"transactionRequestData": {
"batchNo": "001212",
"merchantInvoice": "2018-TESTR-2-012304"
}
}
Example Response
{
"type": "0410",
"processingCode": "040000",
"amount": 100700,
"date": "2018-11-06 16:58:26.000",
"traceNumber": 165826,
"hostTime": "165827",
"hostDate": "1106",
"referenceNumber": 11704,
"responseCode": "00",
"tid": "43380001",
"mid": "Jneheadq0000001",
"transactionRequestData": {
"merchantInvoice": "2018-TESTR-2-012304",
"batchNo": "001212"
}
}
Void Push to Pay Transactions (Optional)
Method: POST ( raw : json )
Notes
- Cut off time to void the transaction is at 23:59 or 11:59 PM (before transaction recap in end of day).
- The eligible push to pay transaction for void only allowed within one day. Example: If a customer performs a transaction on 23rd January 2018 at 17:00 and decides to void the transaction on 23rd January 2018 at 21:30, it’s still allowed to void the transaction.
- For transactions more than one day old (already settled), it needs to be treated as a manual refund and not allowed with the void method. Example: If a customer performs a transaction on 24th February 2019 at 22:00 and wants to void the transaction on 25th February 2019 at 00:19, this transaction (void request) isn’t allowed. Please treat this request as a manual refund.
Body
| Parameter Name | Availability | Type | Description | Example | |
|---|---|---|---|---|---|
| type | Mandatory | N 4 | Type code of transaction. | See the table of type & processing code of transactions | |
| processingCode | Mandatory | N 6 | Type code of processing transaction. |
See the table of type & processing code of transactions | |
| amount | Mandatory | N .8 | Total money spent for transactions |
99999999 | |
| date | Mandatory | date | yyyy-MM-dd HH:mm:ss.SSS | 2018-11-05 13:47:20.671 |
|
| referenceNumber | Mandatory | N .6 | Transaction ID for every transaction. Increment for each Push to Pay Transaction. Maximum 999999 |
999999 | |
| tid | Mandatory | N 8 | Will be provided later by OVO |
04770001 | |
| mid | Mandatory | AN 15 | Will be provided later by OVO |
JKTWEBOVO112516 | |
| merchantId | Mandatory | Auto Generated |
Will be provided later by OVO | 01435 | |
| storeCode | Mandatory | AN ..15 | Will be provided later by OVO |
TokoJKTBRT00001 | |
| appSource | Mandatory | A 3 | Transaction source |
POS | |
| transactionRequestData | Mandatory | Transaction request data based on TLV data ISO 8583 | |||
| batchNo | Mandatory | N .6 | Batch number of transaction for settlement. Value increment on daily basis, except if the Reference Number already reached maximum value. Maximum of Batch number is 6 digits. |
999999 | |
| phone | Mandatory | N ..16 | Phone number or Loyalty ID customers who already registered on OVO | 081212345678 / 8000917793301600 | |
| merchantInvoice | Mandatory | AN ..35 | Invoice generated by the merchant. Must be unique for each transaction. Special characters not included, only “-“ allowed. |
2018112516-CZ0001 | |
Example Request
{
"type": "0200",
"processingCode": "020040",
"amount": 1750000,
"date": "2018-11-06 17:02:04.556",
"referenceNumber": 7,
"tid": "06990001",
"mid": "ruparupaweb0001",
"merchantId": "10699",
"storeCode": "rrweb0001",
"appSource": "POS",
"transactionRequestData": {
"batchNo": "777",
"merchantInvoice": "RRWEB0007",
"phone": "081212345678"
}
}
Example Response
{
"type": "0210",
"processingCode": "020040",
"amount": 1750000,
"date": "2018-11-06 17:02:04.556",
"traceNumber": 170204,
"hostTime": "170205",
"hostDate": "1106",
"referenceNumber": 7,
"approvalCode": "852459",
"responseCode": "00",
"tid": "06990001",
"mid": "ruparupaweb0001",
"transactionRequestData": {
"merchantInvoice": "RRWEB0007",
"batchNo": "000777",
"phone": "081212345678"
},
"transactionResponseData": {
"storeAddress1": "Kawan Lama Kembangan",
"ovoid": "********8094",
"cashUsed": "1750000",
"storeAddress2": "www.ruparupa.com",
"fullName": "Dikha Rahardian Putra",
"storeName": "Rupa Rupa Website",
"ovoPointsUsed": "0",
"storeCode": "rrweb0001",
"paymentType": "VOIDPUSHTOPAY"
}
}
Check Payment Status (Optional)
Method: POST ( raw : json )
Notes
- Check Payment Status based on push to pay request data (Merchant ID, Store Code, MID, TID, Batch Number, Reference Number & Merchant Invoice, Amount)
- You can check the reversal payment status to ensure whether the transaction amount already reversed to customer account or not
- You can check payment status for last seven days (7days x 24hr) transactions using this API
- For inquiry void payment status please change the Processing code to 020040 or refer to table of type & processing code of transactions
- You can check void status for last seven days (7days x 24hr) of void transactions using this API
Body
| Parameter Name | Availability | Type | Description | Example | |
|---|---|---|---|---|---|
| type | Mandatory | N 4 | Type code of transaction. | See the table of type & processing code of transactions | |
| processingCode | Mandatory | N 6 | Type code of processing transaction. | See the table of type & processing code of transactions | |
| amount | Mandatory | N .8 | Total money spent for transactions | 99999999 | |
| date | Mandatory | date | yyyy-MM-dd HH:mm:ss.SSS | 2018-11-05 13:47:20.671 |
|
| referenceNumber | Mandatory | N .6 | Transaction ID for every transaction. Increment for each Push to Pay Transaction. Maximum 999999 | 999999 | |
| tid | Mandatory | N 8 | Will be provided later by OVO | 04770001 | |
| mid | Mandatory | AN 15 | Will be provided later by OVO | JKTWEBOVO112516 | |
| merchantId | Mandatory | Auto Generated |
Will be provided later by OVO | 01435 | |
| storeCode | Mandatory | AN ..15 | Will be provided later by OVO | TokoJKTBRT00001 | |
| appSource | Mandatory | A 3 | Transaction source | POS | |
| transactionRequestData | Mandatory | Transaction request data based on TLV data ISO 8583 | |||
| batchNo | Mandatory | N .6 | Batch number of transaction for settlement. Value increment on daily basis, except if the Reference Number already reached maximum value. Maximum of Batch number is 6 digits. |
999999 | |
| phone | Mandatory | N ..16 | Phone number or Loyalty ID customers who already registered on OVO | 081212345678 / 8000917793301600 | |
| merchantInvoice | Mandatory | AN ..35 | Invoice generated by the merchant. Must be unique for each transaction. Special characters not included, only “-“ allowed. |
2018112516-CZ0001 | |
Example Request
{
"type": "0100",
"processingCode": "040000",
"amount": 5000,
"date": "2018-11-22 13:38:50.588",
"referenceNumber": "10101",
"tid": "08291205",
"mid": "DamriBus1120181",
"merchantId": "10829",
"storeCode": "DAMRI123",
"appSource": "POS",
"transactionRequestData": {
"batchNo": "123",
"phone": "8001069761694600",
"merchantInvoice": "10101"
}
}
Example Response
{
"type": "0110",
"processingCode": "040000",
"amount": 5000,
"date": "2018-11-22 13:38:50.588",
"traceNumber": 150708,
"hostTime": "150708",
"hostDate": "1122",
"referenceNumber": 10101,
"responseCode": "58",
"tid": "08291205",
"mid": "DamriBus1120181",
"transactionRequestData": {
"batchNo": "000123"
}
}
Response Code of OVO Payment
Response Code table
| RC | Http Header | RC Details | Description |
|---|---|---|---|
| 00 | HTTP Header 200 | Success / Approved | Success / Approved Transaction |
| 13 | Http Header 422 | Invalid amount | Amount is missing (less than Rp 1) |
| 14 | Http Header 422 | Invalid Mobile Number / OVO ID | Phone number / OVO ID not found in OVO System |
| 17 | Http Header 422 | Transaction Decline | OVO User canceled payment using OVO Apps |
| 25 | Http Header 422 | Transaction Not Found | Payment status not found when called by Check Payment Status API |
| 26 | Http Header 422 | Transaction Failed | Failed push payment confirmation to OVO Apps |
| 40 | Http Header 422 | Transaction Failed | Failed Push Payment, payment failed |
| 54 | Http Header 422 | Transaction Expired (More than 7 days) | Transaction details already expired when API check payment status called |
| 58 | Http Header 422 | Transaction Not Allowed | Transaction module not registered in OVO Systems |
| 63 | Http Header 408 | Security Violation | Authentication Failed |
| 68 | Http Header 422 | Transaction Pending / Timeout | OVO Wallet late to give respond to OVO JPOS |
| 73 | Http Header 422 | Transaction has been reversed | Transaction has been reversed by API Reversal Push to Pay in Check Payment Status API |
| 94 | Http Header 422 | Duplicate Request Params | Duplication on merchant invoice or reference number |
| 96 | Http Header 422 | Invalid Processing Code | Invalid Processing Code inputted during Call API Check Payment Status |
| ER | Http Header 422 | System Failure | There is an error in OVO Systems, Credentials not found in OVO Systems |
| EB | Http Header 422 | Terminal Blocked | TID and/or MID not registered in OVO Systems |
| - | Http Header 408 | Timeout | Request has expired Timeout due to invalid usage of unix timestamp (5 minutes max.) |
| - | Http Header 404 | No Response | User did not give any response within the remaining time to finish the transaction |
| BR | Http Header 400 | Bad Request | Incorrect JSON format setup |
| Http Header 422 | Invalid Format Request | Invalid Store code, empty storecode, or invalid appsource |
*For timeout scenario the result should be http status 404 in request header