Overview

Add the Checkout experience to any merchant website by sending a POST request over HTTPS to one of the following URLs to begin the customer payment flow:

• /checkout/initiate for Redirect-based Checkout. Peach Payments recommends this approach.
• /checkout for a form POST Checkout.

🚧

For the form POST method, you must sign the data on the backend and execute the POST from the browser.

You must sign the request and include the required and optional custom parameters. Include the signature parameter to verify the request. When the customer has completed their purchase, Checkout uses a POST request to redirect them back to the merchant's shopperResultUrl. In the redirect, the merchant receives a response confirming the outcome of the payment flow.

Executing a POST using either of the methods above redirects the customer to secure.peachpayments.com/checkout to complete their payment. The POST request must contain the entityId, signature parameter, purchase parameters, and any custom parameters that a merchant optionally sends.

Redirect-based Checkout

To learn more about the required and optional parameters, see the API reference section. Peach Payments recommends that you send the optional parameters as this extra context can help with flagging fraudulent transactions.

The Redirect-based Checkout flow works as follows:

1. The merchant initiates the checkout by making a request to the /checkout/initiate endpoint.
2. The Checkout API responds with a redirect URL for the checkout instance.
3. The merchant redirects the customer to the returned checkout redirect URL.
4. The Checkout API renders the checkout user interface.
5. The Checkout API sends a webhook to the merchant, informing them of the checkout creation.
6. The customer submits the required payment information.
7. The Checkout API sends a webhook to the merchant, informing them that the checkout is pending.
8. When the checkout is successful, cancelled, or expired, the Checkout API sends a webhook to the merchant, informing them of the result of the checkout.
9. The Checkout API redirects the customer back to the URL specified in the shopperResultUrl of the original checkout request.

Example Redirect-based Checkout

curl --location -g --request POST 'https://testsecure.peachpayments.com/checkout/initiate' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'Referer: https://mydemostore.com' \
--data-urlencode 'authentication.entityId=8ac7a4ca68c22c4d0168c2caab2e0025' \
--data-urlencode 'signature=311ed8e11e2da00d98c7479ca390a5396fe643e13629d850243dada877963afd' \
--data-urlencode 'merchantTransactionId=Test1234' \
--data-urlencode 'amount=100.00' \
--data-urlencode 'paymentType=DB' \
--data-urlencode 'currency=ZAR' \
--data-urlencode 'nonce=JHGJSGHDSKJHGJDHGJH' \
--data-urlencode 'shopperResultUrl=https://mydemostore.com' \
--data-urlencode 'defaultPaymentMethod=CARD' \
--data-urlencode 'forceDefaultMethod=false' \
--data-urlencode 'merchantInvoiceId=Test1234' \
--data-urlencode 'customParameters[example]=example' \
--data-urlencode 'customer.merchantCustomerId=0001' \
--data-urlencode 'customer.givenName=John' \
--data-urlencode 'customer.surname=Smith' \
--data-urlencode 'customer.mobile=0712345678' \
--data-urlencode '[email protected]' \
--data-urlencode 'customer.status=NEW' \
--data-urlencode 'customer.birthDate=1999-01-01' \
--data-urlencode 'customer.ip=192.168.1.1' \
--data-urlencode 'customer.phone=0212345678' \
--data-urlencode 'billing.street1=1 Example Road' \
--data-urlencode 'billing.street2=LocalityA' \
--data-urlencode 'billing.city=Cape Town' \
--data-urlencode 'billing.company=CompanyA' \
--data-urlencode 'billing.country=ZA' \
--data-urlencode 'billing.state=Western Cape' \
--data-urlencode 'billing.postcode=7000' \
--data-urlencode 'shipping.street1=1 Example Road' \
--data-urlencode 'shipping.street2=LocalityA' \
--data-urlencode 'shipping.city=Cape Town' \
--data-urlencode 'shipping.company=CompanyA' \
--data-urlencode 'shipping.postcode=7000' \
--data-urlencode 'shipping.country=ZA' \
--data-urlencode 'shipping.state=Western Cape' \
--data-urlencode 'cart.tax=15.00' \
--data-urlencode 'cart.shippingAmount=12.25' \
--data-urlencode 'cart.discount=02.25' \
--data-urlencode 'createRegistration=false' \
--data-urlencode 'notificationUrl=' \
--data-urlencode 'cancelUrl='

Form POST Checkout

To learn more about the required and optional parameters, see the API reference section. Peach Payments recommends that you send the optional parameters as this extra context can help with flagging fraudulent transactions.

The form POST Checkout flow works as follows:

1. The merchant signs the checkout request data and populates a form on the web page with the request data and signature. The customer initiates the checkout by submitting the form to the /checkout endpoint.
2. The Checkout API sends a webhook to the merchant, informing them of the checkout creation.
3. The Checkout API renders the checkout user interface.
4. The customer submits the required payment information.
5. The Checkout API sends a webhook to the merchant, informing them that the checkout is pending.
6. When the checkout is successful, cancelled, or expired, the Checkout API sends a webhook to the merchant, informing them of the result of the checkout.
7. The Checkout API redirects the customer back to the URL specified in the shopperResultUrl of the original checkout request.

Example form POST Checkout

< form name = "Checkout" action = "https://testsecure.peachpayments.com/checkout"
        method = "POST"
        accept-charset = "utf-8" >
< input type = "hidden"
        name = "amount"
        value = "2" />
< input type = "hidden"
        name = "authentication.entityId"
        value = "8ac7a4ca68c22c4d0168c2caab2e0025" />
< input type = "hidden"
        name = "currency"
        value = "ZAR" />
< input type = "hidden"
        name = "defaultPaymentMethod"
        value = "CARD" />
< input type = "hidden"
        name = "merchantTransactionId"
        value = "Test1234" />
< input type = "hidden"
        name = "nonce"
        value = "JHGJSGHDSKJHGJDHGJH" />
< input type = "hidden"
        name = "paymentType"
        value = "DB" />
< input type = "hidden"
        name = "shopperResultUrl"
        value = "https://webhook.site/4e9b63bf-0d99-4d62-bd24-1d36ca866e1b" />
< input type = "hidden"
        name = "signature"
        value = "311ed8e11e2da00d98c7479ca390a5396fe643e13629d850243dada877963afd" />
< input type = "submit" value = "Continue to Payment Method" />
</ form >

Tokenisation

Tokenisation allows you to store payment data for later use. This can be useful for recurring and one-click payments.

📘

Tokenisation is only available for card payments.

Set defaultPaymentMethod=CARD and forceDefaultMethod=true to ensure the user always pays with card. During the Checkout process, store the data by ensuring that createRegistration=true. You can now use the recurring API for recurring payments and can also enable one-click payments for the tokenised card.

After the account holder has filled in their card details, Checkout uses a POST request to redirect them back to your shopperResultUrl. You can retrieve the response information using payment status. This time, the response includes a registrationId token and useful card information that you can store for future recurring or one-click payment requests.

Example requests and responses

For sample requests and responses, see the interactive API playground or use the Peach Payments Postman collection: