Cari Finance

Charges

A charge is one attempt to take a card payment. Charges created by a payment session or a payment link appear here as soon as they are made. All charge routes need a secret key.

Routes

  • GET /charges: your charges, newest first, in the mode (test or live) of the key. See Pagination.
  • GET /charges/{id}: one charge.
  • POST /charges: take a card payment directly with a Stripe card token. Most integrations should use payment sessions instead, which keep the amount out of the browser.
  • PUT /charges/{id}: change descriptive fields only: description, receipt_email, statement_descriptor, statement_descriptor_suffix. Amount, status and refunds can not be changed.
  • DELETE /charges/{id}: remove a charge that failed. A charge that took money, is still pending, or has refunds or disputes is the record of real money and is kept; deleting it is refused.

Refunds have their own route: Refunds.

The charge object

  • Name
    id
    Type
    string
    Description

    Starts with ch_.

  • Name
    amount
    Type
    integer
    Description

    In the smallest unit of currency.

  • Name
    currency
    Type
    string
    Description

    Lower case, for example usd.

  • Name
    status
    Type
    string
    Description

    succeeded, pending or failed.

  • Name
    amount_refunded
    Type
    integer
    Description

    Total refunded so far.

  • Name
    fee_amount
    Type
    integer
    Description

    Our fee for this charge, written by the system.

  • Name
    net_amount
    Type
    integer
    Description

    amount - fee_amount, written by the system.

  • Name
    customer
    Type
    string
    Description

    A customer id, when the charge has one.

  • Name
    description
    Type
    string
    Description
  • Name
    receipt_email
    Type
    string
    Description
  • Name
    livemode
    Type
    boolean
    Description
  • Name
    created_at
    Type
    timestamp
    Description

    UTC, without a zone suffix.

Create a charge with a token

POST /charges takes provider: "card", an amount, a currency (default usd) and card.token, a Stripe tok_ or pm_ id. Mobile money and bank debit are refused with payment_method_not_supported. Always send an Idempotency-Key header: repeating a request with the same key returns the first result and never charges twice, and the same key with a different body is a 409.

POST /charges

curl https://api.cari.finance/charges \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  -H "Idempotency-Key: order-1042-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"provider": "card", "amount": 2500, "currency": "usd", "card": {"token": "tok_..."}}'

In live mode, charges need a verified email and an approved business verification.

Was this page helpful?