Skip to main content

​
Overview

The Payment Link Service lets your organization generate shareable, time-limited payment links that can be emailed to customers. Each link is tied to an organization and optionally to a specific transaction, amount, and currency. Links expire automatically and can be revoked at any time. The service supports two access patterns:
  • Direct links — generated by your backend and shared with customers immediately.
  • OTP-gated links — the customer verifies their email with a one-time password before accessing the link, adding an extra layer of identity confirmation.
Use POST /payment-links to generate a link. You must provide the recipient’s email and your org_id. All other fields are optional:
FieldTypeDescription
emailstring (email)Recipient’s email address
org_idstringYour organization ID
transaction_idstringOptional — ties the link to an existing transaction
payment_amountfloatOptional — pre-fills the amount on the checkout page
currencystringOptional — e.g. NGN, USD
scheduled_atstring (ISO 8601)Optional — date/time the link is scheduled to be sent
otpstringOptional — pre-verified OTP code
This endpoint requires the internal-admin or org-admin role.

​
OTP Verification Flow

For OTP-gated links, the flow is:
  1. Send OTP — call POST /payment-links/otp with the customer’s email. The service sends a one-time code.
  2. Verify OTP — call PUT /payment-links/otp with the email and otp. On success, you receive a short-lived JWT (type: "payment_link", 24 h expiry).
  3. Access the link — include the JWT as Authorization: Bearer <token> when accessing the protected payment link.
Neither OTP endpoint requires prior authentication — they are designed for unauthenticated customer-facing flows.
Two public endpoints exist for checking a link’s state:
  • GET /payment-links/{link_id} — retrieves the full link object including its status, expiry, and associated metadata.
  • POST /payment-links/verify — lightweight check; returns whether the link is valid (not expired or revoked) along with the link object.
Both endpoints require no authentication and are safe to call from customer-facing frontends.
DELETE /payment-links/{link_id} revokes a payment link. You can also pass an email in the request body to revoke all active links for that recipient at once. At least one of the path link_id or a body email must be provided. This endpoint requires the internal-admin or org-admin role.
GET /orgs/{org_id}/payment-links returns all payment links created under an organization, along with a total count. This is useful for dashboards and audit views. This endpoint requires the internal-admin or org-admin role.

​
Scheduled Payments

The service includes a scheduled-trigger endpoint (POST /payment-links/scheduled) used by an internal job to dispatch reminder emails. The job queries all links whose scheduled_at falls within a configurable window:
FieldTypeDescription
scheduled_atstring (ISO 8601)Target date to query due links
periodintegerLook-ahead window in hours (default: 24)
This endpoint does not require authentication and is intended for internal scheduler use only.