Skip to content

🤖 Explain with AI

Payment Links API

The Payment Links API allows you to create shareable payment links that customers can use to complete payments without a custom integration.

Base URL

https://api.4geeks.io

Authentication

All endpoints require the X-Api-Key header:

X-Api-Key: sk_test_your_api_key_here

See Authentication for details.

Creates a new payment link.

POST /v1/payment-links

Request Body

Field Type Required Description
amount integer Yes Amount in cents
currency string Yes Currency code (e.g., USD, EUR)
description string Yes Description of the payment
return_url string No Where the buyer lands after paying. Without it the gateway shows its own confirmation page

Request Example

curl -X POST 'https://api.4geeks.io/v1/payment-links' \
  -H 'X-Api-Key: sk_test_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 4999,
    "currency": "USD",
    "description": "One-time service fee"
  }'

import requests

response = requests.post(
    'https://api.4geeks.io/v1/payment-links',
    headers={'X-Api-Key': 'sk_test_your_api_key_here'},
    json={
        'amount': 4999,
        'currency': 'USD',
        'description': 'One-time service fee'
    }
)
print(response.json())

const response = await fetch('https://api.4geeks.io/v1/payment-links', {
    method: 'POST',
    headers: {
        'X-Api-Key': 'sk_test_your_api_key_here',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        amount: 4999,
        currency: 'USD',
        description: 'One-time service fee'
    })
});
const data = await response.json();
console.log(data);

Response (200 OK)

Field Type Description
id string Internal payment link ID
object string Object type (default: “payment_link”)
url string The URL to redirect the user to
active boolean Whether the link is active

Response Example

{
    "id": "plink_3m4n5o6p7q8r",
    "object": "payment_link",
    "url": "https://pay.4geeks.io/link/plink_3m4n5o6p7q8r",
    "active": true
}

Lists payment links with pagination.

GET /v1/payment-links

Query Parameters

Parameter Type Required Default Description
limit integer No 10 Page size, 1–100
offset integer No 0 Number of results to skip (up to 1000)

Request Example

curl -X GET 'https://api.4geeks.io/v1/payment-links?limit=5&offset=0' \
  -H 'X-Api-Key: sk_test_your_api_key_here'

import requests

response = requests.get(
    'https://api.4geeks.io/v1/payment-links',
    headers={'X-Api-Key': 'sk_test_your_api_key_here'},
    params={'limit': 5, 'offset': 0}
)
print(response.json())

const response = await fetch('https://api.4geeks.io/v1/payment-links?limit=5&offset=0', {
    headers: {'X-Api-Key': 'sk_test_your_api_key_here'}
});
const data = await response.json();
console.log(data);

Response (200 OK)

Field Type Description
items array[PaymentLinkResponse] Array of payment link objects
total_items integer Total number of payment links. Lower bound: the gateway does not expose counts
limit integer Requested page size
offset integer Requested offset
has_more boolean Whether another page exists

Response Example

{
    "items": [
        {
            "id": "plink_3m4n5o6p7q8r",
            "object": "payment_link",
            "url": "https://pay.4geeks.io/link/plink_3m4n5o6p7q8r",
            "active": true
        },
        {
            "id": "plink_9s8t7u6v5w4x",
            "object": "payment_link",
            "url": "https://pay.4geeks.io/link/plink_9s8t7u6v5w4x",
            "active": false
        }
    ],
    "total_items": 2,
    "limit": 5,
    "offset": 0,
    "has_more": false
}

Error Response (422 Validation Error)

All endpoints may return a 422 status when validation fails.

{
    "detail": [
        {
            "loc": ["body", "amount"],
            "msg": "field required",
            "type": "value_error.missing"
        }
    ]
}

Still have questions? Ask on Discord or explore the tutorials.