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	Card Object	`null`	Basis Theory Card Token.
`card`	conditional	Card Object	`null`	Credit or debit card raw details.
`encryptedCard`	conditional	string	`null`	Card details encrypted using provided client encryption key.

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.
`expirationMonth`	true	string	`null`	Card expiration month in `MM` format.
`expirationYear`	true	string	`null`	Card expiration year in `YYYY` format.
`cvc`	true	string	`null`	Card security code.

Response

{
  "id": "26859380-7829-4ee1-8a0a-38927881e7ef",
  "type": "card",
  "entityId": "user-12345",
  "card": {
    "type": "credit",
    "brand": "visa",
    "details": {
      "bin": "424242",
      "last4": "4242",
      "expirationMonth": "12",
      "expirationYear": "2025"
    },
    "display": {
      "name": "Visa",
      "color": "#1A1F71"
    }
  },
  "credentialTypes": ["network-token", "virtual-card", "pan"],
  "createdAt": "2025-01-15T14:00:00Z",
  "token": {
    "id": "token_26859380-7829-4ee1-8a0a-38927881e7ef",
    "fingerprint": "fp_1234567890abcdef",
    "createdAt": "2025-01-15T14:00:00Z",
    "maskedData": "424242****4242"
  }
}

Response Properties

Property	Type	Description
`id`	string	The payment method ID.
`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 for this payment method.
`createdAt`	string	ISO 8601 timestamp when the payment method was created.
`token`	Token Object	Secure token information from BasisTheory.

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

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.

Note: The token object is only included if the project has its own BasisTheory API key configured.

Error Handling

{
  "error": {
    "status": 400,
    "type": "invalidRequest",
    "title": "The request is invalid",
    "message": "Request is invalid, check details object for details.",
    "details": {
      "fields": {
        "card.number": "Must be a valid card number."
      }
    }
  }
}