Skip to main content

Merchant Help

 

Affirm Merchant Help

Receive Checkout Token

Summary

After a user has successfully completed the Affirm checkout flow, the customer is returned to the "user_confirmation_url" that is provided to Affirm in the checkout object. Affirm will POST a "checkout_token" to this endpoint. This is the token used to Authorize a particular charge, completing the checkout. 

Authorization flow
  1. User successfully completes an Affirm checkout & confirms their loan.
  2. User is redirected from Affirm.com to the user_confirmation_url via the HTTP method defined by user_confirmation_url_action 
  3. The HTTP request to the user_confirmation_url contains the checkout_token in the request parameters.
  4. The page at the user_confirmation_url reads the request form and temporarily stores this checkout_token.
  5. The page at the user_confirmation_url sends a POST request to the Affirm API authorization endpoint (/api/v2/charges/) with the saved checkout_token.
  6. The page at the user_confirmation_url expects a response from the Affirm API with the charge information
  7. The page at the user_confirmation_url validates that the authorized amount is equal to the order total and that the Order_ID matches the order
  8. If the amount and order_id are valid, the page at the user_confirmation_url stores the 'id' from the returned charge object. This Charge ID is attached to the order; and is used to uniquely identify the order. All future charge actions require this identifier.
  9. Order is created.
  10. Customer is presented with order confirmation page/message.
Define the user_confirmation_url

When assembling the checkout object, you will have to define a user_confirmation_url. This URL should point to your page that is expecting the checkout_token and then attempts charge authorization.

The merchant object contains the user_confirmation_url and user_cancel_url, which represent the two possible outcomes of the checkout attempt. The user goes to the confirmation_url if the user is approved and confirms their loan. The user goes to the cancel_url in all other cases (voluntary cancel, credit decline, identity verification issue, etc.). 

"merchant": {
    "user_confirmation_url":    "https://merchantsite.com/confirm",
    "user_cancel_url":          "https://merchantsite.com/cancel",
    "user_confirmation_url_action": "POST", // or "GET"
    "name":          "External Company Name"
     },
user_confirmation_url
required url. URL that the customer is sent to if they successfully complete the Affirm checkout flow. 
A checkout_token will be sent to this URL in the POST request, and that checkout_token should be used to authorize the charge before the user is redirected to the order confirmation page.
Analytics tags are other query string parameters can be persisted here as well. Read more here.
user_cancel_url
required url. URL that the customer is sent to if the customer exits the Affirm checkout flow.
This is the same if the user voluntarily cancels or closes the window before completion, or if the user is denied. You should setup the cancel_url to be the checkout payment page, and you can also append analytics tags to the URL to help you identify who you may want to reach out to about alternative payment methods or reapplying. 
Analytics tags are other query string parameters can be persisted here as well. Read more here.
user_confirmation_url_action
optional string. Accepted values are: 'GET', 'POST'. Defaults to 'POST'. Read more here.
name
optional string. If you have multiple sites operating under a single Affirm account, you can override the external company/brand name that the customer sees. This affects all references to your company name in the Affirm UI.

Confirmation page logic

The logic on your user_confirmation_url should be as follows:

  1. Expect checkout_token in HTTP request parameters
  2. Use checkout_token to make an authorization request to Affirm's API
    • If successful (200) response:
      • Validate that authorized amount equals the order total
        • If authorized amount is valid
          • Redirect user to order confirmation page or display order confirmation message.
          • Store charge ID.
          • Mark order payment as pending.
        • If authorized amount is invalid
          • Message to the user that the payment failed
          • Redirect user to payment method selection screen in the checkout flow
    • If error (non-200) response (edge case):
      • Message to the user that the payment failed
      • Redirect user to payment method selection screen in the checkout flow
Receive the checkout_token

To receive the checkout_token, you will have to setup your page with server-side scripting that reads the HTTP request parameters. This can be accomplished using any server-side scripting language, such as PHP, ASP, Perl, Ruby, etc. For more specific instructions based on your web application language, please contact mts@affirm.com for help.