# Add a payment method
> Add a payment method to a shopper's Bolt Account Wallet. For security purposes, this request must come from your backend.
**Note**: Before using this API, the credit card details must be tokenized by Bolt's credit card tokenization service. Please review our [Bolt Payment Field Component](https://help.boltapp.com/products/ignite/api-implementation/#enhance-payments) or [Install the Bolt Tokenizer](https://help.boltapp.com/developers/references/bolt-tokenizer) documentation.
Source: https://help.boltapp.com/api-reference/embeddable-checkout-v3/account/accountaddpaymentmethod
`POST /account/payment-methods`
## OpenAPI definition
This endpoint as it appears in the OpenAPI document, with every schema it references included.
```json
{
"openapi": "3.2.0",
"info": {
"version": "3.3.22",
"title": "Bolt API Reference",
"description": "A comprehensive Bolt API reference for interacting with Accounts, Payments, Orders and more.",
"termsOfService": "https://www.boltapp.com/end-user-terms",
"contact": {
"name": "Bolt",
"email": "merchantsupport@boltapp.com",
"url": "https://help.boltapp.com/api-bolt/"
}
},
"servers": [
{
"url": "https://{environment}.boltapp.com/v3",
"variables": {
"environment": {
"enum": [
"api",
"api-sandbox"
],
"default": "api-sandbox"
}
}
}
],
"paths": {
"/account/payment-methods": {
"post": {
"summary": "Add a payment method",
"operationId": "accountAddPaymentMethod",
"x-speakeasy-name-override": "AddPaymentMethod",
"description": "Add a payment method to a shopper's Bolt Account Wallet. For security purposes, this request must come from your backend.
**Note**: Before using this API, the credit card details must be tokenized by Bolt's credit card tokenization service. Please review our [Bolt Payment Field Component](https://help.boltapp.com/products/ignite/api-implementation/#enhance-payments) or [Install the Bolt Tokenizer](https://help.boltapp.com/developers/references/bolt-tokenizer) documentation.",
"tags": [
"Account"
],
"security": [
{
"oauth": [
"bolt.account.manage"
],
"api-key": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/x-publishable-key"
},
{
"$ref": "#/components/parameters/x-merchant-client-id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment-method"
},
"examples": {
"credit-card-address-reference-id": {
"$ref": "#/components/examples/credit-card-with-address-id"
},
"credit-card-address-reference-explicit": {
"$ref": "#/components/examples/credit-card-with-address-explicit"
}
}
}
}
},
"responses": {
"200": {
"description": "The payment method was successfully added",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment-method"
}
}
}
},
"4XX": {
"$ref": "#/components/responses/response-payment-method-error"
},
"default": {
"$ref": "#/components/responses/response-default"
}
}
}
}
},
"components": {
"parameters": {
"x-publishable-key": {
"description": "The publicly shareable identifier used to identify your Bolt merchant division.",
"in": "header",
"name": "X-Publishable-Key",
"required": true,
"schema": {
"type": "string"
}
},
"x-merchant-client-id": {
"description": "A unique identifier for a shopper's device, generated by Bolt. The value is retrieved with `Bolt.state.merchantClientId` in your frontend context, per-shopper. This header is required for proper attribution of this operation to your analytics reports. Omitting this header may result in incorrect statistics.",
"in": "header",
"name": "X-Merchant-Client-Id",
"required": false,
"schema": {
"type": "string"
}
}
},
"schemas": {
"payment-method": {
"oneOf": [
{
"$ref": "#/components/schemas/payment-method-credit-card"
},
{
"$ref": "#/components/schemas/payment-method-googlepay"
},
{
"$ref": "#/components/schemas/payment-method-applepay"
},
{
"$ref": "#/components/schemas/payment-method-paypal"
},
{
"$ref": "#/components/schemas/payment-method-affirm"
},
{
"$ref": "#/components/schemas/payment-method-afterpay"
},
{
"$ref": "#/components/schemas/payment-method-klarna"
},
{
"$ref": "#/components/schemas/payment-method-klarna-account"
},
{
"$ref": "#/components/schemas/payment-method-klarna-paynow"
}
],
"discriminator": {
"propertyName": ".tag",
"mapping": {
"credit_card": "#/components/schemas/payment-method-credit-card",
"googlepay": "#/components/schemas/payment-method-googlepay",
"applepay": "#/components/schemas/payment-method-applepay",
"paypal": "#/components/schemas/payment-method-paypal",
"affirm": "#/components/schemas/payment-method-affirm",
"afterpay": "#/components/schemas/payment-method-afterpay",
"klarna": "#/components/schemas/payment-method-klarna",
"klarna_account": "#/components/schemas/payment-method-klarna-account",
"klarna_paynow": "#/components/schemas/payment-method-klarna-paynow"
}
}
},
"payment-method-credit-card": {
"title": "Credit Card Payment Method",
"allOf": [
{
"type": "object",
"required": [
".tag",
"type",
"billing_address"
],
"properties": {
".tag": {
"type": "string",
"enum": [
"credit_card"
],
"x-order": 0,
"examples": [
"credit_card"
]
},
"id": {
"type": "string",
"format": "id",
"readOnly": true,
"x-order": 1,
"examples": [
"X5h6j8uLpVGK"
]
},
"type": {
"type": "string",
"description": "The type of payment method",
"x-order": 2,
"examples": [
"credit_card"
]
},
"billing_address": {
"$ref": "#/components/schemas/address-reference"
}
}
},
{
"$ref": "#/components/schemas/credit-card"
}
]
},
"address-reference": {
"oneOf": [
{
"$ref": "#/components/schemas/address-reference-id"
},
{
"$ref": "#/components/schemas/address-reference-explicit"
},
{
"$ref": "#/components/schemas/address-reference-partial"
}
],
"discriminator": {
"propertyName": ".tag",
"mapping": {
"id": "#/components/schemas/address-reference-id",
"explicit": "#/components/schemas/address-reference-explicit",
"partial": "#/components/schemas/address-reference-partial"
}
}
},
"address-reference-id": {
"type": "object",
"title": "Address ID Reference",
"required": [
".tag",
"id"
],
"properties": {
".tag": {
"type": "string",
"enum": [
"id"
],
"description": "The type of address reference",
"examples": [
"id"
]
},
"id": {
"type": "string",
"format": "id",
"description": "The address's ID",
"examples": [
"D4g3h5tBuVYK9"
]
}
}
},
"address-reference-explicit": {
"type": "object",
"title": "Explicit Address Reference",
"required": [
".tag",
"first_name",
"last_name",
"street_address1",
"locality",
"postal_code",
"country_code"
],
"properties": {
".tag": {
"type": "string",
"enum": [
"explicit"
],
"description": "The type of address reference",
"x-order": 0,
"examples": [
"explicit"
]
},
"id": {
"type": "string",
"format": "id",
"description": "The address's unique identifier.",
"readOnly": true,
"x-order": 1,
"examples": [
"D4g3h5tBuVYK9"
]
},
"first_name": {
"type": "string",
"description": "The first name of the person associated with this address.",
"x-order": 2,
"examples": [
"Alice"
]
},
"last_name": {
"type": "string",
"description": "The last name of the person associated with this address.",
"x-order": 3,
"examples": [
"Baker"
]
},
"company": {
"type": "string",
"description": "The company associated with this address.",
"x-order": 4,
"examples": [
"ACME Corporation"
]
},
"street_address1": {
"type": "string",
"description": "The street address associated with this address.",
"x-order": 5,
"examples": [
"535 Mission St, Ste 1401"
]
},
"street_address2": {
"type": "string",
"description": "Any additional, optional, street address information associated with this address.",
"x-order": 6,
"examples": [
"c/o Shipping Department"
]
},
"locality": {
"type": "string",
"description": "The locality (e.g. city, town, etc...) associated with this address.",
"x-order": 7,
"examples": [
"San Francisco"
]
},
"postal_code": {
"type": "string",
"description": "The postal code associated with this address.",
"x-order": 8,
"examples": [
"94105"
]
},
"region": {
"type": "string",
"description": "The region or administrative area (e.g. state, province, county, etc...) associated with this address.",
"x-order": 9,
"examples": [
"CA"
]
},
"country_code": {
"$ref": "#/components/schemas/country-code"
},
"email": {
"type": "string",
"format": "email",
"description": "The email address associated with this address.",
"x-order": 11,
"examples": [
"alice@example.com"
]
},
"phone": {
"type": "string",
"format": "phone",
"description": "The phone number associated with this address.",
"x-order": 12,
"examples": [
"+14155550199"
]
}
}
},
"country-code": {
"type": "string",
"description": "The country (in its ISO 3166 alpha-2 format) associated with this address.",
"enum": [
"AF",
"AX",
"AL",
"DZ",
"AS",
"AD",
"AO",
"AI",
"AQ",
"AG",
"AR",
"AM",
"AW",
"AU",
"AT",
"AZ",
"BH",
"BS",
"BD",
"BB",
"BY",
"BE",
"BZ",
"BJ",
"BM",
"BT",
"BO",
"BQ",
"BA",
"BW",
"BV",
"BR",
"IO",
"BN",
"BG",
"BF",
"BI",
"KH",
"CM",
"CA",
"CV",
"KY",
"CF",
"TD",
"CL",
"CN",
"CX",
"CC",
"CO",
"KM",
"CG",
"CD",
"CK",
"CR",
"CI",
"HR",
"CU",
"CW",
"CY",
"CZ",
"DK",
"DJ",
"DM",
"DO",
"EC",
"EG",
"SV",
"GQ",
"ER",
"EE",
"ET",
"FK",
"FO",
"FJ",
"FI",
"FR",
"GF",
"PF",
"TF",
"GA",
"GM",
"GE",
"DE",
"GH",
"GI",
"GR",
"GL",
"GD",
"GP",
"GU",
"GT",
"GG",
"GN",
"GW",
"GY",
"HT",
"HM",
"VA",
"HN",
"HK",
"HU",
"IS",
"IN",
"ID",
"IR",
"IQ",
"IE",
"IM",
"IL",
"IT",
"JM",
"JP",
"JE",
"JO",
"KZ",
"KE",
"KI",
"KP",
"KR",
"KW",
"KG",
"LA",
"LV",
"LB",
"LS",
"LR",
"LY",
"LI",
"LT",
"LU",
"MO",
"MK",
"MG",
"MW",
"MY",
"MV",
"ML",
"MT",
"MH",
"MQ",
"MR",
"MU",
"YT",
"MX",
"FM",
"MD",
"MC",
"MN",
"ME",
"MS",
"MA",
"MZ",
"MM",
"NA",
"NR",
"NP",
"NL",
"NC",
"NZ",
"NI",
"NE",
"NG",
"NU",
"NF",
"MP",
"NO",
"OM",
"PK",
"PW",
"PS",
"PA",
"PG",
"PY",
"PE",
"PH",
"PN",
"PL",
"PT",
"PR",
"QA",
"RE",
"RO",
"RU",
"RW",
"BL",
"SH",
"KN",
"LC",
"MF",
"PM",
"VC",
"WS",
"SM",
"ST",
"SA",
"SN",
"RS",
"SC",
"SL",
"SG",
"SX",
"SK",
"SI",
"SB",
"SO",
"ZA",
"GS",
"SS",
"ES",
"LK",
"SD",
"SR",
"SJ",
"SZ",
"SE",
"CH",
"SY",
"TW",
"TJ",
"TZ",
"TH",
"TL",
"TG",
"TK",
"TO",
"TT",
"TN",
"TR",
"TM",
"TC",
"TV",
"UG",
"UA",
"AE",
"GB",
"US",
"UM",
"UY",
"UZ",
"VU",
"VE",
"VN",
"VG",
"VI",
"WF",
"EH",
"YE",
"ZM",
"ZW"
],
"x-oapi-codegen-extra-tags": {
"validate": "country,required"
},
"x-order": 11,
"examples": [
"US"
]
},
"address-reference-partial": {
"type": "object",
"title": "Partial Address Reference",
"required": [
".tag",
"postal_code"
],
"properties": {
".tag": {
"type": "string",
"enum": [
"partial"
],
"description": "The type of address reference",
"x-order": 0,
"examples": [
"partial"
]
},
"postal_code": {
"type": "string",
"description": "The postal code associated with the credit card billing address.",
"x-order": 1,
"examples": [
"94105"
]
}
}
},
"credit-card": {
"required": [
"network",
"bin",
"last4",
"expiration",
"token"
],
"type": "object",
"properties": {
"network": {
"$ref": "#/components/schemas/credit-card-network"
},
"bin": {
"type": "string",
"description": "The Bank Identification Number (BIN). This is the first 4 to 8 digits of the account number.",
"pattern": "^\\d+$",
"examples": [
"411111"
]
},
"last4": {
"type": "string",
"description": "The account number's last four digits.",
"pattern": "^\\d{4}$",
"examples": [
"1004"
]
},
"expiration": {
"type": "string",
"description": "The expiration date, in YYYY-MM format.",
"pattern": "^\\d{4}-\\d{2}$",
"examples": [
"2029-03"
]
},
"token": {
"type": "string",
"description": "The Bolt token associated with the credit card.",
"writeOnly": true,
"examples": [
"a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0"
]
},
"affirm_vcn_token": {
"type": "string",
"description": "The checkout token associated with Affirm VCN credit cards.",
"examples": [
"a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0"
]
},
"default": {
"type": "boolean",
"description": "Indicates whether this credit card is the default payment method.",
"examples": [
true
]
}
}
},
"credit-card-network": {
"type": "string",
"description": "The credit card's network.",
"enum": [
"visa",
"mastercard",
"amex",
"discover",
"jcb",
"dinersclub",
"unionpay",
"alliancedata",
"citiplcc"
],
"x-oapi-codegen-extra-tags": {
"validate": "required"
},
"examples": [
"visa"
]
},
"payment-method-googlepay": {
"title": "Googlepay Payment Method",
"allOf": [
{
"type": "object",
"required": [
".tag",
"type"
],
"properties": {
".tag": {
"type": "string",
"enum": [
"googlepay"
],
"x-order": 0,
"examples": [
"googlepay"
]
},
"id": {
"type": "string",
"format": "id",
"readOnly": true,
"x-order": 1,
"examples": [
"X5h6j8uLpVGK"
]
},
"type": {
"type": "string",
"description": "The type of payment method",
"x-order": 2,
"examples": [
"googlepay"
]
},
"billing_address": {
"$ref": "#/components/schemas/address-reference"
}
}
},
{
"$ref": "#/components/schemas/credit-card"
}
]
},
"payment-method-applepay": {
"title": "ApplePay Payment Method",
"allOf": [
{
"type": "object",
"required": [
".tag",
"type"
],
"properties": {
".tag": {
"type": "string",
"enum": [
"applepay"
],
"x-order": 0,
"examples": [
"applepay"
]
},
"id": {
"type": "string",
"format": "id",
"readOnly": true,
"x-order": 1,
"examples": [
"X5h6j8uLpVGK"
]
},
"type": {
"type": "string",
"description": "The type of payment method",
"x-order": 2,
"examples": [
"applepay"
]
},
"billing_address": {
"$ref": "#/components/schemas/address-reference"
}
}
},
{
"$ref": "#/components/schemas/credit-card"
},
{
"type": "object",
"properties": {
"bolt_reference": {
"type": "string",
"description": "Bolt generated Applepay token id needed for token life cycle management.",
"examples": [
"a6f57b8c-3b12-4baf-9e77-0b9b2e3cb3d7"
]
}
}
}
]
},
"payment-method-paypal": {
"type": "object",
"title": "PayPal Payment Method",
"required": [
".tag",
"success_url",
"cancel_url"
],
"properties": {
".tag": {
"type": "string",
"enum": [
"paypal"
],
"x-order": 0,
"examples": [
"paypal"
]
},
"success_url": {
"type": "string",
"description": "Redirect URL for successful PayPal transaction.",
"format": "url",
"writeOnly": true,
"examples": [
"https://www.example.com/paypal-callback/success"
]
},
"cancel_url": {
"type": "string",
"description": "Redirect URL for canceled PayPal transaction.",
"format": "url",
"writeOnly": true,
"examples": [
"https://www.example.com/paypal-callback/cancel"
]
}
}
},
"payment-method-affirm": {
"type": "object",
"required": [
".tag",
"return_url"
],
"title": "Affirm Payment Method",
"properties": {
".tag": {
"type": "string",
"enum": [
"affirm"
],
"examples": [
"affirm"
]
},
"return_url": {
"type": "string",
"description": "Return URL to return to after payment completion in Affirm.",
"format": "url",
"writeOnly": true,
"examples": [
"https://www.example.com/handle_affirm_success"
]
}
}
},
"payment-method-afterpay": {
"type": "object",
"required": [
".tag",
"return_url"
],
"title": "Afterpay Payment Method",
"properties": {
".tag": {
"type": "string",
"enum": [
"afterpay"
],
"examples": [
"afterpay"
]
},
"return_url": {
"type": "string",
"description": "Return URL to return to after payment completion in Afterpay.",
"format": "url",
"writeOnly": true,
"examples": [
"https://www.example.com/handle_afterpay_success"
]
}
}
},
"payment-method-klarna": {
"type": "object",
"required": [
".tag",
"return_url"
],
"title": "Klarna Payment Method",
"properties": {
".tag": {
"type": "string",
"enum": [
"klarna"
],
"examples": [
"klarna"
]
},
"return_url": {
"type": "string",
"description": "Return URL to return to after payment completion in Klarna.",
"format": "url",
"writeOnly": true,
"examples": [
"https://www.example.com/handle_klarna_success"
]
}
}
},
"payment-method-klarna-account": {
"type": "object",
"required": [
".tag",
"return_url"
],
"title": "Klarna Account Payment Method",
"properties": {
".tag": {
"type": "string",
"enum": [
"klarna_account"
],
"examples": [
"klarna_account"
]
},
"return_url": {
"type": "string",
"description": "Return URL to return to after payment completion in Klarna.",
"format": "url",
"writeOnly": true,
"examples": [
"https://www.example.com/handle_klarna_account_success"
]
}
}
},
"payment-method-klarna-paynow": {
"type": "object",
"required": [
".tag",
"return_url"
],
"title": "Klarna Pay Now Payment Method",
"properties": {
".tag": {
"type": "string",
"enum": [
"klarna_paynow"
],
"examples": [
"klarna_paynow"
]
},
"return_url": {
"type": "string",
"description": "Return URL to return to after payment completion in Klarna.",
"format": "url",
"writeOnly": true,
"examples": [
"https://www.example.com/handle_klarna_paynow_success"
]
}
}
},
"error": {
"type": "object",
"required": [
".tag",
"message"
],
"properties": {
".tag": {
"type": "string",
"enum": [
"unauthorized",
"forbidden",
"unprocessable_request",
"not_found"
],
"description": "The type of error returned",
"examples": [
"unprocessable_request"
]
},
"message": {
"type": "string",
"description": "A human-readable error message, which might include information specific to the request that was made.",
"examples": [
"We were unable to process your request."
]
}
}
},
"field-error": {
"type": "object",
"description": "An error that pertains to validation of a specific field in the request.",
"required": [
".tag",
"message",
"field"
],
"properties": {
".tag": {
"type": "string",
"enum": [
"invalid_input_parameter"
],
"description": "The type of error returned",
"examples": [
"invalid_input_parameter"
]
},
"message": {
"type": "string",
"description": "A human-readable error message, which might include information specific to the request that was made.",
"examples": [
"We were unable to process your request."
]
},
"field": {
"type": "string",
"description": "The field (in its hierarchical form) that is failing validation.",
"examples": [
"address.phone"
]
}
}
},
"credit-card-error": {
"type": "object",
"required": [
".tag",
"message"
],
"properties": {
".tag": {
"type": "string",
"enum": [
"declined",
"declined_invalid_amount",
"declined_invalid_cvv",
"declined_invalid_merchant",
"declined_invalid_number",
"declined_expired",
"declined_call_issuer",
"declined_unsupported"
],
"description": "The type of error returned",
"examples": [
"declined_invalid_cvv"
]
},
"message": {
"type": "string",
"description": "A human-readable error message, which might include information specific to the request that was made.",
"examples": [
"The payment was declined because the CVV is not valid"
]
}
}
}
},
"examples": {
"credit-card-with-address-id": {
"summary": "Add a credit card, providing a billing address ID corresponding to an existing address on the shopper's account",
"value": {
".tag": "credit_card",
"type": "credit",
"network": "visa",
"bin": "411111",
"last4": "1004",
"expiration": "2025-03",
"token": "a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0",
"billing_address": {
".tag": "id",
"id": "D4g3h5tBuVYK9"
}
}
},
"credit-card-with-address-explicit": {
"summary": "Add a credit card, providing an explicit billing address",
"value": {
".tag": "credit_card",
"type": "credit",
"network": "visa",
"bin": "411111",
"last4": "1004",
"expiration": "2025-03",
"token": "a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0",
"billing_address": {
".tag": "explicit",
"first_name": "Charlie",
"last_name": "Dunn",
"street_address1": "535 Mission St",
"locality": "San Francisco",
"postal_code": "94105",
"region": "CA",
"country_code": "US"
}
}
}
},
"responses": {
"response-payment-method-error": {
"description": "The payment method is invalid and cannot be added, or some other error has occurred",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/error"
},
{
"$ref": "#/components/schemas/field-error"
},
{
"$ref": "#/components/schemas/credit-card-error"
}
]
},
"examples": {
"missing-input": {
"summary": "A required field is missing",
"value": {
".tag": "invalid_input_parameter",
"message": "token is required",
"field": "token"
}
},
"invalid-input": {
"summary": "A field has a malformed value that does not conform to the schema",
"value": {
".tag": "invalid_input_parameter",
"message": "last4 value 104 is invalid",
"field": "last4"
}
},
"invalid-credit-card": {
"summary": "The credit card payment method could not be added because it was declined",
"value": {
".tag": "declined_invalid_cvv",
"message": "The payment was declined because the CVV is not valid"
}
}
}
}
}
},
"response-default": {
"description": "An error has occurred, and no further details are provided (e.g. 5xx errors)"
}
},
"securitySchemes": {
"api-key": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key"
},
"oauth": {
"flows": {
"authorizationCode": {
"authorizationUrl": "/v1/oauth/authorize",
"refreshUrl": "/v1/oauth/token",
"tokenUrl": "/v1/oauth/token",
"scopes": {
"bolt.account.manage": "This scope grants permissions to perform read/edit/delete actions on Bolt Account data",
"bolt.account.view": "This scope grants permissions to perform read only actions on Bolt Account data",
"openid": "This scope grants permissions that enable Bolt Single Sign-On (SSO) by granting a JSON Web Token (JWT) that stores account data."
}
}
},
"type": "oauth2"
}
}
}
}
```