---
title: "Create a Payment Method"
method: POST
path: "/payment_methods"
tags: ["Payment Methods"]
---

# Create a Payment Method

`POST /payment_methods`

## Request

- Base URL: `https://api.justifi.ai/v1`
- URL: `https://api.justifi.ai/v1/payment_methods`
- Auth: none declared. Required headers: `Idempotency-Key`, `Authorization`, `Sub-Account`
- TypeScript: <https://skmtc.dev/justifi/apis/justifi-api-documentation/docs/payment_methods/post.ts> (a function with typed inputs; its response is checked against the schema)

**This endpoint requires prior approval.** New integrations should use the
**[JustiFi Tokenize Payment Method Web Component](https://docs.justifi.tech/web-components/payment-facilitation/tokenize-payment-method)** 
to securely collect and tokenize payment method details.

The web component handles PCI-scoped data collection and returns a payment method token that you can pass to the
[Create Payment](https://docs.justifi.tech/api-spec#tag/Payments/operation/CreatePayment) endpoint.

If you have a use case that requires creating payment methods directly via the API, contact [JustiFi Customer Success](mailto:customer_success@justifi.tech) for approval. 
At minimum, a completed SAQ (Self-Assessment Questionnaire) is required to allow raw PAN submissions.

*Note: If the sub account status is not `enabled`, `400` will be returned.*

## Headers

- `Idempotency-Key` string, uuid, required
- `Authorization` string, required
- `Sub-Account` string, required

## Request body

- object
  - `payment_method` object, required
    - `payment_method_group_id` string: When present this payment method will be associated with the given payment method group
    - `card` CreateCard
      - `name` string, required: cardholder full name
      - `number` string, required: card number
      - `verification` string: card verification number
      - `month` string, required: card expiration month
      - `year` string, required: card expiration year
      - `address_line1` string: card address street
      - `address_line2` string: card address apartment, suite, etc.
      - `address_city` string: card address city
      - `address_state` string: card address state
      - `address_postal_code` string, required: card address ZIP
      - `address_country` string: card address 2-character country code
      - `brand` string: card brand or institution
      - `metadata` object: any useful information you'd like to store alongside this card
    - `bank_account` CreateBankAccount: Bank Account
      - `account_owner_name` string, required: account owner name
      - `routing_number` string, required: routing number
      - `account_number` string, required: bank account number
      - `account_type` 'checking' | 'savings', required: type of account
      - `account_owner_type` 'individual' | 'company', required: type of account holder
      - `country` string, required: country associated with the bank account
      - `currency` 'usd' | 'cad', required: currency of the bank account
      - `bank_name` string: bank name
      - `metadata` object: any useful information you'd like to store alongside this bank account
  - `email` string, email: email address to associate with the payment method
  - `force_tokenize` boolean: Optional. If set to true in the request payload, allows for tokenization even if validations and authorization fail during the creation of the payment method

## Response `201`

Payment method was created successfully

- union
  - CardResponse
    - `id` number: the object id
    - `type` string: the object type, or array of objects
    - `data` object: the attributes for the object
      - `id` string: unique id of the payment method
      - `signature` string, nullable: unique signature associated with the payment_method
      - `customer_id` string, nullable: customer_id is a deprecated field. Please use our payment method groups instead.
      - `account_id` string, nullable: account id associated with payment method
      - `status` string: signals whether the payment method is valid or invalid
      - `invalid_reason` string, nullable: informs reason that the payment method has been marked invalid, if status is invalid
      - `payment_method_import_id` string, nullable: id of the payment method import that created this payment method, if it was imported
      - `created_at` string, date-time
      - `updated_at` string, date-time
      - `card` object: the card associated with the payment_method
        - `id` string, uuid: unique card payment method id
        - `name` string, nullable: card holder name
        - `acct_last_four` string: last 4 digits of the account number
        - `brand` string: card brand or institution
        - `digital_wallet` 'apple_pay' | 'google_pay' | 'null', nullable: which digital wallet provider the card is tied to
        - `token` string: same value as unique bank account id; can be saved and used to process multiple payments with the same bank account
        - `month` string: expiration date month
        - `year` string: expiration date year
        - `metadata` object, nullable: any useful information you'd like to store alongside this card
        - `address_line1_check` 'fail' | 'pass' | 'unavailable' | 'unchecked': Result of the address line 1 verification check. `pass` — matches the cardholder's address on file; `fail` — does not match; `unavailable` — verification could not be performed; `unchecked` — no address was provided for verification.
        - `address_postal_code_check` 'fail' | 'pass' | 'unavailable' | 'unchecked': Result of the postal code verification check. `pass` — matches the cardholder's postal code on file; `fail` — does not match; `unavailable` — verification could not be performed; `unchecked` — no postal code was provided for verification.
        - `bin_details` BinDetails, nullable: BIN (Bank Identification Number) details for a card. bin_details are not guaranteed to be present on every card payment method — availability depends on the card network and issuer. When unavailable, this field will be null.
          - `type` string: Type of card issued, values include Credit, Debit, Prepaid, Unknown
          - `card_brand` string: Brand or network associated with card. Possible values include Visa, Mastercard, American Express, Discover
          - `card_class` string
          - `country` string: Long form country name which issued the card
          - `issuer` string: Issuing bank
          - `funding_source` string: Source of funds defined by BIN for a given card. Values include Charge, Credit, Debit, Deferred Debit (Visa Only), Network Only, Prepaid
    - `page_info` string, nullable: information for cursor style pagination, is null for single records
  - BankAccountResponse
    - `id` number: the object id
    - `type` string: the object type, or array of objects
    - `data` object: the attributes for the object
      - `id` string: unique id of the payment method
      - `signature` string, nullable: unique signature associated with the payment_method
      - `customer_id` string, nullable: customer_id is a deprecated field. Please use our payment method groups instead.
      - `account_id` string: account id associated with payment method
      - `status` string: signals whether the payment method is valid or invalid
      - `invalid_reason` string, nullable: informs reason that the payment method has been marked invalid, if status is invalid
      - `payment_method_import_id` string, nullable: id of the payment method import that created this payment method, if it was imported
      - `created_at` string, date-time
      - `updated_at` string, date-time
      - `bank_account` object: the bank account associated with the payment_method
        - `id` string, uuid: unique bank account payment method id
        - `account_owner_name` string: account owner name
        - `account_type` string: type of account (checking, savings, etc.)
        - `bank_name` string, nullable: bank name
        - `acct_last_four` string: last 4 digits of the account number
        - `token` string: same value as unique bank account id; can be saved and used to process multiple payments with the same bank account
        - `metadata` object, nullable: any useful information you'd like to store alongside this bank account
    - `page_info` string, nullable: information for cursor style pagination, is null for single records
  - CardPresentResponse
    - `id` number: the object id
    - `type` string: the object type, or array of objects
    - `data` object: the attributes for the object
      - `id` string: unique id of the payment method
      - `signature` string, nullable: unique signature associated with the payment_method
      - `customer_id` string, nullable: customer_id is a deprecated field. Please use our payment method groups instead.
      - `account_id` string, nullable: account id associated with payment method
      - `status` string: signals whether the payment method is valid or invalid
      - `invalid_reason` string, nullable: informs reason that the payment method has been marked invalid, if status is invalid
      - `payment_method_import_id` string, nullable: id of the payment method import that created this payment method, if it was imported
      - `created_at` string, date-time
      - `updated_at` string, date-time
      - `card_present` object: the card present payment method
        - `id` string, uuid: unique card present payment method id
        - `brand` string: card brand or institution
        - `cardholder_name` string: name of the cardholder
        - `last4` string: last 4 digits of the card number
        - `expiry` string: card expiration date in MM/YY format
        - `type` string: the payment method type
    - `page_info` string, nullable: information for cursor style pagination, is null for single records

## Other responses

- `400`: Full card number submitted without PCI approval

---

[API](https://skmtc.dev/justifi/apis/justifi-api-documentation.md) - [All operations](https://skmtc.dev/justifi/apis/justifi-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/justifi/apis/justifi-api-documentation/revisions/dd9f3fed7e46?raw)