Device upgrades

Overview

For customers using Affirm to finance a smartphone, you can set up an integration in your billing system that allows consumers to upgrade to a new device. When a customer pays and reaches a certain loan balance on their existing phone, they can trade it in and upgrade to a new phone.

Quickstart

Enabling your customers to upgrade their smartphones is easy with Affirm. If you already have an existing integration with our Direct API, you only need to do the following to enable device upgrades for your customers:

1. Use the Read charge progress endpoint to retrieve the customer’s data from their existing loan and determine eligibility based on how much they've paid towards the loan.
2. Initiate a new charge for the upgraded phone.
3. Use the Refund charge endpoint to credit the remaining balance for the trade-in. 

The rest of this quickstart goes through setting up device upgrades in detail.

1. Retrieve charge progress details

Use the GET /api/v2/charges/{charges_ari}/progress endpoint to retrieve the customer's existing loan details.

Request

curl -X GET \
  https://sandbox.affirm.com/api/v2/charges/ALE5-YGRS/progress
  -u "public_key:private_key"

Response

When retrieving the customer’s loan details, the response includes the following information:

{
"loan_id": "ALE5-YGRS",
"total_loan_value": 75000,
"down_payment": 10000,
"paid_principal": 5000,
"paid_interest": 2500
}

2. Initiate a new loan

Use our Affirm Direct to initiate a loan for the customer’s new device.

3. Credit value of trade-in phone

If the customer is eligible for an upgrade and chooses to trade in their phone, you'll need to use the Refund API to credit the value of the phone. Use the amount parameter to specify the amount (in cents) to credit back to the customer. If this parameter is missing or null, the entire loan balance will be refunded.

Request

curl -X POST \
  https://sandbox.affirm.com/api/v2/charges/ALE5-YGRS/refund \
  -H 'Content-Type: application/json' \
  -u "public_key:private_key"
  -d '{"amount": 50000}'

Response

{
"created": "2019-08-03T19:00:10Z"
"fee_refunded": 0, 
"Amount": 50000,
"type": "refund",
"id": "QWA49MWUCA29SBVQ",
"transaction_id": "r86zdlcHOMBcaiVJK"
}