API Pagamenti

🤖 Spiega con l'intelligenza artificiale

L’API Pagamenti è uno strumento di elaborazione dei pagamenti che consente alle aziende di accettare ed elaborare pagamenti online in modo sicuro ed efficiente. Con questa API, le aziende possono integrare le funzionalità di elaborazione dei pagamenti nei propri siti web, applicazioni e altre soluzioni software.

Supporta i principali metodi di pagamento, tra cui carte di credito, carte di debito e portafogli digitali. Fornisce inoltre funzionalità come l’elaborazione dei pagamenti in tempo reale, la conversione automatica della valuta e la prevenzione delle frodi.

Tutte le richieste di addebito richiedono per impostazione predefinita il 3DS alla banca del titolare della carta.

Creare una richiesta di pagamento¶

Endpoint

POST /v1/payments/

Questo endpoint crea una singola pagina di fatturazione sicura, basata sui seguenti parametri. Tieni presente che devi indirizzare il titolare della carta a una pagina generata, dove inserirà i dati del metodo di pagamento. Invieremo la risposta della transazione all’indirizzo return_url.

Campi:

Parametro	Descrizione	Tipo	Obbligatorio
`amount`	Importo totale da addebitare (formato decimale, es. 99.99)	string	true
`description`	Una descrizione del pagamento o del servizio	string	true
`currency`	Un codice valuta ISO-4217 valido, ad esempio `USD`, `CAD`, `CRC`, `EUR`.	string	true
`items`	Nome/i del/i prodotto/i o servizio/i. È solo un’etichetta informativa.	array	true
`return_url`	Verrai reindirizzato a questo URL dopo il completamento del pagamento con `id_payment` concatenato come parametro di query, in modo da poter consultare lo stato della transazione.	string	true

Esempio di richiesta:

cURLPythonJavaScriptAngular

curl -X POST 'https://api.4geeks.io/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"
}'

import requests
from requests.auth import HTTPBasicAuth

api_key = "sk_test_51O62xYzAbcDef123"
response = requests.post(
    'https://api.4geeks.io/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())

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

fetch("https://api.4geeks.io/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));

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("https://api.4geeks.io/v1/payments/", payload, { headers })
    .subscribe((data) => console.log(data));

Risposta (202 Accepted):

{
    "code": 202,
    "title": "Azione richiesta",
    "content": "Mostra la pagina di checkout per completare il pagamento.",
    "data": {
        "id_payment": "pay_1ABC123XYZ456",
        "redirect": "https://console.4geeks.io/checkout/?data=eyJyZXR1cm5fdXJsIjogImh0dHA6Ly9leGFtcGxlLmNvbS9wYXltZW50LXJlc3VsdCIsICJ0ZXN0IjogdHJ1ZSwgImhhc19jdXN0b21lciI6IGZhbHNlLCAiY29tcGFueV9lbWFpbCI6ICJzdXBwb3J0QDRnZWVrcy5pbyIsICJwcm9kdWN0IjogeyJ0b3RhbF9wcmljZSI6IDUwMC4wMCwgInByaWNlIjogNTAwLjAwLCAiY3VycmVuY3kiOiAiVVNEIiwgIm5hbWUiOiAiUHJlbWl1bSBzcWJzY3JpcHRpb24gcGF5bWVudCIsICJkZXNjcmlwdGlvbiI6IFsiUHJlbWl1bSBQbGFuIC0gTW9udGhseSJdfSwgInN0YXRlbWVudF9kZXNjcmlwdG9yIjogWyI0R0VFS1MiXSwgImNvbXBhbnlfbmFtZSI6ICI0R2Vla3MgUGF5bWVudHMifQ=="
    }
}

Ottenere un pagamento¶

Endpoint

GET /v1/payments/{id}

Recupera i dettagli di una specifica transazione di pagamento tramite il suo ID. Questo endpoint restituisce le informazioni complete sulla transazione, inclusi stato, importo, valuta, dettagli del cliente e informazioni sul metodo di pagamento.

Parametri di percorso:

Parametro	Descrizione	Tipo	Obbligatorio
`id`	ID pagamento univoco (es. `pay_1ABC123XYZ456`)	string	true

Parametri di query:

Parametro	Descrizione	Tipo	Obbligatorio
`test`	Filtra per modalità test (true/false)	boolean	false

Esempio di richiesta:

curl -X GET 'https://api.4geeks.io/v1/payments/pay_1ABC123XYZ456' \
  -u "sk_test_51O62xYzAbcDef123:" \
  -H 'Accept: application/json'

Risposta (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
}

Risposta di errore (404 Not Found):

{
    "code": 404,
    "title": "Pagamenti non trovati",
    "content": "Sono stati riscontrati errori durante la ricerca, per favore verifica i dati.",
    "type": "danger"
}

Ottenere tutti i pagamenti¶

Endpoint

GET /v1/payments/internal

Recupera un elenco paginato di tutti i pagamenti. Supporta opzioni di filtraggio e ordinamento.

Parametri di query:

Parametro	Descrizione	Tipo	Obbligatorio
`status`	Filtra per stato pagamento (es. `succeeded`)	string	false
`test`	Filtra per modalità test (true/false)	boolean	false

Esempio di richiesta:

curl -X GET 'https://api.4geeks.io/v1/payments/?status=succeeded&test=false' \
  -u "sk_test_51O62xYzAbcDef123:" \
  -H 'Accept: application/json'

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

Gestione degli errori¶

L’API restituisce codici di stato HTTP standard per indicare il successo o il fallimento di una richiesta. Di seguito sono riportati gli errori comuni specifici dell’API Pagamenti:

Codice di stato	Tipo di errore	Descrizione
400	Bad Request	Campi obbligatori mancanti o formato importo/valuta non valido.
401	Unauthorized	Autenticazione con chiave API mancante o non valida.
402	Payment Required	Metodo di pagamento rifiutato o fondi insufficienti.
404	Not Found	L’ID del pagamento non esiste.
409	Conflict	Richiesta di pagamento duplicata (controllo idempotenza).
500	Server Error	Errore imprevisto del server durante l’elaborazione del pagamento.

Esempio: Non autorizzato (401)

{
    "detail": "Formato della chiave API non valido."
}

Esempio: Pagamento fallito (402)

{
    "error": {
        "code": 402,
        "type": "payment_failed",
        "message": "Carta rifiutata. Per favore prova un altro metodo di pagamento.",
        "decline_reason": "fondi_insufficienti"
    }
}

Problemi comuni e risoluzione¶

Problema: 401 Unauthorized

Verifica che la tua chiave API sia corretta e non sia stata ruotata di recente
Assicurati che l’header Basic Auth includa i due punti finali (:)
Controlla che il tipo di chiave (test/live) corrisponda al tuo ambiente

Hai ancora domande? Richiedi supporto..
Check out the changelog.