OVO Partner Integration Documentation

Push To Pay API

Credentials

Question Answer
What is staging credentials? Staging Credentials are special values for the merchants to be used in the OVO Push To Pay APIs in a Staging/Sandbox environment, consisting of merchantId, storeCode, tid, mid, appid, appkey.
How to get staging credentials? Staging Credentials provided by OVO, on merchant side please provide public key so OVO team can share it encrypted. Please refer to file Client Credential Sharing SOP.
What is production credentials? Production Credentials are special values for the merchants to be used in the OVO Push To Pay APIs in a Production environment, consisting of merchantId, storeCode, tid, mid, appid, appkey.
How to get production credentials? Production Credentials provided by OVO after UAT phase finished & the PKS has completely done, on merchant side please provide public key so OVO team can share it encrypted. Please refer to file Client Credential Sharing SOP.

OVO Stage Account

Question Answer
Is there any dedicated account for test in stage environment? No, partner will use their own OVO stage account.
How to request the account in stage?
  1. For the OVO stage apps download invitation (https://forms.gle/fb7k75ypWyZrnfr37)
  2. For the topup OVO stage balance (https://forms.gle/voDkaPfJEhsgvVb86)
    *notes:
    • For registration, it will perform by user self thru OVO stage apps
    • Only allow Indonesian mobile number
    • The OTP is using 4 last digit phone number
    • Topup balance only able to be executed once user success perform registration in stage
Are the OVO stage apps support for Android & iOS? Yes
Is it allowed for foreign phone number? Currently only allowed for Indonesian phone number
User can't open the download link of OVO stage apps Please ensure the account that is used to receive the invitation is Google-based (for Android) & logged into the Google Playstore or Apple Store using the same account.
Will OVO send the OTP? No
How to get the OTP code? In stage, the OTP uses the last 4 digits of the OVO stage account phone number.
What need to be input during security PIN challenge? During registration in OVO staging apps, a new user will be asked to create a security PIN code.
User getting stuck on verification page User can double tap on the middle of the mobile screen app.

Customer Phone Number Inquiry API

Question Answer
Is it necessary to implement the Customer Phone Number Inquiry API? Optional but OVO suggests merchant to develop this API.
What is the function of the Customer Phone Number Inquiry API? To inquire the customer phone number whether already registered in OVO or not. If not, merchant is required to show the information to the customer. Recommended to use this API before merchant hits the Push To Pay API.
What to do if Customer Phone Number Inquiry API gets RC00? RC00 in the Customer Phone Number Inquiry API means that the customer's phone number has been registered as an OVO account, meaning the API flow can continue to call the Push To Pay API.
What to do if Customer Phone Number Inquiry API returns RC14? RC14 on the Customer Phone Number Inquiry API means that the customer's phone number is not registered as an OVO account, so the API flow cannot continue to call the Push To Pay API. An error notification can be displayed on the front end to the customer to inform that the number has not been registered as an OVO account.

Push To Pay API

Question Answer
Is it necessary to implement the Push To Pay API? Yes, it is mandatory.
What is the function of the Push To Pay API? To produce a Push To Pay notification on the customer OVO apps. The best practice to implement this API is after the Customer Phone Number Inquiry API call.
Push To Pay is using synchronous or asynchronous method? Push To Pay is using synchronous method.
How long can a customer pay after receiving a Push To Pay request? Customer needs to confirm the payment within 55 seconds.
What happens if the customer does not confirm payment on the OVO application within 55 seconds? In this case, OVO will not send any response code. Merchants are required to call the Reversal API after 60 seconds to ensure that if there is any customer's balance deducted, it will be returned immediately. The merchant needs to display on the front end to inform the customer that the payment request already expired/timeout.
How will OVO inform the merchant whether the transaction is successful or not? OVO will send the response to the merchant side once the customer successfully performs the payment on the OVO apps, or if there is any other reason that caused the transaction to fail (except for expired/timeout condition).
What parameter in the body response can the merchant refer to indicate whether the transaction is successful or not? Merchant can refer to the parameter ResponseCode. Please refer to the table of ResponseCode in the technical documentation for more details.
How long will OVO take to send the response to the merchant? Immediately after the customer performs the payment confirmation on OVO apps or if there is any other reason that caused the transaction to fail (except for expired/timeout condition).
What to do if Push To Pay API returns RC00? RC00 in the Push To Pay API means that the customer's balance has been successfully deducted on the OVO side. The merchant side should mark the payment for the transaction as successful and display on the front end to the customer to inform that the OVO payment is completed successfully.
What to do if Push To Pay API returns RC17? RC17 in the Push To Pay API means that the payment request has been rejected by the customer in the OVO application. The merchant side can display on the front end to the customer to inform that the payment request has been canceled by the customer.
What condition makes Push To Pay API return RC26? RC26 in the Push To Pay API means that the OVO backend cannot push payment notifications to the customer's OVO application. Here are some conditions that can cause RC26:
  • The user is not logged into the OVO application.
  • The user does not have the OVO application installed on the device.
  • Obsolete version of the OVO application.
  • Notification service error.
When getting RC26, please advise the customers to:
  • Make sure the customer is using the latest version of the OVO application.
  • Make sure the customer is logged into the OVO application.
  • Make sure the internet connection is good.
What to do if Push To Pay API does not return any RC? Push To Pay API not returning any RC can happen because:
  • Customers do not confirm or cancel payment requests in the OVO application.
  • There was a communication problem between the OVO connection and the merchant, so the response was not received on the merchant's side.
Merchants need to call the Reversal API after 60 seconds and can display on the front end to the customer to inform that the payment request already expired/timeout.
Who will generate the ReferenceNumber, BatchNumber & MerchantInvoice? Merchant side.
Who will generate the merchantId, MID, TID & StoreCode? OVO side.
Does the Push To Pay API support deeplink? No.
Does the Push To Pay API support sending the response to a webview/URL? No.
Is there any method for the ReffNumber usage? Merchant will start using ReffNumber with 000001 for each BatchNumber, and it will increase per hit transaction.
Is there any method for the BatchNumber usage? There are 2 methods:
  1. Date format (e.g., 010123): Merchant can use this method if the counting of hit transactions is under 1 million hit transactions within a day.
  2. Sequence (e.g., 000001, 000002, 000003): Merchant can use this method if the hit transactions exceed 1 million hit transactions within a day.
Please note, BatchNumber increases on a daily basis or when the ReffNumber reaches the maximum (999999).
Is there any concern if the merchant produces the Push To Pay initiation via the merchant Front End instead of Back End? OVO not suggest for this initiation, for Push To Pay integration is using server to server (Backend to Backend) communication between merchant Backend to OVO Backend. If there any issue due the merchant still implementing communication from the Front End, then the risk will be under the merchant side. Aside of the backend communication, merchant should keep secure the credential without exposing to the external parties.
Does the merchant need to show all errors to the customer based on the RC code list? No, the merchant only needs to inform some RC that will be faced by the customer:
  • RC00: Success transaction.
  • RC14: Invalid OVO phone number.
  • RC17: Cancel transaction.
  • RC26: Failed to send Push To Pay notification.
  • No response: Timeout/expired.

Reversal API

Question Answer
Is it necessary to implement the Reversal API? Yes, it is mandatory.
What is the function of the Reversal API? The function of the Reversal API is to return the customer balance when getting deducted but the merchant side didn't get a response from OVO side within 60s. The best practice to implement this API is after the Push To Pay API call. If no response code from OVO is received within the checkout window of 55 seconds + 5 seconds backend buffer, it is recommended to call this API at 65 seconds after the Push To Pay call.
Why does the Reversal API always return RC=00? The Reversal API will always return RC=00 to indicate that the API reversal call was successful.
When the Reversal API returns RC=00, does the customer balance also return to the customer? If the customer successfully performed the payment and the balance was deducted, OVO will return the customer balance immediately. However, if no transaction was performed by the customer, no balance will be returned.
Once the Reversal API is hit by the merchant, how long will it take for the customer balance to be returned? Once the Reversal API is called by the merchant, if there was a customer balance deduction, OVO will return the customer balance immediately.
Can the Reversal API be used as a Void? It is suggested not to use the Reversal API as a Void since they have different conditions. The Reversal API should only be used if the merchant didn't get a response from OVO side within 60 seconds (incident condition). On the other hand, the Void API is used to cancel a successful transaction (the merchant has already received a success payment response and wants to cancel the transaction).

Void API

Question Answer
Is it necessary to implement the Void API? No, it is optional.
What is the function of the Void API? The function of the Void API is to return the customer balance due to cancellation of the successful transaction.
How long can the Void API be invoked? The Void API only supports transactions on the same day they occurred (D+0).
Does the Void API support partial refunds? No, it only applies to the full amount of the transaction.
Since the function of the Void API is the same as the Reversal API (for returning the customer balance), what is the difference between those APIs? Both the Reversal and Void APIs have the same function for returning the customer balance, but they differ in their conditions:
  • The Reversal API is called only if the merchant didn't get a response from OVO within 60 seconds (can be considered an incidental condition).
  • The Void API is called to cancel a successful transaction, meaning the merchant has already received a success payment response.

Check Payment Status API

Question Answer
Is it necessary to implement the Check Payment Status API? No, it is optional.
What is the function of the Check Payment Status API? The function of the Check Payment Status API is to check the transaction status of Push To Pay.
How long can the Push To Pay transaction be checked by the Check Payment Status API? The Check Payment Status API can support checking the Push To Pay transaction status for up to 7 days (24-hour cycle).
What to do if the Check Payment Status API returns RC00? RC00 in the Check Payment Status API means the payment status is successful on the OVO side. It depends on the merchant's policy whether to mark the transaction as a successful transaction or not.
What to do if the Check Payment Status API returns RC25? RC25 in the Check Payment Status API means the payment status is not found on the OVO side. The merchant can mark the payment as still not successful.
How to implement the Check Payment Status API? The Check Payment Status API can be implemented in two methods: Automatic and Manual.
a. Automatic: Merchant will call the Check Payment Status API only if they did not receive any response from OVO within 60 seconds, and before calling the Reversal API. Example:
  • 09:00:00 - Call Push To Pay API
  • 09:01:00 - Expired/timeout (merchant didn't get response from OVO)
  • 09:01:02 - Call Check Payment API
Note:
  • If the Check Payment response returns RC=00, the transaction is found, and the merchant's policy decides whether to mark it as successful.
  • If the Check Payment response returns RC=25, the transaction is not found, and no action is needed.
  • If the Check Payment response returns RC=26, 40, or 58, the merchant should call the Reversal API.
b. Manual: Merchant will call the Check Payment API on an ad-hoc basis.
What date and time will be used when calling the Check Payment API? The date and time from the original Push To Pay transaction will be used.
Is there any concern if the merchant uses the Check Payment Status API below 60s? Yes, since the Push To Pay session lasts 60 seconds, and there is a possibility that the customer is performing the payment near the end of the payment session (55s). It is recommended to call the Check Payment Status API above 60s to get the final payment status.
Are the API only used to check the Push To Pay request? Apart from checking Push To Pay, the Check Payment Status API can also be used to check the Void status.

UAT

Question Answer
What needs to be prepared for UAT?
  1. Conduct the test together with OVO team (can be online).
  2. Set the timestamp to follow GMT+7 JKT time.
  3. Reference numbers increment per transaction and reset once the batch changes.
  4. Batch numbers increment daily or when the reference number reaches its maximum (999999). If the transaction count is under 999999 within a day, it is suggested to set the batch number with the format DDMMYY and change it daily.
  5. During UAT, provide backend logs (request and response) and merchant screen captures for every customer journey scenario. Below are mandatory capture requirements:
    1. Checkout items with the estimated amount to pay.
    2. Select Payment method (OVO) and enter phone number for OVO's Push To Pay.
    3. Waiting for Payment Confirmation, with guidance to check the OVO app to complete the payment.
    4. Payment confirmation for Success (RC.00) and Failed transactions (RC.14, RC.17, timeout, etc.). Map the failed payment confirmation based on the Response Code list.
  6. PTP and Reversal are mandatory APIs to be developed. Void, Inquiry Phone Number, and Check Payment APIs are optional.
  7. The Reversal API will be called after 60 seconds if the merchant didn't get any response within 60 seconds. It is suggested to call it at 65 seconds.