OVO Partner Integration Documentation

Payment API Guidance

Integration Step

To ensure the confidentiality and secrecy of the client credentials, OVO expects its OpenAPI partners to follow below mentioned SOP to receive the client credentials from OVO.

No Partner Purpose
1 Registration Credential in Staging
Requirement :
  1. Public Key for sharing credentials (X.509)
  2. Public Key for signature generation (PKCS1)
  3. Provide Callback URL for staging : it can be multiple callback URL
Registering partner in OVO BE staging environment
2 UI/UX Review
Requirement : Provide Mockup journey UI/UX		 Review the mockup/ UI/UX journey
3 BI Submission Testing :
- Devsite Testing,
- Functionality Testing		 Partner do testing for BI requirement
4 UAT Testing
Requirement : Share APK/IPA/Web URL for UAT 		Do the UAT for each partner platforms
5 Review UAT UAT result will be documentation and review by OVO Approver
6 Registration Credential in Production
Requirement :
  1. Public Key for staging credentials (with PKCS1 format and X509)
  2. IP Whitelist for whitelisted in OVO side
  3. Provide Callback URL for production: it can be multiple callback URL
  4. Provide Daily Refund Limit
Registering partner in OVO Side (production)

Generate Public Key

Generate Public Key for Sharing Credentials (X.509)

To ensure the confidentiality and secrecy of the client credentials, OVO expects its OpenAPI partners to follow below mentioned SOP to receive the client credentials from OVO.

Step Responsibility
Partner needs to share their public key in .pem format with OVO PIS Team Partner
OVO PIS Team
OVO to generate client credentials. OVO
OVO to generate and share the encrypted .enc files to partner. OVO
Partner needs to decrypt the .enc file to extract the client credentials. Partner
Recommended Version

These versions or later are recommended for generating and decrypting credentials

Program Version
OpenSSL (often in Windows) 1.1.0 or later (2016)
LibreSSL (often in MacOS) 2.9.1 or later (2018)

Generate Public Key for Sharing Credentials :

How to generate public key :
Command
openssl genrsa -des3 -out id_rsa.pem 2048
Generate the public key
Command
openssl rsa -in id_rsa.pem -outform PEM -pubout -out id_rsa.pub.pem

If merchants have it in rsa format (e.g., they use it for ssh), then have them do:

Generate the private key
Command
openssl rsa -in id_rsa -outform pem > id_rsa.pem
Generate the public key
Command
openssl rsa -in id_rsa -pubout -outform pem > id_rsa.pub.pem

Partner need to send id_rsa.pub.pem to OVO

Decrypt the file to extract the client credentials

OVO will share the .enc files to the partner. Partner can execute below mentioned commands to decrypt the .enc file and extract the client credentials.

Command
openssl rsautl -decrypt -inkey id_rsa.pem -in key.bin.enc -out key.bin
openssl enc -d -aes-256-cbc -in cred_file.enc -out cred_file.txt -pass file:./key.bin -md sha256

Generate Public Key for Signature Generation

For signature generation related to SNAP Open API integration, merchant need to provide the additional public key with PKCS1 format. Below is the step how to generate the public key with PKCS1 format:

  1. Generate Private Key
    • For Openssl version 1.x.x
      Command
      openssl genrsa -out private.pem 4096
    • For Openssl version 3.x.x and above
      Command
      openssl genrsa -traditional -out private.pem 4096
  2. Generate PKCS1 Public Key:
    Command
    openssl rsa -in private.pem -RSAPublicKey_out -out public.pem

UI/UX Mockup Review

For the sake of smoothness during UAT later, merchants should provide a UI/UX Mockup that OVO team can review in the beginning of integration process. Please find below for the several points that need to be provide in the UI/UX:

  1. Linkage Process
  2. Showing OVO Balance with 2 conditions:
    • When OVO points are allow
    • When OVO points are not allowed
  3. Unexist OVO Account Case
  4. Unlink process
  5. Payment process
  6. Insufficient balance Case

Linkage Process

In the linkage flow, Partner must called LOOKUP API in the beginning of Linkage (this is Mandatory) then partner will get the account_status from ovo. Partner must aware that there will be 2 conditions that the Linkage is not allowed :

  • BLOCKED_MSISDN,
  • CAN_REGISTER, Conditional
  • LINKED (Suggest not to continue the linkage process)

If partner get one of above account status, Partner must showing the specific error message on the Partner Apps.
After get the account status from Lookup API and the status is ACTIVE or ACTIVE_NO_PIN, then partner can continue to call the Activation API

Linkage Notification

Partner need to showing the specific message in the partner platform whether the Linkage Process is success or not . The aim is to make sure the customer is aware that their OVO account already linkage in to partner platform. For example Partner can show the message through the Pop Up message or the individual screen.

Sample Success Linkage Page

Partner can refer to these sample of how the other partner showing the success linkage message

Fig. 1
Success linkage notification use pop up message


Fig. 2
Success linkage notification use an individual page

Showing OVO Balance

When the linkage process is success, Partner need to show Customer OVO balance. Customer balance has to visible in the partner platforms when user do the payment and also it can be seen in the payment method page.

Sample Showing Balance Page

Partner can refer to these sample of how the other partner showing the OVO balance:

Fig. 3
Showing OVO Balance in the Payment Method Page


Fig. 4
Showing OVO Balance in the Checkout Page

OVO Point Usage

There are two source of found for Payment API in OVO, which are OVO Cash and OVO Points. Partner can use points as default if there was mention in agreement (in this case please liaise with OVO business team). So that for the OVO Points usage it will need some adjustment in merchant side.

If Partner develop OVO Point as their payment method. Partner need to have 2 UI/UX for payment :

  1. The condition that is able to perform payment with using OVO points
  2. The condition that is unable to perform payment using OVO points

Sample Payment Page with and without OVO Points

Partner can refer to these sample:

Fig. 5
Showing OVO Balance in that eligible using OVO Points


Fig. 6
Showing OVO Balance in that unable using OVO Points

OVO Payment Flow

Notes : For partner who integrate both one time payment and recurring (Auto Debt), partner need to redirect user to PIN Webview at their first payment of Auto Debt transactions.


Unlink OVO Account

For the Unlink process, partner can refer to the below journey, and need to showing that unlink success:

Fig. 7
Unlink account flow


Fig. 8
Unlink account success notification use pop up message


Fig. 9
Unlink account success notification use an individual page

Unlink Wording

Below is the unlink wording base on OVO compliance team, and partner have to showing the message while the unlink process.

English Version:

Unlink OVO?
To use your remaining OVO Cash and OVO Points balance, you'll need to reactivate OVO in the [Partner’s Name] App or download OVO app for more functionalities such as P2P transfer and withdrawal to bank account.
Contact [email protected] for more information.
[No]       [Unlink]

Bahasa Version:

Memutus Tautan (Unlink) Akun OVO?
Untuk menggunakan saldo OVO Cash dan OVO Points, Anda harus mengaktifkan kembali Akun OVO Anda pada Aplikasi [Nama Partner] atau download Aplikasi OVO untuk menikmati fungsi-fungsi lainnya seperti transfer dan penarikan dana ke rekening bank.
Hubungi [email protected] atau 1500696 untuk informasi lebih lanjut.
[Tidak]       [Putuskan Tautan]

Unlink Special Case

For the unlink process, it will need the AccessToken as the authorization. However the AccessToken can be invalid, when:

  • User perform unlink in Partner platform
  • User change their phone number on the OVO Apps

For case number 2, usually user will not aware that their action on OVO Apps will impacted to their linkage in the partner side. When they open the partner Apps, they will found can’t neither perform payment or check their ovo balance. It happen because all the token store in Partner was invalid. In this case when user facing this issue they need perform unlink from partner platform. In partner side when called API Unlink with the invalid AccessToken , then OVO will response as below:

{
   "error": {
        "code": "OV00502",
        "message": "Unauthorized access"
   },
   "responseCode": "401XX00",
   "responseMessage": "General unauthorized error (No Interface Def, API is Invalid, Oauth Failed, Verify Client Secret File, Client Forbidden Access API, Unknown Client, Key not Found)"
}

If partner got the above error when called unlink API, please refer to handling token expired.

How to Handle Token Expired

For expired token condition, please use below flow

  1. if access token invalid/expired then call refresh token API
  2. if refresh token API get success => use new access token to continue the process/transaction
  3. if refresh token API get response (401XXXX) unathorized => revoke all token for this customer( mark customer as unlinked)

Sample Page

User changes their phone number in the OVO apps, that will broke the AccessToken :

Fig. 10
User change their phone number in OVO Apps

For the Unlink process keep success in the front end:

Fig. 11
Meanwhile the unlink process keep success

Fig. 12
even though partner received the error in the backend

Insufficient OVO Balance Case

In the partner platforms, when user wants to checkout their transaction then they continue to the payment page , partner need to called Get User Account Balance first. It is intended to make our user aware of their OVO balance is insufficient and customer cannot continue the payment. In this case, partner need to :

  1. Showing the specific error message. E.g “Your OVO balance is not enough for this transaction”
  2. Set to disable the “Pay” / “OVO” button
  3. Add Top Up instructions button

Sample Insufficient Balance Page

Partner can refer to these sample of how the other partner inform to user that their balance is insufficient

Fig. 13
Showing warning message that indicate the OVO balance is not enough and also add the How to Top Up Button

Fig. 14
The OVO payment method button is turn into grey/disabled due to the insufficient OVO balance of customer

Expired AccessToken Case

AccessToken will have specific time expired. Currently the AccessToken expiry is 15 days, if the AccessToken is expired then partner will get the error like below:

{
   "error": {
        "code": "OV00502",
        "message": "Unauthorized access"
   },
   "responseCode": "401XXXX",
   "responseMessage": "General unauthorized error (No Interface Def, API is Invalid, Oauth Failed, Verify Client Secret File, Client Forbidden Access API, Unknown Client, Key not Found)"
}

UAT Process

For UAT partner need to perform :

  1. BI Submission
    1. Dev Testing in BI SNAP Website*
    2. Functional Test
    *For any query related to the BI Requirement testing , please refer to URL https://apidevportal.aspi-indonesia.or.id/
  2. OVO UAT Testing
    1. OVO will conduct the UAT for each partner platforms (ex: if partner develop for 3 platform such as android,ios,desktop then UAT will conducted for each platforms). In this Process, OVO integration team will perform some scenario and documented the UAT result to be submitted to OVO internal reviewer.

Tokens

Token Handling and Backend Log Storage

  1. There are several types of tokens such as LinkageToken, B2B2C AccessToken, RefreshToken, SingleUseToken, and B2B AccessToken.
  2. Those tokens above are used by the OVO system to uniquely identify a user.
  3. The Credentials and Tokens are confidential information, the merchant must keep it safe and not share or expose it to the public,
  4. Merchants must ensure the security of storing the credentials and tokens on the merchant side to avoid security vulnerabilities,
  5. In the process of PIN WebView, If the partner wants to integrate their website or mobile website, we suggest the partner hide the token in the URL
  6. Merchant must keep the backend log at at their side. The backend log will be useful for investigating issue in either a staging or production environment.

Sample OVO Payment Page in the Partner Website

OVO suggest to Partner to hide the token/URL in the front end (in case partner also develop in Website/m-Website version)

Fig. 15
Page in the desktop

Token Expiry

As partner additional info, below for the details of expiration for each token :

  1. B2B2C AccessToken: expiry 15 days
  2. RefreshToken : no expiry
  3. B2B AccessToken / System Token: 15 minutes
  4. All token will be invalid in two condition :
    • Customer perform unlink from partner platforms
    • Customer perform change phone number on OVO apps