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.

📘

Hosted Checkout can tokenise cards.

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 in an uncertain status, 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://example.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://example.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 in an uncertain status, 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://example.com/example-webhook" />
< input type = "hidden"
        name = "signature"
        value = "311ed8e11e2da00d98c7479ca390a5396fe643e13629d850243dada877963afd" />
< input type = "submit" value = "Continue to Payment Method" />
</ form >

Example requests and responses

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