Manage prepaid credit balances, grant promotional or purchased credits, and deduct usage charges.

Credit Wallets API

Credit Wallets allow you to build prepaid billing structures. You can issue credits to customers (via purchase or promotional grants), automatically deduct credits as they consume services, and query their wallet transaction ledger.

Get Credit Balance

Retrieve the current credit balance of a customer. Wallets are currency-based (defaulting to the merchant's collection currency, e.g. GHS).

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/credits/:customerId`
Request Type	`GET`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`credits:read`

Path Parameters

Parameter	Type	Required	Description
`:customerId`	`String`	Yes	Unique ID of the customer (e.g. `cust_cl8z2e9z...`).

Code Examples

curl https://api.xtopay.co/v1/credits/cust_cl8z2e9z50000a \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

Sample Response

200 OK

{
  "success": true,
  "data": {
    "id": "cwa_cl8z2g8820000f",
    "balance": 1500,
    "currency": "GHS",
    "createdAt": "2026-06-05T12:00:00Z",
    "updatedAt": "2026-06-05T12:10:00Z"
  }
}

Grant Credits

Add credits to a customer's wallet. If the customer does not have an active credit wallet, one will be created automatically.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/credits/:customerId/grant`
Request Type	`POST`
Content Type	`application/json`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`credits:write`

Path Parameters

Parameter	Type	Required	Description
`:customerId`	`String`	Yes	Unique ID of the customer receiving the credit grant.

Request Parameters

Parameter	Type	Required	Description
`amount`	`Integer`	Yes	The number of credits to add (must be a positive integer).
`description`	`String`	No	A note or reason for the transaction displayed on the ledger (e.g. `"Promo sign-up reward"`).
`expiresAt`	`String`	No	ISO 8601 date string when these specific credits expire (e.g. `"2026-12-31T23:59:59Z"`).
`metadata`	`Object`	No	Flat key-value object containing transaction metadata.

Code Examples

curl https://api.xtopay.co/v1/credits/cust_cl8z2e9z50000a/grant \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "description": "API Integration Promo Credits",
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

Sample Response

200 OK

{
  "success": true,
  "data": {
    "wallet": {
      "id": "cwa_cl8z2g8820000f",
      "balance": 2000,
      "currency": "GHS"
    },
    "transaction": {
      "id": "ctx_cl8z2h8820000g",
      "type": "GRANT",
      "amount": 500,
      "balanceBefore": 1500,
      "balanceAfter": 2000,
      "description": "API Integration Promo Credits",
      "expiresAt": "2026-12-31T23:59:59Z",
      "metadata": null,
      "createdAt": "2026-06-05T12:20:00Z"
    }
  }
}

Deduct Credits

Deduct credits from a customer's wallet balance when they consume resources.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/credits/:customerId/deduct`
Request Type	`POST`
Content Type	`application/json`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`credits:write`

Path Parameters

Parameter	Type	Required	Description
`:customerId`	`String`	Yes	Unique ID of the customer to deduct credit from.

Request Parameters

Parameter	Type	Required	Description
`amount`	`Integer`	Yes	The number of credits to deduct (must be a positive integer).
`description`	`String`	No	A description for the deduction ledger (e.g. `"API request deduction"`).
`metadata`	`Object`	No	Flat key-value object containing transaction metadata.

Code Examples

curl https://api.xtopay.co/v1/credits/cust_cl8z2e9z50000a/deduct \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50,
    "description": "AI Image Ingestion Deduction"
  }'

Sample Response

200 OK

{
  "success": true,
  "data": {
    "wallet": {
      "id": "cwa_cl8z2g8820000f",
      "balance": 1950,
      "currency": "GHS"
    },
    "transaction": {
      "id": "ctx_cl8z2i8820000h",
      "type": "USAGE",
      "amount": 50,
      "balanceBefore": 2000,
      "balanceAfter": 1950,
      "description": "AI Image Ingestion Deduction",
      "metadata": null,
      "createdAt": "2026-06-05T12:25:00Z"
    }
  }
}

List Credit Transactions

Retrieve a history of credit ledger transactions for a customer's wallet.

Detail	Description
API Endpoint	`https://api.xtopay.co/v1/credits/:customerId/transactions`
Request Type	`GET`
Authentication	`Basic Base64(clientId:clientSecret)`
Required Scope	`credits:read`

Path Parameters

Parameter	Type	Required	Description
`:customerId`	`String`	Yes	Unique ID of the customer wallet.

Query Parameters

Parameter	Type	Required	Description
`type`	`String`	No	Filter by transaction type: `PURCHASE`, `USAGE`, `GRANT`, `ADJUSTMENT`, `EXPIRY`, `REFUND`.
`limit`	`Integer`	No	Maximum results to return per page (range 1–100, default `20`).
`cursor`	`String`	No	Pagination cursor from the `nextCursor` value of a previous response.

Code Examples

curl "https://api.xtopay.co/v1/credits/cust_cl8z2e9z50000a/transactions?type=USAGE&limit=1" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

Sample Response

200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "ctx_cl8z2i8820000h",
        "type": "USAGE",
        "amount": 50,
        "balanceBefore": 2000,
        "balanceAfter": 1950,
        "description": "AI Image Ingestion Deduction",
        "createdAt": "2026-06-05T12:25:00Z"
      }
    ],
    "nextCursor": "ctx_cl8z2i8820000h",
    "hasMore": false
  }
}

Credit Wallets API

On this page