OVO

OVO offers 2 payment schemes, which are; 1) OVO Open API that provides Tokenization scheme, and 2) OVO Recurring that provides Recurring scheme.

Integration Steps

Overview of integration process with both OVO Open API and OVO Recurring.

1. Account Binding

2. Balance Inquiry

3. Payment

4. Payment Notification

5. Additional Feature

---

1. Account Binding

Account Binding process should be done before payment can be made and processed. Merchant will send account binding request from customer to DOKU. The request includes customer's phone number that is registered to customer's OVO account.

Each OVO account can only be bind to one customer on one merchant. Customer needs to do verification for account binding process by inputting OTP and PIN.

Account Binding Flow

Account Binding Flow - OVO

API Endpoint

Environment	Endpoint
HTTP Method	POST
API Sandbox	https://api-sandbox.doku.com
API Production	https://api.doku.com
Path	.../direct-debit/core/v1/registration-account-binding

Sample of Request Header, Request Body and Response Body

Notes:

Parameter with (*) is mandatory

Paramater without (*) is optional/conditional

Account Binding

post

/direct-debit/core/v1/registration-account-binding

Header parameters

X-TIMESTAMPstring · utc timestamprequired

Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format

Example: 2020-12-21T07:56:11.000Z

X-SIGNATUREstringrequired

Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)

Example: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5

X-PARTNER-IDstringrequired

Unique ID for a partner (DOKU'S Client ID)

Example: 821508239190

X-EXTERNAL-IDstringrequired

Numeric String. Reference number that should be unique in the same day (request-id)

Example: 418075533589

Authorizationstringrequired

Access Token obtained from Get B2B Token API

Example: 95221

Body

phoneNostringrequired

Phone Number Customer | Format: 628238748728423 | min length: 9 max length: 16 | Mandatory

Example: 628238748728423

additionalInfoobjectrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://{api-domain}/direct-debit/core/v1/registration-account-binding' \
  --header 'X-TIMESTAMP: 2020-12-21T07:56:11.000Z' \
  --header 'X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5' \
  --header 'X-PARTNER-ID: 821508239190' \
  --header 'X-EXTERNAL-ID: 418075533589' \
  --header 'Authorization: 95221' \
  --header 'Content-Type: application/json' \
  --data '{"phoneNo":"628238748728423","additionalInfo":{"channel":"EMONEY_OVO_SNAP","custIdMerchant":"cust-001","customerName":"John Doe","email":"[e-mail]","idCard":"12345","country":"Indonesia","address":"Bali","dateOfBirth":"19990101","successRegistrationUrl":"https://merchant.doku.com/success","failedRegistrationUrl":"https://www.merchant.com/failed"}}'

200

200

{
  "responseCode": "2000700",
  "responseMessage": "Successful",
  "referenceNo": "129260743966",
  "redirectUrl": "https://doku.com/direct-debit/ui/binding/2238230713001534401107183161486001168389",
  "additionalInfo": {
    "custIdMerchant": 12345679504,
    "status": "PENDING",
    "authCode": 2.23823090518282e+39
  }
}

Successful

2. Balance Inquiry

After customer has bind/linked their OVO account, customer can check their account balance infirmation using Balance Inquiry. Merchant will send balance inquiry request from customer to DOKU.

Merchant can also use balance inquiry API to check if customer has sufficient balance before invoking payment process.

Balance Inquiry Flow

Balance Inquiry Flow - OVO

API Endpoint

Environment	Endpoint
HTTP Method	POST
API Sandbox	https://api-sandbox.doku.com
API Production	https://api.doku.com
Path	.../direct-debit/core/v1/balance-inquiry

Sample of Request Header, Request Body and Response Body

Notes:

Parameter with (*) is mandatory

Paramater without (*) is optional/conditional

Balance Inquiry

post

/direct-debit/core/v1/balance-inquiry

Header parameters

X-TIMESTAMPstring · utc timestamprequired

Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format

Example: 2020-12-21T07:56:11.000Z

X-SIGNATUREstringrequired

Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)

Example: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5

X-PARTNER-IDstringrequired

Unique ID for a partner (DOKU'S Client ID)

Example: 821508239190

X-EXTERNAL-IDstringrequired

Numeric String. Reference number that should be unique in the same day (request-id)

Example: 418075533589

Authorization-customerstringrequired

Access token obtained from B2B2C API

Example: Bearer fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a

Authorizationstringrequired

Access Token obtained from Get B2B Token API

Example: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ

Body

additionalInfoobjectrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://{api-domain}/direct-debit/core/v1/balance-inquiry' \
  --header 'X-TIMESTAMP: 2020-12-21T07:56:11.000Z' \
  --header 'X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5' \
  --header 'X-PARTNER-ID: 821508239190' \
  --header 'X-EXTERNAL-ID: 418075533589' \
  --header 'Authorization-customer: Bearer fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a' \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTgwNTA3NDMsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjExLTE2OTY5MTk2NTE5MTgifQ.x-D5VlK6TlVZbLPUSCr-Gbfgh4tnp0QDJmedYFHJGHFjg1c4x39pszU4sLvRhr0Jk0vKdMIzxUZeNhKoesWqDJitnG3kfrNZNsMb_WYUC0tJW91onXzYOKXiTgsHwRNFoWPQHlXIEtT3RQm-SRlCpk_E0gsavgkQn2-kbJEBnPhIs4eKg5IUY9GYi4hRr-_GHsudDl8sd2B5UBB_rHYq36BRmLXH7i7MQADHPsB1ktPVgk3ZWF0jebEjI-lJ88p-omL1vQNvRseXej2HKBa9chGLmPDvXYBQaRmmstHz-tv1boFrHfwsHJebcUec-i3WE1vMvP_3EPXdbqb45N4ciQ' \
  --header 'Content-Type: application/json' \
  --data '{"additionalInfo":{"channel":"EMONEY_OVO_SNAP"}}'

200

200

{
  "responseCode": 2001100,
  "responseMessage": "Successful",
  "accountInfos": [
    {
      "balanceType": "CASH",
      "amount": {
        "value": "10000.00",
        "currency": "IDR"
      },
      "flatAmount": {
        "value": "10000.00",
        "currency": "IDR"
      },
      "holdAmount": {
        "value": "10000.00",
        "currency": "IDR"
      }
    }
  ]
}

Successful

3. Payment

After customer's account is bind/linked and customer has enough balance for payment, merchant can send payment request from customer to DOKU.

Payment - OVO Open API

In OVO Open API, every payment needs to be verified by customer with inputting OTP and/or PIN. In order to do that, merchant needs to bring parameter paymentType : "SALE"in payment request body.

And as the response, merchant will receive parameter webRedirectUrl to redirect the customer to merchant's page/platform to complete the payment by inputting OTP and/or PIN. After the payment is completed, merchant then will receive the notification.

Payment - Recurring

In OVO Recurring, the payment process will be scheduled. Hence, verification using OTP and/or PIN is not required in every payment. Customers only need to do the verification during account binding process and it will give merchant the authorization to run scheduled payment. In order to do that, merchant needs to bring parameter paymentType : "RECURRING"in payment request body.

And as the response, merchant will not receive parameter webRedirectUrl to redirect the customer to merchant's page/platform to complete the payment. Payment request will be directly processed by acquirer and merchant will receive the notification.

Payment Flow

This below payment flow is for OVO Open API.

Payment Flow - OVO Open API

API Endpoint

Environment	Endpoint
HTTP Method	POST
API Sandbox	https://api-sandbox.doku.com
API Production	https://api.doku.com
Path	.../direct-debit/core/v1/debit/payment-host-to-host

Sample of Request Header, Request Body and Response Body

Notes:

Parameter with (*) is mandatory

Paramater without (*) is optional/conditional

Payment

post

/direct-debit/core/v1/debit/payment-host-to-host

Header parameters

X-TIMESTAMPstring · utc timestamprequired

Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format

Example: 2020-12-21T07:56:11.000Z

X-SIGNATUREstringrequired

Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)

Example: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5

X-PARTNER-IDstringrequired

Unique ID for a partner (DOKU'S Client ID)

Example: 821508239190

X-EXTERNAL-IDstringrequired

Numeric String. Reference number that should be unique in the same day (request-id)

Example: 418075533589

Authorization-customerstringrequired

Access token obtained from B2B2C API

Example: Bearer fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a

Authorizationstringrequired

Access Token obtained from Get B2B Token API

Example: 95221

Body

partnerReferenceNostringrequired

Partner Reference No from partner | max: 64 | Mandatory

Example: INV-0001

feeTypestring

Fee type from partner | value should be: OUR/BEN/SHA

Example: OUR

amountobjectrequired

additionalInfoobjectrequired

payOptionDetailsobject[]required

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://{api-domain}/direct-debit/core/v1/debit/payment-host-to-host' \
  --header 'X-TIMESTAMP: 2020-12-21T07:56:11.000Z' \
  --header 'X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5' \
  --header 'X-PARTNER-ID: 821508239190' \
  --header 'X-EXTERNAL-ID: 418075533589' \
  --header 'Authorization-customer: Bearer fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a' \
  --header 'Authorization: 95221' \
  --header 'Content-Type: application/json' \
  --data '{"partnerReferenceNo":"INV-0001","feeType":"OUR","amount":{"value":"10000.00","currency":"IDR"},"additionalInfo":{"channel":"EMONEY_OVO_SNAP","successPaymentUrl":"www.merchant.com/success","failedPaymentUrl":"www.merchant.com/failed","paymentType":"SALE/RECURRING"},"payOptionDetails":[{"payMethod":"CASH","transAmount":{"value":"10000.00","currency":"IDR"},"feeAmount":{"value":"10000.00","currency":"IDR"}}]}'

200

200

{
  "responseCode": "2005400",
  "responseMessage": "Successful",
  "webRedirectUrl": "https://app-uat.doku.com/link/283702597342040",
  "partnerReferenceNo": "INV-0001"
}

Successful

4. Payment Notification

After payment is completed, DOKU will send HTTP Notification to merchant's defined Notification URL.Learn how to handle the notification from DOKU.

5. Additional Feature

Online Refund

This endpoint is used to create refund request for previous successful payment. Merchant can request a transaction refund to DOKU.

Online Refund Flow

Online Refund Flow - OVO

API Endpoint

Environment	Endpoint
HTTP Method	POST
API Sandbox	https://api-sandbox.doku.com
API Production	https://api.doku.com
Path	.../direct-debit/core/v1/debit/refund

Sample of Request Header, Request Body and Response Body

Notes:

Parameter with (*) is mandatory

Paramater without (*) is optional/conditional

Refund

post

/direct-debit/core/v1/debit/refund

Header parameters

X-TIMESTAMPstring · utc timestamprequired

Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format

Example: 2020-12-21T07:56:11.000Z

X-SIGNATUREstringrequired

Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)

Example: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5

X-PARTNER-IDstringrequired

Unique ID for a partner (DOKU'S Client ID)

Example: 821508239190

X-EXTERNAL-IDstringrequired

Numeric String. Reference number that should be unique in the same day (request-id)

Example: 418075533589

Authorizationstringrequired

Access Token obtained from Get B2B Token API

Example: 95221

Body

originalPartnerReferenceNostringrequired

Partner Reference No Purchase Transaction | max: 32 | Mandatory

Example: INV-0001

originalExternalIdstring

External ID Purchase Transaction | max: 36 |

Example: REQ-0001

refundAmountobjectrequired

reasonstring

Reason from customer | max: 255

Example: Request by Customer

partnerRefundNostringrequired

Partner Refund No| max: 64 | Mandatory

Example: INV-REF-0001

additionalInfoobject

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://{api-domain}/direct-debit/core/v1/debit/refund' \
  --header 'X-TIMESTAMP: 2020-12-21T07:56:11.000Z' \
  --header 'X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5' \
  --header 'X-PARTNER-ID: 821508239190' \
  --header 'X-EXTERNAL-ID: 418075533589' \
  --header 'Authorization: 95221' \
  --header 'Content-Type: application/json' \
  --data '{"originalPartnerReferenceNo":"INV-0001","originalExternalId":"REQ-0001","refundAmount":{"value":"10000.00","currency":"IDR"},"reason":"Request by Customer","partnerRefundNo":"INV-REF-0001","additionalInfo":{"channel":"EMONEY_OVO_SNAP"}}'

200

200

{
  "responseCode": "2000700",
  "responseMessage": "Successful",
  "refundAmount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "originalPartnerReferenceNo": "Ra7o1bLJAh2oV9eb33129stQc5xFm5s7",
  "originalReferenceNo": "Ra7o1bLJAh2oV9eb33129stQc5xFm5s7",
  "refundNo": "Ra7o1bLJAh2oV9eb33129stQc5xFm5s7",
  "partnerRefundNo": "Ra7o1bLJAh2oV9eb33129stQc5xFm5s7",
  "refundTime": "2024-01-01T09:09:00.123"
}

Successful

Account Unbinding

If a registered customer no longer wants their account/card to be bind/linked and wish to remove themself from DOKU's and merchant’s system, merchant can send account unbinding request that is initiated by customer.

API Endpoint

Environment	Endpoint
HTTP Method	POST
API Sandbox	https://api-sandbox.doku.com
API Production	https://api.doku.com
Path	.../direct-debit/core/v1/registration-account-unbinding

Sample of Request Header, Request Body and Response Body

Notes:

Parameter with (*) is mandatory

Paramater without (*) is optional/conditional

Account Unbinding

post

/direct-debit/core/v1/registration-account-unbinding

Header parameters

X-TIMESTAMPstring · utc timestamprequired

Client's current local time in yyyy-MM- ddTHH:mm:ssTZD format

Example: 2020-12-21T07:56:11.000Z

X-SIGNATUREstringrequired

Algorithm symmetric signature HMAC_SHA512 (clientSecret, stringToSign)

Example: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5

X-PARTNER-IDstringrequired

Unique ID for a partner (DOKU'S Client ID)

Example: 821508239190

X-EXTERNAL-IDstringrequired

Numeric String. Reference number that should be unique in the same day (request-id)

Example: 418075533589

Authorizationstringrequired

Access Token obtained from Get B2B Token API

Example: 95221

Body

tokenIdstring

format: Value from getTokenB2B2C | max: 2048 | Mandatory

Example: eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTg4MjI3NTQsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjAyLTE2OTAyNzUzNTM3OTgiLCJhY2NvdW50SWQiOiJjZTBhZWIyM2YyMmZhOTgxZWViNTE1MjFmZmNkYmUzNyJ9.QZ2z0p2PoCYbuBSId7LleLqTUwNyNIeM1PUSaV4DwGKO05l7xQ3EbpdAPK62hxKNcczKqQqGY2Om6rzS78s2Tj88dkDD2vl46o3xEPd_plqQW8ayFqS74Z_HcFJfdo-egqFv9rAX7qgiE5AJHSx_hFolET9B3o3Jx82lmQutnXOjYb5gW9PV0FCPIZRWOaXppOSJSVcmTvXZxF0KUID9-2QVmQ5aPZroHjShYJKGyUu-1tCPClD_CbZMCi3TxhKLnI3e2oIoK7VjXEsrJjuil8O1zZTT7_aXAGgTu5UcPCrc0U9_3Nj-wQlEjDpedMVypKAWATWBUVpMo2MAsBRDAw

additionalInfoobject

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://{api-domain}/direct-debit/core/v1/registration-account-unbinding' \
  --header 'X-TIMESTAMP: 2020-12-21T07:56:11.000Z' \
  --header 'X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5' \
  --header 'X-PARTNER-ID: 821508239190' \
  --header 'X-EXTERNAL-ID: 418075533589' \
  --header 'Authorization: 95221' \
  --header 'Content-Type: application/json' \
  --data '{"tokenId":"eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTg4MjI3NTQsImlzcyI6IkRPS1UiLCJjbGllbnRJZCI6IkJSTi0wMjAyLTE2OTAyNzUzNTM3OTgiLCJhY2NvdW50SWQiOiJjZTBhZWIyM2YyMmZhOTgxZWViNTE1MjFmZmNkYmUzNyJ9.QZ2z0p2PoCYbuBSId7LleLqTUwNyNIeM1PUSaV4DwGKO05l7xQ3EbpdAPK62hxKNcczKqQqGY2Om6rzS78s2Tj88dkDD2vl46o3xEPd_plqQW8ayFqS74Z_HcFJfdo-egqFv9rAX7qgiE5AJHSx_hFolET9B3o3Jx82lmQutnXOjYb5gW9PV0FCPIZRWOaXppOSJSVcmTvXZxF0KUID9-2QVmQ5aPZroHjShYJKGyUu-1tCPClD_CbZMCi3TxhKLnI3e2oIoK7VjXEsrJjuil8O1zZTT7_aXAGgTu5UcPCrc0U9_3Nj-wQlEjDpedMVypKAWATWBUVpMo2MAsBRDAw","additionalInfo":{"channel":"EMONEY_OVO_SNAP"}}'

200

200

{
  "responseCode": "2000500",
  "responseMessage": "Successful",
  "referenceNo": "UNB-0001"
}

Successful