Payment Links

Payment links let you collect payments from your customers on a prebuilt checkout page. Payment links are more flexible than the dedicated Atlas Checkout .

Checkouts are designed for one-time payments with hardcoded details and expiries. Unlike a one-time checkout, with a single payment link, you can collect payments of varying amounts, from different customers with no fixed expiry.

Create a link, share it with your customers, and Atlas handles the payment flow. Each link has a unique URL your customers can open to complete a payment.

Creating a payment link

To create a payment link, make a POST request to the Create Payment Link endpoint with the required fields below:

link_name: A label for the payment link, visible on the payment page.
narration: A description of what the payment is for.
fee_bearer: Who bears the transaction fee. It can either be MERCHANT (You) or CUSTOMER. The fee bearer setting at this level overrides your default setting on your dashboard for the payment link.
source_reference: A unique string you provide to identify the link on your system.

Optional fields:

amount: A fixed payment amount. If you omit this field, the customers can pay any amount to the payment link (minimum of NGN 100 required).
customer_emails: An array of email addresses Atlas will send the link to after creation.
redirect_link: A URL Atlas redirects the customer to after a successful payment. If you leave this blank, the customer will be stuck on the success page after their payment is confirmed.
start_date / end_date: Dates to control when the link is active.

Note

If you set an amount, any payment to the payment link that does not match it exactly will be refunded to the sender.

curl -X POST "https://atlas.tryduplo.com/api/v1/payment-link" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "link_name": "March Contributions",
    "narration": "Payment for Monthly Fire Department Contributions",
    "fee_bearer": "MERCHANT",
    "amount": 50000,
    "source_reference": "PLK_SRC_001",
    "customer_emails": ["john.doe@example.com"]
  }'

On a successful request, you'll receive the payment link details including the shareable linkUrl:

JSON

{
  "requestId": "5d11fab4-0846-4979-b63d-98c2df8b4d18",
  "requestTimestamp": "2026-03-30 11:58:11.195",
  "message": "Payment link created successfully.",
  "statusCode": 201,
  "data": {
    "linkName": "March Invoice",
    "linkUrl": "https://atlas-app.tryduplo.com/pay/PLK_ABC123XYZ",
    "amount": 50000,
    "currency": "NGN",
    "status": "active",
    "reference": "PLK_ABC123XYZ",
    "sourceReference": "PLK_SRC_001"
  }
}

Share the linkUrl with your customers. You can embed it in an email, invoice, or website.

Important

When a customer tries to make a payment using a payment link, Atlas initiates a checkout for them and all checkout rules will apply to that payment session. The session will follow the lifecycle of a checkout and you will receive a webhook depending on the final status of the checkout.

Fetching payment links

Both the reference (Atlas-generated) and source_reference (your own identifier) can be used to look up a payment link. Use the Get Payment Link endpoint when you have the Atlas-generated reference - for example, if you stored it after creation or received it in a webhook:

curl -X GET "https://atlas.tryduplo.com/api/v1/payment-link/find-by-reference/PLK_ABC123XYZ" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

If you didn't store the Atlas reference but set a source_reference at creation time, use the Get Payment Link by Source Reference endpoint instead:

curl -X GET "https://atlas.tryduplo.com/api/v1/payment-link/find-by-source-reference/PLK_SRC_001" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Listing payment links

You can retrieve all the payment links associated with your business by making a GET request to the List Payment Links endpoint. The endpoint supports the following optional query parameters:

page: Page number for pagination (default: 1).
limit: Number of results per page (default: 15).
status: Filter by link status, e.g. active.
search: Search by link name or reference.

curl -X GET "https://atlas.tryduplo.com/api/v1/payment-link" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Fetching payment link transactions

Each payment made through a link is recorded as a separate transaction. Use the Get Payment Link Transactions endpoint to reconcile payments against a specific link. Both transaction endpoints support the following optional query parameters:

page: Page number for pagination (default: 1).
limit: Number of results per page (default: 15).
status: Filter by transaction status, e.g. successful.
search: Search by transaction reference.

curl -X GET "https://atlas.tryduplo.com/api/v1/payment-link/find-by-reference/PLK_ABC123XYZ/transactions" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

If you only have the source_reference on hand, use the Get Payment Link Transactions by Source Reference endpoint:

curl -X GET "https://atlas.tryduplo.com/api/v1/payment-link/source-reference/PLK_SRC_001/transactions" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Activating and deactivating a payment link

Deactivating a link is useful when a campaign ends, a promotion expires, or you want to temporarily stop accepting payments without deleting the link. Use the Toggle Payment Link Status endpoint - set activate to false to deactivate or true to re-enable it:

curl -X POST "https://atlas.tryduplo.com/api/v1/payment-link/toggle-status" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "link_id": "019d1019-f9b3-70d2-be9f-cef3ec5b4566",
    "activate": false
  }'

Set activate to true to re-enable a deactivated link. Customers who visit a deactivated link's URL will not be able to complete a payment.

Creating a payment link

Fetching payment links

Listing payment links

Fetching payment link transactions

Activating and deactivating a payment link

Related guides

On this page