Payment Links API

Basically the Payment Links API help businesses to generate and customize the payment link with specific details such as the payment amount, currency, description and customer.

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 a payment link for a specific product.

Fields:

Parameter	Description	Type	Required
product	A product to sell.	string	true
customers	List of customer IDs for whom the payment link is intended.	array	false
test	Indicates if the payment link is in test mode (true for testing, false for production).	boolean	false

Request:

curl -X POST 'https://api.4geeks.io/v1/payment-links/' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
           "product": "123e4567-e89b-12d3-a456-426614174000",
           "customers": [],
           "test": false
         }'

Response:

{
  "code": 201,
  "title": "Payment link created",
  "content": "The payment link was created correctly.",
  "type": "success",
  "data": {
    "id": "987f6543-b21c-43d8-a567-123456789abc",
    "link": "https://api.4geeks.io/pl/987f6543-b21c-43d8-a567-123456789abc"
  }
}

Get all payment links¶

Endpoint

GET /v1/payment-links/

This endpoint retrieves all payment links.

Request:

curl -X GET 'https://api.4geeks.io/v1/payment-links/' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response:

[
  {
    "id": "aabbccdd-1122-3344-5566-77889900aabb",
    "amount": 50.0,
    "total_amount": 50.0,
    "currency": "USD",
    "product": "123e4567-e89b-12d3-a456-426614174000",
    "client_name": "John Doe",
    "email": "johndoe@example.com",
    "customer": "11223344-5566-7788-99aa-bbccddeeff00",
    "active": true,
    "recurring": false,
    "next_date_of_payment": "2025-04-01T10:00:00.000Z",
    "status": "pending",
    "test": false,
    "created_on": "2025-03-18T10:24:28.162994Z"
  }
]

Get a payment link¶

Endpoint

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

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

Request:

curl -X GET 'https://api.4geeks.io/v1/payment-links/aabbccdd-1122-3344-5566-77889900aabb/' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response:

{
  "id": "aabbccdd-1122-3344-5566-77889900aabb",
  "product": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Premium Subscription",
    "short_description": "One-year premium membership",
    "description": "<p>Access to exclusive content and features for one year.</p>",
    "stock": 10,
    "price": 50.0,
    "currency": "USD",
    "is_physical": false,
    "bar_code": "9876543210",
    "sku": "PREMIUM-1Y",
    "recurrence": "yearly",
    "images": {
      "images": [],
      "default": ""
    }
  },
  "payment_link": true,
  "created_on": "2025-03-14T10:11:56.759828Z",
  "test": false,
  "total_price": 50.0,
  "taxes": [
    {
      "type": "VAT",
      "percentage": 5.0
    }
  ],
  "active": true,
  "recurring": false,
  "next_date_of_payment": "2025-04-01T10:00:00.000Z",
  "status": "pending",
  "payment_logs": []
}

Update a payment link¶

Endpoint

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

Updates an existing payment link

Fields

Parameter	Description	Type	Required
active	Indicates whether the payment link is active.	`boolean`	true
status	The current status (`pending`, `canceled`, `defaulter`, `paid`, `paid_period`, `pending_period`).	`string`	true
recurring	Determines if the payment link is recurring.	`boolean`	false
next_date_of_payment	The next scheduled payment date (ISO 8601 format).	string	false
product	The ID of the associated product.	string	true
customer	The ID of the customer (if any).	string	false
test	If `true`, the link is in test mode. If `false`, it works in production mode.	`boolean`	true

Request:

curl -X PUT 'https://api.4geeks.io/v1/payment-links/aabbccdd-1122-3344-5566-77889900aabb/' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
           "active": true,
           "status": "canceled",
           "recurring": false,
           "next_date_of_payment": "2025-02-20 12:39:00",
           "product": "1472e400-accb-4e23-997d-209fb41e8fac",
           "customer": null,
           "test": false
         }'

Response:

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

Delete a Payment Link¶

Endpoint

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

Deletes a specific payment link.

Request:

curl -X DELETE 'https://api.4geeks.io/v1/payment-links/aabbccdd-1122-3344-5566-77889900aabb/' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response:

{
  "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 some common errors:

Status Code	Error Message	Description
400	Bad Request	The request is malformed or missing required parameters.
401	Unauthorized	The request lacks valid authentication credentials.
404	Not Found	The requested resource (e.g., Payment Link ID) does not exist.
500	Internal Server Error	An unexpected error occurred on the server. Contact support for assistance.

Example error response¶

{
  "error": "Unauthorized",
  "message": "Authentication credentials were not provided."
}