Credit Wallets API

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

Get Credit Balance

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

GET /v1/credits/:customerId

Request Scopes

credits:read

Example Request

curl https://api.xtopay.co/v1/credits/cust_cl8z2e9z... \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Example Response

{
  "success": true,
  "data": {
    "id": "cwa_cl8z2g...",
    "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.

POST /v1/credits/:customerId/grant

Request Scopes

credits:write

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/reason for the transaction shown on the ledger (e.g. `"Promo sign-up reward"`).
`expiresAt`	`string`	No	ISO 8601 date string when these specific credits expire.
`metadata`	`object`	No	Flat key-value object containing transaction metadata.

Example Request

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

Example Response

{
  "success": true,
  "data": {
    "wallet": {
      "id": "cwa_cl8z2g...",
      "balance": 2000,
      "currency": "GHS"
    },
    "transaction": {
      "id": "ctx_cl8z2h...",
      "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.

POST /v1/credits/:customerId/deduct

Request Scopes

credits:write

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.

Example Request

curl https://api.xtopay.co/v1/credits/cust_cl8z2e9z.../deduct \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50,
    "description": "AI Image Ingestion Deduction"
  }'

Example Response

{
  "success": true,
  "data": {
    "wallet": {
      "id": "cwa_cl8z2g...",
      "balance": 1950,
      "currency": "GHS"
    },
    "transaction": {
      "id": "ctx_cl8z2i...",
      "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.

GET /v1/credits/:customerId/transactions

Request Scopes

credits:read

Query Parameters

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

Example Request

curl "https://api.xtopay.co/v1/credits/cust_cl8z2e9z.../transactions?type=USAGE&limit=1" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Example Response

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

Credit Wallets API

On this page