API Link di Pagamento

🤖 Spiega con l'intelligenza artificiale

L’API Link di Pagamento aiuta le aziende a generare e personalizzare link di pagamento con dettagli specifici come l’importo del pagamento, la valuta, la descrizione e le informazioni sul cliente.

Una volta generato il link di pagamento, le aziende possono condividerlo con i propri clienti via email, social media o altri canali di comunicazione. Quando il cliente clicca sul link, viene indirizzato a una pagina di elaborazione del pagamento dove può inserire i propri dettagli di pagamento e completare la transazione.

Creare un nuovo link di pagamento¶

Endpoint

POST /v1/payment-links/

Questo endpoint consente di creare uno o più link di pagamento per clienti specifici o senza dettagli del cliente.

Parametri di query:

Parametro	Descrizione	Tipo	Obbligatorio
test	Indica se il link di pagamento è in modalità test	boolean	false

Campi del corpo della richiesta:

Parametro	Descrizione	Tipo	Obbligatorio
description	Descrizione del pagamento	string	true
amount	Importo del pagamento (minimo equivalente a USD $1.00)	decimal	true
currency	Codice valuta (default: USD)	string	false
customers	Array di oggetti cliente o ID cliente	array	false

Campi dell’oggetto cliente (se si forniscono nuovi clienti):

Parametro	Descrizione	Tipo	Obbligatorio
id	UUID cliente esistente	string	false
customer	ID cliente alternativo	string	false
first_name	Nome del cliente	string	false*
last_name	Cognome del cliente	string	false*
email	Indirizzo email del cliente	string	false*

*Richiesti insieme se non si fornisce id o customer

Richiesta (Creazione singolo link di pagamento):

curl -X POST 'https://api.4geeks.io/v1/payment-links/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -H 'Content-Type: application/json' \
     -d '{
           "description": "Premium Subscription 1 Year",
           "amount": 99.99,
           "currency": "USD",
           "customers": []
         }'

Richiesta (Creazione link di pagamento per più clienti):

curl -X POST 'https://api.4geeks.io/v1/payment-links/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -H 'Content-Type: application/json' \
     -d '{
           "description": "Product License",
           "amount": 49.99,
           "currency": "USD",
           "customers": [
             {
               "id": "550e8400-e29b-41d4-a716-446655440000"
             },
             {
               "first_name": "John",
               "last_name": "Doe",
               "email": "john.doe@example.com"
             }
           ]
         }'

Risposta (201 Created - Singolo link):

{
    "code": 201,
    "title": "Link di pagamento creato",
    "content": "Il link di pagamento è stato creato correttamente.",
    "type": "success",
    "data": {
        "id": "b3196f0b-bcba-46bc-b833-0bc845007c89",
        "link": "http://localhost:4200/pl/b3196f0b-bcba-46bc-b833-0bc845007c89"
    }
}

Risposta (201 Created - Più link):

{
    "code": 201,
    "title": "Link di pagamento creato",
    "content": "I link di pagamento sono stati creati correttamente.",
    "type": "success",
    "data": [
        {
            "id": "987f6543-b21c-43d8-a567-123456789abc",
            "customer": "550e8400-e29b-41d4-a716-446655440000",
            "customer_name": "Alex Miller",
            "link": "http://localhost:3000/pl/987f6543-b21c-43d8-a567-123456789abc"
        },
        {
            "id": "aabbccdd-1122-3344-5566-77889900aabb",
            "customer": "650f9501-f40c-52e5-c827-557766551111",
            "customer_name": "John Doe",
            "link": "http://localhost:3000/pl/aabbccdd-1122-3344-5566-77889900aabb"
        }
    ]
}

Ottenere tutti i link di pagamento¶

Endpoint

GET /v1/payment-links/

Questo endpoint recupera tutti i link di pagamento per il tuo account con supporto alla paginazione.

Parametri di query:

Parametro	Descrizione	Tipo	Obbligatorio
page	Numero di pagina per la paginazione	integer	false
test	Filtra per modalità test (true/false)	boolean	false

Richiesta:

curl -X GET 'https://api.4geeks.io/v1/payment-links/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Richiesta (Con paginazione):

curl -X GET 'https://api.4geeks.io/v1/payment-links/?page=1' \
     -u 'sk_test_51O62xYzAbcDef123:'

Risposta (200 OK):

{
    "count": 15,
    "next": "https://api.4geeks.io/v1/payment-links/?page=2",
    "previous": null,
    "results": [
        {
            "id": "aabbccdd-1122-3344-5566-77889900aabb",
            "description": "Premium Subscription 1 Year",
            "amount": "99.99",
            "currency": "USD",
            "payment_link": true,
            "active": true,
            "recurring": false,
            "next_date_of_payment": null,
            "status": "pending",
            "test": false,
            "created_on": "2025-12-04T10:30:00Z"
        },
        {
            "id": "ccddee11-2233-4455-6677-88990011aabb",
            "description": "Product License",
            "amount": "49.99",
            "currency": "USD",
            "payment_link": true,
            "active": true,
            "recurring": false,
            "next_date_of_payment": null,
            "status": "pending",
            "test": false,
            "created_on": "2025-12-03T15:45:00Z"
        }
    ]
}

Ottenere un link di pagamento specifico¶

Endpoint

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

Questo endpoint recupera i dettagli completi di uno specifico link di pagamento tramite il suo ID.

Parametri di percorso:

Parametro	Descrizione	Tipo	Obbligatorio
id	L’identificatore univoco di un link di pagamento	string	true

Richiesta:

curl -X GET 'https://api.4geeks.io/v1/payment-links/aabbccdd-1122-3344-5566-77889900aabb/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Risposta (200 OK):

{
    "id": "b3196f0b-bcba-46bc-b833-0bc845007c89",
    "description": "Premium Subscription 1 Year",
    "amount": 99.99,
    "currency": "USD",
    "payment_link": true,
    "active": true,
    "recurring": false,
    "next_date_of_payment": null,
    "status": "pending",
    "test": false,
    "created_on": "2025-12-04T22:56:39.903352Z",
    "payment_logs": []
}

Aggiornare un link di pagamento¶

Endpoint

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

Aggiorna un link di pagamento esistente con nuovi dettagli.

Parametri di percorso:

Parametro	Descrizione	Tipo	Obbligatorio
id	L’identificatore univoco di un link di pagamento	string	true

Campi del corpo della richiesta (tutti opzionali):

Parametro	Descrizione	Tipo	Obbligatorio
product	L’ID del prodotto associato	string	false
customer	L’ID del cliente (o null per rimuoverlo)	string	false
active	Se il link di pagamento è attivo	boolean	false
recurring	Determina se il link di pagamento è ricorrente	boolean	false
next_date_of_payment	Prossima data di pagamento programmata (YYYY-MM-DD HH:MM:SS)	string	false
status	Lo stato attuale del link	string	false
test	Se true, il link è in modalità test; false per produzione	boolean	false

Valori di stato validi:

pending - In attesa di pagamento
paid - Pagamento completato
paid_period - Pagamento del periodo completato
pending_period - Pagamento del periodo in attesa
cancelled / canceled - Link annullato
defaulter - Pagamento scaduto
active - Il link è attivo
inactive - Il link è inattivo

Richiesta:

curl -X PUT 'https://api.4geeks.io/v1/payment-links/aabbccdd-1122-3344-5566-77889900aabb/' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -H 'Content-Type: application/json' \
     -d '{
           "active": true,
           "status": "pending",
           "recurring": false,
           "customer": null
         }'

Risposta (200 OK):

{
    "code": 200,
    "title": "Link di pagamento aggiornato",
    "content": "Il link di pagamento è stato aggiornato con successo.",
    "type": "success"
}

Risposta (400 Bad Request - Stato non valido):

{
    "code": 400,
    "title": "Stato non valido",
    "content": "Lo stato specificato non è valido.",
    "type": "error"
}

Eliminare un link di pagamento¶

Endpoint

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

Elimina uno specifico link di pagamento.

Parametri di percorso:

Parametro	Descrizione	Tipo	Obbligatorio
id	L’identificatore univoco di un link di pagamento	string	true

Richiesta:

curl -X DELETE 'https://api.4geeks.io/v1/payment-links/aabbccdd-1122-3344-5566-77889900aabb/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Risposta (200 OK):

{
    "code": 200,
    "title": "Eliminato",
    "content": "Il link di pagamento è stato rimosso con successo.",
    "type": "success"
}

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 per i link di pagamento:

400 Bad Request¶

Si verifica quando la richiesta è malformata o mancano campi obbligatori.

Scenari:

Scenario	Messaggio di errore	Soluzione
Descrizione mancante	`"Non hai fornito una descrizione per il pagamento."`	Includi il campo `description`
Importo mancante	`"Non hai fornito un prezzo per il pagamento."`	Includi il campo `amount`
Importo sotto il minimo	`"L'importo è pari a $X USD, che è inferiore al minimo di $1.00 USD"`	Aumenta l’importo ad almeno l’equivalente di $1.00 USD
Dati cliente non validi	`"Non hai fornito nome, cognome e email o un ID cliente."`	Fornisci un ID cliente esistente o i dettagli completi del cliente
Formato data non valido	`"Il formato della data deve essere YYYY-MM-DD HH:MM:SS"`	Usa il formato: `2025-12-25 14:30:00`
Stato non valido	`"Lo stato specificato non è valido."`	Usa uno stato valido: pending, paid, cancelled, ecc.

Esempio di risposta di errore:

{
    "code": 406,
    "title": "Dati mancanti",
    "content": "Non hai fornito una descrizione per il pagamento.",
    "type": "danger"
}

401 Unauthorized¶

Autenticazione fallita. La chiave API non è valida, è mancante o è formattata male.

Esempio:

{
    "detail": "Le credenziali di autenticazione non sono state fornite."
}

Soluzione:

Verifica di aver incluso il parametro -u 'sk_test_...: o l’header Authorization: Basic
Assicurati che la tua chiave API sia corretta e attiva
Testa con Postman utilizzando Basic Auth

404 Not Found¶

Il link di pagamento richiesto non esiste.

Esempio:

{
    "code": 404,
    "title": "Link di pagamento non trovato",
    "content": "Non è stato possibile trovare il link di pagamento, per favore controlla l'ID.",
    "type": "danger"
}

Soluzione:

Verifica che l’ID del link di pagamento esista
Usa l’endpoint di elenco per trovare l’ID del link di pagamento corretto
Assicurati che il link di pagamento appartenga al tuo account sviluppatore

Note importanti¶

Validazione del link di pagamento

L’importo deve essere almeno l’equivalente di USD $1.00
La descrizione è obbligatoria
I link non possono essere modificati una volta pagati

Informazioni sul cliente

I link di pagamento possono essere creati con o senza informazioni sul cliente
Quando crei link per clienti esistenti, fornisci il loro UUID
Quando crei link per nuovi clienti, fornisci first_name, last_name e email

Stato del pagamento

I link di pagamento iniziano nello stato pending
Lo stato si aggiorna automaticamente in base all’attività di pagamento
I link ricorrenti passano a paid_period dopo il pagamento

Test vs Produzione

Usa la tua Chiave di Test (sk_test_...) per lo sviluppo e il testing
Usa la tua Chiave Live (sk_live_...) per le transazioni reali
Il parametro di query ?test=true o ?test=false controlla la modalità
Il sistema rileva automaticamente la modalità in base alla Chiave API utilizzata

Migliori pratiche¶

Includi descrizioni chiare - Aiuta i clienti a capire cosa stanno pagando
Usa la valuta corretta - Adattala alla tua regione aziendale e alle aspettative dei clienti
Imposta importi minimi - Assicurati che gli importi siano almeno l’equivalente di $1.00 USD
Assegna i clienti - Collega i pagamenti ai record dei clienti per un tracciamento migliore
Monitora i log dei pagamenti - Usa i log dei pagamenti per riconciliare le transazioni
Aggiorna lo stato in modo appropriato - Mantieni lo stato del link di pagamento sincronizzato con lo stato effettivo del pagamento
Testa prima della produzione - Usa la modalità test con le chiavi API di test per la validazione

Risoluzione dei problemi¶

Problema: “L’importo è inferiore al minimo”¶

Causa: L’importo del pagamento è inferiore all’equivalente di USD $1.00
Soluzione:

Aumenta il campo amount ad almeno 1.00
Verifica la conversione di valuta se utilizzi una valuta diversa da USD

Problema: “Non hai fornito una descrizione”¶

Causa: Campo obbligatorio description mancante
Soluzione:

Includi un titolo chiaro e descrittivo per il pagamento
Esempio: “Abbonamento Premium”, “Licenza Prodotto”, “Commissione Servizio”

Problema: “Non hai fornito nome, cognome e email o un ID cliente”¶

Causa: Informazioni sul cliente incomplete
Soluzione:

Fornisci un ID cliente esistente nell’array customers
Oppure fornisci i dettagli completi del cliente: first_name, last_name e email

Problema: “Lo stato specificato non è valido”¶

Causa: Valore di stato fornito non valido
Soluzione:

Usa solo valori di stato validi: pending, paid, paid_period, pending_period, cancelled, canceled, defaulter, active, inactive
Controlla la documentazione per le definizioni degli stati

Problema: “Link di pagamento non trovato”¶

Causa: L’ID del link di pagamento non esiste o appartiene a un diverso account sviluppatore
Soluzione:

Verifica l’ID del link di pagamento utilizzando l’endpoint di elenco
Assicurati di utilizzare la chiave API corretta
Controlla che il link di pagamento non sia stato eliminato

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