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 a redirect-based Checkout
/checkout for a form POST Checkout

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

Below is a list of all allowed parameters and their descriptions. Send the required parameters in every single request to the API. Peach Payments recommends that you send the optional parameters as this extra context can help with flagging fraudulent transactions.

Parameters

Parameter	Description	Format	Condition
`authentication.entityId`	The entity for the request. By default this is the channel's ID.	AN32 [a-f0-9]{32}	Required
`signature`	The signature for the request.	AN64 [a-f0-9]{64}	Required
`merchantTransactionId`	Merchant-provided reference number, should be unique for your transactions.	AN255 [\s\S]{8,255}	Required
`amount`	The amount of the payment request. The dot is the decimal separator.	N10.N2 [0-9]{1,10}(.[0-9]{2})?	Required
`paymentType`	The payment type for the request; supports the `DB` payment type.	A2	Required
`currency`	The currency code of the payment request amount; supports ZAR, USD, KES, MUR, GBP, and EUR.	A3 [A-Z]{3}	Required
`createRegistration`	If true, the customer's card details are stored with the request. The response includes the `registration.id` parameter which you can use to reference the registration for later payments.	A5 true\|false	Optional
`nonce`	Unique value to represent each request.		Required
`shopperResultUrl`	The customer is redirected to this URL after the completion of Checkout. Must be a valid URL that can be accessed through a browser.	AN2048 [\s\S]{6,2048}	Required
`defaultPaymentMethod`	The preferred payment method that is the active payment method in the Checkout page at the point of redirecting.	Possible values: - `CARD` - `MOBICRED` - `MASTERPASS` - `EFTSECURE` - `MPESA` - `APLUS` - `1FORYOU` - `PAYPAL` - `ZEROPAY` - `PAYFLEX` - `STITCHEFT` - `FINCHOICEPAY` - `BLINKBYEMTEL` - `CAPITECPAY` Note: Certain payment methods are in pilot phase and might not be available to you. For more information, contact support.	Optional
`merchantInvoiceId`	Merchant-provided invoice number; should be unique for your transactions. This identifier is not sent onwards.	AN255 [\s\S]{8,255}	Optional
`customParameters[name]`	A name value pair used for sending custom information.	name: AN64 [a-zA-Z0-9._]{3,64} value: AN2048 [\s\S]{0,2048}	Optional
`customer.merchantCustomerId`	An identifier for this customer. Typically this is the ID that identifies the shopper in the shop's system.		Optional
`customer.givenName`	The first name or given name of the customer. Required if you send any other customer parameters, also required for some risk checks and payment providers. Truncated after 48 characters.	AN [\s\S]	Optional
`customer.surname`	The last name or surname of the customer. Required if you send any other customer parameters, also required for some risk checks and payment providers. Truncated after 48 characters.	AN [\s\S]	Optional
`customer.mobile`	The customer's mobile number.	AN25 [+0-9][0-9 \.()/-]{5,24}	Optional
`customer.email`	The customer's email address.	AN128 [\s\S]{6,128}	Optional
`customer.status`	The status of the customer. Can be `NEW` or `EXISTING`.	A9 [\s\S]{1,255}	Optional
`customer.birthDate`	The birth date of the customer in the yyyy-MM-dd format, for example, 1970-02-17.	AN10 {19\|20)([0-9]{2})-(0[1- 9]\|1[0-2])-(0[1-9]\|1[0-9 ]\|2[0-9]\|3[0-1]}	Optional
`customer.ip`	The customer's IP address.	AN255 [\s\S]{1,255}	Optional
`customer.phone`	The customer's phone number.	AN25 [+0-9][0-9 \.()/-]{5,24}	Optional
`billing.street1`	The door number, floor, building number, building name, and street name of the billing address.	AN100 [\s\S]{1,100}	Optional
`billing.street2`	The adjoining road or locality (if required) of the billing address.	AN100 [\s\S]{1,100}	Optional
`billing.city`	The town, district, or city of the billing address.	AN80 [\s\S]{1,80}	Optional
`billing.country`	The country of the billing address (ISO 3166-1).	A2 [A-Z]{2}	Optional
`billing.state`	The county, state, or region of the billing address.	AN50 [a-zA-Z0-9.]{1,50}	Optional
`billing.postcode`	The postal code or zip code of the billing address.	AN30 [A-Za-z0-9]{1,30}	Optional
`shipping.street1`	The door number, floor, building number, building name, and street name of the shipping address.	[\s\S]{1,100}	Optional
`shipping.street2`	The adjoining road or locality (if required) of the shipping address.	AN100 [\s\S]{1,100}	Optional
`shipping.city`	The town, district, or city of the shipping address.	AN80 [a-zA-Z]{1,80}	Optional
`shipping.postcode`	The postal code or zip code of the shipping address.	AN30 [A-Za-z0-9]{1,30}	Optional
`shipping.country`	The country of the shipping address (ISO 3166-1).	A2 [A-Za-z]{2}	Optional
`shipping.state`	The county, state, or region of the shipping address.	AN50 [a-zA-Z0-9.]{1,50}	Optional

Tokenisation

Tokenisation allows you to store payment data for later use. This can be useful for subscription 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.

After the account holder has filled in their card details, Checkout redirects 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 subscription payment requests.

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='

Example form POST

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