> ## Documentation Index > Fetch the complete documentation index at: https://docs.guile.app/llms.txt > Use this file to discover all available pages before exploring further. # Add a payment method > Add a new payment method to the current customer's profile. Payment methods must be tokenized through the payment processor before being added. The payment method token should be obtained from the payment processor's client-side SDK (e.g., Stripe.js) to ensure sensitive payment information is never sent directly to the API. ## OpenAPI ````yaml /api-reference/Customers/openapi.yaml post /me/paymentMethods openapi: 3.0.0 info: title: Customers version: 0.1.0 contact: name: Guile Engineering url: https://www.guile.app email: engineering@guile.app license: name: MIT url: https://opensource.org/license/mit description: The Customer API provides operations for customers on the Guile platform. servers: - url: https://api.guile.app variables: {} - url: https://guile.fly.dev variables: {} security: [] tags: - name: Customers description: Customer profile, cards on file, and bookings paths: /me/paymentMethods: post: tags: - Customers summary: Add a payment method description: >- Add a new payment method to the current customer's profile. Payment methods must be tokenized through the payment processor before being added. The payment method token should be obtained from the payment processor's client-side SDK (e.g., Stripe.js) to ensure sensitive payment information is never sent directly to the API. operationId: addPaymentMethod parameters: - $ref: '#/components/parameters/idempotencyKeyRequest' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/addPaymentMethodRequest' responses: '201': description: Created. content: application/json: schema: $ref: '#/components/schemas/paymentMethod' '400': description: >- Bad Request. The request body, request headers, and/or query parameters are not well-formed. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/badRequest](https://docs.guile.app/problems/badRequest) content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' '401': description: >- Unauthorized. The operation requires authentication but no authentication or insufficient authentication was given. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/unauthorized](https://docs.guile.app/problems/unauthorized) content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' '403': description: >- Forbidden. The authenticated caller is not authorized to perform the requested operation. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/forbidden](https://docs.guile.app/problems/forbidden) content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' '409': description: >- Conflict. The request conflicts with the state of the application. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/conflict](https://docs.guile.app/problems/conflict) * [https://docs.guile.app/problems/idempotencyKeyConflict](https://docs.guile.app/problems/idempotencyKeyConflict) * [https://docs.guile.app/problems/idempotencyRequestInProgress](https://docs.guile.app/problems/idempotencyRequestInProgress) * [https://docs.guile.app/problems/paymentMethodLimitReached](https://docs.guile.app/problems/paymentMethodLimitReached) content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' '422': description: >- Unprocessable Entity. The request body and/or query parameters were well-formed but otherwise invalid. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/unprocessableEntity](https://docs.guile.app/problems/unprocessableEntity) * [https://docs.guile.app/problems/digitalWalletCardNotAllowed](https://docs.guile.app/problems/digitalWalletCardNotAllowed) content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' '429': description: >- Too Many Requests. The client has sent too many requests in a given amount of time. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/tooManyRequests](https://docs.guile.app/problems/tooManyRequests) headers: Retry-After: required: true description: The number of seconds to wait before retrying the request. schema: type: integer format: uint32 content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' '500': description: >- Internal Server Error. The server encountered an unexpected condition that prevented it from fulfilling the request. This problem response may have one of the following `type` values: * [https://docs.guile.app/problems/internalServerError](https://docs.guile.app/problems/internalServerError) content: application/problem+json: schema: $ref: '#/components/schemas/apiProblem' security: - BearerAuth: [] components: parameters: idempotencyKeyRequest: name: Idempotency-Key in: header required: true description: >- A client-generated idempotency key to ensure operations are only processed once even if a client retries the operation. The V4 UUID format, as defined in [RFC 4122](https://tools.ietf.org/html/rfc4122), is recommended to avoid collisions but is not required. schema: type: string maxLength: 255 schemas: addPaymentMethodRequest: type: object required: - paymentMethodToken - isDefault properties: paymentMethodToken: type: string minLength: 1 maxLength: 500 description: >- The payment method token obtained from the payment processor's client-side SDK. For card payments, this should be a tokenized representation of the card (e.g., a Stripe payment method token). Specific cards for digital wallets (like Apple Pay or Google Pay) cannot be added and should instead be processed directly through the payment processor during checkout. This token is used to securely add the payment method without exposing sensitive payment information to the API. isDefault: type: boolean description: >- Whether to set this payment method as the default payment method for the customer. If set to true, this payment method will be used by default for future transactions. If the customer already has a default payment method, it will be replaced. default: false nickname: type: string maxLength: 50 description: An optional nickname for the payment method to help identify it. description: >- Request body for adding a payment method to a customer's profile. Payment methods must be tokenized through the payment processor's client-side SDK before being submitted to this API. Never send raw card details directly. paymentMethod: type: object required: - type - isDefault properties: type: allOf: - $ref: '#/components/schemas/paymentMethodType' description: Indicator of the payment method type. card: allOf: - $ref: '#/components/schemas/cardPaymentMethod' description: |- A representation of the customer's credit or debit card. This property is required when the payment method type is `card`. digitalWallet: allOf: - $ref: '#/components/schemas/digitalWallet' description: >- A representation of the customer's digital wallet, such as Apple Pay. This property is required when the payment method type is `digitalWallet`. isDefault: type: boolean description: >- Indicates if this card is the default card in a customer's saved payment methods. default: false nickname: type: string maxLength: 50 description: An optional nickname for the payment method to help identify it. description: Representation of a payment method for a customer. apiProblem: type: object required: - type - title - occurredAt - id - status properties: type: allOf: - $ref: '#/components/schemas/uri' description: A URI reference that identifies the problem type. title: type: string maxLength: 120 description: >- A short, human-readable summary of the problem type. The title is usually the same for all problems with the same `type`. occurredAt: type: string format: date-time description: >- The date-time when this problem occurred, in [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived and immutable. detail: type: string maxLength: 256 description: >- A human-readable explanation specific to this occurrence of the problem. id: allOf: - $ref: '#/components/schemas/resourceId' description: >- The unique identifier for this problem. This is an immutable opaque string. status: allOf: - $ref: '#/components/schemas/statusCode' description: >- The [HTTP status code](https://datatracker.ietf.org/doc/html/rfc7231#section-6)for this occurrence of the problem. instance: allOf: - $ref: '#/components/schemas/uri' maxLength: 2048 description: >- A URI reference that identifies the specific occurrence of the problem. This is the URI of an API resource that the problem is related to, with a unique error correlation ID URI fragment. attributes: type: object additionalProperties: {} description: >- Additional optional attributes related to the problem. This data conforms to the schema associated with the error type. recovery: allOf: - $ref: '#/components/schemas/clientFailureRecovery' description: The recovery contract for this problem occurrence. problems: type: array items: $ref: '#/components/schemas/problem' maxItems: 128 description: |- Optional root-causes if there are multiple problems in the request or API call processing. description: >- API problem or error response, as per [RFC 9457 application/problem+json](https://tools.ietf.org/html/rfc9457). paymentMethodType: type: string enum: - card - digitalWallet description: The type of payment method. cardPaymentMethod: type: object required: - id - network - last4 - expirationMonth - expirationYear properties: id: allOf: - $ref: '#/components/schemas/resourceId' description: The unique identifier for this card. network: allOf: - $ref: '#/components/schemas/cardNetwork' description: The card network facilitating the money movement. last4: type: string description: The last 4 digits of the card number. expirationMonth: type: string minLength: 2 maxLength: 2 description: The 2 digit representation of the card's expiration month. expirationYear: type: string minLength: 2 maxLength: 2 description: The 2 digit representation of the card's expiration year. description: Representation of a customer's credit or debit card. digitalWallet: type: object required: - provider properties: provider: allOf: - $ref: '#/components/schemas/digitalWalletProvider' description: The name of the digital wallet provider. description: Representation of a customer's digital wallet. uri: type: string maxLength: 1024 format: uri description: A URI reference to an internal or external resource. resourceId: type: string description: >- The unique, opaque system identifier for a resource. This case-sensitive ID is also used as path parameters in URLs or in other properties or parameters that reference a resource by ID rather than URL. statusCode: type: integer format: uint16 minimum: 100 maximum: 599 description: The HTTP status code for a response. clientFailureRecovery: type: object required: - outcome - retry properties: outcome: allOf: - $ref: '#/components/schemas/clientFailureOutcome' description: The known outcome of the request. retry: allOf: - $ref: '#/components/schemas/clientRetryDirective' description: The safe retry action for the request. sessionAction: allOf: - $ref: '#/components/schemas/clientSessionAction' description: The session action required before the request can continue. rateLimit: allOf: - $ref: '#/components/schemas/rateLimit' description: The rate limit state that prevented the request. description: The recovery contract for a failed client request. problem: type: object required: - type - title - occurredAt - id - status properties: type: allOf: - $ref: '#/components/schemas/uri' description: A URI reference that identifies the problem type. title: type: string maxLength: 120 description: >- A short, human-readable summary of the problem type. The title is usually the same for all problems with the same `type`. occurredAt: type: string format: date-time description: >- The date-time when this problem occurred, in [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. This is derived and immutable. detail: type: string maxLength: 256 description: >- A human-readable explanation specific to this occurrence of the problem. id: allOf: - $ref: '#/components/schemas/resourceId' description: >- The unique identifier for this problem. This is an immutable opaque string. status: allOf: - $ref: '#/components/schemas/statusCode' description: >- The [HTTP status code](https://datatracker.ietf.org/doc/html/rfc7231#section-6)for this occurrence of the problem. instance: allOf: - $ref: '#/components/schemas/uri' maxLength: 2048 description: >- A URI reference that identifies the specific occurrence of the problem. This is the URI of an API resource that the problem is related to, with a unique error correlation ID URI fragment. attributes: type: object additionalProperties: {} description: >- Additional optional attributes related to the problem. This data conforms to the schema associated with the error type. description: >- Standard problem or error response, as per [RFC 9457 application/problem+json](https://tools.ietf.org/html/rfc9457). cardNetwork: type: string enum: - visa - discover - mastercard - amex - other description: The card payment processing network. digitalWalletProvider: type: string enum: - apple - google description: The provider of digital wallet. clientFailureOutcome: type: string enum: - notApplied - unknown description: The known outcome of a failed client request. clientRetryDirective: type: string enum: - doNotRetry - retrySameRequest - retrySameRequestAfterDelay description: The safe retry action for a failed client request. clientSessionAction: type: string enum: - refresh - signIn description: The session action required before a failed request can continue. rateLimit: type: object required: - limit - remaining - resetsAt properties: limit: type: integer format: uint64 description: The maximum number of requests allowed in the active window. remaining: type: integer format: uint64 description: The number of requests remaining in the active window. resetsAt: type: string format: date-time description: >- The date-time when the active window resets, in [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC. description: The rate limit state for the request. securitySchemes: BearerAuth: type: http scheme: Bearer ````