Manage Purchases

Overview

With the Transactions API, merchants can manage purchases through various states and integrate each of these actions in their order management system where they fulfill order, process payments, refund, and cancellations.

Capture and Update purchases

Capture purchase

Once an order is fulfilled, the CapturePurchase API is used to capture or settle the funds from your back-end systems. This endpoint requires the purchase_id returned from the CreatePurchase request.

The following example shows a capture request:

curl --request POST \
     --url https://www.affirm.com/api/partner/v1/transactions/PURCHASE-ARI-123/capture \
     --header 'Idempotency-Key: 0ddb9813-e62d-4370-93c5-476cb93038a9' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "order_id": "A1B2C3D4",
  "reference_id": "W1X2Y3Z4",
  "shipping_carrier": "USPS",
  "shipping_confirmation": "C12345678901234"
}
'

The response includes the total amount captured, including shipping and tax in cents, the time when purchase was created, the unique id for the purchase event, and the type of event.

{
  "amount": 20000,
  "created": "2019-01-01T00:00:00.000Z",
  "currency": "USD",
  "fee": 500,
  "fee_refunded": 500,
  "id": "A1B2C3D4",
  "reference_id": "W1X2Y3Z4",
  "type": "capture"
}

Update purchase

The UpdatePurchase endpoint allows merchants to update details, such as shipping information, for a specific purchase. The following example updates the shipping carrier to FedEx.

curl --request POST \
     --url https://www.affirm.com/api/partner/v1/transactions/PURCHASE-ARI-123 \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "shipping_carrier": "FedEx"
}
'

The response includes the same details as the capture request. The event type will show as updated for this this request.


Refund and Void purchases

Refund purchase

With the RefundPurchase endpoint, merchants can either fully or partially refund a purchase. The following request refunds $100 dollars from the original purchase.

curl --request POST \
     --url https://www.affirm.com/api/partner/v1/transactions/PURCHASE-ARI-123/refund \
     --header 'Idempotency-Key: 0ddb9813-e62d-4370-93c5-476cb93038a9' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"amount":10000}'

Void purchase

The VoidPurchase endpoint completely cancels a purchase.

curl --request POST \
     --url https://www.affirm.com/api/partner/v1/transactions/PURCHASE-ARI-123/void \
     --header 'Idempotency-Key: 0ddb9813-e62d-4370-93c5-476cb93038a9' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "reference_id": "W1X2Y3Z4"
}
'

Read and List purchases and purchase events

The following are example requests for ReadPurchase, ListPurchases, and ListPurchaseEvents

To retrieve a specific purchase by id, call ReadPurchase.

curl --request GET \
     --url https://www.affirm.com/api/partner/v1/transactions/PURCHASE-ARI-123 \
     --header 'accept: application/json'
curl --request GET \
     --url 'https://www.affirm.com/api/partner/v1/transactions?transaction_type=charge&before=A1B2C3D4&limit=10&before_date=2023-01-01' \
     --header 'accept: application/json'
curl --request GET \
     --url 'https://www.affirm.com/api/partner/v1/transactions/events?transaction_type=charge&transaction_event_type=capture&limit=25&after_date=2023-01-01' \
     --header 'accept: application/json'