Payment notification
Example of notification received:
{
"message": "OK",
"code": 200,
"current_time": "2022-11-16T11:16:33+0100",
"order": {
"uuid": "D16004FF-3421-409C-ADFC-DA2618D36135",
"created": "2022-11-16T11:11:03+0100",
"created_from_client_timezone": "2022-11-16T12:11:03+0200",
"amount": 1050,
"currency": "978",
"paid": true,
"status": "SUCCESS",
"safe": true,
"refunded": 0,
"additional": "227610373340",
"service": "CREDORAX",
"service_uuid": "B1F13B01-BA97-491C-BBDE-1C18988BD229",
"customer": "user42",
"cof_txnid": "202232016000606",
"transactions": [
{
"uuid": "2343BE77-1383-491E-8D95-5E00F0D35FAA",
"created": "2022-11-16T11:11:15+0100",
"created_from_client_timezone": "2022-11-16T12:11:15+0200",
"operative": "AUTHORIZATION",
"amount": 1050,
"authorization": "651979",
"processor_id": "XZZ01d4d229b0d5dB40RPKQCOSFNBGBH",
"status": "SUCCESS",
"error": "NONE",
"source": {
"object": "CARD",
"uuid": "F1E73ECB-D88C-4C57-919E-102F0E822416",
"type": "CREDIT",
"token": "95d37eaa18762d7d8c7b4ef098c4dd1e55450f21a9efaea27466d42da183b21b6cf3d0d8b74001b17ee3ba7d23e1daba7dda9b54a37979f3bb7cebc6e18ee7fe",
"brand": "VISA",
"country": "MT",
"holder": "Miguel C",
"bin": 401881,
"last4": "0036",
"is_saved": true,
"expire_month": "12",
"expire_year": "34",
"additional": null,
"bank": "BANK OF VALLETTA P.L.C",
"prepaid": false,
"validation_date": "2022-11-16 11:12:02",
"creation_date": "2022-11-16 11:11:51",
"brand_description": null,
"origin": "PAYMENT_CARD",
"cof": {
"is_available": true
}
},
"antifraud": null,
"device": {
"fingerprint": "495973560",
"user_agent": "Mozilla\/5.0 (X11; Linux x86_64; rv:106.0) Gecko\/20100101 Firefox\/106.0"
},
"error_details": null,
"bizum": {
"account": "ES51XXXXXXXXXXXXXXXX0001",
"phone_number": "346XXXXX306"
}
}
],
"token": null,
"ip": "127.0.0.1",
"reference": null,
"dynamic_descriptor": null,
"threeds_data": {
"version": "2.1",
"flow": "FRICTIONLESS",
"sca_requested": false,
"status": "Y",
"eci": "06",
"exemption": null
},
"dcc": {
"fee": "3.00 %",
"change": 0.099415,
"mode": "LOCAL",
"selection": "CARD",
"card_currency": "NOK",
"merchant_currency": "EUR",
"ecb_change": null
}
},
"client": {
"uuid": "42B8CF56-A7D7-4D4A-8349-4E27263CB2D5"
},
"extra_data": {
"halcash": {
"sender_name": "sender",
"secret_key": "1234",
"expiry_date": "2022-11-11"
}
},
"validation_hash": "8fe27963c7dd6c134dfd09fca6e544942acf89a57c8488c6437ca9c355397250"
}
NOTES:
- The
transaction.bizumfield of the notification will only be included in Bizum payments. - The
order.dccfield in the notification will only be included in DCC transactions.
There are different ways to check that the notifications received at url_post come from Paylands.
Whitelist Paylands IPs
Firstly, you can whitelist the IPs coming from the Paylands servers. This is one of the most common and simplest solutions.
To do so, contact soporte@paylands.com to receive the IPs.
Validation using the hash of the notification
The other way to check that the communication between Paylands and the merchant is not being intercepted is by checking the validation hash. Once the request to Paylands has been processed, a json response like the one below will be returned.
The extra_data field will only appear if it was included in the initial request.
{
"message": "OK",
"code": 200,
"current_time": "2023-04-05T17:39:56+0200",
"order": {
"uuid": "E89DFBF6-23D3-4D78-BC98-06936F38D85F",
"created": "2022-12-30T12:21:32+0100",
"created_from_client_timezone": "2022-12-30T12:21:32+0100",
"amount": 10,
"currency": "978",
"paid": true,
"status": "SUCCESS",
"safe": false,
"refunded": 0,
"additional": null,
"service": "CREDORAX",
"service_uuid": "E6C5D97A-BDE8-45E0-904C-60EDEFDEC16D",
"customer": "test2222",
"cof_txnid": null,
"transactions": [
{
"uuid": "7DD3AE71-A758-416C-B813-D3EE936500F3",
"created": "2022-12-30T12:21:32+0100",
"created_from_client_timezone": "2022-12-30T12:21:32+0100",
"operative": "AUTHORIZATION",
"amount": 10,
"authorization": "202046",
"processor_id": "XZZ01f0a9404ffbb7B95LCGT274ERFW7",
"status": "SUCCESS",
"error": "NONE",
"source": {
"object": "CARD",
"uuid": "80C55ED9-3D72-4636-8AC7-27898AAD36B3",
"type": "CREDIT",
"token": "d3879e8cf246d2a9fbd0db46e013329a4772127a8634ea9b5fcb86ec1b9b29c888d60912fc96ff8320673d0570620967c959cb6d6671ce9145315a8b664c7ea4",
"brand": "VISA",
"country": "MT",
"holder": "Miguel C",
"bin": 401881,
"last4": "0011",
"is_saved": false,
"expire_month": "12",
"expire_year": "34",
"additional": null,
"bank": "Bank of Valletta p.l.c",
"prepaid": null,
"validation_date": "2022-12-30 12:22:18",
"creation_date": "2022-12-30 12:21:58",
"brand_description": "Visa Classic",
"origin": "KEYENTRY",
"cof": {
"is_available": false
}
},
"antifraud": null,
"device": {
"fingerprint": "2032183838",
"user_agent": "Mozilla\/5.0 (X11; Linux x86_64; rv:108.0) Gecko\/20100101 Firefox\/108.0"
},
"error_details": null
}
],
"token": null,
"ip": "127.0.0.1",
"reference": null,
"dynamic_descriptor": null,
"threeds_data": null
},
"client": {
"uuid": "42B8CF56-A7D7-4D4A-8349-4E27263CB2D5"
},
"validation_hash": "eae6e4c9d3dcb27067041aac25e15044909bc5a96830387332c62885cb6324b8"
}
After fetching the received json from the notification, we must calculate a hash using the signature credential.
First of all we must extract the order, client and extra_data fields from the received notification and store them in an array. Then we json encode this array and calculate the hash using the SHA 256 algorithm and the signature as described in the example below.
As mentioned before, the extra_data field may not appear if it was not sent in the initial request sent by the merchant.
<?php
$jsonObject = json_decode($response);
$array['order'] = $jsonObject->order;
$array['client'] = $jsonObject->client;
$array['extra_data'] = $jsonObject->extra_data;
$data = json_encode($array, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$signature ='341f7de8e6fc49da8d8736473af6b03a';
$validationHash = hash('sha256', $data . $signature);
The $validationHash obtained must be identical to the one received in the Paylands notification.
The above example can be used for the necessary tests, since this is a real case.
Notifications of expired orders
Paylands has the ability to notify expired orders. To enable this option you must contact soporte@paylands.com and request to enable Notify expired orders.
After enabling this feature, whenever Paylands changes an order status to expired, a notification will be sent to the merchant to the url specified in the url_post field along with the updated order object:
{
"message": "OK",
"code": 200,
"current_time": "2023-04-05T17:39:56+0200",
"order": {
"uuid": "E89DFBF6-23D3-4D78-BC98-06936F38D85F",
"created": "2022-12-30T12:21:32+0100",
"created_from_client_timezone": "2022-12-30T12:21:32+0100",
"amount": 10,
"currency": "978",
"paid": false,
"status": "EXPIRED",
"safe": false,
"refunded": 0,
"additional": null,
"service": "CREDORAX",
"service_uuid": "E6C5D97A-BDE8-45E0-904C-60EDEFDEC16D",
"customer": "test2222",
"cof_txnid": null,
"transactions": [
{
"uuid": "7DD3AE71-A758-416C-B813-D3EE936500F3",
"created": "2022-12-30T12:21:32+0100",
"created_from_client_timezone": "2022-12-30T12:21:32+0100",
"operative": "AUTHORIZATION",
"amount": 10,
"authorization": "",
"processor_id": null,
"status": "CREATED",
"error": "NONE",
"source": null,
"antifraud": null,
"device": null,
"error_details": null
}
],
"token": null,
"ip": "127.0.0.1",
"reference": null,
"dynamic_descriptor": null,
"threeds_data": null
},
"client": {
"uuid": "42B8CF56-A7D7-4D4A-8349-4E27263CB2D5"
},
"validation_hash": "eae6e4c9d3dcb27067041aac25e15044909bc5a96830387332c62885cb6324b8"
}
The complete specification for Generate payment order can be found in the API Reference.