Manage Repayments

Payment Instrument APIs

The following section covers the CreatePaymentInstrument, ListPaymentInstruments, and DeletePaymentInstrument APIs. It details how to create new payment instruments, list all instruments associated with a buyer, and delete specific payment instruments.

Create payment instrument

The CreatePaymentInstrument endpoint is designed to create a new payment instrument for a buyer. This endpoint is essential for setting up payment instruments, such as cards, for various purposes including auto-pay, down payments, or initial payments.

The request requires details like buyer ID, card information, and billing address.

curl --request POST \
     --url https://www.affirm.com/api/partner/v1/instruments \
     --header 'Country-Code: United States' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "card",
  "buyer_id": "BUYER-ARI-1234",
  "name": "Suzie Store",
  "card_number": "4111111111111111",
  "expiration": "0425",
  "cvc": "852",
  "zipcode": "94561"
}
'

Upon successful execution, the response includes a unique identifier for the newly created payment instrument.

{
  "id": "INSTRUMENT-ARI-1"
}

List payment instruments

The ListPaymentInstruments endpoint is useful for managing and reviewing multiple payment instruments linked to a buyer. By retrieving a list of all payment instruments associated with the buyer, this endpoint streamlines the process and makes it easier to keep track of transactions.

In the following request uses the buyer_id query parameter to retrieve the payment instruments for a particular buyer.

curl --request GET \
     --url 'https://www.affirm.com/api/partner/v1/instruments?buyer_id=BUYER-ARI-1234' \
     --header 'accept: application/json'

The response includes an array of objects, each representing a payment instrument associated with the specified buyer.

{
  "payment_instruments": [
    {
      "id": "INSTRUMENT-123",
      "card_number": "1111",
      "card_type": "credit",
      "network": "Visa",
      "expiration": "12/25"
    },
    {
      "id": "INSTRUMENT-456",
      "card_number": "2222",
      "card_type": "debit",
      "network": "MasterCard",
      "expiration": "08/24"
    }
  ]
}

Delete payment instrument

The DeletePaymentInstrument endpoint allows for removing a specific payment instrument associated with a buyer. This functionality is essential for managing and updating payment instruments, mainly when a particular instrument is no longer needed or valid.

In the following request, the instrument_id in the URL specifies the payment instrument to be deleted.

curl --request DELETE \
     --url https://www.affirm.com/api/partner/v1/instruments/INSTRUMENT-ARI-1 \
     --header 'accept: application/json'

On success, Affirm returns a 200 response indicating that the payment instrument was deleted successfully,

Autopay

This section covers the EnableAutopay and DisableAutopay endpoints, focusing on activating or deactivating automatic payments for purchases using designated payment instruments, thus offering flexibility and control over recurring or one-time payment arrangements.

Enable autopay

The EnableAutopay endpoint automates payments for specific purchases with a designated payment method, ensuring timely payment for recurring and one-time purchases.

curl --request POST \
     --url https://www.affirm.com/api/partner/v1/purchases/PURCHASE-ARI-123/autopay \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "disclosures": {
    "evidence": "disclosure.html"
  },
  "instrument_id": "INSTRUMENT-ARI-1"
}
'

This request authorizes autopay for purchase PURCHASE-ARI-123 using INSTRUMENT-ARI-1 and includes the HTML content of the disclosure for payment authorization consent.

Upon successful execution, the API returns a 200 status code, confirming the activation of autopay.

Disable autopay

The DisableAutopay endpoint deactivates the autopay feature for a specified purchase.

curl --request DELETE \
     --url https://www.affirm.com/api/partner/v1/purchases/PURCHASE-ARI-123/autopay \
     --header 'accept: application/json'

This request disables the autopay functionality for PURCHASE-ARI-123.

On success, Affirm returns a 200 response indicating that autopay was disabled.

Creating a payment

This section delves into the CreatePayment endpoint, outlining the process of initiating a payment for a buyer.

Create payment

This following request initiates a payment of $25.00 (2500 cents) for the PURCHASE-ARI-123 using the payment instrument INSTRUMENT-ARI-1.

curl --request POST \
     --url https://www.affirm.com/api/partner/v1/payments \
     --header 'Country-Code: USA' \
     --header 'Idempotency-Key: 0ddb9813-e62d-4370-93c5-476cb93038a9' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "disclosures": {
    "evidence": "disclosure.html"
  },
  "currency": "USD",
  "purchase_id": "PURCHASE-ARI-123",
  "buyer_id": "USER-ARI-123",
  "instrument_id": "INSTRUMENT-ARI-1",
  "amount": 2500
}
'

The response includes the id of the payment transaction and its state, which indicates whether the payment was successful, pending, submitting, or failed. In this case, the state is successful, indicating the payment was processed successfully.

{
  "id": "PAYMENT-ARI-12",
  "state": "successful"
}

Retrieve Purchases

In this section, we will go over the GetPurchase and ListPurchases endpoints. These endpoints retrieve detailed information about a specific purchase and obtain a comprehensive, paginated list of all purchases made.

Get purchase

The GetPurchase endpoint provides detailed information about a purchase, including financial details, status, and payment timeline. This endpoint is essential for tracking individual purchases and understanding their current state.

curl --request GET \
     --url https://www.affirm.com/api/partner/v1/purchases/PURCHASE-ARI-123 \
     --header 'accept: application/json'

The response contains comprehensive details about the specified purchase, including financial amounts, status, timeline, and other relevant metadata.

{
  "id": "PURCHASE-ARI-123",
  "amounts": {
    "receivable": 25000,
    "interest_rebate": 2500,
    "charged_off": 0,
    "overdue": 0,
    "apr": "0.0",
    "refunded": 0,
    "financed": 20000,
    "paid": 10000,
    "original": 25000,
    "interest": 0,
    "total": 25000,
    "downpayment": 5000,
    "pending": 0,
    "payoff": 100000,
    "next_due_amount": 2500
  },
  "summary": {
    "created": "2020-03-18T03:16:02Z",
    "merchant_name": "Target",
    "status": "disputed",
    "date": "2020-03-19T03:16:02Z",
    "autopay_enabled": false,
    "payment_progress": "0.6",
    "plan_length": 3,
    "frequency": "monthly",
    "interval": 0,
    "autopay_instrument_id": "INSTRUMENT-ARI-1",
    "days": 3,
    "can_show_autopay": true,
    "can_pay": true
  },
  "disclosures": [
    {
      "id": "disclosure-1",
      "type": "terms_and_conditions",
      "html": "<html>Disclosure Content</html>"
    }
  ],
  "timeline": [
    {
      "next_due": true,
      "date": "2020-03-18T03:16:02Z",
      "description": "Due",
      "amount": "50.00",
      "type": "invoice_due",
      "details": "no payment failure",
      "instrument_description": "VISA ···· 1881",
      "instrument_type": "VISA",
      "instrument_last_four": "1881"
    }
  ],
  "authorization_expiration": "2020-03-18T03:16:02Z",
  "currency": "USD",
  "transfer_counter": "1",
  "metadata": {
    "secondary_id": "id_1234"
  }
}

List Purchases

The ListPurchases endpoint enables users to fetch a paginated list of purchases made by a specific buyer. This functionality is essential for tracking and managing multiple transactions, offering a comprehensive view of a buyer's purchase history.

The following fetches up to 10 purchases made by the buyer BUYER-ARI-1234, listing those made before the transaction identified by TRANS-ARI.

curl --request GET \
     --url 'https://www.affirm.com/api/partner/v1/purchases?buyer_id=BUYER-ARI-1234&limit=10&before=TRANS-ARI' \
     --header 'Affirm-Locale: en_US' \
     --header 'accept: application/json'

The response includes a count of the returned purchases and the paginated data with details of each purchase.

{
  "count": 1,
  "data": [
    {
      "created": "2020-03-18T03:16:02Z",
      "merchant_name": "Target",
      "status": "disputed",
      "date": "2020-03-19T03:16:02Z",
      "autopay_enabled": false,
      "payment_progress": "0.6",
      "id": "PURCHASE-ARI-123",
      "next_due_amount": 5000
    }
  ],
  "prev": "https://example.com/prev_purchase",
  "next": "https://example.com/next_purchase"
}

Disclosures

Use GenerateDisclosure to create post-purchase disclosures for transactions. This endpoint generates and retrieves disclosure documents, ensuring compliance and transparency in Affirm purchases.

Generate disclosure

The following request generates a disclosure document for the purchase PURCHASE-ARI-123 and for the buyer USER-ARI-123.

curl --request POST \
     --url https://www.affirm.com/api/partner/v1/disclosures \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "payment_authorization_installment_autopay",
  "purchase_id": "PURCHASE-ARI-123",
  "buyer_id": "USER-ARI-123"
}
'

The response contains the id of the created disclosure and its html content, which is the actual disclosure document in HTML format, ready to be rendered or displayed as needed

{
  "id": "DISCLOSURE-1234",
  "html": "<html>Disclosure Content</html>"
}