Integrazione di pagamento personalizzata

Questo documento spiega come Monetization abilita il supporto all’elaborazione dei pagamenti per provider di terze parti non supportati out-of-the-box o per integrazioni personalizzate.

Categoria:

Sviluppo e integrazione

Argomenti in questo documento:

Elaborazione pagamenti di terze parti in Monetization
Elaborazione asincrona dei pagamenti
- Esportazione delle invoice
  - Exporting job - file CSV su SFTP
  - Metodo notification - webhook
- Importazione dei pagamenti
  - CSV file import via SFTP
  - Import via API call
    - Authentication
    - Payment import request
Elaborazione sincrona dei pagamenti

Elaborazione pagamenti di terze parti in Monetization

L’elaborazione dei pagamenti di terze parti può avvenire con due metodi: sincrono e asincrono. Il metodo sincrono richiede risposte immediate dal componente di integrazione dei pagamenti, mentre il metodo asincrono combina l’estrazione delle invoice da Monetization e la successiva importazione dei pagamenti.

Informazioni:

In genere, il caso d’uso determina quale metodo di elaborazione è ottimale.

Elaborazione asincrona dei pagamenti

Per l’elaborazione asincrona dei pagamenti, esporti le invoice da Monetization e i pagamenti vengono elaborati interamente fuori da Monetization. Quando sono disponibili i risultati dell’elaborazione, li importi tramite file CSV o API di Monetization.

Esportazione delle invoice

Puoi esportare invoice da Monetization configurando un invoice export mapper e pianificando un exporting job che esporta i file in una posizione SFTP, oppure sottoscrivendo la creazione invoice tramite webhook, che attiva una richiesta invoice all’URL fornito ogni volta che viene creata una nuova invoice.

Exporting job - file CSV su SFTP

Per esportare invoice come file CSV, è necessario configurare un Invoice Export mapper per mappare i parametri invoice alle colonne del file CSV. L’interfaccia utente di Monetization consente questa configurazione in Business configuration Export Invoice mappers.

Example of invoice export mapper configuration Figura 1: Esempio di configurazione invoice export mapper

Le esportazioni invoice sono pianificate tramite Exporting Jobs, che possono essere attività one-off o automatizzate per periodi specifici. L’Exporting Job salva il file CSV esportato nella rispettiva posizione SFTP storage/invoice/folder_name/file_name.csv.

Example of invoice export job Figura 2: Esempio di invoice export job

Metodo notification - webhook

L’esportazione delle invoice tramite webhook consente di riceverle immediatamente alla creazione. Questo avviene configurando una Invoice Notification Rule, che invia ogni invoice creata come richiesta con body JSON all’URL fornito, insieme alle opzioni header preconfigurate.

Example of invoice creation webhook configuration Figura 3: Esempio di configurazione webhook per creazione invoice

Importazione dei pagamenti

Puoi importare transazioni di pagamento in Monetization configurando un payment import mapper e caricando i file CSV dei pagamenti nella posizione SFTP di input, oppure usando la REST API di Monetization.

CSV file import via SFTP

Affinché Monetization importi transazioni di pagamento tramite file CSV, deve essere configurato un Payment Import Mapper. La configurazione è disponibile nell’interfaccia utente di Monetization in Business configuration Import Payment mappers.

Il Payment mapper consente di mappare le colonne CSV ai parametri della transazione di pagamento e di definire un prefisso file che deve essere presente nei file caricati.

I file vengono caricati sul server SFTP nella cartella edl/input e spostati nelle cartelle edl/processed, edl/successful, edl/error e edl/rejected in base ai risultati dell’elaborazione.

Example of payment import mapper configuration Figura 4: Esempio di configurazione payment import mapper

Import via API call

Per importare una transazione di pagamento tramite API di Monetization, invia una richiesta JSON contenente i dettagli della transazione alla REST API di Monetization.

Nota:

Un utente deve prima autenticarsi per comunicare con l’API di Monetization.

Authentication

L’API di Monetization usa l’autenticazione Bearer Token:

Esegui la richiesta Authentication con username, password e codice sito specifico.
Recupera il token dalla risposta.
Imposta l’header Authorization a Bearer <token> nelle richieste successive.
Il token scade dopo 5 minuti.

URL: {{api_url}}/authenticate

Headers
Content-Type:application/json

Body
{
    "username": "your_monetization_username",
    "password": "password",
    "site_code": "your_monetization_site_code - subdomain"
}

Payment import request

URL: {{api_url}}/api/v1/import

Headers
Content-Type:application/json
Authorization:Bearer {{auth_token}}
Data-Type:Payment

Body
{
    "invoice_id": 123,
    "transaction_identifier": "T-1233-cew3-445f-feew3",
    "amount": 150,
    "transaction_time": 1600613169000,
    "currency": "EUR",
    "method": "other",
    "type": "charge",
    "provider": "stripe"
}

Elaborazione sincrona dei pagamenti

L’elaborazione sincrona dei pagamenti richiede comunicazione sincrona tra Monetization e il componente di integrazione dei pagamenti. Questo metodo abilita autorizzazioni con carte di credito/debito e pagamenti immediati.

Configuri Monetization per specificare dove inviare le richieste relative all’elaborazione dei pagamenti; Monetization ha risposte predefinite che si aspetta in ritorno. Questo metodo consente di memorizzare riferimenti al metodo di pagamento sui clienti e supporta processi automatici di riscossione dei pagamenti.

Per Monetization, il processo di integrazione è praticamente lo stesso di un’integrazione out-of-the-box con un provider esistente (Stripe, Braintree, ecc.). Tuttavia, la comunicazione avviene tramite un componente sviluppato da te, che funge da gateway verso il provider di pagamento locale.

Operazioni essenziali per supportare l’elaborazione sincrona dei pagamenti:

Setup Intent
Authorize
Capture
Charge

Configurazione provider di pagamento di terze parti

Per configurare l’integrazione con un provider di pagamento di terze parti, configura un profilo payment gateway di terze parti e fornisci l’URL a cui Monetization deve inviare le richieste.

È possibile farlo dall’interfaccia utente in System configuration Payment gateways, oppure creando un Payment Gateway Profile tramite REST API di Monetization.

URL: {{api_url}}/api/v1/payment-gateway-profiles

Headers
Content-Type:application/json
Authorization:Bearer {{auth_token}}

Request
{
    "provider": "third-party",
    "headers": {
        "PGW_URL": "URL to your payment gateway"
    }
}

Operazioni cliente

Le operazioni cliente si applicano solo quando il provider di pagamento di terze parti supporta la gestione clienti. Se il provider non supporta la gestione clienti, gli ids cliente possono essere sostituiti con qualsiasi valore, ad esempio il timestamp Unix della richiesta.

Creare cliente (senza carta)

Crea un cliente come oggetto nel servizio del provider di pagamento.

Richiesta inviata da Monetization:

{
    "action": "create_customer",
    "content": {
        "customer": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
    }
}

Risposta attesa:

HTTP Stato: 201 Created

{
    "customer": {
        "id": "payment_provider_customer_id"
    }
}

Aggiornare cliente

Aggiorna un oggetto cliente nel servizio del provider di pagamento.

Richiesta inviata da Monetization:

{
    "action": "update_customer",
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
    }
}

Risposta attesa:

HTTP Stato: 204 No Content

Nessun body di risposta

Leggere cliente

Legge un oggetto cliente dal servizio del provider di pagamento.

{
    "action": "read_customer",
    "content": {
        "id": "payment_provider_customer_id_1"
    }
}

Risposta attesa:

HTPP Stato: 200 OK

{
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        },
        "credit_cards": [
            {
                "is_default": true,
                "card_holder_name": "John Anderson",
                "expiration_month": "03",
                "expiration_year": "2026",
                "type": "Mastercard",
                "token": "payment_provider_card_token",
                "last_four": "1234"
            }
        ]
    }
}

Eliminare cliente

Elimina un oggetto cliente dal servizio del provider di pagamento.

Richiesta inviata da Monetization:

{
    "action": "delete_customer",
    "content": {
        "id": "payment_provider_customer_id_1"
    }
}

Risposta attesa:

HTTP Stato: 204 No Content

Nessun body di risposta

Operazioni carta

Le operazioni carta riguardano la configurazione o rimozione di carte di credito e debito.

Setup (richiesta setup carta)

Attiva un processo in cui il cliente può fornire i dettagli della carta di credito, che vengono tokenizzati e memorizzati in Monetization. Alla richiesta di aggiunta di una nuova carta di credito, Monetization invia una richiesta setup al componente di integrazione.

Il componente di integrazione deve gestire la logica relativa ai servizi del provider di pagamento e restituire a Monetization un URL di redirect come risposta. Il cliente verrà quindi reindirizzato all’URL fornito, dove il form ospitato dal provider di pagamento raccoglierà e tokenizzerà i dettagli della carta.

Credit card setup Figura 5: Configurazione carta di credito

Richiesta inviata da Monetization:

{
    "action": "setup",
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
        "custom_attributes": {
            "callback_url": "https://callbackurl.com"
        }
    }
}

Risposta attesa:

HTTP Stato: 201 Created

{
    "customer": {
        "id": "payment_provider_customer_id"
    },
    "redirect_url": "https://card-data-collection-form.com"
}

Eliminare carta

Invia una richiesta al componente di integrazione per gestire la logica di rimozione del riferimento alla carta di credito tramite i servizi del provider di pagamento, quindi rimuove il riferimento da Monetization in caso di esito positivo.

Richiesta inviata da Monetization:

{
    "action": "delete_credit_card",
    "content": {
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

Risposta attesa:

HTTP Stato: 204 No Content

Nessun body di risposta

Operazioni transazione

Le operazioni transazione riguardano azioni transazionali eseguite sui token del metodo di pagamento memorizzato (carta di credito/debito). Queste azioni includono:

Authorization
Capture
Charge
Void
Refund

Authorization

Authorization viene usata per autorizzare (bloccare) fondi sul metodo di pagamento del cliente. Le autorizzazioni possono essere successivamente acquisite (Captured) o annullate (Voided). La richiesta seguente viene inviata al componente di integrazione, che deve gestire la logica del servizio del provider di pagamento e restituire una risposta.

Richiesta inviata da Monetization:

{
    "action": "authorize",
    "content": {
        "amount": 20.5,
        "currency": "EUR",
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

Risposta attesa:

HTTP Stato: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Capture

Capture indica la riscossione di fondi autorizzati da una richiesta Authorization precedente. L’importo da riscuotere può essere uguale o inferiore all’importo autorizzato.

Eventuali fondi autorizzati non riscossi verranno rilasciati al cliente dal servizio del provider di pagamento. La richiesta seguente viene inviata al componente di integrazione, che deve gestire la logica del servizio del provider di pagamento e restituire una risposta.

Richiesta inviata da Monetization:

{
    "action": "capture",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234",
        "amount": 10.5
    }
}

Risposta attesa:

HTTP Stato: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 10.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Charge

Charge autorizza e acquisisce i fondi come singola transazione immediata. La richiesta seguente viene inviata al componente di integrazione, che deve gestire la logica del servizio del provider di pagamento e restituire una risposta.

Richiesta inviata da Monetization:

{
    "action": "charge",
    "content": {
        "amount": 25.5,
        "currency": "EUR",
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

Risposta attesa:

HTTP Stato: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Void

L’operazione Void annulla una transazione Authorization, rilasciando i fondi autorizzati. La richiesta seguente viene inviata al componente di integrazione, che deve gestire la logica del servizio del provider di pagamento e restituire una risposta.

Richiesta inviata da Monetization:

{
    "action": "void",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234"
    }
}

Risposta attesa:

HTTP Stato: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Refund

Refund restituisce fondi al cliente e fa riferimento a una transazione Charge o Capture precedente. La richiesta seguente viene inviata al componente di integrazione, che deve gestire la logica del servizio del provider di pagamento e restituire una risposta.

Richiesta inviata da Monetization:

{
    "action": "refund",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234",
        "amount": 10.5
    }
}

Risposta attesa:

HTTP Stato: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Gestione errori

Se un’operazione non ha esito positivo nel componente di integrazione, restituisci qualsiasi stato fuori dall’intervallo 200-300 e il messaggio di errore nel body della risposta.

Dispositivi