A payment link is a URL to a checkout page that Payve hosts. The payer opens it, chooses how to pay, and pays. The money lands in your wallet and you get a payin.successful event. The checkout URL is built from the link’s slug:
POST /v1/payment-links · needs the payins:write scope
string
required
Shown to the payer. Also used to build the slug.
string
required
The currency to collect.
integer
A fixed amount in minor units. Leave it out to let the payer enter the amount.
string
More detail for the payer.
string
When the link stops working. ISO 8601.
string
Where the checkout sends the payer afterwards.
string[]
Limit how the payer can pay: bank_transfer, card, mobile_money.
integer
default:"0"
How far above amount a payment may be and still count as paid in full. Minor units.
integer
default:"0"
How far below amount a payment may be and still count as paid in full. Minor units.
object
Your own key-value data.
Response · 201
integer
Use this in URLs: GET /v1/payment-links/{id}.
string
The last part of the checkout URL.
string
active, paid, inactive or expired.
string | null
The fixed amount, or null for a link where the payer enters the amount.

Fixed and open amounts

  • Fixed amount. Set amount. The checkout charges exactly that. A payer cannot change it.
  • Open amount. Leave amount out. The payer enters what they want to pay.

What the payer sees

The hosted checkout shows your title, description and amount, then the payment methods you allowed. For a bank transfer it shows the account to pay into. For a card it collects the card and any PIN or one-time code. When the payment finishes it sends the payer to redirectUrl if you set one. You never handle card numbers.

Know when you are paid

Each payment through a link is a pay-in. Its merchantReference is paylink- followed by the link’s slug, so you can match it to the link.
  1. Receive payin.successful.
  2. Match data.merchant_reference, for example paylink-invoice-1042-k3x9qa, to your link.
  3. Fetch the pay-in and check status and subStatus.
  4. Fulfil.
Do not treat the payer arriving at your redirectUrl as proof of payment. Anyone can open that URL. Fulfil only after the pay-in is successful.

Overpayment and underpayment

A bank transfer can arrive for a different amount than the link asked for. On a fixed-amount link, Payve compares what arrived with amount and your two tolerances. Both tolerances default to 0: any difference, however small, counts as over or under.
An underpaid payment still reports status: successful and still sends payin.successful. Nothing was credited. Always check subStatus before you fulfil an order from a payment link.
The comparison uses the amount received after any transfer levy has been deducted. Set underpaymentTolerance high enough to cover such deductions, or an exact payment can be treated as short.

How the refund reaches the payer

Payve creates a refund for the excess or for the whole short payment. If the paying account is known, the refund waits for Payve’s review and is then sent there. If it is not known, the checkout asks the payer where to send it. GET /v1/refunds?payinTransactionId={id} shows the refund for a pay-in. Open-amount links have no expected amount, so no payment is over or under. PATCH and DELETE need the payins:write scope. To stop a link taking payments without deleting it, set its expiresAt to a time in the past. An expired link’s checkout page returns not found.
Deleting a link cannot be undone. Anyone who still has the URL will see a page that says the link was not found.

Limits on the checkout

The hosted checkout allows 120 payment attempts per link and 20 per payer IP address in any 10 minutes. See Rate limits.

When it fails