Charges

Retrieve charges created from charge intents. A charge is the settled record of a successful payment.

export FRAME_API_KEY='sk_sandbox_...'

The Charge object

Attributes
idstring

Unique identifier for the charge

objectstring

Object type identifier. Always charge.

amountinteger

Amount charged in cents

currencystring

Three-letter ISO currency code

statusstring

Charge status. One of pending, succeeded, or failed.

failure_codeenum

Machine-readable reason the charge failed. One of account_closed, approve_with_id, authentication_required, call_issuer, card_not_enrolled, card_not_supported, card_velocity_exceeded, cardholder_name_mismatch, currency_not_supported, debit_not_authorized, do_not_honor, do_not_try_again, duplicate_transaction, expired_card, fraudulent, generic_decline, incorrect_cvc, incorrect_number, incorrect_pin, incorrect_zip, insufficient_funds, invalid_account, invalid_amount, invalid_cvc, invalid_expiry_month, invalid_expiry_too_far, invalid_expiry_year, invalid_number, invalid_pin, issuer_not_available, lost_card, merchant_blacklist, new_account_information_available, no_account, no_action_taken, not_permitted, offline_pin_required, online_or_offline_pin_required, payment_method_single_use, pickup_card, pin_try_exceeded, processing_error, reenter_transaction, restricted_card, revocation_of_all_authorizations, revocation_of_authorization, security_violation, service_not_allowed, stolen_card, stop_payment_order, testmode_decline, transaction_not_allowed, try_again_later, unsupported_card_network, or withdrawal_count_limit_exceeded.

livemodeboolean

true if live mode, false if test mode

createdinteger

Unix timestamp of creation

charge_intent_idnullable string

ID of the charge intent that created this charge

THE CHARGE OBJECT
{
  "id": "b72fce52-eb12-5704-91a4-e3da890fb648",
  "object": "charge",
  "amount": 2000,
  "currency": "usd",
  "status": "succeeded",
  "failure_code": null,
  "livemode": false,
  "created": 1721010605,
  "charge_intent_id": "a70cd72f-e74a-40f2-96a2-3f60714aac4a"
}

Get charge

Retrieve a charge by ID

Path parameters
idstringrequired

Charge ID

Returns

Successful response

GET/v1/charges/{id}
curl --request GET \
  --url https://api.framepayments.com/v1/charges/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "00000000-0000-4000-8000-000000000001",
  "currency": "usd",
  "failure_code": null,
  "failure_message": null,
  "failure_category": null,
  "description": null,
  "status": "succeeded",
  "acquirer_reference_number": null,
  "authorization_code": null,
  "object": "charge",
  "payment_method_details": {
    "id": "00000000-0000-4000-8000-000000000002",
    "customer_id": null,
    "account_id": null,
    "billing": {
      "id": "00000000-0000-4000-8000-000000000003",
      "city": "Tyronebury",
      "country": "US",
      "state": "CA",
      "postal_code": "70896",
      "line_1": "46131 Yundt Gateway",
      "line_2": "Suite 224",
      "livemode": false,
      "type": "billing"
    },
    "type": "card",
    "object": "payment_method",
    "created": 1745107200,
    "updated": 1745107200,
    "livemode": false,
    "status": "active",
    "card": {
      "brand": "visa",
      "exp_month": "04",
      "exp_year": "30",
      "issuer": null,
      "currency": null,
      "segment": null,
      "type": null,
      "last_four": "4242",
      "instant_available": false,
      "instant_unavailable_reason": "card_not_debit",
      "instant_steer_to": "bank_account"
    }
  },
  "customer": "00000000-0000-4000-8000-000000000004",
  "account": null,
  "account_id": null,
  "payment_method": "00000000-0000-4000-8000-000000000002",
  "amount": 1000,
  "amount_captured": 0,
  "amount_refunded": 0,
  "created": 1745107200,
  "updated": 1745107200,
  "livemode": false,
  "captured": true,
  "disputed": false,
  "charge_intent": "00000000-0000-4000-8000-000000000005",
  "refunded": false,
  "net_amount": 926
}

Get charge trace

Retrieve a charge with ledger/trace information

Path parameters
idstringrequired

Charge ID

Returns

Charge with trace data

GET/v1/charges/{id}/trace
curl --request GET \
  --url https://api.framepayments.com/v1/charges/a70cd72f-e74a-40f2-96a2-3f60714aac4a/trace \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "00000000-0000-4000-8000-000000000001",
  "currency": "usd",
  "failure_code": null,
  "failure_message": null,
  "failure_category": null,
  "description": null,
  "status": "succeeded",
  "acquirer_reference_number": null,
  "authorization_code": null,
  "object": "charge",
  "payment_method_details": {
    "id": "00000000-0000-4000-8000-000000000002",
    "customer_id": null,
    "account_id": null,
    "billing": {
      "id": "00000000-0000-4000-8000-000000000003",
      "city": "Kandacebury",
      "country": "US",
      "state": "CA",
      "postal_code": "15820-5335",
      "line_1": "129 Kathleen Plain",
      "line_2": "Apt. 588",
      "livemode": false,
      "type": "billing"
    },
    "type": "card",
    "object": "payment_method",
    "created": 1745107200,
    "updated": 1745107200,
    "livemode": false,
    "status": "active",
    "card": {
      "brand": "visa",
      "exp_month": "05",
      "exp_year": "30",
      "issuer": null,
      "currency": null,
      "segment": null,
      "type": null,
      "last_four": "4242",
      "instant_available": false,
      "instant_unavailable_reason": "card_not_debit",
      "instant_steer_to": "bank_account"
    }
  },
  "customer": "00000000-0000-4000-8000-000000000004",
  "account": null,
  "account_id": null,
  "payment_method": "00000000-0000-4000-8000-000000000002",
  "amount": 1000,
  "amount_captured": 0,
  "amount_refunded": 0,
  "created": 1745107200,
  "updated": 1745107200,
  "livemode": false,
  "captured": true,
  "disputed": false,
  "charge_intent": "00000000-0000-4000-8000-000000000005",
  "refunded": false,
  "net_amount": 926,
  "ledger": {
    "journals": []
  }
}