OVO Partner Integration Documentation

BI SNAP Dynamic QRIS API

Stage Credentials Creation Requirements

Question Answer
What are the requirements for staging credentials creation?
  1. Public Key for sharing credentials (X.509)
  2. Public Key for signature generation (PKCS1)
  3. Provide URL Callback for payment status (Optional)
What information will be shared with the merchant for the credentials? OVO will share clientId, secret, merchant id, tid, mid
Whether the credentials can be created at store level? Yes, it can

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 URL Callback for payment status (Optional)
  4. Provide IP whitelist
What information will be shared with the merchant for the credentials? OVO will share clientId, secret, merchant id, tid, mid
Whether the credentials can be created at store level? Yes, it can

BI Submission Test

Question Answer
How many tests does the partner need to do for the BI submission test? There are 2 testing, which are Devsite Testing and Functionality Testing
How can the partner 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 the partner is using a 3rd party for development, which user should be registered on the ASPI website? For a partner who uses a 3rd party, the account user should be the partner's name instead of the 3rd party username.
How many scenarios need to be run for Devsite Testing? There are 2 scenarios (Positive and Negative) for each of the below APIs:
  • /api/v1.0/access-token/b2b
  • /api/v1.0/qr/qr-mpm-generate
  • /api/v1.0/qr/qr-mpm-notify
  • /api/v1.0/qr/qr-mpm-query
  • /api/v1.0/qr/qr-mpm-refund
So, in total, the partner needs to run 10 scenarios.
What should the partner do when they have finished the Devsite testing, and what documents need to be sent to the OVO team? After finishing the Devsite Testing, the partner can download the results from the BI Portal, then send the .pdf document to the OVO team through email at [email protected]. For the testing guidance, please refer to the Google Drive folder "Devsite Testing Video."
When can the partner perform the BI Submission Test? The partner can perform the Devsite test once the integration has started and can perform the Functional Test during the development phase.
What does the partner need to fill in the functionality testing results document? The partner only needs to fill in the Request and Response column with the partner's full backend log, including the header (cURL). Below is an example:

Request:
POST /ovosnap/qr-mpm-generate HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb2RlaGFzaCI6IlptVm1OemMxWW1RNE1EUTNOR05rTW1JMVlqZzFOVGN4WVRJd016Sm1ZVEEiLCJyYW5kb20iOiJNVEUzT1RRMk16YyIsInZlcnNpb24iOjF9.R3bheRFIAtiqrat-pFkWXbxrAAi6NTdNRoMkxycoS9A
X-EXTERNAL-ID: 20240130111702000000000184
X-TIMESTAMP: 20240130T11:17:02.682+07:00
CHANNEL-ID: OVO
X-SIGNATURE: DIHCtwZFE5aO+Je0ZXv1LdaT/1PBhTZHY2wWeuO+rj2LGoJRbXQ63NfFmS5e3dquzjBP2ymn59MrQzWS8bZT2g==
X-PARTNER-ID: pertaminastore
Connection: close
Content-Type: application/json
Content-Length: 301
Host: 10.14.236.28:8080

{""terminalId"":""20240125"",""merchantId"":""AJPertamina2024"",""amount"":{""value"":""100000.00"",""currency"":""IDR""},""feeAmount"":{""value"":"""",""currency"":""IDR""},""partnerReferenceNo"":""20240130111655168"",""additionalInfo"":{""deviceId"":""AJPertamina2024"",""channel"":""OVO"",""transactionDate"":""240130"",""allowedSources"":""100""}}
Response:
{
   "data": {
      "actionables": [
         {
           "pinWebviewURL": "https://webview.byte-stack.net/cellblockui/v2/paymentPin",
           "qParams": {"action":"regeneratePayment","client-id":"pertaminastore"},
           "token":"PaymentToken"
         }
      ],
      "error": {"code":"OV00502","message":"Unauthorized access"}
   },
   "responseCode":"4014701",
   "responseMessage":"Invalid Token:Anda Tidak Memiliki Akses"
}
For the functional test, does the partner only need to fill the Request & Response table? Yes, the partner only needs to fill the Request & Response columns.
Please do not change any other values, as they will be submitted to BI (regulator).
To whom will the partner submit the Devsite & Functionality Test result? The test result of Devsite Test & Functional Test can be submitted via email to [email protected] with cc to the OVO Business team.
If the partner wants to move to the next step in integration (UAT), do they need to wait for approval from BI? No, the partner doesn't need to wait, as the verification from BI can be done in parallel.
For a partner under the PG, does the partner need to submit all the BI submission testing to OVO? For the connection OVO - PG - partner, only 1 submission to BI is required. The integration between PG and the partner under PG will be handled by PG itself.

OVO Stage Account

Question Answer
Is there any dedicated account for testing in the stage environment? No, the 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 top-up OVO stage balance: https://forms.gle/voDkaPfJEhsgvVb86

*Notes:
- For registration, it will be performed by the user through the OVO stage apps.
- Only Indonesian mobile numbers are allowed.
- The OTP uses the last 4 digits of the phone number.
- Top-up balance can only be executed once the user has successfully completed registration in the stage environment.
Are the OVO stage apps supported for Android & iOS? Yes
Is it allowed for foreign phone numbers? Currently, only Indonesian phone numbers are allowed.
User can't open the download link of the OVO stage apps Please ensure that the account used to receive the invitation is Google-based (for Android) and logged into the Google Play Store or Apple Store using the same account.
Will OVO send the OTP? No
How to get the OTP code? In the stage environment, the OTP uses the last 4 digits of the OVO stage account phone number.
What needs to be input during the security PIN challenge? During registration in the OVO stage apps, a new user will be asked to create a security PIN code.
User is getting stuck on the verification page The user can double tap in the middle of the mobile screen apps.

Secret Key

Question Answer
What is the client-ID & Secret for running the API? The client-ID & the secret key will be shared by OVO to the partner side once the partner provides:
  • Public key
  • Callback URL (optional)
Note: All the credentials will be different for stage & production environments.
How to generate the public key & how to decrypt the key? Please refer to the file "Client Credential Sharing SOP" & the "Additional Guidance" file.

Mandatory API

Question Answer
What API is mandatory to be developed by the partner?
  • /api/v1.0/access-token/b2b
  • /api/v1.0/qr/qr-mpm-generate
  • /api/v1.0/qr/qr-mpm-query

Signature Generation

Question Answer
Signature generation classification for each API Transaction Asymmetric* (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 uses SHA256withRSA to generate the signature with your Private Key as the key. For stringToSign, use:
HTTPMethod + ":" + EndpointUrl + Lowercase(HexEncode(SHA-256(minify(RequestBody)))) + ":" + TimeStamp

Asymmetric
- B2B Token request (/B2B Token request)

Symmetric
- Generate QR (/api/v1.0/qr/qr-mpm-generate)
- Refund (/api/v1.0/qr/qr-mpm-refund)
- Inquiry Status (/api/v1.0/qr/qr-mpm-query)
- Callback (/api/v1.0/qr/qr-mpm-notify)
What is the difference between X-CLIENT-KEY and X-PARTNER-ID? The client-key and partner key are the same value, but are used for different APIs.

Tokenization

Question Answer
How many tokens will be used for this integration & what is the usage? There is only 1 token:
systemToken/b2b_accessToken: Will get the token after calling /OVOSNAP/v1.0/access-token/b2b. This token will be used for transactional APIs.
What is the expiry of each token? systemToken/b2b_accessToken: 15 minutes
What is the treatment if the accessToken gets expired? The partner needs to re-generate the systemToken/b2b_accessToken again.
Is the partner required to keep the token? Yes, the partner needs to keep the token and also maintain all backend logs for all APIs.

QR Generate

Question Answer
Is it necessary to implement the QRGenerate API? Yes, it is mandatory.
What is the function of the QRGenerate API? The function of the QRGenerate API is to produce a QR payload string. The partner needs to translate this QR payload string into a QR image so that the user can scan it.
What do merchantId and terminalId mean in the body request? The partner can refer to the mid and tid provided by the OVO team.
Can the QR expiry time of 75 seconds be customized? No, it can't. Currently, the 75-second QR expiry time applies to all partners.
What code needs to be generated to QR? The partner can refer to qrStr from the response.
Is it supported for using callback? Yes.
How can the merchant define which allowedSources can be used? It depends on the business deal.
Who will generate the partnerReferenceNo? Is there any standard? The partnerReferenceNo is a unique identifier number generated by the partner, and it must be 12 digits in length.
Is it allowed to use special characters/symbols in the partnerReferenceNo? If allowed, which characters are permitted? Only numeric values are allowed. No special characters are permitted.
Is the partnerReferenceNo supported for idempotency? No.
What is the maximum amount for QR generation? IDR 5,000,000.
How does the partner know whether the transaction has expired or not? The partner can use the API Transaction Status to check the transaction status, and the merchant can refer to the body response.

Callback/Payment Notify

Question Answer
Who will provide the callback? The partner will provide the stage callback to be registered in the OVO environment.
For failed transactions, does OVO inform the partner? No.
When will the partner receive the callback/payment notification from OVO? OVO will only send the callback/payment notification for successful payments.
What should the partner do if OVO doesn't send the callback? The partner needs to call the API query payment.
Does OVO support multiple callback URLs? For SNAP Dynamic QRIS, only 1 merchant is supported per callback URL.

Query Payment

Question Answer
Is it necessary to implement the QRInquiry API? Yes, it is mandatory.
When will the Inquiry Transaction be used? When the partner wants to check the status of a transaction.
Is there any limitation for the partner to call this API? For transactions below 75 seconds, the partner can call this API every 5 seconds. For transactions that exceed 75 seconds, the partner can periodically check the status until they receive the final status.

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/qr/qr-mpm-refund)
Does it support partial refunds? No, only full refunds are supported.
Is there any Refund Period? Only same-day refunds are supported.
Who will generate the partnerRefundNo? The partnerRefundNo is generated by the partner.