NAV
php bash javascript python

Steps

The steps to use the K-Merchant API are the following.

On your "Shops" page in Back Office, click on "Add a new shop" and make sure that you select "Online Shop" as the shop type and then complete the "Callback URL" field (this is the URL where our system sends the callback when a transaction is processed).

To get your API Key click on the icon found in the top-right corner of the Back Office then click on "Account settings".

Use the Generate POST call to generate the token.

Use the Transaction GET call to redirect the user to the API portal interface.

Use the Decrypt POST call/function to decrypt the response sent in Callback URL.

Suggestions

Use the Generate POST call in the background before loading the payout page, this way no one will see the parameters sent in the request.

Attach the Transaction GET URL to the "Pay" redirect button from your payout page to redirect the customer.

Use the function from Decrypt section to decrypt the response, this way you will avoid waiting for another call from our system.

To avoid receiving too many requests from the K-Merchant System you can change the function (from the callback route) that receives the message and write a return "OK" using a die(), that will return to our system a string 'OK' when the message is received. This way we can see that the callback_url was called sucessfully.

Check

/shopType

Check the shop type using the api_key and the shop_id

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://merchant.k-merchant.com/api/v1/check/shopType/1/1',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Api-Version' => 'v1',
        ],
        'json' => [
            'api_key' => '63ae8fc464a936e55d4572c481aa1925680e060d',
            'shop_id' => '117',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
curl -X GET \
    -G "https://merchant.k-merchant.com/api/v1/check/shopType/1/1" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Api-Version: v1" \
    -d '{"api_key":"63ae8fc464a936e55d4572c481aa1925680e060d","shop_id":"117"}'
const url = new URL(
    "https://merchant.k-merchant.com/api/v1/check/shopType/1/1"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Api-Version": "v1",
};

let body = {
    "api_key": "63ae8fc464a936e55d4572c481aa1925680e060d",
    "shop_id": "117"
}

fetch(url, {
    method: "GET",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));
import requests
import json

url = 'https://merchant.k-merchant.com/api/v1/check/shopType/1/1'
payload = {
    "api_key": "63ae8fc464a936e55d4572c481aa1925680e060d",
    "shop_id": "117"
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Api-Version': 'v1'
}
response = requests.request('GET', url, headers=headers, json=payload)
response.json()

Example response (200):

{
    "message": "online | real"
}

Example response (404):

{
    "message": "Api key not assigned to any merchant!"
}

HTTP Request

GET api/v1/check/shopType/{api_key}/{shop_id}

Body Parameters

Parameter Type Status Description
api_key required optional Authentication key generated by request.
shop_id required optional The shop id, it can be seen in the backoffice, Shops section.

/apiKey

Get a merchant id usign the api_key as validation.

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://merchant.k-merchant.com/api/v1/check/apiKey/1',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Api-Version' => 'v1',
        ],
        'json' => [
            'api_key' => '63ae8fc464a936e55d4572c481aa1925680e060d',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
curl -X GET \
    -G "https://merchant.k-merchant.com/api/v1/check/apiKey/1" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Api-Version: v1" \
    -d '{"api_key":"63ae8fc464a936e55d4572c481aa1925680e060d"}'
const url = new URL(
    "https://merchant.k-merchant.com/api/v1/check/apiKey/1"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Api-Version": "v1",
};

let body = {
    "api_key": "63ae8fc464a936e55d4572c481aa1925680e060d"
}

fetch(url, {
    method: "GET",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));
import requests
import json

url = 'https://merchant.k-merchant.com/api/v1/check/apiKey/1'
payload = {
    "api_key": "63ae8fc464a936e55d4572c481aa1925680e060d"
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Api-Version': 'v1'
}
response = requests.request('GET', url, headers=headers, json=payload)
response.json()

Example response (200):

{
    "message": "678"
}

Example response (404):

{
    "message": "Api key not assigned to any merchant!"
}

HTTP Request

GET api/v1/check/apiKey/{api_key}

Body Parameters

Parameter Type Status Description
api_key required optional Authentication key generated by request.

/merchant/level

Get a merchant KYC level using the api_key

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://merchant.k-merchant.com/api/v1/check/merchant/level/1',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Api-Version' => 'v1',
        ],
        'json' => [
            'api_key' => '63ae8fc464a936e55d4572c481aa1925680e060d',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
curl -X GET \
    -G "https://merchant.k-merchant.com/api/v1/check/merchant/level/1" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Api-Version: v1" \
    -d '{"api_key":"63ae8fc464a936e55d4572c481aa1925680e060d"}'
const url = new URL(
    "https://merchant.k-merchant.com/api/v1/check/merchant/level/1"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Api-Version": "v1",
};

let body = {
    "api_key": "63ae8fc464a936e55d4572c481aa1925680e060d"
}

fetch(url, {
    method: "GET",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));
import requests
import json

url = 'https://merchant.k-merchant.com/api/v1/check/merchant/level/1'
payload = {
    "api_key": "63ae8fc464a936e55d4572c481aa1925680e060d"
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Api-Version': 'v1'
}
response = requests.request('GET', url, headers=headers, json=payload)
response.json()

Example response (200):

{
    "message": "1 | 2 | 3"
}

Example response (404):

{
    "message": "Api key not assigned to any merchant!"
}

HTTP Request

GET api/v1/check/merchant/level/{api_key}

Body Parameters

Parameter Type Status Description
api_key required optional Authentication key generated by request.

Merchant

/data

Get shops,cryptos and apiTransactions for a merchant using merchant's api_key.

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://merchant.k-merchant.com/api/v1/merchant/data',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Api-Version' => 'v1',
        ],
        'json' => [
            'api_key' => '63ae8fc464a936e55d4572c481aa1925680e060d',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
curl -X POST \
    "https://merchant.k-merchant.com/api/v1/merchant/data" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Api-Version: v1" \
    -d '{"api_key":"63ae8fc464a936e55d4572c481aa1925680e060d"}'
const url = new URL(
    "https://merchant.k-merchant.com/api/v1/merchant/data"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Api-Version": "v1",
};

let body = {
    "api_key": "63ae8fc464a936e55d4572c481aa1925680e060d"
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));
import requests
import json

url = 'https://merchant.k-merchant.com/api/v1/merchant/data'
payload = {
    "api_key": "63ae8fc464a936e55d4572c481aa1925680e060d"
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Api-Version': 'v1'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200):

{
    "shops": [
        "id: 117",
        "merchantId: 78",
        "type: online",
        "name: Online Shop",
        "address: ",
        "link: https:\/\/online.com",
        "email: [email protected]",
        "manager: Alderson",
        "phone: 1234567890",
        "deleted: 0",
        "created_at: 2019-09-26 08:42:37",
        "updated_at: 2019-09-26 08:42:37"
    ],
    "cryptos": "[KBC,BTC,ETH]",
    "apiTransactions": [
        "block_tx: [ecbad62ab64e90118942c87faa4e595d4bcdbd07cbd6e56391bb72f98c354e61]",
        "signature: 4791852289e53d6463366d66cb0e322f09390bac",
        "shop_id: 117",
        "customer_id: 1",
        "reference: 1",
        "status: validated",
        "created_at :2019-11-20 15:07:32",
        "pos_tx :33a125ec4c799fcab8a367ff1d06009b92b4b45f"
    ]
}

Example response (404):

{
    "message": "Api key not assigned to any merchant or transaction not found!"
}

HTTP Request

POST api/v1/merchant/data

Body Parameters

Parameter Type Status Description
api_key required optional Authentication key generated by request.

Transaction

/

Return API Portal for the customer to be redirected on

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://merchant.k-merchant.com/api/transaction',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Api-Version' => 'v1',
        ],
        'query' => [
            'token' => 'a4aeab96e986019f61854ac0faaaf066399d7aef',
            'currency' => 'BTC|ETH|KBC',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
curl -X GET \
    -G "https://merchant.k-merchant.com/api/transaction?token=a4aeab96e986019f61854ac0faaaf066399d7aef&currency=BTC%7CETH%7CKBC" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Api-Version: v1"
const url = new URL(
    "https://merchant.k-merchant.com/api/transaction"
);

let params = {
    "token": "a4aeab96e986019f61854ac0faaaf066399d7aef",
    "currency": "BTC|ETH|KBC",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Api-Version": "v1",
};

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
import requests
import json

url = 'https://merchant.k-merchant.com/api/transaction'
params = {
  'token': 'a4aeab96e986019f61854ac0faaaf066399d7aef',
  'currency': 'BTC|ETH|KBC'
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Api-Version': 'v1'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()

Example response (200):

{
    "message": "The API Portal"
}

Example response (404):

{
    "message": "Transaction not found"
}

HTTP Request

GET api/transaction

Query Parameters

Parameter Status Description
token required The token generated by the back-end request to /transaction/generate.
currency required The Crypto currency.

/generate

Generate token for the portal request

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://merchant.k-merchant.com/api/v1/transaction/generate',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Api-Version' => 'v1',
        ],
        'json' => [
            'api_key' => '67868976bdd81c3130956c69fd921f88603c5d83',
            'custom_token' => 'a4aeab96e986019f61854ac0faaaf066399d7aef',
            'customer_address' => 'Street no 4',
            'customer_city' => 'Chester',
            'customer_country' => 'United States',
            'customer_email' => '[email protected]',
            'customer_firstname' => 'John',
            'customer_id' => '37887',
            'customer_lastname' => 'Doe',
            'customer_phone' => '123-455-9414',
            'customer_state' => 'CA',
            'customer_zipcode' => '92314',
            'fiat_currency' => 'USD',
            'fiat_amount' => 200.3,
            'order_id' => 6554223,
            'shop_id' => 117,
            'cancel_url' => 'https://shop.com/order-cancelled',
            'redirect_url' => 'https://shop.com/order-completed',
            'signature' => 'b8aee86e809534f8e308c752aec621e07056c76b',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
curl -X POST \
    "https://merchant.k-merchant.com/api/v1/transaction/generate" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Api-Version: v1" \
    -d '{"api_key":"67868976bdd81c3130956c69fd921f88603c5d83","custom_token":"a4aeab96e986019f61854ac0faaaf066399d7aef","customer_address":"Street no 4","customer_city":"Chester","customer_country":"United States","customer_email":"[email protected]","customer_firstname":"John","customer_id":"37887","customer_lastname":"Doe","customer_phone":"123-455-9414","customer_state":"CA","customer_zipcode":"92314","fiat_currency":"USD","fiat_amount":200.3,"order_id":6554223,"shop_id":117,"cancel_url":"https:\/\/shop.com\/order-cancelled","redirect_url":"https:\/\/shop.com\/order-completed","signature":"b8aee86e809534f8e308c752aec621e07056c76b"}'
const url = new URL(
    "https://merchant.k-merchant.com/api/v1/transaction/generate"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Api-Version": "v1",
};

let body = {
    "api_key": "67868976bdd81c3130956c69fd921f88603c5d83",
    "custom_token": "a4aeab96e986019f61854ac0faaaf066399d7aef",
    "customer_address": "Street no 4",
    "customer_city": "Chester",
    "customer_country": "United States",
    "customer_email": "[email protected]",
    "customer_firstname": "John",
    "customer_id": "37887",
    "customer_lastname": "Doe",
    "customer_phone": "123-455-9414",
    "customer_state": "CA",
    "customer_zipcode": "92314",
    "fiat_currency": "USD",
    "fiat_amount": 200.3,
    "order_id": 6554223,
    "shop_id": 117,
    "cancel_url": "https:\/\/shop.com\/order-cancelled",
    "redirect_url": "https:\/\/shop.com\/order-completed",
    "signature": "b8aee86e809534f8e308c752aec621e07056c76b"
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));
import requests
import json

url = 'https://merchant.k-merchant.com/api/v1/transaction/generate'
payload = {
    "api_key": "67868976bdd81c3130956c69fd921f88603c5d83",
    "custom_token": "a4aeab96e986019f61854ac0faaaf066399d7aef",
    "customer_address": "Street no 4",
    "customer_city": "Chester",
    "customer_country": "United States",
    "customer_email": "[email protected]",
    "customer_firstname": "John",
    "customer_id": "37887",
    "customer_lastname": "Doe",
    "customer_phone": "123-455-9414",
    "customer_state": "CA",
    "customer_zipcode": "92314",
    "fiat_currency": "USD",
    "fiat_amount": 200.3,
    "order_id": 6554223,
    "shop_id": 117,
    "cancel_url": "https:\/\/shop.com\/order-cancelled",
    "redirect_url": "https:\/\/shop.com\/order-completed",
    "signature": "b8aee86e809534f8e308c752aec621e07056c76b"
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Api-Version': 'v1'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200):

{
    "token": "a4aeab96e986019f61854ac0faaaf066399d7aef"
}

Example response (404):

{
    "error": [
        "Any of the above parameter not sent!",
        "Any of the above parameter is null!",
        "Api key not assigned to any merchant or KYC level too low!",
        "Callback URL not completed in the shop backoffice!",
        "customer_email parameter is not a valid email!",
        "fiat_amount parameter is not a valid number!",
        "Wrong shop type!",
        "Wrong signature!"
    ]
}

HTTP Request

POST api/v1/transaction/generate

Body Parameters

Parameter Type Status Description
api_key string required Authentication key generated by request.
custom_token string required Unique token generated before request, needed for transaction validation.
customer_address string required In-shop customer's address.
customer_city string required In-shop customer's city.
customer_country string required In-shop customer's country.
customer_email string required In-shop customer's email.
customer_firstname string required In-shop customer's firstname.
customer_id string required In-shop customer's id.
customer_lastname string required In-shop customer's lastname.
customer_phone string required In-shop customer's phone.
customer_state string required In-shop customer's state.
customer_zipcode string required In-shop customer's zipcode.
fiat_currency string required Fiat currency. Example: USD, EUR, GBP.
fiat_amount float required In-shop order amount.
order_id integer required In-shop order id.
shop_id integer required Shop id from your merchant account.
cancel_url string required URL called when the user clicks "Cancel Transaction".
redirect_url string required URL called when transaction is validated in the API Portal, redirecting to in-shop order summary.
signature string required All the above parameters, concatenated into a string without any trim. Ordered alphabetically by parameter key, with SHA1 encryption.

/response/decrypt

Decrypt the response received in the callback_url, sent by the system

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://merchant.k-merchant.com/api/v1/transaction/response/decrypt',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Api-Version' => 'v1',
        ],
        'json' => [
            'api_key' => '63ae8fc464a936e55d4572c481aa1925680e060d',
            'text' => 'U3hGUEhuTGZxbStGTE5ZOTNubHZEeFkrRHVPb1dJWklsTjVETnhROTZHTT0=',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
curl -X POST \
    "https://merchant.k-merchant.com/api/v1/transaction/response/decrypt" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Api-Version: v1" \
    -d '{"api_key":"63ae8fc464a936e55d4572c481aa1925680e060d","text":"U3hGUEhuTGZxbStGTE5ZOTNubHZEeFkrRHVPb1dJWklsTjVETnhROTZHTT0="}'
const url = new URL(
    "https://merchant.k-merchant.com/api/v1/transaction/response/decrypt"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Api-Version": "v1",
};

let body = {
    "api_key": "63ae8fc464a936e55d4572c481aa1925680e060d",
    "text": "U3hGUEhuTGZxbStGTE5ZOTNubHZEeFkrRHVPb1dJWklsTjVETnhROTZHTT0="
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));
import requests
import json

url = 'https://merchant.k-merchant.com/api/v1/transaction/response/decrypt'
payload = {
    "api_key": "63ae8fc464a936e55d4572c481aa1925680e060d",
    "text": "U3hGUEhuTGZxbStGTE5ZOTNubHZEeFkrRHVPb1dJWklsTjVETnhROTZHTT0="
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Api-Version': 'v1'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200):

{
    "id_customer": 3444,
    "id_order": 784,
    "custom_token": "custom_token321dsa31dsadsafs231s",
    "currency": "EUR",
    "amount": "274.00",
    "status": [
        "pending | failed | validated"
    ],
    "error_message": "",
    "signature": "92bb5fc134f9f4e308846ee098229cf445f60823"
}

Example response (404):

{
    "message": "Api key not assigned to any merchant or transaction not found!"
}

HTTP Request

POST api/v1/transaction/response/decrypt

Body Parameters

Parameter Type Status Description
api_key string required Authentication key generated by request.
text string required The text received in callback_url.

Or you can use the PHP function instead of a call to our system

public static function response($action, $apiKey, $string) {
$output = false;
$encrypt_method = "AES-256-CBC";
$key = hash('sha256', $apiKey);
$iv = substr(hash('sha256', $apiKey), 0, 16);
if ($action == 'encrypt') {
$output = openssl_encrypt($string, $encrypt_method, $key, 0, $iv);
$output = base64_encode($output);
} else if ($action == 'decrypt') {
$output = openssl_decrypt(base64_decode($string), $encrypt_method, $key, 0, $iv);
} return $output;
}