Payment Methods

Vault and manage saved payment methods.

Use a Collect.js token or raw card details to vault a card, then charge it later via POST /charges. On Paysio Debit & Payouts workspaces you can also save bank accounts — usable for ACH debits and as payout destinations.

Add Payment Method

Save a payment method to a customer. If the customer has no vault yet, one is created automatically. Accepts a paysio.js token (from paysio.createToken()), raw card details, or — on bank-capable workspaces (Paysio Debit & Payouts or NMI) — bank account details with type 'bank_account'.

POSThttps://paysio.com/api/v1/customers/:id/payment-methods

Authorizations

Authorizationstringheaderrequired

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

Body

typestring

"card" (default) or "bank_account" (Paysio Debit & Payouts or NMI workspaces)

payment_tokenstring

Token from paysio.createToken() (card)

cc_numberstring

Card number (use payment_token instead when possible)

cc_exp_monthstring

Expiry month (01-12), required with cc_number

cc_exp_yearstring

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

routing_numberstring

9-digit routing number, required with type "bank_account"

account_numberstring

Bank account number (4-17 digits), required with type "bank_account"

account_typestring

"checking" (default) or "saving", with type "bank_account" (only used by NMI)

account_holder_typestring

"personal" (default) or "business", with type "bank_account" (NMI eCheck only; ignored by Debit & Payouts)

descriptionstring

Optional label for a bank account (e.g. "Payroll account")

Example request — cURL

curl -X POST https://paysio.com/api/v1/customers/:id/payment-methods \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "...",
  "payment_token": "...",
  "cc_number": "..."
}'

Example request — JavaScript

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

Example response (200)

// Card:
{
  "data": {
    "billing_id": "1234567890",
    "customer_vault_id": "abc-vault-id"
  }
}

// Bank account (type: "bank_account"):
{
  "data": {
    "id": "instrument-id",
    "billing_id": "instrument-id",
    "type": "bank_account",
    "bank_last_four": "7890",
    "routing_number": "021000021",
    "customer_vault_id": "identity-id"
  }
}

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"
}

List Payment Methods

List a customer's saved payment methods, with masked details. Treat id as an OPAQUE string — pass it as payment_method_id to POST /charges, /payouts, /account-checks and /three-ds/authenticate, but never parse or build it yourself. On accounts using the Paysio vault (the default for cards on NMI and Debit & Payouts) ids look like 'vault_…' and processor is 'paysio_vault'; legacy methods keep their gateway instrument id. Both forms are accepted everywhere. payout_eligible tells you whether a method can receive a payout — banks and debit/prepaid cards qualify once Debit & Payouts is enabled, while a known CREDIT card returns false (push-to-card only settles on debit rails; unclassified cards default to true and are re-verified at send time). Paysio-vaulted methods are gateway-agnostic, so a card saved while charging on NMI can still be paid out. Lists can mix cards and bank accounts (type 'bank_account').

GEThttps://paysio.com/api/v1/customers/:id/payment-methods

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/payment-methods \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

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

Example response (200)

{
  "data": [
    {
      "id": "vault_2f6c1b90-8d3e-4a71-9c02-5b8e7a4d1e33",
      "billing_id": "vault_2f6c1b90-8d3e-4a71-9c02-5b8e7a4d1e33",
      "type": "card",
      "processor": "paysio_vault",
      "payout_eligible": true,
      "card_last_four": "1111",
      "card_type": "visa",
      "card_bin": "411111",
      "is_default": true,
      "cc_exp": "12/28",
      "first_name": "Jane",
      "last_name": "Doe",
      "created_at": "2026-01-15T10:30:00"
    },
    {
      "id": "instrument-id",
      "billing_id": "instrument-id",
      "type": "bank_account",
      "processor": "aptpay",
      "payout_eligible": true,
      "card_last_four": null,
      "bank_last_four": "7890",
      "card_type": null,
      "cc_exp": null,
      "created_at": "2026-01-16T09:00:00"
    }
  ]
}

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"
}

Delete a payment method

Remove a saved payment method from a customer's vault.

DELETEhttps://paysio.com/api/v1/customers/:id/payment-methods/:billingId

Authorizations

Authorizationstringheaderrequired

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

Example request — cURL

curl -X DELETE https://paysio.com/api/v1/customers/:id/payment-methods/:billingId \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

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

Example response (200)

{
  "data": {
    "deleted": true,
    "billing_id": "1234567890"
  }
}

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"
}