--- title: "Retain payment method" method: PUT path: "/payment_methods/{payment_method_token}/retain" tags: ["payment_methods"] --- # Retain payment method `PUT /payment_methods/{payment_method_token}/retain` Retain (keep in the Spreedly vault for future use) a payment method. ## Request body - 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 `200` successful - PaymentMethodRetainResponse - `transaction` object — Root element - `transaction_type` string — The type of transaction, e.g., Authorization, Capture, Credit - `token` string — The token uniquely identifying this transaction at Spreedly - `succeeded` boolean — `true` if the transaction request was successfully executed, `false` otherwise - `state` string — The current state of the transaction. Valid values are `succeeded`, `failed`, and `pending` - `payment_method` PaymentMethod - `token` string — The token identifying the 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 - `bin_metadata` object — BIN metadata is available in the response if the card is enrolled in Advanced Vault. See [BIN metadata](https://developer.spreedly.com/docs/bin-metadata) for more information. - `card_brand` string - `card_category` string - `card_type` string - `issuing_bank` string - `issuing_country_iso_number` string - `issuing_country_iso_a2_code` string - `issuing_country_iso_a3_code` string - `issuing_country_iso_name` string - `issuing_bank_phone_number` string - `issuing_bank_website` string - `bin_type` string - `regulated` string - `max_pan_length` string - `message` string - `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 - `401` — Unauthorized - `404` — Not Found - `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)