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

# Generate Card Collection URL

> Generate a URL for customers to add their payment method details



## OpenAPI

````yaml GET /api/v1/checkout/generate-card-collection-url
openapi: 3.0.1
info:
  title: Metrifox API Documentation
  version: v1
  description: >-
    Welcome to Metrifox Platform's API documentation. This comprehensive API
    suite enables seamless integration with our platform, providing secure and
    efficient access to our services.
servers:
  - url: https://{defaultHost}
    variables:
      defaultHost:
        default: api.metrifox.com
security:
  - api_key: []
paths:
  /api/v1/checkout/generate-card-collection-url:
    get:
      tags:
        - Checkout
      summary: Generate card collection URL
      description: >
        Generates a secure URL for customers to add or update their payment
        method details.

        This is useful when a customer starts a trial without providing payment
        details, or when

        you need to collect card information separately from the checkout flow.


        A subscription ID or order ID is required because the currency on the
        order determines which payment gateway

        is used to collect payment details.


        **Use Cases:**

        - Trial-to-paid conversions where card was not collected upfront

        - In-app "Add Billing" prompts (e.g., "Your trial ends in 7 days — Add
        Billing to Continue")

        - Re-collecting payment details after a card expires or is removed
      operationId: generateCardCollectionUrl
      parameters:
        - name: subscription_id
          in: query
          required: false
          description: >-
            The subscription ID to collect card details for. Either
            subscription_id or order_id is required.
          schema:
            type: string
            format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        - name: order_id
          in: query
          required: false
          description: >-
            The order ID to collect card details for. Either subscription_id or
            order_id is required.
          schema:
            type: string
            format: uuid
          example: f9e8d7c6-b5a4-3210-fedc-ba0987654321
      responses:
        '200':
          description: Card collection URL generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: ''
                  data:
                    type: object
                    properties:
                      checkout_url:
                        type: string
                        format: uri
                        description: The generated card collection URL
                        example: >-
                          https://app.metrifox.com/your-organization/checkout/premium_plan?order=a1b2c3d4&customer=cust_123&collect_card=true
              examples:
                card_collection_url_response:
                  summary: Successful Card Collection URL Generation
                  value:
                    statusCode: 200
                    message: ''
                    data:
                      checkout_url: >-
                        https://app.metrifox.com/your-organization/checkout/premium_plan?order=a1b2c3d4&customer=cust_123&collect_card=true
        '400':
          description: Bad request - Missing required parameters or checkout not configured
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: Either subscription_id or order_id is required
                  data:
                    type: object
                    example: {}
                  meta:
                    type: object
                    example: {}
                  errors:
                    type: object
                    example: {}
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: Unauthorized
                  data:
                    type: object
                    example: {}
                  meta:
                    type: object
                    example: {}
                  errors:
                    type: object
                    example: {}
        '404':
          description: Not found - Subscription or order not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 404
                  message:
                    type: string
                    example: Subscription not found
                  data:
                    type: object
                    example: {}
                  meta:
                    type: object
                    example: {}
                  errors:
                    type: object
                    example: {}
      x-codeSamples:
        - lang: curl
          label: cURL
          source: >
            # Using subscription ID

            curl -X GET
            "https://api.metrifox.com/api/v1/checkout/generate-card-collection-url?subscription_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890"
            \
              -H "x-api-key: your-api-key"

            # Using order ID

            curl -X GET
            "https://api.metrifox.com/api/v1/checkout/generate-card-collection-url?order_id=f9e8d7c6-b5a4-3210-fedc-ba0987654321"
            \
              -H "x-api-key: your-api-key"
        - lang: python
          label: Python SDK
          source: |
            from metrifox_sdk import MetrifoxClient

            client = MetrifoxClient(api_key="your_api_key")

            # Card collection URL for a subscription
            url = client.checkout.card_collection_url(
                subscription_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
            )

            # Or for an order
            url = client.checkout.card_collection_url(
                order_id="f9e8d7c6-b5a4-3210-fedc-ba0987654321"
            )
        - lang: javascript
          label: Javascript SDK
          source: >
            import { init } from "metrifox-js";


            const metrifoxClient = init({
              apiKey: process.env.METRIFOX_API_KEY
            });


            // Card collection URL for a subscription

            const url = await metrifoxClient.checkout.cardCollectionUrl({
              subscriptionId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            });


            // Or for an order

            const urlForOrder = await
            metrifoxClient.checkout.cardCollectionUrl({
              orderId: "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
            });
        - lang: ruby
          label: Ruby SDK
          source: |
            require 'metrifox-sdk'

            METRIFOX_SDK = MetrifoxSDK.init({ api_key: "your-api-key" })

            # Card collection URL for a subscription
            url = METRIFOX_SDK.checkout.card_collection_url(
              subscription_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
            )

            # Or for an order
            url = METRIFOX_SDK.checkout.card_collection_url(
              order_id: "f9e8d7c6-b5a4-3210-fedc-ba0987654321"
            )
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

````