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",
  "nonce": "JHGJSGHDSKJHGJDHGJH",
  "paymentType": "DB",
  "shopperResultUrl": "https://webhook.site/4e9b63bf-0d99-4d62-bd24-1d36ca866e1b",
  "notificationUrl": "",
}

secret_string = "".join([str(key) + str(request_data[key]) for key in sorted(request_data)])
# secret_string = amount2authentication.entityId8ac7a4ca68c22c4d0168c2caab2e0025currencyZARdefaultPaymentMethodCARDmerchantTransactionIdTest1234nonceJHGJSGHDSKJHGJDHGJHnotificationUrlpaymentTypeDBshopperResultUrlhttps://webhook.site/4e9b63bf-0d99-4d62-bd24-1d36ca866e1b

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:

amount2authentication.entityId8ac7a4ca68c22c4d0168c2caab2e0025currencyZARdefaultPaymentMethodCARDmerchantTransactionIdTest1234nonceJHGJSGHDSKJHGJDHGJHpaymentTypeDBshopperResultUrlhttps://webhook.site/4e9b63bf-0d99-4d62-bd24-1d36ca866e1b

Secret token:

3fcd7cf22f55119eadbe02d14de18c0c

Computed HMAC:

311ed8e11e2da00d98c7479ca390a5396fe643e13629d850243dada877963afd

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.entityId8ac7a4ca68c22c4d0168c2caab2e0025currencyZARdefaultPaymentMethodCARDmerchantTransactionIdTest1234nonceJHGJSGHDSKJHGJDHGJHpaymentTypeDBshopperResultUrlhttps://webhook.site/4e9b63bf-0d99-4d62-bd24-1d36ca866e1b".encode('utf-8')
secret = "3fcd7cf22f55119eadbe02d14de18c0c".encode('utf-8')

signature = hmac.new(key=secret, msg=message, digestmod=hashlib.sha256).hexdigest()
print(signature)

import CryptoJS from "crypto-js";

const secret = "3fcd7cf22f55119eadbe02d14de18c0c";
const message = "amount2authentication.entityId8ac7a4ca68c22c4d0168c2caab2e0025currencyZARdefaultPaymentMethodCARDmerchantTransactionIdTest1234nonceJHGJSGHDSKJHGJDHGJHpaymentTypeDBshopperResultUrlhttps://webhook.site/4e9b63bf-0d99-4d62-bd24-1d36ca866e1b";

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

console.log(signature);

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.

Allowlist domains

All URL domains that execute the API POST request to Checkout require allowlisting for added security.

Add a domain to the allowlist

1. Log in to your Peach Payments Dashboard.
2. In the left navigation menu, click Checkout.
3. Scroll down to the Allowlisted domains section and click Add domain.
4. Enter the domain, subdomain, or IP that you want to add to the allowlist, then click Add.

   

5. If the domain that you added:
   • Matches the one that Peach Payments has on record for you, the domain appears in the allowlisted domains list.
   • Doesn't match the one that Peach Payments has on record for you (or if Peach Payments doesn't have a domain on record), the domain enters a pending state until Peach Payments has verified the domain, whereafter the domain appears in the allowlisted domains list.

📘

Adding a domain on sandbox does not need verification.

Delete a domain from the allowlist

📘

You cannot delete pending domains.

To delete a domain from the allowlist:

1. Log in to your Peach Payments Dashboard.
2. In the left navigation menu, click Checkout.
3. Scroll down to the Allowlisted domains section and click the more options icon next to the domain that you want to delete.
4. Click Delete.

The domain disappears from the allowlisted domains section.

Authorisation

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.