Configurez la caisse Express

Disponibilité des pays

Liste des pays ⬇️

USA

❗️

Vous souhaitez offrir Affirm Express Checkout ?

Contactez votre gestionnaire de compte Affirm pour confirmer la disponibilité et connaître les prochaines étapes pour construire vos API.

Conditions préalables

• Créez un compte dans le Tableau de bord des commerçants Affirm.
• Intégrez l’option Affirm Checkout par défaut.
• Accédez à vos clés API publiques et privées.
• Contactez votre gestionnaire de compte Affirm pour confirmer la disponibilité et connaître les prochaines étapes pour construire vos API.

Étapes

1. Créer un identifiant de commande unique

Créez un order_id unique (p. ex., un identifiant de panier ou de session) dans votre backend pour suivre la session de caisse. Cet identifiant est utilisé tout au long du flux de la Caisse Express et est renvoyé dans les étapes suivantes pour lier les calculs d'expédition et les totaux de la commande à la bonne transaction. Pour améliorer la sécurité, utilisez un identifiant à forte entropie (tel qu'un UUID) plutôt qu'une valeur séquentielle.

2. Configurer Affirm Express Checkout

Vous devez configurer l’ objet de caisse d’Affirm spécifiquement pour le flux de paiement express :

• Définir le type de caisse : inclure checkout_variant: "express" dans l'objet merchant.
• Inclure un identifiant de commande : Transmettez le order_id généré à l'étape 1 pour suivre la session de caisse. Cet identifiant est retourné dans les étapes ultérieures.
• Fournir le sous-total : inclure une valeur subtotal représentant le coût des articles avant taxes et frais d'expédition.
• Ne pas tenir compte des frais d'expédition et du total : n'incluez pas l'objet shipping ou total field, car ils sont déterminés pendant le flux hébergé par Affirm.
• Inclure les attributs standard : Fournissez le tableau items et tous les autres champs obligatoires de la caisse.

affirm.checkout({
  merchant: {
    checkout_variant: "express", // ensure this attribute is passed for Express Checkout
    user_confirmation_url: "https://merchantsite.com/confirm",
    user_cancel_url: "https://merchantsite.com/cancel",
    public_api_key: "YOUR_PUBLIC_KEY",
    user_confirmation_url_action: "POST",
  },
  order_id: "unique_merchant_cart_identifier", // merchant's unique order identifier
  metadata: {
    subtotal: 20000, // cost of items excluding taxes or shipping
    // rest of metadata attributes
  },
  items: [{
    display_name: "Awesome Pants",
    sku: "ABC-123",
    unit_price: 10000,
    qty: 2,
  }],
  // exclude the shipping object and the total field
  // rest of checkout object attributes
});

affirm.checkout.open();

3. Configurer le point de terminaison HTTP « Livraison et totaux »

Fournir un point de terminaison côté serveur qu'Affirm appelle pendant la caisse pour récupérer les options d'expédition et calculer les totaux de commande associés à chaque option.

• Accepte les articles du panier et les détails de livraison du client, et
• Retourne le montant d’expédition calculé, le montant de la taxe et le montant total de la commande pour la méthode d’expédition choisie.

Flux de requêtes et de réponses

• Affirm recueille l’adresse d’expédition du client au moment de la caisse.
• Affirm envoie une requête de serveur à serveur à votre point de terminaison avec :
  • order_id,
  • shipping adresse.
• Votre point de terminaison retourne :
  • Options de livraison disponibles.
  • Frais d'expédition, taxes et total pour chaque option.

Le client choisit une option d'expédition dans l'expérience Affirm, et le total correspondant est utilisé pour souscrire le prêt. Ce montant final est ensuite retourné à votre backend pour validation lors de l’autorisation de la transaction.

Configuration

L'URL du point de terminaison d'expédition et des totaux est configurée en interne par Affirm et n'est pas directement accessible ou modifiable par les commerçants.

Pour mettre à jour cette URL ou configurer des environnements distincts (p. ex., environnement de test et environnement de production), contactez votre Gestionnaire de Compte Technique (TAM).

Sécurité des points de terminaison

Pour vous assurer que les requêtes proviennent d’Affirm, vous devez vérifier la signature de la requête incluse dans l’en-tête X-Affirm-Signature.

Format de signature

Affirm génère un hachage HMAC-SHA512 de l'horodatage actuel et du corps de la requête en utilisant votre clé API privée. L'en-tête est formaté comme suit :

"t={current_timestamp},v0={hash("{current_timestamp}.{request_body}")}"

Vérifier la requête

Sur votre serveur :

1. Extraire les signatures timestamp et v0 de l'en-tête.
2. Recalculer le hachage HMAC-SHA512 à l'aide de votre clé d'API privée.
3. Comparez votre hachage calculé à la valeur v0.
4. Rejeter la requête si :
   1. Les signatures ne correspondent pas → retour HTTP 401 Non autorisé,
   2. L'horodatage est plus ancien que 5 minutes.

Rotation de clé

Lors de la rotation des clés, Affirm peut inclure une valeur de hachage générée avec plusieurs clés. La valeur de l'en-tête est :

"t={current_timestamp},v0={key1_hash}={key2_hash}"

Veuillez noter que key1 est la plus ancienne des deux clés.

Communications sécurisées

Toute communication entre Affirm et vos points de terminaison côté serveur doit être effectuée via HTTPS en utilisant TLS 1.2 ou supérieur.

Performance du point de terminaison

• Délai de réponse : Votre point de terminaison Expédition et Totaux doit répondre dans les 5 secondes (5 000 ms).
• Comportement du délai d'expiration : Si le point de terminaison ne répond pas dans cette fenêtre, la requête arrivera à expiration, ce qui entraînera une erreur de caisse et empêchera le client de finaliser son achat.

Gestion des erreurs de calcul et de validation

Si votre backend ne peut pas calculer les options d’expédition ou le total des commandes en raison de zones d’expédition restreintes, de données d’adresse invalides ou de pénuries d’inventaires, vous devez retourner un code d’état HTTP 422 Entité non traitable.

Lorsque cette erreur se produit, Affirm s'attend à ce que :

• error_code : Affirm analyse cette chaîne lisible par machine pour déterminer la logique interne et la gestion du flux.
• message : Cette chaîne est affichée directement au client dans l'interface de caisse Affirm pour expliquer pourquoi la caisse ne peut pas être réalisée.
• fields : (Optionnel) Un tableau de chaînes de caractères identifiant les propriétés spécifiques de la charge utile de la requête qui ont causé l’erreur (par exemple, ["shipping_address.pays"]).

Pour connaître les exigences détaillées du schéma et des exemples de charges utiles, veuillez consulter la page de l’API Express Checkout.

Exemple

Lors de la sélection de l’adresse d’expédition par l’utilisateur, Affirm enverra une requête avec une charge utile similaire à la suivante :

{
    "currency":"USD",
    // The merchant order id provided by the merchant
    "order_id": "unique_merchant_cart_identifier",
    // https://docs.affirm.com/developers/reference/shipping-billing-object
    "shipping":{
        "line1": "123 Example Street",
        "line2": "Apt 123",
        "city": "San Francisco",
        "country": "US",
        "state": "CA",
        "zipcode": "94107"
    }
}

Si la requête est réussie, Affirm s'attend à une réponse HTTP 200 similaire à la suivante :

{
  "order_id": "unique_merchant_cart_identifier",
  "currency": "USD",
  "subtotal": 20000,
  "shipping_options": [
    {
      "shipping_type": "unique_merchant_shipping_identifier_1",
      "shipping_label": "Standard Shipping (7-10 Days)",
      "shipping_amount": 0,  
      "tax_amount": 100,
      "total": 20100  
    },
    {
      "shipping_type": "unique_merchant_shipping_identifier_2",
      "shipping_label": "Express Shipping (3-5 Days)",
      "shipping_amount": 200,  
      "tax_amount": 100,
      "total": 20300  
    },
    {
      "shipping_type": "unique_merchant_shipping_identifier_3",
      "shipping_label": "Overnight Shipping (1 Day)",
      "shipping_amount": 500,  
      "tax_amount": 100,
      "total": 20600  
    }
  ]
}

Si la requête échoue, le point de terminaison devrait renvoyer un code d’état 422 Entité Non Traitée. Le corps de la réponse doit contenir un tableau d'erreurs avec un ou plusieurs objets d'erreur :

Erreur unique

{
  "errors": [
    {
      "error_code": "UNSUPPORTED_SHIPPING_ZONE",
      "message": "We currently do not offer shipping to Hawaii or Alaska.",
      "fields": [
        "shipping_address.state"
      ]
    }
  ]
}

Erreurs multiples

{
  "errors": [
    {
      "error_code": "INVALID_SHIPPING_ADDRESS",
      "message": "The provided ZIP code does not match the selected state.",
      "fields": [
        "shipping_address.zipcode",
        "shipping_address.state"
      ]
    },
    {
      "error_code": "INVENTORY_UNAVAILABLE",
      "message": "One or more items in your cart are no longer in stock."
    }
  ]
}

4. Calculer le total de la commande

Une fois la caisse Affirm du client terminée, récupérez les détails définitifs de la commande auprès d'Affirm et vérifiez le total avant de finaliser la transaction.

Retrieve checkout details

Utilisez le checkout_id pour appeler l'API de lecture de caisse:

GET /api/v2/checkout/{checkout_id}

Cela renvoie tous les détails d'expédition, y compris :

• Adresse d'expédition
• Méthode d'expédition sélectionnée
• Montant final des frais d'expédition, des taxes et du total

Utilisez ces données pour calculer le total final de la commande dans votre backend.

🚧

Numéro de commande

Si votre système génère un nouvel identifiant de commande à ce stade qui diffère de l'identifiant initial fourni à l'étape 1, assurez-vous de transmettre cet identifiant mis à jour lors de l'autorisation de la transaction.

À partir de ce moment, utilisez l'identifiant de l'ordre mis à jour comme référence principale pour tous les appels ultérieurs de l'API Transaction.

Valider le total

Appelez le point de terminaison de la transaction autorisée pour récupérer le montant du prêt autorisé auprès d’Affirm.

Comparez les éléments suivants :

• Votre total calculé.
• Montant autorisé par Affirm.

Ces valeurs doivent correspondre exactement pour s'assurer que le prêt légalement autorisé couvre le coût final de la commande avant de poursuivre.

Finaliser la commande

Si les totaux correspondent :

• Terminez la transaction.
• Dirigez le client vers votre page de confirmation.

S'ils ne correspondent pas :

• N'exécutez pas la commande.
• À considérer comme un échec de validation.

Exemple de lecture de la réponse de l'API de caisse

{
  "order_id": "unique_merchant_cart_identifier",
  "currency": "USD",
  // order totals collected during user checkout journey
  "total": 20600,
  "tax_amount": 100,
  "shipping_amount": 500,
  "shipping": {
    // shipping method collected during user checkout journey  
    "shipping_type": "unique_merchant_shipping_identifier_3",
    "shipping_label": "Standard Shipping (7-10 Days)"
    "name": {
      "full": "John Doe",
      "first": "John",
      "last": "Doe"
    },
    "address": {
      "city": "San Francisco",
      "country": "US",
      "line1": "123 Example Street",
      "line2": "Apt 123",
      "state": "CA",
      "zipcode": "94107"
    },
    "email": "[email protected]",
    "phone_number": "1234567890"
  },
  "merchant": {
    "checkout_variant": "express", // flag for whether this checkout was Express
    "public_api_key": "string",
    "user_cancel_url": "string",
    "user_confirmation_url": "string",
    "user_confirmation_url_action": "string",
    "name": "string",
  },
  // rest of checkout data
  "metadata": {
    "subtotal": 20000 // subtotal
  },
  "billing_frequency": "monthly",
  "financial_program_external_name": "string",
  "financial_program_name": "standard_3_6_12",
  "loan_type": "classic",
  "financing_program": "string",
  "merchant_external_reference": "ab-12345",
  "billing": {
    "name": {
      "last": "string",
      "first": "string"
    },
    "phone_number": "1234567890",
    "email": "[email protected]"
  },
  "mfp_rule_input_data": {
    "items": {
      "sku_number": {
        "sku": 0,
        "item_url": "string",
        "display_name": "string",
        "unit_price": 0,
        "qty": 0,
        "item_type": "string",
        "item_image_url": "string"
      }
    },
    "total": 49999,
    "metadata": {
      "checkout_channel_type": "online",
      "mode": "redirect"
    },
    "financing_program": "string"
  },
  "checkout_type": "merchant",
  "checkout_flow_type": "classic",
  "checkout_status": "string",
  "use_adaptive": true,
  "config": "string",
  "product_type": "string",
  "api_version": "v2",
  "product": "string",
  "suppress_expiration_declination_messaging": true,
  "meta": {
    "release": "string",
    "user_timezone": "America/Los_Angeles",
    "_affirm_tracking_uuid": "356a483a-86b2-4846-b6f2-70d37d95a78c"
  }
}

(Optionnel) 5. Ajouter le bouton de paiement Affirm

Ajoutez le bouton de caisse Affirm pré-stylisé sur votre site web pour bénéficier du paiement express. Consultez le bouton caisse pour plus de détails.

Exemple:

<div class="affirm-checkout-button-container"
     data-page-type="product"
     data-size="large"
     data-theme="dark"
     data-shape="rounded"
     data-button-text="checkout"
>
</div>

Quelle est la prochaine étape?

• Messagerie promotionnelle et préadmissibilité
• Configurer l'API Directe
• Aperçu du processus de paiement