Skip to content
PaySigna

Payment links

Endpoint What it does
POST /v1/payment-links Create a payment link
GET /v1/payment-links List payment links
GET /v1/payment-links/{id} Retrieve a payment link
GET /v1/payment-links/{id}/payments Payments made through a link
POST /v1/payment-links/{id}/status Pause, resume or archive a payment link

Try any of them in the API tester.

Section titled “Create a payment link”

POST /v1/payment-links

A shareable address that takes payments on rules you set, on a page with your checkout branding. A fixed or open amount; one-time, limited or unlimited uses; an opening and closing time; paid in full, in parts the payer chooses, or in equal instalments; and what to ask the payer. Share url, or its QR code.

Every payment through a link is an ordinary charge: it appears in transactions and webhooks like any other, and metadata.payment_link names the link.

With a live key, a channels entry your account is not enabled to collect over is refused with 403 capability_disabled. A method that is enabled but not yet priced is accepted, and the payment page leaves it out until a price applies.

Authentication: a secret key (server-side only) with the scope billing.write.

Request body

Section titled “Request body”
Field Type Required Allowed values and limits What it is
amount integer no min 1; e.g. 15000 The amount for a fixed link, or the total to collect when payment_mode is payer_parts or instalments. Minor units.
amount_mode string yes One of: fixed, open fixed: the link names the amount. open: the payer types it, within min_amount and max_amount.
channels array yes How payers may pay: mobile_money, card.
collect_email string no One of: required, optional, hidden Default optional. A card payment always asks for an email.
collect_name string no One of: required, optional, hidden Whether the page asks the payer’s name. Default required.
collect_phone string no One of: required, optional, hidden Default hidden.
currency string no exactly 3 characters; e.g. GHS Defaults to your settlement currency.
custom_fields array no Up to three questions of your own, such as an order or student number. Answers come back on each payment.
description string no at most 1000 characters Shown under the title.
expires_at string (date-time) no Not payable from this. Omit for no end.
instalment_count integer no min 2; max 60 instalments: how many parts. The remainder of the division goes on the last.
max_amount integer no min 1 Open amount, full payments: the most a payer may pay.
max_uses integer no min 1 Full payments only: how many payments the link takes. Omit for unlimited; 1 makes a one-time link.
min_amount integer no min 1 Open amount, full payments: the least a payer may pay.
min_part integer no min 1 payer_parts: the smallest part accepted. The last part may be smaller: whatever is left.
payment_mode string no One of: full, payer_parts, instalments full (default): each payment pays in full. payer_parts: payers pay any part until amount is collected. instalments: amount is split into instalment_count equal parts, paid in order.
redirect_url string no https:// address the payer is sent to a few seconds after paying.
starts_at string (date-time) no Not payable before this. Omit to open now.
success_message string no at most 500 characters Shown after a payment. Defaults to your checkout branding’s.
title string yes at least 2 characters; at most 150 characters; e.g. Workshop ticket Shown at the top of the payment page.
Terminal window
curl -X POST https://sandbox.paysigna.com/v1/payment-links \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 15000,
  "amount_mode": "fixed",
  "channels": "string",
  "currency": "GHS",
  "title": "Workshop ticket"
}'

Response 201

Section titled “Response 201”
Field Type What it is
amount integer The amount for a fixed link, or the total to collect when payment_mode is payer_parts or instalments. Minor units.
amount_mode string fixed: the link names the amount. open: the payer types it, within min_amount and max_amount. One of: fixed, open
availability string Whether a payer could pay it right now, and if not, why. sold_out: every use or part is taken or in flight. One of: open, paused, not_started, expired, completed, sold_out, archived
channels array How payers may pay: mobile_money, card.
collect_email string Default optional. A card payment always asks for an email. One of: required, optional, hidden
collect_name string Whether the page asks the payer’s name. Default required. One of: required, optional, hidden
collect_phone string Default hidden. One of: required, optional, hidden
collected integer What those payments came to, in minor units.
created_at string (date-time)
currency string Defaults to your settlement currency.
custom_fields array Up to three questions of your own, such as an order or student number. Answers come back on each payment.
description string Shown under the title.
expires_at string (date-time) Not payable from this. Omit for no end.
id string
instalment_count integer instalments: how many parts. The remainder of the division goes on the last.
max_amount integer Open amount, full payments: the most a payer may pay.
max_uses integer Full payments only: how many payments the link takes. Omit for unlimited; 1 makes a one-time link.
min_amount integer Open amount, full payments: the least a payer may pay.
min_part integer payer_parts: the smallest part accepted. The last part may be smaller: whatever is left.
next_instalment integer Instalments: the one a payer would pay now.
next_instalment_amount integer
object string
paid_count integer Payments that succeeded.
payment_mode string full (default): each payment pays in full. payer_parts: payers pay any part until amount is collected. instalments: amount is split into instalment_count equal parts, paid in order. One of: full, payer_parts, instalments
redirect_url string https:// address the payer is sent to a few seconds after paying.
remaining integer Parts and instalments: what is left of amount, net of payments in flight.
starts_at string (date-time) Not payable before this. Omit to open now.
status string completed: its total was reached or its last use taken. One of: active, paused, completed, archived
success_message string Shown after a payment. Defaults to your checkout branding’s.
title string Shown at the top of the payment page.
url string The address to share. Its QR code is the same address.

Errors

Section titled “Errors”
  • 400: the request is malformed
  • 401: the key is missing, wrong or revoked
  • 403: the key lacks the scope, or your account may not do this
  • 404: no such resource on this account
  • 409: it conflicts with the current state, or the idempotency key was used for a different request
  • 422: a field is invalid; errors names it
  • 429: too many requests; wait for Retry-After
  • 500: Internal Server Error

Every error is a JSON problem with a stable code. See Errors.

Section titled “List payment links”

GET /v1/payment-links

Authentication: a secret key (server-side only) with the scope billing.read.

Parameters

Section titled “Parameters”
Field Type Required Allowed values and limits What it is
status string no One of: active, paused, completed, archived Only links in this status.
limit integer no min 1; max 100; default 50 Page size.
offset integer no min 0 How many to skip.

Response 200

Section titled “Response 200”
Field Type What it is
data array
object string

Errors

Section titled “Errors”
  • 400: the request is malformed
  • 401: the key is missing, wrong or revoked
  • 403: the key lacks the scope, or your account may not do this
  • 404: no such resource on this account
  • 409: it conflicts with the current state, or the idempotency key was used for a different request
  • 422: a field is invalid; errors names it
  • 429: too many requests; wait for Retry-After
  • 500: Internal Server Error

Every error is a JSON problem with a stable code. See Errors.

Section titled “Retrieve a payment link”

GET /v1/payment-links/{id}

With availability: whether a payer could pay it right now, and if not, why.

Authentication: a secret key (server-side only) with the scope billing.read.

Parameters

Section titled “Parameters”
Field Type Required Allowed values and limits What it is
{id} string (uuid) yes The link’s id.

Response 200

Section titled “Response 200”
Field Type What it is
amount integer The amount for a fixed link, or the total to collect when payment_mode is payer_parts or instalments. Minor units.
amount_mode string fixed: the link names the amount. open: the payer types it, within min_amount and max_amount. One of: fixed, open
availability string Whether a payer could pay it right now, and if not, why. sold_out: every use or part is taken or in flight. One of: open, paused, not_started, expired, completed, sold_out, archived
channels array How payers may pay: mobile_money, card.
collect_email string Default optional. A card payment always asks for an email. One of: required, optional, hidden
collect_name string Whether the page asks the payer’s name. Default required. One of: required, optional, hidden
collect_phone string Default hidden. One of: required, optional, hidden
collected integer What those payments came to, in minor units.
created_at string (date-time)
currency string Defaults to your settlement currency.
custom_fields array Up to three questions of your own, such as an order or student number. Answers come back on each payment.
description string Shown under the title.
expires_at string (date-time) Not payable from this. Omit for no end.
id string
instalment_count integer instalments: how many parts. The remainder of the division goes on the last.
max_amount integer Open amount, full payments: the most a payer may pay.
max_uses integer Full payments only: how many payments the link takes. Omit for unlimited; 1 makes a one-time link.
min_amount integer Open amount, full payments: the least a payer may pay.
min_part integer payer_parts: the smallest part accepted. The last part may be smaller: whatever is left.
next_instalment integer Instalments: the one a payer would pay now.
next_instalment_amount integer
object string
paid_count integer Payments that succeeded.
payment_mode string full (default): each payment pays in full. payer_parts: payers pay any part until amount is collected. instalments: amount is split into instalment_count equal parts, paid in order. One of: full, payer_parts, instalments
redirect_url string https:// address the payer is sent to a few seconds after paying.
remaining integer Parts and instalments: what is left of amount, net of payments in flight.
starts_at string (date-time) Not payable before this. Omit to open now.
status string completed: its total was reached or its last use taken. One of: active, paused, completed, archived
success_message string Shown after a payment. Defaults to your checkout branding’s.
title string Shown at the top of the payment page.
url string The address to share. Its QR code is the same address.

Errors

Section titled “Errors”
  • 400: the request is malformed
  • 401: the key is missing, wrong or revoked
  • 403: the key lacks the scope, or your account may not do this
  • 404: no such resource on this account
  • 409: it conflicts with the current state, or the idempotency key was used for a different request
  • 422: a field is invalid; errors names it
  • 429: too many requests; wait for Retry-After
  • 500: Internal Server Error

Every error is a JSON problem with a stable code. See Errors.

Section titled “Payments made through a link”

GET /v1/payment-links/{id}/payments

Authentication: a secret key (server-side only) with the scope billing.read.

Parameters

Section titled “Parameters”
Field Type Required Allowed values and limits What it is
{id} string (uuid) yes
limit integer no min 1; max 100; default 50
offset integer no min 0

Response 200

Section titled “Response 200”
Field Type What it is
data array
object string

Errors

Section titled “Errors”
  • 400: the request is malformed
  • 401: the key is missing, wrong or revoked
  • 403: the key lacks the scope, or your account may not do this
  • 404: no such resource on this account
  • 409: it conflicts with the current state, or the idempotency key was used for a different request
  • 422: a field is invalid; errors names it
  • 429: too many requests; wait for Retry-After
  • 500: Internal Server Error

Every error is a JSON problem with a stable code. See Errors.

Section titled “Pause, resume or archive a payment link”

POST /v1/payment-links/{id}/status

Authentication: a secret key (server-side only) with the scope billing.write.

Parameters

Section titled “Parameters”
Field Type Required Allowed values and limits What it is
{id} string (uuid) yes

Request body

Section titled “Request body”
Field Type Required Allowed values and limits What it is
status string yes One of: active, paused, archived paused stops payments until resumed; archived ends the link for good.
Terminal window
curl -X POST https://sandbox.paysigna.com/v1/payment-links/{id}/status \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active"
}'

Response 200

Section titled “Response 200”
Field Type What it is
amount integer The amount for a fixed link, or the total to collect when payment_mode is payer_parts or instalments. Minor units.
amount_mode string fixed: the link names the amount. open: the payer types it, within min_amount and max_amount. One of: fixed, open
availability string Whether a payer could pay it right now, and if not, why. sold_out: every use or part is taken or in flight. One of: open, paused, not_started, expired, completed, sold_out, archived
channels array How payers may pay: mobile_money, card.
collect_email string Default optional. A card payment always asks for an email. One of: required, optional, hidden
collect_name string Whether the page asks the payer’s name. Default required. One of: required, optional, hidden
collect_phone string Default hidden. One of: required, optional, hidden
collected integer What those payments came to, in minor units.
created_at string (date-time)
currency string Defaults to your settlement currency.
custom_fields array Up to three questions of your own, such as an order or student number. Answers come back on each payment.
description string Shown under the title.
expires_at string (date-time) Not payable from this. Omit for no end.
id string
instalment_count integer instalments: how many parts. The remainder of the division goes on the last.
max_amount integer Open amount, full payments: the most a payer may pay.
max_uses integer Full payments only: how many payments the link takes. Omit for unlimited; 1 makes a one-time link.
min_amount integer Open amount, full payments: the least a payer may pay.
min_part integer payer_parts: the smallest part accepted. The last part may be smaller: whatever is left.
next_instalment integer Instalments: the one a payer would pay now.
next_instalment_amount integer
object string
paid_count integer Payments that succeeded.
payment_mode string full (default): each payment pays in full. payer_parts: payers pay any part until amount is collected. instalments: amount is split into instalment_count equal parts, paid in order. One of: full, payer_parts, instalments
redirect_url string https:// address the payer is sent to a few seconds after paying.
remaining integer Parts and instalments: what is left of amount, net of payments in flight.
starts_at string (date-time) Not payable before this. Omit to open now.
status string completed: its total was reached or its last use taken. One of: active, paused, completed, archived
success_message string Shown after a payment. Defaults to your checkout branding’s.
title string Shown at the top of the payment page.
url string The address to share. Its QR code is the same address.

Errors

Section titled “Errors”
  • 400: the request is malformed
  • 401: the key is missing, wrong or revoked
  • 403: the key lacks the scope, or your account may not do this
  • 404: no such resource on this account
  • 409: it conflicts with the current state, or the idempotency key was used for a different request
  • 422: a field is invalid; errors names it
  • 429: too many requests; wait for Retry-After
  • 500: Internal Server Error

Every error is a JSON problem with a stable code. See Errors.