# wallet (https://docs.billwave.example/sdk/wallet)

wallet [#wallet]

Query, add, and remove payment methods for a customer. Payment methods are used for overage billing, credit pack purchases, and trial conversions.

billwave.wallet(customer) [#billwavewalletcustomer]

Shorthand for `billwave.wallet.list()`. Returns the customer's saved payment methods.

```ts
const wallet = await billwave.wallet("user_123");
```

Returns Promise<WalletResult> [#returns-promisewalletresult]

```ts
interface WalletResult {
  hasCard: boolean;
  card: CardInfo | null;
  methods: PaymentMethodInfo[];
}

interface CardInfo {
  last4: string;
  brand: string;
  expMonth: string;
  expYear: string;
}

interface PaymentMethodInfo {
  id: string;
  providerId: string;
  type: "card" | "provider_managed";
  cardLast4?: string | null;
  cardBrand?: string | null;
  cardExpMonth?: string | null;
  cardExpYear?: string | null;
  isDefault: boolean;
  createdAt: number;
}
```

***

billwave.wallet.list(customer) [#billwavewalletlistcustomer]

List all saved payment methods for a customer.

```ts
const result = await billwave.wallet.list("user_123");

for (const method of result.methods) {
  console.log(method.cardBrand, `**** ${method.cardLast4}`);
}
```

Parameters [#parameters]

| Parameter  | Type     | Required | Description           |
| ---------- | -------- | -------- | --------------------- |
| `customer` | `string` | Yes      | Your internal user ID |

Returns Promise<WalletResult> [#returns-promisewalletresult-1]

Same shape as `billwave.wallet()`.

***

billwave.wallet.setup(customer, opts?) [#billwavewalletsetupcustomer-opts]

Initiate card authorization. Returns a URL where the customer completes the setup flow on the provider's page.

```ts
const setup = await billwave.wallet.setup("user_123", {
  callbackUrl: "https://yourapp.com/billing",
  provider: "paystack",
});

if (setup.url) {
  // Redirect customer to authorize their card
  console.log(setup.url);
}
```

Parameters [#parameters-1]

| Parameter          | Type     | Required | Description                                       |
| ------------------ | -------- | -------- | ------------------------------------------------- |
| `customer`         | `string` | Yes      | Your internal user ID                             |
| `opts.callbackUrl` | `string` | No       | URL to redirect customer to after authorization   |
| `opts.provider`    | `string` | No       | Provider ID (e.g. `"paystack"`, `"dodopayments"`) |

Returns Promise<WalletSetupResult> [#returns-promisewalletsetupresult]

```ts
interface WalletSetupResult {
  url: string;
  reference: string;
}
```

Notes [#notes]

* For **Paystack**, a small verification charge is made and auto-refunded
* For **Dodo Payments**, an on-demand subscription mandate is created (no charge)
* After the customer completes the flow, the provider sends a webhook and Billwave stores the payment method automatically

***

billwave.wallet.remove(customer, id) [#billwavewalletremovecustomer-id]

Remove a saved payment method.

```ts
const result = await billwave.wallet.remove("user_123", "pm_abc123");
console.log(result.success); // true
```

Parameters [#parameters-2]

| Parameter  | Type     | Required | Description                 |
| ---------- | -------- | -------- | --------------------------- |
| `customer` | `string` | Yes      | Your internal user ID       |
| `id`       | `string` | Yes      | Payment method ID to remove |

Returns Promise<WalletRemoveResult> [#returns-promisewalletremoveresult]

```ts
interface WalletRemoveResult {
  success: boolean;
}
```