Gestion des transactions Split Capture

Aperçu

Les transactions représentent les prêts Affirm émis à l'utilisateur final. Vous pouvez interagir avec les transactions via l'API Transaction, afin de modifier l'état de la transaction, de mettre à jour les métadonnées ou de récupérer des détails.

Autorisation

L'autorisation se produit lorsqu'un utilisateur a terminé avec succès le flux de paiement Affirm et retourne sur le site du commerçant. L'autorisation de la transaction génère un transaction_id (A1B2-C3D4), que vous utiliserez pour référencer ce prêt à l’avenir.

Le point de terminaison de la ressource Autoriser crée un prêt et réserve les fonds. Lorsque vous autorisez, Affirm génère un transaction_id que vous utiliserez pour faire référence à la transaction. Vous devez autoriser une transaction pour le créer entièrement.

❗️
Si vous n'autorisez pas une charge, elle ne sera pas considéré comme active. Cela signifie que l’utilisateur ne verra pas le prêt et que vous ne pourrez pas récupérer les fonds. Pour cette raison, vous devez authorize le prêt dès que vous recevez un token checkout.

curl https://sandbox.affirm.com/api/v1/transactions \
     -X POST \
     -u "<public_api_key>:<private_api_key>" \
     -H "Content-Type: application/json" \
     -d '{"transaction_id": "<checkout_token>","order_id": "JKLM4321"}'

Vous devriez recevoir une réponse qui ressemble à ceci avec le transaction_id.

{
   "amount": 6100,
   "amount_refunded": 0,
   "authorization_expiration": "2019-01-01T00:00:00Z",
   "checkout_id": "A1B2C3D4E5F6G7H8",
   "created": "2019-01-01T00:00:00Z",
   "currency": "USD",
   "id": "A1B2-C3D4",
   "order_id": "JKLM4321",
   "provider_id": 1,
   "status": "authorized"
}

Après avoir autorisé une transaction et reçu le montant autorisé, l’utilisateur sera redirigé vers la page user_confirmation_url sur votre site, qui fera ce qui suit :

Valider que le montant autorisé correspond au total de la commande
Rediriger le client vers la page de confirmation de commande ou afficher un message de confirmation de commande
Conserver le transaction_id
Marquez le paiement de la commande comme étant en attente

Si l'autorisation échoue, l'utilisateur sera redirigé vers la page user_cancel_url sur votre site, qui fera ce qui suit :

Rediriger le client vers la page d'erreur de commande ou indiquer que la commande est incomplète.
Conserver potentiellement cette tentative de paiement, ce qui n'est pas obligatoire de notre côté.

📘
Vous ne devez autoriser un prêt Affirm donné qu'une seule fois, pour le montant total de la
transaction en cours d'achat.

Gérer les transactions

Vous pouvez intégrer le point de terminaison Transaction dans votre système de gestion des commandes back-end, où vous traitez normalement les commandes et les paiements.

L'API Transaction vous permet de gérer la transaction à travers différents états tels que autorisée, capturée et annulée.

Si vous souhaitez lire ou mettre à jour les informations du prêt, vous pouvez utiliser les statuts read et update .

Capturer une transaction

Après avoir traité une commande, vous devez envoyer une requête Capture Transaction API à Affirm, afin de capturer ou de régler les fonds. Vous voudrez effectuer cette activité à partir de vos systèmes back-end sécurisés. Pour capturer une transaction autorisée, vous aurez besoin ducharge_id fourni dans la réponse API Autorisation. Il n'y a pas de champs obligatoires qui doivent être enregistrés à partir de la réponse Capture.

La capture des fonds est similaire à celle d'une transaction par carte de crédit. Après avoir capturé le prêt, nous procédons comme suit :

Informer le client que le prêt a été saisi et que son premier paiement sera dû à l’avenir.
Payer le commerçant dans 2 à 3 jours ouvrables.

Pour les Split Cpatures, vous pouvez Capture le prêt dans vos incréments souhaités en spécifiant le paramètre amount pour chaque demande de capture unique dans la fenêtre d'autorisation.

❗️
Montant
Si vous ne transmettez pas de montant dans la capture de la requête Capture, le montant total sera capturé.

Fenêtre d'autorisation

Toutes les captures doivent se produire dans la fenêtre d'autorisation définie. À l’expiration de la période d’autorisation, les montants non capturés seront remboursés au prêt du client et ne pourront plus être récupérés. Travaillez avec votre homologue technique pour vous assurer que la fenêtre d’autorisation est définie correctement selon vos délais d’expédition. La fenêtre d'authentification par défaut est par ailleurs fixée à 30 jours.

curl https://sandbox.affirm.com/api/v1/transactions/{transaction_id}/capture \
     -X POST \
     -u "{public_api_key}:{private_api_key}" \
     -H "Content-Type: application/json" \
     -d '{"amount":"50000", "order_id": "{order_id}", "shipping_carrier": "USPS", "shipping_confirmation": "1Z23223"}'

Vous recevrez ensuite une réponse avec la confirmation.

{
  "fee": 600,
  "created": "2016-03-18T00:03:44Z",
  "order_id": "JKLM4321",
  "currency": "USD",
  "amount": 50000,
  "type": "capture",
  "id": "O5DZHKL942503649",
  "transaction_id": "6dH0LrrgUaMD7Llc"
}

Captures, remboursements et annulations multiples

Pour collecter des fonds par incréments, envoyez une requête Capture Transaction API pour le montant spécifié dans la fenêtre d'autorisation. Par exemple, si votre fenêtre d'autorisation est de 30 jours, vous pouvez créer une requête unique Capture pour chaque article de la commande dans ce délai de 30 jours. Vous pouvez également utiliser le point de terminaison d'annulation pour annuler les fonds non collectés et le point de terminaison de remboursement pour traiter les remboursements pour les fonds partiellement capturés.

Exemples

Vous trouverez ci-dessous quelques exemples de cas d’utilisation courants de Split Capture et nous vous expliquerons comment soumettre plusieurs requêtes Capture. Ces exemples concernent une entreprise fictive, Prometheus Furniture, qui vend des meubles et des appareils électroménagers. En raison de la forte demande de leurs meubles, ils expédient généralement des articles pour plusieurs commandes à différents moments.

Exemple 1 : capturer tous les fonds

Prometheus Furniture vient de passer une commande pour un canapé de 400 dollars et un bureau d'ordinateur de 600 dollars, soit un total de 1 000 dollars. Dans l'exemple ci-dessous, le canapé est prêt à être expédié immédiatement, tandis que le bureau d'ordinateur prendra plus de temps.

Tout d'abord, il autorisera le prêt pour un montant total de 1000 $.

curl https://sandbox.affirm.com/api/v1/transactions \
     -X POST \
     -u "<public_api_key>:<private_api_key>" \
     -H "Content-Type: application/json" \
     -d '{"transaction_id": "<checkout_token>","order_id": "JKLM4321"}'

Ensuite, Prometheus Furniture envoie une demande Capture en spécifiant le amount pour 400 dollars au premier jour du prêt.

#First capture for $400
curl https://sandbox.affirm.com/api/v1/transactions/{transaction_id}/capture \
     -X POST \
     -u "{public_api_key}:{private_api_key}" \
     -H "Content-Type: application/json" \
     -d '{"amount":40000, "order_id": "JKLM4321", "shipping_carrier": "USPS", "shipping_confirmation": "1Z23223"}'

26 jours plus tard, lorsque le bureau d'ordinateur est prêt à être expédié, Prometheus Furniture soumet une autre requête de capture en précisant le montant restant de 600 dollars.

#Second capture for $600
curl https://sandbox.affirm.com/api/v1/transactions/{transaction_id}/capture \
     -X POST \
     -u "{public_api_key}:{private_api_key}" \
     -H "Content-Type: application/json" \
     -d '{"amount":60000, "order_id": "JKLM4321", "shipping_carrier": "USPS", "shipping_confirmation": "1Z23223"}'

Exemple 2 : capturer une quantité inférieure à la totalité avec une annulation partielle

Parfois, les clients demandent un prêt supérieur au montant qu'ils finissent par dépenser en raison de l'annulation d'un article ou d'un ajustement fiscal. Dans l’exemple ci-dessous, un client prend un prêt de 1 000 $, mais commande deux tabourets de bar pour 300 $, et un meuble de patio pour 500 $, et une chaise pour 200 $. Après avoir autorisé le montant total du prêt, Prometheus saisit les fonds pour les tabourets de bar en spécifiant le paramètre amount de 300 $.

#First capture for $300
curl https://sandbox.affirm.com/api/v1/transactions/{transaction_id}/capture \
     -X POST \
     -u "{public_api_key}:{private_api_key}" \
     -H "Content-Type: application/json" \
     -d '{"amount":30000, "order_id": "JKLM4421", "shipping_carrier": "USPS", "shipping_confirmation": "1Z23223"}'

Lorsque le meubles de patio est prêt à être expédié le 13 ème jour, le deuxième montant est prélevé pour le meuble de patio.

#Second capture for $500
curl https://sandbox.affirm.com/api/v1/transactions/{transaction_id}/capture \
     -X POST \
     -u "{public_api_key}:{private_api_key}" \
     -H "Content-Type: application/json" \
     -d '{"amount":50000, "order_id": "JKLM4421", "shipping_carrier": "USPS", "shipping_confirmation": "1Z23223"}'

La chaise initialement commandée a été annulée avant d'être expédiée. Par conséquent, Prometheus Furniture n’a pas saisi les 200 $, mais plutôt soumis une requête Void dans la fenêtre d'autorisation du montant restant.

#Void $200
curl https://sandbox.affirm.com/api/v1/transactions/{transaction_id}/void \
    -X POST \
    -H "Content-Type: application/json" \
    -u "{public_api_key}:{private_api_key}" \
    -d '{"amount":20000}'

Exemple 3 : capturer tous les fonds avec un remboursement

Dans cet exemple, le client a décidé d'acheter un nouveau tapis pour 200 $ et un nouveau réfrigérateur pour 800 $. Après l'autorisation initiale, Prometheus Furniture envoie cette première requête de capture pour 200 $.

#First capture for $200
curl https://sandbox.affirm.com/api/v1/transactions/{transaction_id}/capture \
     -X POST \
     -u "{public_api_key}:{private_api_key}" \
     -H "Content-Type: application/json" \
     -d '{"amount":20000, "order_id": "JKLM5431", "shipping_carrier": "USPS", "shipping_confirmation": "1Z23223"}'

Prometheus peut livrer le réfrigérateur au client un peu plus tôt que d’habitude et saisit le deuxième montant pour 800 $ le jour 4.

#Second capture for $800
curl https://sandbox.affirm.com/api/v1/transactions/{transaction_id}/capture \
     -X POST \
     -u "{public_api_key}:{private_api_key}" \
     -H "Content-Type: application/json" \
     -d '{"amount":80000, "order_id": "JKLM5431", "shipping_carrier": "USPS", "shipping_confirmation": "1Z23223"}'

Le client était très excité d’obtenir ses articles rapidement, mais n’aimait pas vraiment le contraste entre le tapis et les couleurs de son salon. Heureusement, Prometheus Furniture a une excellente politique de remboursement et a initié un remboursement pour le client lorsqu'ils l'ont découvert. Cette fois, ils utiliseront l'API Refund pour créditer les 200 $ au client.

curl https://sandbox.affirm.com/api/v1/transactions/{transaction_id}/refund \
    -X POST \
    -H "Content-Type: application/json" \
    -u "{public_api_key}:{private_api_key}" \
    -d '{"amount": 20000}'

Bien que Prometheus Furniture ait fini par récupérer l’intégralité du prêt, ils ont pu rembourser le montant demandé au client qui sera appliqué à la fin du prêt.

Exemple 4 : le prêt partiellement capturé doit être annulé et remboursé

Pour cet exemple, un client a commandé une table de salle à manger pour 1000 $ et 6 chaises pour 1200 $. Prometheus furniture capture alors le premier montant de 1000 $ pour la table de salle à manger.

#First capture for $1000
curl https://sandbox.affirm.com/api/v1/transactions/{transaction_id}/capture \
     -X POST \
     -u "{public_api_key}:{private_api_key}" \
     -H "Content-Type: application/json" \
     -d '{"amount":100000, "order_id": "JKLM5555", "shipping_carrier":   "USPS", "shipping_confirmation": "1Z23223"}'

Lorsque la table arrive chez le client, celui-ci se rend compte qu'elle est beaucoup trop grande pour sa salle à manger et décide de la retourner. Maintenant que la table est retournée, les chaises de salle à manger ne sont plus nécessaires et le client demande l'annulation de la commande non exécutée. Pour annuler la commande, la première étape consiste à annuler le montant supplémentaire autorisé mais non capturé de 1 200 $.

#Voiding the authorized but uncaptured loan amount of $1200
curl https://sandbox.affirm.com/api/v1/transactions/{transaction_id}/void \
    -X POST \
    -H "Content-Type: application/json" \
    -u "{public_api_key}:{private_api_key}" \
    -d '{"amount":120000}

Après avoir annulé le montant de la transaction autorisé mais non saisi de 1 200 $, l'étape suivante consiste à rembourser le montant du prêt capturé de 1 000 $ pour la table à manger.

#Refunding the captured loan amount of $1000
curl https://sandbox.affirm.com/api/v1/transactions/{transaction_id}/refund \
    -X POST \
    -H "Content-Type: application/json" \
    -u "{public_api_key}:{private_api_key}" \
    -d '{"amount": 100000}'

Étant donné que le prêt a été partiellement capturé, mais que le client a décidé de retourner la table et d'annuler la commande des chaises, il était nécessaire d'annuler d'abord le montant de transaction autorisé mais non capturé de 1 200 $. Suivi d'un remboursement pour le montant du prêt partiellement capturé de 1 000 $.

Aperçu

Autorisation

❗️

📘

Gérer les transactions

Capturer une transaction

❗️Montant

Fenêtre d'autorisation

Captures, remboursements et annulations multiples

Exemples

Exemple 1 : capturer tous les fonds

Exemple 2 : capturer une quantité inférieure à la totalité avec une annulation partielle

Exemple 3 : capturer tous les fonds avec un remboursement

Exemple 4 : le prêt partiellement capturé doit être annulé et remboursé

❗️
Montant