Charges

Charges are a core part of the Cari Finance platform, allowing you to handle financial transactions securely and efficiently. On this page, we'll dive into the different charge endpoints you can use to manage charges programmatically. We'll look at how to query, create, update, and delete charges.

The charge model

The charge model contains all the information about a financial transaction, such as the amount, currency, and status. It also includes metadata about the transaction, such as when it was created and last updated.

Properties

Name
provider
Type
string
Description
Payment provider to use: "card", "mobile", or "bank"
Name
card
Type
object
Description
Card details for the charge.
- Name
  token
  Type
  string
  Description
  The token representing the card.
Name
description
Type
string
Description
A description of the charge.
Name
currency
Type
string
Description
Three-letter ISO currency code (e.g., "usd").
Name
amount
Type
integer
Description
The amount to charge in the smallest currency unit (e.g., cents).
Name
customer
Type
object
Description
Customer details for the charge.
- Name
  name
  Type
  string
  Description
  The customer's full name.
- Name
  email
  Type
  string
  Description
  The customer's email address.

Payment providers

Cari Finance supports multiple payment providers to process transactions:

Name
card
Type
object
Description
Process credit card payments. Requires a token obtained from our client-side SDK.
Name
mobile
Type
object
Description
Process mobile money payments, common in various regions.
Name
bank
Type
object
Description
Process bank transfers.

Customer information

Each charge requires customer information that can be provided in two ways:

Name
customer
Type
string | object
Description
Either an existing customer ID or a new customer object

When creating a new customer, the following information is required:

Name
name
Type
string
Description
The customer's full name.
Name
email
Type
string
Description
The customer's email address.
Name
phone
Type
string
Description
The customer's phone number (optional).

GET/charges

List all charges

This endpoint allows you to retrieve a list of all charges. Results are paginated and 20 charges are returned per page by default.

Query Parameters

Name
page
Type
integer
Description
The page number to retrieve (default: 1)
Name
items_per_page
Type
integer
Description
Number of items per page (default: 20, max: 100)

Request

GET

/charges

curl -G https://api.cari.finance/charges \
  -H "Authorization: Bearer pk_test_27436257e3fe4b0fa266f4a6f59047a3"

Response

{
  "charges": [
    {
      "id": "charge_id_1",
      "amount": 1000,
      "amount_captured": 1000,
      "amount_refunded": 0,
      "currency": "usd",
      "customer": "cust_123456789",
      "created": 1697040000,
      "status": "succeeded",
      "livemode": false,
      "created_at": "2023-10-11T00:00:00",
      "updated_at": "2023-10-11T00:00:00"
    }
  ],
  "total_items": 1,
  "total_pages": 1
}

POST/charges

Create a charge

This endpoint allows you to create a new charge. You must provide the necessary payment details.

Required Parameters

Name
provider
Type
string
Description
Payment provider to use: "card", "mobile", or "bank"
Name
card
Type
object
Description
Card details for the charge.
- Name
  token
  Type
  string
  Description
  The token representing the card.
Name
description
Type
string
Description
A description of the charge.
Name
currency
Type
string
Description
Three-letter ISO currency code (e.g., "usd")
Name
amount
Type
integer
Description
The amount to charge in the smallest currency unit (e.g., cents)
Name
customer
Type
object
Description
Customer details for the charge.
- Name
  name
  Type
  string
  Description
  The customer's full name.
- Name
  email
  Type
  string
  Description
  The customer's email address.

Request

POST

/charges

{
  "provider": "card",
  "card": {
    "token": "your_card_token"
  },
  "description": "Purchasing a new car",
  "currency": "usd",
  "amount": 10000,
  "customer": {
    "name": "John Doe",
    "email": "john.doe@example.com"
  }
}

GET/charges/:id

Retrieve a charge

This endpoint allows you to retrieve a specific charge by its ID.

Request

GET

/charges/{id}

curl https://api.cari.finance/charges/charge_id_1 \
  -H "Authorization: Bearer pk_test_27436257e3fe4b0fa266f4a6f59047a3"

Response

{
  "id": "charge_id_1",
  "amount": 1000,
  "amount_captured": 1000,
  "amount_refunded": 0,
  "currency": "usd",
  "customer": "cust_123456789",
  "status": "succeeded",
  "livemode": false,
  "created_at": "2023-10-11T00:00:00",
  "updated_at": "2023-10-11T00:00:00"
}

PUT/charges/:id

Update a charge

This endpoint allows you to update certain properties of an existing charge.

Updatable Fields

Name
description
Type
string
Description
An optional description for the charge
Name
receipt_email
Type
string
Description
Email address to send the receipt to
Name
metadata
Type
object
Description
Set of key-value pairs for storing additional information

Request

PUT

/charges/{id}

curl -X PUT https://api.cari.finance/charges/charge_id_1 \
  -H "Authorization: Bearer pk_test_27436257e3fe4b0fa266f4a6f59047a3" \
  -H "Content-Type: application/json" \
  -d '{
        "description": "Updated description for this charge",
        "receipt_email": "customer@example.com"
      }'