Authentication and authorisation

Security and authentication

All requests must be over SSL.

Why is a signature required

Payment requests to Hosted Checkout require a signature token to verify the integrity of the payment, ensuring that the payment request is from a valid merchant and that no one has tampered with it.

Webhooks and redirects from Checkout are also signed using the same method as defined below. This allows merchants to ensure that the webhook request came from Hosted Checkout and that no one has tampered with it.

How to generate a signature (HMAC SHA256)

The signature uses the HMAC SHA256 algorithm, all parameters in the request, and the secret token as the key to generate the signature. The secret token is a shared secret between the merchant and Peach Payments and you can retrieve it from the Peach Payments Dashboard.

To generate the signature, all payment parameters (including empty parameters) must be in alphabetical order, concatenated, without any spaces or special characters, and signed with the secret token as the key. The generated signature itself forms part of the request for validation by Peach Payments.


See the Checkout PHP SDK for an example showing how to generate the Checkout signature.

request_data = {
  "amount": "2",
  "authentication.entityId": "8ac7a4ca68c22c4d0168c2caab2e0025",
  "currency": "ZAR",
  "defaultPaymentMethod": "CARD",
  "merchantTransactionId": "Test1234",
  "paymentType": "DB",
  "shopperResultUrl": "",
  "notificationUrl": "",

secret_string = "".join([str(key) + str(request_data[key]) for key in sorted(request_data)])
# secret_string = amount2authentication.entityId8ac7a4ca68c22c4d0168c2caab2e0025currencyZARdefaultPaymentMethodCARDmerchantTransactionIdTest1234nonceJHGJSGHDSKJHGJDHGJHnotificationUrlpaymentTypeDBshopperResultUrl

Peach Payments signs the payment responses to the shopper result URL and transaction webhooks using the same signing method for the merchant to verify their authenticity.

Peach Payments provides an entity ID and secret token to authenticate with the API. Keep your secret token safe and use it when computing the signature needed to redirect to the Peach Payments Checkout page.

Example of HMAC generation:

Concatenated string:


Secret token:


Computed HMAC:


Verify your HMAC SHA256 algorithm using the FreeFormatter HMAC testing tool.

The example below describes the required parameters. If you include any other parameters, they must be part of the encrypted message.

See the API reference section for a full list of the supported parameters.

import hashlib
import hmac

message = "amount2authentication.entityId8ac7a4ca68c22c4d0168c2caab2e0025currencyZARdefaultPaymentMethodCARDmerchantTransactionIdTest1234nonceJHGJSGHDSKJHGJDHGJHpaymentTypeDBshopperResultUrl".encode('utf-8')
secret = "3fcd7cf22f55119eadbe02d14de18c0c".encode('utf-8')

signature =, msg=message, digestmod=hashlib.sha256).hexdigest()
import CryptoJS from "crypto-js";

const secret = "3fcd7cf22f55119eadbe02d14de18c0c";
const message = "amount2authentication.entityId8ac7a4ca68c22c4d0168c2caab2e0025currencyZARdefaultPaymentMethodCARDmerchantTransactionIdTest1234nonceJHGJSGHDSKJHGJDHGJHpaymentTypeDBshopperResultUrl";

const signature = CryptoJS.HmacSHA256(message, secret).toString(CryptoJS.enc.Hex);


Uniqueness of request

The Checkout payment request requires a unique nonce parameter to ensure the authenticity of each payment request. Merchants manage nonces and ensure that they are unique for each request made to the /checkout URL. This unique nonce helps generate a unique signature. In doing so, the nonce helps to identify and prevent the merchant or unauthorised third parties from executing duplicate requests.

Domain allowlisting

All URL domains that execute the API POST request to Checkout require allowlisting for added security. Log a support ticket to add URLs to the allowlist.


The entity ID provided to you by Peach Payments limits the currencies and payment methods your application can process. Should you have issues with accessing a particular currency or payment method, contact your Peach Payments account manager so they can discuss the commercial implications of more payment methods.