AccueilCommencerSolutionsPlateformesIntégrations globales
Docs

Gestion des transactions Split Capture

En savoir plus sur la gestion des états des transactions dans votre passerelle de paiement.

Suggérer des modifications

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

Authorization occurs after a user has successfully completed the Affirm checkout flow and returns back to the merchant site. Authorizing the transaction generates a transaction_id ex: (A1B2-C3D4), that you'll use to reference this loan moving forward.

The Authorize resource endpoint creates a loan and reserves the funds. When you authorize, Affirm will generate a transaction_id that you’ll use to reference the transaction moving forward. You must authorize a transaction to complete its creation.

❗️

Authorizing the Loan

If you don't authorize a charge, the loan will not become active. The user won't see the loan, and you won't be able to capture the funds. To avoid this, authorize the loan as soon as you receive a checkout token.

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"}'

You should receive a response that looks like the example below with the 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 :

  • Validate that authorized amount equals the order total.
  • Redirect the customer to the order confirmation page or display an order confirmation message.
  • Store the transaction_id.
  • Mark the order payment as pending.

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é.

📘

Authorizing an Affirm Loan

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

Gestion des transactions

You can integrate the Transaction endpoints into your back-end order management system, where you fulfill orders and process payments.

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 .

Capture a Transaction

After fulfilling an order, you must send a Capture Transaction API request to Affirm in order to capture or settle the funds. You'll want to perform this activity from your secure back-end systems. To capture a previous authorization, you'll need the charge_id provided in the Authorization API response. There are no required fields that need to be stored from the capture response.

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

If you do not pass a specified amount in the the capture request, the entire amount will be captured.

Authorization Window

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"
}

Multiple Captures, Refunds, and Voids

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

Below are examples of common Split Capture use cases, where we guide you through submitting multiple capture requests. These examples follow a fictional business, Prometheus Furniture, that sells home furnishings and appliances. Due to the high demand of their furniture, they typically ship items for multiple orders at different times.

Example 1: Capture All Funds

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"}'

Example 2: Capture Less than Full Amount with a Partial Void

Sometimes, customers request a loan greater than the amount they end up spending due to a canceled item or tax adjustment. In the example below, a customer takes out a $1000 loan, but orders two bar stools for $300, and patio furniture for $500, and a chair for $200. After authorizing the full loan amount, Prometheus captures the funds for the bar stools specifying the amount of $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}'

Example 3: Captures All Funds with a Refund

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}'

Although Prometheus Furniture ultimately captured the full loan, they refunded the requested amount to the customer, which will be applied at the end of the loan.

Example 4: Partially Captured Loan Needs to be Voided and Refunded

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 $.

Mis à jour 14 days ago