Accept an Affirm payment

Learn how to accept Affirm, a buy now and pay later payment method.

Stripe users can use the Payment Intents API– a single integration path for creating payments using any supported method–to accept Affirm payments from customers in the following countries:

Canada
United States

Accepting Affirm payments on your website consists of:

Creating an object to track a payment
Collecting payment method information
Submitting the payment to Stripe for processing
Handling the Affirm redirect and relevant webhook events

Set up Stripe
Server-side

First, create a Stripe account or sign in.

Use our official libraries to access the Stripe API from your application:

Create a PaymentIntent
Server-side

A PaymentIntent is an object that represents your intent to collect payment from a customer and tracks the lifecycle of the payment process through each stage.

First, create a PaymentIntent on your server and specify the amount to collect and the currency. If you already have an integration using the Payment Intents API, add affirm to the list of payment method types for your PaymentIntent.

You can also use the Payment Element and manage payment methods from the Dashboard. Stripe handles the return of eligible payment methods based on factors such as the transaction’s amount, currency, and payment flow. See Accept a payment for more details.

Retrieve the client secret

The PaymentIntent includes a client secret that the client side uses to securely complete the payment process. You can use different approaches to pass the client secret to the client side.

Retrieve the client secret from an endpoint on your server, using the browser’s fetch function. This approach is best if your client side is a single-page application, particularly one built with a modern frontend framework like React. Create the server endpoint that serves the client secret:

And then fetch the client secret with JavaScript on the client side:

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Collect payment method details and submit
Client-side

When a customer clicks to pay with Affirm, we recommend you use Stripe.js to submit the payment to Stripe. Stripe.js is our foundational JavaScript library for building payment flows. It will automatically handle integration complexities, and enables you to easily extend your integration to other payment methods in the future.

Include the Stripe.js script on your checkout page by adding it to the head of your HTML file.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/v3/"></script>
</head>

Create an instance of Stripe.js with the following JavaScript on your checkout page.

script.js
// Set your publishable key. Remember to change this to your live publishable key in production!
// See your keys here: https://dashboard.stripe.com/apikeys
var stripe = Stripe(
  'pk_test_TYooMQauvdEDq54NiTphI7jx'

);

Rather than sending the entire PaymentIntent object to the client, use its client secret from Step 1. This is different from your API keys that authenticate Stripe API requests.

Handle the client secret carefully, because it can complete the charge. Don’t log it, embed it in URLs, or expose it to anyone but the customer.

Improve payment success rates with additional details

We recommend passing shipping and billing details to improve conversion rates, although these are not required.

This integration guide suggests passing the shipping and billing information on the client after the customer selects their payment method.

If you pass these fields, the shipping address should include valid data in line1, city, state, postal_code, and country. Similarly, billing details must include valid data in all of line1, city, state, postal_code, and country.

Confirm the PaymentIntent

Use stripe.confirmAffirmPayment to handle the redirect away from your page and to complete the payment. You must also pass a return_url to this function to indicate where Stripe redirects the user after they complete the payment on the Affirm website or mobile application.

On Affirm’s payments page, the customer selects the payment options available to them. See the overview page for more details. You can’t limit or pre-select payment options on the Affirm payments page—deferring this choice to the consumer maximizes their opportunity to transact with you.

script.js
// Redirects away from the client
stripe.confirmAffirmPayment(
  '{{PAYMENT_INTENT_CLIENT_SECRET}}',
  {
    payment_method: {
      // Billing information is optional but recommended to pass in.
      billing_details: {
        email: 'jenny@rosen.com',
        name: 'Jenny Rosen',
        address: {
          line1: '1234 Main Street',
          city: 'San Francisco',
          state: 'CA',
          country: 'US',
          postal_code: '94111',
        },
      },
    },

    // Shipping information is optional but recommended to pass in.
    shipping: {
      name: 'Jenny Rosen',
      address: {
        line1: '1234 Main Street',
        city: 'San Francisco',
        state: 'CA',
        country: 'US',
        postal_code: '94111',
      },
    },
    // Return URL where the customer should be redirected after the authorization.
    return_url: 'https://example.com/checkout/complete',
  }
).then(function(result) {
  if (result.error) {
    // Inform the customer that there was an error.
    console.log(result.error.message);
  }
});

When your customer submits a payment, Stripe redirects them to the return_url and includes the following URL query parameters. The return page can use them to get the status of the PaymentIntent so it can display the payment status to the customer.

When you specify the return_url, you can also append your own query parameters for use on the return page.

Parameter	Description
`payment_intent`	The unique identifier for the `PaymentIntent`.
`payment_intent_client_secret`	The client secret of the `PaymentIntent` object. For subscription integrations, this client_secret is also exposed on the `Invoice` object via `confirmation_secret`

When the customer is redirected back to your site, you can use the payment_intent_client_secret to query for the PaymentIntent and display the transaction status to your customer.

Test Affirm integration

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_action 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, click X in the top left corner. The PaymentIntent will transition from requires_action to requires_payment_method.

When redirected to the Affirm sandbox, Affirm may ask for the last four digits of your SSN. Affirm suggests using '0000' or '5678'.

OptionalSeparate authorization and capture

OptionalHandle the Affirm redirect manually

OptionalHandle post-payment events

OptionalDisplay payment method messaging on your website

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

Other than a payment being declined, for an Affirm PaymentIntent with a status of requires_action, customers are expected to complete the payment within 12 hours after they’re redirected to the Affirm site. If no action is taken after 12 hours, the PaymentMethod is detached and the PaymentIntent object’s status automatically transitions to requires_payment_method.

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
`payment_intent_payment_attempt_failed`	A generic failure indicating the Affirm checkout failed. Additional information may be available in the charge outcome reason.
`payment_method_provider_decline`	Affirm declined the customer’s payment. As a next step, the customer needs to contact Affirm for more information.
`payment_intent_payment_attempt_expired`	The customer never completed the payment on Affirm’s checkout page, and the payment session has expired. Stripe automatically expires Payment Intents that are not successfully authorized 12 hours after initial checkout creation.
`payment_method_not_available`	Affirm experienced a service related error and is unable to complete the request. Retry at a later time.
`amount_too_small`	Enter an amount within Affirm’s default transactions limits.
`amount_too_large`	Enter an amount within Affirm’s default transactions limits.

Some errors might have additional insight included in the charge outcome reason:

Outcome Reason	What this means
`generic_decline`	The default outcome reason for a payment error. This usually indicates that the partner declined the payment (for example, because of insufficient funds), the bank issuer declined the charge, the transaction included a high-risk purchase, or a similar reason. Stripe may not always receive a decline reason for these cases.
`affirm_checkout_canceled`	Either the customer has explicitly canceled the Affirm checkout or Affirm has rejected the customer’s loan eligibility. Stripe can’t distinguish the difference between these two types of events.