Managing Applications

Overview

The Purchase API offers a comprehensive range of capabilities to manage loan applications, making the application process streamlined for partners. Each endpoint is designed to handle specific aspects of loan application management, ensuring efficiency and security throughout the process. This enables various operations, including creating new applications, authorizing purchases, retrieving detailed application information, and updating existing applications.

Create an Application

Use the CreateApplication endpoint to create and underwrite an application. Creating an application requires the following attributes:

  • items - an array of objects
    • display_name: The name of the item.
    • sku: The SKU (Stock Keeping Unit) of the item.
    • unit_price: Subtotal of the item, specified in cents.
    • qty: Quantity of the items in the current transaction.

The above items are required, but your application can include various parameters as inputs to collect for the underwriting process. Refer to the API Reference for detailed descriptions of the parameters.

The following example creates a application for the online purchase of a Queen mattress for a total of $720.

curl --request POST \
     --url https://www.affirm.com/api/partner/v1/applications \
     --header 'Country-Code: USA' \
     --header 'Idempotency-Key: 0ddb9813-e62d-4370-93c5-476cb93038a9' \
     --header 'Locale: en_US' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "shipping_address": {
    "street1": "650 California Street",
    "city": "San Francisco",
    "region1_code": "CA",
    "postal_code": "94108",
    "country_code": "US"
  },
  "items": [
    {
      "display_name": "Queen mattress",
      "sku": "SKU-1234",
      "unit_price": 70000,
      "item_url": "merchant.com/item",
      "quantity": "1"
    }
  ],
  "buyer_id": "BUYER-ARI-1234",
  "subtotal": 70000,
  "tax": 2000,
  "total": 72000,
  "currency": "USD",
  "checkout_experience": "online"
}
'

On success, Affirm returns the applicationId.

{
  "id": "APPLICATION-1"
}

Update an Application

To update an application, call the UpdateApplication endpoint and include the applicationId. You'll need the last 4 digits of the user's SSN collected when submitting an application. You See the example request below

curl --request PUT \
     --url https://www.affirm.com/api/partner/v1/applications/APPLICATION-ID-123 \
     --header 'Country-Code: USA' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"ssn4":"9500"}'

On success, Affirm returns a 200 response with the id of the updated application ad the status of the application update.


Retrieve an Application

The GetApplication endpoint retrieves the details of an application with a given applicationId. On success, this returns the application_decision as well as the planId and disclosuresId which you'll need for the AuthorizePurchases call. See the example response below.

{
  "application_decision": "application_approved",
  "buyer_id": "BUYER-ARI-1234",
  "order_id": "ORDER-ID-1234",
  "application_id": "APPLICATION-ID-123",
  "purchase_id": "PURCHASE-ID-1234",
  "plans": [
    {
      "id": "string",
      "disclosures": [
        {
          "id": "string",
          "type": "string",
          "html": "string"
        }
      ],
      "installments": [
        {
          "due_date": "string",
          "amount": 0
        }
      ],
      "frequency": "monthly",
      "interval": 2,
      "downpayment_amount": 1200,
      "apr": 8.66,
      "financing_type": "installment_loan",
      "required_info": [
        "check_ssn4"
      ],
      "interest_amount": 100.99
    }
  ],
  "metadata": {},
  "adverse_action_notices": [
    {
      "id": "string",
      "type": "string",
      "html": "string"
    }
  ]
}

Authorize Purchases

Call the AuthorizePurchases endpoint to authorize a specific amount of a purchase given an application approval. Authorizing purchases requires the following attributes:

  • application_id: The id of the approved application used to authorize a purchase. Returned by underwriting.
  • plan_id: The id of the plan chosen from the array in the application object.
  • `disclosures: Information regarding disclosures.
    • id: The id of disclosure provided in the application webhook.
    • type: The type field of the disclosure shown to the user. It is only necessary for loan terms disclosure.
  • autopay_enabled Determines if autopay is enabled for this particular purchase.

See an example of the AuthorizePurchases request below:

curl --request POST \
     --url https://www.affirm.com/api/partner/v1/purchases \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "autopay_enabled": true,
  "disclosures": [
    {
      "id": "53ed-b59f",
      "type": "disclosure1"
    }
  ],
  "application_id": "b59f-4d12",
  "plan_id": "8d80-01fd"
}
'

On success, Affirm returns a 201 response with the authorization_expiration and the transaction_event object with details about the purchase.

{
  "authorization_expiration": "2023-11-28T15:30:45Z",
  "id": "PURCHASE-ARI-456",
  "order_id": "ORDER-5678",
  "transaction_event": {
    "amount": 5000,
    "created": "2023-11-28T10:00:00Z",
    "currency": "USD",
    "fee": 200,
    "id": "TRANSACT-789",
    "type": "purchase"
  }
}