OVO Partner Integration Documentation

BI SNAP Payment API

Stage Credentials Creation Requirements

Question Answer
What are the requirements for staging credentials creation?
  1. a. 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

Production Credentials Creation Requirements

Question Answer
What are the requirements for production credentials creation?
  1. Public Key for sharing credentials (X.509)
  2. Public Key for signature generation (PKCS1)
  3. Provide Callback URL for production: it can be multiple callback URL
  4. Provide IP whitelist
  5. Provide Daily Refund Limit *if partner using Refund
For migration activity, if partner used existing clientid, is there any procedure that partner need to config ? Yes, if partner used existing clientid, the expiry token need to set up into 15 mins as per BI requirement (for non SNAP the default its 8 hours). If partner used any scheduler or service to automate token generate, it must be changed into less than 15 mins.

BI Submission Test

Question Answer
How many test that partner need to do for the BI submission test? There are 2 testing, which is Devsite Testing and Functionality Testing
How partner can get the credentials to do the Devsite Testing? Partner can sign up directly in the BI SNAP Portal https://apidevportal.aspi-indonesia.or.id/
If partner using 3rd party for development, which user that should registered in ASPI website? For partner who use 3rd party, the account user should be the partner name instead of the 3rd party username.
How much the scenario that need to run for Devsite Testing? There will 2 scenario (Positive and Negative) for each the below API:

/api/v1.0/registration-account-binding (API Account Binding)
/api/v1.0/registration-account-unbinding (API Account Unbinding)
/api/v1.0/balance-inquiry (API Balance Inquiry)
/api/v1.0/debit/payment-host-to-host (API Direct Debit Payment)
/api/v1.0/debit/status (API Direct Debit Payment Status)
/api/v1.0/debit/refund (API Direct Debit Payment Refund)

So in total partner need to run 12 scenario.
What partner need to do when already done for the Devsite testing and what document that partner need to send to OVO team? After finished the Devsite Testing, partner can download the results from the BI Portal then partner can send the .pdf document to OVO team through email to [email protected].
For the testing guidance please refer to the google drive "Devsite Testing Video" folder
When the partner can perform the BI Submission Test? Partner can perform the Devsite test once the integration has started & can perform the Functional Test during the development phase
What are the partner need to fill in the functionality testing results document? Partner only need to fill in the Request and Response column with the partner full backend log include the header (cURL), below for the example:

Request:
POST /OVOSNAP/v1.0/oauth/account/registration-account-unbinding HTTP/1.1
Host: https://app.byte-stack.net
Authorization: Bearer 111eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb2RlaGFzaCI6Ik56TmhOakV5WVRRd05URmtOR0V4TUdGalpqVTJPV1kzWVdWak1EWXlNekEiLCJyYW5kb20iOiJOalV5TWpnMU5BIiwidmVyc2lvbiI6MX0.ugKRb-k2ZiU9hFHdpeNW-B2XqW4_2NcSB480cDftjCY
X-EXTERNAL-ID: 1666593760774
X-Partner-ID: oamerchantal
X-Signature: de6716ba730866e05d9921149f62adb8d1727224866bcf57f731a7581f7f356768a3539d08d49544208294f0b5ca2bf6fd656531c42c34a1e9a542e868df2042
X-Timestamp: 2022-10-24T13:42:13.092+07:00
Content-Type: application/json
Content-Length: 53

{""partnerReferenceNo"":""085718159655"",""authCode"":null}"

Response:
{
   "responseCode":"4010700",
   "responseMessage":"Unauthorized. Signature Failed: AGW-002-05."
}
For functional test, does the partner only need to fill table Request & Response? Yes, partner only need to fill column Request & Response.
Please do not change another value since it will be submit to BI (regulator)
How about the scenario that has a note as "Not Eligible" Partner can keep it as is & do not change the value
To whom partner will submit the Devsite & Funtionality Test result? The test result of Devsite Test & Functionalit Test can be submit thru email to [email protected] with cc the OVO Business team
Should partner do the separate scenarios for the "Any Service" in the each sheet? Yes, partner need to do it separately because even if it is state as "Any Service" the API request should be in accordance with the services. For example if in balance inquiry sheet, the end point should be the Balance inquiry API and if its in the Direct Debit sheet the end point should be in any API from Direct Debit (Direct Debit Payment, Status or Refund)
If partner want to go the next step in integration (UAT) do partner have to wait until got the approval from BI? No, partner don't need to wait due to the verification from BI can do it in paralel.
For partner under the PG, do partner need to submit to OVO the for all the BI submission testing? For connection OVO - PG - partner, it's only need 1 times submission to BI . So for the integration between PG and the partner under PG, it will handle by PG it self.

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 userself thru OVO stage apps
- Only allow Indonesian mobile number
- The OTP is using 4 last digit phone number
- Topup balance only able to be execute 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 use for receive the invitation is a google base (for Android) & login 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 use the last 4 digit number of the OVO stage account
What need to be input during security PIN challange? During registration in OVO staging apps, a new user will be asking for create a security PIN code.
User getting stuck on verification page User can double tap on the midle of the mobile screen apps

Secret Key

Question Answer
What is the client-ID & key for running the API? The client-ID & the secret key will be share by OVO to partner side once the partner providing:
- public key
- callback URL
note : The client-id & key will be different for stage & production environment
How to generate the public key & how to decrypted the key? Please refer to file Client Credential Sharing SOP & the Additional Guidance file

Mandatory API

Question Answer
What API is mandatory to be develop by partner? Below is the mandatory API need to be develop by partner:
Linkage
  1. Lookup Phone No
  2. Account Binding
  3. Access Token Request (B2B2C)
  4. Account Unbinding
  5. Generate Token
  6. Generate System Token (B2B) *only if the partner using Refund API
Direct Debit
  1. Balance Inquiry
  2. Direct Debit

Signature Generation

Question Answer
Signature generation classification for each API Transaction Asymetric* (please refer to the pre-request script in the postman collection)
1. Registration Account Binding (/OVOSNAP/v1.0/oauth/account/registration-account-binding)

*this signature used SHA256withRSA to generate the signature with your Private Key as the key but for stringTosign please use HTTPMethod + ”:“+ EndpointUrl + Lowercase(HexEncode(SHA-256(minify(RequestBody)))) + ":“ + TimeStamp

Asymetric
1. B2B2C Binding (OVOSNAP/v1.0/access-token/b2b2c)
2. B2B2C Refresh (OVOSNAP/v1.0/access-token/b2b2c)
3. Get Access Token B2B (OVOSNAP/v1.0/access-token/b2b)

Symetric
1. Unbinding (OVOSNAP/v1.0/oauth/account/registration-account-unbinding)
2. Balance inquiry (OVOSNAP/v1.0/balance-inquiry)
3. DD Payment (OVOSNAP/v1.0/debit/payment-host-to-host)
4. DD Check Status (OVOSNAP/v1.0/debit/status)
5. DD Refund (OVOSNAP/v1.0/debit/refund)

API that use OVO signature (please refer to the pre-request script in the postman collection)
1. Lookup (user/v2/account/lookup?phone)
2. Generate Token (/user/v1/oauth/token?grantType=authorization_code&code=)
3. Top Up Instruction (reference/v1/topup/options)

Tokenization

Question Answer
How many token will be use for this integration & what is the usage? There are 5 tokens which are:
linkageToken : Will get when user perform binding and unbinding request. This token will be use for binding and unbinding process when user open the webview
accessToken : Will be get right after the binding process success. This token will be use for payment, get balance, open the webview, unbinding API
refreshToken : Will be get right after the binding process success. This token will be use for renewal the the accessToken once it expired
singleUseToken : Will get the token after partner hit the API Generate Token ( /user/v1/oauth/token?grantType=authorization_code&code) using the authCode from OVO webview. This token will be use for validate the payment transactions or to make the payment complete.
systemToken/b2b_accessToken : Will get the token after call the OVOSNAP/v1.0/access-token/b2b. This token will be use only for refund.
What is the expiry of each token? accessToken : 15 days
refreshToken : No Expiry (unless user do the unbinding)
linkageToken : 5 minutes
singleUseToken : 15 minutes
systemToken/b2b_accessToken : 15 minutes
What is the treatment if the accessToken getting expired? Partner should call the Refresh Token API using the refreshToken as the authorization.
Does the partner is required to keep the token? Yes, partner need to keep the customer token & also all backend log for all API
What will happen if the customer change the OVO phone number? The accessToken & refreshToken will be broken, in this case partner required to revoke all the customer tokens and remarks the user as unbinded

Binding - Unbinding

Question Answer
Is it possible to have multiple linkage within one partner? No, only allowed for 1 partner account to be linked with 1 OVO account
Are lookup API is mandatory to be develop? Yes, lookup API is mandatory to be develop by partner before the linkage initiation. This is to identify whether the user is eligible to continue for linkage activity or not.
How if getting response as "CAN_REGISTER" when hit the Lookup API? Partner need to inform to the customer to perform registration within OVO apps
What will cause the refreshToken getting broken? The refresh token will be broken if customer do unlink on partner platform, within OVO Apps (Android) & if the customer change their OVO phone number also if the OVO account status from customer is CLOSED
Do partner need to keep the ILP? Yes, aside of the token partner should keep the ILP value
Are the Unbinding API is mandatory to be develop? Yes it's mandatory to be developed by partner
How many for the max attempt OTP to be generated? 5 times, after that user will be temporary blocked for 30 minutes
How many the max attempt for user input the wrong OTP during a binding process? 5 times, after that user will be temporary blocked for 30 minutes
How many the max attempt for user input the wrong Security PIN during a binding/Payment process? 3 times, after that user will be temporary blocked for 1 hours then if user try again until 6 times user will permanently blocked

Callback URL

Question Answer
Who will provide the callback URL? Partner will provide the stage callback URL to be registered in OVO environment
Is it possible to have a dynamic URL address? No, the callback URL should have a static value & should be registered in OVO environment before use by partner
Whether partner can registered multiple callback URL? Yes, it can
How can partner differentiate the callback url for binding, payment and unbinding? The callback URL will be return according to the request, for example:

Request open OVO webview using the below URL:
https://webview.byte-stack.net/cellblockui/partner/activation?authType=2FA&submissionType=redirect&destination=https://piswebblank.pis&action=otpLinkage&phoneNumber=08129376****&refId=56d39eff-cdb6-470c-ac39-c05a9bbd5bd0&client-id=oamerchantam&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb2RlaGFzaCI6Ik1EQm1NbVpoTlRKaE5HUmpORE0zWkdKaFlqbG1ZV0U1TkdVNFl6QmhNMlkiLCJyYW5kb20iOiJOalkwTkRjNE5RIiwidmVyc2lvbiI6MX0.Q_ff6lWbLxkl-b4R9XJ9zhTpT1TmObysfwpc71I26PU

then the reponse will be:
https://piswebblank.pis/?response=%7B%22displayMsg%22%3A%22SUCCESS%22%2C%22displayHeader%22%3A%22%22%2C%22retryAttemptsLeft%22%3A4%2C%22authCode%22%3A%22YOAKdzhRSviBfGyAc15_LQ%22%2C%22errorCode%22%3A%22%22%2C%22enable_redirection%22%3Afalse%7D

So if partner want to differentiate the callback URL for each action, partner differentiate their callback URL accordingly to the action parameter, with notes partner need to registered first the callback url to OVO team .
How partner can identify the transaction by the callback response? Partner can add the state parameter as an identifier of transactions in the url, for example:

https://webview.byte-stack.net/cellblockui/partner/activation?authType=2FA&submissionType=redirect&destination=https://piswebblank.pis&action=otpLinkage&phoneNumber=08129376****&refId=56d39eff-cdb6-470c-ac39-c05a9bbd5bd0&client-id=oamerchantam&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb2RlaGFzaCI6Ik1EQm1NbVpoTlRKaE5HUmpORE0zWkdKaFlqbG1ZV0U1TkdVNFl6QmhNMlkiLCJyYW5kb20iOiJOalkwTkRjNE5RIiwidmVyc2lvbiI6MX0.Q_ff6lWbLxkl-b4R9XJ9zhTpT1TmObysfwpc71I26PU&state=payment1234
For the failed transaction, does OVO informing the partner? Yes, OVO will send the error response
Does the callback URL is support for the error redirection? Yes, partner need to inform OVO side if they want to use URL for the error redirection, it need to be registered in OVO side
How if partner doesn't have error redirection URL? Commonly partner will use a "back" or "home" button provide by partner side
How to request if partner want to an additional callback URL? Partner can send the email request to [email protected] with the below format:

Email subject: Request to add/modify the URL Callback for [Partner Name]
Body Email:

Client-id :
URL:
Type of request: Add/Modify/Delete
What is the SLA for add/modify the callback URL? 3WD

Webview

Question Answer
What will happen if user input the invalid PIN/OTP? If user invalid put the OTP/Security PIN, their page will stop at OVO webview. So there will be no redirection if user do the mistake in webview. Commonly partner will use a "back" or "home" button provide by partner side.
How long the timeout for webview? less than 15 minutes
Who will provide the PIN Webview? OVO will provide the webview
What the parameter that partner will be use to open the webview? To open the webview, the partner needs to include all the query parameters from the body response along with the token, partner callback URL, and submission type. Below is a sample body response:
Body Response:
{
  "responseCode": "2000700",
  "responseMessage": "Success",
  "linkageToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb2RlaGFzaCI6Ik1HWTFNalprWVRKalpETTNORGMwTjJJek9EWmxORGt5TnpSbE0yVTJNV00iLCJyYW5kb20iOiJOalkzTkRnMU9BIiwidmVyc2lvbiI6MX0.XIUcpHaRs0hp3KauGcebSHd-HDV7rG3KHUeli2NPTiA",
  "redirectUrl": "https://webview.byte-stack.net/cellblockui/partner/activation",
  "additionalInfo": {
    "account": {
      "accountStatus": "ACTIVE"
    },
    "qParams": {
      "action": "otpLinkage",
      "authType": "2FA",
      "client-id": "oamerchantam",
      "phoneNumber": "08129376****",
      "refId": "fcfde016-97e0-460e-926a-307860b4a51f"
    }
  }
}
So the webview URL should be:
https://webview.byte-stack.net/cellblockui/partner/activation?authType=2FA&submissionType=redirect&destination=[partner callback url]&action=otpLinkage&phoneNumber=08129376****&refId=fcfde016-97e0-460e-926a-307860b4a51f&client-id=oamerchantam&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb2RlaGFzaCI6Ik1HWTFNalprWVRKalpETTNORGMwTjJJek9EWmxORGt5TnpSbE0yVTJNV00iLCJyYW5kb20iOiJOalkzTkRnMU9BIiwidmVyc2lvbiI6MX0.XIUcpHaRs0hp3KauGcebSHd-HDV7rG3KHUeli2NPTiA

Direct Debit

Question Answer
When the Balance Inquiry API will be use? The Balance Inquiry API is used whenever the partner would like to show the OVO customer balance & before hit Direct Debit API.
It's mandatory to call the Balance Inquiry API before hit the Direct Debit API
Is there any impact if the partner didn't use the Balance Inquiry API before hit the Direct Debit API? Partner will have a lot of failed transaction when the customer have an insufficient balance. OVO side strongly suggest the partner to use this API to reduce the possibility of failed transaction due insufficient balance & it's also impacting the success rate.
Why getting response "Transaction still on process" when initiate the transaction? Because the transaction haven't completely success.
There are 2 step for Direct Debit API:
  1. Initiate the transaction (using accessToken)
  2. Succeeded the transaction (using singleUseToken)
When getting response "Transaction still on process" are the customer balance has been deducted? No, the customer balance will be deducted once success perform the second hit of Direct Debit API (using singleUseToken)
Are the Direct Debit API support idempotecy? Yes the OVO Direct Debit API support for idempotecny
Whether partner need to changes the body request between the 1st call and 2nd call? No need. Partner only need to changes the Authorization in the header.

1st call --> using accessToken
2nd call --> using singleUseToken
Value that can be a benchmark in the Balance Inquiry response? Partner can referring to the balanceType and amount
Who will generate the partnerReferenceNo? It will be generate by partner.
The value should be unique for each transactions.
Is there any timeout for the Direct Debit? the timeout is 15 minutes. After user open the webview

Refund

Question Answer
Step 1. Call the Get Access Token B2B API (OVOSNAP/v1.0/access-token/b2b)
2. Using the b2b accessToken to call the Refund API (OVOSNAP/v1.0/debit/refund)
How long the refund period is allow? Based on business agrrement (Default is 60 days)
Why refund have a specific token? It's because refund can be perform even if the user already unbind from the Partner platfroms.
How if the customer already unbind/unlink from the partner side? The refund process still can be perform, because the Refund API already have a specific token. And the balance will be return to the customer OVO balance.

Inquiry

Question Answer
When the Inquiry Transaction will be used? When the partner want to check the status transaction

Recurring

Question Answer
How if partner want to use recurring feature? If Partner want to use the recurring feature, partner can put "subTransactionType : AUTO"
Is it possible partner have One Time Payment & Recurring under same clientId? Currently it's possible, since partner can confirm that they can differentiate the transactions between one time and recurring. also merchant need to confirm that they will not use the recurring feature for one time payment transactions.
Is there any validation on OVO side to differentiate between recurring and one time payment? Currently there is no validation from OVO side. The decision to choose one time payment or recurring is on merchant side.