> ## Documentation Index
> Fetch the complete documentation index at: https://juo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a payment method

> Used to create a payment method.

This endpoint does not accept payment details. It initiates a flow that the customer completes themselves: they receive an email containing a secure link where they enter their payment information.

The payment method is therefore not usable for billing when the response returns — treat the `201` as confirmation that the flow has started, not that the payment method is ready. In a portal UI, prompt the customer to check their inbox rather than waiting on the response.


## OpenAPI

````yaml openapi-customer.json POST /payment-methods
openapi: 3.1.0
info:
  version: 8.15.0
  title: '@fastify/swagger'
servers:
  - url: https://api.juo.io/customer/v1
security:
  - DelegatedToken: []
  - AccessToken: []
paths:
  /payment-methods:
    post:
      tags:
        - api.customer.v1
      description: >-
        Requests a new payment method for the authenticated customer. Triggers
        the Shopify payment method update email so the customer can securely
        enter their payment details.
      parameters:
        - $ref: '#/components/parameters/TenantHeader'
      responses:
        '201':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerPaymentMethod'
components:
  parameters:
    TenantHeader:
      name: X-Tenant-ID
      x-speakeasy-name-override: tenant
      x-speakeasy-globals-hidden: true
      in: header
      schema:
        type: string
      required: true
      description: >-
        Unique identifier of the tenant in the system (usually a store
        identifier)
  schemas:
    CustomerPaymentMethod:
      type: object
      properties:
        id:
          format: uuid
          type: string
        customer:
          description: >-
            Customer `id` when not expanded, or the full `Customer` object when
            the field name is included in the `expand` query parameter.
          anyOf:
            - minLength: 1
              description: Customer ID (numeric string).
              examples:
                - '7654321'
              type: string
            - $ref: '#/components/schemas/Customer'
        instrument:
          anyOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - credit-card
                brand:
                  minLength: 1
                  description: Credit card network name.
                  type: string
                maskedNumber:
                  minLength: 1
                  description: Masked card number.
                  type: string
                lastDigits:
                  minLength: 1
                  description: Last digits of the card number.
                  type: string
                expiryMonth:
                  minimum: 1
                  maximum: 12
                  type: integer
                expiryYear:
                  type: integer
                cardholderName:
                  minLength: 1
                  type: string
              required:
                - type
                - brand
                - maskedNumber
                - lastDigits
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - paypal
                paypalAccountEmail:
                  format: email
                  description: Email of the associated PayPal account.
                  type:
                    - 'null'
                    - string
              required:
                - type
                - paypalAccountEmail
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - shop-pay
                maskedNumber:
                  minLength: 1
                  description: Masked card number.
                  type: string
                expiryMonth:
                  minimum: 1
                  maximum: 12
                  type: integer
                expiryYear:
                  type: integer
                cardholderName:
                  minLength: 1
                  type: string
              required:
                - type
                - maskedNumber
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - sepa-direct-debit
                consumerName:
                  minLength: 1
                  description: Full name of the account holder.
                  type: string
                consumerBic:
                  minLength: 1
                  description: BIC code.
                  type:
                    - 'null'
                    - string
                maskedConsumerAccount:
                  minLength: 1
                  description: Masked IBAN.
                  type: string
              required:
                - type
                - consumerName
                - consumerBic
                - maskedConsumerAccount
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - blik
              required:
                - type
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - mbway
                phone:
                  minLength: 1
                  type: string
              required:
                - type
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - bacs
                maskedNumber:
                  minLength: 1
                  description: Masked number.
                  type: string
              required:
                - type
                - maskedNumber
        billingAddress:
          oneOf:
            - type: 'null'
            - type: object
              properties:
                firstName:
                  minLength: 1
                  description: Customer's first name.
                  type:
                    - 'null'
                    - string
                lastName:
                  minLength: 1
                  description: Customer's last name.
                  type:
                    - 'null'
                    - string
                address1:
                  minLength: 1
                  description: Primary street address.
                  type:
                    - 'null'
                    - string
                address2:
                  minLength: 1
                  description: Additional address information (apartment, suite, etc.)
                  type:
                    - 'null'
                    - string
                zip:
                  minLength: 1
                  description: Postal/ZIP code.
                  type:
                    - 'null'
                    - string
                city:
                  minLength: 1
                  description: City name.
                  type:
                    - 'null'
                    - string
                country:
                  minLength: 1
                  description: Full country name.
                  type:
                    - 'null'
                    - string
                countryCode:
                  minLength: 2
                  maxLength: 2
                  description: Two-letter country code (ISO 3166-1).
                  type:
                    - 'null'
                    - string
                provinceCode:
                  minLength: 1
                  description: Province/state code.
                  type:
                    - 'null'
                    - string
                province:
                  minLength: 1
                  description: Full province/state name.
                  type:
                    - 'null'
                    - string
                phone:
                  minLength: 1
                  description: Contact phone number.
                  type:
                    - 'null'
                    - string
                company:
                  minLength: 1
                  description: Company name.
                  type:
                    - 'null'
                    - string
              required:
                - firstName
                - lastName
                - address1
                - address2
                - zip
                - city
                - country
                - countryCode
                - provinceCode
                - province
                - phone
                - company
      required:
        - id
        - customer
      title: CustomerPaymentMethod
    Customer:
      type: object
      properties:
        id:
          minLength: 1
          description: Customer ID (numeric string).
          type: string
          example: '7654321'
        resource:
          type: string
          enum:
            - customer
        displayName:
          minLength: 1
          description: Customer's full name.
          type: string
          example: Jane Smith
        email:
          format: email
          description: Customer's contact email.
          type:
            - 'null'
            - string
          example: jane.smith@example.com
        phone:
          minLength: 1
          description: Customer's contact phone number in E.164 format.
          type:
            - 'null'
            - string
          example: '+15550100'
      required:
        - id
        - resource
        - displayName
        - email
        - phone
      title: Customer
  securitySchemes:
    DelegatedToken:
      type: apiKey
      name: X-Delegated-Token
      in: header
    AccessToken:
      type: http
      scheme: bearer

````