Vai al contenuto

Come accettare pagamenti con carta di credito sul tuo sito web utilizzando l'API 4Geeks Payments

🤖 Spiega con l'intelligenza artificiale

L’API 4Geeks Payments consente agli sviluppatori di creare esperienze di checkout completamente personalizzabili. Che tu gestisca un semplice negozio di e-commerce o una complessa piattaforma SaaS, questa API ti consente di elaborare transazioni con carte di credito, carte di debito e portafogli digitali direttamente dalla tua applicazione.

Questa guida fornisce una procedura dettagliata per l’integrazione dell’API Payments, garantendo un’elaborazione delle transazioni sicura ed efficiente.

Prerequisiti

Prima di scrivere qualsiasi codice, assicurati di avere quanto segue pronto:

  • Account 4Geeks verificato: Devi avere accesso alla 4Geeks Console.
  • Servizio Payments attivo: Assicurati che il modulo Payments sia abilitato nelle impostazioni del tuo account.
  • Credenziali API: Avrai bisogno del tuo Client ID e Client Secret (o chiavi API) dalla dashboard per sviluppatori.
  • Certificato SSL: Il tuo sito web deve servire contenuti tramite HTTPS per gestire in modo sicuro i dati delle transazioni.

Istruzioni passo-passo

Segui questi passaggi per elaborare un addebito di pagamento standard utilizzando l’API.

Passaggio 1: Ottieni le tue credenziali API

Per comunicare con l’API, devi prima recuperare le tue credenziali sicure.

  1. Accedi alla 4Geeks Console.
  2. Vai a Settings > API Keys nel menu laterale.
  3. Individua il tuo Client ID e Client Secret.

Suggerimento: Vedrai due serie di chiavi: “Test” e “Live”. Usa sempre le chiavi di test durante lo sviluppo per simulare le transazioni senza spostare denaro reale. Passa alle chiavi Live solo quando sei pronto per il lancio.

Passaggio 2: Genera un Access Token

L’API 4Geeks utilizza l’autenticazione Bearer Token. Devi scambiare le tue credenziali con un token di accesso temporaneo prima di effettuare richieste di pagamento.

Endpoint: POST /oauth/token

Corpo della richiesta: 

    {
        "client_id": "IL_TUO_CLIENT_ID",
        "client_secret": "IL_TUO_CLIENT_SECRET",
        "grant_type": "client_credentials"
    }

Risposta: L’API restituirà un oggetto JSON contenente un access_token. Utilizzerai questo token nell’intestazione delle tue richieste successive.

Passaggio 3: Crea un addebito di pagamento

Ora che sei autenticato, puoi avviare una transazione. Questa richiesta invia i dettagli del pagamento a 4Geeks per l’elaborazione.

Endpoint: POST /v1/payments/

Intestazioni:

  • Authorization: Bearer <IL_TUO_ACCESS_TOKEN>
  • Content-Type: application/json

Parametri del corpo:

  • amount: Il costo totale (ad es. 150.00).
  • currency: Il codice ISO a 3 lettere (ad es. USD, EUR).
  • description: Un breve riepilogo dell’acquisto.
  • return_url: L’URL a cui verrà reindirizzato il cliente dopo il processo di pagamento (essenziale per i flussi 3D Secure).

Esempio di richiesta:

{
  "amount": 150.00,
  "currency": "USD",
  "description": "Abbonamento Premium Annuale",
  "return_url": "[https://tuo-sito.it/checkout/successo](https://tuo-sito.it/checkout/successo)"
}

Passaggio 4: Gestisci la risposta

L’API restituirà immediatamente lo stato della transazione.

  • Successo: Se lo stato è succeeded o approved, il pagamento è completo. Dovresti mostrare un messaggio di successo all’utente e aggiornare il tuo database.
  • Azione richiesta: Se lo stato è action_required (comune con 3D Secure), la risposta includerà un redirect_url. Devi reindirizzare il cliente a questo URL per completare la verifica bancaria.

Casi d’uso comuni

1. Checkout E-commerce

Un cliente aggiunge articoli al carrello e clicca su “Checkout”. Il tuo backend calcola il totale e chiama l’endpoint /v1/payments/. Dopo una risposta positiva, attivi il tuo sistema di inventario (magari gestito da 4Geeks Asset) per detrarre le scorte e inviare un’email di conferma.

2. Fatturazione dell’abbonamento SaaS

Per un servizio software mensile, puoi tokenizzare la carta di un cliente durante il primo pagamento. Puoi quindi utilizzare quel token per automatizzare addebiti futuri tramite l’API senza chiedere all’utente di reinserire i propri dettagli ogni mese. Questo si integra perfettamente con le funzionalità di fatturazione ricorrente di 4Geeks Payments.

Risoluzione dei problemi

Ecco le soluzioni agli errori comuni che potresti incontrare durante l’integrazione:

  • Errore 401 Unauthorized:
  • Causa: Il tuo Bearer Token è mancante, errato o scaduto.

  • Soluzione: Rigenera un nuovo token utilizzando l’endpoint /oauth/token e assicurati che sia incluso correttamente nell’intestazione Authorization.

  • Transazione rifiutata (Errore generico):

  • Causa: L’emittente della carta ha rifiutato la transazione (ad es. fondi insufficienti).

  • Soluzione: Controlla l’error_code nella risposta API. Se sei in modalità test, assicurati di utilizzare i numeri di carta di prova validi forniti nella documentazione.

  • Errore CORS:

  • Causa: Stai tentando di effettuare chiamate API direttamente dal browser (lato client).
  • Soluzione: Per sicurezza, non esporre mai il tuo Client Secret nel codice frontend. Indirizza sempre le richieste di pagamento tramite il tuo server backend.

Conclusione

L’integrazione dell’API 4Geeks Payments ti offre il pieno controllo sui tuoi flussi di pagamento, consentendo un’esperienza sicura e personalizzata per i tuoi utenti. Seguendo questi passaggi, puoi iniziare ad accettare carte di credito in modo sicuro ed efficiente.

Per configurazioni più avanzate, come il salvataggio delle carte per un uso futuro o la gestione dei webhook, visita la 4Geeks Console o esplora la nostra documentazione per sviluppatori.

Risorse aggiuntive