---
title: "Create payment method"
method: POST
path: "/payment_methods"
tags: ["payment_methods"]
---

# Create payment method

`POST /payment_methods`

Add a payment method (credit card, bank account/ACH, Apple Pay, Google Pay, or third party token) to the authenticated environment's vault.

To create a test payment method, use one of the [test card numbers](https://developer.spreedly.com/docs/test-data). For more information see the [Spreedly testing guide](https://developer.spreedly.com/docs/testing).

Third party tokens are payment methods stored in the Spreedly vault, that are a reference to another payment method stored at the gateway's vault. For more information see the [third party token guide](https://developer.spreedly.com/docs/third-party-vaulting).

## Request body

- PaymentMethodRequest
  - `payment_method` object
    - `credit_card` CreditCard — Credit card element
      - `first_name` string, required — The first name of the cardholder
      - `last_name` string, required — The last name of the cardholder
      - `full_name` string — The full name of the cardholder. If provided, `full_name` will be parsed to determine `first_name` and `last_name`. If “full_name” is entered with only a single name, “first_name” will be populated with “Not Provided” and “last_name” will be populated with the provided name.
      - `number` string, required — The full card number
      - `verification_value` string — The verification value (CVV/CVC) of the card
      - `month` string, required — The expiration month of the card
      - `year` string, required — The 4 digit expiration year of the card
      - `company` string — The company name associated with the credit card
      - `address1` string — The first line of the billing address
      - `address2` string — The second line of the billing address
      - `city` string — The city of the billing address
      - `state` string — The state of the billing address
      - `zip` string — The zip code of the billing address
      - `country` string — The country code of the billing address
      - `phone_number` string — The phone number of the billing address
      - `shipping_address1` string — The first line of the shipping address
      - `shipping_address2` string — The second line of the shipping address
      - `shipping_city` string — The city of the shipping address
      - `shipping_state` string — The state of the shipping address
      - `shipping_zip` string — The zip code of the shipping address
      - `shipping_country` string — The country code of the shipping address
      - `shipping_phone_number` string — The phone number of the shipping address
    - `bank_account` BankAccount
      - `first_name` string, required — The first name of the account owner
      - `last_name` string, required — The last name of the account owner
      - `bank_routing_number` string, required — The account routing number
      - `bank_account_number` string, required — The account number
      - `bank_account_type` 'checking' | 'savings' — The type of account. Can be one of `checking` or `savings`.
      - `bank_account_holder_type` 'business' | 'personal' — The account holder type. Can be one `business` or `personal`.
      - `full_name` string — The full name of the account owner. If provided, will be parsed to determine first_name and last_name. Note: optional: either full_name or both first_name and last_name are required
    - `apple_pay` ApplePay
      - `payment_data` object, required — The JSON serialized [`paymentData` property of an Apple Pay PKPaymentToken](https://developer.apple.com/library/ios/documentation/PassKit/Reference/PaymentTokenJSON/PaymentTokenJSON.html#//apple_ref/doc/uid/TP40014929-CH8-SW2)
        - `version` unknown
        - `data` unknown
        - `signature` unknown
        - `header` object
          - `ephemeralPublicKey` unknown
          - `transactionId` unknown
          - `publicKeyHash` unknown
      - `test_card_number` unknown
    - `google_pay` GooglePay
      - `payment_data` object, required — The JSON serialized [paymentData](https://developers.google.com/pay/api/web/guides/resources/payment-data-cryptography#payment-method-token-structure)
        - `signature` string — Verifies that the message came from Google. Base64-encoded. Created using ECDSA.
        - `protocolVersion` string — Identifies the encryption/signing scheme under which the message was created. Allows the protocol to evolve over time, if needed. If it's not set, assume `ECv0`.
        - `signedMessage` string — A serialized JSON string containing the `encryptedMessage`, `ephemeralPublicKey` and `tag`. Serialized to simplify the signature verification process.
      - `test_card_number` string — Specify a [test card number](https://developer.spreedly.com/docs/test-data#credit-cards) in this field. Doing so will prevent this payment method from being used against a production gateway, while still verifying the submitted Google Pay payment data.
      - `first_name` string — The first name of the cardholder
      - `last_name` string — The last name of the cardholder
      - `address_1` string — Cardholder's address, line 1
      - `address_2` string — Cardholder's address, line 2
      - `city` string — Cardholder's city
      - `state` string — Cardholder's state
      - `zip` string — Cardholder's zip
      - `country` string — Cardholder's country
    - `payment_method_type` string — For third party token vaulting requests, set to `third_party_token` to represent an externally vaulted payment method reference
    - `reference` string — For third party token vaulting requests, the token identifying the payment method at the external gateway
    - `gateway_type` string — Required for third party token vaulting requests. The type of the external gateway
    - `email` string — The email address of the customer associated with this credit card
    - `retained` boolean — `true` if this payment method should be automatically retained on creation
    - `allow_blank_name` boolean — `true` if this payment method should skip the name validation requirement
    - `allow_expired_date` boolean — `true` if this payment method should skip the expired date validation requirement
    - `allow_blank_date` boolean — `true` if this payment method should skip the expiration date validation requirement
    - `eligible_for_card_updater` boolean — `true` if this payment method should be included in Account Updater
    - `metadata` object — metadata key-value pairs (limit 25). Keys are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types
    - `provision_network_token` boolean — `true` if this transaction should attempt to provision a network token. `false` or omit this element to not provision a network token for this transaction. Please see our [network tokenization guide](https://developer.spreedly.com/docs/network-tokenization#provisioning-network-tokens) for more details.

## Response `201`

Created

- PaymentMethodCreateResponse
  - `transaction` object — Root element
    - `token` string — The token uniquely identifying this transaction (not the created payment method) at Spreedly
    - `succeeded` boolean — `true` if the transaction request was successfully executed, `false` otherwise
    - `retained` string — if the payment method was set to be automatically retained on creation
    - `payment_method` object — The payment method created as part of this transaction
      - `token` string — The token identifying the newly created payment method in the Spreedly vault
      - `created_at` string — The time the payment method token was created
      - `updated_at` string — The time the payment method token was last updated
      - `email` string — The email address of the customer associated with this credit card
      - `storage_state` string — The `storage_state` (retained, redacted, cached, used) of the payment method
      - `test` boolean — `true` if this payment method is a test payment method and cannot be used against real gateways or receivers
      - `metadata` object — metadata key-value pairs (limit 25). Keys are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types
      - `callback_url` string — The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by `callback_format` if provided or XML if `callback_format` is not present or null. (default: `null`)
      - `last_four_digits` string — The last four digits of the credit card number. This can be displayed to the user.
      - `first_six_digits` string — The first six digits of the credit card number. This can be displayed to the user.
      - `card_type` string — The [type](https://developer.spreedly.com/docs/supported-payment-methods), or brand, of the card. Please see the `card_type_mapping` function below for more detail.
      - `first_name` string — The first name of the cardholder
      - `last_name` string — The last name of the cardholder
      - `month` string — The expiration month
      - `year` string — The expiration year
      - `address1` string — The first line of the billing address
      - `address2` string — The second line of the billing address
      - `city` string — The city of the billing address
      - `state` string — The state of the billing address
      - `zip` string — The zip code of the billing address
      - `country` string — The country code of the billing address
      - `phone_number` string — The phone number of the billing address
      - `company` string — The company of the cardholder
      - `full_name` string — The full name of the cardholder.
      - `eligible_for_card_updater` string — `true` if this payment method should be included in Account Updater
      - `shipping_address1` string — The first line of the shipping address
      - `shipping_address2` string — The second line of the shipping address
      - `shipping_city` string — The city of the shipping address
      - `shipping_state` string — The state of the shipping address
      - `shipping_zip` string — The zip code of the shipping address
      - `shipping_country` string — The country code of the shipping address
      - `issuer_identification_number` string — The numbers of the PAN required to identify the card issuer.
      - `click_to_pay` string — `true` if the card was tokenized using Click to Pay
      - `managed` string — The value indicating the payment method's management status.
      - `payment_method_type` string — The type of this payment method, e.g., `credit_card`, `bank_account`, `apple_pay`, `google_pay`, `third_party_token`, etc…
      - `errors` string — If the payment method is invalid (missing required fields, etc…), there will be associated error messages here
      - `fingerprint` string — An identifying string that will match all cards in the environment with the same PAN
      - `verification_value` string — The obscured verification value (CVV), e.g., XXX or XXXX
      - `number` string — The obscured credit card number, e.g., XXXX-XXXX-XXXX-4444
      - `subscribed_to_mastercard_abu` boolean — `true` if this payment method is subscribed to Mastercard ABU updating service
      - `last_successfully_used` string, date-time, nullable — The time (UTC) the payment method was last successfully transacted with. The following transaction types are considered: Authorization, Purchase, Verification, GeneralCredit, OffsiteVerification, or OffsitePurchase
    - `network_tokenization` NetworkTokenization — The network tokenization details for the transaction
      - `provisioned` boolean — Indicates if the network tokenization was successfully provisioned
      - `token_status` string — The status of the network token
      - `token_reference` string — The unique reference key for the network token
      - `token_first_six_digits` string — The first six digits of the network token's DPAN
      - `token_last_four_digits` string — The last four digits of the network token's DPAN
      - `token_created_at` string — The timestamp when the network token was created
      - `token_updated_at` string — The timestamp when the network token was last updated
      - `attempted` boolean — Indicates if the transaction attempted to use a network token
      - `errors` object[] — An array of errors that occurred during the network tokenization process
        - `key` string — The error key
        - `message` string — The error message
        - `action` string — The action taken which lead to the error

## Other responses

- `422` — Unprocessable Entity

---

[API](https://skmtc.dev/spreedly/apis/spreedly-api-v1.md) · [All operations](https://skmtc.dev/spreedly/apis/spreedly-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/spreedly/spreedly-api-v1/revisions/72ba4e23e65c/schema)