Configurez la caisse Express

Disponibilité des pays

Liste des pays ⬇️

USA

La liste de vérification de l'intégration du paiement express peut être utilisée pour suivre votre progression

Étapes d'intégration

1. Créer un identifiant de commande unique

Générez un identifiant de commande unique, comme un identifiant de panier, de session ou de commande, dans votre système principal. Nous recommandons d’utiliser un identifiant à forte entropie (p. ex., un UUID) plutôt qu’un numéro séquentiel pour renforcer la sécurité. Cet identifiant sert de référence principale pour la session du client tout au long du processus du paiement Affirm et sera renvoyé à votre serveur aux étapes 3 et 4, vous permettant d’identifier la transaction en toute sécurité et de calculer les options d’expédition et les totaux de la commande appropriés.

2. Configurer Affirm Express Checkout

Pour amorcer le flux du paiement express, vous devez configurer l’objet du paiement Affirm selon les exigences spécifiques suivantes :

• Définir le type de caisse : inclure checkout_variant: "express" dans l'objet merchant.
• Spécifiez l’URL de rappel: incluez la chaîne shipping_and_totals_callback_url dans l’objet commerçant. Ceci définit le point de terminaison de serveur à serveur qu’Affirm appellera en temps réel pour récupérer les modes d’expédition, les taxes et les totaux mis à jour une fois que le client aura saisi son adresse.
• Définir l'identifiant de commande: incluez le champ order_id avec l'identifiant unique généré à l'étape 1. Cet identifiant sera renvoyé à votre serveur dans la demande de rappel Expédition & totaux (étape 3) et retourné dans la réponse de l'API de lecture de caisse (étape 4), ce qui vous permettra d'associer le paiement Affirm à la bonne session de panier.
• Définir le sous-total: fournissez un entier subtotal représentant le coût des articles avant taxes et frais d’expédition. Cette valeur doit être définie dans l’objet metadata. Les paiements dont le sous-total est inférieur au seuil de panier configuré ne sont pas admissibles au processus de paiement express.
• Omettre les frais d'expédition et le total: n'incluez pas l'objet shipping ou le champ total, car ceux-ci seront déterminés pendant le flux hébergé par Affirm.
• Inclure les attributs standard: Assurez-vous d’inclure le tableau items et tous les autres attributs de caisse standard.

affirm.checkout({
  merchant: {
    checkout_variant: "express", // ensure this attribute is passed for Express Checkout
    shipping_and_totals_callback_url: "https://merchantsite.com/shipping-totals?example_param=123456ABC", // Affirm will call this endpoint server-to-server to get shipping options and totals based on the customer's shipping address
    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 »

Cette étape recueille les renseignements d’expédition du client et les totaux de la caisse omis lors de la configuration du paiement express Affirm. Configurez un point de terminaison HTTP qui accepte l’identifiant de commande du commerçant et l’adresse de livraison du client comme données d’entrée et renvoie toutes les options d’expédition valides avec le montant d’expédition, le montant de la taxe et le montant total de la commande. L’URL de ce point de terminaison est celle qui est transmise dans le champ shipping_and_totals_callback_url lors de la création du paiement Affirm..

L'utilisateur sélectionnera ensuite une option d'expédition, et le montant total de la commande correspondant à cette sélection sera utilisé pour souscrire le prêt Affirm. Ce montant final est ensuite retourné via le point de terminaison d'autorisation de la transaction pour votre vérification.

Sécurité des points de terminaison

• Vérification des requêtes (HMAC): Pour vous assurer que les requêtes transmises à votre point d’accès proviennent légitimement d’Affirm, vous devez vérifier l’en-tête X-Affirm-Signature.
  • La 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. La valeur de l'en-tête sera formatée comme suit : “t={current_timestamp},v0={hash("{current_timestamp}.{request_body}")}”
  • Vérification: Recalculez le hachage sur votre serveur à l'aide de votre clé privée et comparez-le à la valeur de l'en-tête. S'ils ne correspondent pas, la demande doit être rejetée comme non autorisée (HTTP 401). Si le current_timestamp date de plus de 5 minutes, la demande doit également être rejetée. current_timestamp sera exprimé sous forme d’un nombre entier correspondant au nombre de secondes écoulées depuis l’époque (ex. 1772576438).
  • Rotation des clés: pendant les périodes de rotation des clés, Affirm générera une valeur de hachage avec chacune des deux clés et formatera la valeur de l'en-tête sous la forme “t={current_timestamp},v0={key1_hash}={key2_hash}”, où key1 est la plus ancienne des deux clés
• Validation de l’URL de rappel : afin d’empêcher l’injection d’URL de rappel malveillantes lors de la création du paiement, Affirm vérifie le nom d’hôte shipping_and_totals_callback_url par rapport à une liste de modèles de noms d’hôte autorisés enregistrés pour votre compte marchand. Seul le nom d'hôte est validé; le chemin de l'URL, les paramètres de chemin et les paramètres de requête ne sont pas vérifiés. Affirm prend en charge et encourage l'utilisation de listes d'autorisations différentes selon l'environnement, par exemple pour l'environnement de test et de production. Pour enregistrer ou mettre à jour vos modèles de nom d'hôte autorisés, contactez votre responsable technique de compte (TAM), car ces listes d'autorisations sont configurées en interne par Affirm et ne sont pas directement accessibles ou modifiables par les commerçants.
• 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.
• Sécurité du périmètre: si votre environnement de production utilise un CDN, un pare-feu ou une autre couche de sécurité réseau, vous devez ajouter les adresses IP sortantes d’Affirm à votre liste d’autorisation. Puisqu’Affirm utilise des requêtes de serveur à serveur en temps réel pour récupérer les options d’expédition et les montants totaux, ces mécanismes de sécurité peuvent bloquer ce trafic et entraîner une erreur 403. Veuillez communiquer avec votre responsable technique (TAM) pour obtenir la liste requise des adresses IP de production et de sandbox.

Performance du point de terminaison

• Délai de réponse (SLA): Affirm exige que votre point de terminaison HTTP Expédition et totaux réponde dans un délai de 5 000 millisecondes (5 secondes).
• Comportement du délai d’expiration: Si votre point de terminaison ne répond pas dans cette fenêtre, la caisse hébergée par Affirm rencontrera une erreur de délai d’expiration et le client ne pourra pas 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 cela se produit, Affirm s'attend à recevoir un corps de réponse contenant la propriété errors avec un tableau d'objets contenant les éléments suivants :

• 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",
    "shipping":{
        "line1": "123 Example Street",
        "line2": "Apt 123",
        "city": "San Francisco",
        "country": "USA",
        "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 et du client, 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
• Nom du client
• Courriel du client
• Numéro de téléphone du client

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

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)",
    "address": {
      "city": "San Francisco",
      "country": "USA",
      "line1": "123 Example Street",
      "line2": "Apt 123",
      "state": "CA",
      "zipcode": "94107"
    }
    // name, phone_number, and email will only be provided within billing
  },
  "billing": {
    "name": {
      "last": "string",
      "first": "string"
    },
    "phone_number": "1234567890",
    "email": "[email protected]"
    // address will only be provided within shipping
  },
  "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",
  "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"
  }
}

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