Issue Card

Issue a USD virtual card. Pass the cardholder’s KYC inline (the cardholder is created or reused automatically), or use the Cardholders flow to issue to an existing cardholder. initialBalance is debited from your USD card wallet (fund-first). Every card is a wallet-enabled USD card (addable to Apple/Google Wallet), so capability is optional — omit it, or send APPLE_PAY/GOOGLE_PAY explicitly.

Card endpoints use the same base URL and API key as the rest of the API, and are signature-gated: send X-Numero-Signature and X-Numero-Signature-Version: v2 as well. See Request signing.

Endpoint

POST /api/v1/business/card/issue

Signature required: Yes

Headers

Header	Required	Description
`X-Numero-Api-Key`	Yes	Your API key
`X-Numero-Signature`	Yes	Base64 HMAC-SHA256 over the exact raw request body (POST) or the canonicalised query string (GET), keyed with your Public Key. See Request signing.
`X-Numero-Signature-Version`	Yes	Always `v2`.

Request body

Field	Type	Required	Description
`productCode`	string	Yes	Card product to issue from (see List Card Products)
`capability`	string	No	`APPLE_PAY` · `GOOGLE_PAY`. Omit for the same wallet-enabled card — it is the only type issued.
`initialBalance`	number	Yes for current products	Total amount to debit from the USD CARD wallet for activation. The current minimum is USD 10.00. It includes the mandatory opening card funding; it is not necessarily the resulting spendable card balance.
`firstName`	string	Yes	Cardholder first name
`lastName`	string	Yes	Cardholder last name
`email`	string	Yes	Cardholder email
`phone`	string	Yes	Cardholder phone including country calling code
`dateOfBirth`	string	Yes	`YYYY-MM-DD`
`address1`	string	Yes	Residential street address
`city`	string	Yes	City
`state`	string	Yes	State
`zipcode`	string	Yes	Postal code
`country`	string	Yes	ISO country code, e.g. `NG`
`idType`	string	Yes	`PASSPORT`, `NIN`, `NATIONAL_ID`, `DRIVERS_LICENSE`, `VOTERS_CARD` or `RESIDENT_ID`
`idNumber`	string	Yes	Identity-document number
`bvn`	string	No	Bank Verification Number (required by some issuers)
`idDocumentFrontUrl`	string	Required for new cardholder identity evidence	Direct HTTPS JPEG/PNG document-image URL accessible to Numero; not a Cloudinary management/share page or PDF URL.
`idDocumentBackUrl`	string	When required by document type	Direct HTTPS reverse-side image URL. Omit when not applicable.
`gender`	string	Yes	`male` or `female`
`proofOfAddressDocumentUrl`	string	Yes	Direct public HTTPS JPEG/PNG proof-of-address image
`proofOfFunds`	object	Yes	All five customer-attested proof-of-funds fields documented below
`label`	string	No	Friendly card name

These KYC fields are required by the inline issuance route because it creates a new cardholder when necessary. To issue to an existing cardholder without resubmitting their stored KYC, use POST /business/cardholders/{customerId}/cards.

Funding and identity requirements

Set initialBalance to the total activation amount. The current minimum is USD 10.00, including USD 5 mandatory initial funding available to spend. The same amount must be available in the merchant’s USD CARD wallet. It is not enough to have funds in another USD wallet: check it with GET /business/balance?currency=USD&purpose=CARD. For a new cardholder, supply accurate contact details, date of birth, residential address, ID type/number and the required document image. Numero converts the image into the issuer’s required representation; developers send image URLs, not provider base64 payloads. The dashboard collects uploads and can reuse eligible activation documents; API clients supply the direct image URL. Do not substitute a portrait for an identity document or change identity types to bypass verification.

Errors and safe retries

Missing identity evidence and malformed document URLs return HTTP 400 with error.code: "validation_error" and the affected field in error.param, before funding is reserved. For example:

{
  "data": null,
  "error": {
    "code": "validation_error",
    "message": "idDocumentFrontUrl is required for a new cardholder. Supply a public HTTPS URL to a JPG or PNG identity document.",
    "param": "idDocumentFrontUrl"
  },
  "meta": { "request_id": "YOUR_REQUEST_ID", "pagination": null }
}

The same validation applies to test keys. Use synthetic identity details and a public HTTPS-shaped fixture URL such as https://documents.example/front.jpg in test mode; test-mode document handling does not download real identity evidence. Existing cardholders reuse their stored evidence where available. Invalid proof-of-funds answers identify proofOfFunds in error.param. Correct the named field rather than increasing the activation amount. If initialBalance is below the product’s customer-facing activation minimum, the response uses error.code: "activation_required" and error.param: "initialBalance". This is request validation, not a wallet-balance lookup; correct the requested total, then check the USD CARD wallet separately. An approved card product or an ACTIVE provider customer is not sufficient proof of complete card KYC. Missing identity evidence can block issuance. Retain Numero’s request ID and any existing cardholder reference; correct the evidence on the existing profile instead of creating duplicate customers. Do not disable KYC checks. Test keys use the same product code and field validation, but do not require a production card-product activation. An enabled product returned by GET /business/card/products is immediately issuable in test mode. A provider timeout or server error is not proof that nothing was created or debited. Check the card list, request outcome, USD CARD wallet statement and webhooks before retrying. A confirmed pre-issuance rejection with no card or wallet movement must not be presented as successful issuance. Issuance, funding and notification delivery are separate outcomes to reconcile.

Request example

Proof of funds and address

Both inline issuance and cardholder creation also accept:

Field	Type	Description
`gender`	string	Customer’s gender, when required for issuer KYC.
`proofOfAddressDocumentUrl`	string	Direct HTTPS document-image URL; Numero converts it to the issuer’s base64 representation.
`proofOfFunds`	object	Customer-attested answers below; never populate using guessed or example values.

The proof-of-funds object uses camelCase Numero fields: employmentStatus, occupation, primaryPurpose, sourceOfFunds, expectedMonthlyPay. If provided, all five must contain valid documented options. See the machine-readable CardProofOfFunds schema for the complete accepted values. This is a questionnaire, not an extra document-upload URL. Provider KYC readiness is required before issuance; a locally created cardholder is not proof of approval.

curl -X POST "https://api.usenumero.com/numeroaccount/api/v1/business/card/issue" \
  -H "X-Numero-Api-Key: your_api_key" \
  -H "X-Numero-Signature: $SIGNATURE" \
  -H "X-Numero-Signature-Version: v2" \
  -H "Content-Type: application/json" \
  -d '{
    "productCode": "USD_APPLE_PAY",
    "capability": "APPLE_PAY",
    "initialBalance": 25,
    "firstName": "Ada",
    "lastName": "Obi",
    "email": "[email protected]",
    "phone": "+2348000000000",
    "dateOfBirth": "1990-01-01",
    "address1": "1 Example Street",
    "city": "Lagos",
    "state": "Lagos",
    "zipcode": "100001",
    "country": "NG",
    "gender": "female",
    "idType": "PASSPORT",
    "idNumber": "TEST123",
    "idDocumentFrontUrl": "https://cdn.example.com/test-passport.png",
    "proofOfAddressDocumentUrl": "https://cdn.example.com/test-address.png",
    "proofOfFunds": {
      "employmentStatus": "employed",
      "occupation": "151252",
      "primaryPurpose": "purchase_goods_and_services",
      "sourceOfFunds": "salary",
      "expectedMonthlyPay": "0_4999"
    }
  }'

Response

Returns the card (masked only). HTTP 200 alone does not confirm issuance: status: Pending with operationReference and operationStatus means processing or reconciliation is outstanding. Keep the reference and read the card again; do not submit another issuance while the first is unresolved. Use the returned card balance to determine the amount available to spend.

{
  "data": {
    "cardReference": "NCRD24AD18BEBD474A",
    "customerId": "NCUS9953596C2B7F45",
    "label": "Ads spend",
    "nameOnCard": "Ada Obi",
    "billingAddress": {
      "address": "100 Test Street",
      "city": "Test City",
      "state": "Test State",
      "postalCode": "00000",
      "country": "US"
    },
    "brand": "Visa",
    "firstSix": "428852",
    "lastFour": "6353",
    "expiryMonth": "06",
    "expiryYear": "2029",
    "currency": "USD",
    "balance": 22.0,
    "status": "Active",
    "isPhysical": false,
    "dailyLimit": 5000,
    "perTransactionLimit": 1000,
    "issuedAt": "2026-06-16T12:00:00Z",
    "capabilities": [
      "USD",
      "APPLE_PAY",
      "GOOGLE_PAY"
    ]
  },
  "error": null,
  "meta": {
    "request_id": "req_365123ebc73323f1482508560ce6400e",
    "pagination": null
  }
}

Getting Started

Transfers & Payouts

Collections (Virtual Accounts)

Wallet-as-a-Service

Customers

Invoices

Cards

Cardholders

Balance & Transactions

Value Added Services

Credit

Verification / KYC

Webhooks

Endpoint

Headers

Request body

Funding and identity requirements

Errors and safe retries

Request example

Proof of funds and address

Response

​Endpoint

​Headers

​Request body

​Funding and identity requirements

​Errors and safe retries

​Request example

​Proof of funds and address

​Response

Endpoint

Headers

Request body

Funding and identity requirements

Errors and safe retries

Request example

Proof of funds and address

Response