QRIS API Integration

This section is intended for QRIS partner to integrate with Indodana.

Preparation

To get started, please make sure that you have the MERCHANT_API_KEY and MERCHANT_SECRET_KEY ready.

You also need to make sure that you have access to our staging & production API URLs. The staging API URL is located in https://stg-k-api.indodanafinance.com. The production API URL is located in https://api.indodanafinance.co.id.

Here are preparation list you might required during this integration:

Merchant Account
Merchant API Key
Indodana Staging URL
Indodana Production URL
Whitelist Indodana IP

Authorizing Your Request

The important thing that you need to know when you want to perform a direct integration is the API authentication. By default, all of Indodana Merchant API endpoints are secured and you will need to authenticate your request. To be able to execute the API successfully, you will need to authorize yourself by presenting a valid Authorization header in your HTTP request.

To generate the Authorization header, please refer to the following snippets of code.

const crypto = require('crypto')

const apiKey = '<MERCHANT_API_KEY>'
const secret = '<MERCHANT_SECRET_KEY>'
const nonce = Math.floor(Date.now() / 1000);

const hmac = crypto.createHmac('sha256', secret);
  
var generateAuthorizationHeader = function () {
  const content = `${apiKey}:${nonce}`;
  
  var signature = null
  var authorization = ''
  hmac.on('readable', () => {
    const data = hmac.read();
    if (data) {
      signature = data.toString('hex')
      authorization = `Bearer ${apiKey}:${nonce}:${signature}`
    }
  });
  hmac.write(content);
  hmac.end();
  
  console.log('HTTP Authorization Header')
  console.log('Authorization: ' + authorization)
  
  return authorization
}
generateAuthorizationHeader()

<?php
  $apiKey = '<MERCHANT_API_KEY>';
  $secret = '<MERCHANT_SECRET_KEY>';

  function generateAuthorizationHeader() {
    $nonce = time();

    $string = $apiKey.':'.$nonce;
    $signature = hash_hmac('sha256', $string, $secret);

    echo 'HTTP Authorization Header'.PHP_EOL;
    echo "Authorization: Bearer {$apiKey}:{$nonce}:{$signature}".PHP_EOL;
    
    return "Bearer {$apiKey}:{$nonce}:{$signature}";
  }
?>

As you can see, the content of Authorization header is generated by creating a sha256 hash of apiKey:nonce. The sha256 hash algorithm should take the MERCHANT_SECRET_KEY as the secret key. The example result of the above snippets when you try to ran the code should be as follow

HTTP Authorization Header
Authorization: Bearer sudahlahbossque:1562328997:091e834ec466df5e31b87077134e9d44ac428f515b78055673a2cfa65dbd5956

After you have successfully created the Authorization header, then you can proceed on the next step to develop the integration according to scenario:

Check transaction status
Refund / cancel transaction

QRIS Check Transaction Status

In times of operating, there are several times that you may need to provide / check the status of the transaction (e.g: at the time of customer inquiry, or when you need to synchronize the state of the transaction). Indodana has provided an API endpoint for the merchants to easily check their transaction status.

There are several transaction statuses that the merchant needs to be aware of:

INITIATED - Transaction has been created by Indodana
EXPIRED - Customer failed to complete the transaction
PAID - Transaction passed the fraud detection and is confirmed to-be-paid by Indodana
REJECTED - If the transactions is identified as fraudulent transactions or in blacklisted merchants

It's really simple to check your transaction status. This is the code that will be required to perform the transaction status check.

const Promise = require('bluebird')
const superagent = Promise.promisifyAll(require('superagent'));
const path = require('path')

// Variable authorization should contain value of : 
//    'Bearer <api-key>:<nonce>:<signature>'
var authorization = generateAuthorizationHeader()

var baseUrl = "https://stg-k-api.indodanafinance.com/chermes/merchant"
var endpoint = `${baseUrl}/v1/transactions/qris/check_status`
  
var payload = {
  "merchantOrderId": "<MERCHANT-ORDER-ID>"
}

superagent
    .get(endpoint)
    .set('Authorization', authorization)
    .query(payload)
    .send()
    .endAsync()
    .then(response => {
      // Do something with response.body
      console.log(response.body)
    })
    .catch(err => {
      // Handle error
      console.log(err.response.text)
    });

The sample responses (successful & error responses) that are possibly returned by the API can be found in the section of API Reference > Sample API Request & Response > QRIS Check Transaction Status.

Purchase Transaction Cancellation / Refund

Merchant is able to void / cancel a completed transaction. Note that, there are two types of cancellation. The first is FULL CANCELLATION - when the amount that is posted in the Refund / Cancellation request is the same as the transaction amount. The second is PARTIAL CANCELLATION - when the amount that is posted in the Refund / Cancellation request is different / less than the transaction amount.

It is required for merchant to include the cancellation reason, the preferred cancellation reason that given to Indodana are:

Expired - when the seller does not give a response for the transaction after the predetermined time
Out of Stock - when the seller does not give a response for the transaction after the predetermined time
Items Returned - when the customer has cancelled the transaction because there was an issue with the item
Others - any other reason beside the three above

Full Cancellation

const Promise = require('bluebird')
const superagent = Promise.promisifyAll(require('superagent'));
const path = require('path')

// Variable authorization should contain value of : 
//    'Bearer <api-key>:<nonce>:<signature>'
var authorization = generateAuthorizationHeader()

var baseUrl = "https://stg-k-api.indodanafinance.com/chermes/merchant"
var endpoint = `${baseUrl}/v3/order_cancellation`
  
var payload = {
  "refundId":"<MERCHANT-REFUND-ID>",
  "merchantOrderId":"<MERCHANT-ORDER-ID>",
  "cancellationAmount" : 100000,
  "cancellationReason":"Out of stock",
  "cancelledBy":"<SELLER/CUSTOMER>",
  "cancellationDate":"2019-09-12T18:18:18+07:00"
}

superagent
    .post(endpoint)
    .set('Authorization', authorization)
    .send(payload)
    .endAsync()
    .then(response => {
      // Do something with response.body
      console.log(response.body)
    })
    .catch(err => {
      // Handle error
      console.log(err.response.text)
    });

The sample responses (successful & error responses) that are possibly returned by the API can be found in the section of API Reference > Sample API Request & Response > Refund / Purchase Transaction Cancellation / Refund.

Partial Cancellation

const Promise = require('bluebird')
const superagent = Promise.promisifyAll(require('superagent'));
const path = require('path')

// Variable authorization should contain value of : 
//    'Bearer <api-key>:<nonce>:<signature>'
var authorization = generateAuthorizationHeader()

var baseUrl = "https://stg-k-api.indodanafinance.com/chermes/merchant"
var endpoint = `${baseUrl}/v3/order_cancellation`
  
var payload = {
  "refundId":"<MERCHANT-REFUND-ID>",
  "merchantOrderId":"<MERCHANT-ORDER-ID>",
  "cancellationAmount" : 50000,  
  "cancellationReason":"Out of stock",
  "cancelledBy":"<SELLER/CUSTOMER>",
  "cancellationDate":"2019-09-12T18:18:18+07:00"
}

superagent
    .post(endpoint)
    .set('Authorization', authorization)
    .send(payload)
    .endAsync()
    .then(response => {
      // Do something with response.body
      console.log(response.body)
    })
    .catch(err => {
      // Handle error
      console.log(err.response.text)
    });

PreviousDirect API Integration NextIntegrate with E-commerce Plugins

Last updated 17 days ago