OVO Partner Integration Documentation

Additional Guidance BI SNAP

Integration Step

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 URL Callback for payment status (Optional)
 Registering partner in OVO BE staging environment
2 BI Submission Testing :
  • Devsite Testing,
  • Functionality Testing
Partner do testing for BI requirement
3 UAT Testing Do the UAT for each partner platforms
4 Review UAT UAT result will be documentation and review by OVO Approver
5 Registration Credential in Production
Requirement :
  1. Public Key for sharing credentials (X.509)*
  2. Public Key for signature generation (PKCS1)
  3. IP Whitelist for whitelisted in OVO side
  4. Provide URL Callback for payment status (Optional)
 Registering partner in OVO Side (production)

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

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

Partner need to send file public.pem to OVO

Expired AccessToken Case

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

{"responseCode":"401XX00","responseMessage":"Unauthorized. Signature Failed: AGW-002-05."}

If access token invalid/expired then partner can re-generate the accessToken using get Access Token B2B API

Refresh System Token Logic

There are two ways in which a partner can refresh the expired tokens

  1. Proactive approach: Partner proactively generates a new B2B token every 15 min, just when the old token is about to expire. This requires partner to be aware of the expiry beforehand
  2. Reactive approach: Partner reacts to the responseCode returned by OVO. If a responseCode corresponding to expiredToken is received while using the B2B token, the partner need to regenerates the tokens using the above API.
Notes: Merchants should refrain from generating multiple B2B tokens before the expiry. A single token should be created and reused throughout the expiry

QRIS Expired Case

QRIS that generated by partner has the expiry time, as mention in technical document the QRIS will be expired after 75s. For the QRIS expired case, we suggest partner to showing the specific error message.

Integration Testing

For integration testing 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 the URL: https://apidevportal.aspi-indonesia.or.id/

  2. OVO UAT Testing
    1. OVO will conduct the UAT for each partner platforms (ex: if partner develops for 2 platforms such as mobile and desktop, then UAT will be conducted for each platform). In this process, OVO integration team will perform some scenarios and document the UAT results to be submitted to OVO internal reviewer.

Token Handling and Backend Log Storage

  1. AccessTokens are used by the OVO system as the authorization for API call.
  2. TheCredentials and Tokens are confidential information, the merchant must keep it safe and not share or expose it to the public.
  3. Merchants must ensure the security of storing the credentials and tokenson the merchant side to avoid security vulnerabilities. 
  4. 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.
  5. The communication for SNAP Dynamic QRIS integration is backend (server) to backend (server) base, we are not allowed to using communication from Front End/Client Side merchant directly to OVO Server.

Expiry

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

  1. B2B AccessToken / System Token: 15 minutes
  2. QRIS Code : 75s