Overview

A card is a payment instrument that enables users to conduct transactions at merchant locations. Endpoints

Method	Url
`POST`	/cards
`GET`	/cards
`GET`	/cards/customer/:id
`GET`	/card/:id
`GET`	/card/:id/balance
`PUT`	/card/:id/send-pin
`PUT`	/card/:id/pin
`PUT`	/card/:id/enroll2fa
`PUT`	/card/:id
`GET`	/card/digitalize/:id
`GET`	/card/:id/token
`POST`	/card/order

USD cards: verification and status USD virtual cards (MasterCard and Visa) are issued by our card partner, who verifies the customer before the card can be used. A new USD card can therefore have one of these statuses:

Status	Meaning
`pending`	The customer is still being verified. The card can’t be used, funded, or set to `active` or `inactive` yet.
`active`	Verification passed and the card is ready to use.
`canceled`	Verification failed, or the card was canceled. `cancellationReason` explains why when a reason is given.

You receive a card.updated event whenever the status changes, so there’s no need to poll. When verification fails If the card partner can’t verify the customer, the card is canceled and the amount you funded it with is returned to you automatically:

You receive card.updated with status set to canceled and cancellationReason saying why, for example Invalid BVN provided.
The card partner returns the card’s funded amount. This can take a little while after the card.updated event.
The amount is credited to your business’s USD settlement account, and you receive card.terminated with balance set to the amount returned.

The amount is returned once per card. The card issuance fee isn’t refunded. To try again, fix the customer’s details using cancellationReason and create a new card. Before creating a USD card, make sure the customer meets the USD card requirements. They’re checked before the customer is charged, and reissuing a card (POST /cards/:id/reissue) is checked the same way:

{
    "statusCode": 400,
    "message": "This card can't be reissued yet. Missing or invalid: a valid email address."
}

A canceled card can’t be funded, and neither can a USD card that is still pending. This applies to funding the card (POST /cards/:id/fund) and to a transfer into the card’s account. Nothing is charged, and the response is one of these messages:

This card has been canceled and can't be funded.
This card is still being verified by the card issuer and can't be funded yet.

Card Object

{
  "_id": "61d7004261f2a5ebf1e18a63",
  "business": "61d4150b00c7cdd1184ef455",
  "customer": {
    "_id": "61d6baf144b3a74b6b258630",
    "business": "61d57b7ebc8deefb4330f5b4",
    "type": "individual",
    "name": "Farouk Bakre",
    "status": "active",
    "individual": {
      "firstName": "Farouk",
      "lastName": "Bakre",
      "identity": {
        "type": "BVN",
        "number": "23456543",
        "_id": "61d6baf144b3a74b6b258632"
      },
      "_id": "61d6baf144b3a74b6b258631"
    },
    "billingAddress": {
      "line1": "Ikeja, Lagos",
      "line2": "",
      "city": "Lagos",
      "state": "Lagos",
      "country": "Nigeria",
      "postalCode": "100001",
      "_id": "61d6baf144b3a74b6b258633"
    },
  },
  "account": {
    "_id": "61d7004261f2a5ebf1e18a61",
    "business": "61d4150b00c7cdd1184ef455",
    "type": "wallet",
    "currency": "NGN",
    "accountName": "SUDO / FAROUK BAKRE",
    "bankCode": "999240",
    "accountType": "Current",
    "accountNumber": "8016813168",
    "currentBalance": 0,
    "availableBalance": 0,
    "provider": "SafeHaven",
    "providerReference": "61d70040240846001ebeb8ff",
    "referenceCode": "subacc_1641480256224",
    "isDefault": true,
  },
  "fundingSource": {
    "_id": "61d4150b00c7cdd1184ef459",
    "business": "61d4150b00c7cdd1184ef455",
    "type": "default",
    "status": "active",
    "jitGateway": null,
    "isDefault": true,
  },
  "type": "physical",
  "brand": "Verve",
  "currency": "NGN",
  "maskedPan": "506100******2989",
  "expiryMonth": "01",
  "expiryYear": "2025",
  "status": "active",
  "spendingControls": {
    "channels": {
      "atm": true,
      "pos": true,
      "web": true,
      "mobile": true,
      "_id": "61d7004261f2a5ebf1e18a65"
    },
    "allowedCategories": [],
    "blockedCategories": [],
    "spendingLimits": [
      {
        "amount": 10000000,
        "interval": "daily",
        "categories": [],
        "_id": "61d7004261f2a5ebf1e18a66"
      }
    ],
    "_id": "61d7004261f2a5ebf1e18a64"
  },
}

Customers

Funding Sources

Card Programs

Cards

Accounts

Authorizations

Transactions

Disputes

Simulator (Sandbox Only)

Overview