Payment Links API

Payment Links allow you to create shareable URLs that accept payments without writing checkout code.

The Payment Link Object

{
  "id": "pl_abc123def456",
  "object": "payment_link",
  "active": true,
  "amount": 10000,
  "currency": "GHS",
  "name": "Premium Subscription",
  "description": "Monthly subscription to Premium plan",
  "url": "https://paygate.44.200.142.19.nip.io/pay/pl_abc123def456",
  "allow_custom_amount": false,
  "minimum_amount": null,
  "maximum_amount": null,
  "collect_phone": true,
  "collect_email": true,
  "collect_name": false,
  "success_url": "https://yoursite.com/success",
  "metadata": {
    "product_id": "prod_123"
  },
  "created_at": "2024-01-15T10:00:00Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier
`object`	string	Always `"payment_link"`
`active`	boolean	Whether link is active
`amount`	integer	Amount in pesewas (null for custom amounts)
`currency`	string	Currency code
`name`	string	Link name/title
`description`	string	Description
`url`	string	Shareable payment URL
`allow_custom_amount`	boolean	Allow customer to enter amount
`minimum_amount`	integer	Minimum amount if custom
`maximum_amount`	integer	Maximum amount if custom
`collect_phone`	boolean	Require phone number
`collect_email`	boolean	Require email
`collect_name`	boolean	Require name
`success_url`	string	Redirect after payment
`metadata`	object	Custom metadata
`created_at`	string	Creation timestamp

Create a Payment Link

Creates a new payment link.

POST /v1/payment_links

Request Body

Parameter	Type	Required	Description
`amount`	integer	No*	Amount in pesewas
`currency`	string	No	Currency (default: `GHS`)
`name`	string	Yes	Link name
`description`	string	No	Description
`allow_custom_amount`	boolean	No	Allow custom amount
`minimum_amount`	integer	No	Min amount (if custom)
`maximum_amount`	integer	No	Max amount (if custom)
`collect_phone`	boolean	No	Require phone
`collect_email`	boolean	No	Require email
`collect_name`	boolean	No	Require name
`success_url`	string	No	Redirect URL
`expires_at`	string	No	Expiration timestamp
`metadata`	object	No	Custom metadata

Either amount or allow_custom_amount: true is required.

# Fixed amount link
curl -X POST https://api.44.200.142.19.nip.io/v1/payment_links \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "GHS",
    "name": "Premium Subscription",
    "description": "Monthly subscription to Premium plan",
    "collect_email": true,
    "success_url": "https://yoursite.com/success",
    "metadata": {
      "product_id": "prod_123"
    }
  }'

# Custom amount link (donation)
curl -X POST https://api.44.200.142.19.nip.io/v1/payment_links \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Donation",
    "description": "Support our cause",
    "allow_custom_amount": true,
    "minimum_amount": 100,
    "maximum_amount": 1000000,
    "collect_email": true,
    "collect_name": true
  }'

// Fixed amount link
const link = await paygate.paymentLinks.create({
  amount: 10000,
  currency: 'GHS',
  name: 'Premium Subscription',
  description: 'Monthly subscription to Premium plan',
  collect_email: true,
  success_url: 'https://yoursite.com/success',
  metadata: {
    product_id: 'prod_123'
  }
})

console.log(link.url) // https://paygate.44.200.142.19.nip.io/pay/pl_abc123

// Custom amount link (donation)
const donationLink = await paygate.paymentLinks.create({
  name: 'Donation',
  description: 'Support our cause',
  allow_custom_amount: true,
  minimum_amount: 100,
  maximum_amount: 1000000,
  collect_email: true,
  collect_name: true
})

# Fixed amount link
link = client.payment_links.create(
    amount=10000,
    currency='GHS',
    name='Premium Subscription',
    description='Monthly subscription to Premium plan',
    collect_email=True,
    success_url='https://yoursite.com/success',
    metadata={'product_id': 'prod_123'}
)

print(link.url)  # https://paygate.44.200.142.19.nip.io/pay/pl_abc123

# Custom amount link
donation_link = client.payment_links.create(
    name='Donation',
    description='Support our cause',
    allow_custom_amount=True,
    minimum_amount=100,
    maximum_amount=1000000,
    collect_email=True,
    collect_name=True
)

// Fixed amount link
$link = $paygate->paymentLinks->create([
    'amount' => 10000,
    'currency' => 'GHS',
    'name' => 'Premium Subscription',
    'description' => 'Monthly subscription to Premium plan',
    'collect_email' => true,
    'success_url' => 'https://yoursite.com/success',
    'metadata' => ['product_id' => 'prod_123']
]);

echo $link->url;

// Custom amount link
$donationLink = $paygate->paymentLinks->create([
    'name' => 'Donation',
    'description' => 'Support our cause',
    'allow_custom_amount' => true,
    'minimum_amount' => 100,
    'maximum_amount' => 1000000,
    'collect_email' => true,
    'collect_name' => true
]);

Retrieve a Payment Link

Retrieves a payment link by ID.

GET /v1/payment_links/:id

curl https://api.44.200.142.19.nip.io/v1/payment_links/pl_abc123def456 \
  -H "Authorization: Bearer sk_test_..."

const link = await paygate.paymentLinks.retrieve('pl_abc123def456')

link = client.payment_links.retrieve('pl_abc123def456')

Update a Payment Link

Updates a payment link.

PATCH /v1/payment_links/:id

Request Body

Parameter	Type	Description
`name`	string	Link name
`description`	string	Description
`active`	boolean	Whether link is active
`success_url`	string	Redirect URL
`metadata`	object	Custom metadata

curl -X PATCH https://api.44.200.142.19.nip.io/v1/payment_links/pl_abc123def456 \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Product Name",
    "active": true
  }'

const link = await paygate.paymentLinks.update('pl_abc123def456', {
  name: 'Updated Product Name',
  active: true
})

link = client.payment_links.update('pl_abc123def456',
    name='Updated Product Name',
    active=True
)

List Payment Links

Returns a list of payment links.

GET /v1/payment_links

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (1-100)
`starting_after`	string	Cursor for pagination
`active`	boolean	Filter by active status

curl "https://api.44.200.142.19.nip.io/v1/payment_links?active=true&limit=10" \
  -H "Authorization: Bearer sk_test_..."

const links = await paygate.paymentLinks.list({
  active: true,
  limit: 10
})

links = client.payment_links.list(active=True, limit=10)

Deactivate a Payment Link

Deactivate a link to stop accepting payments:

const link = await paygate.paymentLinks.update('pl_abc123def456', {
  active: false
})

Track Payments from Links

List payments made through a specific link:

const payments = await paygate.payments.list({
  payment_link: 'pl_abc123def456'
})

console.log(`Total payments: ${payments.data.length}`)

Or use webhooks:

app.post('/webhooks', (req, res) => {
  const event = Webhook.constructEvent(req.body, signature, secret)

  if (event.type === 'payment.succeeded') {
    const payment = event.data.object

    if (payment.payment_link) {
      console.log(`Payment via link: ${payment.payment_link}`)
      // Process the payment
    }
  }

  res.json({ received: true })
})

Payment Links

On this page