Skip to main content

Merchant Help

 

Affirm Merchant Help

Charge Authorization

POST /api/v2/charges
Summary

Charge authorization occurs after a user has successfully completed the Affirm checkout flow and returns back to the merchant site. Authorizing the charge generates the charge ID that will be used to reference this charge moving forward. A charge is not fully created before being authorized, and thus is not visible in the 'read charge' response, nor in the User/Merchant Dashboard.

Authorization request

curl https://sandbox.affirm.com/api/v2/charges/
     -X POST
     -u "<public_api_key>:<private_api_key>"
     -H "Content-Type: application/json"
     -d '{"checkout_token": "<checkout_token>","order_id": "JKLM4321"}'
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.

Authorization response

The response to your request will contain the full charge response object, which includes all of the information that was submitted when you initialized checkout in addition to the charge and transaction-level identifiers.

The only two pieces of information you need to parse from this charge response object are the 'amount' and the charge 'id' (highlighted below):

{
   "id:ALO4-UVGR",
   "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
  • 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

 

  • Validate that the authorized amount equals the order total amount
  • If amount is valid, store the (charge) 'id' to reference the charge when performing the various charge actions: capture, void, refund, and update.
Authorization error handling

If the authorization request fails for some reason, you will setup error handling to block order creation and direct the user back to payment method selection.

Error HTTP status Message to display Action to take
Authorization failed 400 "There was an issue authorizing your Affirm loan. Please check out again or use a different payment method." Redirect user back to payment method selection.
Unauthorized 401 "There was an issue authorizing your Affirm loan. Please check out again or use a different payment method." Redirect user back to payment method selection.
Checkout_token expired 401 "There was an issue authorizing your Affirm loan. Please check out again or use a different payment method." Redirect user back to payment method selection.