Initiate checkout

post

https://testsecure.peachpayments.com/v2/checkout

Create a checkout to use in Embedded Checkout or redirect the customer to the redirectUrl for Hosted Checkout. For more information, see the Embedded Checkout or Hosted Checkout documentation, and for sample calls, see the public Postman collection.

Body Params

authentication.entityId

string

required

length ≤ 32

The entity for the request. By default, this is the channel ID.

merchantTransactionId

string

required

length between 8 and 16

Merchant-provided reference number unique for your transactions.

amount

number

required

0 to 99999999.99

The amount of the payment request. The period is used as the decimal separator. An amount of 0 is only supported when the paymentType is PA and createRegistration is set to true. M-PESA does not support decimal amounts, so Checkout automatically rounds them up.

currency

string

enum

required

The currency code of the payment request amount.

Allowed:

paymentType

string

enum

The payment type for the request. Does not accept RG, but you can tokenise a card by performing a DB or PA with createRegistration. PA is only supported when forceDefaultMethod is set to true and defaultPaymentMethod is CARD. Following a PA, you can either capture or reverse the PA. Refund transactions through the Dashboard or as described in the documentation.

Allowed:

nonce

string

required

length between 1 and 64

Unique value to represent each request.

shopperResultUrl

string

required

Checkout uses a POST request to redirect the customer to this URL after the customer completes checkout. Embedded Checkout allows you to override the redirect behaviour by using the onCompleted event. Note: Must be a valid URL that can be accessed through a browser.

defaultPaymentMethod

string

enum

Checkout opens in this payment method. Customers can choose to go back and select a different payment method.

forceDefaultMethod

boolean

Defaults to false

Force the default payment method to be the only payment method available.

merchantInvoiceId

string

length between 8 and 255

Merchant-provided invoice number unique for your transactions. Truncated to 17 characters for FNB acquiring.

cancelUrl

string

The customer is redirected to this URL if they cancel checkout. To enable the cancelUrl parameter, contact support. Note: It must be a valid URL that can be reached through a browser.

notificationUrl

string

Checkout sends a webhook to this URL for any changes to the checkout, in addition to the webhook sent to the Dashboard-configured webhook URL.

customParameters

object

A name value pair used for sending custom information. To display custom parameters in the Peach Payments Dashboard > transaction details panel > More details tab, use the "customParameters":{"auxData":"{\"user_id\":\"12345\",\"paymentId\":\"98765\"}"} format, changing the parameters as required.

customer

object

billing

object

shipping

object

createRegistration

boolean

Used to enable card tokenisation when customer pays with card. You must get permission from your customer before tokenising their cards. Cannot be true if allowStoringDetails is true.

originator

string

length ≤ 100

Used to provide a name for the application that is creating the checkout instance.

returnTo

string

enum

Text to display on "Return to Store" button on completing checkout.

Allowed:

cardTokens

array of strings

List of card tokens. The card tokens must be linked to the customer as they enable one-click payment support for the customer. See the documentation for more information.

cardTokens

allowStoringDetails

boolean

Allow the customer to store their card details for future use. When this is set, the customer is given an option to tokenise their card during checkout. If the customer chooses to store their card details, a registrationId is returned in the response from checkout. Similar to createRegistration. Cannot be true if createRegistration is true. See the documentation for more information.

standingInstruction

object

Standing instruction parameters for credential-on-file payments. Use them with createRegistration to set constraints for credential-on-file tokenisation.

cardRemovalUrl

string

If a customer removes a stored card, you must remove it from their profile, and ensure that you do not provide the removed card's token when using the cardTokens parameter. Checkout sends a POST request to this URL when the customer removes a card from Hosted Checkout so that you know which token to remove from your customer's profile. Checkout sends the following parameters in the POST request:

checkoutId - ID of the checkout instance.
registrationId - ID of the card token removed.
signature - Signature of the request.

If you are using Embedded Checkout, please use the onRemoveCard callback instead.

descriptor

string

length ≤ 127

Override a portion of the descriptor displayed on the customer's bank statement.

merchant.name

string

length ≤ 100

Override the descriptor displayed on the customer's bank statement.

enableAddNewCard

boolean

Whether to enable the "Add New Card" button.

cardSubmitButtonText

string

length ≤ 50

Custom text for the card submit button. Defaults to "Pay Now" if not provided.

cardHeadingText

string

length ≤ 255

Custom heading text for the card form. Defaults to "Please enter your card details below to complete the payment." if not provided.

cardHeadingSavedCardsText

string

length ≤ 255

Custom heading text for the header section when there are cards saved.

Headers

Referer

string

required

An allowlisted domain for the merchant.

Responses

200Checkout successfully created.

400A validation error has occurred with Checkout.

401Request lacks valid authentication, message in response contains specifics.

404Invalid entity ID passed.

500Internal server error.