---
title: "Create Card"
method: POST
path: "/cards"
---

# Create Card

`POST /cards`

Create, map or replace cards for a specific customer.

## Request body

- object
  - `customerId` string, required — The customer `_id`.
  - `fundingSourceId` string — The funding source `_id`. Required if you wish to map card to an existing funding source.
  - `type` 'physical' | 'virtual', required — The card type.
  - `brand` 'Verve' | 'AfriGo' | 'MasterCard' | 'Visa' — The card brand.
  - `number` string — The card PAN (Verve or AfriGo) or Card ID (Visa). Required if `type` is `physical`.
  - `enable2FA` boolean — Enable 2FA for the card, this enables the card to receive OTP for web and mobile transactions.
  - `currency` 'NGN' | 'USD', required — The currency type.
  - `issuerCountry` 'NGA' | 'USA' — 3 Digits Issuer Country. `NGA` for Nigeria and `USA` for United States. Defaults to `NGA`.
  - `status` 'active' | 'inactive', required — The initial card status.
  - `metadata` string, json — The metadata object to attach to the card. Stored in key-value pair
  - `spendingControls` object — Card spending controls. Default usage limits will be applied if non is provided.
    - `allowedCategories` string[] — Array of allowed categories (MCC).
    - `blockedCategories` string[] — Array of blocked categories (MCC).
    - `channels` object — Channels allowed to use card on
      - `atm` boolean — Set to `true` to allow atm transactions. Otherwise, set to `false`.
      - `pos` boolean — Set to `true` to allow pos transactions. Otherwise, set to `false`.
      - `web` boolean — Set to `true` to allow web transactions. Otherwise, set to `false`.
      - `mobile` boolean — Set to `true` to allow mobile transactions.
    - `spendingLimits` object[] — Array of spending limit objects.
      - `amount` integer, required — The amount to set as limit.
      - `interval` 'daily' | 'weekly' | 'monthly' | 'yearly', required — The limit interval.
  - `bankCode` string — The bank code of existing account. Required if you wish to map card to existing account.
  - `accountNumber` string — The account number of existing account. Required if you wish to map card to existing account.
  - `replacementFor` string — The `_id` of the current card you wish to replace. Required for card replacement.
  - `replacementReason` 'lost' | 'stolen' — The reason for replacement. Required for card replacement.
  - `debitAccountId` string — Debit account `_id`. Required for all virtual cards and giftcards.
  - `amount` integer — Funding amount. Required for mastercard.
  - `sendPINSMS` boolean — Send default PIN to customer phone number via SMS.
  - `expirationDate` string — Card expiry date. Applies to Visa cards only. Format `MMM-YYYY` example `AUG-2025`. All cards are subject to maximum of 3 years validity.

## Response `201`

Card created successfully.

- object
  - `statusCode` integer — Status code of the response. `200` indicates a successful request.
  - `message` string — Human-readable description of the result.
  - `data` object — Response payload.
    - `business` string — Identifier of the business that owns this object.
    - `customer` string — Associated customer — an id, or a summary object on nested resources.
    - `account` string — Associated account — an id, or a summary object on nested resources.
    - `fundingSource` string — Identifier of the funding source backing this object.
    - `type` string — Type of the object.
    - `brand` string — Card scheme/brand (e.g. `Verve`, `MasterCard`).
    - `currency` string — ISO 4217 currency code (e.g. `NGN`).
    - `maskedPan` string — Masked card number (PAN).
    - `expiryMonth` string — Card expiry month (MM).
    - `expiryYear` string — Card expiry year (YYYY).
    - `metadata` object — Arbitrary key-value pairs attached to the object.
      - `createdBy` string — Identifier of the actor that created the object.
      - `purpose` string — Free-text purpose of the card.
    - `status` string — Current status of the object.
    - `spendingControls` object — Spending limits and channel/category controls applied to the card.
      - `channels` object — Channels through which the card may be used.
        - `atm` boolean — Whether ATM usage is allowed.
        - `pos` boolean — Whether POS usage is allowed.
        - `web` boolean — Whether web/online usage is allowed.
        - `mobile` boolean — Whether mobile usage is allowed.
        - `_id` string — Unique identifier of the object.
      - `allowedCategories` unknown[] — Merchant category codes (MCC) explicitly allowed.
        - unknown
      - `blockedCategories` unknown[] — Merchant category codes (MCC) explicitly blocked.
        - unknown
      - `spendingLimits` object[] — Configured spending limits.
        - `amount` integer — Amount in the minor currency unit (e.g. kobo).
        - `interval` string — Interval the limit applies over (`daily`, `weekly`, `monthly`, `yearly`).
        - `categories` unknown[] — Merchant category codes the limit applies to.
          - unknown
        - `_id` string — Unique identifier of the object.
      - `_id` string — Unique identifier of the object.
    - `is2FAEnrolled` boolean — Whether the card is enrolled for 3-D Secure / 2FA.
    - `isDefaultPINChanged` boolean — Whether the default PIN has been changed.
    - `disposable` boolean — Whether the card is single-use / disposable.
    - `refundAccount` unknown
    - `isDeleted` boolean — Whether the object has been soft-deleted.
    - `createdAt` string, date-time — ISO 8601 timestamp of when the object was created.
    - `updatedAt` string, date-time — ISO 8601 timestamp of when the object was last updated.
    - `_id` string — Unique identifier of the object.
    - `__v` integer — Internal document version (Mongo).

## Other responses

- `400` — Validation error.
- `401` — Authentication failed — missing or invalid API key.

---

[API](https://skmtc.net/sudo/apis/sudo-sandbox-api.md) · [All operations](https://skmtc.net/sudo/apis/sudo-sandbox-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sudo/sudo-sandbox-api/versions/52be624fcb53/schema)