Generate a payment link

The generate link API allows you to create a unique payment link for a transaction which you can send to a recipient via email, SMS, WhatsApp, or a combination of the three.

Request

The generate link object consists of the following parameters.

Path parameters

ParameterDescriptionFormatCondition
entityIdThe entity for the request, in this case, the channelId.StringRequired

Payment object parameters

ParameterDescriptionFormatCondition
merchantInvoiceIdUnique, merchant-provided invoice number. The invoice number is used to link the payment to an invoice on the merchant's system. The length of the invoice number should be 16 characters or less.String
AN255
[\s\S]{5,25}
Required
amountThe payment amount for the payment link. The amount can only be positive and cannot be more than 999999.9.String N10.N2
[0-9]{1,10}(.[0-9]{2})?
Required
currencyThe three letter currency code (ISO 4217) of the payment request's amount, for example, ZAR for South African rand.String A3
[A-Z]{3}
Required
filesA list of files attached to the payment. It takes the name and URL of a file.Array of strings in UUID formatOptional
notesA note to be attached to the payment. The length of the note should be 140 characters or less.StringOptional

Customer object parameters

ParameterDescriptionFormatCondition
customer.givenNameThe first name or given name of the customer.String
AN
[\s\S]
Required
customer.surnameThe last name or surname of the customer.String
AN
[\s\S]
Required
customer.emailThe email address of the customer. The email is used to communicate with customers regarding payment.String
AN128
[\s\S]{6,128}
Optional
customer.mobileThe customer's mobile number. Required for communicating with customers regarding payment. Format should be +27123456789. Required if sendSms is true.AN25
[+0-9][0-9 \.()/-]{5,25}
Optional

As part of 3-D Secure 2.0, you can also send the customer billing information in the payment links API. Below are the parameters for the billing object.

ParameterDescriptionFormatCondition
billing.street1The door number, floor, building number, building name, and street name of the billing address. Mandatory for 3-D Secure v2AN100
[\s\S]{1,100}
Optional
billing.cityThe town, district, or city of the billing address. Mandatory for 3-D Secure v2.AN48
[\s\S]{1,48}
Optional
billing.postcodeThe postal code or zip code of the billing address. Mandatory for 3-D Secure v2.AN16
[\s\S]{1,16}
Optional
billing.countryThe country of the billing address (ISO 3166-1). Mandatory for 3-D Secure v2.A2
[A-Z]{2}
Optional

Options object parameters

ParameterDescriptionFormatCondition
sendEmailSpecifies whether to send an email to a customer after creating a payment.BooleanRequired
sendSmsSpecifies whether to send an SMS to a customer after creating a payment.BooleanRequired
sendWhatsappSpecifies whether to send a WhatsApp message to a customer after creating a payment.BooleanRequired
emailCcList of email addresses separated by commas to receive a copy of the email.String
AN128
[\s\S]{6,128}
Optional
emailBccList of email addresses separated by commas to receive a blind copy of the email.String
AN128
[\s\S]{6,128}
Optional
expiryTimeIndicates the time, in seconds, when the payment link expires.IntegerOptional
notificationUrlThe URL to send webhook updates.String
AN128
[\s\S]{6,128}
Optional

Checkout object parameters

ParameterDescriptionFormatCondition
defaultPaymentMethodThe preferred payment method that will be active in the Checkout page at the point of redirecting.Alphanumeric extendedOptional
tokeniseCardAn ID or token is used to replace sensitive customer data that has no connection to the account owner.
A merchant indicates whether they would like to enable the tokenization of their customers' cards via the Checkout process (One Click), or they may have a subscription service where they instruct Peach Payments to run a batch of cards on a specific date.
BooleanOptional

Example requests and responses

For sample requests and responses, see the interactive API playground and the Postman workspace.