Building a Direct API Integration - Step 3: Testing Your Integration

Contents 

 

 

Implementation process

 

Direct API integrations require some coding. There are a few things you must do before you can deploy it to your production account and go live:

  1. Retrieving your API keys
  2. Development
  3. Testing your integration
    • Initiate checkout
    • Authorize charges
      • Receiving the checkout token
      • Authorizing the charge
      • Authorization request format
    • Manage charges
      • Capture + capture request format
      • Void + void request format
      • Refund + refund request format
  4. Deploying your integration

 

We'll cover the items that are bolded in this article. We'll cover the other steps in the other guide steps.

 

Back To Top

 

Testing your integration

 

 

There are a few steps you must follow before going live in order to finish the Direct API integration process.

 

1. Initiate a checkout

The steps below provide a high-level overview of how to initiate a checkout with the Affirm payment method.

 

  1. Once the Affirm.js embed code has been added, the following commands will be used to create and send the checkout object to our API endpoints.
    • affirm.checkout({ }) creates and stores the checkout object.
    • affirm.checkout.open() sends the checkout object to our checkout API.
  2.  The checkout object is the data payload that gets POSTed to the Affirm API to initialize checkout.

  3. The different components of the checkout object are described below:
    6._Checkout_component_objects.png
  4. After creating the checkout object, call affirm.checkout.open(); This does the following:
    • Sends the checkout object to our checkout API.
    • Redirects the customer to the Affirm checkout process on the affirm.com domain or shows them an Affirm modal.
    • Validates the required data in the checkout object.


For full documentation on the Affirm checkout initiation, click here.

 

Back To Top

 

2. Authorize charges

The topics below provide a high-level overview of how to authorize the charge once the user has completed the loan application and confirmed their loan terms.

 

 

Receiving the checkout token

After a checkout is initiated 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. 

 

Click here for more information on choosing a method. To receive the checkout token, you’ll need to add server-side scripting that reads the HTTP request on your page.

 

While developing and testing in our sandbox, step through the checkout process in your browser to trigger the HTTP request with the checkout token.

 

Note: When testing the checkout process, enter 1234 as your verification code as we don’t send text messages from our sandbox.

 

Follow these steps to receive the checkout token:

  1. Initiate checkout to access the Affirm account creation screen.
  2. If you have an existing account, click on sign in.
  3. If you don’t have an existing account, create one with the following:
    • Any first and last name.
    • An email address with a valid format.
    • A valid US cell phone number (you do not need access to this number) that you will use in all subsequent checkout attempts.
    • A birth date older than 18 years old.
    • Any four digits.

     4. Enter 1234 for the verification code and click VERIFY CODE.

     5. Complete checkout flow and click CONFIRM LOAN.

 

Back To Top

 

Authorizing the charge

After completing the checkout flow and receiving the checkout token, you'll authorize the charge. Authorizing generates an 8-character charge ID that you’ll use to reference the charge moving forward. You must authorize a charge to fully create it. A charge is not visible in the merchant dashboard until you authorize it. 

 

After authorizing the charge and receiving a success (200) response with the authorized amount, your page (at user_confirmation_url) should:

  • Validate that authorized amount equals the order total.
  • Redirect the customer to the order confirmation page or display an order confirmation message.
  • Store the charge ID.
  • Mark the order payment as pending.

 

If there is an error (non-200) response when authorizing the charge or the authorized amount does not equal the order total:

      • Notify the customer that the payment failed.
      • Redirect the customer to the payment method selection screen.

 

Authorization request format

URL

 

Options

  • Type: POST
  • Authorization: Basic
  • Content type: application/JSON
  • Data: JSON string

 

Data

  • checkout_token required string
    • Unique token used to authorize a charge. Received to the user_confirmation_url
  • order_id optional string.
    • Identifies the order within the merchant's order management system that this charge corresponds to. Only returned in the response if included in the request.


For full documentation on loan authorization, click here.

 

Back To Top

 

3. Manage charges (capture, void, refund)

While it is recommended to integrate these functions (capture, void, refund) into your order management system, it is not required in order to launch; once the loan has been authorized, these actions can be processed through the Affirm dashboard.

 

Capture

All authorized charges need to be captured in order to transfer funds to the merchant, similar to capturing a credit card transaction.

 

Note: The charge must be captured within 30 days or the loan authorization will expire. After capturing the loan:

  • We notify the customer that the loan has been captured and that their first payment is due to Affirm in 30 days.
  • Affirm pays the merchant within 2-3 business days.
  • Affirm can process full or partial refunds within 120 days.

 

Capture request format

URL

 

Data

  • order_id optional string
    • Your internal order id. This is stored for your own future reference.
  • shipping_carrier optional string
    • The shipping carrier used to ship the items in the charge.
  • shipping_confirmation optional string

https://jsfiddle.net/3hoevrjw/1/embedded/html

 

 

 

Void

Void a charge to cancel an authorized charge. For example, void a charge when a customer decides to cancel their order before you fulfill it. After voiding a charge:

      • We permanently cancel the loan, and no one can re-authorize it.
      • We notify the customer about the cancellation.

 

Void request format

https://jsfiddle.net/3hoevrjw/2/embedded/html

 

 

 

Refund

Refund a charge based on the original purchase, similar to refunding a credit card transaction. Affirm automatically calculates all interest and fees corresponding to the refunded amount. For partial refunds, you can apply any amount of refunds so long as there is a positive balance on the loan.

 

Once a loan has been fully refunded, it can’t be reinstated.

 

Refund request format

URL

 

Data

  • amount optional integer.
  • The amount to be refunded in USD cents ($500 = 50000). If this parameter is missing or null, then by default the entire remaining loan balance will be refunded (full refund).

https://jsfiddle.net/3hoevrjw/4/embedded/html


For full documentation on Affirm's order management functions, click here.

 

Back To Top

<< Step 2: Development

>> Step 4: Deploying Your Integration