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

# Initiate a collection

> Create a card collection request for a business wallet. Card collections require a verified customer and card details, and may not be enabled for every business. Customer attachment after creation is not supported for API card collections. Required scope: `collection:create`.



## OpenAPI

````yaml /api-reference/collection/create-openapi.json post /api/external/collection
openapi: 3.1.0
info:
  title: Blaaiz Platform API - Initiate Collection
  version: 1.0.0
  description: >-
    Create a card collection request for a business wallet. Card collections
    require a verified customer and card details, and may not be enabled for
    every business.
servers:
  - url: https://api-prod.blaaiz.com
  - url: https://api-dev.blaaiz.com
security: []
tags:
  - name: Collection
paths:
  /api/external/collection:
    post:
      tags:
        - Collection
      summary: Initiate a collection
      description: >-
        Create a card collection request for a business wallet. Card collections
        require a verified customer and card details, and may not be enabled for
        every business. Customer attachment after creation is not supported for
        API card collections. Required scope: `collection:create`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateCollectionRequest'
            example:
              method: card
              amount: 50000
              wallet_id: wallet_123
              customer_id: customer_123
              card_holder_name: John Doe
              card_number: '4242424242424242'
              expiry: 12/30
              cvc: '123'
              phone: '+2348012345678'
              redirect_url: https://merchant.example.com/payment/callback
      responses:
        '200':
          description: Collection initiated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiateCollectionResponse'
              example:
                message: Collection initiated successfully.
                transaction_id: txn_987654322
                url: https://checkout.example.com/card-auth/xyz789
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    status: false
                    message: Invalid request parameters
                method_not_supported_for_wallet_currency:
                  value:
                    status: false
                    message: Funding NGN using card is not supported yet.
                customer_not_verified_for_card:
                  value:
                    status: false
                    message: >-
                      Customer is not verified. Ensure you have uploaded
                      identify docs for customer.
                card_not_enabled_for_business:
                  value:
                    status: false
                    message: Card collection is not enabled for this business yet.
                attach_customer_not_supported:
                  value:
                    status: false
                    message: Customer cannot be updated for API card collections.
                invalid_redirect_url:
                  value:
                    message: The redirect url field must be a valid URL.
                    errors:
                      redirect_url:
                        - The redirect url field must be a valid URL.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: false
                message: Invalid or missing access token
      security:
        - oauth2ClientCredentials:
            - collection:create
components:
  schemas:
    InitiateCollectionRequest:
      type: object
      properties:
        method:
          type: string
          enum:
            - card
          description: Collection method. Use `card`.
        amount:
          type: number
          description: Amount to collect. Minimum value is `0.1`.
        wallet_id:
          type: string
          description: ID of the business wallet to credit.
        customer_id:
          type: string
          description: >-
            Business customer ID. Required for `card` collections. The customer
            must belong to the business and be VERIFIED.
        phone:
          type: string
          description: Optional customer phone number.
        card_holder_name:
          type: string
          description: Full card holder name. Required for `card` collections.
        card_number:
          type: string
          description: 16-digit card number. Required for `card` collections.
        expiry:
          type: string
          description: Card expiry in `MM/YY` format. Required for `card` collections.
        cvc:
          type: string
          description: 3-digit card CVC. Required for `card` collections.
        redirect_url:
          type: string
          format: uri
          description: >-
            Optional HTTPS URL to redirect the customer to after payment
            authorization (e.g. 3DS). Blaaiz appends `transaction_id` and
            `status` query parameters to this URL before redirecting. Maximum
            2048 characters.
          maxLength: 2048
      required:
        - method
        - amount
        - wallet_id
    InitiateCollectionResponse:
      type: object
      properties:
        message:
          type: string
        transaction_id:
          type: string
        url:
          type:
            - string
            - 'null'
          format: uri
          description: Checkout or redirect URL returned for the card collection flow.
      required:
        - message
        - transaction_id
        - url
    Error:
      type: object
      properties:
        status:
          type: boolean
        message:
          type: string
      required:
        - message
  securitySchemes:
    oauth2ClientCredentials:
      type: oauth2
      description: >-
        Use your OAuth client credentials to obtain a short-lived Bearer token
        from POST /oauth/token.
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes:
            collection:create: Initiate collections.

````