Checkout payment request

Overview

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

  • /checkout/initiate for a redirect-based Checkout
  • /checkout for a form POST Checkout

The request must be signed and include the required parameters below in addition to optional custom parameters. A signature parameter is included to validate the request. When the customer has completed their purchase they are redirected 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. The required parameters are expected in every single request that is sent to the API. We recommend that you send the optional parameters as this extra context can help with flagging fraudulent transactions.

Parameters

ParameterDescriptionFormatCondition
authentication.entityIdThe entity for the request. By default this is the channel's ID.AN32
[a-f0-9]{32}
Required
signatureThe signature for the request.AN64
[a-f0-9]{64}
Required
merchantTransactionIdMerchant-provided reference number, should be unique for your transactions.AN255
[\s\S]{8,255}
Required
amountThe amount of the payment request. The dot is used as the decimal separator.N10.N2
[0-9]{1,10}(.[0-9]{2})?
Required
paymentTypeThe payment type for the request; supports the DB payment type.A2Required
currencyThe currency code of the payment request amount. ZAR and KES are supported.A3
[A-Z]{3}
Required
createRegistrationIf true, the customer’s card details are stored with the request. As part of the response, the registration.id parameter is returned which you can use to reference the registration for later payments.A5
true|false
Optional
nonceUnique value to represent each request.Required
shopperResultUrlThe 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
defaultPaymentMethodThe 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

Note: Certain payment methods are being piloted and might not be available to you. For more information, please check with your account manager or contact support.
Optional
merchantInvoiceIdMerchant-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.merchantCustomerIdAn identifier for this customer. Typically this is the ID that identifies the shopper in the shop's system.Optional
customer.givenNameThe 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.surnameThe 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.mobileThe customer's mobile number.AN25
[+0-9][0-9 \.()/-]{5,24}
Optional
customer.emailThe customer's email address.AN128
[\s\S]{6,128}
Optional
customer.statusThe status of the customer. Can be NEW or EXISTING.A9
[\s\S]{1,255}
Optional
customer.birthDateThe 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.ipThe customer's IP address.AN255
[\s\S]{1,255}
Optional
customer.phoneThe customer's phone number.AN25
[+0-9][0-9 \.()/-]{5,24}
Optional
billing.street1The door number, floor, building number, building name, and/or street name of the billing address.AN100
[\s\S]{1,100}
Optional
billing.street2The adjoining road or locality (if required) of the billing address.AN100
[\s\S]{1,100}
Optional
billing.cityThe town, district, or city of the billing address.AN80
[\s\S]{1,80}
Optional
billing.countryThe country of the billing address (ISO 3166-1).A2
[A-Z]{2}
Optional
billing.stateThe county, state, or region of the billing address.AN50
[a-zA-Z0-9.]{1,50}
Optional
billing.postcodeThe postal code or zip code of the billing address.AN30
[A-Za-z0-9]{1,30}
Optional
shipping.street1The door number, floor, building number, building name, and/or street name of the shipping address.[\s\S]{1,100}Optional
shipping.street2The adjoining road or locality (if required) of the shipping address.AN100
[\s\S]{1,100}
Optional
shipping.cityThe town, district, or city of the shipping address.AN80
[a-zA-Z]{1,80}
Optional
shipping.postcodeThe postal code or zip code of the shipping address.AN30
[A-Za-z0-9]{1,30}
Optional
shipping.countryThe country of the shipping address (ISO 3166-1).A2
[A-Za-z]{2}
Optional
shipping.stateThe 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.

📘

Tokenization 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 and is redirected back to your shopperResultUrl, you can retrieve the response information using payment status. This time, however, 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 >