Qodex.ai

Payment Links [Public]

Number of APIs: 12

The Payment Links collection allows you to generate and cancel payment links, query payment statuses, and retrieve all payment links.

API endpoints

The following are the API endpoints for the live and sandbox servers:

  • Live: https://links.peachpayments.com

  • Sandbox: https://sandbox-l.ppay.io

Prerequisites

Retrieve the following credentials from the Payment Links section of the Peach Payments Dashboard:

  • clientId: It resembles c3e5374856a3334f2dfe1451d36f3z.

  • clientSecret: It resembles aonSYINF2PxLB0EUBeXPIR+xYRTNhYb17i762K4SUb5gBINz8GGwHvcYfZg29qtAAIHiniL/n7LrVGqdmNkrdz==.

  • merchantId: It resembles 9f6ea39b121d11e89d9774d4352a31dz.

  • entityId: It resembles 8ac7a4ca694cec2601694cf5f936002z.

To receive notifications whenever a payment link's status changes, you'll also need a webhook URL to insert into notificationUrl.

Fork the environment and collection

To fork the environment from the [Peach Payments workspace]

  1. Navigate to Environments, click View more actions next to the Payment-Links-Public environment, and click Create a fork.
  2. Enter a fork label, select the workspace to fork to, and click Fork Environment.

To fork the collection from the [Peach Payments workspace]

  1. Navigate to Collections, click View more actions next to the Payment Links [Public] collection, and click Create a fork.
  2. Enter a fork label, select the workspace to fork to, ensure that Watch original collection is selected, and click Fork Collection.

Configure the environment

To get started:

  1. Enter the credentials from the Prerequisites section above into the CURRENT VALUE column of the forked environment.
  2. Enter your webhook URL into the CURRENT VALUE column for the notificationUrl parameter.
  3. Select the Payment-Links-Public option from the environment drop-down list in the upper right of the screen.
  4. Click Save in the upper right of the screen.

Authentication

Before you can begin sending requests, you need to authenticate:

Payment%20Links%20authentication.
  1. In your forked collection, navigate to Payment Links [Public] > auth > POST Merchant Access and select the Payment-Links-Public option from the environment drop-down list in the upper right of the screen.
  2. Click Send.

Use the Payment Links API

Upload a file

To upload a file that can be attached to a payment link:

  1. In your forked collection, navigate to Payment Links [Public] > Links > api > attachments > POST Upload a file and select the Body tab of the request.
  2. Click Select Files in the VALUE column, select a file, and click Open. Note: Only PDFs that are less than 5 MB in size are supported.
  3. Select the Payment-Links-Public option from the environment drop-down list in the upper right of the screen.
  4. Click Send.

The file is uploaded and a fileId is returned in the response. Take note of this fileId as you will require it to attach this file to a payment link.

Note: The fileId can only be used for a single payment link.

Generate a payment link

To generate a payment link:

  1. In your forked collection, navigate to Payment Links [Public] > Links > api > channels/{entity Id} > POST Generate link and select the Body tab of the request.
  2. Enter the fileId that was returned in the file upload response into the files field, ensuring that you enclose the value in quotation marks. It should look similar to "files": ["ca6cd55b-4be6-451d-bd72-fe5b7ec1f75z"],.
  3. Select the Payment-Links-Public option from the environment drop-down list in the upper right of the screen.
  4. Click Send.

The payment link appears in the url parameter of the response body. Open the link in your browser to see the payment link details, the attachment, and to make payment.

Download a file

To download a file that was attached to a payment link:

  1. In your forked collection, navigate to Payment Links [Public] > Links > api > payments > {payment Id} > files > GET Download a file and select the Payment-Links-Public option from the environment drop-down list in the upper right of the screen.
  2. Click Send.

The file's location is returned in the response body; hold Ctrl or Command and click the URL to download the file.

Query a payment link's status

To query a payment link's status:

  1. In your forked collection, navigate to Payment Links [Public] > Links > api > payments > {payment Id} > GET Query payment status and select the Payment-Links-Public option from the environment drop-down list in the upper right of the screen.
  2. Click Send.

The response body lists the payment link's status, including the audit object.

Retrieve all payment links

To retrieve all payment links:

  1. In your forked collection, navigate to Payment Links [Public] > Links > api > payments > GET Retrieve all payment links and select the Payment-Links-Public option from the environment drop-down list in the upper right of the screen.
  2. Click Send.

The response body lists all your payment links without the audit objects.

Note: To return all payment links successfully created using a batch CSV, include the batchId in the request's search parameter. Entering a linkId or batchId into the search parameter results in all other filters being ignored. Entering a customer name or invoice ID results in other filters being included.

Export all payment links

To export all the payment links for a particular merchant to a CSV file:

  1. In your forked collection, navigate to Payment Links [Public] > Links > api > payments > GET Export all merchant payment links and select the Payment-Links-Public option from the environment drop-down list in the upper right of the screen.
  2. Click Send.

The response body includes the CSV location; hold Ctrl or Command and click the URL to download the file.

Note: Entering a linkId or batchId into the search parameter results in all other filters being ignored. Entering a customer name or invoice ID results in other filters being included.

Cancel a payment link

To cancel the payment link that you just created:

  1. In your forked collection, navigate to Payment Links [Public] > Links > api > payments > {payment Id} > DEL Cancel link and select the Payment-Links-Public option from the environment drop-down list in the upper right of the screen.
  2. Click Send.

The payment link is cancelled.

Generate a batch payment links URL

To generate a batch payment links URL to which you can upload a CSV:

  1. In your forked collection, navigate to Payment Links [Public] > Batch > api > channels/{entity Id} > POST Create batch.
  2. Select the Payment-Links-Public option from the environment drop-down list in the upper right of the screen.
  3. Click Send.

The batch payment links URL appears in the url parameter of the response body.

Submit a batch payment links CSV

Before completing these instructions, ensure that you have a batch payment links CSV.

If necessary, copy the contents of the sample CSV from the bulk payment links tutorial. Introduce one error into the CSV by changing the currency for one of the rows to a non-existent currency code, such as AAA. This is to show how the API handles errors in a later section.

Submit a batch payment links CSV as follows:

  1. In your forked collection, navigate to Payment Links [Public] > Batch > api > channels/{entity Id} > PUT Submit batch and select the Body tab.
  2. Click Select File.
  3. Select the CSV file and click Open.
  4. Select the Payment-Links-Public option from the environment drop-down list in the upper right of the screen.
  5. Click Send.

You receive a 200 response.

Retrieve all batches

Retrieve all batches as follows:

  1. In your forked collection, navigate to Payment Links [Public] > Batch > api > channels/{entity Id} > GET Retrieve all batches.
  2. Select the Payment-Links-Public option from the environment drop-down list in the upper right of the screen.
  3. Click Send.

The batches, together with metadata, are returned in the response.

Query a batch status

Query a specific batch's status as follows:

  1. In your forked collection, navigate to Payment Links [Public] > Batch > api > batches/{batch Id} > GET Query batch status.
  2. Select the Payment-Links-Public option from the environment drop-down list in the upper right of the screen.
  3. Click Send.

The status of the latest batch that was submitted is returned in the response.

Retrieve batch error files

Retrieve the batch error and error details files as follows:

  1. In your forked collection, navigate to Payment Links [Public] > Batch > api > batches/{batch Id} > files > GET Retrieve batch error files.
  2. Select the Payment-Links-Public option from the environment drop-down list in the upper right of the screen.
  3. Click Send.

If there were any processing errors for the batch, the response includes two URLs, one for the error file and one for the error details file. Hold Ctrl and click the URLs to downlaod the files.

Otherwise, No processing errors on this batch is returned in the response.

  1. auth - Merchant Access POST {{authUrl}}/api/oauth/token

  2. Links-api-channels/{entity Id} - Generate link POST {{baseUrl}}/api/channels/:entityId/payments

  3. Links-api-payments-{payment Id}-files - Download a file GET {{baseUrl}}/api/payments/:paymentId/files/:fileId

  4. Links-api-payments-{payment Id} - Cancel link DELETE {{baseUrl}}/api/payments/:paymentId

  5. Links-api-payments-{payment Id} - Query payment status GET {{baseUrl}}/api/payments/:paymentId

  6. Links-api-payments - Export all merchant payment links GET {{baseUrl}}/api/payments?perPage=2&offset=0&filters[startDate]=2022-01-25T10:00:00Z&filters[endDate]=2022-01-30T10:00:00Z&filters[status][0]=expired&filters[amountOperator]=gt&filters[amountValue]=0.00&merchant={{merchantId}}

  7. Links-api - Upload a file POST {{baseUrl}}/api/attachments

  8. Batch-api-channels/{entity Id} - Create batch POST {{baseUrl}}/api/channels/:entityId/payments/batches

  9. Batch-api-channels/{entity Id} - Submit batch PUT {{batchUrl}}

  10. Batch-api-channels/{entity Id} - Retrieve all batches GET {{baseUrl}}/api/channels/:entityId/payments/batches?filters[startDate]=2023-01-20T10:00:00Z&filters[endDate]=2023-01-25T14:00:00Z