Customers

Manage customers and their payment methods.

Customers are sandbox-aware — test keys only see sandbox customers. You can store contact, billing, and shipping details on each customer.

List Customers

List customers. Automatically filtered by sandbox/live based on API key mode. Each customer includes processorType ('nmi', 'stripe', or 'aptpay') — the gateway their saved payment methods live on.

GEThttps://paysio.com/api/v1/customers

Authorizations

Authorizationstringheaderrequired

Any API key. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Query parameters

limitinteger

1-100, default 10

starting_afterstring

Cursor for pagination

processorstring

Filter by gateway: 'nmi', 'stripe', or 'aptpay'. Use processor=aptpay to list customers whose saved payment methods can receive payouts.

searchstring

Find a customer by email, first or last name, full name, or phone. Case-insensitive, matches anywhere in the field; phone ignores punctuation and needs at least 4 digits.

Example request — cURL

curl -X GET https://paysio.com/api/v1/customers \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/customers", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": [
    {
      "object": "customer",
      "id": "cus_8f2a1c9e-4b3d-47a1-9e12-0a5f6c7d8b90",
      "workspaceId": "3d9b2e10-7c44-4a2f-bb8e-1f6a2c3d4e5f",
      "processorType": "nmi",
      "email": "[email protected]",
      "firstName": "Jane",
      "lastName": "Doe",
      "phone": "+14155550123",
      "billingAddress1": "123 Market St",
      "billingCity": "San Francisco",
      "billingState": "CA",
      "billingPostalCode": "94103",
      "billingCountry": "US",
      "walletBillingIds": [],
      "sandbox": false,
      "source": "api",
      "createdAt": "2026-06-28T14:12:05.331Z",
      "updatedAt": "2026-06-28T14:12:05.331Z"
    }
  ],
  "has_more": false
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Get Customer

Retrieve a single customer by ID.

GEThttps://paysio.com/api/v1/customers/:id

Authorizations

Authorizationstringheaderrequired

Any API key. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X GET https://paysio.com/api/v1/customers/:id \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/customers/:id", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": {
    "object": "customer",
    "id": "cus_8f2a1c9e-4b3d-47a1-9e12-0a5f6c7d8b90",
    "workspaceId": "3d9b2e10-7c44-4a2f-bb8e-1f6a2c3d4e5f",
    "nmiCustomerVaultId": "987654321",
    "stripeCustomerId": null,
    "aptpayIdentityId": null,
    "processorType": "nmi",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "phone": "+14155550123",
    "billingAddress1": "123 Market St",
    "billingCity": "San Francisco",
    "billingState": "CA",
    "billingPostalCode": "94103",
    "billingCountry": "US",
    "shippingFirstName": "Jane",
    "shippingLastName": "Doe",
    "shippingAddress1": "123 Market St",
    "shippingCity": "San Francisco",
    "shippingState": "CA",
    "shippingPostalCode": "94103",
    "shippingCountry": "US",
    "walletBillingIds": [],
    "sandbox": false,
    "source": "api",
    "createdAt": "2026-06-28T14:12:05.331Z",
    "updatedAt": "2026-06-28T14:12:05.331Z"
  }
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Create Customer

Create or update a customer with optional card vaulting. If a customer with the same email already exists, their info is updated and the response includes existing: true (no error — safe to call repeatedly).

POSThttps://paysio.com/api/v1/customers

Authorizations

Authorizationstringheaderrequired

Secret key (sk_*). Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Body

emailstringrequired

Customer email address

first_namestring

First name

last_namestring

Last name

phonestring

Phone number

billing_address_1string

Billing street address

billing_citystring

Billing city

billing_statestring

Billing state/province

billing_postal_codestring

Billing ZIP/postal code

billing_countrystring

Billing country (2-letter ISO code)

shipping_first_namestring

Shipping recipient first name

shipping_last_namestring

Shipping recipient last name

shipping_address_1string

Shipping street address

shipping_citystring

Shipping city

shipping_statestring

Shipping state/province

shipping_postal_codestring

Shipping ZIP/postal code

shipping_countrystring

Shipping country (2-letter ISO code)

payment_tokenstring

Token from paysio.createToken() — vault a card at creation (optional)

cc_numberstring

Card number — vault via raw card (optional, use payment_token instead)

cc_exp_monthstring

Expiry month (01-12), required with cc_number

cc_exp_yearstring

Expiry year (e.g. 2028), required with cc_number

Example request — cURL

curl -X POST https://paysio.com/api/v1/customers \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "..."
}'

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/customers", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "email": "..."
  }),
})
const data = await res.json()

Example response (200)

// Customer created with card vaulted:
{
  "data": {
    "id": "uuid",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "phone": "+15551234567",
    "billingAddress1": "123 Main St",
    "billingCity": "New York",
    "billingState": "NY",
    "billingPostalCode": "10001",
    "billingCountry": "US",
    "sandbox": true,
    "createdAt": "2026-01-15T10:30:00.000Z"
  },
  "payment_method": {
    "billing_id": "1234567890",
    "customer_vault_id": "abc-vault-id"
  }
}

// Without payment fields, payment_method is null.

// If customer already exists, returns 200 with existing: true:
{
  "data": {
    "id": "uuid",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "sandbox": true,
    "createdAt": "2026-01-10T08:00:00.000Z"
  },
  "payment_method": null,
  "existing": true
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Update a customer

Update an existing customer's details. Only fields you include in the request body are updated.

PATCHhttps://paysio.com/api/v1/customers/:id

Authorizations

Authorizationstringheaderrequired

Secret key (sk_*). Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Body

first_namestring

First name

last_namestring

Last name

phonestring

Phone number

billing_address_1string

Billing street address

billing_citystring

Billing city

billing_statestring

Billing state/province

billing_postal_codestring

Billing ZIP/postal code

billing_countrystring

Billing country (2-letter ISO code)

shipping_first_namestring

Shipping recipient first name

shipping_last_namestring

Shipping recipient last name

shipping_address_1string

Shipping street address

shipping_citystring

Shipping city

shipping_statestring

Shipping state/province

shipping_postal_codestring

Shipping ZIP/postal code

shipping_countrystring

Shipping country (2-letter ISO code)

Example request — cURL

curl -X PATCH https://paysio.com/api/v1/customers/:id \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
  "first_name": "...",
  "last_name": "...",
  "phone": "..."
}'

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/customers/:id", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "first_name": "...",
    "last_name": "...",
    "phone": "..."
  }),
})
const data = await res.json()

Example response (200)

{
  "data": {
    "id": "uuid",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "phone": "+15551234567",
    "billingAddress1": "456 Oak Ave",
    "billingCity": "Los Angeles",
    "billingState": "CA",
    "billingPostalCode": "90001",
    "billingCountry": "US",
    "sandbox": true,
    "createdAt": "2026-01-15T10:30:00.000Z"
  }
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Complete custom checkout flow

This example shows the full flow: collect form data + card token from paysio.js, then create/find a customer, vault the card, and charge it — all from your server.

JavaScript

// FRONTEND: Get a token from your card form

const { token } = await paysio.createToken({
  number: '4111111111111111',
  exp_month: '12', exp_year: '29', cvv: '123',
});

// Send everything to YOUR server
await fetch('/api/checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    token,
    email: '[email protected]',
    first_name: 'Jane',
    last_name: 'Doe',
    phone: '+15551234567',
    billing_address_1: '123 Main St',
    billing_city: 'New York',
    billing_state: 'NY',
    billing_postal_code: '10001',
    billing_country: 'US',
    amount: 2999,
  }),
});

// SERVER: Process the checkout
const API = 'https://paysio.com/api/v1';
const SK = 'sk_live_your_secret_key';
const headers = {
  'Authorization': `Bearer ${SK}`,
  'Content-Type': 'application/json',
};

// Step 1: Create (or update) customer + vault card in one call
const createRes = await fetch(`${API}/customers`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    email: body.email,
    first_name: body.first_name,
    last_name: body.last_name,
    phone: body.phone,
    billing_address_1: body.billing_address_1,
    billing_city: body.billing_city,
    billing_state: body.billing_state,
    billing_postal_code: body.billing_postal_code,
    billing_country: body.billing_country,
    payment_token: body.token,  // vault the card at creation
  }),
});

const { data: customer, payment_method, existing } = await createRes.json();
const customerId = customer.id;
// If existing === true, customer was updated (not duplicated)
// payment_method.billing_id — reference for this card

// Step 2: Charge the customer
const chargeRes = await fetch(`${API}/charges`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    customer_id: customerId,
    amount: body.amount,
    currency: 'USD',
  }),
});

const { data: charge } = await chargeRes.json();
// charge.status === 'pending_settlement' means success