Authentication and authorisation

Security and authentication

All requests must be made over SSL.

Signature (HMAC SHA256)

Payment requests to https://secure.peachpayments.com/checkout or https://testsecure.peachpayments.com/checkout require a signature token to verify the integrity of the payment, ensuring that only the merchant sending the request is accepted.

The signature uses the HMAC SHA256 algorithm, all of the payment parameters in the request, and the secret token as the key to generate the signature. This secret token is only known to the merchant and Peach Payments and is available in the Peach Payments Dashboard or Console.

To generate the signature, all payment 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 is added to the payment request for validation by Peach Payments.

The payment responses and transaction webhooks are signed by Peach Payments using the same signing method for the merchant to validate their authenticity.

We provide an entity ID and secret token which are used to authenticate with the API. Your secret token should only be known to you and is required when computing the signature needed to successfully 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 contains only the required parameters. If you include any additional parameters, they must be part of the message being encrypted.

See the Checkout payment request 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=payloadData, digestmod=hashlib.sha256).hexdigest()
print(signature)
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.9-1/crypto-js.min.js"></script>

<script>
  var hash = CryptoJS.HmacSHA256("amount2authentication.entityId8ac7a4ca68c22c4d0168c2caab2e0025currencyZARdefaultPaymentMethodCARDmerchantTransactionIdTest1234nonceJHGJSGHDSKJHGJDHGJHpaymentTypeDBshopperResultUrlhttps://webhook.site/4e9b63bf-0d99-4d62-bd24-1d36ca866e1b", "3fcd7cf22f55119eadbe02d14de18c0c");
  var signature = hash.toString(CryptoJS.enc.Hex);
  document.write(signature);
</script>

Uniqueness of request

The Checkout payment request additionally requires a unique nonce parameter to ensure the authenticity of each payment request. A nonce is unique to each request made to the /checkout URL and must be managed by the merchant. This unique nonce generates a unique signature. In doing so, the nonce helps to identify and prevent duplicate requests from being made by the merchant or unauthorized third parties.

Domain allowlisting

All URL domains that initiate the API POST request to Checkout require allowlisting for added security. A list of URLs can be allowlisted in the Peach Payments Console under the Checkout section or by contacting [email protected].

Authorisation

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