# OVO

## Integration Steps

Overview of integration process with OVO.

1. [Account Binding](#id-1.-account-binding)
2. [Balance Inquiry](#id-2.-balance-inquiry)
3. [Payment](#id-3.-payment) 
4. [Payment Notification](#id-4.-payment-notification)
5. [Additional Feature](#id-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**

<figure><img src="https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FRvN7kaQVamKsVj8u8csI%2FOVO%20Flow_Account%20Binding.png?alt=media&#x26;token=1d7ea04e-8a99-4fbf-829f-e9c960f97ce6" alt=""><figcaption><p>Account Binding Flow - OVO</p></figcaption></figure>

**API Endpoint**

<table><thead><tr><th width="176">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/registration-account-binding</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="<https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FLGMZEespXiNIOoWmnsL7%2Fopenapi%20(3).yaml?alt=media&token=a25b6424-d6b3-49d5-98ad-a0697ca30a92>" path="/direct-debit/core/v1/registration-account-binding" method="post" %}
[openapi (3).yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FLGMZEespXiNIOoWmnsL7%2Fopenapi%20\(3\).yaml?alt=media\&token=a25b6424-d6b3-49d5-98ad-a0697ca30a92)
{% endopenapi %}

### 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.&#x20;

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

**Balance Inquiry Flow**

<figure><img src="https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FMas8GqGL76HdymjCgGmE%2F24112023%20Checkout_Balance%20Inquiry.png?alt=media&#x26;token=c849995c-64b8-4f6c-97a4-62bcf3cf3c31" alt=""><figcaption><p>Balance Inquiry Flow - OVO </p></figcaption></figure>

**API Endpoint**

<table><thead><tr><th width="176">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/balance-inquiry</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="<https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FUycHyLC1SJUAwhBGQiDp%2Fopenapi%20(3).yaml?alt=media&token=12610cd8-afd0-4726-aa8f-95e6b86838ea>" path="/direct-debit/core/v1/balance-inquiry" method="post" %}
[openapi (3).yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FUycHyLC1SJUAwhBGQiDp%2Fopenapi%20\(3\).yaml?alt=media\&token=12610cd8-afd0-4726-aa8f-95e6b86838ea)
{% endopenapi %}

### 3. Payment&#x20;

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

#### One Time Payment

For One-Time Payments, each transaction must be verified by the customer by entering an OTP and PIN. To enable this flow, merchants are required to include the parameter `paymentType: "SALE"` in the payment request body.

In response, the merchant will receive a `webRedirectUrl`, which should be used to redirect the customer to complete the payment by entering their OTP and PIN. Once the payment process is completed, the merchant will receive a payment notification confirming the transaction status.

#### Recurring Payment

For OVO Recurring, payments are processed on a scheduled basis. Therefore, OTP and PIN verification is not required for every transaction. Customers only need to complete the verification once during the account binding process, which grants the merchant authorization to execute subsequent scheduled payments.

To initiate this flow, merchants are required to include the parameter `paymentType: "RECURRING"` in the payment request body. In this scheme, the merchant will not receive a `webRedirectUrl`, as no customer redirection is needed. The payment request will be processed directly by the acquirer, and the merchant will receive a notification with the transaction result.

**Payment Flow**

<figure><img src="https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FYUMdh9t3lmovCZx8Rbir%2FOVO%20Flow_Payment%20Sale.png?alt=media&#x26;token=31f71601-ae89-41e6-8df0-629f3f58649d" alt=""><figcaption><p>One Time Payment Flow - OVO</p></figcaption></figure>

<figure><img src="https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F1PpVPaQRVHBkadQflRQC%2FOVO%20Flow_Payment%20Recurring.png?alt=media&#x26;token=e69f0d5b-2d33-471e-9172-bf926e0e3688" alt=""><figcaption><p>Recurring Payment Flow - OVO</p></figcaption></figure>

#### API Endpoint

<table><thead><tr><th width="176">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/payment-host-to-host</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="<https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F0DOQzeTFV1yXf13XpUGj%2Fopenapi%20(3).yaml?alt=media&token=d3f5f369-7eb3-4836-81e8-b6fd718f2add>" path="/direct-debit/core/v1/debit/payment-host-to-host" method="post" %}
[openapi (3).yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F0DOQzeTFV1yXf13XpUGj%2Fopenapi%20\(3\).yaml?alt=media\&token=d3f5f369-7eb3-4836-81e8-b6fd718f2add)
{% endopenapi %}

### 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](https://developers.doku.com/get-started-with-doku-api/notification).

### 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**

<figure><img src="https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FYWPk6oDdUVSrDkVzNakG%2F24112023%20Checkout_Refund.png?alt=media&#x26;token=4932b55a-f1a6-43e9-bde0-22a94e4a2041" alt=""><figcaption><p>Online Refund Flow - OVO</p></figcaption></figure>

#### API Endpoint&#x20;

<table><thead><tr><th width="215">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/debit/refund</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="<https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F2Sj5SX3XxvI4geY3rNBs%2Fopenapi%20(3).yaml?alt=media&token=d37f878e-f005-4f40-8c8d-d47756bef225>" path="/direct-debit/core/v1/debit/refund" method="post" %}
[openapi (3).yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2F2Sj5SX3XxvI4geY3rNBs%2Fopenapi%20\(3\).yaml?alt=media\&token=d37f878e-f005-4f40-8c8d-d47756bef225)
{% endopenapi %}

### 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.

**Account Unbinding Flow**

<figure><img src="https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2FpkdkhNVVgdtWmZGfeArg%2Fimage%20(30).png?alt=media&#x26;token=7c4370f8-4dc5-449f-807d-e4bcda868b64" alt=""><figcaption><p>Account Unbinding Flow - OVO</p></figcaption></figure>

#### API Endpoint&#x20;

<table><thead><tr><th width="199">Environment</th><th>Endpoint</th></tr></thead><tbody><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>API Sandbox</td><td><a href="https://api-sandbox.doku.com">https://api-sandbox.doku.com</a></td></tr><tr><td>API Production</td><td><a href="https://api.doku.com">https://api.doku.com</a></td></tr><tr><td>Path</td><td><code>.../direct-debit/core/v1/registration-account-unbinding</code></td></tr></tbody></table>

**Sample of Request Header, Request Body and Response Body**

Notes:&#x20;

Parameter with (\*) is mandatory&#x20;

Paramater without (\*) is optional/conditional

{% openapi src="<https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2Fs4FdoS120xyJeQvlaqhR%2Fopenapi%20(3).yaml?alt=media&token=17987dfc-41b3-46f8-84a7-5b9a3200c0cf>" path="/direct-debit/core/v1/registration-account-unbinding" method="post" %}
[openapi (3).yaml](https://3092822868-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCxtvLoJNNxvp4U7kLHd%2Fuploads%2Fs4FdoS120xyJeQvlaqhR%2Fopenapi%20\(3\).yaml?alt=media\&token=17987dfc-41b3-46f8-84a7-5b9a3200c0cf)
{% endopenapi %}