Secure Signature

This field ensures the integrity of requests made to our services. It also allows merchants to control the number of requests made to transactional APIs by a specific user.

The Security Signature is required for the following services:

  • API api/v2/transaction/other or hosted/payment/other
  • SDK doSale or API api/v2/transaction/sale
  • SDK doAuth or API api/v2/transaction/auth
  • SDK doCapture or API api/v2/transaction/capture
  • SDK getStatus or API api/v2/transaction/status

Required Fields

Depending on the service being implemented, the signature must be generated using some of the fields included in the request:

  • app_key: the merchant identifier, can be extracted here
  • order_id: the order number of the transaction you wish to sign
  • app_url: the merchant's platform, can be extracted here
  • secret_key: the merchant secret key, can be extracted here

In more advanced cases, you may also need to include other fields in the signature:

  • transaction_approved_amount: for fund capture transactions, this is the total amount to be captured
  • payment_uuid: for fund capture transactions or getting the payment's status, this is the payment identifier
Service Required Fields
API api/v2/transaction/other
API hosted/payment/other
API api/v2/transaction/sale
API api/v2/transaction/auth
SDK doSale
SDK doAuth		 app_key, order_id, app_url
API api/v2/transaction/capture
SDK doCapture		 app_key, transaction_approved_amount, payment_uuid, app_url
API api/v2/transaction/status
SDK getStatus		 app_key, payment_uuid, app_url

Signature Creation

Once you have identified the service and the fields needed to sign your request, you must concatenate all the fields into a string with the symbol |. This string must then be processed through HMAC with the SHA3-512 algorithm, using the secret key to sign it.

Since creating the signature involves using the secret key, make sure you do it in a controlled environment such as a server or internal API, and not within the user's device. If you suspect your secret key has been exposed, see here to learn how to create a new one.

For example, to create the signature for a transaction made using the service Direct Sale with order number ORDER-8888 and fictitious merchant keys, the result must be 688084a6...e852ee2a:

<?php // Sandbox credentials, replace with your merchant's details $app_key = "1234567890"; $order_id = "ORDER-8888"; $app_url = "https://pixelpay.dev"; $secret_key = "@s4ndb0x-abcd-1234-n1l4-p1x3l"; echo hash_hmac( "sha3-512", implode("|", [$app_key, $order_id, $app_url]), $secret_key ); import { createHmac } from "crypto"; // Sandbox credentials, replace with your merchant's details const app_key = "1234567890"; const order_id = "ORDER-8888"; const app_url = "https://pixelpay.dev"; const secret_key = "@s4ndb0x-abcd-1234-n1l4-p1x3l"; const signature = createHmac("sha3-512", secret_key) .update([app_key, order_id, app_url].join("|")) .digest("hex"); console.log(signature);

Signature Delivery

Once we have created the signature, it must be sent in the request header x-client-signature. If you use the SDK services, see here on how to add this header to your requests.