---
updatedAt: 2026-05-25T16:41:59.000Z
agentTools:
  projectIndex: https://developer.peachpayments.com/llms.txt
---

# Hosted Checkout authentication and authorisation

# Security and authentication

All requests must be over SSL.

## 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](https://dashboard.peachpayments.com/checkout#api-keys).

### 1. Prepare parameters for signature generation

* Include all payment parameters (even empty ones) and sort them in alphabetical order.
* Concatenate parameter names and values into a single string without spaces or special characters.
* Use the secret token as the key.

### 2. Generate and verify the signature

* Use the HMAC SHA256 algorithm to sign the concatenated string with the secret token.
* Include the generated signature in the request for validation by Peach Payments.

<Callout icon="📘" theme="info">
See the [Checkout PHP SDK](https://gitlab.com/p2886/checkout-php-sdk/-/blob/main/lib/Signature.php?ref_type=heads) for an example showing how to generate the Checkout signature.
</Callout>

```python
request_data = {
  "amount": "2",
  "authentication.entityId": "8ac7a4ca68c22c4d0168c2caab2e0025",
  "currency": "ZAR",
  "defaultPaymentMethod": "CARD",
  "merchantTransactionId": "Test1234",
  "nonce": "JHGJSGHDSKJHGJDHGJH",
  "paymentType": "DB",
  "shopperResultUrl": "https://example.com/example-webhook",
  "notificationUrl": "",
}

secret_string = "".join([str(key) + str(request_data[key]) for key in sorted(request_data)])
# secret_string = amount2authentication.entityId8ac7a4ca68c22c4d0168c2caab2e0025currencyZARdefaultPaymentMethodCARDmerchantTransactionIdTest1234nonceJHGJSGHDSKJHGJDHGJHnotificationUrlpaymentTypeDBshopperResultUrlhttps://example.com/example-webhook
```

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:**

```text
amount2authentication.entityId8ac7a4ca68c22c4d0168c2caab2e0025currencyZARdefaultPaymentMethodCARDmerchantTransactionIdTest1234nonceJHGJSGHDSKJHGJDHGJHpaymentTypeDBshopperResultUrlhttps://example.com/example-webhook
```

**Secret token:**

```text
3fcd7cf22f55119eadbe02d14de18c0c
```

**Computed HMAC:**

```text
311ed8e11e2da00d98c7479ca390a5396fe643e13629d850243dada877963afd
```

Verify your HMAC SHA256 algorithm using the [FreeFormatter HMAC testing tool](https://www.freeformatter.com/hmac-generator.html).

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](https://developer.peachpayments.com/reference/post_checkout-initiate) section for a full list of the supported parameters.

```python
import hashlib
import hmac

message = "amount2authentication.entityId8ac7a4ca68c22c4d0168c2caab2e0025currencyZARdefaultPaymentMethodCARDmerchantTransactionIdTest1234nonceJHGJSGHDSKJHGJDHGJHpaymentTypeDBshopperResultUrlhttps://example.com/example-webhook".encode('utf-8')
secret = "3fcd7cf22f55119eadbe02d14de18c0c".encode('utf-8')

signature = hmac.new(key=secret, msg=message, digestmod=hashlib.sha256).hexdigest()
print(signature)
```
```TypeScript
import CryptoJS from "crypto-js";

const secret = "3fcd7cf22f55119eadbe02d14de18c0c";
const message = "amount2authentication.entityId8ac7a4ca68c22c4d0168c2caab2e0025currencyZARdefaultPaymentMethodCARDmerchantTransactionIdTest1234nonceJHGJSGHDSKJHGJDHGJHpaymentTypeDBshopperResultUrlhttps://example.com/example-webhook";

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

console.log(signature);
```

## 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.

## 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](https://developer.peachpayments.com/docs/dashboard-overview#log-in-to-the-dashboard) to your Peach Payments Dashboard.

2. In the left navigation menu, click **Checkout**.
   <Callout icon="📘" theme="info">
     If you don't have access to the **Checkout** section, [contact support](https://support.peachpayments.com/support/tickets/new?ticket_form=log_a_support_ticket).
   </Callout>

3. Scroll down to the **Allowlisted domains** section and click **Add domain**.

4. Enter each domain, subdomain, or IP that you want to add to the allowlist, pressing **Enter** after each one, then click **Add**.

   <Image src="https://files.readme.io/ca363652a056c9584178ca8b68cad67a1dff03ee6a28ebc7f89108fb28542c2e-image.png" alt="Add domains to the allowlist." align="center" width="450px" caption="Add domains to the allowlist." />

5. If a 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. If the domain fails the Peach Payments risk checks, it enters a declined state for 14 days, whereafter Peach Payments removes it from the domain list.

<Callout icon="📘" theme="info">
  Adding domains on sandbox does not need verification.
</Callout>

### Delete a domain from the allowlist

<Callout icon="📘" theme="info">
  You cannot delete pending or declined domains.
</Callout>

To delete a domain from the allowlist:

1. [Log in](https://developer.peachpayments.com/docs/dashboard-overview#log-in-to-the-dashboard) to your Peach Payments Dashboard.
2. In the left navigation menu, click **Checkout**.
   <Callout icon="📘" theme="info">
     If you don't have access to the **Checkout** section, [contact support](https://support.peachpayments.com/support/tickets/new?ticket_form=log_a_support_ticket).
   </Callout>
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.