Payments API

🤖 Explain with AI

The Payments API enables you to create checkout sessions, process payments, manage payment intents, and retrieve transaction details. Most endpoints require authentication via API Key.

Base URL

https://api.4geeks.io

Authentication¶

Most endpoints require the X-Api-Key header:

X-Api-Key: sk_test_your_api_key_here

See Authentication for details.

Create Checkout Session¶

Creates a secure checkout session in the database (Server-to-Server Flow). Returns the session ID and the custom checkout URL to redirect the user to.

POST /v1/payments/session

Request Body¶

Field	Type	Required	Description
amount	string	Yes	Total amount to charge (decimal format, e.g., 99.99)
currency	string	Yes	A valid currency code ISO-4217, e.g. USD
return_url	string	Yes	URL to redirect after payment completion
description	string	No	A description of the payment
items	array[string]	No	Name(s) of product(s) or service(s). Default: []
mode	string	No	Checkout mode: ‘payment’ or ‘subscription’. Default: “payment”
price_id	string	No	Payment Processor Price ID for subscriptions
customer_id	string	No	Payment Processor Customer ID

Request Example¶

cURLPythonJavaScript

curl -X POST 'https://api.4geeks.io/v1/payments/session' \
  -H 'X-Api-Key: sk_test_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": "99.99",
    "currency": "USD",
    "description": "Premium subscription",
    "items": ["Premium Plan"],
    "return_url": "https://yoursite.com/success"
  }'

import requests

response = requests.post(
    'https://api.4geeks.io/v1/payments/session',
    headers={'X-Api-Key': 'sk_test_your_api_key_here'},
    json={
        'amount': '99.99',
        'currency': 'USD',
        'description': 'Premium subscription',
        'items': ['Premium Plan'],
        'return_url': 'https://yoursite.com/success'
    }
)
print(response.json())

const response = await fetch('https://api.4geeks.io/v1/payments/session', {
    method: 'POST',
    headers: {
        'X-Api-Key': 'sk_test_your_api_key_here',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        amount: '99.99',
        currency: 'USD',
        description: 'Premium subscription',
        items: ['Premium Plan'],
        return_url: 'https://yoursite.com/success'
    })
});
const data = await response.json();
console.log(data);

Response (201 Created)¶

Field	Type	Description
session_id	string	The unique session ID to pass to the frontend
checkout_url	string	The URL you should redirect your user to

Response Example¶

{
    "session_id": "sess_1a2b3c4d5e6f",
    "checkout_url": "https://checkout.4geeks.io/session/sess_1a2b3c4d5e6f"
}

Get Checkout Session¶

Retrieves safe details of a checkout session for the frontend to display. No API key required because the session_id acts as a secure token for the buyer.

GET /v1/payments/session/{session_id}

Path Parameters¶

Parameter	Type	Required	Description
session_id	string	Yes	The checkout session ID

Request Example¶

cURLPythonJavaScript

curl -X GET 'https://api.4geeks.io/v1/payments/session/sess_1a2b3c4d5e6f'

import requests

response = requests.get(
    'https://api.4geeks.io/v1/payments/session/sess_1a2b3c4d5e6f'
)
print(response.json())

const response = await fetch('https://api.4geeks.io/v1/payments/session/sess_1a2b3c4d5e6f');
const data = await response.json();
console.log(data);

Response (200 OK)¶

Field	Type	Description
id	string	Session ID
amount	string	Amount
currency	string	Currency code
description	string	Payment description
items	array[string]	Product/service names
mode	string	Checkout mode
price_id	string	Price ID for subscriptions
customer_id	string	Customer ID
return_url	string	Redirect URL
gateway_account_id	string	Connected gateway account ID
merchant_name	string	Merchant name from API keys table

Response Example¶

{
    "id": "sess_1a2b3c4d5e6f",
    "amount": "99.99",
    "currency": "USD",
    "description": "Premium subscription",
    "items": ["Premium Plan"],
    "mode": "payment",
    "price_id": null,
    "customer_id": null,
    "return_url": "https://yoursite.com/success",
    "gateway_account_id": "acct_abc123",
    "merchant_name": "My Store"
}

Create Payment Intent¶

Creates a PaymentIntent securely using a predefined session_id. No API key required here because the session is already securely bound to a merchant.

POST /v1/payments/intent

Request Body¶

Field	Type	Required	Description
session_id	string	Yes	The secure checkout session ID

Request Example¶

cURLPythonJavaScript

curl -X POST 'https://api.4geeks.io/v1/payments/intent' \
  -H 'Content-Type: application/json' \
  -d '{
    "session_id": "sess_1a2b3c4d5e6f"
  }'

import requests

response = requests.post(
    'https://api.4geeks.io/v1/payments/intent',
    json={'session_id': 'sess_1a2b3c4d5e6f'}
)
print(response.json())

const response = await fetch('https://api.4geeks.io/v1/payments/intent', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({session_id: 'sess_1a2b3c4d5e6f'})
});
const data = await response.json();
console.log(data);

Response (201 Created)¶

Field	Type	Description
client_secret	string	PaymentIntent client_secret. Pass this to the client SDK on the frontend
payment_intent_id	string	The unique PaymentIntent ID
amount	string	Amount
currency	string	Currency code

Response Example¶

{
    "client_secret": "pi_1a2b3c_secret_4d5e6f",
    "payment_intent_id": "pi_1a2b3c4d5e6f",
    "amount": "99.99",
    "currency": "USD"
}

Create Subscription (via Payment Intent)¶

Creates a Subscription securely using a predefined session_id. Returns the client_secret of the first invoice’s PaymentIntent.

POST /v1/payments/subscription

Request Body¶

Field	Type	Required	Description
session_id	string	Yes	The secure checkout session ID

Request Example¶

cURLPythonJavaScript

curl -X POST 'https://api.4geeks.io/v1/payments/subscription' \
  -H 'Content-Type: application/json' \
  -d '{
    "session_id": "sess_1a2b3c4d5e6f"
  }'

import requests

response = requests.post(
    'https://api.4geeks.io/v1/payments/subscription',
    json={'session_id': 'sess_1a2b3c4d5e6f'}
)
print(response.json())

const response = await fetch('https://api.4geeks.io/v1/payments/subscription', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({session_id: 'sess_1a2b3c4d5e6f'})
});
const data = await response.json();
console.log(data);

Response (201 Created)¶

Same schema as Create Payment Intent.

Create Payment¶

Creates a Hosted Checkout Session request.

POST /v1/payments/

Request Body¶

Field	Type	Required	Description
amount	string	Yes	Total amount to charge (decimal format, e.g., 99.99)
description	string	Yes	A description of the payment or service
currency	string	Yes	A valid currency code ISO-4217, e.g. USD, CAD, CRC, EUR
items	array[string]	Yes	Name(s) of product(s) or service(s)
return_url	string	Yes	URL to redirect after payment completion

Request Example¶

cURLPythonJavaScript

curl -X POST 'https://api.4geeks.io/v1/payments/' \
  -H 'X-Api-Key: sk_test_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": "49.99",
    "description": "Monthly plan",
    "currency": "USD",
    "items": ["Monthly Subscription"],
    "return_url": "https://yoursite.com/thank-you"
  }'

import requests

response = requests.post(
    'https://api.4geeks.io/v1/payments/',
    headers={'X-Api-Key': 'sk_test_your_api_key_here'},
    json={
        'amount': '49.99',
        'description': 'Monthly plan',
        'currency': 'USD',
        'items': ['Monthly Subscription'],
        'return_url': 'https://yoursite.com/thank-you'
    }
)
print(response.json())

const response = await fetch('https://api.4geeks.io/v1/payments/', {
    method: 'POST',
    headers: {
        'X-Api-Key': 'sk_test_your_api_key_here',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        amount: '49.99',
        description: 'Monthly plan',
        currency: 'USD',
        items: ['Monthly Subscription'],
        return_url: 'https://yoursite.com/thank-you'
    })
});
const data = await response.json();
console.log(data);

Response (202 Accepted)¶

Field	Type	Description
code	integer	HTTP status code (default: 202)
title	string	Response title (default: “Action required”)
content	string	Response message (default: “Show the checkout page to complete payment.”)
data	object	Payment data object
data.id_payment	string	Payment ID
data.redirect	string	Redirect URL for checkout

Response Example¶

{
    "code": 202,
    "title": "Action required",
    "content": "Show the checkout page to complete payment.",
    "data": {
        "id_payment": "pay_7g8h9i0j1k2l",
        "redirect": "https://checkout.4geeks.io/pay/pay_7g8h9i0j1k2l"
    }
}

List Payments¶

Retrieve details of payments with pagination.

GET /v1/payments/

Query Parameters¶

Parameter	Type	Required	Default	Description
status	string	No	-	Filter by payment status
test	boolean	No	-	Filter by test mode
limit	integer	No	10	Number of results per page
offset	integer	No	0	Number of results to skip

Request Example¶

cURLPythonJavaScript

curl -X GET 'https://api.4geeks.io/v1/payments/?status=completed&limit=5' \
  -H 'X-Api-Key: sk_test_your_api_key_here'

import requests

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

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

Response (200 OK)¶

Array of PaymentResponse objects.

Field	Type	Description
id	string	The unique payment ID
amount	string	Amount
currency	string	Currency code
description	string	Payment description
status	string	Payment status
items	array[string]	Product/service names
customer_email	string	Customer email
return_url	string	Redirect URL
payment_method	string	Payment method (default: “card”)
card_last4	string	Last 4 digits of card
card_brand	string	Card brand
created_at	string (datetime)	Creation timestamp
updated_at	string (datetime)	Update timestamp
test	boolean	Test mode flag (default: true)

Response Example¶

[
    {
        "id": "pay_7g8h9i0j1k2l",
        "amount": "49.99",
        "currency": "USD",
        "description": "Monthly plan",
        "status": "completed",
        "items": ["Monthly Subscription"],
        "customer_email": "customer@example.com",
        "return_url": "https://yoursite.com/thank-you",
        "payment_method": "card",
        "card_last4": "4242",
        "card_brand": "visa",
        "created_at": "2026-04-25T10:30:00Z",
        "updated_at": "2026-04-25T10:31:00Z",
        "test": true
    }
]

Get Payment¶

Retrieve details of a specific payment transaction by its ID.

GET /v1/payments/{id}

Path Parameters¶

Parameter	Type	Required	Description
id	string	Yes	The payment ID

Request Example¶

cURLPythonJavaScript

curl -X GET 'https://api.4geeks.io/v1/payments/pay_7g8h9i0j1k2l' \
  -H 'X-Api-Key: sk_test_your_api_key_here'

import requests

response = requests.get(
    'https://api.4geeks.io/v1/payments/pay_7g8h9i0j1k2l',
    headers={'X-Api-Key': 'sk_test_your_api_key_here'}
)
print(response.json())

const response = await fetch('https://api.4geeks.io/v1/payments/pay_7g8h9i0j1k2l', {
    headers: {'X-Api-Key': 'sk_test_your_api_key_here'}
});
const data = await response.json();
console.log(data);

Response (200 OK)¶

Same schema as List Payments (single object).

Response Example¶

{
    "id": "pay_7g8h9i0j1k2l",
    "amount": "49.99",
    "currency": "USD",
    "description": "Monthly plan",
    "status": "completed",
    "items": ["Monthly Subscription"],
    "customer_email": "customer@example.com",
    "return_url": "https://yoursite.com/thank-you",
    "payment_method": "card",
    "card_last4": "4242",
    "card_brand": "visa",
    "created_at": "2026-04-25T10:30:00Z",
    "updated_at": "2026-04-25T10:31:00Z",
    "test": true
}

List Payments Internal¶

Retrieve a paginated list of all payments (Internal use).

GET /v1/payments/internal

Query Parameters¶

Same as List Payments.

Request Example¶

cURLPythonJavaScript

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

import requests

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

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

Response (200 OK)¶

Same schema as List Payments.

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 questions? Ask the community or explore tutorials