Skip to content

Payment Links API

Explain with AI

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.

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"
  }
}

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"
  }
]

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": []
}

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"
}

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."
}