Payment links

A payment link is a hosted start page for a payment. You create it once, share the URL by message, email, invoice or QR code, and every customer who opens it can pay through Vestrapay checkout. There is no integration to build on the customer-facing side, which makes links ideal for invoices, donations, event fees, one-off collections and merchants who do not have a website. Each time a customer pays through a link, Vestrapay initialises a fresh payment behind the scenes. Everything that applies to normal payments applies here: the same channels, fees, webhooks and verification.

Create a link

The easiest way is the dashboard: Payments → Payment links. You can also create links with the API. Link management uses a merchant session token, not the secret key, because it is a dashboard operation.

curl -X POST https://api.sandbox.vestrapay.app/v1/merchants/payment-links \
  -H "Authorization: Bearer MERCHANT_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Pay for Order 123",
    "description": "Premium subscription renewal",
    "amount": "250.00",
    "currency": "NGN",
    "channels": ["card", "bank_transfer"],
    "redirectUrl": "https://yourapp.com/thank-you",
    "feeBearer": "customer",
    "metadata": {
      "email": { "label": "Email", "type": "email", "required": true, "placeholder": "customer@example.com" },
      "orderId": { "label": "Order ID", "type": "text", "required": true }
    }
  }'

The response gives you the link and its URL:

{
  "status": "success",
  "data": {
    "id": "6b1c2a2e-1d4f-4c1e-9a07-3d5f0e9c1a11",
    "slug": "abc123hex",
    "status": "active",
    "title": "Pay for Order 123",
    "amount": "250.00",
    "feeBearer": "customer",
    "paymentLinkUrl": "https://…/abc123hex"
  }
}

Share data.paymentLinkUrl. The URL shown is abbreviated here. Use the exact value the response returns for the environment you called.

Link fields

Field	Required	Notes
`title`	Yes	The name shown to the customer.
`description`	No	Short detail shown under the title.
`amount`	No	A fixed amount in major units as a string. Omit it, or send an empty or zero value, for an open-amount link where the customer types the amount.
`currency`	No	Defaults to NGN.
`channels`	No	Restrict the link to some channels, for example `["card", "bank_transfer"]`.
`redirectUrl`	No	Where to send the customer after a successful payment.
`feeBearer`	No	`customer` or `merchant`. If omitted, your current payment-settings default is stored.
`distribution`	No	Map of service key to amount, applied to every payment made through the link. See Distribution.
`metadata`	No	The form the customer fills in. See below.

Metadata is a form, not an echo

On a payment link, metadata defines the prompts the customer completes before checkout starts. It is an object whose keys are your field names and whose values describe each prompt, with a label, a type such as email or text, whether it is required, and an optional placeholder. Vestrapay adds a stable id to each prompt, and the customer’s answers are keyed by that ID. This differs from the metadata object you send on initialise, which is opaque correlation data returned on verify. Do not confuse the two.

Fixed amounts, open amounts and splits

Fixed amount. The link always charges that amount.
Open amount. The customer enters the amount at checkout. If the link also has a distribution, the amount they enter must be at least the sum of the distribution amounts, otherwise the payment is rejected.
With splits. A distribution on the link is applied on every payment, so the split happens without any code on your side. If a service named in the distribution is later disabled, paying through the link is rejected until you fix the link or re-enable the service.

Manage links

All of these use the merchant session token.

Action	Request
List links	GET `/v1/merchants/payment-links` with optional page, pageSize and search query parameters.
Get one link	GET `/v1/merchants/payment-links/{id}`
Update a link	PATCH `/v1/merchants/payment-links/{id}`

Update accepts the same fields as create, plus status, which you can set to active or paused to switch a link off and on without deleting it. Links can also become expired or exhausted. Those states are managed by the system and cannot be set manually. Omit distribution or metadata from an update to leave the existing values as they are. A paused, expired or exhausted link returns HTTP 410 with payment_link.inactive to anyone who opens it.

What the customer does

Opens the link.
Completes any prompts you configured.
Vestrapay initialises checkout for that link.
The customer pays on hosted checkout.
You confirm with webhooks and verify.

If you want a fully custom page in front of a link, two public endpoints power it. Neither needs authentication.

Purpose	Request
Load the link for display	GET `/v1/merchants/payment-links/{slug}/display`
Submit answers and start checkout	POST `/v1/merchants/payment-links/{slug}/pay`

The display response contains the title, amount, currency, merchant name, environment and the prompts, each with its generated id. The pay request carries the answers keyed by those IDs, and an amount when the link is open-amount:

curl -X POST https://api.sandbox.vestrapay.app/v1/merchants/payment-links/abc123hex/pay \
  -H "Content-Type: application/json" \
  -d '{
    "answers": { "fld_email_123": "jane@example.com", "fld_order_456": "ORD-12345" },
    "amount": "1500.00"
  }'

The response is a normal payment session, so redirect to data.checkoutUrl:

{
  "status": "success",
  "data": {
    "reference": "PLINK_abc123def456_1A2B3C4D",
    "accessCode": "a1b2c3d4e5f6a1b2",
    "checkoutUrl": "https://checkout.sandbox.vestrapay.app/a1b2c3d4e5f6a1b2",
    "amount": "250.00",
    "currency": "NGN",
    "status": "pending"
  }
}

The amount in the pay body is required for open-amount links and ignored for fixed-amount links.

Reconciling link payments

A link payment is an ordinary transaction with its own reference. Your webhook receives the same events, and verify returns the same data, so your fulfilment code does not need a separate path. Use the answers you collected, such as an order ID prompt, to match the payment to your records, since there is no initialise call of your own to attach metadata to.

Failure modes

Situation	Response
Link slug unknown	404 `payment_link.not_found`
Link paused, expired or exhausted	410 `payment_link.inactive`
A required prompt left blank	400 `payment_link.missing_required_answer`
An answer key that is not a prompt on the link	400 `payment_link.unknown_answer_id`
Invalid or missing email prompt	400 `payment_link.invalid_email` or `payment_link.email_required`
Open-amount link with no amount	400 `payment_link.amount_required`
Distribution names a disabled or unknown service	400 `INVALID_SPLIT_AMOUNT`

See Errors for the full list.

Get started

Accept payments

Services & splits

Partners

Settlements

Create a link

Link fields

Metadata is a form, not an echo

Fixed amounts, open amounts and splits

Manage links

What the customer does

Reconciling link payments

Failure modes

​Create a link

​Link fields

​Metadata is a form, not an echo

​Fixed amounts, open amounts and splits

​Manage links

​What the customer does

​Reconciling link payments

​Failure modes

Create a link

Link fields

Metadata is a form, not an echo

Fixed amounts, open amounts and splits

Manage links

What the customer does

Reconciling link payments

Failure modes