Skip to main content

Merchant Help

 

Affirm Merchant Help

Receive Checkout Token BETA

Redirect or Modal

If you've initiated the modal checkout flow, you have the option of defining a success and fail callback function to receive the checkout_token at runtime. Otherwise, the checkout_token will be passed in the request body to the user_confirmation_url that you've defined.

user_confirmation_url

The customer's browser is redirected to the user_confirmation_url if the default redirect checkout flow is used. Otherwise, if using the modal checkout, the modal checkout window will display the user_confirmation_url. The checkout_token is always passed in the request to the user_confirmation_url you've defined.

Therefore, if you're using the modal checkout flow, you can receive the checkout_token through either the JavaScript callback, or the user_confirmation_url request parameters.

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

 

Modal
Authorization flow
  1. User successfully completes an Affirm checkout & confirms their loan.
  2. Success callback is triggered from the Affirm runtime.
  3. The function defined as the success callback will be passed a success_object, which contains the checkout_token.
  4. The page that initiated checkout will be passing the checkout_token to another function, which is responsible for authorizing the charge with this checkout_token. That function is likely going to do an asyncronous call an page/endpoint on your domain that will do the actual HTTP request.
  5. A server-side script sends a POST request to the Affirm API authorization endpoint (/api/v2/charges/) with the saved checkout_token.
  6. The server-side script expects a response from the Affirm API with the charge object, including the charge 'id'. A 200 status and a charge 'id' indicates a successful authorization.
  7. The server-side script 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 server-side script takes 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 modal callback functions

When using the modal checkout flow, you should define JavaScript callbacks when checkout is initiated. The function calls are defined in object that's passed to the checkout.open() function. The functions that you define

{
    onFail: function(){yourAffirmCancelFunction()},
    onSuccess: function(succes_object){yourAffirmSuccessFunction(succes_object)}
}
onFail
optional function. Called when the user exits from, cancels, or is declined in the Affirm checkout flow
onSuccess
optional function. Called when the user confirms their approved Affirm loan. A success_object is passed through to your success function, which contains the checkout_token.

Receive the checkout_token

{
    checkout_token:"ZO1E88NAF8SRTYMU"
    created:"2017-09-15T23:51:16.600370Z"
}
checkout_token
string. This checkout_token is used to authorize the charge.
created
timestamp. UTC timestamp of when the confirmation action took place.

To receive the checkout_token, you will have to setup your success callback function to read the checkout_token from the success_object. The checkout_token then needs ot be passed onto a server-side authorization script, as described below.

An example success function is found below.

Authorization script logic

The logic of your server-side authorization script should be as follows:

  1. Expect checkout_token in HTTP request parameters from your client-side success function.
  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