Utilizzo dell'API Meta Pay

Quando elabori i pagamenti per Meta Pay, devi informare Meta di qualsiasi attività correlata alle transazioni di pagamento, come le autorizzazioni e i rimborsi, richiamando webhook nell'API Meta Pay. L'attività della transazione di pagamento viene mostrata nella pagina Ordini e pagamenti dell'account Facebook di un cliente.

Per scoprire come usare le API di Meta, consulta Panoramica dell'API Graph e tieni presente che le API descritte di seguito sono relative all'URL host API Graph standard (https://graph.facebook.com). Per informazioni di carattere più generale, consulta Panoramica dell'integrazione di Meta Pay.

Registrazione

Prima di poter iniziare a usare le API Meta Pay, devi completare la seguente procedura:

• Completa la procedura di registrazione generale
• Rivedi l'elaborazione dei pagamenti in Meta Pay

Chiamata delle API Meta Pay

Nell'ambito della procedura di registrazione generale, devi creare una nuova app nel Portale per sviluppatori Meta. Una volta creata l'app, riceverai un ID dell'app e una chiave segreta.

Ogni chiamata effettuata a un'API Meta Pay richiede un token d'accesso dell'app derivato dall'ID dell'app e dalla chiave segreta. Invia il token d'accesso dell'app utilizzando l'intestazione Authorization, non un parametro di query access_token. Le API Meta Pay rifiutano le chiamate con i token utente.

Ad esempio, usa il seguente codice:

Authorization: OAuth <APP_ACCESS_TOKEN>

Firma

Ogni richiesta HTTP alle API Meta Pay deve includere l'intestazione FBPAY_SIGNATURE. Il valore di questa intestazione è un oggetto JSON Web Signature (JWS) con l'algoritmo ES256, serializzazione compatta e un payload scollegato (detached) (come descritto in https://tools.ietf.org/html/rfc7515#appendix-F). Il valore di payload è il corpo della richiesta HTTP POST. La chiave di firma JWS deve essere identificata con l'intestazione x5c, che deve contenere un certificato collegato al certificato radice attendibile (trust root) del partner. Il certificato root del partner è condiviso con Meta come parte della procedura di registrazione (indicato come il certificato di firma dell'API Meta Pay).

Esempio di richiesta con firma

curl -i -X POST \
  -H "Content-Type: application/json" \
  -H "FBPAY_SIGNATURE: eyJhbGciOiJFUzI1NiIsIng1YyI6WyJNSUlCaERDQ0FTcWdBd0lCQWdJQkFUQUtCZ2dxaGtqT1BRUURBakFoTVI4d0hRWURWUVFEREJad1lYSjBibVZ5SUhOcFoyNWhkSFZ5WlNCalpYSjBNQjRYRFRJd01EY3hNekl5TWpVek1Gb1hEVEkwTURNeE1USXlNalV6TUZvd0lURWZNQjBHQTFVRUF3d1djR0Z5ZEc1bGNpQnphV2R1WVhSMWNtVWdZMlZ5ZERCWk1CTUdCeXFHU000OUFnRUdDQ3FHU000OUF3RUhBMElBQkFuRngwR1NKMklPZGZpcFdiMGMwZytBVThlbDh6QnRVS0kxdWRzT2kzN2thd1JRSFkzV29YaWRvRThIOHM1cVIySmo2ZkFKWVhOTURXY0NiditWMEJ1alV6QlJNQjBHQTFVZERnUVdCQlR4NlBGRkhjd2FUZnY5cVdzZUJcL1NjMWFPbVZ6QWZCZ05WSFNNRUdEQVdnQlR4NlBGRkhjd2FUZnY5cVdzZUJcL1NjMWFPbVZ6QVBCZ05WSFJNQkFmOEVCVEFEQVFIXC9NQW9HQ0NxR1NNNDlCQU1DQTBnQU1FVUNJUUNBRE9zZ0pZanRXVm9xNUZOSjc3U2JDeWtON1ZldUlKR2pXb3NBVUFNd1ZRSWdUTlVcL2ttc1wvN0cxVUx5Z01DRWVXemNiYTNrMVo4NEE4RmNlMXQzYUNGbGc9Il19..ZnT7ZR3EqsPYMQt3WdgUZYScBiyK9RI77zMaUKr-tkFRBHgBJQVTOORwM2fFh0QQCTLwOp1TiAzt_q9ofvw6JQ" "https://graph.facebook.com/1001200005002/notify_authorizations" \
  -d '{"notification":{"partner_merchant_id":"123e4567-e89b-12d3-a456-426614174000","container_id":"cGF5bWVudF9jb250YWluZAXI6MTIzNDU2NzhfX01FUkNIQU5UX1RFU1RfRTJFX19QU1BfVEVTVF8x","event_time":1582230020020,"type":"notify_authorizations"},"resource":{"partner_auth_id":"1234567890","auth_amount":{"currency":"USD","value":29508},"status":"SUCCEEDED","created_time":1582230019010,"metadata":[]},"idempotence_token":"ddbdf2cf-d339-4b0b-a27e-4731d8d37c9d"}'

La richiesta precedente codifica i seguenti dati:

{
  "notification": {
    "partner_merchant_id": "123e4567-e89b-12d3-a456-426614174000",
    "container_id": "cGF5bWVudF9jb250YWluZAXI6MTIzNDU2NzhfX01FUkNIQU5UX1RFU1RfRTJFX19QU1BfVEVTVF8x",
    "event_time": 1582230020020,
    "type": "notify_authorizations"
  },
  "resource": {
    "partner_auth_id": "1234567890",
    "auth_amount": {
      "currency": "USD",
      "value": 29508
    },
    "status": "SUCCEEDED",
    "created_time": 1582230019010,
    "metadata": []
  },
  "idempotence_token": "ddbdf2cf-d339-4b0b-a27e-4731d8d37c9d"
}

Di seguito è riportata la firma della richiesta precedente, con decodifica Base64 e JSON per maggiore chiarezza:

base64url(
 json({
   "x5c": [
     "MIIBhDCCASqgAwIBAgIBATAKBggqhkjOPQQDAjAhMR8wHQYDVQQDDBZwYXJ0bmVyIHNpZ25hdHVyZSBjZXJ0MB4XDTIwMDcxMzIyMjUzMFoXDTI0MDMxMTIyMjUzMFowITEfMB0GA1UEAwwWcGFydG5lciBzaWduYXR1cmUgY2VydDBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABAnFx0GSJ2IOdfipWb0c0g+AU8el8zBtUKI1udsOi37kawRQHY3WoXidoE8H8s5qR2Jj6fAJYXNMDWcCbv+V0BujUzBRMB0GA1UdDgQWBBTx6PFFHcwaTfv9qWseB/Sc1aOmVzAfBgNVHSMEGDAWgBTx6PFFHcwaTfv9qWseB/Sc1aOmVzAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0gAMEUCIQCADOsgJYjtWVoq5FNJ77SbCykN7VeuIJGjWosAUAMwVQIgTNU/kms/7G1ULygMCEeWzcba3k1Z84A8Fce1t3aCFlg="
   ],
   "alg": "ES256"
 })
) + // Protected Header
 "." +
 "" + // Payload is detached
 "." +
 "ZnT7ZR3EqsPYMQt3WdgUZYScBiyK9RI77zMaUKr-tkFRBHgBJQVTOORwM2fFh0QQCTLwOp1TiAzt_q9ofvw6JQ" // Signature

Idempotenza

Il campo idempotence_token permette di prevenire l'esecuzione duplicata di richieste quando queste vengono ritentate dopo un errore di rete o un timeout. Il token di idempotenza è un valore unico generato dal client, il quale stabilisce come generarlo. Ad esempio, puoi usare uno UUID V4 per generare un token di idempotenza.

Quando una richiesta viene completata con successo, oppure una chiamata all'API restituisce risultati validi, i dati di risposta vengono salvati con il token di idempotenza. Quando si tenta di eseguire nuovamente un richiesta riuscita con un token di idempotenza già utilizzato, viene restituita la risposta precedentemente salvata, ma senza rieseguire codice.

Quando una richiesta genera un errore, non viene salvato alcun risultato. Puoi ritentare la richiesta e usare lo stesso token di idempotenza.

Se effettui 2 richieste allo stesso tempo con lo stesso token di idempotenza, solo una restituirà i dati di risposta.

I token di idempotenza sono progettati come token temporanei da utilizzare esclusivamente per ritentare le chiamate all'API in caso di errore. Se ritenti una richiesta in un momento successivo, potresti ricevere una risposta diversa da quella ottenuta nella chiamata precedente.

I parametri della richiesta vengono ignorati. Se modifichi il contenuto della richiesta, crea un nuovo token di idempotenza per quella richiesta.

Riconciliazione batch

Quando elabori i pagamenti, informi Meta di qualsiasi attività correlata alle transazioni di pagamento usando i webhook di Meta Pay. Richiamando i webhook, l'attività della transazione di pagamento viene mostrata tempestivamente nella pagina Attività di Facebook Pay dell'account Facebook del cliente.

Le notifiche non andate a buon fine vengono acquisite da Meta durante la riconciliazione batch e mostrate successivamente nell'account Facebook del cliente.

Per supportare la riconciliazione batch, carica ogni giorno un file contenente le notifiche che hai inviato a Meta quel giorno. Includi sia le notifiche andate a buon fine sia quelle non recapitate. Per maggiori dettagli sul caricamento di un file sull'API Meta, consulta Caricare file su Facebook.

Gestione degli errori

Le API Meta Pay usano la modalità di gestione degli errori dell'API Graph standard.

Inizializzazione e aggiornamento dei venditori

Per inizializzare o aggiornare i dati di un venditore da te supportato, effettua una richiesta POST all'API Graph del venditore /metapay_partner/merchant e specifica i parametri di quel venditore.

https://graph.facebook.com/metapay_partner/merchant

Parametri della richiesta

Risposta

Dopo aver effettuato una richiesta POST all'API del venditore, la risposta 200 OK indica che la richiesta POST è stata elaborata con successo. Il corpo della risposta indica lo stato del venditore, ovvero ENABLED o DISABLED. I modificatori dello stato non vuoti forniscono informazioni aggiuntive.

Una comune risposta positiva ha un aspetto simile a questo:

{
    "status":"ENABLED",
    "status_modifiers":[]
}

Una risposta per un venditore momentaneamente sottoposto a verifica ha un aspetto simile a questo:

{
    "status":"DISABLED",
    "status_modifiers":["PENDING_SCREENING"]
}

Di seguito sono riportati i possibili modificatori dello stato.

Acquisizione di venditori

Per recuperare una lista di venditori registrati, effettua una richiesta GET all'API Graph del venditore /metapay_partner/merchants.

https://graph.facebook.com/metapay_partner/merchants

Parametri della richiesta

I seguenti parametri facoltativi di richiesta sono supportati come parametri URL:

Risposta

I risultati ottenuti dall'API GET del venditore sono paginati. Fai riferimento alla pagina collegata per il formato di risposta generale. Ogni elemento restituito nell'array data è nel formato dei parametri della richiesta del venditore. Esempio:

curl -H "Authorization: OAuth $OAUTH" -X GET "https://graph.facebook.com/metapay_partner/merchants?partner_merchant_id=MERCHANT_TEST_1"
{
    "data": [
        {
            "partner_merchant_id": "MERCHANT_TEST_1",
            "merchant_status": "DISABLED",
            "display_name": "Test merchant 1",
            "business_uri": "https://facebook.com/",
            "icon_uri": "https://facebook.com/favicon.ico",
            "mcc_list": [7311],
            "support_email": "example@facebook.com",
            "support_phone": "+11234567890",
            "valid_origins": [
                "https://facebook.com/"
            ],
            "legal_structure": "COMPANY_TYPE_NOT_SPECIFIED",
            "status_modifiers":["BLOCKED"],
            "effective_merchant_status":"DISABLED"
        }
    ],
    "paging": {
        "cursors": {
            "before": "aaa...",
            "after": "bbb..."
        },
        "next": "https://graph.facebook.com/metapay_partner/merchants?limit=25&after=..."
    }
}

Webhook

Devi informare Meta di qualsiasi attività correlata a transazioni di pagamento richiamando i webhook di Meta a ogni procedura di autorizzazione, acquisizione, contestazione, pagamento o rimborso.

La risposta 200 OK indica che il webhook è stato elaborato con successo. Il corpo di una risposta con esito positivo restituisce il parametro container_id:

{
    "id":"cGF5bWVudF9jb250YWluZAXI6N2I3ODA1ZATYtZAmRiNS00Yzc4LWFjYjAtZATg3ZAjJhMzg2YTc5XzM2ODkyNjAzMTc4MDEzNzYZD"
}

Se un'invocazione webhook ha esito negativo, riprova almeno tre volte per almeno settantadue ore con backoff incrementale. Se l'invocazione continua a non andare a buon fine, la notifica può essere acquisita in un secondo momento durante la riconciliazione batch.

Di seguito è riportato un diagramma entità-relazione per le risorse modellate nei webhook dell'API Meta. Le proprietà con puntini neri indicano gli attributi obbligatori.

Notifica

Ogni volta che richiami un webhook, includi un parametro notification nel corpo della richiesta e i dettagli relativi al tipo di notifica nel campo resource, come descritto nelle sezioni che seguono. La struttura generale per la notifica è questa:

{
  idempotence_token: '<your token>',
  notification:
  {
    ...
  },
  resource:
  {
    ...
  }
}

Parametro notification

Notifica delle autorizzazioni

Effettua una richiesta POST a /<CONTAINER_ID>/notify_authorizations per informare Meta dell'attività di autorizzazione per una transazione di pagamento.

https://graph.facebook.com/<CONTAINER_ID>/notify_authorizations

Risorsa di tipo autorizzazione

Notifica delle acquisizioni

Effettua una richiesta POST a /<CONTAINER_ID>/notify_captures per informare Meta dell'attività di acquisizione per una transazione di pagamento.

https://graph.facebook.com/<CONTAINER_ID>/notify_captures

Risorsa capture

Notifica delle contestazioni

Effettua una richiesta POST a /<CONTAINER_ID>/notify_disputes per informare Meta dell'attività di contestazione per una transazione di pagamento.

https://graph.facebook.com/<CONTAINER_ID>/notify_disputes

Risorsa dispute

Notifica dei pagamenti

Effettua una richiesta POST a /<CONTAINER_ID>/notify_payments per informare Meta dell'attività di pagamento non relativa alle operazioni di trasferimento di denaro. Ad esempio, puoi decidere di non elaborare il pagamento di un utente che non ha superato i controlli relativi ai rischi.

https://graph.facebook.com/<CONTAINER_ID>/notify_payments

Risorsa di tipo pagamento

Notifica dei rimborsi

Effettua una richiesta POST a /<CONTAINER_ID>/notify_refunds per informare Meta dell'attività di rimborso per una transazione di pagamento.

https://graph.facebook.com/<CONTAINER_ID>/notify_refunds

Risorsa di tipo rimborso

Oggetto notification amount

Usa un oggetto amount per rappresentare un valore monetario in una specifica valuta per le notifiche relative ad autorizzazioni, acquisizioni, contestazioni e rimborsi.

Oggetto amount

Oggetto notification error

Se si verifica un errore durante l'elaborazione di un'autorizzazione, un'acquisizione, un pagamento o un rimborso, includi un oggetto error in resource per fornire informazioni su quell'errore.

Oggetto error