Onboard a customer

Before you can subscribe a customer, Paylera needs to know who they are and how to charge them.

1. Create the customer

POST /v1/customers
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "billing_address": {
    "line1": "100 Market St",
    "city":  "San Francisco",
    "region": "CA",
    "country": "US",
    "postal_code": "94105"
  },
  "metadata": {
    "your_user_id": "u_28471"
  }
}

Use metadata to carry your application’s foreign keys. Maximum 50 keys, each ≤ 500 bytes.

The response includes a customer_id. Persist it against your user record — every subsequent call uses it.

2. Capture a tax ID (optional, B2B)

POST /v1/customers/{id}/tax-ids
{ "type": "eu_vat", "value": "DE123456789" }

The tax engine validates the ID asynchronously. If invalid, the customer is marked tax_id_invalid and the next invoice doesn’t apply reverse-charge. Listen for customer.tax_id_invalidated.

3. Attach a payment method

The recommended path is hosted checkout — you don’t touch card data, your PCI scope stays SAQ-A, and 3DS is handled for you. See Hosted checkout.

For full control (and a steeper PCI burden), use the provider’s client-side SDK to tokenise the card, then attach the token:

POST /v1/customers/{id}/payment-methods
Idempotency-Key: <uuid>
{
  "type": "card",
  "token": "tok_visa_…",
  "set_as_default": true
}

Supported type values: card, bank_account (ACH/SEPA), paypal, wallet (Apple Pay / Google Pay).

The response includes a payment_method_id and the (provider-validated) last-4 / brand / expiry for display.

4. Set the default payment method

If you didn’t pass set_as_default: true, do it explicitly:

PATCH /v1/customers/{id}
{ "default_payment_method_id": "pm_…" }

The default is what subscriptions use to collect by default. Individual subscriptions can override it.

5. (Optional) Verify the card with a $0 auth

For B2B and high-ticket flows, you may want to verify the method before the first real charge:

POST /v1/payment-methods/{id}/verify

Provider-dependent: cards get a $0 / $1 auth (depending on jurisdiction) and reverse it; bank accounts run a micro-deposit verification flow that returns verifying and emits payment_method.verified when the customer confirms.

What’s next

• The customer is ready to be subscribed: Create a subscription.
• If you want a customer-facing UI for managing payment methods and invoices: Customer portal.

Common pitfalls

• Don’t create a new customer per session. Reuse the same customer_id across logins. Use metadata.your_user_id to look up existing customers if you’ve lost the ID.
• Idempotency keys are global per-tenant per-route. Two unrelated POST /v1/customers calls with the same key get the same response. Use a fresh UUID per request.
• Email isn’t unique. Two customers with the same email are allowed — Paylera doesn’t enforce a uniqueness constraint, since the same email may legitimately have multiple accounts. If you need uniqueness, enforce it in your application.

Webhook events

Event	When
customer.created	After successful create.
customer.updated	Any field changed.
customer.payment_method_attached	A new method was added.
customer.payment_method_detached	A method was removed.
customer.tax_id_invalidated	Tax ID validation failed.