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¤cy=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;
}