Create Payment Method

Create a payment method from payment details. This endpoint stores payment information securely and returns a tokenized reference.

Request

POST /projects/:projectId/payment-methods

URL Parameters

Parameter	Required	Type	Default	Description
`projectId`	true	string	`null`	The project ID (must match JWT issuer).

Request

curl -X POST \
  https://api.basistheory.ai/projects/:projectId/payment-methods \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "entityId": "user-12345",
    "card": {
      "number": "4242424242424242",
      "expirationMonth": "12",
      "expirationYear": "2025",
      "cvc": "123"
    }
  }'

Request Parameters

Parameter	Required	Type	Default	Description
`entityId`	true	string	`null`	Unique user identifier (must match JWT `sub` claim).
`tokenId`	conditional	string	`null`	BasisTheory card token ID (UUID format).
`card`	conditional	Card Object	`null`	Credit or debit card raw details.

Note: Either tokenId or card must be provided, but not both.

Note: Either tokenId or card or encryptedCard must be provided, but not more than one.

Card Object

Parameter	Required	Type	Default	Description
`number`	true	string	`null`	Credit or debit card number (13-19 digits, digits only).
`expirationMonth`	true	string	`null`	Card expiration month in `MM` format (01-12).
`expirationYear`	true	string	`null`	Card expiration year in `YYYY` format (current year or later).
`cvc`	true	string	`null`	Card security code (3-4 digits).

Response

{
  "id": "26859380-7829-4ee1-8a0a-38927881e7ef",
  "type": "card",
  "entityId": "user-12345",
  "card": {
    "brand": "mastercard",
    "type": "credit",
    "details": {
      "bin": "424242",
      "last4": "4242",
      "expirationMonth": "12",
      "expirationYear": "2025"
    },
    "display": {
      "name": "Mastercard",
      "color": "#FF5A00"
    }
  },
  "credentialTypes": ["virtual-card"],
  "createdAt": "2025-01-15T14:00:00Z"
}

Response Properties

Property	Type	Description
`id`	string	The payment method ID (UUID).
`type`	string	The payment method type (always “card”).
`entityId`	string	The user ID that owns this payment method.
`card`	Card Object	Card-specific details and metadata.
`credentialTypes`	string[]	Array of credential types available (currently only [“virtual-card”]).
`createdAt`	string	ISO 8601 timestamp when the payment method was created.
`token`	Token Object	Secure token information from BasisTheory (legacy only).

Card Object

Property	Type	Description
`type`	string	The card type: `debit` or `credit`.
`brand`	string	The card brand (i.e. `visa`, `mastercard`).
`details`	Card Details Object	Details about the card.
`display`	Card Display Object	UI details for displaying the card.

Card Details Object

Property	Type	Description
`bin`	string	6 digit card BIN number.
`last4`	string	Card last 4 numbers.
`expirationMonth`	string	Card expiration month in `MM` format.
`expirationYear`	string	Card expiration year in `YYYY` format.

Card Display Object

Property	Type	Description
`name`	string	Human-readable card brand name.
`color`	string	Hex color code for UI rendering.

Token Object (Legacy)

Property	Type	Description
`id`	string	BasisTheory token ID for the stored card data.
`fingerprint`	string	Unique fingerprint for identifying duplicate cards.
`createdAt`	string	ISO 8601 timestamp when the token was created.
`maskedData`	string	Masked card number for display purposes.

Error Handling

{
  "error": {
    "status": 400,
    "type": "validation_error",
    "title": "Validation failed",
    "message": "The request contained invalid data.",
    "details": {
      "fields": {
        "card.number": "Card number must be at least 13 digits.",
        "card.expirationMonth": "Expiration month must be in MM format (01-12).",
        "card.expirationYear": "Expiration year must be current year or later.",
        "card.cvc": "CVC must be 3 or 4 digits.",
        "tokenId": "Token ID must be a valid UUID."
      }
    }
  }
}