Promos API Integration
En savoir plus sur l'utilisation de notre API Promos pour ajouter des messages promotionnels Affirm.
Aperçu
Vous pouvez utiliser le point de terminaison de l'API prmos côté serveur pour afficher des prix mensuels dynamiques (ou d'autres textes promotionnels) et pour présenter des modales éducatives hébergés par Affirm sur votre site web. Nous avons conçu notre service de promotions pour qu'il soit léger et utilisable pour les commerçants et les développeurs Affirm, ce qui facilite son implémentation dans différents environnements. Vous trouverez ci-dessous des renseignements sur notre nouvelle API Promos ainsi que des instructions d'intégration.
Comment ça fonctionne
Le point de terminaison promos s'interface avec notre service promos. En fonction des paramètres de requête envoyés par le client, notre service retourne la bonne réponse contenant les modalités et les styles de financement pour la messagerie modale Affirm et APQ (« Aussi Peu Que »).
Entrées
Base Path: https://www.affirm.com/api/promos/v2/{YOUR_PUBLIC_KEY} où YOUR_PUBLIC_KEY est votre clé d'api publique.
Clé API publique
Chaque commerçant Affirm possède une clé API publique unique, vous devez donc travailler avec un CSM Affirm pour intégrer un nouveau commerçant que vous souhaitez utiliser ce point de terminaison API.
Attributs
| Nom du paramètre de requête | Type de données | Description | Valeurs prises en charge | Par défaut |
| amount
Obligatoire |
int32 | Le montant total du paiement en dollars américains ou en dollars canadiens (par ex., 10 000 centimes pour facturer 100,00 $). | Paramètres régionaux par défaut de la devise actuelle | |
| page_type | string | Identifie votre messagerie promotionnelle afin qu'Affirm puisse appliquer les personnalisations nécessaires en fonction de la page sur laquelle ils sont affichés.
|
homepage \ landing \ search \ category \ product
panier paiement banner \ marketplace |
Produit |
| template_field
optionnel |
Déterminez les types de promotions à afficher. Il y a 3 possibilités :
|
en_US \ en_CA \ fr_CA | Paramètres régionaux par défaut du pays actuel |
Champs de réponse
L'exemple suivant démontre les données retournées par notre API de promotion qui peuvent ensuite être utilisées pour personnaliser le texte. Veuillez travailler en collaboration avec votre partenaire Affirm, afin de vous assurer que vous êtes conforme.
Pour personnaliser le texte renvoyé par l'API des promotions, veuillez travailler en collaboration avec votre partenaire Affirm.
APQ
{
"promo": {
"html_ala": HTML formatted as low as messaging,
"config": [Internal Use Only],
"ala": As low as messaging
}
}
Modal
Remarque : un grand nombre de ces champs sont utilisés pour le formatage des modales Affirm.
{
"promo": {
"content_space_1": [Internal Use Only],
"Description": One-line message about what Affirm is,
"footer": Legal disclosures for educational modal,
"headline": Headline for educational modal,
"tagline": One-line sample of the best term for the specified
data amount and merchant,
"button": Call to action text for user,
"html_footer": HTML formatted legal disclosures,
"content_space_2": [Internal Use Only],
"terms_description": [Internal Use Only],
"config": {
"styles": [Internal Use Only],
"promo_style": [Internal Use Only],
"is_ada_compliant": [Internal Use Only],
"promo_prequal_enabled": indicator of if prequalification
is enabled for this merchant and
this promotional message (true or
false),
"show_white_labeling": [Internal Use Only],
"images": {
"hero2x": High quality merchant promotional image url
(default null),
"logo": Merchant logo url (default null),
"hero": Merchant promotional image url (default null),
"logo2x": High quality merchant logo url (default null),
},
"merchant_name": Merchant's name,
}
},
"offer": {
"expiry_date": [Internal Use Only],
"terms": List of sample loan terms for the given cart amount.
Each term will have the following format:
{
"loan_type": Loan type available for this merchant
(classic, affirm_go_v3, affirm_go),
"interest_amount": Amount of interest for this
loan term,
"billing_frequency": Frequency at which the user will
need to pay back the loan,
"apr": APR for this loan term,
"installment_amount": Amount due at each payment,
"minimum_loan_amount": Minimum loan amount available
to the user,
"amount": Total amount due when loan is completed,
"installment_count": Total number of installments
},
"minimum_loan_amount": Minimum loan amount available to the user
}
}
Tous
{
"promo": {
"html_ala": HTML formatted as low as messaging,
"ala": As low as messaging
"content_space_1": [Internal Use Only],
"Description": One-line message about what Affirm is,
"footer": Legal disclosures for educational modal,
"headline": Headline for educational modal,
"tagline": One-line sample of the best term for the specified
data amount and merchant,
"button": Call to action text for user,
"html_footer": HTML formatted legal disclosures,
"content_space_2": [Internal Use Only],
"terms_description": [Internal Use Only],
"config": {
"styles": [Internal Use Only],
"promo_style": [Internal Use Only],
"is_ada_compliant": [Internal Use Only],
"promo_prequal_enabled": indicator of if prequalification
is enabled for this merchant and
this promotional message (true or
false),
"show_white_labeling": [Internal Use Only],
"images": {
"hero2x": High quality merchant promotional image url
(default null),
"logo": Merchant logo url (default null),
"hero": Merchant promotional image url (default null),
"logo2x": High quality merchant logo url (default null),
},
"merchant_name": Merchant's name,
}
},
"offer": {
"expiry_date": [Internal Use Only],
"terms": List of sample loan terms for the given cart amount.
Each term will have the following format:
{
"loan_type": Loan type available for this merchant
(classic, affirm_go_v3, affirm_go),
"interest_amount": Amount of interest for this
loan term,
"billing_frequency": Frequency at which the user will
need to pay back the loan,
"apr": APR for this loan term,
"installment_amount": Amount due at each payment,
"minimum_loan_amount": Minimum loan amount available
to the user,
"amount": Total amount due when loan is completed,
"installment_count": Total number of installments
},
"minimum_loan_amount": Minimum loan amount available to the user
}
}
Requêtes
Messagerie Aussi Peu Que
Requête de base utilisant les valeurs par défaut
https://affirm.com/api/promos/v2/{YOUR_PUBLIC_KEY}?amount={AMOUNT_IN_CENTS}&field=ala&use_best_terms=true&show_cta=true
Exemple de demande
https://affirm.com/api/promos/v2/L6MZWHPL1AHQOYOJ?amount=18500&field=ala&use_best_terms=true&show_cta=true
Exemple de réponse
{
"promo":
{
"html_ala": "Starting at <span class='affirm-ala-price'>$17</span>/mo with <span class='__affirm-logo __affirm-logo-blue'>Affirm</span>. <a class='affirm-modal-trigger'>Prequalify now</a>",
"config":
{
"promo_prequal_enabled": true,
"promo_style": "prequal"
},
"ala": "Starting at $17/mo with Affirm. Prequalify now"
}
}
Requête de base avec des personnalisations
https://www.affirm.com/api/promos/v2/{YOUR_PUBLIC_KEY}?amount={AMOUNT_IN_CENTS}&field=ala&items=%5B%7B%22sku%22%3A%22{ITEM_SKU}%22%2C%22display_name%22%3A{ITEM_NAME}%2C%22qty%22%3A{QUANTITY}%2C%22unit_price%22%3A{UNIT_PRICE}%7D%5D&page_type=product
Exemple de demande
https://www.affirm.com/api/promos/v2/L6MZWHPL1AHQOYOJ?amount=10000&field=ala&items=%5B%7B%22sku%22%3A%22ABC123%22%2C%22display_name%22%3A%22Glasses%22%2C%22qty%22%3A2%2C%22unit_price%22%3A5000%7D%5D&page_type=product
Exemple de réponse
{
"promo":
{
"html_ala": "Starting at <span class='affirm-ala-price'>$10</span>/mo with <span class='__affirm-logo __affirm-logo-blue'>Affirm</span>. <a class='affirm-modal-trigger'>Prequalify now</a>",
"config":
{
"promo_prequal_enabled": true,
"promo_style": "prequal"
},
"ala": "Starting at $10/mo with Affirm. Prequalify now"
}
}
Rendu de modale
Requête de base utilisant les valeurs par défaut
https://affirm.com/api/promos/v2/{YOUR_PUBLIC_KEY}?amount={AMOUNT_IN_CENTS}&field=modal&use_best_terms=true
Exemple de demande
https://affirm.com/api/promos/v2/L6MZWHPL1AHQOYOJ?amount=10000&field=modal&use_best_terms=true
Exemple de réponse
{
"promo":
{
"content_space_1": "quick_and_easy",
"description": "Get a real-time decision with just 5 pieces of info.",
"footer": "Rates are between 10–30% APR. A down payment may be required. Subject to eligibility check and approval. Payment options depend on your purchase amount. Estimated payment amount excludes taxes and shipping fees. Actual terms may vary. Payment options through Affirm are provided by these lending partners: affirm.com/lenders. Visit affirm.com/help for more info.",
"headline": "Make easy monthly payments over 3, 6, or 12 months",
"tagline": "$9.04/mo. based on a purchase price of $100.00 at 15% APR for 12 months. Rates from 10–30% APR.",
"button": "See if you qualify",
"html_footer": "Rates are between 10–30% APR. A down payment may be required. Subject to eligibility check and approval. Payment options depend on your purchase amount. Estimated payment amount excludes taxes and shipping fees. Actual terms may vary. Payment options through Affirm are provided by these lending partners: [affirm.com/lenders](https://www.affirm.com/lenders). Visit [affirm.com/help](https://affirm.com/help) for more info.",
"content_space_2": "no_hidden_fees",
"terms_description": "",
"config":
{
"styles":
{
"color": null,
"fontFamily": "'proxima-nova', sans-serif"
},
"promo_style": "prequal",
"is_ada_compliant": false,
"promo_prequal_enabled": true,
"show_white_labeling": false,
"images":
{
"hero2x": null,
"logo": null,
"hero": null,
"logo2x": null
},
"merchant_name": "[TEST] Sandbox Merchant"
}
},
"offer":
{
"expiry_date": null,
"terms":
[
{
"downpayment_amount": null,
"loan_type": "classic",
"interest_amount": 256,
"billing_frequency": "monthly",
"apr": 15.29,
"installment_amount": 3418,
"minimum_loan_amount": 50,
"amount": 10256,
"installment_count": 3
},
{
"downpayment_amount": null,
"loan_type": "classic",
"interest_amount": 449,
"billing_frequency": "monthly",
"apr": 15.24,
"installment_amount": 1742,
"minimum_loan_amount": 50,
"amount": 10449,
"installment_count": 6
},
{
"downpayment_amount": null,
"loan_type": "classic",
"interest_amount": 843,
"billing_frequency": "monthly",
"apr": 15.22,
"installment_amount": 904,
"minimum_loan_amount": 100,
"amount": 10843,
"installment_count": 12
}
],
"minimum_loan_amount": 50
}
}
Requête de base avec des personnalisations
https://www.affirm.com/api/promos/v2/{YOUR_PUBLIC_KEY}?amount={AMOUNT_IN_CENTS}&field=modal&items=%5B%7B%22sku%22%3A%22{ITEM_SKU}%22%2C%22display_name%22%3A{ITEM_NAME}%2C%22qty%22%3A{QUANTITY}%2C%22unit_price%22%3A{UNIT_PRICE}%7D%5D&page_type=product
Exemple de demande
https://www.affirm.com/api/promos/v2/L6MZWHPL1AHQOYOJ?amount=10000&field=modal&items=%5B%7B%22sku%22%3A%22ABC123%22%2C%22display_name%22%3A%22Glasses%22%2C%22qty%22%3A2%2C%22unit_price%22%3A5000%7D%5D&page_type=product
Exemple de réponse
{
"promo":
{
"content_space_1": "quick_and_easy",
"description": "",
"footer": "A down payment may be required. Subject to eligibility check and approval. Payment options depend on your purchase amount. Estimated payment amount excludes taxes and shipping fees. Actual terms may vary. Payment options through Affirm are provided by these lending partners: affirm.com/lenders. Visit affirm.com/help for more info.",
"headline": "Make easy monthly payments over 3, 6, or 12 months",
"tagline": "$9.04/mo. based on a purchase price of $100.00 at 15% APR for 12 months. Rates from 10–30% APR.",
"button": "See if you qualify",
"html_footer": "A down payment may be required. Subject to eligibility check and approval. Payment options depend on your purchase amount. Estimated payment amount excludes taxes and shipping fees. Actual terms may vary. Payment options through Affirm are provided by these lending partners: [affirm.com/lenders](https://www.affirm.com/lenders). Visit [affirm.com/help](https://affirm.com/help) for more info.",
"content_space_2": "no_hidden_fees",
"terms_description": "",
"config":
{
"styles":
{
"color": null,
"fontFamily": "'proxima-nova', sans-serif"
},
"promo_style": "prequal",
"is_ada_compliant": false,
"promo_prequal_enabled": true,
"show_white_labeling": false,
"images":
{
"hero2x": null,
"logo": null,
"hero": null,
"logo2x": null
},
"merchant_name": "[TEST] Sandbox Merchant"
}
},
"offer":
{
"expiry_date": null,
"terms":
[
{
"downpayment_amount": null,
"loan_type": "classic",
"interest_amount": 256,
"billing_frequency": "monthly",
"apr": 15.29,
"installment_amount": 3418,
"minimum_loan_amount": 50,
"amount": 10256,
"installment_count": 3
},
{
"downpayment_amount": null,
"loan_type": "classic",
"interest_amount": 449,
"billing_frequency": "monthly",
"apr": 15.24,
"installment_amount": 1742,
"minimum_loan_amount": 50,
"amount": 10449,
"installment_count": 6
},
{
"downpayment_amount": null,
"loan_type": "classic",
"interest_amount": 843,
"billing_frequency": "monthly",
"apr": 15.22,
"installment_amount": 904,
"minimum_loan_amount": 100,
"amount": 10843,
"installment_count": 12
}
],
"minimum_loan_amount": 50
}
}
Implémentation
-
Créez une requête API GET avec les paramètres requis pour récupérer la messagerie APQ (Aussi Peu Que) à partir du point de terminaison ci-dessous.
https://www.affirm.com/api/promos/v2/{YOUR_PUBLIC_KEY} -
Utilisez la valeur du champ ala dans la réponse pour obtenir le message promotionnel Aussi Peu Que (par ex., À partir de 185 $/mois avec Affirm. Vérifier l'admissibilité maintenant).
-
Établissez un hyperlien HTML sur votre site Web pour le CTA de préadmissibilité (appel à l’action) avec une URL parallèle suivant ce format :
URL parallèle
https://www.affirm.com/apps/prequal/?public_api_key=YOUR_PUBLIC_KEY&unit_price=PRODUCT_PRICE&page_type=PAGE_TYPE&use_promo=true&referring_url=https://www.YourReturningURL.com
Par exemple, si vous souhaitez implémenter la préadmissibilité avec la fonction Aussi Peu Que " À partir de 185 $/mois avec Affirm. Vérifier l'admissibilité maintenant " sur votre page de produit, vous utiliserez l'extrait HTML suivant :
<p>Starting at $185/mo with Affirm. <a href="https://www.affirm.com/apps/prequal/?public_api_key=L6MZWHPL1AHQOYOJ&unit_price=222000&PRODUCT_PRICE&page_type=product&use_promo=true&referring_url=https%253A%252F%252Fwww.affirm.com%252F&" target="_blank">Prequalify now</a></p>
URL parallèle
L’URL parallèle est l’URL qui doit être visiblement liée au CTA qui dirige vers une page d’information en raison des exigences réglementaires. Veuillez consulter l'exemple suivant :
URL parallèle
https://www.affirm.com/apps/prequal/?public_api_key=YOUR_PUBLIC_KEY&unit_price=25000&page_type=product&use_best_terms=true&use_promo=true&referring_url=https://www.YourReturningURL.com
\
Note:
- La clé amount passe à unit_price pour l'URL d'information.
- Le referring_url n'est applicable que si la fonction de préadmissibilité est active
- Si vous prenez en charge le financement basé sur sku, vous pouvez également transmettre des éléments stringifiés
Si la préadmissibilité est activée, cette URL sera utilisée pour rediriger l'utilisateur vers le site web une fois la préadmissibilité terminée.
- Validez la fonctionnalité avec un échantillon de jsfiddle et assurez-vous que la fonctionnalité de préadmissibilité fonctionne
Des questions?
Si vous avez des questions, communiquez avec votre contact technique chez Affirm.
Exemple de mise en œuvre sur une page de produit
Chaque fois que vous souhaitez ajouter la messagerie Affirm Aussi peu que (par ex,. " À partir de 185 $/mois avec Affirm. Vérifier l'admissibilité maintenant "), vous devez inclure les deux parties suivantes :
- La messagerie APQ elle-même : à partir de 185 $/mois avec Affirm
- Le CTA qui inclut un lien vers un modal avec divulgations, etc. : Vérifiez l'admissibilité maintenant
Le CTA, un lien vers une page Affirm avec les détails correspondant et expliquant le message Aussi peu que, est requis pour satisfaire aux réglementations de prêt. Autrement dit, pour toute demande promotionnelle générée, une URL parallèle pour une page d’information doit être créée et liée visiblement sur le CTA du message Aussi peu que retourné par le point de terminaison Aussi peu que.
Par exemple, sur une page de détails de produit, vous utiliserez la demande suivante pour récupérer la fonction Aussi peu que d’un produit de 250 $ :
demande
curl --request GET \
--url https://www.affirm.com/api/promos/v2/YOUR_PUBLIC_KEY?amount=25000&use_best_terms=true&page_type=product
Réponse
La réponse renvoyée par cette demande ressemblerait à ce qui suit :
JSON
{
"promo": {
"content_space_1": "quick_and_easy",
"description": "Get a real-time decision with just 5 pieces of info.",
"footer": "Rates are between 0\u201330% APR. A down payment may be required. Subject to eligibility check and approval. Payment options depend on your purchase amount. Estimated payment amount excludes taxes and shipping fees. Actual terms may vary. Payment options through Affirm are provided by these lending partners: affirm.com/lenders. Visit affirm.com/help for more info.",
"headline": "Make easy monthly payments over 3, 6, or 12 months",
"tagline": "$22.60/mo. based on a purchase price of $250.00 at 15% APR for 12 months. Rates from 0\u201330% APR.",
"html_ala": "Starting at <span class='affirm-ala-price'>$23</span>/mo with <span class='__affirm-logo __affirm-logo-blue'>Affirm</span>. <a class='affirm-modal-trigger'>Prequalify now</a>",
"ala": "Starting at $23/mo with Affirm. Prequalify now",
"html_footer": "Rates are between 0\u201330% APR. A down payment may be required. Subject to eligibility check and approval. Payment options depend on your purchase amount. Estimated payment amount excludes taxes and shipping fees. Actual terms may vary. Payment options through Affirm are provided by these lending partners: <a class='affirm-loan-originator' href='https://www.affirm.com/lenders'>affirm.com/lenders</a>. Visit affirm.com/help for more info.",
"content_space_2": "no_hidden_fees",
"terms_description": "",
"config": {
"styles": {
"color": null,
"fontFamily": "'proxima-nova', sans-serif"
},
"promo_style": "prequal",
"is_ada_compliant": false,
"promo_prequal_enabled": true,
"show_white_labeling": false,
"images": {
"hero2x": null,
"logo": null,
"hero": null,
"logo2x": null
},
"merchant_name": "Merchant Name"
},
"button": "See if you qualify"
},
"offer": {
"expiry_date": null,
"terms": [
{
"loan_type": "classic",
"interest_amount": 0,
"billing_frequency": "monthly",
"apr": 0.00,
"installment_amount": 8333,
"minimum_loan_amount": 50,
"amount": 25000,
"installment_count": 3
},
{
"loan_type": "classic",
"interest_amount": 1128,
"billing_frequency": "monthly",
"apr": 15.31,
"installment_amount": 4355,
"minimum_loan_amount": 50,
"amount": 26128,
"installment_count": 6
},
{
"loan_type": "classic",
"interest_amount": 2115,
"billing_frequency": "monthly",
"apr": 15.27,
"installment_amount": 2260,
"minimum_loan_amount": 100,
"amount": 27115,
"installment_count": 12
}
],
"minimum_loan_amount": 50
}
}
À partir de ces deux réponses, nous créerons ensuite le code HTML à insérer sur votre page :
- Tirez le html_ala de la réponse promotionnelle :
"html_ala": "Starting at \<span class='affirm-ala-price'>$23\</span>/mo with \<span class='**affirm-logo **affirm-logo-blue'>Affirm\</span>. \<a class='affirm-modal-trigger'>Prequalify now\</a>"
- Identifiez le CTA. Dans cet exemple, le CTA est " Vérifiez l'admissibilité maintenant " et il est enveloppé dans une balise avec class=affirm-modal-trigger.
Insérez votre attribut href et le lien vers l'URL parallèle :
href='https://www.affirm.com/apps/prequal/?public_api_key=API_KEY&unit_price=25000&page_type=product&use_promo=true
Le code HTML final ressemblerait à ceci :
HTML
Starting at <span class='affirm-ala-price'>$23</span>/mo with <span class='__affirm-logo __affirm-logo-blue'>Affirm</span>. <a class='affirm-modal-trigger' href='https://www.affirm.com/apps/prequal/?public_api_key=YOUR_PUBLIC_KEY&unit_price=25000&page_type=product&use_promo=true&referring_url=https://www.YourReturningURL.com'>Prequalify now</a>
Note
Le referring_url n'est applicable que si la fonction de préadmissibilité est active.
Mis à jour 5 months ago