authentication.entityIdstring required
The entity for the request. By default, this is the channel ID.
signaturestring required
Token to verify the integrity of the payment, ensuring that only the merchant sending the request is accepted.
merchantTransactionIdstring 8-16 required
Merchant-provided reference number unique for your transactions.
rateLimitIdstring
Merchant-defined identifier used for rate limiting on checkout load. You can set this to an order ID, cart ID, customer ID, or a composite identifier.
amountstring ^[0-9]{1,8}(\\.[0-9]{2})?$ 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.
paymentType'DB' | 'PA' 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.
currency'ZAR' | 'USD' | 'KES' | 'MUR' | 'GBP' | 'EUR' required
The currency code of the payment request amount.
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. Must be a valid URL that can be accessed through a browser.
defaultPaymentMethod'CARD' | 'MASTERPASS' | 'MOBICRED' | 'MPESA' | '1FORYOU' | 'APLUS' | 'PAYPAL' | 'ZEROPAY' | 'PAYFLEX' | 'BLINKBYEMTEL' | 'CAPITECPAY' | 'PAYBYBANK' | 'APPLE PAY' | 'GOOGLEPAY' | 'SAMSUNGPAY' | 'MCBJUICE' | 'RCS' | 'FLOAT' | 'HAPPYPAY' | 'MAUCAS' | 'MONEYBADGER' | 'PAYSHAP' | 'NEDBANKDIRECTEFT' | 'ABSAEFT'
Checkout opens in this payment method. Customers can choose to go back and select a different payment method.
forceDefaultMethod'true' | 'false'
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.
customParameters[name]string name: [a-zA-Z0-9\._]{3,64} value: [\s\S]{0,2048}
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.merchantCustomerIdstring [\s\S]{0,48}
An identifier for this customer. Typically this is the ID that identifies the shopper in the shop's system.
customer.givenNamestring [\s\S]{0,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.
customer.surnamestring [\s\S]{0,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.
customer.mobilestring [+0-9][0-9 \.()/-]{5,24}
The customer's mobile number.
customer.emailstring [\s\S]{6,128}
The customer's email address.
customer.status'NEW' | 'EXISTING'
The customer's status. Accepts NEW or EXISTING.
customer.birthDatestring yyyy-MM-dd
The customer's birth date in the yyyy-MM-dd format.
customer.ipstring [\s\S]{1,255}
The customer's IP address.
customer.phonestring [+0-9][0-9 \.()/-]{5,24}
The customer's phone number.
customer.idNumberstring [\s\S]{13,13}
The customer's ID number, required for high-risk merchants supporting Capitec Pay.
billing.street1string [\s\S]{1,100}
The door number, floor, building number, building name, and/or street name of the billing address.
billing.street2string [\s\S]{1,100}
The adjoining road or locality, if required, of the billing address.
billing.citystring [\s\S]{1,80}
The town, district, or city of the billing address.
billing.companystring [\s\S]{1,64}
The company of the billing address.
billing.countrystring ISO 3166-1 alpha-2
The country of the billing address (ISO 3166-1 alpha-2).
billing.statestring [\s\S]{1,50}
The county, state, or region of the billing address.
billing.postcodestring [\s\S]{1,30}
The postal code or ZIP code of the billing address.
shipping.street1string [\s\S]{1,100}
The door number, floor, building number, building name, and/or street name of the shipping address.
shipping.street2string [\s\S]{1,100}
The adjoining road or locality, if required, of the shipping address.
shipping.citystring [\s\S]{1,80}
The town, district, or city of the shipping address.
shipping.companystring [\s\S]{1,64}
The company of the shipping address.
shipping.postcodestring [\s\S]{1,30}
The postal code or ZIP code of the shipping address.
shipping.countrystring ISO 3166-1 alpha-2
The country of the shipping address (ISO 3166-1 alpha-2).
shipping.statestring [\s\S]{1,50}
The county, state, or region of the shipping address.
cart.taxstring ^[0-9]{1,8}(\\.[0-9]{2})?$
The tax percentage applied to the price of the item in the shopping cart.
cart.shippingAmountstring ^[0-9]{1,8}(\\.[0-9]{2})?$
The total amount of the cart item including quantity.
cart.discountstring ^[0-9]{1,8}(\\.[0-9]{2})?$
Discount amount applied on order amount.
createRegistration'true' | 'false'
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.
cardTokensstring
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.
allowStoringDetails'true' | 'false'
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.expirystring 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.
standingInstruction.frequencystring
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.
standingInstruction.recurringType'SUBSCRIPTION' | 'STANDING_ORDER'
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.
standingInstruction.type'UNSCHEDULED' | 'INSTALLMENT' | 'RECURRING'
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.
standingInstruction.mode'INITIAL' | 'REPEATED'
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).
standingInstruction.industryPractice'INCREMENTAL_AUTH' | 'RESUBMISSION' | 'REAUTHORIZATION' | 'DELAYED_CHARGES' | 'NO_SHOW'
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.
standingInstruction.numberOfInstallmentsstring
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.
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.
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.