Wallet & Payments

Manage your account wallet, balances, payment methods, invoices, and transactions. Use these endpoints to check general and AI balances, top up via Stripe Checkout, transfer funds between balance types, and review payment history.

All endpoints are scoped to the authenticated user. Amounts are submitted as strict decimal strings (e.g., "25.00", "10") — no exponents, no negatives, up to 2 decimal places.

---

Balances

GET /api/v1/wallet/balances

Return the user’s aggregate balances (general + AI) in a single response.

This endpoint takes no parameters.

cURL

curl -X GET "https://api.example.com/api/v1/wallet/balances" \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.api.wallet.getAggregateBalances();

Response

200

{
  "statusCode": 200,
  "message": "Balances retrieved successfully",
  "data": {
    "general_balance": "125.50",
    "ai_limit": "50.00",
    "ai_usage": "23.45",
    "ai_remaining": "26.55"
  }
}

---

GET /api/v1/wallet/balances/general

Return the user’s general account balance only.

This endpoint takes no parameters.

cURL

curl -X GET "https://api.example.com/api/v1/wallet/balances/general" \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.api.wallet.getGeneralBalance();

Response

200

{
  "statusCode": 200,
  "message": "General balance retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439100",
    "user_id": "507f1f77bcf86cd799439011",
    "general_balance": "125.50",
    "created_at": "2025-01-10T08:30:00.000Z",
    "updated_at": "2025-01-21T20:00:00.000Z"
  }
}

---

GET /api/v1/wallet/balances/ai

Return the user’s AI credit limit, usage, and remaining balance.

This endpoint takes no parameters.

cURL

curl -X GET "https://api.example.com/api/v1/wallet/balances/ai" \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.api.wallet.getAiBalance();

Response

200

{
  "statusCode": 200,
  "message": "AI balance retrieved successfully",
  "data": {
    "ai_limit": "50.00",
    "ai_usage": "23.45",
    "ai_remaining": "26.55"
  }
}

---

AI Fee History

GET /api/v1/wallet/ai-fee-history

Paginated list of platform fees charged on AI credit transfers and admin credits.

Parameters

Name	In	Type	Required	Description
page	query	number	No	Page number. Default: 1
limit	query	number	No	Items per page. Default: 20
sort_by	query	string	No	One of: created_at, amount, transaction_id. Default: "created_at"
sort_order	query	string	No	One of: asc, desc. Default: "desc"

cURL

curl -X GET "https://api.example.com/api/v1/wallet/ai-fee-history?page=1&limit=20&sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer <token>"

SDK

for await (const fee of client.api.wallet.listAiFeeHistoryIterator({
  page: 1,
  limit: 20,
  sort_by: "created_at",
  sort_order: "desc"
})) {
  console.log(fee);
}

Response

200

{
  "statusCode": 200,
  "message": "AI fee history retrieved successfully",
  "data": {
    "fees": [
      {
        "id": "507f1f77bcf86cd799439200",
        "transaction_id": "507f1f77bcf86cd799439110",
        "amount": "1.25",
        "created_at": "2025-01-21T20:00:00.000Z",
        "transaction": {
          "id": "507f1f77bcf86cd799439110",
          "reason": "Transfer to AI credits",
          "amount": "25.00"
        }
      }
    ],
    "pagination": {
      "total": 12,
      "page": 1,
      "limit": 20,
      "totalPages": 1
    }
  }
}

---

Transfers

POST /api/v1/wallet/transfers

One-way transfer from the general balance to AI credit balance. A platform fee is deducted from the gross amount; the net amount is added to the AI credit limit.

Request Body

Field	Type	Required	Description
amount	string	Yes	USD amount as a string with up to 2 decimals (e.g., "10.00"). No exponent, no negatives.

{
  "amount": "25.00"
}

cURL

curl -X POST "https://api.example.com/api/v1/wallet/transfers" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "25.00"
  }'

SDK

const result = await client.api.wallet.transferToAi({
  amount: "25.00"
});

Response

200

{
  "statusCode": 200,
  "message": "Transfer completed and AI credit limit synced",
  "data": {
    "gross_transferred": "25.00",
    "net_ai_credit": "23.75",
    "fee": "1.25",
    "general_balance": "100.50",
    "ai_balance": "75.00",
    "key_created": false
  }
}

---

Transactions

GET /api/v1/wallet/transactions

List the user’s wallet transactions with sorting.

Parameters

Name	In	Type	Required	Description
limit	query	number	No	Items per page. Default: 20
sort_by	query	string	No	One of: id, transaction_type, status, amount, created_at, updated_at. Default: "created_at"
sort_order	query	string	No	One of: asc, desc. Default: "desc"

cURL

curl -X GET "https://api.example.com/api/v1/wallet/transactions?limit=20&sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer <token>"

SDK

for await (const tx of client.api.wallet.listTransactionsIterator({
  limit: 20,
  sort_by: "created_at",
  sort_order: "desc"
})) {
  console.log(tx);
}

Response

200

{}

---

GET /api/v1/wallet/transactions/{id}

Retrieve a single wallet transaction by ID.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Transaction ID.

cURL

curl -X GET "https://api.example.com/api/v1/wallet/transactions/507f1f77bcf86cd799439140" \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.api.wallet.getTransaction("507f1f77bcf86cd799439140");

Response

200

{}

---

Payment Methods

GET /api/v1/wallet/payment-methods/

List all payment methods on file for the authenticated user.

This endpoint takes no parameters.

cURL

curl -X GET "https://api.example.com/api/v1/wallet/payment-methods/" \
  -H "Authorization: Bearer <token>"

SDK

for await (const pm of client.api.wallet.listPaymentMethodsIterator()) {
  console.log(pm);
}

Response

200

{
  "statusCode": 200,
  "message": "Payment methods retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439130",
      "user_id": "507f1f77bcf86cd799439011",
      "type": "credit_card",
      "name": "Visa ending in 4242",
      "status": "active",
      "details": {
        "last4": "4242",
        "brand": "visa",
        "exp_month": 12,
        "exp_year": 2026
      },
      "is_default": true,
      "created_at": "2025-01-15T10:00:00.000Z",
      "updated_at": "2025-01-15T10:00:00.000Z"
    }
  ]
}

---

GET /api/v1/wallet/payment-methods/{id}

Retrieve a single payment method by ID.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Payment method ID.

cURL

curl -X GET "https://api.example.com/api/v1/wallet/payment-methods/507f1f77bcf86cd799439130" \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.api.wallet.getPaymentMethod("507f1f77bcf86cd799439130");

Response

200

{
  "statusCode": 200,
  "message": "Payment method retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439130",
    "user_id": "507f1f77bcf86cd799439011",
    "type": "credit_card",
    "name": "Visa ending in 4242",
    "status": "active",
    "details": {
      "last4": "4242",
      "brand": "visa",
      "exp_month": 12,
      "exp_year": 2026
    },
    "is_default": true,
    "created_at": "2025-01-15T10:00:00.000Z",
    "updated_at": "2025-01-15T10:00:00.000Z"
  }
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Payment method not found"
}

---

POST /api/v1/wallet/payment-methods/

Add a new payment method to the user’s account.

Request Body

Field	Type	Required	Description
type	string	Yes	Payment method type (e.g., credit_card).
name	string	Yes	Human-readable label (e.g., "Mastercard ending in 5555").
details	object	No	Gateway-specific details (e.g., { last4, brand, exp_month, exp_year }).
is_default	boolean	No	Whether to mark this as the default method.

{
  "type": "credit_card",
  "name": "Mastercard ending in 5555",
  "details": {
    "last4": "5555",
    "brand": "mastercard",
    "exp_month": 8,
    "exp_year": 2027
  },
  "is_default": false
}

cURL

curl -X POST "https://api.example.com/api/v1/wallet/payment-methods/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "credit_card",
    "name": "Mastercard ending in 5555",
    "details": {
      "last4": "5555",
      "brand": "mastercard",
      "exp_month": 8,
      "exp_year": 2027
    },
    "is_default": false
  }'

SDK

const result = await client.api.wallet.addPaymentMethod({
  type: "credit_card",
  name: "Mastercard ending in 5555",
  details: {
    last4: "5555",
    brand: "mastercard",
    exp_month: 8,
    exp_year: 2027
  },
  is_default: false
});

Response

201

{
  "statusCode": 201,
  "message": "Payment method added successfully",
  "data": {
    "id": "507f1f77bcf86cd799439131",
    "user_id": "507f1f77bcf86cd799439011",
    "type": "credit_card",
    "name": "Mastercard ending in 5555",
    "status": "active",
    "details": {
      "last4": "5555",
      "brand": "mastercard",
      "exp_month": 8,
      "exp_year": 2027
    },
    "is_default": false,
    "created_at": "2025-01-21T20:30:00.000Z",
    "updated_at": "2025-01-21T20:30:00.000Z"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid payment method payload"
}

---

PATCH /api/v1/wallet/payment-methods/{id}

Partially update an existing payment method (status, default flag, or details).

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Payment method ID.

Request Body

Field	Type	Required	Description
details	object	No	Replacement gateway-specific details object.
status	string	No	One of: active, inactive.
is_default	boolean	No	Mark this payment method as the default.

{
  "status": "active",
  "is_default": true,
  "details": {
    "last4": "5555",
    "brand": "mastercard",
    "exp_month": 10,
    "exp_year": 2027
  }
}

cURL

curl -X PATCH "https://api.example.com/api/v1/wallet/payment-methods/507f1f77bcf86cd799439131" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "is_default": true
  }'

SDK

const result = await client.api.wallet.updatePaymentMethod("507f1f77bcf86cd799439131", {
  is_default: true
});

Response

200

{
  "statusCode": 200,
  "message": "Payment method updated successfully",
  "data": {
    "id": "507f1f77bcf86cd799439131",
    "user_id": "507f1f77bcf86cd799439011",
    "type": "credit_card",
    "name": "Mastercard (primary)",
    "status": "active",
    "details": {
      "last4": "5555",
      "brand": "mastercard",
      "exp_month": 10,
      "exp_year": 2027
    },
    "is_default": true,
    "created_at": "2025-01-21T20:30:00.000Z",
    "updated_at": "2025-01-21T20:45:00.000Z"
  }
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Payment method not found"
}

---

PATCH /api/v1/wallet/payment-methods/{id}/default

Promote an existing payment method to be the user’s default.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Payment method ID.

cURL

curl -X PATCH "https://api.example.com/api/v1/wallet/payment-methods/507f1f77bcf86cd799439131/default" \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.api.wallet.setDefaultPaymentMethod("507f1f77bcf86cd799439131");

Response

200

{
  "statusCode": 200,
  "message": "Default payment method set successfully",
  "data": {
    "id": "507f1f77bcf86cd799439131",
    "user_id": "507f1f77bcf86cd799439011",
    "type": "credit_card",
    "name": "Mastercard (primary)",
    "status": "active",
    "details": {
      "last4": "5555",
      "brand": "mastercard",
      "exp_month": 10,
      "exp_year": 2027
    },
    "is_default": true,
    "created_at": "2025-01-21T20:30:00.000Z",
    "updated_at": "2025-01-21T21:00:00.000Z"
  }
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Payment method not found"
}

---

DELETE /api/v1/wallet/payment-methods/{id}

Delete a payment method from the user’s account.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Payment method ID.

cURL

curl -X DELETE "https://api.example.com/api/v1/wallet/payment-methods/507f1f77bcf86cd799439131" \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.api.wallet.deletePaymentMethod("507f1f77bcf86cd799439131");

Response

200

{
  "statusCode": 200,
  "message": "Payment method deleted successfully"
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Payment method not found"
}

---

Payments

POST /api/v1/wallet/payments/

Process a payment using a saved payment method. Credits the user’s wallet, creates an invoice, and updates the balance atomically.

Request Body

Field	Type	Required	Description
payment_method_id	string	Yes	ID of the payment method to charge.
amount	string	Yes	USD amount as a strict decimal string with up to 2 decimals (e.g., "10", "10.00"). No negatives, no exponent.
credit_distribution	array	No	Optional allocation hint. Each item: { type: "general", amount: "<decimal string>" }. Informational only; amounts must be strict dollar strings.
reason	string	No	Free-form description that appears on the invoice.

{
  "payment_method_id": "507f1f77bcf86cd799439130",
  "amount": "100.00",
  "reason": "Monthly subscription payment"
}

cURL

curl -X POST "https://api.example.com/api/v1/wallet/payments/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method_id": "507f1f77bcf86cd799439130",
    "amount": "100.00",
    "reason": "Monthly subscription payment"
  }'

SDK

const result = await client.api.wallet.processPayment({
  payment_method_id: "507f1f77bcf86cd799439130",
  amount: "100.00",
  reason: "Monthly subscription payment"
});

Response

200

{
  "statusCode": 200,
  "message": "Payment processed successfully",
  "data": {
    "transaction": {
      "id": "507f1f77bcf86cd799439140",
      "user_id": "507f1f77bcf86cd799439011",
      "payment_method_id": "507f1f77bcf86cd799439130",
      "transaction_type": "payment",
      "status": "completed",
      "amount": 100,
      "currency": "USD",
      "gateway_name": "stripe",
      "gateway_transaction_id": "ch_3ABC123xyz",
      "reason": "Monthly subscription payment",
      "created_at": "2025-01-21T20:00:00.000Z",
      "updated_at": "2025-01-21T20:00:00.000Z"
    },
    "invoice": {
      "id": "507f1f77bcf86cd799439141",
      "invoice_number": "INV-2025-000789"
    },
    "balance": {
      "id": "507f1f77bcf86cd799439100",
      "user_id": "507f1f77bcf86cd799439011",
      "balance": 225.5,
      "created_at": "2025-01-10T08:30:00.000Z",
      "updated_at": "2025-01-21T20:00:00.000Z"
    }
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid amount format"
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Payment method not found"
}

---

GET /api/v1/wallet/payments/{id}

Retrieve the status and details of a previously submitted payment.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Payment transaction ID.

cURL

curl -X GET "https://api.example.com/api/v1/wallet/payments/507f1f77bcf86cd799439140" \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.api.wallet.getPaymentStatus("507f1f77bcf86cd799439140");

Response

200

{
  "statusCode": 200,
  "message": "Payment status retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439140",
    "user_id": "507f1f77bcf86cd799439011",
    "payment_method_id": "507f1f77bcf86cd799439130",
    "transaction_type": "payment",
    "status": "completed",
    "amount": 100,
    "currency": "USD",
    "gateway_name": "stripe",
    "gateway_transaction_id": "ch_3ABC123xyz",
    "reason": "Monthly subscription payment",
    "created_at": "2025-01-21T20:00:00.000Z",
    "updated_at": "2025-01-21T20:00:00.000Z",
    "details": [
      {
        "id": "507f1f77bcf86cd799439142",
        "transaction_id": "507f1f77bcf86cd799439140",
        "credit_type": "general",
        "amount": 100,
        "created_at": "2025-01-21T20:00:00.000Z"
      }
    ],
    "invoice": {
      "id": "507f1f77bcf86cd799439141",
      "invoice_number": "INV-2025-000789",
      "status": "paid",
      "issue_date": "2025-01-21T20:00:00.000Z",
      "paid_date": "2025-01-21T20:00:00.000Z"
    }
  }
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Payment not found"
}

---

Stripe Card Payments

Note

Card top-ups use Stripe Checkout. After calling createStripeCheckout, redirect the user to data.checkout_url. The wallet is credited only after Stripe confirms settlement via webhook — poll getStripePaymentIntent after the redirect to learn the final status.

Possible payment intent statuses: creating, pending, processing, completed, failed, expired, cancelled, admin_review.

POST /api/v1/wallet/payments/stripe/checkout

Create a payment intent and a hosted Stripe Checkout session for the user.

Request Body

Field	Type	Required	Description
amount	string	Yes	USD amount as a strict decimal string (e.g., "25" or "25.00").
idempotency_key	string	No	Caller-provided idempotency key (1–128 chars). Repeats with the same key return the original intent.

{
  "amount": "25.00",
  "idempotency_key": "topup-2026-06-10-001"
}

cURL

curl -X POST "https://api.example.com/api/v1/wallet/payments/stripe/checkout" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "25.00",
    "idempotency_key": "topup-2026-06-10-001"
  }'

SDK

const result = await client.api.wallet.createStripeCheckout({
  amount: "25.00",
  idempotency_key: "topup-2026-06-10-001"
});

Response

201

{
  "statusCode": 201,
  "message": "Checkout session created",
  "data": {
    "intent": {
      "id": "665f1f77bcf86cd799439011",
      "provider": "stripe",
      "status": "pending",
      "amount": 25,
      "currency": "USD",
      "redirect_url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3",
      "credited_at": null,
      "expires_at": "2026-06-11T12:00:00.000Z",
      "created_at": "2026-06-10T12:00:00.000Z",
      "updated_at": "2026-06-10T12:00:00.000Z"
    },
    "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3"
  }
}

---

GET /api/v1/wallet/payments/stripe/intents

List the authenticated user’s Stripe payment intents, newest first.

Parameters

Name	In	Type	Required	Description
limit	query	number	No	Items per page. Default: 20
offset	query	number	No	Items to skip. Default: 0

cURL

curl -X GET "https://api.example.com/api/v1/wallet/payments/stripe/intents?limit=20&offset=0" \
  -H "Authorization: Bearer <token>"

SDK

// Paginated call
const page = await client.api.wallet.listStripePaymentIntents({ limit: 20, offset: 0 });

// Iterator (auto-paginates)
for await (const intent of client.api.wallet.listStripePaymentIntentsIterator({ limit: 20 })) {
  console.log(intent);
}

Response

200

{
  "statusCode": 200,
  "message": "Payment intents retrieved successfully",
  "data": {
    "intents": [
      {
        "id": "665f1f77bcf86cd799439011",
        "provider": "stripe",
        "status": "pending",
        "amount": 25,
        "currency": "USD",
        "redirect_url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3",
        "credited_at": null,
        "expires_at": "2026-06-11T12:00:00.000Z",
        "created_at": "2026-06-10T12:00:00.000Z",
        "updated_at": "2026-06-10T12:00:00.000Z"
      }
    ],
    "total": 1
  }
}

---

GET /api/v1/wallet/payments/stripe/intents/{id}

Retrieve a single Stripe payment intent by ID. Use this after the user returns from Stripe Checkout to learn whether the payment settled.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Payment intent ID.

cURL

curl -X GET "https://api.example.com/api/v1/wallet/payments/stripe/intents/665f1f77bcf86cd799439011" \
  -H "Authorization: Bearer <token>"

SDK

const intent = await client.api.wallet.getStripePaymentIntent("665f1f77bcf86cd799439011");

Response

200

{
  "statusCode": 200,
  "message": "Payment intent retrieved successfully",
  "data": {
    "id": "665f1f77bcf86cd799439011",
    "provider": "stripe",
    "status": "completed",
    "amount": 25,
    "currency": "USD",
    "redirect_url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3",
    "credited_at": "2026-06-10T12:05:30.000Z",
    "expires_at": "2026-06-11T12:00:00.000Z",
    "created_at": "2026-06-10T12:00:00.000Z",
    "updated_at": "2026-06-10T12:05:30.000Z"
  }
}

---

Invoices

GET /api/v1/wallet/invoices/

List all invoices issued to the authenticated user.

Parameters

Name	In	Type	Required	Description
limit	query	number	No	Items per page. Default: 20
sort_by	query	string	No	Field to sort by. Default: "created_at"
sort_order	query	string	No	One of: asc, desc. Default: "desc"

cURL

curl -X GET "https://api.example.com/api/v1/wallet/invoices/?limit=20&sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer <token>"

SDK

for await (const invoice of client.api.wallet.listInvoicesIterator({
  limit: 20,
  sort_by: "created_at",
  sort_order: "desc"
})) {
  console.log(invoice);
}

Response

200

{
  "statusCode": 200,
  "message": "Invoices retrieved successfully",
  "data": {
    "invoices": [
      {
        "id": "507f1f77bcf86cd799439120",
        "user_id": "507f1f77bcf86cd799439011",
        "transaction_id": "507f1f77bcf86cd799439110",
        "invoice_number": "INV-2025-000456",
        "status": "paid",
        "amount": 50,
        "currency": "USD",
        "issue_date": "2025-01-20T15:30:00.000Z",
        "due_date": "2025-02-20T15:30:00.000Z",
        "paid_date": "2025-01-20T15:30:00.000Z",
        "created_at": "2025-01-20T15:30:00.000Z",
        "updated_at": "2025-01-20T15:30:00.000Z",
        "transaction": {
          "id": "507f1f77bcf86cd799439110",
          "transaction_type": "payment",
          "status": "completed",
          "amount": 50,
          "currency": "USD",
          "created_at": "2025-01-20T15:30:00.000Z"
        }
      }
    ],
    "pagination": {
      "total": 23,
      "page": 1,
      "limit": 10,
      "totalPages": 3
    }
  }
}

---

GET /api/v1/wallet/invoices/{id}

Retrieve a single invoice with full line items and billing details.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Invoice ID.

cURL

curl -X GET "https://api.example.com/api/v1/wallet/invoices/507f1f77bcf86cd799439120" \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.api.wallet.getInvoice("507f1f77bcf86cd799439120");

Response

200

{
  "statusCode": 200,
  "message": "Invoice retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439120",
    "user_id": "507f1f77bcf86cd799439011",
    "transaction_id": "507f1f77bcf86cd799439110",
    "invoice_number": "INV-2025-000456",
    "status": "paid",
    "amount": 50,
    "currency": "USD",
    "billing_details": {
      "name": "John Doe",
      "address": "123 Main St"
    },
    "items": [
      {
        "description": "Account credit",
        "amount": 50
      }
    ],
    "issue_date": "2025-01-20T15:30:00.000Z",
    "due_date": "2025-02-20T15:30:00.000Z",
    "paid_date": "2025-01-20T15:30:00.000Z",
    "created_at": "2025-01-20T15:30:00.000Z",
    "updated_at": "2025-01-20T15:30:00.000Z",
    "transaction": {
      "id": "507f1f77bcf86cd799439110",
      "transaction_type": "payment",
      "status": "completed",
      "amount": 50,
      "currency": "USD",
      "created_at": "2025-01-20T15:30:00.000Z"
    }
  }
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Invoice not found"
}

---

GET /api/v1/wallet/invoices/{id}/pdf

Download an invoice as a PDF file (binary response, application/pdf).

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Invoice ID.

cURL

curl -X GET "https://api.example.com/api/v1/wallet/invoices/507f1f77bcf86cd799439120/pdf" \
  -H "Authorization: Bearer <token>" \
  -o invoice.pdf

SDK

const blob = await client.api.wallet.downloadInvoicePdf("507f1f77bcf86cd799439120");
// Save blob to disk as needed

Response

200

{
  "description": "PDF binary file (application/pdf)"
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Invoice not found"
}

---

POST /api/v1/wallet/invoices/generate/{id}

Generate an invoice for a specific transaction. Returns 201 if a new invoice is created, or 200 if an invoice already exists for that transaction.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Transaction ID to generate an invoice for.

cURL

curl -X POST "https://api.example.com/api/v1/wallet/invoices/generate/507f1f77bcf86cd799439110" \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.api.wallet.generateInvoice("507f1f77bcf86cd799439110");

Response

201

{
  "statusCode": 201,
  "message": "Invoice generated successfully",
  "data": {
    "invoice_id": "507f1f77bcf86cd799439121",
    "invoice_number": "INV-2025-000457"
  }
}

200

{
  "statusCode": 200,
  "message": "Invoice already exists",
  "data": {
    "invoice_id": "507f1f77bcf86cd799439120",
    "invoice_number": "INV-2025-000456"
  }
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Transaction not found"
}