TagPayTagPay

API Reference

Payment Links

A Payment Link is a shareable URL that opens a hosted checkout. Use it for invoices, donation pages, social-media stores, and recurring billing. Every link has a `linkType`: `fixed` (you set the amount), `open` (the customer chooses), or `subscription` (enrols the payer in a plan). The create response includes a ready-to-share `url`.

Create a payment link

POST/v1/payment-links

Create a link and share the returned url with customers — via email, WhatsApp, a button on your site, anywhere. name and linkType are always required; the other required fields depend on linkType (see amount and plan).

Body parameters

namestringrequired

Internal label shown in the dashboard (1–200 chars). Not the customer-facing title.

linkTypestringrequired

fixed — amount required at creation. open — omit amount; the customer enters it at pay time. subscription — plan required; paying enrols the customer in recurring billing.

Allowed: 'fixed''open''subscription'

amountintegeroptional

Amount in kobo. **Required** when linkType is fixed. Must be omitted for open. Ignored for subscription (the plan amount is charged).

planstringoptional

Plan code (PLN_…). **Required** when linkType is subscription. Must be an active plan you own.

descriptionstringoptional

Optional description (up to 500 chars), shown on the hosted checkout page.

redirectUrlstringoptional

Where to send the customer after a successful payment. Must be a valid URL.

singleUsebooleanoptional

When true, the link auto-deactivates after the first successful payment. Defaults to false. Ignored for subscription.

activebooleanoptional

Whether the link accepts payments immediately. Defaults to true.

targetAmountintegeroptional

Fundraising goal in kobo. **Only valid for open links** — the link auto-deactivates once cumulative payments reach it. Rejected for fixed/subscription.

trialPeriodDaysintegeroptional

Free-trial length in days. **Only valid for subscription links** (max 365). The customer pays a small one-off card-verification fee instead of the first cycle; the first plan charge fires this many days later.

metadataobjectoptional

Arbitrary key/value pairs echoed on every charge created via this link.

Response

201
linkCodestring

TagPay link code (`PLK_…`). Use this in every payment-link API call (retrieve, update).

urlstring

Shareable customer-facing URL. Hand this out directly — it opens the hosted checkout.

namestring

Internal label.

descriptionstring | null

Optional description shown on the hosted page.

amountinteger | null

Fixed amount in kobo, or `null` for `open` links.

currencystring

Always `NGN`.

linkTypestring

One of `fixed`, `open`, `subscription`.

planCodestring | null

Plan code for `subscription` links, otherwise `null`.

activeboolean

Whether the link currently accepts payments.

singleUseboolean

Whether the link auto-deactivates after the first successful payment.

paidAtstring | null

ISO-8601 timestamp of the payment that exhausted a single-use link, else `null`.

totalCollectedinteger

Cumulative successful payments through this link, in kobo.

paymentCountinteger

Number of successful payments through this link.

targetAmountinteger | null

Fundraising goal in kobo for `open` links, else `null`.

trialPeriodDaysinteger | null

Trial length in days for `subscription` links, else `null`.

redirectUrlstring | null

Post-payment redirect URL, or `null`.

metadataobject | null

Arbitrary key/value pairs echoed on every charge created via this link.

createdAtstring

ISO-8601 creation timestamp.

updatedAtstring

ISO-8601 last-update timestamp.

Errors

VALIDATION_ERROR400A field is missing, has the wrong name, or violates a per-type rule (e.g. `amount` is required for fixed-type links).
NOT_FOUND404The supplied `plan` code does not exist or is not owned by you.
UNAUTHORIZED401Secret key missing or invalid.

List payment links

GET/v1/payment-links

Returns links in reverse-chronological order. Deactivated links are included by default — pass active=true to hide them. Results are scoped to the mode (test/live) of the secret key used.

Query parameters

activebooleanoptional

If true, only return links currently accepting payments.

pageintegeroptional

Page number, 1-indexed. Defaults to 1.

perPageintegeroptional

Results per page, max 100. Defaults to 20.

Response

200
dataarray<PaymentLink>

Array of payment link objects (same shape as create).

metaobject

Pagination metadata.

totalinteger

Total matching records.

pageinteger

Current page.

perPageinteger

Per-page count.

pageCountinteger

Total number of pages.

Retrieve a payment link

GET/v1/payment-links/:code

Returns the full payment link resource.

Path parameters

codestringrequired

The link code (PLK_…) returned at creation.

Response

200
linkCodestring

TagPay link code (`PLK_…`). Use this in every payment-link API call (retrieve, update).

urlstring

Shareable customer-facing URL. Hand this out directly — it opens the hosted checkout.

namestring

Internal label.

descriptionstring | null

Optional description shown on the hosted page.

amountinteger | null

Fixed amount in kobo, or `null` for `open` links.

currencystring

Always `NGN`.

linkTypestring

One of `fixed`, `open`, `subscription`.

planCodestring | null

Plan code for `subscription` links, otherwise `null`.

activeboolean

Whether the link currently accepts payments.

singleUseboolean

Whether the link auto-deactivates after the first successful payment.

paidAtstring | null

ISO-8601 timestamp of the payment that exhausted a single-use link, else `null`.

totalCollectedinteger

Cumulative successful payments through this link, in kobo.

paymentCountinteger

Number of successful payments through this link.

targetAmountinteger | null

Fundraising goal in kobo for `open` links, else `null`.

trialPeriodDaysinteger | null

Trial length in days for `subscription` links, else `null`.

redirectUrlstring | null

Post-payment redirect URL, or `null`.

metadataobject | null

Arbitrary key/value pairs echoed on every charge created via this link.

createdAtstring

ISO-8601 creation timestamp.

updatedAtstring

ISO-8601 last-update timestamp.

Errors

NOT_FOUND404No payment link with that code in this mode.

Update a payment link

PUT/v1/payment-links/:code

Send only the fields you want to change. linkType, amount, plan, and singleUse are immutable — a link shared externally must not change its billing terms under customers who bookmarked it. To deactivate a link, send `{ "active": false }` (there is no separate deactivate endpoint); the URL keeps resolving but shows a "no longer accepting payments" page.

Path parameters

codestringrequired

The link code (PLK_…).

Body parameters

namestringoptional

New internal label (1–200 chars).

descriptionstringoptional

New description (up to 500 chars).

redirectUrlstringoptional

New post-payment redirect URL.

activebooleanoptional

Set false to deactivate the link, true to reactivate.

targetAmountinteger | nulloptional

Update the fundraising goal (kobo) on an open link. Pass null to clear it. Rejected with 400 on fixed/subscription links.

trialPeriodDaysinteger | nulloptional

Update the trial length (days) on a subscription link. Pass null to remove the trial. Existing subscriptions are unaffected; only new signups see the change. Rejected with 400 on fixed/open links.

metadataobjectoptional

Replaces the stored metadata entirely.

Response

200
linkCodestring

TagPay link code (`PLK_…`). Use this in every payment-link API call (retrieve, update).

urlstring

Shareable customer-facing URL. Hand this out directly — it opens the hosted checkout.

namestring

Internal label.

descriptionstring | null

Optional description shown on the hosted page.

amountinteger | null

Fixed amount in kobo, or `null` for `open` links.

currencystring

Always `NGN`.

linkTypestring

One of `fixed`, `open`, `subscription`.

planCodestring | null

Plan code for `subscription` links, otherwise `null`.

activeboolean

Whether the link currently accepts payments.

singleUseboolean

Whether the link auto-deactivates after the first successful payment.

paidAtstring | null

ISO-8601 timestamp of the payment that exhausted a single-use link, else `null`.

totalCollectedinteger

Cumulative successful payments through this link, in kobo.

paymentCountinteger

Number of successful payments through this link.

targetAmountinteger | null

Fundraising goal in kobo for `open` links, else `null`.

trialPeriodDaysinteger | null

Trial length in days for `subscription` links, else `null`.

redirectUrlstring | null

Post-payment redirect URL, or `null`.

metadataobject | null

Arbitrary key/value pairs echoed on every charge created via this link.

createdAtstring

ISO-8601 creation timestamp.

updatedAtstring

ISO-8601 last-update timestamp.

Errors

NOT_FOUND404No payment link with that code in this mode.
VALIDATION_ERROR400An immutable field was sent, or a per-type rule was violated (e.g. `targetAmount` on a non-open link).