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;
}