Introduction
Paymentz is a simple, fast and reliable payment engine with open architecture. Founded back in 2018 now it is supported and constantly developing by the community of software engineers with bold background in payment and e-wallet systems.
Paymentz Business API - a solution specifically designed for internet businesses in need of multicurrency payment processing. We support all major currencies.
Environments
There are two environments available for integration:
- Production environment: https://business.paymentz.co.uk
Sandbox Environment
Sandbox provides full functionality but it only emulates processing, no actual bank transactions are made. You can use the following PAN for tests:
- 4617611794313933: CONFIRMED as 3-D Secure transaction
- 4626233193837898: DECLINED as 3-D Secure transaction
- 4392963203551251: CONFIRMED as non 3-D Secure transaction
- 4730198364688516: DECLINED as non 3-D Secure transaction
- 4627342642639018: APPROVED PAYOUT
- 4968357931420422: DECLINED PAYOUT
You can use any cardholder name, expiry date and CVV2/CVC2 with these PANs. 3-D Secure is also emulated with a page that doesn’t require any password but only shows you 2 buttons. One button is for successful authentication, another is for failed authentication. Note, that when you choose to fail authentication, order is always declined, no matter what PAN was used.
Production Environment
Once you complete integration with the Sandbox environment you will be provided with Production credentials. These are completely different credentials, not related with the ones on Sandbox. Production always makes real bank transactions, cards from Sandbox are not supported on this environment.
Authentication
curl https://business.paymentz.co.uk/v1/charges \
-H "Authorization: Bearer merchant_private_key"
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_HTTPHEADER => array(
"authorization: Bearer merchant_private_key",
),
));
import http.client
conn = http.client.HTTPSConnection("...")
headers = {
'authorization': "Bearer merchant_private_key",
}
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://business.paymentz.co.uk/api/v1/payouts")
...
.addHeader("content-type", "application/json")
.addHeader("authorization", "Bearer merchant_private_key")
.build();
Response response = client.newCall(request).execute();
Authenticate your account when using the API, by including your secret API key which has been sent via email during registration. Management of your API keys can be done within the Backoffice. Your API keys carry importance and privileges, be sure to store them securely. Please do not share your secret API keys in publicly accessible areas such GitHub and client-side code areas.
Authentication to the API is performed via bearer auth keys (for cross-origin requests), use -H “Authorization: Bearer merchant_private_key”.
All API requests must be made through HTTPS. Calls made through plain HTTP will fail. API requests without authentication will also fail.
Payments
Paymentz payment processing REST API.
Create
Code: Copy
curl "https://business.paymentz.co.uk/api/v1/payments" \
-X POST \
-H "Authorization: Bearer merchant_private_key" \
-H "Content-Type: application/json" -d '{
"product" : "Your Product",
"amount" : "1000",
"currency" : "CNY",
"redirectSuccessUrl" : "https://your-site.com/success",
"redirectFailUrl" : "https://your-site.com/fail",
"extraReturnParam" : "your order id or other info",
"orderNumber" : "your order number",
"locale": "zh"
}'
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://business.paymentz.co.uk/api/v1/payments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{ \"product\" : \"Your Product\", \"amount\" : "10000", \"currency\" : \"CNY\", \"redirectSuccessUrl\" : \"https://your-site.com/success\", \"redirectFailUrl\" : \"https://your-site.com/fail\", \"extraReturnParam\" : \"your order id or other info\", \"orderNumber\" : \"your order number\", \"locale\" : \"zh\"\n}",
CURLOPT_HTTPHEADER => array(
"authorization: Bearer merchant_private_key",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
from django.http import HttpResponseRedirect, HttpResponse
import requests
import json
def pay(request) :
MERCHANT_PRIVATE_KEY = 'merchant_private_key'
LIVE_URL = 'https://business.paymentz.co.uk';
SANDBOX_URL = 'https://business.paymentz.co.uk'
payload = {
"product" : request.POST['product_name'],
"amount" : request.POST['order_amount'],
"currency" : "CNY",
"redirectSuccessUrl": request.POST['notify_url'],
"redirectFailUrl" : request.POST['return_url'],
"extraReturnParam" : request.POST['order_no'],
"orderNumber" : request.POST['order_number'],
"locale" : request.POST['locale']
}
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer %s' % (MERCHANT_PRIVATE_KEY)
}
resp = requests.post('%s/api/v1/payments' % (SANDBOX_URL), json=payload, headers=headers)
if resp.status_code == 200:
resp_payload = json.loads(resp.text)
return HttpResponseRedirect(resp_payload['processingUrl'])
else:
return HttpResponse('<html><body><span>Something gone wrong: %s</span></body></html>' % (resp.status_code))
MediaType JSON = MediaType.parse("application/json; charset=utf-8");
HashMap<String, Object> params = new HashMap<String, Object>();
params.put("product", "Paymentz Example Payment");
params.put("amount", "1000");
params.put("currency", "EUR");
params.put("redirectSuccessUrl", "[sucess redirect url]");
params.put("redirectFailUrl", "[fail redirect url]");
params.put("orderNumber", "[merchat system order number]");
params.put("extraReturnParam", "[some additional params]");
params.put("locale", "[user locale]");
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://business.paymentz.co.uk/api/v1/payments")
.post(RequestBody.create(JSON, new Gson().toJson(params)))
.addHeader("content-type", "application/json")
.addHeader("authorization", "Bearer merchant_private_key")
.build();
Call call = client.newCall(request);
call.enqueue(new Callback() {
@Override
public void onFailure(Call call, IOException e) {
Log.e("response ", "onFailure(): " + e.getMessage() );
}
@Override
public void onResponse(Call call, Response response) throws IOException {
String resp = response.body().string();
Log.e("response ", "onResponse(): " + resp );
}
});
Return status 200 and JSON: Copy
{
"success": true | false,
"errors": [],
"token": "[payment token]",
"processingUrl": "https://business.paymentz.co.uk/p/[payment token]",
"payment": {
"amount": "10020",
"currency": "CNY",
"status": "init"
},
"redirectRequest": {
"url": "[redirect url, for example ACS URL for 3ds]",
"params": {
"PaReq": "[PaReq for current payment]",
"TermUrl": "https://business.paymentz.co.uk/checkout_results/[payment token]/callback_3ds"
},
"type": "post"
}
}
Initialize payments - to begin receiving payments, you must first call using the following script. This will enable you to obtain a payment token, which will be required later to complete API integration.
HTTP Request over SSL
POST '/api/v1/payments'
Query Parameters
Parameter | Mandatory | Description | Validation |
---|---|---|---|
product | yes | Product name (Service description) (example: 'iPhone'). | minLength: 5, maxLength: 255 |
amount | yes | Payment amount in cents (10020), except JPY | minLength: 1, maxLength: 32 |
currency | yes | Currency code (CNY, EUR, USD, JPY). | minLength: 3, maxLength: 3 |
callbackUrl | yes | The server URL a merchant will be notified about a payment finalisation | Valid URI format |
redirectSuccessUrl | no | The URL a customer will be redirected to in the case of successfull payment | Valid URI format |
redirectFailUrl | no | The URL a customer will be redirected to in the case of payment error or failure | Valid URI format |
extraReturnParam | no | Bank/Payment method list, description, etc | minLength: 1, maxLength: 1024 |
orderNumber | no | The current order number from a company system. | minLength: 3, maxLength: 255 (string) |
locale | no | The locale is used on a payment page by default. Currently supported locales: en, zh and jp from ISO 639-1. | minLength: 2, maxLength: 5 (string) |
walletToken | no | Set this parameter when making recurring payment from a customer’s wallet. A customer will receive notification and has to confirm the payment. | returns by API for recurring payments only |
recurring | no | Set this parameter to true when initializing recurring payment. | boolean |
recurringToken | no | Set this parameter when making recurring payment previously initialized with recurring param. | returns by API for recurring payments only |
needConfirmation | no | Set this parameter whe making payment in two steps (preAuth and confirm/decline) | |
card | no | Card object for Host2Host payments. | |
customer | yes | Customer object. |
Card Object Parameters
Parameter | Mandatory | Description | Validation |
---|---|---|---|
pan | yes | Customer’s card number (PAN). Any valid card number, may contain spaces | Valid card number (16-19 digits) |
expires | yes | Customer’s card expiration date. Format: mm/yyyy | mm/yyyy format |
holder | yes | Customer’s cardholder name. Any valid cardholder name | minLength: 5, maxLength: 50 |
cvv | yes | Customer’s CVV2 / CVC2 / CAV2 | minLength: 3, maxLength: 3 Only digits (\d+) |
Customer Object Parameters (optional)
Parameter | Mandatory | Description | Validation |
---|---|---|---|
yes | Customer’s email, is mandatory if Customer object posted on a request | Valid email format | |
address | no | Customer's billing address | minLength: 5, maxLength: 55 |
country | no | Customer's billing country | ISO country code format "GB" |
city | no | Customer's billing city | minLength: 4, maxLength: 55 |
region | no | Customer's billing region | minLength: 5, maxLength: 55 |
postcode | no | Customer's billing ZipCode | minLength: 4, maxLength: 55 |
phone | no | Customer's billing phone number | minLength: 6, maxLength: 20 |
ip | no | Customer IP address | Valid IP address format (XX.XX.XX.XX) |
browser | no | Customer browser object for 3ds2 payments. |
Customer browser object for 3ds2 payments (optional)
Parameter | Mandatory | Description | Validation |
---|---|---|---|
accept_header | no | Browser's content type | text/html |
color_depth | no | Browser's color depth value | 32 |
ip | no | Browser's ip | 177.255.255.35 |
language | no | Browser's language | ru |
screen_height | no | Browser's screen height | 1080 |
screen_width | no | Browser's screen width | 1920 |
tz | no | Browser's time zone | 180 |
user_agent | no | Browser's user agent | Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:96.0) Gecko/20100101 Firefox/96.0 |
java_enabled | no | Is java enabled | true |
javascript_enabled | no | Is javascript enabled | true |
window_width | no | Browser's window width | 1920 |
window_height | no | Browser's windows height | 1080 |
Payments Providers
Code: Copy
MediaType JSON = MediaType.parse("application/json; charset=utf-8");
HashMap<String, Object> params = new HashMap<String, Object>();
params.put("product", "Paymentz Example Payment");
params.put("amount", "1000");
params.put("currency", "EUR");
params.put("redirectSuccessUrl", "[sucess redirect url]");
params.put("redirectFailUrl", "[fail redirect url]");
params.put("orderNumber", "[merchat system order number]");
params.put("extraReturnParam", "[some additional params]");
params.put("locale", "[user locale]");
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://business.paymentz.co.uk/api/v1/payments")
.post(RequestBody.create(JSON, new Gson().toJson(params)))
.addHeader("content-type", "application/json")
.addHeader("authorization", "Bearer merchant_private_key")
.build();
Call call = client.newCall(request);
call.enqueue(new Callback() {
@Override
public void onFailure(Call call, IOException e) {
Log.e("response ", "onFailure(): " + e.getMessage() );
}
@Override
public void onResponse(Call call, Response response) throws IOException {
String resp = response.body().string();
Log.e("response ", "onResponse(): " + resp );
}
});
Return status 200 and JSON: Copy
{
"success": true | false,
"errors": [],
"token": "[payment token]",
"processingUrl": [
{
"webmoney": "http://business.paymentz.co.uk/p/165998589a413b56ae72fbfdc15b016b/webmoney?locale=en"
},
{
"bank_card": "http://business.paymentz.co.uk/p/165998589a413b56ae72fbfdc15b016b/bank_card?locale=en"
},
{
"qiwi_wallet": "http://business.paymentz.co.uk/p/165998589a413b56ae72fbfdc15b016b/qiwi_wallet?locale=en"
},
{
"skrill_wallet": "http://business.paymentz.co.uk/p/165998589a413b56ae72fbfdc15b016b/skrill_wallet?locale=en"
}
],
"selectorURL": "https://business.paymentz.co.uk/select/[payment token]/",
"payment": {
"amount": "10020",
"currency": "CNY",
"status": "init"
},
"redirectRequest": {
"url": "[redirect url, for example ACS URL for 3ds]",
"params": {
"PaReq": "[PaReq for current payment]",
"TermUrl": "https://business.paymentz.co.uk/checkout_results/[payment token]/callback_3ds"
},
"type": "post"
}
}
In case multiple payment providers enabled to a merchant account, Create payment response JSON will have processingUrl object represented as an array of available payment providers (please refer to JSON response). Use those URLs to redirect your customer to a payment provider (method).
List of payment providers
In case you want a customer to choose a payment provider (method) it might be convenient to use a specific page (widget) with payment provider list, which is available by "selectorURL" parameter in JSON response object.
List
Code: Copy
curl "https://business.paymentz.co.uk/api/v1/payments?dateFrom=2016-05-11&page=1&perPage=1" \
-H "Authorization: Bearer merchant_private_key"
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://business.paymentz.co.uk/api/v1/payments?dateFrom=2016-05-11&page=1&perPage=1",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => array(
"authorization: Bearer merchant_private_key"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://business.paymentz.co.uk/api/v1/payments")
.get()
.addHeader("authorization", "Bearer merchant_private_key")
.build();
Response response = client.newCall(request).execute();
Return status 200 and JSON: Copy
{
"success": true | false,
"errors": [],
"status": 200,
"totalCount": 10,
"curentPage": 1,
"perPage": 1,
"totalPage": 10,
"payments": [
{
"id": 1,
"status": "sent",
"token": "[payment token]",
"currency": "CNY",
"product": "Your Product",
"redirect_success_url": "https://your-site.com/success",
"redirect_fail_url": "https://your-site.com/fail",
"amount": 10000,
"created_at": "2016-06-27T14:13:00.273Z",
"updated_at": "2016-06-27T14:15:44.715Z",
"extra_return_param": "your order id or other info",
"operation_type": "pay",
"order_number": 1
}
]
}
Payments List - this is the method used to display the list of returned payments.
HTTP Request over SSL
GET '/api/v1/payments'
Query Parameters
Parameter | Description | Required |
---|---|---|
dateFrom | Date from (example: '2015-01-01') | No |
dateTo | Date to (example: '2015-01-02') | No |
page | Page number (default: 1) | No |
perPage | Payment per page (max: 500, default: 20) | No |
operationType | Operation type (Available values: pays, payouts, all) | No |
orderNumber | Merchant's order number | No |
Get
Code: Copy
curl "https://business.paymentz.co.uk/api/v1/payments/[payment_token]" \
-H "Authorization: Bearer merchant_private_key"
Return status 200 and JSON: Copy
{
"success": true | false,
"errors": [],
"status": 200,
"payment": {
"id": 2599,
"status": "pending | approved | declined",
"token": "[payment token]",
"currency": "[payment currency]",
"product": "[product description]",
"callback_url": "[callback/notification url]",
"redirect_success_url": "success redirection url",
"redirect_fail_url": "fail redirection url",
"amount": 0,
"created_at": "[creation date]",
"updated_at": "[last status update date]",
"extra_return_param": "[extra params, can be use to payment identification in merchat system]",
"operation_type": "pay | payout",
"order_number": "[merchant's order number]"
}
}
Payment Get - this is the method used to retrieve information about single payment.
HTTP Request over SSL
GET '/api/v1/payments/[payment_token]'
Confirm Two-Step
Code: Copy
curl "https://business.paymentz.co.uk/api/v1/payments/confirm" \
-X POST \
-H "Authorization: Bearer merchant_private_key" \
-H "Content-Type: application/json" -d '{
"token" : "Your Product"
}'
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://business.paymentz.co.uk/api/v1/payments/confirm",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{ \"token\" : \"payment token\""\n}",
CURLOPT_HTTPHEADER => array(
"authorization: Bearer merchant_private_key",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
from django.http import HttpResponseRedirect, HttpResponse
import requests
import json
def pay(request) :
MERCHANT_PRIVATE_KEY = 'merchant_private_key'
LIVE_URL = 'https://business.paymentz.co.uk';
SANDBOX_URL = 'https://business.paymentz.co.uk'
payload = {
"token" : request.POST['token payment']
}
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer %s' % (MERCHANT_PRIVATE_KEY)
}
resp = requests.post('%s/api/v1/payments/confirm' % (SANDBOX_URL), json=payload, headers=headers)
if resp.status_code == 200:
resp_payload = json.loads(resp.text)
return HttpResponseRedirect(resp_payload['processingUrl'])
else:
return HttpResponse('<html><body><span>Something gone wrong: %s</span></body></html>' % (resp.status_code))
MediaType JSON = MediaType.parse("application/json; charset=utf-8");
HashMap<String, Object> params = new HashMap<String, Object>();
params.put("token", "payment token");
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://business.paymentz.co.uk/api/v1/payments/confirm")
.post(RequestBody.create(JSON, new Gson().toJson(params)))
.addHeader("content-type", "application/json")
.addHeader("authorization", "Bearer merchant_private_key")
.build();
Call call = client.newCall(request);
call.enqueue(new Callback() {
@Override
public void onFailure(Call call, IOException e) {
Log.e("response ", "onFailure(): " + e.getMessage() );
}
@Override
public void onResponse(Call call, Response response) throws IOException {
String resp = response.body().string();
Log.e("response ", "onResponse(): " + resp );
}
});
Return status 200 and JSON: Copy
{
"success": true | false,
"result": 0,
"status": 200,
"payment": {
"amount": 100,
"gateway_amount": 100,
"currency": "USD",
"status": "approved|declined",
"two_stage_mode": true
}
}
Confirm Two-Step payment by providing a payment token.
HTTP Request over SSL
POST '/api/v1/payments/confirm'
Query Parameters
Parameter | Mandatory | Description |
---|---|---|
token | yes | Payment token. |
Decline Two-Step
Code: Copy
curl "https://business.paymentz.co.uk/api/v1/payments/decline" \
-X POST \
-H "Authorization: Bearer merchant_private_key" \
-H "Content-Type: application/json" -d '{
"token" : "Your Product"
}'
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://business.paymentz.co.uk/api/v1/payments/decline",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{ \"token\" : \"payment token\""\n}",
CURLOPT_HTTPHEADER => array(
"authorization: Bearer merchant_private_key",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
from django.http import HttpResponseRedirect, HttpResponse
import requests
import json
def pay(request) :
MERCHANT_PRIVATE_KEY = 'merchant_private_key'
LIVE_URL = 'https://business.paymentz.co.uk';
SANDBOX_URL = 'https://business.paymentz.co.uk'
payload = {
"token" : request.POST['token payment']
}
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer %s' % (MERCHANT_PRIVATE_KEY)
}
resp = requests.post('%s/api/v1/payments/decline' % (SANDBOX_URL), json=payload, headers=headers)
if resp.status_code == 200:
resp_payload = json.loads(resp.text)
return HttpResponseRedirect(resp_payload['processingUrl'])
else:
return HttpResponse('<html><body><span>Something gone wrong: %s</span></body></html>' % (resp.status_code))
MediaType JSON = MediaType.parse("application/json; charset=utf-8");
HashMap<String, Object> params = new HashMap<String, Object>();
params.put("token", "payment token");
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://business.paymentz.co.uk/api/v1/payments/decline")
.post(RequestBody.create(JSON, new Gson().toJson(params)))
.addHeader("content-type", "application/json")
.addHeader("authorization", "Bearer merchant_private_key")
.build();
Call call = client.newCall(request);
call.enqueue(new Callback() {
@Override
public void onFailure(Call call, IOException e) {
Log.e("response ", "onFailure(): " + e.getMessage() );
}
@Override
public void onResponse(Call call, Response response) throws IOException {
String resp = response.body().string();
Log.e("response ", "onResponse(): " + resp );
}
});
Return status 200 and JSON: Copy
{
"success": true | false,
"result": 0,
"status": 200,
"payment": {
"amount": 100,
"gateway_amount": 100,
"currency": "USD",
"status": "approved|declined",
"two_stage_mode": true
}
}
Decline Two-Step payment by providing a payment token.
HTTP Request over SSL
POST '/api/v1/payments/decline'
Query Parameters
Parameter | Mandatory | Description |
---|---|---|
token | yes | Payment token. |
Refunds
Paymentz refunds processing REST API.
Create refund
Code: Copy
curl "https://business.paymentz.co.uk/api/v1/refunds" \
-X POST \
-H "Authorization: Bearer merchant_private_key" \
-H "Content-Type: application/json" -d '{
"token" : "Your Product",
"amount": 1000
}'
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://business.paymentz.co.uk/api/v1/payments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{ \"token\" : \"payment token\""\n}",
CURLOPT_HTTPHEADER => array(
"authorization: Bearer merchant_private_key",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
from django.http import HttpResponseRedirect, HttpResponse
import requests
import json
def pay(request) :
MERCHANT_PRIVATE_KEY = 'merchant_private_key'
LIVE_URL = 'https://business.paymentz.co.uk';
SANDBOX_URL = 'https://business.paymentz.co.uk'
payload = {
"token" : request.POST['token payment'],
"amount": 100
}
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer %s' % (MERCHANT_PRIVATE_KEY)
}
resp = requests.post('%s/api/v1/refunds' % (SANDBOX_URL), json=payload, headers=headers)
if resp.status_code == 200:
resp_payload = json.loads(resp.text)
return HttpResponseRedirect(resp_payload['processingUrl'])
else:
return HttpResponse('<html><body><span>Something gone wrong: %s</span></body></html>' % (resp.status_code))
MediaType JSON = MediaType.parse("application/json; charset=utf-8");
HashMap<String, Object> params = new HashMap<String, Object>();
params.put("token", "payment token");
params.put("amount", 100);
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://business.paymentz.co.uk/api/v1/refunds")
.post(RequestBody.create(JSON, new Gson().toJson(params)))
.addHeader("content-type", "application/json")
.addHeader("authorization", "Bearer merchant_private_key")
.build();
Call call = client.newCall(request);
call.enqueue(new Callback() {
@Override
public void onFailure(Call call, IOException e) {
Log.e("response ", "onFailure(): " + e.getMessage() );
}
@Override
public void onResponse(Call call, Response response) throws IOException {
String resp = response.body().string();
Log.e("response ", "onResponse(): " + resp );
}
});
Return status 200 and JSON: Copy
{
"success": true | false,
"errors": [],
"token": "[payment token]",
"processingUrl": "https://business.paymentz.co.uk/p/[payment token]",
"refund": {
"token": "3a1a4fc8f975eb022a1c0ddb3abcded9",
"amount": "10020",
"currency": "USD",
"status": "approved|declined"
}
}
Create refunds by providing a payment token.
HTTP Request over SSL
POST '/api/v1/refunds'
Query Parameters
Parameter | Mandatory | Description |
---|---|---|
token | yes | Payment token. |
amount | no | Refund amount in cents. |
Payouts
Transferring money from a business account to a client account.
Make a payout
Code: Copy
curl "https://business.paymentz.co.uk/api/v1/payouts" \
-X POST \
-H "Authorization: Bearer merchant_private_key" \
-H "Content-Type: application/json" -d '{
"amount" : 1000,
"currency" : "CNY",
"callbackUrl": "https://your-site.com/callback",
"orderNumber": "10001",
"extraReturnParam" : "test payout",
"card": {
"pan" : "4276111152393643",
"expires" : "08/2022",
"holder": "Jhon Doe"
},
"customer": {
"name" : "Mike",
"surname" : "Green",
"email" : "test@paymentz.co.uk",
"address" : "725 5th Ave, New York, NY 10022, United States",
"ip" : "1.1.1.1"
}
}'
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://business.paymentz.co.uk/api/v1/payouts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{ \"amount\" : 1000, \"currency\" : \"CNY\", \"orderNumber\" : \"10001\", \"extraReturnParam\" : \"test payout\", \"card\": { \"pan\" : \"4276111152393643\", \"expires\" : \"08/2022\", \"holder\": \"Jhon Doe\" }, \"customer\": { \"email\" : \"test@paymentz.co.uk\", \"address\" : \"test test\", \"ip\" : \"1.1.1.1\"}"\n}",
CURLOPT_HTTPHEADER => array(
"authorization: Bearer edf526c5374796cdcec5dce731405cee",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
from django.shortcuts import render
from django.http import HttpResponseRedirect, HttpResponse, HttpResponseNotFound
from django.views.decorators.csrf import csrf_exempt
import requests
import json
def payout(request) :
MERCHANT_PRIVATE_KEY = 'your-merchant-private-key'
LIVE_URL = 'https://business.paymentz.co.uk';
SANDBOX_URL = 'https://business.paymentz.co.uk'
payload = {
"amount" : 10000,
"currency" : "EUR",
"callbackUrl": "https://your-site.com/callback",
"orderNumber": "10001",
"card": {
"pan" : "4276111152393643",
"expires" : "08/2022",
"holder": "Jhon Doe"
},
"customer": {
"email" : "test@paymentz.co.uk",
"address" : "test test",
"ip" : "1.1.1.1"
}
}
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer %s' % (MERCHANT_PRIVATE_KEY)
}
resp = requests.post('%s/api/v1/payouts' % (SANDBOX_URL), json=payload, headers=headers)
if resp.status_code == 200:
resp_o = json.loads(resp.text)
return HttpResponseRedirect(resp_o['status'])
else:
return HttpResponse('<html><body><span>Something gone wrong: %s</span> : %s</body></html>' % (resp.status_code, resp.text))
MediaType JSON = MediaType.parse("application/json; charset=utf-8");
HashMap<String, Object> params = new HashMap<String, Object>();
params.put("amount", 1000);
params.put("currency", "EUR");
params.put("orderNumber", "[merchat system order number]");
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://business.paymentz.co.uk/api/v1/payouts")
.post(RequestBody.create(JSON, new Gson().toJson(params)))
.addHeader("content-type", "application/json")
.addHeader("authorization", "Bearer merchant_private_key")
.build();
Call call = client.newCall(request);
call.enqueue(new Callback() {
@Override
public void onFailure(Call call, IOException e) {
Log.e("response ", "onFailure(): " + e.getMessage() );
}
@Override
public void onResponse(Call call, Response response) throws IOException {
String resp = response.body().string();
Log.e("response ", "onResponse(): " + resp );
}
});
Return status 200 with JSON: Copy
{
"success": true | false,
"errors": [],
"payout": {
"token": "[payment token]",
"status": "[payment status]",
"timestamp": "2016-06-09T03:46:45Z"
}
}
Create a payout operation.
HTTP Request over SSL
POST '/api/v1/payouts'
Query Parameters
Parameter | Mandatory | Description |
---|---|---|
amount | yes | Payment amount in minimal values as of; USD and EUR / Cents, for JPY / Yen, for CNY / Fen. |
currency | yes | Currency code (CNY, EUR, USD, JPY) |
callbackUrl | yes | The server URL a merchant will be notified about a payout finalisation |
orderNumber | yes | Paymentz's client inner order number |
card | yes | Card object for Host2Host payouts. |
customer | yes | Customer object for Host2Host payouts. |
Card Payout Object Parameters
Parameter | Mandatory | Description |
---|---|---|
pan | yes | Customer’s card number (PAN). Any valid card number, may contain spaces |
expires | yes | Customer’s card expiration date. Format: mm/yyyy |
holder | yes | Сardholder name. Any valid cardholder name. Min length - 5 max - 50 |
Customer Object Parameters (optional)
Parameter | Mandatory | Description |
---|---|---|
yes | Customer’s email, is mandatory if Customer object posted on a request | |
country | no | Customer's payout country; Use ISO (GB, UK, US) |
city | no | Customer's payout city. Min length - 4, max - 55 |
address | no | Customer's billing address in the full format like "725 5th Ave, New York, NY 10022, United States" |
ip | yes | Customer IP address |
name | no | Customer name |
surname | no | Customer surname |
Providers
Code: Copy
curl "https://business.paymentz.co.uk/api/v1/payouts" \
-X POST \
-H "Authorization: Bearer merchant_private_key" \
-H "Content-Type: application/json" -d '{
"amount" : 1000,
"currency" : "CNY",
"orderNumber": "10001",
"extraReturnParam" : "test payout",
"card": {
"pan" : "4276111152393643",
"expires" : "08/2022"
},
"customer": {
"email" : "test@paymentz.co.uk",
"address" : "test test",
"ip" : "1.1.1.1"
}
}'
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://business.paymentz.co.uk/api/v1/payouts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{ \"amount\" : 1000, \"currency\" : \"CNY\", \"orderNumber\" : \"10001\", \"extraReturnParam\" : \"test payout\", \"card\": { \"pan\" : \"4276111152393643\", \"expires\" : \"08/2022\" }, \"customer\": { \"email\" : \"test@paymentz.co.uk\", \"address\" : \"test test\", \"ip\" : \"1.1.1.1\"}"\n}",
CURLOPT_HTTPHEADER => array(
"authorization: Bearer edf526c5374796cdcec5dce731405cee",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
from django.shortcuts import render
from django.http import HttpResponseRedirect, HttpResponse, HttpResponseNotFound
from django.views.decorators.csrf import csrf_exempt
import requests
import json
def payout(request) :
MERCHANT_PRIVATE_KEY = 'your-merchant-private-key'
LIVE_URL = 'https://business.paymentz.co.uk';
SANDBOX_URL = 'https://business.paymentz.co.uk'
payload = {
"amount" : 10000,
"currency" : "EUR",
"orderNumber": "10001",
"card": {
"pan" : "4276111152393643",
"expires" : "08/2022"
},
"customer": {
"email" : "test@paymentz.co.uk",
"address" : "test test",
"ip" : "1.1.1.1"
}
}
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer %s' % (MERCHANT_PRIVATE_KEY)
}
resp = requests.post('%s/api/v1/payouts' % (SANDBOX_URL), json=payload, headers=headers)
if resp.status_code == 200:
resp_o = json.loads(resp.text)
return HttpResponseRedirect(resp_o['status'])
else:
return HttpResponse('<html><body><span>Something gone wrong: %s</span> : %s</body></html>' % (resp.status_code, resp.text))
MediaType JSON = MediaType.parse("application/json; charset=utf-8");
HashMap<String, Object> params = new HashMap<String, Object>();
params.put("amount", 1000);
params.put("currency", "EUR");
params.put("orderNumber", "[merchat system order number]");
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://business.paymentz.co.uk/api/v1/payouts")
.post(RequestBody.create(JSON, new Gson().toJson(params)))
.addHeader("content-type", "application/json")
.addHeader("authorization", "Bearer merchant_private_key")
.build();
Call call = client.newCall(request);
call.enqueue(new Callback() {
@Override
public void onFailure(Call call, IOException e) {
Log.e("response ", "onFailure(): " + e.getMessage() );
}
@Override
public void onResponse(Call call, Response response) throws IOException {
String resp = response.body().string();
Log.e("response ", "onResponse(): " + resp );
}
});
Return status 200 and JSON: Copy
{
"success": true | false,
"errors": [],
"token": "[payment token]",
"processingUrl": [
{
"webmoney": "http://business.paymentz.co.uk/pout/165998589a413b56ae72fbfdc15b016b/webmoney?locale=en"
},
{
"bank_card": "http://business.paymentz.co.uk/pout/165998589a413b56ae72fbfdc15b016b/bank_card?locale=en"
},
{
"qiwi_wallet": "http://business.paymentz.co.uk/pout/165998589a413b56ae72fbfdc15b016b/qiwi_wallet?locale=en"
},
{
"skrill_wallet": "http://business.paymentz.co.uk/pout/165998589a413b56ae72fbfdc15b016b/skrill_wallet?locale=en"
}
],
"selectorURL": "https://business.paymentz.co.uk/select/pout/[payment token]/",
"payment": {
"amount": "10020",
"currency": "CNY",
"status": "init"
}
}
In case multiple payout providers enabled to a merchant account, Create payout repsonse JSON will have processingUrl object represented as an array of available payout providers (please refer to JSON response). Use those URLs to redirect your customer to a payout provider (method).
List of payout providers
In case you want a customer to choose a payout provider (method) it might be convenient to use a specific page (widget) with payout provider list, which is available by "selectorURL" parameter in JSON response object.
Balance
Request current Paymentz balance.
Receive Balance
Code: Copy
curl "https://business.paymentz.co.uk/api/v1/balance?currency=CNY" \
-X GET \
-H "Authorization: Bearer merchant_private_key" \
-H "Content-Type: application/json"
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://business.paymentz.co.uk/api/v1/balance?currency=CNY",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => array(
"authorization: Bearer merchant_private_key",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
from django.shortcuts import render
from django.http import HttpResponseRedirect, HttpResponse, HttpResponseNotFound
from django.views.decorators.csrf import csrf_exempt
import requests
import json
def balance(request) :
MERCHANT_PRIVATE_KEY = 'merchant_private_key'
LIVE_URL = 'https://business.paymentz.co.uk';
SANDBOX_URL = 'https://business.paymentz.co.uk'
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer %s' % (MERCHANT_PRIVATE_KEY)
}
resp = requests.get('%s/api/v1/balance' % (SANDBOX_URL), params = {'currency':'CNY'}, headers=headers)
if resp.success:
resp_o = json.loads(resp.text)
return HttpResponse('<html><body><span>Your balance %s</body></html>' % (resp_o['wallet']['available']))
else:
return HttpResponse('<html><body><span>Something gone wrong: %s</span> : %s</body></html>' % (resp.status_code, resp.text))
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://business.paymentz.co.uk/api/v1/balance?currency=CNY")
.get()
.addHeader("content-type", "application/json")
.addHeader("authorization", "Bearer merchant_private_key")
.build();
Response response = client.newCall(request).execute();
Return status 200 and JSON: Copy
{
"success": true | false,
"errors": [],
"wallet": {
"available": 0,
"hold": 0,
"currency": "CNY"
}
}
Receiving the balance for a business account. Balance is returned as an object displaying available and pending amounts. Balances shown may not be released and/or processed.
HTTP Request over SSL
GET '/api/v1/balance'
Query Parameters
Parameter | Description |
---|---|
currency | Currency code (CNY) |
Disputes
Request current Paymentz dispute list.
Dispute list
Code: Copy
curl "https://business.paymentz.co.uk/api/v1/disputes/list" \
-X GET \
-H "Authorization: Bearer merchant_private_key" \
-H "Content-Type: application/json"
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://business.paymentz.co.uk/api/v1/disputes/list",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => array(
"authorization: Bearer merchant_private_key",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
from django.shortcuts import render
from django.http import HttpResponseRedirect, HttpResponse, HttpResponseNotFound
from django.views.decorators.csrf import csrf_exempt
import requests
import json
def disputes(request) :
MERCHANT_PRIVATE_KEY = 'merchant_private_key'
LIVE_URL = 'https://business.paymentz.co.uk';
SANDBOX_URL = 'https://business.paymentz.co.uk'
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer %s' % (MERCHANT_PRIVATE_KEY)
}
resp = requests.get('%s/api/v1/disputes/list' % (SANDBOX_URL), headers=headers)
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://business.paymentz.co.uk/api/v1/disputes/list")
.get()
.addHeader("content-type", "application/json")
.addHeader("authorization", "Bearer merchant_private_key")
.build();
Response response = client.newCall(request).execute();
Return status 200 and JSON: Copy
{
"success": true,
"status": 200,
"disputes": [
{
"id": 27,
"amount": 2,
"currency": "USD",
"investigation_report": null,
"status": "processing",
"merchant_profile_id": 3,
"user_profile_id": 3,
"feed_id": 330,
"created_at": "2019-09-13T08:46:21.302Z",
"updated_at": "2019-09-13T08:46:21.343Z",
"dispute_type": 2,
"reason_code": "123",
"comment": "some comment"
}
]
}
Getting a list of last disputes for a business account.
HTTP Request over SSL
GET '/api/v1/disputes/list'
Query Parameters
No parameters, returns 100 latest records
Notifications
Notifications with the payment or payout status are sent to your callback URL using POST methods. In case payment or payout status changed (pending/approved/declined) -- notification type is sent accordingly.
Code: Copy
from django.views.decorators.csrf import csrf_exempt
from django.http import HttpResponseRedirect, HttpResponse, HttpResponseNotFound
@csrf_exempt
def notifyme(request) :
req_o = json.loads(request.read());
return HttpResponse('Status is:%s' % (req_o['status']))
Params: Copy
{
"token": "payment token",
"type": "payment type: payment | payout",
"status" : "payment status: pending | approved | declined ",
"extraReturnParam" : "extra params",
"orderNumber" : "merchant order number",
"walletToken": "payer's Paymentz wallet unique identifier, only for Paymentz payments",
"recurringToken": "payer's previously initialized recurring token, for making recurrent payment repeatedly",
"sanitizedMask": "payer's sanitized card, if it was provided",
"amount": "payment amount in cents",
"currency": "payment currency",
"gatewayAmount": "exchanged amount in cents",
"gatewayCurrency": "exchanged currency",
"signature": "security token for transaction validation"
}
Signature
Signature calculation
Required params for calculation: Copy
{
"token": "edVrCSWBbtYvcg3d76NQeko7zXHHzooT",
"type": "pay",
"status": "approved",
"extraReturnParam": "_blank_",
"orderNumber": "6574860",
"amount": 100,
"currency": "EUR",
"gatewayAmount": 100,
"gatewayCurrency": "EUR"
}
- Remove signature from original callback.
- Use attributes in this order:
token, type, status, extraReturnParam, orderNumber, amount, currency, gatewayAmount, gatewayCurrency
- For each param calculate the size and put it before the value.
5 + param = 5param
- Concat previous strings into single one.
10firstParam + 11secondParam = 10param11secondParam
- Join private key to the end of the string.
10param11secondParam + private_key = 10param11secondParamprivate_key
- Use the MD5 algorithm on the string to calculate signature.
md5(10param11secondParamprivate_key) = 44fe366929d98e92c2a0be8e8ef43a9b
- Compare the resulting signature with the original one.
Example
Example callback from test merchant
Merchant key: dd0fdd55135783da1d2d
Callback example: Copy
{
"token": "edVrCSWBbtYvcg3d76NQeko7zXHHzooT",
"type": "pay",
"status": "approved",
"extraReturnParam": "_blank_",
"orderNumber": "6574860",
"walletDisplayName": "",
"amount": 100,
"currency": "EUR",
"gatewayAmount": 100,
"gatewayCurrency": "EUR",
"gatewayDetails": {
"ip": {
"country": "POLAND",
"ccode_iso": "POL",
"ccode_short": "PL"
},
"bin": {
"ps": "VISA",
"www": "",
"code": "840",
"type": "CREDIT",
"country": "UNITED STATES",
"sub_type": "",
"bank_name": "",
"ccode_iso": "USA",
"ccode_short": "US"
},
"processing_url": "https://business.paymentz.co.uk/checkout/edVrCSWBbtYvcg3d76NQeko7zXHHzooT?locale=en"
},
"cardHolder": "John Doe",
"sanitizedMask": "439296******1251",
"walletToken": "1591d198cbaf9912acc1f1a491d5b224c846",
"signature": "70bbe1a27ddcc6dfd246215a14a4f265"
}
string = 32 + edVrCSWBbtYvcg3d76NQeko7zXHHzooT + 3 + pay + 8 + approved + 7 + _blank_ + 7 + 6574860 + 3 + 100 + 3 + EUR + 3 + 100 + 3 + EUR
string = 32edVrCSWBbtYvcg3d76NQeko7zXHHzooT3pay8approved7_blank_7657486031003EUR31003EUR
sign = md5(32edVrCSWBbtYvcg3d76NQeko7zXHHzooT3pay8approved7_blank_7657486031003EUR31003EURdd0fdd55135783da1d2d)
sign = 70bbe1a27ddcc6dfd246215a14a4f265
Dictionaries
Errors
If any method failed, the JSON response with status code 403 returned that specified the problem.
Return status 403 and JSON: Copy
{'success': false, 'result': 1, 'status': 403, 'errors': {'list': [{'code': 'merchant_not_found', 'kind': 'api_error'}]}}
{'success': false, 'result': 1, 'status': 403, 'errors': [{'code': 'amount_less_than_minimum', 'kind': 'invalid_request_error'}]}
{'success': false, 'result': 1, 'status': 403, 'errors': [{'code': 'amount_less_than_balance', 'kind': 'processing_error'}]}
Payment states
State | Final | Description |
---|---|---|
init | no | Request to API will initiate payments. |
pending | no | User redirected to the Paymentz Checkout facility during payment processing period. |
approved | yes | Successfully completed payment. |
declined | yes | Unsuccessful payment. |
refunded | yes | Successfully refunded payment. |
expired | yes | Abandoned transaction. |
Kinds of errors
Kind | Description |
---|---|
api_error | Indicate rare occasions such as an Paymentz API server technicality. |
authentication_error | Authentication request failure. |
invalid_request_error | Invalid parameters which produce invalid requests. |
processing_error | Processing the payment generated an error. |
Codes of errors
Code | Description |
---|---|
incorrect_private_key | The current private key cannot identify the user. |
incorrect_address_info | Absent or incorrect address information. |
incorrect_bank_card_info | Absent or incorrect bank card information. |
order_number_already_exists | Repeating an order of already identified order number. |
amount_less_than_balance | Payout cannot be completed due to insufficient funds. |
incorrect_amount | Absent or incorrect amount value. |
incorrect_currency | Absent or incorrect currency value. |
incorrect_order_number | Absent or incorrect order value. |
amount_less_than_minimum | Minimum payout amount has not been requested. |