---
title: "Generate link"
method: POST
path: "/api/channels/{entityId}/payments"
tags: ["Generate or cancel"]
---

# Generate link

`POST /api/channels/{entityId}/payments`

## Request

- Base URL: `https://sandbox-l.ppay.io`
- URL: `https://sandbox-l.ppay.io/api/channels/{entityId}/payments`
- Auth: HTTP bearer

Generate a unique payment link for a transaction and optionally send this link to the recipient via email, SMS, WhatsApp, or a combination of the three.

For more information, see the [documentation](https://developer.peachpayments.com/docs/generate-link-1), and for sample calls, see the [public Postman collection](https://www.postman.com/peachpayments/peach-payments-public-workspace/request/xc1ix2g/payment-links-public?action=share&creator=20323380&ctx=documentation&active-environment=13324425-10da86ae-9bc2-4124-8f55-f7255fa3ff55).

## Request body

- GenerateLinkPayment: The request body for generating a payment link, including payment details, customer, options, and checkout configuration.
  - `payment` object, required: The payment object contains the payment details, files, and notes for the payment link.
    - `merchantInvoiceId` string, required: Invoice ID that can be used to link the payment to an invoice on the merchant's system.
    - `amount` number, required: Payment amount. An amount of 0 is only supported when the `paymentType` is `PA` and `tokeniseCard` is set to `true`.
    - `currency` 'ZAR' | 'KES' | 'USD', required: The currency code of the payment request amount (ISO 4217).
    - `files` string[]: Files to attach to the payment link.
    - `notes` string: A note to include with the payment link.
  - `customer` Customer, required: The customer object contains all the customer's information, including the given name, surname, contact details, and more.
    - `givenName` string, required: The first name or given name of the customer.
    - `surname` string: The last name or surname of the customer.
    - `email` string: The customer's email address. Required for communicating with customers regarding payment. Required if sendEmail is true.
    - `mobile` string: The customer's mobile number. Required for communicating with customers regarding payment. Format should be +27123456789. Required if sendSms is true.
    - `whatsapp` string: The customer's WhatsApp number. Required for communicating with customers regarding payment. Format should be +27123456789. Required if sendWhatsapp is true.
    - `billing` Address: Billing address details.
      - `street1` string: The door number, floor, building number, building name, and/or street name of the address.
      - `city` string: The town, district, or city of the address.
      - `state` string: The county, state, or region of the address.
      - `postalCode` string: The postal code or ZIP code of the address.
      - `country` string: The country of the address (ISO 3166-1 alpha 2).
  - `options` PaymentOptions, required: The options object contains all the communication preferences for the payment link.
    - `sendEmail` boolean: Indicates whether to send an email to the customer after creating the payment link.
    - `sendSms` boolean: Indicates whether to send an SMS to the customer after creating the payment link.
    - `sendWhatsapp` boolean: Indicates whether to send a WhatsApp message to the customer after creating the payment link.
    - `emailCc` string: List of comma-separated email addresses to CC.
    - `emailBcc` string: List of comma-separated email addresses to BCC.
    - `expiryTime` integer: Time in minutes until the link expires. By default, expiry time is set to 30 days, which is also the maximum expiry time.
    - `notificationUrl` string: Peach Payments sends a webhook to this URL for any changes to this payment, overriding your default webhook.
  - `checkout` CheckoutOptions, required: The checkout object contains the default payment method and whether to tokenise the card number.
    - `defaultPaymentMethod` string, nullable: The default payment method to show when Checkout loads.
    - `forceDefaultMethod` boolean, nullable: Force the default payment method to be the only payment method.
    - `tokeniseCard` boolean: Tokenise the card number to allow it to be stored. You must get permission from your customer before tokenising their cards.
    - `paymentType` 'DB' | 'PA', nullable: The payment type for the request. Does not accept `RG`, but you can tokenise a card by performing a DB or PA with `tokeniseCard`. PA is only supported when `forceDefaultMethod` is set to `true` and `defaultPaymentMethod` is `CARD`. A PA reserves funds but does not transfer funds or settle you. You must [capture](https://developer.peachpayments.com/docs/card-manage-payments#capture-a-preauthorisation) the PA for funds to move and for you to receive settlement. An uncaptured PA does not appear in settlement. Alternatively, you can [reverse](https://developer.peachpayments.com/docs/card-manage-payments#reverse-a-preauthorisation) the PA. Refund transactions through the Dashboard or as described in the [documentation](https://developer.peachpayments.com/docs/checkout-refund).

## Response `200`

Payment link successfully generated.

- GenerateLinkResponse: The response returned after successfully generating a payment link.
  - `url` string, required: Payment link.
  - `id` string, required: ID of payment link.

## Other responses

- `400`: The request body failed validation.
- `401`: Request lacks valid authentication.

---

[API](https://skmtc.dev/peachpayments/apis/payment-links.md) - [All operations](https://skmtc.dev/peachpayments/apis/payment-links/llms.txt) - [OpenAPI document](https://skmtc.dev/peachpayments/apis/payment-links/revisions/3a63dca6b297?raw)