Skip to main content
POST
/
payment-links
Create a payment link
curl --request POST \
  --url https://prod-api.pcxpay.com/v1/payment-links \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <x-api-key>' \
  --data '
{
  "email": "customer@example.com",
  "org_id": "org_abc123",
  "transaction_id": "txn_xyz789",
  "payment_amount": 5000,
  "scheduled_at": "2026-04-15T10:00:00",
  "otp": "482910",
  "currency": "NGN"
}
'
{
  "link_id": "lnk_a1b2c3d4",
  "transaction_id": "txn_xyz789",
  "org_id": "org_abc123",
  "payment_link": "https://pay.pcxpay.com/lnk_a1b2c3d4",
  "expires_at": "2026-04-16T10:00:00",
  "expires_at_timestamp": 1744790400,
  "status": "active",
  "email": "customer@example.com",
  "payment_amount": 5000,
  "scheduled_at": "2026-04-15T10:00:00",
  "created_at": "2026-04-13T08:00:00",
  "currency": "NGN"
}

Headers

​
Authorization
string
default:NONE
required

Bearer JWT for user-facing flows (Bearer eyJraWQ...), or the literal string NONE when authenticating via API key.

Example:

"Bearer eyJraWQ..."

​
X-Api-Key
string
default:NONE
required

API key for server-to-server flows, or the literal string NONE when authenticating via JWT.

Example:

"pcx_abc123_xxxx"

Body

application/json
​
email
string<email>
required

Recipient email address for the payment link.

Example:

"customer@example.com"

​
org_id
string
required

The organization ID issuing the payment link.

Example:

"org_abc123"

​
transaction_id
string | null

Optional transaction ID to associate with this payment link.

Example:

"txn_xyz789"

​
payment_amount
number<float> | null

Amount the customer is expected to pay. If omitted, the link is open-ended.

Example:

5000

​
scheduled_at
string | null

ISO 8601 date/datetime at which this link is scheduled to be sent. Used by the scheduled email job.

Example:

"2026-04-15T10:00:00"

​
otp
string | null

OTP code (if pre-verified before link creation).

Example:

"482910"

​
currency
string | null

Currency code (e.g. NGN, USD).

Example:

"NGN"

Response

Payment link created successfully.

​
link_id
string
Example:

"lnk_a1b2c3d4"

​
transaction_id
string | null
Example:

"txn_xyz789"

​
org_id
string
Example:

"org_abc123"

​
payment_link
string<uri>

The full URL of the payment link to share with the customer.

Example:

"https://pay.pcxpay.com/lnk_a1b2c3d4"

​
expires_at
string<date-time>
Example:

"2026-04-16T10:00:00"

​
expires_at_timestamp
integer
Example:

1744790400

​
status
enum<string>
Available options:
active,
revoked,
expired
Example:

"active"

​
email
string<email>
Example:

"customer@example.com"

​
payment_amount
number | null
Example:

5000

​
scheduled_at
string | null
Example:

"2026-04-15T10:00:00"

​
created_at
string<date-time>
Example:

"2026-04-13T08:00:00"

​
currency
string | null
Example:

"NGN"