# OVO Tokenize Integration Guide

OVO Tokenize is one of Faspay Collection's products which is a digital financial service that makes it easier for users to transaction online at Merchant. This Ovo Tokenize can be embedded directly on the Merchant store application/website, and the Customer can directly pay the bill through the merchant.

The integration process of OVO will be explained below.

## Integration Step

1. [Activation](#id-1.-activation)
2. [Callback Activation](#2.-callback-activation)
3. [Payment](#3.-payment) 
4. [Payment Notification](#3.1-payment-token-expired)
5. [Top Up Instruction](#5.-top-up-instruction)
6. General API: 
   1. [Check Balance](#6.1-check-balance)
   2. [History Transaction](#body-parameter)
   3. [Unlink](#6.3-unlink)

### 1. Activation

This API service is designed to enable the activation of user (customer) accounts, allowing them to be seamlessly integrated into the merchant's website or application. This integration enables customers to make direct payments for transactions on the merchant's page.

**URL EndPoint**

<table><thead><tr><th width="167.33333333333331">Environment</th><th width="265">XML</th><th>JSON</th></tr></thead><tbody><tr><td><strong>Development</strong></td><td><p>https://debit-</p><p>sandbox.faspay.co.id/pws/100037/183xx00010100000/</p></td><td><p>https://debit-</p><p>sandbox.faspay.co.id/cvr/100037/10</p></td></tr></tbody></table>

{% tabs %}
{% tab title="Body Parameter" %}

<table><thead><tr><th width="191">Parameter</th><th width="148">Data Type</th><th width="110">M/O/C</th><th>Description</th></tr></thead><tbody><tr><td>request</td><td>Alphanumeric</td><td>O</td><td>Request description </td></tr><tr><td>merchant_id</td><td>Numeric</td><td>M</td><td>Merchant Code from Faspay = BOI.</td></tr><tr><td>payment_channel</td><td>Numeric(3)</td><td>M</td><td>Channel code </td></tr><tr><td>phone_no</td><td>Numeric(12)</td><td>M</td><td>Customer phone number</td></tr><tr><td>cust_name</td><td>Alphanumeric</td><td>M</td><td>Customer name</td></tr><tr><td>signature</td><td>Alphanumeric</td><td>M</td><td><code>sha1(md5(user_id + password + phone_no))</code></td></tr></tbody></table>
{% endtab %}

{% tab title="Sample Code - XML" %}

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<faspay>
    <request>Account Activation OVO OpenAPI</request>
    <merchant_id>99999</merchant_id>
    <payment_channel>720</payment_channel>
    <phone_no>081382826301</phone_no>
    <cust_name>Andrea Hinata</cust_name>
    <signature>1d4c5f7246a762c4ab61cd3d399efa4c28978bf3</signature>
</faspay>
```

{% endtab %}

{% tab title="Sample Code - JSON" %}

```json
{
  "request": "Account Activation OVO OpenAPI",
  "merchant_id": "99999",
  "payment_channel": "720",
  "phone_no": "081382826301",
  "cust_name": "Andrea Hinata",
  "signature": "1d4c5f7246a762c4ab61cd3d399efa4c28978bf3"
}
```

{% endtab %}
{% endtabs %}

**Activation Response**

You will get the Activation Response following like below:&#x20;

{% tabs %}
{% tab title="Parameter body" %}

<table><thead><tr><th width="183">Parameter</th><th width="150">Data Type</th><th width="101">M/O/C</th><th>Description</th></tr></thead><tbody><tr><td>response</td><td>Alphanumeric</td><td>O</td><td>response description</td></tr><tr><td>status</td><td>Alphanumeric</td><td>M</td><td>Status activation account</td></tr><tr><td>message</td><td>Alphanumeric</td><td>M</td><td>message response activation</td></tr><tr><td>redirectURL</td><td>Alphanumeric</td><td>M</td><td><p>URL redirection to fill in OTP and PIN fields.</p><p><strong>Notes</strong>: Merchant has to redirect with client</p><p>side browser to this URL.</p></td></tr><tr><td>response_code</td><td>Numeric</td><td>M</td><td><p>Response code from sevice API</p><p>00: Success</p><p>01: Failed</p></td></tr><tr><td>response_desc</td><td>Alphanumeric</td><td>M</td><td>Response Description from response code</td></tr></tbody></table>
{% endtab %}

{% tab title="Sample Code - XML" %}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<faspay>
     <response>Account Activation OVO Open API</response>
     <status>ALLOWED</status>
     <message>SUCCESS</message>
     <redirectURL>https://webview.byte-
stack.net/cellblockui/partner/activation?action=otpLinkage&ampauthType=2F
A&ampclient-
id=OAMERCHANTAB&ampphoneNumber=08138282%2A%2A%2A%2A&amprefId=0cdef070-
77e2-42e9-b365-
9a27bb2a0af5&amptoken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb2RlaGFzaC
I6Ik56QTFNRGxrTldZd05UUmxOR013TmprNU56bGhZVFF5TkRGa01UVXlPR1kiLCJyYW5kb20
iOiJOVGcxTmpFeU53IiwidmVyc2lvbiI6MX0.jiWSIoIZ8SfNEwvwX5Y57raYwg0RIfr3Wr3C
hyLwv7M&ampsubmissionType=redirect&ampdestination=https%3A%2F%2Fdebit-
staging.faspay.co.id%2Fpws%2Fovo_openapi%2Fcallback&ampstate=4f260f83e2fa
19f3cf51c082&amptheme=theme1</redirectURL>
     <response_code>00</response_code>
     <response_desc>Success</response_desc>
</faspay>
```

{% endtab %}

{% tab title="Sample Code - JSON" %}

```json
{
  "response": "Account Activation OVO Open API",
  "status": "ALLOWED",
  "message": "SUCCESS",
  "redirectURL": "https://webview.byte-stack.net/cellblockui/partner/activation?action=otpLinkage&ampauthType=2FA&ampclient-id=OAMERCHANTAB&ampphoneNumber=08138282%2A%2A%2A%2A&amprefId=0cdef070-77e2-42e9-b365-9a27bb2a0af5&amptoke=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb2RlaGFzaCI6Ik56QTFNRGxrTldZd05UUmxOR013TmprNU56bGhZVFF5TkRGa01UVXlPR1kiLCJyYW5kb20iOiJOVGcxTmpFeU53IiwidmVyc2lvbiI6MX0.jiWSIoIZ8SfNEwvwX5Y57raYwg0RIfr3Wr3ChyLwv7M&ampsubmissionType=redirect&ampdestination=https%3A%2F%2Fdebit-staging.faspay.co.id%2Fpws%2Fovo_openapi%2Fcallback&ampstate=4f260f83e2fa19f3cf51c082&amptheme=theme1",
  "response_code": "0",
  "response_desc": "Success"
}
```

{% endtab %}
{% endtabs %}

### 2. Callback Activation

This API service is designed to send notifications to the merchant's server, informing them about the status of the user's account activation, whether it has succeeded or failed.

**URL Endpoint**

For Endpoint URL, from the merchant side specifying.

Example:

```
<url-merchant>/callback/linkageovo
```

**Method: GET**

You will get the callback activation response:&#x20;

{% tabs %}
{% tab title="Body Parameter" %}

<table><thead><tr><th width="186">Parameter</th><th width="143">Data Type</th><th width="84">M/O/C</th><th>Description</th></tr></thead><tbody><tr><td>response</td><td>Alphanumeric</td><td>O</td><td>Response description of the Service.</td></tr><tr><td>phone_number</td><td>Numeric</td><td>M</td><td>Phone number user</td></tr><tr><td>response_code</td><td>Numeric</td><td>M</td><td>Response code<br>00: Success</td></tr><tr><td>response_desc</td><td>Alphanumeric</td><td>M</td><td>Response description from response code.</td></tr></tbody></table>
{% endtab %}

{% tab title="Sample Code - XML" %}

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<faspay>
    <response>Account Activation OVO OpenAPI</response>
    <phone_number>081234567891</phone_number>
    <response_code>00</response_code>
    <response_desc>success</response_desc>
</faspay>
```

{% endtab %}

{% tab title="Sample Code - JSON" %}

```json
{
  "response": "Account Activation OVO OpenAPI",
  "phone_number": "081234567891",
  "response_code": "00",
  "response_desc": "success"
}
```

{% endtab %}
{% endtabs %}

### 3. Payment

This API service is designed to handle transactions made by customers using the OVO Tokenize payment method.

**URL Endpoint**

<table><thead><tr><th width="154.33333333333331">Environment</th><th width="284">XML</th><th>JSON</th></tr></thead><tbody><tr><td><strong>Development</strong></td><td><a href="https://debit-
sandbox.faspay.co.id/pws/100038/189xx0001
0100000/">https://debit-<br>sandbox.faspay.co.id/pws/100038/189xx00010100000/</a></td><td><a href="https://debit-
sandbox.faspay.co.id/cvr/100038/10">https://debit-<br>sandbox.faspay.co.id/cvr/100038/10</a></td></tr></tbody></table>

Method: **POST**

{% tabs %}
{% tab title="Body Parameter" %}

<table><thead><tr><th width="187">Parameter</th><th width="154">Data Type</th><th width="87">M/O/C</th><th>Description</th></tr></thead><tbody><tr><td>request</td><td>Alphanumeric</td><td>O</td><td>Request description of service</td></tr><tr><td>merchant_id</td><td>Numeric</td><td>M</td><td>Merchant code from Faspay = BOI.</td></tr><tr><td>bill_no</td><td>Numeric (32)</td><td>M</td><td>Order number</td></tr><tr><td>bill_desc</td><td>Alphanumeric</td><td>M</td><td>Bill description of transaction</td></tr><tr><td>bill_total</td><td>Numeric</td><td>M</td><td>Total nominal transaction</td></tr><tr><td>bill_currency</td><td>Numeric</td><td>M</td><td>Bill currency</td></tr><tr><td>payment_channel</td><td>Numeric</td><td>M</td><td>Payment channel code</td></tr><tr><td>phone_no</td><td>Numeric</td><td>M</td><td>Phone number customer</td></tr><tr><td>cust_name</td><td>Alphanumeric</td><td>M</td><td>Customer name</td></tr><tr><td>email</td><td>Alphanumeric</td><td>M</td><td>Email customer</td></tr><tr><td>pay_type</td><td>Numeric</td><td>M</td><td><p>Payment type:</p><p>0: Cash Only</p><p>1: Points Only</p><p>2: Cash &#x26; Point, priority Point</p></td></tr><tr><td>signature</td><td>Numeric</td><td>M</td><td><code>sha1(md5(user_id + password + phone_no))</code></td></tr></tbody></table>
{% endtab %}

{% tab title="Sample Code Request - XML" %}

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<faspay>
	<request>Transfer OVO OpenAPI</request>
	<merchant_id>99999</merchant_id>
	<bill_no>123</bill_no>
	<bill_desc>prepaid credit transfer.</bill_desc>
	<bill_total>10000</bill_total>
	<bill_currency>IDR</bill_currency>
	<payment_channel>720</payment_channel>
	<phone_no>081382826301</phone_no>
	<cust_name>Andrea Hinata</cust_name>
	<email>andreahinata@email.com</email>
	<pay_type>0</pay_type>
	<signature>1d4c5f7246a762c4ab61cd3d399efa4c28978bf3</signature>
</faspay>
```

{% endtab %}

{% tab title="Sample Code Response - JSON" %}

```json
{
  "request": "Transfer OVO OpenAPI",
  "merchant_id": "99999",
  "bill_no": "123",
  "bill_desc": "prepaid credit transfer.",
  "bill_total": "10000",
  "bill_currency": "IDR",
  "payment_channel": "720",
  "phone_no": "081382826301",
  "cust_name": "Andrea Hinata",
  "email": "andreahinata@gmail.com",
  "pay_type": "0",
  "signature": "1d4c5f7246a762c4ab61cd3d399efa4c28978bf3"
}
```

{% endtab %}
{% endtabs %}

You will get the payment response:&#x20;

{% tabs %}
{% tab title="Body Parameter" %}

<table><thead><tr><th width="167">Parameter</th><th width="157">Data Type</th><th width="90">M/O/C</th><th>Description</th></tr></thead><tbody><tr><td>response</td><td>Alphanumeric</td><td>O</td><td>Response description</td></tr><tr><td>redirectURL</td><td>Alphanumeric</td><td>M</td><td><p>URL redirection to fill in OTP and PIN fields.</p><p><strong>Notes:</strong> Merchant has to redirect with client</p><p>side browser to this URL.</p></td></tr><tr><td>status</td><td>Alphanumeric</td><td>M</td><td>Status transaction</td></tr><tr><td>trx_id</td><td>Alphanumeric</td><td>M</td><td><p>Transaction ID (Issued/generated by Faspay</p><p>(Media Indonusa)) <br><strong>Notes:</strong> Unique</p><p>Transaction ID for 1 day or as long as it hasn't been paid and hasn't expired.</p></td></tr><tr><td>bill_no</td><td>Numeric (32)</td><td>M</td><td>Order number</td></tr><tr><td>amount</td><td>Alphanumeric</td><td>M</td><td>Amount of transaction.</td></tr><tr><td>payment_day</td><td><p>Datetime</p><p>YYYY-MM-DD</p><p>HH:MM:SS (6)</p></td><td>M</td><td>Date of transaction</td></tr><tr><td>response_code</td><td>Numeric</td><td>M</td><td>Response code from service <br>00: Success<br>01: Failed</td></tr><tr><td>response_desc</td><td>Alphanumeric</td><td>M</td><td>Response description of response code.</td></tr></tbody></table>
{% endtab %}

{% tab title="Sample Code Response - XML" %}

```xml
<?xml version="1.0" encodin0g="UTF-8"?>
<faspay>
    <response>Transfer OVO Open API</response>
    <redirectURL>https://webview.byte-
stack.net/cellblockui/v2/paymentPin?clientTxnId=9999982980212147&ampactio
n=payment&ampclient-
id=OAMERCHANTAB&amptoken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb2RlaGF
zaCI6Ik9UUXdNems0TVRSak0yRmtOR0poTkdJNVlUYzVNbVZrTTJWbE1qaGxNVGciLCJyYW5k
b20iOiJOVGcxTmpJeE5RIiwidmVyc2lvbiI6MX0.fI9wW9ODfFoDpG1YhcZl7B8ntTG7uxS6e
AkEVZlYPgY&ampsubmissionType=redirect&ampdestination=https%3A%2F%2Fdebit-
staging.faspay.co.id%2Fpws%2Fovo_openapi%2Fcallback&ampstate=945b59559ca2
a45c9bc1a00c&amptheme=theme1</redirectURL>
    <status>PENDING</status>
    <trx_id>9999982980212147</trx_id>
    <bill_no>123</bill_no>
    <amount>100</amount>
    <payment_day>2021-11-11 11:26:42</payment_day>
    <response_code>00</response_code>
    <response_desc>Success</response_desc>
</faspay>
```

{% endtab %}

{% tab title="Sample Code Response - JSON" %}

```json
{
  "response": "Transfer OVO Open API",
  "redirectURL": "https://webview.byte-stack.net/cellblockui/v2/paymentPin?clientTxnId=9999982980212147&ampaction=payment&ampclient-id=OAMERCHANTAB&amptoken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb2RlaGFzaCI6Ik9UUXdNems0TVRSak0yRmtOR0poTkdJNVlUYzVNbVZrTTJWbE1qaGxNVGciLCJyYW5kb20iOiJOVGcxTmpJeE5RIiwidmVyc2lvbiI6MX0.fI9wW9ODfFoDpG1YhcZl7B8ntTG7uxS6eAkEVZlYPgY&ampsubmissionType=redirect&ampdestination=https%3A%2F%2Fdebit-staging.faspay.co.id%2Fpws%2Fovo_openapi%2Fcallback&ampstate=945b59559ca2a45c9bc1a00c&amptheme=theme1",
  "status": "PENDING",
  "trx_id": "9999982980212147",
  "bill_no": "123",
  "amount": "100",
  "payment_day": "2021-11-11 11:26:42",
  "response_code": "00",
  "response_desc": "Success"
}
```

{% endtab %}
{% endtabs %}

#### 3.1 Payment Token Expired

Abnormal conditions occur when the payment token has passed the given time period (Expired) or the customer updates the phone number in OVO app or it could be from the customer breaking the linkage from partner app.

{% tabs %}
{% tab title="Body Parameter" %}

<table><thead><tr><th>Parameter</th><th>Data Type</th><th width="88">M/O/C</th><th>Description</th></tr></thead><tbody><tr><td>request</td><td>Alphanumeric</td><td>O</td><td>Request description</td></tr><tr><td>merchant_id</td><td>Numeric</td><td>M</td><td>Merchant Code from Faspay = BOI.</td></tr><tr><td>bill_no</td><td>Numeric (32)</td><td>M</td><td>Order number</td></tr><tr><td>bill_desc</td><td>Alphanumeric</td><td>M</td><td>Bill description of transaction</td></tr><tr><td>bill_total</td><td>Numeric</td><td>M</td><td>Total nominal transaction</td></tr><tr><td>bill_currency</td><td>Numeric</td><td>M</td><td>Bill currency</td></tr><tr><td>payment_channel</td><td>Numeric</td><td>M</td><td>Payment channel code</td></tr><tr><td>phone_no</td><td>Numeric</td><td>M</td><td>Phone number customer</td></tr><tr><td>cust_name</td><td>Alphanumeric</td><td>M</td><td>Customer name</td></tr><tr><td>email</td><td>Alphanumeric</td><td>M</td><td>Email customer</td></tr><tr><td>pay_type</td><td>Numeric</td><td>M</td><td><p>Payment type:</p><p>0: Cash Only</p><p>1: Points Only</p><p>2: Cash &#x26; Point, priority Point</p></td></tr><tr><td>signature</td><td>Alphanumeric</td><td>M</td><td><code>sha1(md5(user_id + password + phone_no))</code></td></tr></tbody></table>

{% endtab %}

{% tab title="Sample Code Request - XML" %}

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<faspay>
    <request>Transfer OVO OpenAPI</request>
    <merchant_id>99999</merchant_id>
    <bill_no>123</bill_no>
    <bill_desc>credit purchase transfer</bill_desc>
    <bill_total>10000</bill_total>
    <bill_currency>IDR</bill_currency>
    <payment_channel>720</payment_channel>
    <phone_no>081382826301</phone_no>
    <cust_name>Andrea Hinata</cust_name>
    <email>andreahinata@email.com</email>
    <pay_type>0</pay_type>
    <signature>1d4c5f7246a762c4ab61cd3d399efa4c28978bf3</signature>
</faspay>
```

{% endtab %}

{% tab title="Sample Code Request - JSON" %}

```json
{
  "request": "Transfer OVO OpenAPI",
  "merchant_id": "99999",
  "bill_no": "123",
  "bill_desc": "credit purchase transfer",
  "bill_total": "10000",
  "bill_currency": "IDR",
  "payment_channel": "720",
  "phone_no": "081382826301",
  "cust_name": "Andrea Hinata",
  "email": "andreahinata@gmail.com",
  "pay_type": "0",
  "signature": "1d4c5f7246a762c4ab61cd3d399efa4c28978bf3"
}
```

{% endtab %}
{% endtabs %}

You will get the response:&#x20;

{% tabs %}
{% tab title="Body Parameter" %}

<table><thead><tr><th width="178">Parameter</th><th width="152">Data Type</th><th width="89">M/O/C</th><th>Description</th></tr></thead><tbody><tr><td>response</td><td>Alphanumeric</td><td>O</td><td>Response description</td></tr><tr><td>response_code</td><td>Numeric</td><td>M</td><td><p>Response code from sevice API</p><p>00: Success</p><p>01: Failed</p><p>02: Failed, please regenerate payment token</p></td></tr><tr><td>response_desc</td><td>Numeric</td><td>M</td><td>Response description of response code.</td></tr><tr><td>url</td><td>Alphanumeric</td><td>M</td><td><p>URL Direction to regenerate payment</p><p>tokens.</p></td></tr></tbody></table>
{% endtab %}

{% tab title="Sample Code Response - XML" %}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<faspay>
    <response>Transfer OVO Open API</response>
    <response_code>02</response_code>
    <response_desc>Failed, please regenerate payment token</response_desc>
    <url>https://webview.byte-stack.net/cellblockui/v2/paymentPin?action=regeneratePayment&client-
id=OAMERCHANTAB&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb2RlaGFzaCI6Ik9XTXlNelJsWm1RMlpEZ3pOR1JpTm1FMFl6TmpNV1ptT0RJM1lqZ3lZelUiLCJyYW5kb20iOiJ
OVGt5TmpreU1RIiwidmVyc2lvbiI6MX0.gsoyoo-7CkQdeNAIaeWKlxd4fvwggHcoQcj_kjiaLXM&submissionType=redirect&state=1467becd
693e806472723795&destination=https%3A%2F%2Fdebit-dev.faspay.co.id%2Fpws%2Fovo_openapi%2Fcallback&theme=theme1
    </url>
</faspay>
```

{% endtab %}

{% tab title="Sample Code Response - JSON" %}

```json
{
  "response": "Transfer OVO Open API",
  "response_code": "02",
  "response_desc": "Failed, please regenerate payment token",
  "url": "https://webview.byte-stack.net/cellblockui/v2/paymentPin?action=regeneratePayment&client-id=OAMERCHANTAB&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb2RlaGFzaCI6Ik9XTXlNelJsWm1RMlpEZ3pOR1JpTm1FMFl6TmpNV1ptT0RJM1lqZ3lZelUiLCJyYW5kb20iOiJOVGt5TmpreU1RIiwidmVyc2lvbiI6MX0.gsoyoo-7CkQdeNAIaeWKlxd4fvwggHcoQcj_kjiaLXM&submissionType=redirect&state=a720b840be9f744f513e12ce&destination=https%3A%2F%2Fdebit-dev.faspay.co.id%2Fpws%2Fovo_openapi%2Fcallback&theme=theme1"
}
```

{% endtab %}
{% endtabs %}

### 4. Payment Notification

Payment notification from Faspay to Merchant backend will also be triggered in the event of transaction status getting updated, to ensure the merchant is securely informed. Please provide the URL and make sure it's registered on the Faspay system. The detailed API reference can be found [here](/merchant-integration/api-reference-1/debit-transaction/payment-notification.md).&#x20;

### 5. Top Up Instruction

This API service shows the content of Top Up instructions if the User/Customer wants to make a Top Up transaction.

**URL Endpoint**

<table><thead><tr><th width="152.33333333333331">Environment</th><th>XML</th><th>JSON</th></tr></thead><tbody><tr><td><strong>Development</strong></td><td><a href="https://debit-
sandbox.faspay.co.id/pws/100042/183xx0001
0100000/">https://debit-<br>sandbox.faspay.co.id/pws/100042/183xx00010100000/</a></td><td><a href="https://debit-
sandbox.faspay.co.id/cvr/100042/10">https://debit-<br>sandbox.faspay.co.id/cvr/100042/10</a></td></tr></tbody></table>

**Method: POST**

{% tabs %}
{% tab title="Body Parameter" %}

<table><thead><tr><th>Parameter</th><th>Data Type</th><th width="96">M/O/C</th><th>Description</th></tr></thead><tbody><tr><td>request</td><td>Alphanumeric</td><td>O</td><td>Request description</td></tr><tr><td>merchant_id</td><td>Numeric</td><td>M</td><td>Merchant Code from Faspay = BOI.</td></tr><tr><td>merchant</td><td>Alphanumeric</td><td>M</td><td>Merchant Name</td></tr><tr><td>phone_no</td><td>Numeric</td><td>M</td><td>Customer phone number.</td></tr><tr><td>payment_channel</td><td>Numeric</td><td>M</td><td>OVO Tokenize channel Code.</td></tr><tr><td>signature</td><td>Alphanumeric</td><td>M</td><td><code>sha1(md5(user_id + password + phone_no))</code></td></tr></tbody></table>
{% endtab %}

{% tab title="Sample Code Request - XML" %}

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<faspay>
    <request>Top Up Instruction OVO Open API</request>
    <merchant_id>99999</merchant_id>
    <merchant>FASPAY DEMO</merchant>
    <phone_no>081382826301</phone_no>
    <payment_channel>720</payment_channel>
    <signature>1d4c5f7246a762c4ab61cd3d399efa4c28978bf3</signature>
</faspay>
```

{% endtab %}

{% tab title="Sample code Request - JSON" %}

```json
{
"request": "Top Up Instruction OVO Open API",
"merchant_id": "99999",
"merchant": "FASPAY DEMO",
"phone_no": "081382826301",
"payment_channel": "720",
"signature": "1d4c5f7246a762c4ab61cd3d399efa4c28978bf3"
}
```

{% endtab %}
{% endtabs %}

You will get the top up instruction response:&#x20;

{% tabs %}
{% tab title="Body Parameter" %}

<table><thead><tr><th>Parameter</th><th width="165">Data Type</th><th width="123">M/O/C</th><th>Description</th></tr></thead><tbody><tr><td>request</td><td>Alphanumeric</td><td>O</td><td>Response description.</td></tr><tr><td>merchant_id</td><td>Numeric</td><td>M</td><td>Merchant Code from Faspay = BOI.</td></tr><tr><td>phone_no</td><td>Alphanumeric</td><td>M</td><td>Customer phone number.</td></tr><tr><td>payment_channel</td><td>Numeric</td><td>M</td><td>OVO Tokenize channel Code.</td></tr><tr><td>merchant</td><td>Alphanumeric</td><td>M</td><td>Merchant name</td></tr><tr><td>topup_instruction</td><td>Array</td><td>M</td><td><p>Information on each type of top up</p><p>instruction.</p></td></tr><tr><td>instruction_1</td><td>Array</td><td>M</td><td>Detailed information for Top Up Instruction</td></tr><tr><td>option</td><td>Alphanumeric</td><td>M</td><td><p>Pilihan metode transaksi top up:</p><p>• ATM</p><p>• Internet/Mobile Banking</p><p>• Grab</p><p>• Tokopedia</p><p>• Merchan t/ Mitra OVO</p></td></tr><tr><td>icon</td><td>Alphanumeric</td><td>M</td><td>Url that displays the icon for each type of top up option</td></tr><tr><td>url</td><td>Alphanumeric</td><td>M</td><td><p>The link that will display the top up</p><p>instruction display.</p></td></tr><tr><td>response_code</td><td>Numeric</td><td>M</td><td><p>Response code from sevice API</p><p>00: Success</p><p>01: Failed</p></td></tr><tr><td>response_desc</td><td>Alphanumeric</td><td>M</td><td>Response description of response code.</td></tr></tbody></table>
{% endtab %}

{% tab title="Sample Code Response - XML" %}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<faspay>
	<response>Top Up Instruction OVO Open API</response>
	<phone_no>081382826301</phone_no>
	<merchant_id>99999</merchant_id>
	<payment_channel>720</payment_channel>
	<merchant>FASPAY DEMO</merchant>
	<topup_instruction>
		<instruction_1>
			<option>ATM</option>
			<icon>https://images.ovo.id/fintech/topup/icons/ic_bank_topup.png</icon>
			<url>https://images.ovo.id/fintech/topup/topup_atm.html?20181102</url>
		</instruction_1>
		<instruction_2>
			<option>Internet / Mobile Banking</option>
			<icon>https://images.ovo.id/fintech/topup/icons/ic_mobile_bank_topup.png</icon>
			<url>https://images.ovo.id/fintech/topup/topup_mobile.html?20181102</url>
		</instruction_2>
		<instruction_3>
			<option>Grab</option>
			<icon>https://images.ovo.id/fintech/topup/icons/ic_grab.png</icon>
			<url>https://images.ovo.id/fintech/topup/topup_grab.html</url>
		</instruction_3>
		<instruction_4>
			<option>Tokopedia</option>
			<icon>https://images.ovo.id/fintech/topup/icons/ic_tokopedia.png</icon>
			<url>https://images.ovo.id/fintech/topup/topup_tokopedia.html</url>
		</instruction_4>
		<instruction_5>
			<option>Merchant / Mitra OVO</option>
			<icon>https://images.ovo.id/fintech/topup/icons/ic_merchant_topup.png</icon>
			<url>https://images.ovo.id/fintech/topup/topup_merchant.html?20181102</url>
		</instruction_5>
	</topup_instruction>
	<response_code>00</response_code>
	<response_desc>Success</response_desc>
</faspay>
```

{% endtab %}

{% tab title="Sample Code Response - JSON" %}

```json
{
  "response": "Top Up Instruction OVO Open API",
  "phone_no": "081382826301",
  "merchant_id": "99999",
  "payment_channel": "720",
  "merchant": "FASPAY DEMO",
  "topup_instruction": {
    "instruction_1": {
      "option": "ATM",
      "icon": "https://images.ovo.id/fintech/topup/icons/ic_bank_topup.png",
      "url": "https://images.ovo.id/fintech/topup/topup_atm.html?20181102"
    },
    "instruction_2": {
      "option": "Internet / Mobile Banking",
      "icon": "https://images.ovo.id/fintech/topup/icons/ic_mobile_bank_topup.png",
      "url": "https://images.ovo.id/fintech/topup/topup_mobile.html?20181102"
    },
    "instruction_3": {
      "option": "Grab",
      "icon": "https://images.ovo.id/fintech/topup/icons/ic_grab.png",
      "url": "https://images.ovo.id/fintech/topup/topup_grab.html"
    },
    "instruction_4": {
      "option": "Tokopedia",
      "icon": "https://images.ovo.id/fintech/topup/icons/ic_tokopedia.png",
      "url": "https://images.ovo.id/fintech/topup/topup_tokopedia.html"
    },
    "instruction_5": {
      "option": "Merchant / Mitra OVO",
      "icon": "https://images.ovo.id/fintech/topup/icons/ic_merchant_topup.png",
      "url": "https://images.ovo.id/fintech/topup/topup_merchant.html?20181102"
    }
  },
  "response_code": "00",
  "response_desc": "Success"
}
```

{% endtab %}
{% endtabs %}

### 6. General API

#### 6.1 Check Balance

The General API service checks customer balances for OVO cash and OVO Points.

**URL Endpoint**

<table><thead><tr><th width="159.33333333333331">Environment</th><th width="324">XML</th><th>JSON</th></tr></thead><tbody><tr><td><strong>Development</strong></td><td><a href="https://debit-
sandbox.faspay.co.id/pws/100039/183xx0001
0100000/">https://debit-<br>sandbox.faspay.co.id/pws/100039/183xx00010100000/</a></td><td><a href="https://debit-
sandbox.faspay.co.id/cvr/100039/10">https://debit-<br>sandbox.faspay.co.id/cvr/100039/10</a></td></tr></tbody></table>

Method: **POST**

{% tabs %}
{% tab title="Body Parameter" %}

<table><thead><tr><th>Parameter</th><th>Data Type</th><th width="98">M/O/C</th><th>Description</th></tr></thead><tbody><tr><td>request</td><td>Alphanumeric</td><td>O</td><td>Request description</td></tr><tr><td>merchant_id</td><td>Numeric</td><td>M</td><td>Merchant Code from Faspay = BOI.</td></tr><tr><td>payment_channel</td><td>Numeric</td><td>M</td><td>OVO Tokenize channel Code.</td></tr><tr><td>phone_no</td><td>Numeric</td><td>M</td><td>Customer phone number.</td></tr><tr><td>signature</td><td>Alphanumeric</td><td>M</td><td><code>sha1(md5(user_id + password + phone_no))</code></td></tr></tbody></table>
{% endtab %}

{% tab title="Sample Code Request - XML" %}

```xml
<faspay>
<request>Check Balance OVO OpenAPI</request>
<merchant_id>99999</merchant_id>
<payment_channel>720</payment_channel>
<phone_no>081382826301</phone_no>
<signature>1d4c5f7246a762c4ab61cd3d399efa4c28978bf3</signature>
</faspay>
```

{% endtab %}

{% tab title="Sample Code Request - JSON" %}

```json
{
"request": "Check Balance OVO OpenAPI",
"merchant_id": "99999",
"payment_channel": "720",
"phone_no": "081382826301",
"signature": "1d4c5f7246a762c4ab61cd3d399efa4c28978bf3"
}
```

{% endtab %}
{% endtabs %}

You will get the response:&#x20;

{% tabs %}
{% tab title="Body Parameter" %}

<table><thead><tr><th>Parameter</th><th>Data Type</th><th width="101">M/O/C</th><th>Description</th></tr></thead><tbody><tr><td>response</td><td>Alphanumeric</td><td>O</td><td>Response description</td></tr><tr><td>phone_no</td><td>Alphanumeric</td><td>M</td><td>Customer phone number.</td></tr><tr><td>payment_channel</td><td>Alphanumeric</td><td>M</td><td>Code channel OVO Tokenize</td></tr><tr><td>merchant_id</td><td>Alphanumeric</td><td>M</td><td>Merchant Code from Faspay = BOI.</td></tr><tr><td>detail</td><td>Array</td><td>M</td><td>Detail of data balance channel</td></tr><tr><td>cash</td><td>Array</td><td>M</td><td>Amount of cash balance</td></tr><tr><td>points</td><td>Array </td><td>M</td><td>Number of points earned by the user</td></tr><tr><td>balance</td><td>Numeric</td><td>M</td><td>Amount balance.</td></tr><tr><td>response_code</td><td>Numeric</td><td>M</td><td><p>Response code from sevice API</p><p>00: Success</p><p>01: Failed</p></td></tr><tr><td>response_desc</td><td>Alphanumeric</td><td>M</td><td>Response description</td></tr></tbody></table>

{% endtab %}

{% tab title="Sample Code Response - XML" %}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<faspay>
    <response>Check Balance OVO Open API</response>
    <phone_no>081382826301</phone_no>
    <payment_channel>720</payment_channel>
    <merchant_id>99999</merchant_id>
    <detail>
        <cash>
          <balance>1967700</balance>
        </cash>
        <points>
          <balance>2539434</balance>
        </points>
    </detail>
    <response_code>00</response_code>
    <response_desc>Success</response_desc>
</faspay>
```

{% endtab %}

{% tab title="Sample Code Response - JSON" %}

```json
{
"response": "Check Balance OVO Open API",
"phone_no": "081382826301",
"payment_channel": "720",
"merchant_id": "99999",
"detail": {
    "cash": {
        "balance": "1967700"
     },
    "points": {
        "balance": "2539434"
     }
},
"response_code": "00",
"response_desc": "Success"
}
```

{% endtab %}
{% endtabs %}

#### 6.2 History Transaction

In the General API service, this function is to check mutations or customer transaction history using the OVO Tokenize payment channel.

**URL Endpoint**

<table><thead><tr><th width="164.33333333333331">Environment</th><th>XML</th><th>JSON</th></tr></thead><tbody><tr><td><strong>Development</strong></td><td><a href="https://debit-
staging.faspay.co.id/pws/100041/183xx00010
100000/">https://debit-<br>sandbox.faspay.co.id/pws/100041/183xx00010100000/</a></td><td><a href="https://debit-
staging.faspay.co.id/cvr/100041/10">https://debit-<br>sandbox.faspay.co.id/cvr/100041/10</a></td></tr></tbody></table>

Method: **POST**

{% tabs %}
{% tab title="Body Parameter" %}

<table><thead><tr><th width="186">Parameter</th><th width="162">Data Type</th><th width="107">M/O/C</th><th>Description</th></tr></thead><tbody><tr><td>request</td><td>Alphanumeric</td><td>O</td><td>Request description</td></tr><tr><td>merchant_id</td><td>Numeric</td><td>M</td><td>Merchant code from Faspay = BOI.</td></tr><tr><td>merchant</td><td>Alphanumeric</td><td>M</td><td>Merchant name</td></tr><tr><td>phone_no</td><td>Numeric</td><td>M</td><td>Customer phone number</td></tr><tr><td>payment_channel</td><td>Numeric</td><td>M</td><td>Channel code of OVO</td></tr><tr><td>start_date</td><td><p>Datetime</p><p>YYYY-MM-DD</p></td><td>M</td><td>Start date that you want to view transactions for. starting from today or before from today.</td></tr><tr><td>end_date</td><td><p>Datetime</p><p>YYYY-MM-DD</p></td><td>M</td><td>The date until the last day you want to see the transaction history. End date it can from before today until today.</td></tr><tr><td>page</td><td>Numeric</td><td>M</td><td>Page of view history transaction.</td></tr><tr><td>limit</td><td>Numeric</td><td>M</td><td><p>Number of transactions history displayed</p><p>perpage</p></td></tr><tr><td>signature</td><td>Alphanumeric</td><td>M</td><td><p><code>sha1(md5(user_id + password +</code></p><p><code>phone_no))</code></p></td></tr></tbody></table>
{% endtab %}

{% tab title="Sample Code Request - XML" %}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<faspay>
    <request>History OVO Open API</request>
    <merchant_id>99999</merchant_id>
    <merchant>FASPAY STORE</merchant>
    <phone_no>081382826301</phone_no>
    <payment_channel>720</payment_channel>
    <start_date>2021-11-11</start_date>
    <end_date>2021-11-11</end_date>
    <page>1</page>
    <limit>10</limit>
    <signature>1d4c5f7246a762c4ab61cd3d399efa4c28978bf3</signature>
</faspay>
```

{% endtab %}

{% tab title="Sample Code Request - JSON" %}

```json
{
  "request": "History OVO Open API",
  "merchant_id": "99999",
  "merchant": "FASPAY STORE",
  "phone_no": "081382826301",
  "payment_channel": "720",
  "start_date": "2021-11-11",
  "end_date": "2021-11-11",
  "page": "1",
  "limit": "10",
  "signature": "1d4c5f7246a762c4ab61cd3d399efa4c28978bf3"
}
```

{% endtab %}
{% endtabs %}

You will get the response:&#x20;

{% tabs %}
{% tab title="Body Parameter" %}

<table><thead><tr><th>Parameter</th><th>Data Type</th><th width="85">M/O/C</th><th>Description</th></tr></thead><tbody><tr><td>response</td><td>Alphanumeric</td><td>O</td><td>Response description</td></tr><tr><td>phone_no</td><td>Numeric</td><td>M</td><td>Customer phone number</td></tr><tr><td>merchant_id</td><td>Numeric</td><td>M</td><td>Merchant code from Faspay = BOI.</td></tr><tr><td>payment_channel</td><td>Numeric</td><td>M</td><td>Channel code of OVO</td></tr><tr><td>merchant</td><td>Alphanumeric</td><td>O</td><td>Merchant name</td></tr><tr><td>list_transaction</td><td>Array</td><td>M</td><td>List history transaction customer.</td></tr><tr><td>transaction_(count)</td><td>Array</td><td>M</td><td><p>Number of list history transaction (example:</p><p>transaction_1, transaction_2)</p></td></tr><tr><td>payment_date</td><td><p>Datetime</p><p>YYYY-MM-DD</p><p>HH:MM:SS (6)</p></td><td>M</td><td>Payment date of transaction.</td></tr><tr><td>status</td><td>Alphanumeric</td><td>M</td><td>Status transaction.</td></tr><tr><td>trx_id</td><td>Numeric</td><td>M</td><td><p>Transaction ID (Issued/generated by Faspay (Media Indonusa)) <br><strong>Notes</strong>: Unique</p><p>Transaction ID for 1 day or as long as it</p><p>hasn't been paid and hasn't expired.</p></td></tr><tr><td>trx_amount</td><td>Numeric</td><td>M</td><td>Transaction amount total</td></tr><tr><td>amount_detail</td><td>Array</td><td>M</td><td>Detail amount</td></tr><tr><td>type</td><td>Alphanumeric</td><td>M</td><td>Type of transaction use <strong>Cash</strong> or <strong>Points</strong></td></tr><tr><td>amt</td><td>Numeric</td><td>M</td><td>Amount alocation OVO</td></tr><tr><td>response_code</td><td>Numeric</td><td>M</td><td><p>Response code from sevice API</p><p>00: Success</p><p>01: Failed</p></td></tr><tr><td>response_desc</td><td>Alphanumeric</td><td>M</td><td>Response description of code response</td></tr></tbody></table>

{% endtab %}

{% tab title="Sample Code Response - XML" %}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<faspay>
	<response>History OVO Open API</response>
	<phone_no>081382826301</phone_no>
	<merchant_id>99999</merchant_id>
	<payment_channel>720</payment_channel>
	<merchant>FASPAY STORE</merchant>
	<list_transaction>
		<transaction_1>
			<payment_date>2021-11-11 11:27:34</payment_date>
			<status>SUCCESS</status>
			<trx_id>9999982980212147</trx_id>
			<trx_amount>100</trx_amount>
			<amount_detail>
				<type>CASH</type>
				<amt>100</amt>
			</amount_detail>
		</transaction_1>
		<transaction_2>
			<payment_date>2021-11-11 10:57:31</payment_date>
			<status>SUCCESS</status>
			<trx_id>9999982903353426</trx_id>
			<trx_amount>100</trx_amount>
			<amount_detail>
				<type>CASH</type>
				<amt>100</amt>
			</amount_detail>
		</transaction_2>
		<transaction_3>
			<payment_date>2021-11-11 10:47:59</payment_date>
			<status>SUCCESS</status>
			<trx_id>9999982941269845</trx_id>
			<trx_amount>100</trx_amount>
			<amount_detail>
				<type>CASH</type>
				<amt>100</amt>
			</amount_detail>
		</transaction_3>
	</list_transaction>
	<list_refund/>
	<response_code>00</response_code>
	<response_desc>Sukses</response_desc>
</faspay>
```

{% endtab %}

{% tab title="Sample Code Response - JSON" %}

```json
{
  "response": "History OVO Open API",
  "phone_no": "081382826301",
  "merchant_id": "99999",
  "payment_channel": "720",
  "merchant": "FASPAY STORE",
  "list_transaction": {
    "transaction_1": {
      "payment_date": "2021-11-11 11:27:34",
      "status": "SUCCESS",
      "trx_id": "9999982980212148",
      "trx_amount": "100",
      "amount_detail": {
        "type": "CASH",
        "amt": "100"
      }
    },
    "transaction_2": {
      "payment_date": "2021-11-11 10:57:31",
      "status": "SUCCESS",
      "trx_id": "9999982903353426",
      "trx_amount": "100",
      "amount_detail": {
        "type": "CASH",
        "amt": "100"
      }
    },
    "transaction_3": {
      "payment_date": "2021-11-11 10:47:59",
      "status": "SUCCESS",
      "trx_id": "9999982941269844",
      "trx_amount": "100",
      "amount_detail": {
        "type": "CASH",
        "amt": "100"
      }
    }
  },
  "list_refund": "",
  "response_code": "00",
  "response_desc": "Success"
}
```

{% endtab %}
{% endtabs %}

#### 6.3 Unlink

In the OVO General API service, this function is to disconnect OVO customer account embedded in the previously connected Merchant web/application.

**URL Endpoint**

<table><thead><tr><th width="162.33333333333331">Environment</th><th>XML</th><th>JSON</th></tr></thead><tbody><tr><td><strong>Development</strong></td><td><a href="https://debit-
staging.faspay.co.id/pws/100040/183xx00010
100000/">https://debit-<br>sandbox.faspay.co.id/pws/100040/183xx00010100000/</a></td><td><a href="https://debit-
staging.faspay.co.id/cvr/100040/10">https://debit-<br>sandbox.faspay.co.id/cvr/100040/10</a></td></tr></tbody></table>

Method: **POST**

{% tabs %}
{% tab title="Body Parameter" %}

<table><thead><tr><th>Parameter</th><th width="165">Data Type</th><th width="95">M/O/C</th><th>Description</th></tr></thead><tbody><tr><td>request</td><td>Alphanumeric</td><td>O</td><td>Request description</td></tr><tr><td>merchant_id</td><td>Numeric</td><td>M</td><td>Merchant code from Faspay = BOI.</td></tr><tr><td>merchant</td><td>Alphanumeric</td><td>M</td><td>Merchant name</td></tr><tr><td>phone_no</td><td>Numeric</td><td>M</td><td>Customer phone number</td></tr><tr><td>payment_channel</td><td>Numeric</td><td>M</td><td>Channel code of OVO</td></tr><tr><td>signature</td><td>Alphanumeric</td><td>M</td><td><p><code>sha1(md5(user_id + password +</code></p><p><code>phone_no))</code></p></td></tr></tbody></table>
{% endtab %}

{% tab title="Sample Code Request - XML" %}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<faspay>
	<request>Unlink OVO Open API</request>
	<merchant_id>99999</merchant_id>
	<merchant>FASPAY STORE</merchant>
	<phone_no>081382826301</phone_no>
	<payment_channel>720</payment_channel>
	<signature>1d4c5f7246a762c4ab61cd3d399efa4c28978bf3</signature>
</faspay>
```

{% endtab %}

{% tab title="Sample Code Request - JSON" %}

```json
{
"request": "Unlink OVO Open API",
"merchant_id": "99999",
"merchant": "FASPAY STORE",
"phone_no": "081382826301",
"payment_channel": "720",
"signature": "1d4c5f7246a762c4ab61cd3d399efa4c28978bf3"

```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.faspay.co.id/merchant-integration/api-reference-1/debit-transaction/e-money-channel-integration-guide/ovo-tokenize-integration-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.