## Overview
Affirm's global integration allows you to deploy Affirm in multiple countries and regions by utilizing a universal domain `global.affirm.com` and API schema. With the introduction of a universal domain, it provides a seamless expansion into international markets.
## How it works
There are four steps to initiate the Affirm application:
Once the customer selects Affirm at checkout, the checkout initiation begins.
## Step 1: Embed Affirm.js
The integration with Affirm.js used for [promos](🔗) and checkout allows for a quick and simple way to implement interactive components of Affirm to your platform. Our global integration features extended parameters to reach international customers, which consist of an exposed `locale` and `country_code` field in the Affirm config.
### public_api_key
The API keys will differ for each country. Currently, the following countries are represented by individual API keys:
The United States
Canada
API Keys
Please ensure that the correct API keys are being used for your region.
### Locale
The `locale` parameter allows Affirm to identify which locale you are serving your site in for any particular user. For example, let's say that you are rendering your site in Canadian French; perhaps this occurred because the user's browser setting detected Canadian French. You can provide Affirm with the user's language setting by passing it in the `locale` parameter. Affirm will then read the locale and translate the pages accordingly, thus, matching the language the user had seen on your site. However, we will not attempt to read the user's locale directly.
### Country_code
The `country_code` parameter represents the country of legal incorporation of your store, which is shown to any given user. So, if you are showing your Canadian website/store to a user and you have a legal presence in Canada, you would pass `CAN` into the `country_code` parameter. This allows us to determine which regulations to abide by and which banks to partner with for this transaction.
Affirm's identity check
In the above scenario, if the user doesn't turn out to be a Canadian resident later in the Affirm checkout flow, they won't pass Affirm's identity check; they are ineligible to receive an Affirm loan.
Additionally, Affirm expects an “Alpha 3” [three-letter country code](🔗) for this parameter. If nothing is sent, Affirm will assume "USA".
### Supported values
Affirm supports the following combinations for these arguments:
| country_code | locale | Country default locale |
`USA` | `en_US` | `en_US` |
`CAN` | `en_CA` | `fr_CA` | `en_CA` |
The following will occur when a `locale` and/or `country_code` is not provided:
When a `
country_code` is _not_ provided, the `country_code` will default to `USA`.When a `
locale` is _not_ provided, the `locale` the default locale for the `country_code` from the above table will be used. Locale will fall back to `en_US` (English speaking US) if a `country_code` is also not provided
## Including the Affirm.js script
The script (as shown below) must be included in the <head> section on every page of your site.
The following URLs can be used for the AFJS `script`:
**Sandbox**: <https://cdn1-sandbox.affirm.com/js/v2/affirm.js>
**Production**: <https://cdn1.affirm.com/js/v2/affirm.js>
Once the `Affirm.js` is added to your site, you will gain access to methods within the Affirm object which then triggers multiple actions.
## Step 2: Render Affirm checkout
When using `Affirm.js`, merchants pass a [checkout object](🔗) during the checkout flow. You can create a `checkout` object and launch the Affirm checkout by utilizing the `affirm.checkout()` function.
For the global integration, merchants will pass an extended International Checkout Object and this schema can be used for all Affirm supported countries. Please see the extended fields in the example below:
For **"address"**, the expanded fields are as follows:
`
street1``
street2` (_optional_)`
region1_code``
postal_code`
Please make sure the following field is accurately populated within the root of the checkout object:
`
currency`
### Affirm.checkout() function
Calling the `affirm.checkout()` function initiates the following actions:
Sends the checkout object to the Affirm backend.
Redirects the customer to the Affirm checkout process on the Affirm domain or shows them an Affirm modal.
Validates the required data in the checkout object.
Additionally, the `checkout` object should be configured with the following items:
A `
user_confirmation_url` to redirect your customer to a confirmation page after they confirm their loan.A `
user_cancel_url` to redirect your customer to a cancellation page if they do not complete their loan application.The customer's billing/shipping address.
A description of their cart.
The code for currency is an ISO 4217 international [currency code](🔗).
## Step 3: Handle Callbacks
After you initiate a checkout and the customer confirms their Affirm loan, we send an `HTTP` request with the `checkout_token` to the URL you defined in the checkout object (`user_confirmation_url`). By default, Affirm sends this request via `POST`. However, you can configure the checkout object to have Affirm send this request via `GET`.
You choose how we send the `checkout_token` by setting the `user_confirmation_url_action` parameter in the checkout object.
Setting it to `
POST` sends the `checkout_token` in the body of the `HTTP` request (default setting).Setting it to `
GET` sends the `checkout_token` in the query string of the `HTTP` request.
Modal checkout
You can also retrieve the `
checkout_token` from a javascript callback if you set the metadata `mode` to `modal`. Learn more about [modal checkout](🔗).
## Step 4: Authorize
When a customer successfully completes a checkout, it is recorded as a new purchase attempt. This needs to be handled on your server-side to be fulfilled via our `Transactions` API.
For a higher level of understanding, this chart (as shown below) illustrates what occurs on Affirm’s end and the merchant’s end during a successful checkout.
### Transactions API
The global integration utilizes Affirm’s [Transaction API](🔗).
If you are currently using the Affirm [Charges API](🔗), please reference our [guide](🔗) to switch from Charges to Transactions. If you are currently using the non-global Affirm [Transactions API](🔗), please reference [this guide](🔗) to make global updates.
#### Country-code request header
To move outside of the United States, any API calls that are made to Affirm such as Auth, Capture Transaction, etc., need to include this custom `HTTP` header parameter to those requests:
`
country-code`
When the `country-code` parameter is used, it will be followed by the three-letter country code as shown below:
`
country-code: "CAN"`
The `country-code` parameter tells Affirm what country of legal incorporation is associated with the store where the user’s transaction was made, as well as what Affirm regional environment to route this request to. This is also an alpha-3 country code. If this parameter is missing, we will default to `USA`.
Any end-user disclosures or emails that may be associated with this API will be sent in the language associated with the locale sent to `Affirm.js` when the transaction was made. For example, if `‘fr_CA”` was passed to `Affirm.js` when this transaction was made, all emails and user communications associated with the APIs involved in this transaction will be shown in Canadian French.
### Authorization process
#### 1. Retrieve the `checkout_token`
Retrieve and save the `checkout_token` sent by Affirm via a `HTTP` request to the success callback.
#### 2. Authorize the `checkout_token`
Authorize the `checkout_token` by passing the value in the `transaction_id` parameter to /transactions within 24 hours.
#### 3. Save the returned id
After authorizing the transaction, save the `id` from the transaction object returned in the response.
## Error handling
Errors generated by the checkout request are presented on the page where checkout is initiated, in the form of a pop-up modal window. Specific messaging about the source of the error is presented in this modal (e.g., "Invalid phone number").
You may define a callback function when this error modal is closed, but currently that callback does not relay any event data specific to the error message that's displayed in the modal.
Here's an example of how this event callback would be defined:
Error descriptions
Some error descriptions _will_ change for the global configuration.