---
title: "Retrieve or export all payment links"
method: GET
path: "/api/payments"
tags: ["Helpers"]
---

# Retrieve or export all payment links

`GET /api/payments`

## Request

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

Retrieve a paginated list or export a CSV of all payment links. To export to CSV, change the request header's `Accept` value to `text/csv`.

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

## Query parameters

- `merchant` string
- `offset` integer
- `perPage` integer
- `filters[startDate]` string, date-time
- `filters[endDate]` string, date-time
- `filters[status]` 'initiated' | 'processing' | 'expired' | 'cancelled' | 'completed'
- `filters[amountValue]` number
- `filters[amountOperator]` 'lt' | 'lte' | 'gt' | 'gte' | 'eq'
- `filters[sendingOptions]` 'sendEmail' | 'sendSms' | 'sendWhatsapp' | 'emailCc' | 'emailBcc'

## Response `200`

Payment links successfully retrieved.

- object
  - `payments` QueryStatusResponse[]
    - `id` string: Payment ID.
    - `payment` object
      - `linkId` string: Payment link ID.
      - `linkUrl` string: Payment link URL.
      - `amount` number: Payment amount.
      - `status` 'initiated' | 'processing' | 'expired' | 'cancelled' | 'completed': Payment link status.
      - `currency` 'ZAR' | 'KES' | 'USD': Currency code for the payment.
      - `merchantInvoiceId` string: Payment order number provided by merchant.
      - `entityId` string: Merchant channel ID that the payment link was created in.
      - `notes` string: A note to include with the payment link.
      - `expiryTime` string: Timestamp when the payment link expires.
      - `batchId` string: Batch ID for the payment link.
    - `source` 'API' | 'Xero' | 'UI': Source of the payment link.
    - `createdAt` string: Timestamp when the payment link was created.
    - `updatedAt` string: Timestamp when the payment link was last modified.
    - `customer` Customer: 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` PaymentResponseOptions: The response representation of 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, nullable: List of comma-separated email addresses to CC.
      - `emailBcc` string, nullable: List of comma-separated email addresses to BCC.
      - `notificationUrl` string: Peach Payments sends a webhook to this URL for any changes to this payment, overriding your default webhook.
    - `checkout` CheckoutState: 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).
      - `registrationId` string: Registration ID added if tokeniseCard is true on card payment.
      - `checkoutId` string: Checkout ID of payment.
      - `transactionUniqueId` string: Unique transaction ID of payment.
      - `resultCode` string: Result code returned for payment.
      - `paymentBrand` string: Payment brand used for payment.
    - `termsOfService` object
      - `id` string: The id of the terms of service that was agreed to.
      - `accepted` boolean: Whether the user agreed to the terms of service.
  - `meta` object
    - `perPage` number: The amount of items to retrieve.
    - `offset` number: The offset from which to read data.
    - `nextOffset` number: The offset from which to read data on a subsequent request.
    - `total` number: The total number of payment links returned by the filter criteria.

## Other responses

- `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)