OVO | Partner Integration Documentation

OVO Partner Integration Documentation

Customer Top Up BI SNAP 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 : Public Key for sharing credentials (X.509) Public Key for signature generation (PKCS1) min and max top up (if any)	Registering partner in OVO BE Staging environment
2	UI/UX Review Requirement : Provide Mockup journey UI/UX	Review the mockup/ UI/UX journey
3	Development Staging	Partner do development in staging environment
4	BI Submission Testing and Functional Test	Partner do testing in https://apidevportal.aspi-indonesia.or.id/ and functional test for for BI requirement
5	UAT OVO Requirement : Share APK/IPA/Web URL for UAT	Do the UAT for each partner platforms with OVO scenario
6	Review UAT	UAT result will be documentation and review by OVO Approver
7	Registration Credential in Production Requirement : 2 Public Key for production credentials (PKCS1 format and X509) IP Public for whitelisted in OVO side min and max top up (if any)	Registering partner in OVO BE production environment

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)

How to generate public key :

Generate the private 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 partner 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, partner need to provide the additional public key with PKCS1 format. Below is the step how to generate the public key with PKCS1 format:

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
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, partner 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:

Top Up Account Inquiry
Top Up Success Flow
Top Up minimum threshold
Amount exceed top up maximum threshold
Input amount exceed user balance

For minimum and maximum top up amount, please refer in this url below : https://www.ovo.id/helpcenter/article/360035974151

Top Up Account Inquiry

Before partner do top up process, Partner must initiated ACCOUNT INQUIRY API first (this is mandatory) the partner will get
Partner must aware that there will be conditions that the Top Up is not allowed, if partner get this response below :

Customer Account not registered in OVO/ Unexist OVO account
"responseCode": "4033718", "responseMessage": "Customer Account Not Found"
Customer account frozen/abnormal
"responseCode": "4033705", "responseMessage": "Account or User Status is Inactive"
Amount Top Up exceed limit Top Up (Balance)
"responseCode": "4033702", "responseMessage": "Exceeds Transaction Amount Limit"
Minimum Amount Top Up Limit
"responseCode": "4043713", "responseMessage": "Invalid Amount"

Top Up Success Flow

Reconfirm for Top Up amount and to destination OVO account, there must be admin fee listed

Success top up page with details Top up (success notif + amount of top up)

Error Message Notification

There were some error code when hit API, Partner need to show this error message below in detail in their platform

Customer Account not registered in OVO/ Unexist OVO account

This sample for response message: 4033718 - Customer Account Not Found

Sample Error Message Notification

Partner can refer to these sample of how the other partner inform user.

Customer Account frozen/abnormal/inactive

This sample for response message: 4033705 - Account or User Status is Inactive
Exceed Amount Limit Top Up

This sample for response message: 4033702 - Exceeds Transaction Amount Limit
Minimum Amount Limit Top Up

This sample for response message: 4043713 - Invalid Amount

Expired AccessToken Case

AccessToken will have specific time expired. Currently the AccessToken expired was 15 mins, and we not allowed to generate token for each transaction. Partner can generate token near expired time (ex : 14 mins)

If the AccessToken is expired then partner will get the error like below when hit Top Up API, and need to generate new AccessToken :


                {

                    "additionalInfo": {

                        "actionables": [

                            {

                                "pinWebviewURL": "https://webview.byte-stack.net/cellblockui/v2/paymentPin",

                                "qParams": {

                                    "action": "regeneratePayment",

                                    "client-id": "oamerchantt"

                                },

                                "token": "PaymentToken"

                            }

                        ],

                        "error": {

                            "code": "OV00502",

                            "message" : "Unauthorized access",

                        }

                    },

                    "responseCode": "4013701",

                    "responseMessage": "Invalid Token: Anda Tidak Memiliki Akses"

                }

Token Handling

Top up API use B2B SystemToken
Those tokens above are used by the OVO system to uniquely identify a user.
The Credentials and Token are confidential information, partner must keep it safe and not share or expose it to the public.
Partner must ensure the security of storing the credentials and token on the partner side to avoid security vulnerabilities.
Partner must generate token before the token expired (< 15 mins), not in each top up transaction.
If the partner use many store/pos under partner control, OVO suggest to use centralize the token.

Backend Log Store

Partner must keep the backend log at at partner side for all API. If there any issue regarding Top Up with OVO, the log will be useful for investigating issue either in staging or production environment.

Sample of log :

Request


                curl --location --request POST 'https://app.byte-stack.net/OVOSNAP/v1.0/emoney/topup' \

                --header 'X-PARTNER-ID: oamerchantam' \

                --header 'X-SCOPE-ID': customer_topup' \

                --header 'X-TIMESTAMP: 2023-09-06T05:02:58.247+07:00' \

                --header 'X-SIGNATURE:

                022436fc0adf99c661d96bc12c0b0ec4a34f134b75f49459349d824927b01a76fb83ea1699594e5c99a544834eedf843f6d830c670f6fd7e5a426af88cf8c8a2' \

                --header 'Authorization: Bearer

                eyJhbGci0iJIUZI1NiIsInR5cc161kpXVCJ9.eyJjb2RlaGFzaC161116RTFObUU0T1ROa05qWT FOR001WkdFd116VmpZalUzTWpNNE5EUmxZalkiLCJyYW5kb20101JNVEUWTnpNNE5q2yIsIn2lcnNpb24i0jF9.8EoHkvTVA03102g6T5 fmrsgfPDCC7yKryCIuR8AsZI4' \

                --header 'Content-Type: application/json' \

                --header 'X-EXTERNAL-ID: sc9imEHK15hyME9e0vTW' \

                --data-raw '{

                    "partnerReferenceNo": "20220728000000001",

                    "customerNumber": "080000000001",

                    "amount": {

                        "value":"10000.00",

                        "currency": "IDR"

                    },

                    "transactionDate": "2022-07-28T10:00:00+07:00",

                    "additionalInfo": {

                        "preInquiryFlag": "N",

                        "senderInstitutionID": "999"

                    }

                }'

Response


                {

                    "responseCode": "2003700",

                    "responseMessage": "Request has been processed succesfully",

                    "referenceNo": "20220728000000001",

                    "partnerReferenceNo": "20220728000000001",

                    "customerNumber": "XXXXXXXX0001",

                    "customerName": "C**tomer Na**",

                    "cusgtomerMonthlyLimit": "40000000",

                    "minAmount": {

                        "value": "10000.00"

                        "currency": "IDR"

                    },

                    "maxAmount": {

                        "value": "20000000.00",

                        "currency": "IDR"

                    },

                    "amount": {

                        "value": "100000.00",

                        "currency": "IDR"

                    },

                    "feeAmount": {

                        "value": "1000.00",

                        "currency": "IDR"

                    },

                    "feeType": "Admin fee",

                    "additionalInfo": {

                        "preInquiryFlag": "N",

                        "senderInstitutionID": "999"

                    }

                }

UAT Process

For UAT partner need to perform :

BI Submission
1. Dev Testing in BI SNAP Website
  https://apidevportal.aspi-indonesia.or.id/
2. Functional Test
* For any query related to the BI Requirement testing , please refer to https://apidevportal.aspi-indonesia.or.id/info
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.

Customer Topup

Customer Top Up BI SNAP Guidance

Integration Step

Generate Public Key for Sharing Credentials (X.509)

Recommended Version

How to generate public key :

Generate the private key

Generate the public key

Generate the private key

Generate the public key

Decrypt the file to extract the client credentials

Generate Public Key for Signature Generation

Generate Private Key

Generate PKCS1 Public Key:

UI/UX Mockup Review

Top Up Account Inquiry

Top Up Success Flow

Error Message Notification

Customer Account not registered in OVO/ Unexist OVO account

Sample Error Message Notification

Customer Account frozen/abnormal/inactive

Exceed Amount Limit Top Up

Minimum Amount Limit Top Up

Expired AccessToken Case

Token Handling

Backend Log Store

Request

Response

UAT Process