Create a payment method

Error

A valid request URL is required to generate request examples

{
  "id": "<string>",
  "object": "payment_method",
  "type": "card",
  "livemode": true,
  "reusable": true,
  "status": "active",
  "customer": "<string>",
  "card": {
    "last4": "<string>",
    "brand": "visa",
    "exp_month": 123,
    "exp_year": 123,
    "funding_type": "credit",
    "country": "<string>"
  },
  "card_present": {
    "bin": "<string>",
    "last4": "<string>",
    "brand": "visa",
    "funding_type": "credit",
    "entry_method": "chip"
  },
  "fingerprint": "<string>",
  "metadata": {},
  "created_at": 123,
  "billing_details": {
    "name": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "address": {
      "line1": "<string>",
      "line2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postal_code": "<string>",
      "country": "<string>"
    }
  }
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "reusable is required"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

POST

payment_methods

Error

A valid request URL is required to generate request examples

{
  "id": "<string>",
  "object": "payment_method",
  "type": "card",
  "livemode": true,
  "reusable": true,
  "status": "active",
  "customer": "<string>",
  "card": {
    "last4": "<string>",
    "brand": "visa",
    "exp_month": 123,
    "exp_year": 123,
    "funding_type": "credit",
    "country": "<string>"
  },
  "card_present": {
    "bin": "<string>",
    "last4": "<string>",
    "brand": "visa",
    "funding_type": "credit",
    "entry_method": "chip"
  },
  "fingerprint": "<string>",
  "metadata": {},
  "created_at": 123,
  "billing_details": {
    "name": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "address": {
      "line1": "<string>",
      "line2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postal_code": "<string>",
      "country": "<string>"
    }
  }
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "reusable is required"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Authorizations

Authorization

string

header

required

A merchant secret key (sk_…) sent as Authorization: Bearer <key>.

Headers

Idempotency-Key

string

A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.

Maximum string length: 255

Body

application/json

type

enum<string>

required

The payment method type. Currently only card is supported.

Available options:

card

token

string

required

A one-time payment token created by the client-side card form.

reusable

boolean

required

true for an instrument that can be charged multiple times; false for a single-use token consumed on its first charge.

currency

string

Three-letter ISO currency code.

customer

string | null

Customer id (cus_…) to attach this method to immediately after creation.

billing_details

object | null

Optional. When provided, becomes the method's initial billing details.

Show child attributes

metadata

object

A string key-value map for storing your own structured data.

Show child attributes

Response

The created payment method.

string

required

The payment method id (pm_…).

object

enum<string>

required

Always payment_method.

Available options:

payment_method

type

enum<string>

required

card is an online/vaulted card. card_present is Ionic's read-only record of one physical Terminal presentation.

Available options:

card,

card_present

livemode

boolean

required

Whether this method belongs to the live (true) or test (false) environment.

reusable

boolean

required

true when the method can be charged multiple times; false for a single-use method that is consumed by its first charge. Only reusable methods can become expired or revoked; single-use methods cannot be revoked and never expire.

status

enum<string>

required

active — eligible for its type-specific application flow. consumed — used by a single-use charge. expired — network-expired reusable card. revoked — permanently deactivated by the merchant. A card_present method is staged active and consumed atomically by Terminal payment processing; clients cannot charge it directly.

Available options:

active,

consumed,

expired,

revoked

customer

string | null

required

The attached customer id (cus_…), or null if not attached.

card

object | null

required

Card details. Present for type: card; null otherwise.

Show child attributes

card_present

object | null

required

Card details returned for type: card_present, or null when unavailable. Null for type: card.

Show child attributes

fingerprint

string

required

Stable card identifier for duplicate detection when available. Always empty for type: card_present.

metadata

object

required

A string key-value map for storing your own structured data.

Show child attributes

created_at

integer

required

Unix epoch seconds.

billing_details

object | null

Billing details captured for this method. Null when not supplied.

Show child attributes

Start here

Checkout

Commerce

Checkout endpoints

Payment link endpoints

Catalog endpoints

Payments

Terminal locations

Terminal management

Terminal testing

Terminal payments

Invoices

Subscriptions

Setup intents

Credit notes

Webhook endpoints

Customer endpoints

API key endpoints

Payment method endpoints

Create a payment method

Authorizations

Headers

Body

Response