Overview

The bulk payment links API enables you to create and send up to 1000 payment links with fewer API calls by uploading a CSV file with the payment links' details.

Experiment with the API using the Peach Payments Postman collection:

Flow

To learn more about the required and optional parameters, see the API reference section.

The bulk payment links flow works as follows:

1. The merchant initiates the bulk payment links generation by making a request to the /api/channels/{entityId}/payments/batches endpoint.
2. The Payment Links API responds with a file URL.
3. The merchant uploads the CSV to the file URL.
4. The Payment Links API sends a webhook to the merchant, informing them that the API has processed the bulk file.
5. If processing of the bulk file fails, the API sends a webhook to the merchant, informing them of the failure.
6. The Payment Links API sends webhook notifications to the merchant for each payment link created from the file.
7. The Payment Links API sends an email, SMS, WhatsApp, or combination of the three to each of the customers in the bulk file.

The merchant continues to receive webhooks for each individual payment link created from the bulk file as customers open and complete them.

Tutorial

This tutorial covers creating three payment links using a bulk upload.

📘

See the Bulk payment links CSV parameters section for details on the parameters that the CSV supports.

INVOICE_ID,AMOUNT,CURRENCY,CUSTOMER_GIVEN_NAME,CUSTOMER_SURNAME,SEND_EMAIL,CUSTOMER_EMAIL
INV-00002,10.00,ZAR,Grace,Nkosi,true,[email protected]
INV-00003,15.00,ZAR,Rex,Bartoletti,true,[email protected]
INV-00004,20.00,ZAR,Cali,Huel,true,[email protected]

1. Call the Generate batch link endpoint to start the upload process.

   cURL

   curl --location --request POST 'https://links.peachpayments.com/api/channels/{entityId}/payments/batches'  
   --header 'content-type: application/json'  
   --data-raw  
   '{  
       "filename": "january-2023.csv"
   }'
   

2. The response contains a URL that you must upload the CSV to.

   Response

   {
     "id": "4f9f5004-e8d5-4077-b1fa-1e603ea74ee8",
     "url": "https://files.example.com/upload?id=4f9f5004-e8d5-4077-b1fa-1e603ea74ee8"
   }
   

   📘

   Store the ID to query the status of the batch at a later stage.

3. Use PUT to upload the file to the provided URL.

   cURL

   curl --location --request PUT '<url from response>' \
   --header 'Content-Type: text/csv' \
   --data-binary '@january-2023.csv'
   

4. You receive a 200 response indicating file upload success.

5. Processing occurs asynchronously.