Skip to main content

Merchant Help

 

Affirm Merchant Help

Charge Management

The charge actions described on this page should all be integrated into your back-end order management system, where you would normally be fulfilling orders and processing payments/refunds/cancelations.

 

Read

GET /api/v2/charges/<charge_id>
  • Read the charge information for a specific charge, or all charges
  • Returns all of the checkout data along with current charge status
    • Status: authorized/captured/voided/refunded/partially-refunded
  • Useful for updating your records or OMS with the current state of a charge before charge actions are performed
  • Can keep your system in sync with Affirm if your staff will be manually managing loans in the Merchant Dashboard
Read request

Read a single charge: 

curl https://sandbox.affirm.com/api/v2/charges/CHARGE_ID/
     -X GET
     -u "public_key:private_key"

 

Read multiple charges: 

curl https://sandbox.affirm.com/api/v2/charges/?limit=5&before=1234-ABCD
     -X GET
     -u "public_key:private_key"

 

URL

 

If no <charge_id> is specified,  a list of charges will be returned, and you can define how the results are paginated using the query string parameters below:

Query String
limit
optional integer. Number of charges to be included in the response
before
optional string. Returns a list of charges that were created before the given charge ID.
after
optional string. Returns a list of charges that were created after the given charge ID.

Read response

{
   "id:ALO4-UVGR",
   "status": "auth",
   "created":"2016-03-18T19:19:04Z",
   "currency":"USD",
   "amount":6100,
   "auth_hold":6100,
   "payable":0,
   "void":false,
   "expires": "2016-04-18T19:19:04Z",
   "order_id":"JKLM4321",
   "events":[
      {
         "created":"2014-03-20T14:00:33Z",
         "currency":"USD",
         "id":"UI1ZOXSXQ44QUXQL",
         "transaction_id":"TpR3Xrx8TkvuGio0",
         "type":"auth"
      }
   ],
   "details":{
      "items":{
         "sweater-a92123":{
            "sku":"sweater-a92123",
            "display_name":"Sweater",
            "qty":1,
            "item_type":"physical",
            "item_image_url":"http://placehold.it/350x150",
            "item_url":"http://placehold.it/350x150",
            "unit_price":5000
         }
      },
      "order_id":"JKLM4321",
      "shipping_amount":400,
      "tax_amount":700,
      "shipping":{
         "name":{
            "full":"John Doe"
         },
         "address":{
            "line1":"325 Pacific Ave",
            "city":"San Francisco",
            "state":"CA",
            "zipcode":"94112",
            "country":"USA"
         }
      }
      "discounts": {
        "RETURN5": {
          "discount_amount":    500,
          "discount_display_name": "Returning customer 5% discount"
        },
        "PRESDAY10": {
          "discount_amount":    1000,
          "discount_display_name": "President's Day 10% off"
        }
      }
   }
}
  • id
  • status
  • created
  • currency
  • amount
  • auth_hold
  • payable
  • void
  • order_id
  • events
    • created
    • currency
    • id
    • transaction_id
    • type
  • details
    • items
      • product sku
        • sku
        • display_name
        • qty
        • item_type
        • item_image_url
        • item_url
        • unit_price
    • order_id
    • shipping_amount
    • tax_amount
    • shipping
      • name
        • full
      • address
        • line1
        • line2
        • city
        • state
        • zipcode
        • country
    • billing
      • name
        • full
      • address
        • line1
        • line2
        • city
        • state
        • zipcode
        • country
    • discounts
      • discount code
        • discount_amount
        • discount_display_name

 

Capture

POST /api/v2/charges/<charge_id>/capture

This captures the funds of an authorized charge, and is the same as capturing a typical credit card transaction.  

Once a loan is captured:

  • User receives a notice that the charge is captured.
  • User's first payment is due to Affirm in 30 days.
  • Affirm pays the merchants within 2-3 business days.
  • Full or partial refunds can be processed within 120 days.
Capture request

curl https://sandbox.affirm.com/api/v2/charges/CHARGE_ID/capture
     -X POST
     -u "(public_api_key):(private_api_key)"
     -H "Content-Type: application/json"
     -d '{"order_id": "JKLM4321", "shipping_carrier": "USPS", "shipping_confirmation": "1Z23223"}'
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. The tracking number for the shipment.

Capture response

{
    "fee": 600,
    "created": "2016-03-18T00:03:44Z",
    "order_id": "JKLM4321",
    "currency": "USD",
    "amount": 6100,
    "type": "capture",
    "id": "O5DZHKL942503649",
    "transaction_id": "6dH0LrrgUaMD7Llc"
}
fee
integer. Portion of the captured amount that represents the merchant fee.
created
string. Timestamp for this event.
order_id
string. The order ID in your order management system.
amount
integer. Amount captured, including any fees.
type
string. Will always be "capture".
id
string. The ID for this API event.
transaction_id
string. The ID for the charge transaction.

 

Capture error handling

Error HTTP status Message to display Action to take
Captured failed 400    
Unauthorized 401    
Authorization expired 401    

Void

POST /api/v2/charges/<charge_id>/void

This cancels an authorized charge. For example, when a user decides to cancel their order before it's fulfilled.

Once a loan is voided:

  • It is permanently canceled and cannot be reauthorized.
  • User receives a notice that the transaction is canceled.
Void request

curl https://sandbox.affirm.com/api/v2/charges/CHARGE_ID/void
     -X POST
     -u "(public_api_key):(private_api_key)"
URL

Void response

{
  "type": "void",
  "id": "N5E9OXSIDJ8TKZZ9",
  "transaction_id": "G9TqohxBlRPWTGB2",
  "created": "2014-03-17T22:52:16Z",
  "order_id": "JLKM4321"
}
type
string. Always 'void'.
id
string. ID for this API event.
transaction_id
string. Transaction ID for this charge event.
created
string. Timestamp for this event.
order_id
optional string. Your internal order ID.

 

Void error handling

Error HTTP status Message to display Action to take
Authorization failed 400    
Unauthorized 401    
Checkout_token expired 401    

 

Refund

POST /api/v2/charges/<charge_id>/refund
  • You can apply any amount of refunds on a charge so long as there is a positive balance on the loan. 
  • Once a loan is fully refunded it cannot be reinstated.
  • Refunds can only be applied within 120 days of capturing the charge.
  • The amount you refund is based upon the original purchase price, just as if it was a normal credit card transaction. Interest and fees corresponding to the refunded amount are all automatically calculated on Affirm's end.
Refund request

curl https://sandbox.affirm.com/api/v2/charges/CHARGE_ID/refund \
     -X POST
     -u "(public_api_key):(private_api_key)"
     -H "Content-Type: application/json"
     -d '{"amount": 500}'
URL
Data
amount
optional integer. The amount to be refunded. If this parameter is missing or null, then by default the remaining loan balance will be refunded.

Refund response

{
  "created": "2014-03-18T19:20:30Z",
  "fee_refunded": 15,
  "amount": 500,
  "type": "refund",
  "id": "OWA49MWUCA29SBVQ",
  "transaction_id": "r86zdkHONPcaiVJJ"
}
created
string. Timestamp for this event.
fee_refunded
integer. Portion of the refunded amount that is subtracted from the merchant fee.
amount
integer. Amount refunded, including any fees.
type
string. Will always be "refund".
id
string. ID for this API event.
transaction_id
string. ID for this charge event.

 

Refund error handling

Error HTTP status Message to display Action to take
Authorization failed 400    
Unauthorized 401    
Checkout_token expired 401    

 

Update

POST /api/v2/charges/<charge_id>/update
  • Update a charge with new shipping, order information or shipping address
    • Shipment tracking number
    • Shipping carrier
    • Order ID
    • Shipping address
  • Shipping information is used by the Affirm customer service staff to see the fulfillment/delivery status of an order
  • Order ID is used in reconciliation reports and other places where Affirm charges need to be associated with internal order IDs
  • Shipping address is used to validate and update the shipping address in Affirm after the order is placed. If shipping address provided in the update request fails validation, an error is returned and the shipping address is not updated.
Update request

curl https://sandbox.affirm.com/api/v2/charges/CHARGE_ID/update
     -X POST
     -u "(public_api_key):(private_api_key)"
     -H "Content-Type: application/json"
     -d '{"order_id": "JLKM4321", "shipping_carrier": "USPS", "shipping_confirmation": "1Z23223", "shipping": {"name":{ "full": "John Doe"},"address": {"line1": "325 Pacific Ave", "state": "CA", "city": "San Francisco", "zipcode": "94111", "country": "USA"}}}'
URL
Data
order_id
optional string. Your internal order ID
shipping_carrier
optional string. The shipment carrier (e.g., "UPS").
shipping_confirmation
optional string. The shipment tracking number.
shipping
optional object. Customer shipping information.
 

Update response

{  
   "created":"2016-11-30T21:07:47Z",
   "order_id":"JLKM4321",
   "shipping_confirmation":"1Z23223",
   "shipping":{  
      "name":{  
         "full":"John Doe"
      },
      "address":{  
         "city":"San Francisco",
         "state":"CA",
         "zipcode":"94111",
         "line1":"325 Pacific Ave",
         "country":"USA"
      }
   },
   "shipping_carrier":"USPS",
   "type":"update",
   "id":"EILMLQLZPGC742HO"
}
created
string. Timestamp for this event.
id
string. ID for this API event.
order_id
optional string. Your internal order ID.
shipping_carrier
optional string. Shipment carrier (e..g, 'UPS').
shipping_confirmation
optional string. Shipment tracking number. 
shipping
optional object. Customer shipping address information.