WebsiteStatusSupportPostman workspacePricingDocumentation hub survey
API reference
RSS feedSign up

Initiate redirect-based checkout

post
https://testsecure.peachpayments.com/checkout/initiate

Provide a redirect URL to the caller to redirect the user to Hosted Checkout. The POST request contains the entityId, signature, purchase parameters, and any custom parameters that a merchant optionally sends. This allows the checkout to be created from a backend without requiring a "form post", or other similar method, from the frontend. For more information, see the documentation, and for sample calls, see the public Postman collection.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
required
length ≤ 32

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

string
required
length ≤ 64

Token to verify the integrity of the payment, ensuring that only the merchant sending the request is accepted.

string
required
length between 8 and 16

Merchant-provided reference number unique for your transactions.

string
required

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.

string
enum
required

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:
string
enum
required

The currency code of the payment request amount.

Allowed:
string
required
length ≤ 64

Unique value to represent each request.

string
required

Checkout uses a POST request to redirect the customer to this URL after the customer completes checkout. Must be a valid URL that can be accessed through a browser.

string
enum

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

string
enum
Defaults to false

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

Allowed:
string
length between 8 and 255

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

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.

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.

string

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.

string
length between 0 and 48

An identifier for this customer. Typically this is the ID that identifies the shopper in the shop's system.

string
length between 0 and 48

The customer's first name or given name. Required if you send in any other customer parameters, and for some risk checks and payment providers. Peach Payments recommends including the name so that it displays in the Peach Dashboard and is available for subsequent queries. Truncated after 48 characters.

string
length between 0 and 48

The customer's last name or surname. Required if you send in any other customer parameters, and for some risk checks and payment providers. Peach Payments recommends including the surname so that it displays in the Peach Dashboard and is available for subsequent queries. Truncated after 48 characters.

string
length between 5 and 24

The customer's mobile number.

string
length between 6 and 128

The customer's email address.

string
enum

The customer's status. Accepts NEW or EXISTING.

Allowed:
string

The customer's birth date in the yyyy-MM-dd format.

string
length between 1 and 255

The customer's IP address.

string
length between 5 and 24

The customer's phone number.

string
length between 13 and 13

The customer's ID number, required for high-risk merchants supporting Capitec Pay.

string
length between 1 and 100

The door number, floor, building number, building name, and/or street name of the billing address.

string
length between 1 and 100

The adjoining road or locality, if required, of the billing address.

string
length between 1 and 80

The town, district, or city of the billing address.

string
length between 1 and 64

The company of the billing address.

string
length between 2 and 2

The country of the billing address (ISO 3166-1 alpha-2).

string
length between 1 and 50

The county, state, or region of the billing address.

string
length between 1 and 30

The postal code or ZIP code of the billing address.

string
length between 1 and 100

The door number, floor, building number, building name, and/or street name of the shipping address.

string
length between 1 and 100

The adjoining road or locality, if required, of the shipping address.

string
length between 1 and 80

The town, district, or city of the shipping address.

string
length between 1 and 64

The company of the shipping address.

string
length between 1 and 30

The postal code or ZIP code of the shipping address.

string
length between 2 and 2

The country of the shipping address (ISO 3166-1 alpha-2).

string
length between 1 and 50

The county, state, or region of the shipping address.

string

The tax percentage applied to the price of the item in the shopping cart.

string

The total amount of the cart item including quantity.

string

Discount amount applied on order amount.

string
enum

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.

Allowed:
string

List of comma-separated 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.

string
enum

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.

Allowed:
date

Expiry date for recurring payments. Use it with createRegistration or allowStoringDetails to set a validity period for credential-on-file tokenisation. This parameter is conditional; mandatory when processing 3-D Secure on recurring transactions and optional for other transactions. If provided, the saved card expires on this date. If not provided, the saved card has no expiry constraint. Must be a future date. Commonly set to 1-3 years from the present date.

string

Number of days between recurring payment authorisations (1-9999). Use it with createRegistration or allowStoringDetails to indicate expected payment frequency. This parameter is conditional; mandatory when processing 3-D Secure on recurring transactions and optional for other transactions. Common values: 7 (weekly), 30 (monthly), 90 (quarterly), 365 (yearly). If not provided, the saved card has no frequency constraint.

string
enum

Conditional type of recurring MIT (Merchant Initiated Transaction) agreement. Indicates whether payments are for fixed or variable amounts.

  • SUBSCRIPTION: Fixed amount and fixed frequency (for example, a monthly newspaper subscription at R99.99/month). - STANDING_ORDER: Variable amount and fixed frequency (for example, a monthly utility payment where the amount varies). Requirements: - Required for all Mastercard CIT and MIT transactions. - Required for Visa recurring transactions executed with cards issued in India. If not provided, this parameter is not sent to the payment gateway.
Allowed:
string
enum

Category of the transaction for credential-on-file payments.

  • RECURRING: Transactions processed at regular fixed intervals for pre-agreed amounts. No fixed duration. - INSTALLMENT: Transactions processed at regular fixed intervals for pre-agreed amounts with a fixed duration for a single purchase. - UNSCHEDULED: Credential-on-file transactions triggered by events (for example, minimum balance threshold), not at pre-agreed intervals. If not provided, the system auto-determines the type based on other parameters.
Allowed:
string
enum

Mode indicating the payment transaction stage.

  • INITIAL: First payment in a series. Must contain authentication data (CVV, 3DS). - REPEATED: Subsequent payment without shopper present. No authentication data required. If not provided, the system auto-sets based on context (INITIAL for new registrations, REPEATED for token payments).
Allowed:
string
enum

MIT type for business practice follow-ups to original cardholder interactions.

  • INCREMENTAL_AUTH: Increase total amount authorised (for example, hotel incidentals). - RESUBMISSION: Retry authorisation after initial decline for insufficient funds. - REAUTHORIZATION: Re-authorise after cardholder has left (for example, split shipment). - DELAYED_CHARGES: Charges processed after service completion (for example, hotel checkout, car rental). - NO_SHOW: Charge for missed reservation or appointment.
Allowed:
string

Maximum number of authorisations permitted for installment payments (1-999). Required when merchant and cardholder have agreed to installment payments with EMV 3-D Secure authentication configured (that is, when standingInstruction.type=INSTALLMENT). Omit if not an installment payment.

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.

string
length ≤ 100

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

string
enum

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

Allowed:
Headers
string
required

An allowlisted domain for the merchant.

string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

400

Invalid authentication information.

500

Internal server error.

Updated 3 months ago

Language
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
text/html
application/json

Updated 3 months ago