With Peach Payments, you can do a custom integration with our hosted payments page.

If you checkout on this Shopify store, you should see what the hosted payments page looks like.

Shopify demo: https://peach-payments-demo.myshopify.com/ 

Let's consider you are building a custom web app, and not using a CMS where the payment process is already integrated. In this scenario, you will want to use our Checkout hosted payments page via a custom Integration.

Attached is an in-depth Integration Guide, however, we have summarised this in a quick breakdown below:

Step 1: Generate signature

Use a tool such as https://www.freeformatter.com/hmac-generator.html  to verify your HMAC256 algorithm

The required parameters for the concatenated string used for input to generate the signature payment status on Checkout are as follows:

  • amount
  • authentication.entityId
  • currency
  • merchantTransactionId (must be equal to or less than 16 alphanumeric characters)
  • nonce
  • paymentType
  • shopperResultUrl

Then you will need to use your Secret Key provided by Peach as part of your account credentials to generate the signature using the concatenated string.

Sample Concatenated String:


Step 2: Generate Checkout

Checkout using params:

    [amount] => 10.00

    [authentication.entityId] => 8ac7a4ca7802ed8e0178176ca52222dc

    [currency] => ZAR

    [merchantTransactionId] => PeachTest

    [nonce] => PeachTest

    [paymentType] => DB

    [shopperResultUrl] => https://httpbin.org/post 

    [signature] => 8d42cb8b70bbc597f51ac2afd76c9541508fb5c2d6d2d0d5fd3df5c0439c77db

Here is a sample HTML form with the above:


<form name="form" action="D" method="POST" accept-charset="utf-8">

    <input type="hidden" name="amount" value="10.00" />

    <input type="hidden" name="authentication.entityId" value="8ac7a4ca7802ed8e0178176ca52222dc " />

    <input type="hidden" name="currency" value="ZAR" />

    <input type="hidden" name="merchantTransactionId" value="PeachTest" />

    <input type="hidden" name="nonce" value="PeachTest" />

    <input type="hidden" name="paymentType" value="DB" />

    <input type="hidden" name="shopperResultUrl" value="https://httpbin.org/post" />

    <input type="hidden" name="signature" value="8d42cb8b70bbc597f51ac2afd76c9541508fb5c2d6d2d0d5fd3df5c0439c77db" />

    <input type="submit" value="Continue to Payment Method"/>


When a payment occurs a webhook response is sent to the shopperResultUrl specified in the Checkout request. Below is an example of a webhook response:


  "args": {}, 

  "data": "", 

  "files": {}, 

  "form": {

    "amount": "1.00", 

    "card.bin": "411111", 

    "card.expiryMonth": "12", 

    "card.expiryYear": "2023", 

    "card.holder": "test", 

    "card.last4Digits": "1111", 

    "checkoutId": "c87db0da697548fba209d2c16dcf00a6", 

    "currency": "ZAR", 

    "id": "8ac7a4a080d934110180db4b6cd44cf0", 

    "merchant.name": "PeachTest", 

    "merchantTransactionId": "PeachTest1", 

    "paymentBrand": "VISA", 

    "paymentType": "DB", 

    "registrationId": "8ac7a4a180d9320a0180db4b6c3b50c0", 

    "result.code": "000.100.110", 

    "result.description": "Request successfully processed in 'Merchant in Integrator Test Mode'", 

    "signature": "058a11ce9d8b0b316e022e7e4131b34ac9369dfa7cde14a3b7774134a21a7c31", 

    "timestamp": "2022-05-19T07:50:01Z"


The "checkoutId" field is important to note here as it is required in the GET status call.

Step 3: Query Payment

The required parameters for a GET payment status on Checkout are as follows:

  • merchantTransactionId
  • entityId
  • checkoutId
  • signature

Query transaction using a new signature from the parameters above.

Note: the checkoutId is found in the payment response which is automatically sent to your redirect URL.

NB: You can't reuse the signature because its encryption input is different

Sample Concatenated String:


GET Status Call:

curl --location --request GET 'https://testapi.peachpayments.com/v1/checkout/status?merchantTransactionId=PeachTest&authentication.entityId=8ac7a4ca7802ed8e0178176ca52222dc&signature=bf875bd49f4c6d398aeeb944140636088ca276d665a17dbf08abea9432d6a80c&checkoutId=5afc3fbc799e4ac5bb9ab1e503228bba'

GET Status response:


    "amount": "10.00",

    "card.bin": "411111",

    "card.expiryMonth": "12",

    "card.expiryYear": "2023",

    "card.holder": "Peach Test",

    "card.last4Digits": "1111",

    "checkoutId": "5afc3fbc799e4ac5bb9ab1e503228bba",

    "currency": "ZAR",

    "id": "8ac7a4a07f1ef705017f22264ac461a1",

    "merchant.name": "Test Account",

    "merchantTransactionId": "PeachTest",

    "paymentBrand": "VISA",

    "paymentType": "DB",

    "result.code": "000.100.110",

    "result.description": "Request successfully processed in 'Merchant in Integrator Test Mode'",

    "signature": "8d42cb8b70bbc597f51ac2afd76c9541508fb5c2d6d2d0d5fd3df5c0439c77db",

    "timestamp": "2022-02-22T15:56:56Z"


For a more detailed breakdown of Custom Checkout, please see the attached Integration Documentation.
Please do reach out to support@peachpayments.com if you have further questions.