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

# Issue a card

> Issues a USD card and funds it in one call. Returns as soon as issuance is under way — the card starts in `creating` and becomes `active` once the provider has issued it.

<Warning>
  **A business client cannot currently issue a card through this API.** `customerId` is required for a business client, and that customer must be at **tier 2 or above** — but [every customer is created at tier 1 and no endpoint raises it](/services/customers/identity-and-verification#tiers). Every attempt therefore ends in `404 card_holder_not_found`. This is recorded as an open contract decision.
</Warning>

## What issuance does

Four things happen in one call: a hidden USD balance account is opened for the card, the card is created at the provider, your funding account is debited, and the card is funded. The `operation` in the response tracks all of it.

## Idempotency, and retrying a failure

`externalReference` is the key. Reusing it returns the existing card and operation — **except** when the previous issuance failed, in which case the same reference **re-drives** it rather than returning the failure.

<Note>This is the opposite of [transfers](/api-reference/transfers/create-a-transfer), where a failed attempt keeps its reference and resending returns the failure. Cards retry; transfers do not.</Note>

## Funding

`debitAccountId` and `amount` are required — there is no unfunded card. `amount` is in the card’s own currency, so USD minor units. The account must be one of your own; a customer wallet is refused with `403 card_client_account_required`.

When that account is not in the card’s currency, Sakawave quotes the FX itself at issuance and debits the equivalent — you do not pass a quote. [`POST /v1/card-fx-quotes`](/api-reference/cards/create-a-card-fx-quote) is still there if you want to show an indicative rate first, but issuance does not take one. Funding and withdrawal on an existing card do.

## Types

| `type` | Behaviour |
| - | - |
| `virtual` | Reusable. Supports spending controls. |
| `disposable` | Single use — moves to `used` after its first payment. Spending controls are rejected. |

## Error codes

| Status | `code` | Cause |
| - | - | - |
| `400` | `validation_failed` | A field failed validation, or spending controls were sent for a disposable card. |
| `400` | `card_holder_required` | A business client did not send a `customerId`. |
| `403` | `— (`reason: feature\_not\_available`)` | Your business is below tier 2, which card issuance requires. |
| `403` | `card_client_account_required` | The funding account is a customer wallet. |
| `404` | `card_holder_not_found` | The customer does not exist, is not an individual, is below tier 2, or is missing a name, email, or phone number. |
| `409` | `card_account_ineligible` | The funding account is missing, inactive, or cannot be debited. |
| `409` | `insufficient_funds` | The funding account cannot cover the amount. |
| `503` | `card_provider_unavailable` | The card provider could not be reached. |
| `503` | `invalid_card_fx_quote` | The FX provider returned an incomplete quote for the conversion. |
| `401` | `INVALID_API_KEY` | The key is missing, invalid, inactive, expired, from the other environment, or blocked by its IP allowlist. |
| `404` | `card_not_found` | No such card for this business. |
| `429` | `api_key_rate_limit_exceeded` | The per-minute limit for this key was exceeded. |


## OpenAPI

````yaml /openapi.json post /v1/cards
openapi: 3.1.0
info:
  title: Sakawave Business API
  version: 1.0.0-draft
  summary: >-
    Accounts, transfers, FX quotes, and transaction reconciliation for Sakawave
    businesses.
  description: >-
    Generated from the public NestJS controllers and their Zod request schemas.
    Public URLs and policy statements remain draft until the Phase 1 contract
    checklist is approved.
  contact:
    name: Sakawave API Support
    email: api-support@sakawave.example
servers:
  - url: https://sandbox-api.sakawave.example
    description: Sandbox (default)
  - url: https://api.sakawave.example
    description: Live
security:
  - bearerAuth: []
tags:
  - name: Bill payments
    description: Browse the biller catalog, validate a customer, and pay a bill.
  - name: Cards
    description: Issue, fund, and control USD virtual and disposable cards.
  - name: eSIM
    description: >-
      Sell mobile data abroad: browse the catalog, buy an eSIM, and manage it
      once installed.
  - name: Currencies and countries
    description: >-
      Reference data: what may be held, what may be sent where, and which
      jurisdictions are served.
  - name: Customers
    description: Create and manage customers of your business.
  - name: Accounts
    description: >-
      Open business and customer accounts, and issue the destinations that fund
      them.
  - name: Transfer destinations
    description: Resolve temporary destinations and saved recipients.
  - name: FX quotes
    description: Create and retrieve time-limited cross-currency quotes.
  - name: Transfers
    description: Preview, create, and monitor transfers.
  - name: Transactions
    description: Read ledger entries for reconciliation.
paths:
  /v1/cards:
    post:
      tags:
        - Cards
      summary: Issue a card
      description: >-
        Issues a USD card and funds it in one call. Returns as soon as issuance
        is under way — the card starts in `creating` and becomes `active` once
        the provider has issued it.
      operationId: createCard
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCardRequest'
            example:
              customerId: 01K2Z3AB4C5D6E7F8G9HJKMNPQ
              type: virtual
              brand: mastercard
              currency: USD
              externalReference: card_issue_20260814_001
              label: Ada travel card
              debitAccountId: 01K2Z3AB4D5E6F7G8H9JKMNPQR
              amount: '5000'
              spendingControls:
                transactionAmountLimit: '2000'
                dailyAmountLimit: '5000'
                dailyTransactionCount: 10
      responses:
        '201':
          description: Successful response.
          headers:
            X-Request-ID:
              description: >-
                The request identifier assigned by Sakawave. Include it in
                support requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  card:
                    $ref: '#/components/schemas/CardResponse'
                  operation:
                    $ref: '#/components/schemas/CardOperationResponse'
                required:
                  - card
                  - operation
              example:
                card:
                  id: 01K2Z3AB4S5T6V7W8XYZABCDEF
                  label: Ada travel card
                  type: virtual
                  brand: mastercard
                  currency: USD
                  status: active
                  maskedPan: •••• •••• •••• 4242
                  expiryMonth: 8
                  expiryYear: 2028
                  holder:
                    type: customer
                    id: 01K2Z3AB4C5D6E7F8G9HJKMNPQ
                    name: Ada Okafor
                  balance: '5000'
                  balanceFormatted: '50.00'
                  spendingControls:
                    transactionAmountLimit: '2000'
                    dailyAmountLimit: '5000'
                    dailyTransactionCount: 10
                  operations:
                    - id: 01K2Z3AB4R5S6T7V8WXYZABCDE
                      cardId: 01K2Z3AB4S5T6V7W8XYZABCDEF
                      type: issuance
                      status: completed
                      sourceCurrency: NGN
                      destinationCurrency: USD
                      sourceAmount: '8000000'
                      destinationAmount: '5000'
                      failureCode: null
                      failureReason: null
                      completedAt: '2026-08-14T09:12:00.000Z'
                      createdAt: '2026-08-14T09:11:40.000Z'
                      updatedAt: '2026-08-14T09:12:00.000Z'
                  createdAt: '2026-08-14T09:11:40.000Z'
                  updatedAt: '2026-08-14T09:12:00.000Z'
                operation:
                  id: 01K2Z3AB4R5S6T7V8WXYZABCDE
                  cardId: 01K2Z3AB4S5T6V7W8XYZABCDEF
                  type: issuance
                  status: completed
                  sourceCurrency: NGN
                  destinationCurrency: USD
                  sourceAmount: '8000000'
                  destinationAmount: '5000'
                  failureCode: null
                  failureReason: null
                  completedAt: '2026-08-14T09:12:00.000Z'
                  createdAt: '2026-08-14T09:11:40.000Z'
                  updatedAt: '2026-08-14T09:12:00.000Z'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ProviderUnavailableError'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateCardRequest:
      type: object
      additionalProperties: false
      properties:
        customerId:
          $ref: '#/components/schemas/Ulid'
          description: >-
            Required for a business client. The customer must be an individual
            at tier 2 or above with a full name, email, and phone number.
        type:
          type: string
          enum:
            - virtual
            - disposable
        brand:
          type: string
          enum:
            - mastercard
        currency:
          type: string
          enum:
            - USD
        externalReference:
          type: string
          minLength: 1
          maxLength: 120
          description: Your idempotency key for the issuance operation.
        label:
          type: string
          minLength: 1
          maxLength: 80
        debitAccountId:
          $ref: '#/components/schemas/Ulid'
          description: One of your own accounts. A customer wallet is refused.
        amount:
          $ref: '#/components/schemas/PositiveMinorUnits'
        spendingControls:
          $ref: '#/components/schemas/CardSpendingControls'
      required:
        - type
        - brand
        - currency
        - externalReference
        - label
        - debitAccountId
        - amount
      description: >-
        A card is always issued funded. A disposable card cannot carry spending
        controls.
    CardResponse:
      type: object
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/Ulid'
        label:
          type: string
          maxLength: 80
          description: Your own name for the card.
        type:
          type: string
          enum:
            - virtual
            - disposable
        brand:
          type: string
          enum:
            - mastercard
        currency:
          type: string
          enum:
            - USD
          description: Cards are USD only.
        status:
          type: string
          enum:
            - creating
            - active
            - frozen
            - funding_failed
            - terminating
            - used
            - terminated
            - failed
            - fraud
        maskedPan:
          type: string
          description: >-
            The masked number. The full PAN is only available from the
            credentials endpoint.
        expiryMonth:
          type: integer
          minimum: 1
          maximum: 12
        expiryYear:
          type: integer
        holder:
          type: object
          additionalProperties: false
          properties:
            type:
              type: string
              enum:
                - customer
                - user
            id:
              anyOf:
                - $ref: '#/components/schemas/Ulid'
                - type: 'null'
            name:
              type: string
          required:
            - type
            - id
            - name
        balance:
          $ref: '#/components/schemas/MinorUnits'
        balanceFormatted:
          type: string
          description: The same figure rendered for display. Never use it in a calculation.
        spendingControls:
          anyOf:
            - $ref: '#/components/schemas/CardSpendingControls'
            - type: 'null'
        operations:
          type: array
          items:
            $ref: '#/components/schemas/CardOperationResponse'
          description: >-
            Issuance, funding, withdrawal, and termination operations for this
            card. Empty on a list response.
        createdAt:
          $ref: '#/components/schemas/IsoTimestamp'
        updatedAt:
          $ref: '#/components/schemas/IsoTimestamp'
      required:
        - id
        - label
        - type
        - brand
        - currency
        - status
        - maskedPan
        - expiryMonth
        - expiryYear
        - holder
        - balance
        - balanceFormatted
        - spendingControls
        - operations
        - createdAt
        - updatedAt
    CardOperationResponse:
      type: object
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/Ulid'
        cardId:
          $ref: '#/components/schemas/Ulid'
        type:
          type: string
          enum:
            - issuance
            - funding
            - withdrawal
            - termination
        status:
          type: string
          enum:
            - created
            - submitting
            - pending
            - completed
            - failed
        sourceCurrency:
          $ref: '#/components/schemas/AssetCode'
        destinationCurrency:
          $ref: '#/components/schemas/AssetCode'
        sourceAmount:
          $ref: '#/components/schemas/MinorUnits'
        destinationAmount:
          $ref: '#/components/schemas/MinorUnits'
        failureCode:
          anyOf:
            - type: string
            - type: 'null'
        failureReason:
          anyOf:
            - type: string
            - type: 'null'
        completedAt:
          anyOf:
            - $ref: '#/components/schemas/IsoTimestamp'
            - type: 'null'
        createdAt:
          $ref: '#/components/schemas/IsoTimestamp'
        updatedAt:
          $ref: '#/components/schemas/IsoTimestamp'
      required:
        - id
        - cardId
        - type
        - status
        - sourceCurrency
        - destinationCurrency
        - sourceAmount
        - destinationAmount
        - failureCode
        - failureReason
        - completedAt
        - createdAt
        - updatedAt
    Ulid:
      type: string
      minLength: 26
      maxLength: 26
      pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
      example: 01K2Z3AB4C5D6E7F8G9HJKMNPQ
      description: A 26-character ULID.
    PositiveMinorUnits:
      type: string
      pattern: ^[1-9]\d*$
      example: '2500000'
      description: A positive integer number of minor units.
    CardSpendingControls:
      type: object
      additionalProperties: false
      properties:
        transactionAmountLimit:
          $ref: '#/components/schemas/PositiveMinorUnits'
        dailyAmountLimit:
          $ref: '#/components/schemas/PositiveMinorUnits'
        dailyTransactionCount:
          type: integer
          minimum: 1
          maximum: 10000
      description: Per-card limits, in USD minor units. Not available on a disposable card.
    MinorUnits:
      type: string
      pattern: ^-?\d+$
      example: '2500000'
      description: >-
        An integer number of the asset’s smallest unit. Use this value for
        arithmetic.
    IsoTimestamp:
      type: string
      format: date-time
      example: '2026-08-14T09:00:00.000Z'
    AssetCode:
      type: string
      enum:
        - NGN
        - USD
        - GBP
        - EUR
        - GHS
        - ZAR
        - UGX
        - CAD
        - MXN
        - AED
        - BTC
        - ETH
        - USDT
        - USDC
    RequestError:
      anyOf:
        - $ref: '#/components/schemas/ValidationError'
        - $ref: '#/components/schemas/Error'
      description: >-
        Either a field-level validation failure carrying an errors array, or a
        rule the request broke, identified by code.
    Error:
      type: object
      additionalProperties: true
      properties:
        statusCode:
          type: integer
        message:
          type: string
          description: >-
            A sentence suitable for a log or a support conversation, not for a
            user interface.
        code:
          type: string
          description: >-
            The stable machine-readable reason. Branch on this, never on the
            message.
      required:
        - message
        - code
      description: >-
        An error body. Individual errors may add context fields alongside these
        three.
    ForbiddenError:
      type: object
      additionalProperties: false
      properties:
        statusCode:
          const: 403
        message:
          type: string
        code:
          type: string
          enum:
            - kyc_approval_required
            - international_questionnaire_required
            - international_account_approval_required
            - international_customer_wallet_not_supported
          description: >-
            Present on verification, international access, and customer wallet
            refusals. Absent on tier denials, which carry `reason` instead.
        reason:
          type: string
          enum:
            - currency_not_available
            - feature_not_available
          description: Present on tier denials. Absent on every other refusal.
        currency:
          $ref: '#/components/schemas/AssetCode'
        feature:
          type: string
        currentTier:
          type: integer
          enum:
            - 1
            - 2
            - 3
        requiredTier:
          type: integer
          enum:
            - 1
            - 2
            - 3
      required:
        - statusCode
        - message
    RateLimitError:
      type: object
      additionalProperties: false
      properties:
        statusCode:
          const: 429
        message:
          type: string
        code:
          const: api_key_rate_limit_exceeded
        retryAfterSeconds:
          type: integer
          minimum: 1
      required:
        - statusCode
        - message
        - code
        - retryAfterSeconds
    ValidationError:
      type: object
      additionalProperties: false
      properties:
        statusCode:
          const: 400
        message:
          type: string
          description: The single failure, or a count when more than one field failed.
        code:
          const: validation_failed
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationFailure'
      required:
        - statusCode
        - message
        - code
        - errors
    ValidationFailure:
      type: object
      additionalProperties: false
      properties:
        message:
          type: string
        field:
          type: string
        code:
          type: string
        path:
          type: array
          items:
            anyOf:
              - type: string
              - type: integer
      required:
        - message
        - field
        - code
        - path
  responses:
    ValidationError:
      description: >-
        The request was rejected before it was acted on. Field failures list
        every failing field.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestError'
          example:
            statusCode: 400
            message: Must be a valid identifier.
            code: validation_failed
            errors:
              - message: Must be a valid identifier.
                field: accountId
                code: custom
                path:
                  - accountId
    AuthenticationError:
      description: >-
        The API key is missing, invalid, inactive, expired, for another
        environment, or blocked by its IP allowlist.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 401
            code: INVALID_API_KEY
            message: Invalid or inactive API credentials.
    ForbiddenError:
      description: >-
        Authenticated, but not permitted to hold or use this currency.
        Entitlement refusals carry `code`; tier denials carry `reason`,
        `currentTier`, and `requiredTier` instead.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenError'
          example:
            statusCode: 403
            message: >-
              International wallets for your customers are not available yet.
              Your own approval cannot be used for a customer wallet.
            code: international_customer_wallet_not_supported
            currency: USD
    NotFoundError:
      description: The requested resource was not found for this business.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 404
            code: resource_not_found
            message: Resource not found.
    ConflictError:
      description: The request conflicts with the current resource state.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 409
            code: resource_conflict
            message: The request conflicts with the current resource state.
    RateLimitError:
      description: The API key rate limit was exceeded.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            statusCode: 429
            message: Too many API requests. Try again later.
            code: api_key_rate_limit_exceeded
            retryAfterSeconds: 17
    ServerError:
      description: An unexpected server error occurred.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 500
            code: internal_server_error
            message: An unexpected error occurred.
    ProviderUnavailableError:
      description: >-
        A payment provider could not be reached. The request had no effect;
        retry shortly.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 503
            code: provider_unavailable
            message: We could not issue an account number just now. Try again shortly.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Sakawave API key
      description: >-
        A secret API key, sent as `Authorization: Bearer sk_test_…` in sandbox
        or `Bearer sk_live_…` in live.

````

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