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

# Create a commerce user payment method

> [!NOTE]
>
> Only for the Commerce API.

Apps using the Commerce API can embed Goody's credit card form into their application to allow the app's end users to enter their credit card to save a payment method. Users can then use that payment method to pay for orders.

Call this endpoint to create a payment method associated with a commerce user; provide the user ID as `commerce_end_user_id`. Then, use the returned payment method `id` as the `payment_method_id` in the [Create an Order Batch](https://developer.ongoody.com/api-reference/order-batches/create-an-order-batch.md) endpoint along with the `commerce_end_user_id`.

For more information, refer to [Embedded Payment Form](https://developer.ongoody.com/commerce-api/embedded-payment-form.md).


## OpenAPI

````yaml POST /v1/commerce_user_payment_methods
openapi: 3.0.1
info:
  title: Goody API
  version: 1.0.0
  contact:
    name: Goody Support
    email: support@ongoody.com
servers:
  - url: https://api.ongoody.com
    description: Production
  - url: https://api.sandbox.ongoody.com
    description: Sandbox
security: []
paths:
  /v1/commerce_user_payment_methods:
    post:
      tags:
        - Commerce User Payment Methods
      summary: Create a commerce user payment method
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommerceUserPaymentMethodInput'
            examples:
              Commerce user payment method created:
                summary: Commerce user payment method created
                value:
                  cardholder_name: John Doe
                  commerce_end_user_id: test_user_pm_2331d26e
                  payment_method_type: card
                  interim_card_key: X9edbacqt1CBCRRKRLkuiINj
                  billing_address:
                    address_1: 123 Main St
                    address_2: Apt 4B
                    city: New York
                    state: NY
                    postal_code: '10001'
                    country: US
      responses:
        '201':
          description: Commerce user payment method created
          content:
            application/json:
              examples:
                Commerce user payment method created:
                  value:
                    id: 7e77b629-5ea9-4bd5-8191-a67a402ccd26
                    card_brand: mastercard
                    card_last_4: '4444'
                    card_exp_month: 12
                    card_exp_year: 2034
                    cardholder_name: John Doe
                    created_at: '2026-06-03T12:24:05Z'
              schema:
                $ref: '#/components/schemas/CommerceUserPaymentMethod'
        '400':
          description: Bad request
          content:
            application/json:
              examples:
                Card declined:
                  value:
                    error: Your card was declined.
                Card missing field:
                  value:
                    error: Cardholder name is required
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearer: []
components:
  schemas:
    CommerceUserPaymentMethodInput:
      type: object
      properties:
        cardholder_name:
          type: string
          description: The name on the card.
        commerce_end_user_id:
          type: string
          description: >-
            The user ID of the user in *your* app to associate this payment
            method with.
        payment_method_type:
          type: string
          description: >-
            The type of payment method to create. Currently, only `card` is
            supported.
        interim_card_key:
          type: string
          description: The key for the interim card to use for the payment method.
        billing_address:
          type: object
          properties:
            address_1:
              type: string
            address_2:
              type: string
              nullable: true
            city:
              type: string
            state:
              type: string
            postal_code:
              type: string
            country:
              type: string
              description: The two-letter country code, e.g. `US`.
          required:
            - address_1
            - city
            - state
            - postal_code
            - country
      required:
        - cardholder_name
        - commerce_end_user_id
        - payment_method_type
        - interim_card_key
        - billing_address
    CommerceUserPaymentMethod:
      type: object
      properties:
        id:
          type: string
        card_brand:
          type: string
          nullable: true
          description: Brand of the card, e.g. 'Visa' or 'Mastercard'.
        card_last_4:
          type: string
          nullable: true
          description: Last 4 digits of the card number.
        card_exp_month:
          type: integer
          nullable: true
        card_exp_year:
          type: integer
          nullable: true
        cardholder_name:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
          description: Date and time the payment method was created, ISO 8601 format.
      required:
        - id
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: Your Goody API key.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.