Accept an Affirm payment
Learn how to accept Affirm, a buy now and pay later payment method.
Caution
Stripe automatically presents your customers payment method options by evaluating their currency, payment method restrictions, and other parameters. We recommend that you configure your payment methods from the Stripe Dashboard using the instructions in Accept a payment.
If you want to continue manually configuring the payment methods you present to your customers with Checkout, use this guide. Otherwise, update your integration to configure payment methods in the Dashboard.
Affirm is a single use, immediate notification payment method that requires customers to authenticate their payment. Customers are redirected to the Affirm site, where they agree to the terms of an installment plan. When the customer accepts the terms, funds are guaranteed and transferred to your Stripe account. The customer repays Affirm directly over time.
Note
Before you start the integration, make sure your account is eligible for Affirm by navigating to your Payment methods settings.
Determine compatibility
A Checkout Session must satisfy all of the following conditions to support Affirm payments:
- You can only use one-time line items. Affirm doesn’t support recurring subscription plans.
- Express all Prices in your domestic currency.
Accept a payment
Note
This guide builds on the foundational accept a payment Checkout integration.
Use this guide to learn how to enable Affirm—it shows the differences between accepting a card payment and using Affirm.
Enable Affirm as a payment method
When creating a new Checkout Session, you need to:
- Add
affirm
to the list ofpayment_
.method_ types - Make sure all your
line_
use your domestic currency.items - We recommend collecting shipping addresses by adding your country to
shipping_
. If you don’t want to collect shipping addresses with Checkout, you can also provide the shipping address usingaddress_ collection[allowed_ countries] payment_
. Doing so helps with loan acceptance rates.intent_ data[shipping]
Fulfill your orders
Use a method such as webhooks to handle order fulfillment, instead of relying on your customer to return to the payment status page.
The following events are sent when the payment status changes:
Event Name | Description | Next steps |
---|---|---|
checkout.session.completed | The customer successfully authorized the payment by submitting the Checkout form. | Wait for the payment to succeed or fail. |
payment_intent.succeeded | The customer’s payment succeeded. The PaymentIntent transitions to succeeded . | Fulfill the goods or services that the customer purchased. |
payment_intent.payment_failed | The customer’s payment was declined, or failed for some other reason. The PaymentIntent returns to the requires_ status. | Email the customer to request that they place a new order. |
Learn more about fulfilling orders.
Test your integration
When testing your Checkout integration, select Affirm as the payment method and click the Pay button.
Test your Affirm integration with your test API keys by viewing the redirect page. You can test the successful payment case by authenticating the payment on the redirect page. The PaymentIntent transitions from requires_
to succeeded
.
To test the case where the user fails to authenticate, use your test API keys and view the redirect page. On the redirect page, close the Affirm modal window and verify that payment failed. The PaymentIntent transitions from requires_
to requires_
.
When redirected to the Affirm sandbox, Affirm may ask for the last four digits of your SSN. Affirm suggests using '0000'
or '5678'
.
For manual capture PaymentIntents in testmode, the uncaptured PaymentIntent auto-expires 10 minutes after successful authorization.
Failed payments
Affirm takes into account multiple factors when deciding to accept or decline a transaction (for example, the length of time buyer has used Affirm, the outstanding amount the customer has to repay, and the value of the current order).
Always present additional payment options such as card
in your checkout flow, as Affirm payments have a higher rate of decline than many payment methods. In these cases, the PaymentMethod is detached and the PaymentIntent object’s status automatically transitions to requires_
.
Other than a payment being declined, for an Affirm PaymentIntent with a status of requires_
, customers need to complete the payment within 12 hours after you redirect them to the Affirm site. If the customer takes no action within 12 hours, the PaymentMethod is detached and the PaymentIntent object’s status automatically transitions to requires_
.
In these cases, inform your customer to try again with a different payment option presented in your checkout flow.
Error codes
These are the common error codes and corresponding recommended actions:
Error code | Recommended action |
---|---|
invalid_ | Enter an amount within Affirm’s default transaction limits, for the country. |
invalid_ | Enter an amount within Affirm’s default transaction limits, for the country. |
missing_ | Check the error message for more information on the required parameter. |
nonexistent_ | Enter a valid two-letter ISO country code for the country property in the shipping and billing details. |
payment_ | Enter the appropriate currency. Affirm only supports payments in your local currency. |
payment_ | Provide a return_ when confirming a PaymentIntent with Affirm. |
payment_ | Check the error message for more information on the parameter. |