Charge actions

Understand Affirm's charge actions

Overview

After creating a charge, you can manage it through various states and integrate each of these actions into your order management system where you fulfill orders and/or process payments, refunds, and cancelations.

📘

Learn more about the charge actions via our API Reference

  • Includes request/response examples
  • JSON-Object definitions
  • Attributes requirement

Read charge

With the Read charge API, you can use the charge_id to retrieve all checkout data and the charge status associated with a specific charge. Reading charge information is useful for updating your records or order management system with the current state of a charge before performing any actions on it. It can also keep your system in sync with Affirm if your staff is manually managing loans in the merchant dashboard.

You can read single or multiple charges. Note that if you don't specify a charge_id, the response includes a list of charges. You can define how the results are paginated using the limit, before, and after query parameters.

// 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"

Void

To cancel or delete an authorized charge, you can use the charge_id to void it. For example, when a user decides to cancel their order before it's fulfilled. Voiding an authorized charge does the following:

  • Permanently cancels a loan
  • Notifies the user that the transaction was canceled
curl https://sandbox.affirm.com/api/v2/charges/CHARGE_ID/void
     -X POST
     -u "(public_api_key):(private_api_key)"

Refund

Refund a charge based on the original purchase, similar to refunding a credit card transaction. Affirm automatically calculates all interest and fees corresponding to the refunded amount. You can also optionally refund part of a transaction by specifying an amount. For partial refunds, you can apply any amount of refunds so long as there is a positive balance on the loan.

Once a loan has been fully refunded, it can’t be reinstated. You can refund the customer using the Refund API or the Merchant Portal.

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": 50000}'

Update

Use the Update API to update a charge with new fulfillment or order information, such as shipping_confirmation, shipping_carrier, or order_id. Settlement reports associate your internal order IDs with specific Affirm charges.

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"}}}'