Payment Links

Create and share payment links with Atlas to collect payments from customers

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

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:

{
  "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.

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

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

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

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

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

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

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.