Payment Links API

🤖 Explain with AI

Payment Links API helps businesses to generate and customize payment links with specific details such as the payment amount, currency, description, and customer information.

Once the payment link is generated, businesses can share it with their customers via email, social media, or other communication channels. When the customer clicks on the link, they are taken to a payment processing page where they can enter their payment details and complete the transaction.

Create a new payment link¶

Endpoint

POST /v1/payment-links/

This endpoint allows you to create one or more payment links for specific customers or without customer details.

Query Parameters:

Parameter	Description	Type	Required
test	Indicates if the payment link is in test mode	boolean	false

Request Body Fields:

Parameter	Description	Type	Required
description	Description of the payment	string	true
amount	Payment amount (minimum USD $1.00 equivalent)	decimal	true
currency	Currency code (default: USD)	string	false
customers	Array of customer objects or customer IDs	array	false

Customer Object Fields (if providing new customers):

Parameter	Description	Type	Required
id	Existing customer UUID	string	false
customer	Alternative customer ID	string	false
first_name	Customer first name	string	false*
last_name	Customer last name	string	false*
email	Customer email address	string	false*

*Required together if not providing id or customer

Request (Create Single Payment Link):

curl -X POST 'https://api.4geeks.io/v1/payment-links/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -H 'Content-Type: application/json' \
     -d '{
           "description": "Premium Subscription 1 Year",
           "amount": 99.99,
           "currency": "USD",
           "customers": []
         }'

Request (Create Payment Link for Multiple Customers):

curl -X POST 'https://api.4geeks.io/v1/payment-links/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -H 'Content-Type: application/json' \
     -d '{
           "description": "Product License",
           "amount": 49.99,
           "currency": "USD",
           "customers": [
             {
               "id": "550e8400-e29b-41d4-a716-446655440000"
             },
             {
               "first_name": "John",
               "last_name": "Doe",
               "email": "john.doe@example.com"
             }
           ]
         }'

Response (201 Created - Single Link):

{
    "code": 201,
    "title": "Payment link created",
    "content": "The payment link was created correctly.",
    "type": "success",
    "data": {
        "id": "b3196f0b-bcba-46bc-b833-0bc845007c89",
        "link": "http://localhost:4200/pl/b3196f0b-bcba-46bc-b833-0bc845007c89"
    }
}

Response (201 Created - Multiple Links):

{
    "code": 201,
    "title": "Payment link created",
    "content": "The payment links were created correctly.",
    "type": "success",
    "data": [
        {
            "id": "987f6543-b21c-43d8-a567-123456789abc",
            "customer": "550e8400-e29b-41d4-a716-446655440000",
            "customer_name": "Alex Miller",
            "link": "http://localhost:3000/pl/987f6543-b21c-43d8-a567-123456789abc"
        },
        {
            "id": "aabbccdd-1122-3344-5566-77889900aabb",
            "customer": "650f9501-f40c-52e5-c827-557766551111",
            "customer_name": "John Doe",
            "link": "http://localhost:3000/pl/aabbccdd-1122-3344-5566-77889900aabb"
        }
    ]
}

Get all payment links¶

Endpoint

GET /v1/payment-links/

This endpoint retrieves all payment links for your account with pagination support.

Query Parameters:

Parameter	Description	Type	Required
page	Page number for pagination	integer	false
test	Filter by test mode (true/false)	boolean	false

Request:

curl -X GET 'https://api.4geeks.io/v1/payment-links/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Request (With Pagination):

curl -X GET 'https://api.4geeks.io/v1/payment-links/?page=1' \
     -u 'sk_test_51O62xYzAbcDef123:'

Response (200 OK):

{
    "count": 15,
    "next": "https://api.4geeks.io/v1/payment-links/?page=2",
    "previous": null,
    "results": [
        {
            "id": "aabbccdd-1122-3344-5566-77889900aabb",
            "description": "Premium Subscription 1 Year",
            "amount": "99.99",
            "currency": "USD",
            "payment_link": true,
            "active": true,
            "recurring": false,
            "next_date_of_payment": null,
            "status": "pending",
            "test": false,
            "created_on": "2025-12-04T10:30:00Z"
        },
        {
            "id": "ccddee11-2233-4455-6677-88990011aabb",
            "description": "Product License",
            "amount": "49.99",
            "currency": "USD",
            "payment_link": true,
            "active": true,
            "recurring": false,
            "next_date_of_payment": null,
            "status": "pending",
            "test": false,
            "created_on": "2025-12-03T15:45:00Z"
        }
    ]
}

Get a specific payment link¶

Endpoint

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

This endpoint retrieves complete details of a specific payment link by its ID.

Path Parameters:

Parameter	Description	Type	Required
id	The unique identifier of a payment link	string	true

Request:

curl -X GET 'https://api.4geeks.io/v1/payment-links/aabbccdd-1122-3344-5566-77889900aabb/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Response (200 OK):

{
    "id": "b3196f0b-bcba-46bc-b833-0bc845007c89",
    "description": "Premium Subscription 1 Year",
    "amount": 99.99,
    "currency": "USD",
    "payment_link": true,
    "active": true,
    "recurring": false,
    "next_date_of_payment": null,
    "status": "pending",
    "test": false,
    "created_on": "2025-12-04T22:56:39.903352Z",
    "payment_logs": []
}

Update a payment link¶

Endpoint

PUT /v1/payment-links/{id}/

Updates an existing payment link with new details.

Path Parameters:

Parameter	Description	Type	Required
id	The unique identifier of a payment link	string	true

Request Body Fields (all optional):

Parameter	Description	Type	Required
product	The ID of the associated product	string	false
customer	The ID of the customer (or null to remove)	string	false
active	Whether the payment link is active	boolean	false
recurring	Determines if the payment link is recurring	boolean	false
next_date_of_payment	Next scheduled payment date (YYYY-MM-DD HH:MM:SS)	string	false
status	The current status of the link	string	false
test	If true, link is in test mode; false for production	boolean	false

Valid Status Values:

pending - Awaiting payment
paid - Payment completed
paid_period - Period payment completed
pending_period - Period payment pending
cancelled / canceled - Link cancelled
defaulter - Payment overdue
active - Link is active
inactive - Link is inactive

Request:

curl -X PUT 'https://api.4geeks.io/v1/payment-links/aabbccdd-1122-3344-5566-77889900aabb/' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -H 'Content-Type: application/json' \
     -d '{
           "active": true,
           "status": "pending",
           "recurring": false,
           "customer": null
         }'

Response (200 OK):

{
    "code": 200,
    "title": "Updated Payment Link",
    "content": "The Payment Link was updated successfully.",
    "type": "success"
}

Response (400 Bad Request - Invalid Status):

{
    "code": 400,
    "title": "Invalid Status",
    "content": "The specified state is invalid.",
    "type": "error"
}

Delete a payment link¶

Endpoint

DELETE /v1/payment-links/{id}/

Deletes a specific payment link.

Path Parameters:

Parameter	Description	Type	Required
id	The unique identifier of a payment link	string	true

Request:

curl -X DELETE 'https://api.4geeks.io/v1/payment-links/aabbccdd-1122-3344-5566-77889900aabb/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Response (200 OK):

{
    "code": 200,
    "title": "Deleted",
    "content": "The Payment Link has been successfully removed.",
    "type": "success"
}

Error Handling¶

The API returns standard HTTP status codes to indicate the success or failure of a request. Below are common errors specific to payment links:

400 Bad Request¶

Occurs when the request is malformed or missing required fields.

Scenarios:

Scenario	Error Message	Solution
Missing description	`"You have not provided a description for the payment."`	Include the `description` field
Missing amount	`"You have not provided a price for payment."`	Include the `amount` field
Amount below minimum	`"The amount is equal to $X USD, which is below the minimum of $1.00 USD"`	Increase the amount to at least $1.00 USD equivalent
Invalid customer data	`"You have not provided a first_name, last_name and email or a customer id."`	Provide either an existing customer ID or complete customer details
Invalid date format	`"The date format must be YYYY-MM-DD HH:MM:SS"`	Use format: `2025-12-25 14:30:00`
Invalid status	`"The specified state is invalid."`	Use valid status: pending, paid, cancelled, etc.

Example Error Response:

{
    "code": 406,
    "title": "Missing Data",
    "content": "You have not provided a description for the payment.",
    "type": "danger"
}

401 Unauthorized¶

Authentication failed. API Key is invalid, missing, or malformed.

Example:

{
    "detail": "Authentication credentials were not provided."
}

Solution:

Verify you included the -u 'sk_test_...: parameter or Authorization: Basic header
Ensure your API Key is correct and active
Test with Postman using Basic Auth

404 Not Found¶

The requested payment link does not exist.

Example:

{
    "code": 404,
    "title": "Payment Link not found",
    "content": "The Payment Link could not be found, please check the id.",
    "type": "danger"
}

Solution:

Verify the payment link ID exists
Use the list endpoint to find the correct payment link ID
Ensure the payment link belongs to your developer account

Important Notes¶

Payment Link Validation

Amount must be at least USD $1.00 equivalent
Description is mandatory
Links cannot be modified once paid

Customer Information

Payment links can be created with or without customer information
When creating links for existing customers, provide their UUID
When creating links for new customers, provide first_name, last_name, and email

Payment Status

Payment links start in pending status
Status updates automatically based on payment activity
Recurring links transition to paid_period after payment

Test vs Production

Use your Test Key (sk_test_...) for development and testing
Use your Live Key (sk_live_...) for real transactions
Query parameter ?test=true or ?test=false controls the mode
The system automatically detects the mode based on the API Key used

Best Practices¶

Include clear descriptions - Help customers understand what they’re paying for
Use correct currency - Match your business region and customer expectations
Set minimum amounts - Ensure amounts are at least $1.00 USD equivalent
Assign customers - Link payments to customer records for better tracking
Monitor payment logs - Use payment logs to reconcile transactions
Update status appropriately - Keep payment link status in sync with actual payment state
Test before production - Use test mode with test API keys for validation

Troubleshooting¶

Problem: “The amount is below the minimum”¶

Cause: Payment amount is less than USD $1.00 equivalent
Solution:

Increase the amount field to at least 1.00
Verify the currency conversion if using non-USD currency

Problem: “You have not provided a description”¶

Cause: Missing required description field
Solution:

Include a clear, descriptive title for the payment
Example: “Premium Subscription”, “Product License”, “Service Fee”

Problem: “You have not provided a first_name, last_name and email or a customer id”¶

Cause: Incomplete customer information
Solution:

Either provide an existing customer ID in the customers array
Or provide complete customer details: first_name, last_name, and email

Problem: “The specified state is invalid”¶

Cause: Invalid status value provided
Solution:

Use only valid status values: pending, paid, paid_period, pending_period, cancelled, canceled, defaulter, active, inactive
Check the documentation for status definitions

Problem: “Payment Link not found”¶

Cause: Payment link ID doesn’t exist or belongs to a different developer account
Solution:

Verify the payment link ID using the list endpoint
Ensure you’re using the correct API Key
Check that the payment link hasn’t been deleted

Login or signup into Console.
Check out the changelog.
Contact our enterprise support team.