v1

latestOpenAPI 3.0.3Proprietary2026-07-2441103204.8 KB

Validate checkout request

Validate a request before trying to initiate a checkout. For sample calls, see the public Postman collection.

post/v2/checkout/validate

Headers

Refererstring required

Example:https://example.com

An allowlisted domain for the merchant.

Request body

authentication.entityIdstring required

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

merchantTransactionIdstring 8-16 required

Merchant-provided reference number unique for your transactions.

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

currency'ZAR' | 'USD' | 'KES' | 'MUR' | 'GBP' | 'EUR' required

The currency code of the payment request amount.

paymentType'DB' | 'PA'

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.

noncestring string (1-64) required

Unique value to represent each request.

shopperResultUrlstring string (6-2048) 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.

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

forceDefaultMethodboolean

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

merchantInvoiceIdstring string (8-255)

Merchant-provided invoice number unique for your transactions. Truncated to 17 characters for FNB, SBSA, MCB, and SBM acquiring.

cancelUrlstring string (6-2048)

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.

notificationUrlstring string (6-2048)

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.

customParametersobject

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.

createRegistrationboolean

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.

originatorstring

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

returnTo'STORE' | 'INVOICE'

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

cardTokensstring[]

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.

allowStoringDetailsboolean

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.

cardRemovalUrlstring string (6-2048)

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.

descriptorstring [\s\S]{1,127}

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

merchant.namestring [\s\S]{1,100}

Override the descriptor displayed on the customer's bank statement. Only applicable to card payments; does not affect other payment methods.

enableAddNewCardboolean

Whether to enable the "Add New Card" button.

cardSubmitButtonTextstring

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

cardHeadingTextstring

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

cardHeadingSavedCardsTextstring

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

Example request

{
  "authentication.entityId": "8ac7a4ca94809723019482814def011f",
  "merchantTransactionId": "OrderNo453432",
  "amount": 1010,
  "currency": "ZAR",
  "paymentType": "DB",
  "nonce": "UNQ00012345678",
  "shopperResultUrl": "https://example.com/OrderNo453432",
  "defaultPaymentMethod": "CARD",
  "forceDefaultMethod": true,
  "merchantInvoiceId": "INV-00001",
  "cancelUrl": "https://example.com/OrderNo453432/cancelled",
  "notificationUrl": "https://example.com/OrderNo453432/webhook",
  "customer": {
    "merchantCustomerId": "971020",
    "givenName": "John",
    "surname": "Smith",
    "mobile": "+27123456789",
    "email": "johnsmith@example.com",
    "idNumber": "9001010000084"
  },
  "billing": {
    "street1": "1 Example Road",
    "street2": "LocalityA",
    "city": "Cape Town",
    "company": "CompanyA",
    "country": "ZA",
    "state": "Western Cape",
    "postcode": "1234"
  },
  "shipping": {
    "street1": "1 Example Road",
    "street2": "LocalityA",
    "city": "Cape Town",
    "company": "CompanyA",
    "postcode": "1234",
    "country": "ZA",
    "state": "Western Cape"
  },
  "createRegistration": true,
  "originator": "Webstore",
  "returnTo": "STORE",
  "cardTokens": [
    "8ac7a49f8e9f15d2018ea09b285f0eaa"
  ],
  "standingInstruction": {
    "expiry": "2026-12-31",
    "frequency": 30,
    "recurringType": "SUBSCRIPTION",
    "type": "RECURRING",
    "mode": "INITIAL",
    "industryPractice": "DELAYED_CHARGES",
    "numberOfInstallments": 12
  },
  "cardRemovalUrl": "https://example.com/users/1234567890/remove-card",
  "descriptor": "CompanyA",
  "merchant.name": "CompanyA",
  "enableAddNewCard": true,
  "cardSubmitButtonText": "Pay Now",
  "cardHeadingText": "Please enter your card details below to complete the payment.",
  "cardHeadingSavedCardsText": "Select a card to pay with"
}

Response

Checkout successfully validated.

messagestring required

Example response

{
  "message": "Valid request"
}