Payments API

🤖 Explain with AI

Payments API is a payment processing tool that allows businesses to accept and process online payments securely and efficiently. With this API, businesses can integrate payment processing functionalities into their websites, applications, and other software solutions.

It supports major payment methods, including credit cards, debit cards, and digital wallets. It also provides features such as real-time payment processing, automatic currency conversion, and fraud prevention.

All charges request 3DS to cardholder’s bank by default.

Create a payment request¶

Endpoint

POST /v1/payments/

This endpoint builds a single secure billing page, based on the following parameters. Please note that you must direct the cardholder to a generated page, where they will enter payment method data. We will send the transaction response to return_url.

Fields:

Parameter	Description	Type	Required
`amount`	Total amount to charge (decimal format, e.g., 99.99)	string	true
`description`	A description of the payment or service	string	true
`currency`	A valid currency code ISO-4217, for example `USD`, `CAD`, `CRC`, `EUR`.	string	true
`items`	Name(s) of product(s) or service(s). It’s an informational label only.	array	true
`return_url`	We’ll redirect to this URL after payment completion with `id_payment` concatenated as a query parameter, so you can consult the transaction status.	string	true

Request Example:

cURL

curl -X POST 'http://127.0.0.1:8000/v1/payments/' \
  -u "sk_test_51O62xYzAbcDef123:" \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": "500.00",
    "description": "Premium subscription payment",
    "currency": "USD",
    "items": ["Premium Plan - Monthly"],
    "return_url": "https://example.com/payment-result"
  }'

Python

import requests
from requests.auth import HTTPBasicAuth

api_key = "sk_test_51O62xYzAbcDef123"
response = requests.post(
    'http://127.0.0.1:8000/v1/payments/',
    auth=HTTPBasicAuth(api_key, ""),
    json={
        "amount": "500.00",
        "description": "Premium subscription payment",
        "currency": "USD",
        "items": ["Premium Plan - Monthly"],
        "return_url": "https://example.com/payment-result"
    }
)
print(response.json())

JavaScript

const apiKey = "sk_test_51O62xYzAbcDef123";
const credentials = Buffer.from(`${apiKey}:`).toString("base64");

fetch("http://127.0.0.1:8000/v1/payments/", {
    method: "POST",
    headers: {
        Authorization: `Basic ${credentials}`,
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        amount: "500.00",
        description: "Premium subscription payment",
        currency: "USD",
        items: ["Premium Plan - Monthly"],
        return_url: "https://example.com/payment-result",
    }),
})
    .then((res) => res.json())
    .then((data) => console.log(data));

Angular

import { HttpClient, HttpHeaders } from "@angular/common/http";

const apiKey = "sk_test_51O62xYzAbcDef123";
const credentials = btoa(`${apiKey}:`);

const headers = new HttpHeaders({
    Authorization: `Basic ${credentials}`,
    "Content-Type": "application/json",
});

const payload = {
    amount: "500.00",
    description: "Premium subscription payment",
    currency: "USD",
    items: ["Premium Plan - Monthly"],
    return_url: "https://example.com/payment-result",
};

this.http
    .post("http://127.0.0.1:8000/v1/payments/", payload, { headers })
    .subscribe((data) => console.log(data));

Postman

Method: POST
URL: http://127.0.0.1:8000/v1/payments/
Authorization: Basic Auth with username sk_test_51O62xYzAbcDef123 and password empty
Body (raw JSON):

{
    "amount": "500.00",
    "description": "Premium subscription payment",
    "currency": "USD",
    "items": ["Premium Plan - Monthly"],
    "return_url": "https://example.com/payment-result"
}

Response (202 Accepted):

{
    "code": 202,
    "title": "Action required",
    "content": "Show the checkout page to complete payment.",
    "data": {
        "id_payment": "pay_1ABC123XYZ456",
        "redirect": "https://console.4geeks.io/checkout/?data=eyJyZXR1cm5fdXJsIjogImh0dHA6Ly9leGFtcGxlLmNvbS9wYXltZW50LXJlc3VsdCIsICJ0ZXN0IjogdHJ1ZSwgImhhc19jdXN0b21lciI6IGZhbHNlLCAiY29tcGFueV9lbWFpbCI6ICJzdXBwb3J0QDRnZWVrcy5pbyIsICJwcm9kdWN0IjogeyJ0b3RhbF9wcmljZSI6IDUwMC4wMCwgInByaWNlIjogNTAwLjAwLCAiY3VycmVuY3kiOiAiVVNEIiwgIm5hbWUiOiAiUHJlbWl1bSBzcWJzY3JpcHRpb24gcGF5bWVudCIsICJkZXNjcmlwdGlvbiI6IFsiUHJlbWl1bSBQbGFuIC0gTW9udGhseSJdfSwgInN0YXRlbWVudF9kZXNjcmlwdG9yIjogWyI0R0VFS1MiXSwgImNvbXBhbnlfbmFtZSI6ICI0R2Vla3MgUGF5bWVudHMifQ=="
    }
}

Get a payment¶

Endpoint

GET /v1/payments/{id}

Retrieve details of a specific payment transaction by its ID. This endpoint returns the complete transaction information including status, amount, currency, customer details, and payment method information.

Path Parameters:

Parameter	Description	Type	Required
`id`	The unique payment ID (e.g., `pay_1ABC123XYZ456`)	string	true

Query Parameters:

Parameter	Description	Type	Required
`test`	Filter by test mode (true/false)	boolean	false

Request Example:

curl -X GET 'http://127.0.0.1:8000/v1/payments/pay_1ABC123XYZ456' \
  -u "sk_test_51O62xYzAbcDef123:" \
  -H 'Accept: application/json'

Response (200 OK):

{
    "id": "pay_1ABC123XYZ456",
    "amount": "500.00",
    "currency": "USD",
    "description": "Premium subscription payment",
    "status": "completed",
    "items": ["Premium Plan - Monthly"],
    "customer_email": "customer@example.com",
    "return_url": "https://example.com/payment-result",
    "payment_method": "card",
    "card_last4": "4242",
    "card_brand": "visa",
    "created_at": "2025-12-04T10:30:00Z",
    "updated_at": "2025-12-04T10:35:00Z",
    "test": true
}

Error Response (404 Not Found):

{
    "code": 404,
    "title": "Payments not found",
    "content": "Errors were encountered during the search, please verify the data.",
    "type": "danger"
}

Get all payments¶

Endpoint

GET /v1/payments/internal

Retrieve a paginated list of all payments. Supports filtering and sorting options.

Query Parameters:

Parameter	Description	Type	Required
`status`	Filter by payment status (`succeeded`, etc.`)	string	false
`test`	Filter by test mode (true/false)	boolean	false

Request Example:

curl -X GET 'http://127.0.0.1:8000/v1/payments/?status=succeeded&test=false' \
  -u "sk_test_51O62xYzAbcDef123:" \
  -H 'Accept: application/json'

Response (200 OK):

[
    {
        "id": "7f277445-d4d0-47e2-bd6f-4664e4480778",
        "product": "981a34d7-729a-4240-a30a-c5819b0e4969",
        "customer": "5c35a9f5-cd2a-4bf5-a0e2-d946eedeefeb",
        "amount": 100.0,
        "fee": 5.5,
        "currency": "USD",
        "description": null,
        "statement_description": "JUANPESA",
        "status": "succeeded",
        "capture": true,
        "created_on": "2025-11-04T14:33:25.690012Z",
        "refund": null,
        "captured": null,
        "test": true,
        "card_last4": "",
        "card_exp_month": "",
        "card_exp_year": "",
        "card_country": "",
        "card_brand": "",
        "exchange_usd_to_payout": 0.0,
        "exchange_original_payout_to_usd": 0.0,
        "exchange_usd_to_local": 533.48,
        "exchange_original_local_to_usd": 1.0,
        "currency_local": "CRC",
        "net": 94.5,
        "net_currency": "USD"
    },
    {
        "id": "e7d9a0ea-58fb-45a0-8005-e2c314bcf3d1",
        "product": "981a34d7-729a-4240-a30a-c5819b0e4969",
        "customer": "9928c043-e480-4b77-aa31-88de9ae52e7c",
        "amount": 100.0,
        "fee": 5.5,
        "currency": "USD",
        "description": null,
        "statement_description": "JUANPESA",
        "status": "succeeded",
        "capture": true,
        "created_on": "2025-09-17T20:58:39.797400Z",
        "refund": null,
        "captured": null,
        "test": true,
        "card_last4": "",
        "card_exp_month": "",
        "card_exp_year": "",
        "card_country": "",
        "card_brand": "",
        "exchange_usd_to_payout": 0.0,
        "exchange_original_payout_to_usd": 0.0,
        "exchange_usd_to_local": 533.48,
        "exchange_original_local_to_usd": 1.0,
        "currency_local": "CRC",
        "net": 94.5,
        "net_currency": "USD"
    }
]

Error Handling¶

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

Status Code	Error Type	Description
400	Bad Request	Missing required fields or invalid amount/currency format.
401	Unauthorized	Missing or invalid API key authentication.
402	Payment Required	Payment method declined or insufficient funds.
404	Not Found	Payment ID does not exist.
409	Conflict	Duplicate payment request (idempotency check).
500	Server Error	Unexpected server error during payment processing.

Example: Unauthorized (401)

{
    "detail": "Invalid API key format."
}

Example: Payment Failed (402)

{
    "error": {
        "code": 402,
        "type": "payment_failed",
        "message": "Card declined. Please try another payment method.",
        "decline_reason": "insufficient_funds"
    }
}

Common Issues & Troubleshooting¶

Problem: 401 Unauthorized

Verify your API key is correct and not rotated recently
Ensure Basic Auth header includes the trailing colon (:)
Check that the key type (test/live) matches your environment

Login or signup into Console.
Check out the changelog.