## How it works

A customer groups the buyer's payments and saved payment methods. A reusable method should be associated with the customer's record and the appropriate consent.

## Implementation

Create or reuse customer_id and attach it to payments. Request setup_future_usage: off_session when saving a supported method. Later payments may refer to a saved payment_method_id or mandate_id, using confirm and off_session where supported. Retrieve and remove saved methods with their own resource routes; do not store card numbers. Merchant-level customer operations may require an account-wide key. Removing a method can affect future subscription renewals.

## Create a customer

| Task | Request |
| --- | --- |
| Retrieve | `GET /customers/{customer_id}` |
| Update | `POST /customers/{customer_id}` |
| List | `GET /customers/list?limit=20&offset=0` |
| Delete | `DELETE /customers/{customer_id}`: redacts personal data and addresses, deletes saved methods |

## Charge a saved method

| Task | Request |
| --- | --- |
| Retrieve | `GET /mandates/{mandate_id}` |
| List a customer's | `GET /customers/{customer_id}/mandates` |
| Revoke | `POST /mandates/revoke/{mandate_id}` |

## Related guides

- [Webhook events](/docs/payment-api/webhooks/)

## Request examples

```bash
curl -X POST https://api.spicepay.net/customers \
  -H 'api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "phone": "170123456",
    "phone_country_code": "+49",
    "metadata": { "internal_id": "user_42" }
  }'
```

```bash
curl -X POST https://api.spicepay.net/payments \
  -H 'api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 2500,
    "currency": "USD",
    "customer_id": "cus_xxxxx",
    "setup_future_usage": "off_session",
    "payment_link": true,
    "return_url": "https://shop.example/return"
  }'
```

```bash
curl https://api.spicepay.net/customers/cus_xxxxx/payment-methods \
  -H 'api-key: YOUR_API_KEY'
```

```bash
curl -X POST https://api.spicepay.net/payments \
  -H 'api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 1500,
    "currency": "USD",
    "customer_id": "cus_xxxxx",
    "confirm": true,
    "off_session": true,
    "recurring_details": { "type": "payment_method_id", "data": "pm_xxxxx" }
  }'
```

```bash
curl -X POST https://api.spicepay.net/customers/cus_xxxxx/payment-methods/pm_xxxxx/default \
  -H 'api-key: YOUR_API_KEY'
```

```bash
curl -X DELETE https://api.spicepay.net/payment-methods/pm_xxxxx \
  -H 'api-key: YOUR_API_KEY'
```