Customers for connected accounts

A connected account’s customers belong to that account. Your platform creates and manages them with the platform secret key and the merchant’s ID, then uses the same merchant when it saves a card or takes a payment for that customer. Store the merchant ID next to each customer’s Ionic ID in your own records. Customer fields and operations are the same as in Manage customers.

Before you begin

A platform secret key from Connect → API keys, kept on your server.
An active connection in the same mode. The platform key and the merchant’s connection both grant each permission an operation needs:

Operation	Permission
Create, update, delete, and restore customers, and set a default payment method	`customers:write`
List and retrieve customers	`customers:read`
Attach and revoke payment methods	`payment_methods:write`
List and retrieve payment methods	`payment_methods:read`

@ionicfi/sdk 0.4.1 or later for the TypeScript examples, installed from npm.

Create the merchant’s customer

import { Ionic } from "@ionicfi/sdk";

const ionic = new Ionic({ token: process.env.IONIC_PLATFORM_SECRET_KEY });

const customer = await ionic.customers.create(
  {
    "Idempotency-Key": "merchant:mer_BBBBBBBBBBBBBB:customer:patient_481",
    email: "[email protected]",
    first_name: "Jane",
    last_name: "Doe",
    metadata: {
      patient_id: "patient_481",
    },
  },
  { account: "mer_BBBBBBBBBBBBBB" },
);

curl https://api.ionicfi.com/v1/customers \
  -H "Authorization: Bearer $IONIC_PLATFORM_SECRET_KEY" \
  -H "Ionic-Account: mer_BBBBBBBBBBBBBB" \
  -H "Idempotency-Key: merchant:mer_BBBBBBBBBBBBBB:customer:patient_481" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "metadata": {
      "patient_id": "patient_481"
    }
  }'

The customer belongs to that merchant and mode. Select the same merchant on every later request for this customer.

Save a card for the customer

Save a card with the customer’s consent using a SetupIntent and a Payment Block on your page. See Save cards for connected accounts. To offer saving during a payment instead, see Accept payments for connected accounts.

List the customer’s saved cards

const methods = await ionic.paymentMethods.list(
  { customer: "cus_2pXqAbc" },
  { account: "mer_BBBBBBBBBBBBBB" },
);

curl "https://api.ionicfi.com/v1/payment_methods?customer=cus_2pXqAbc" \
  -H "Authorization: Bearer $IONIC_PLATFORM_SECRET_KEY" \
  -H "Ionic-Account: mer_BBBBBBBBBBBBBB"

Your application builds any saved-card selection on top of this list.

Choose the default card

An invoice that collects automatically charges the customer’s default payment method when the invoice names none. A subscription that collects automatically sets its own default_payment_method.

const updated = await ionic.customers.setDefaultPaymentMethod(
  {
    id: "cus_2pXqAbc",
    "Idempotency-Key": "merchant:mer_BBBBBBBBBBBBBB:default_pm:pm_abc123",
    default_payment_method: "pm_abc123",
  },
  { account: "mer_BBBBBBBBBBBBBB" },
);

curl -X POST https://api.ionicfi.com/v1/customers/cus_2pXqAbc/default_payment_method \
  -H "Authorization: Bearer $IONIC_PLATFORM_SECRET_KEY" \
  -H "Ionic-Account: mer_BBBBBBBBBBBBBB" \
  -H "Idempotency-Key: merchant:mer_BBBBBBBBBBBBBB:default_pm:pm_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "default_payment_method": "pm_abc123"
  }'

To stop a saved card from being used for new charges, revoke it with Revoke a payment method. A revocation requires a reason.

Customer events

A platform webhook endpoint receives a merchant’s customer.created, customer.updated, customer.deleted, and customer.restored events when that merchant’s connection grants customers:read. The event’s account field names the merchant. See Webhooks for platforms.

Keep customer data with the correct merchant

Value	Owner or scope
Customer and its saved payment methods	The selected connected account, in one mode.
PaymentIntents and SetupIntents for the customer	The same merchant and mode.
`metadata`	Your application’s correlation data for that merchant’s customer.

Connect

Onboard merchants

Set up your platform

Accept payments

After the payment

Launch

Customers for connected accounts

Before you begin

Create the merchant’s customer

Save a card for the customer

List the customer’s saved cards

Choose the default card

Customer events

Keep customer data with the correct merchant

What’s next

Save cards

Read subscriptions and invoices

​Before you begin

​Create the merchant’s customer

​Save a card for the customer

​List the customer’s saved cards

​Choose the default card

​Customer events

​Keep customer data with the correct merchant

​What’s next

Save cards

Read subscriptions and invoices

Before you begin

Create the merchant’s customer

Save a card for the customer

List the customer’s saved cards

Choose the default card

Customer events

Keep customer data with the correct merchant

What’s next