Skip to main content

Card Issuance

Learn how to issue virtual cards for your business members using the Brighty B2B API.

Overview​

Brighty allows you to issue virtual cards for your business members instantly. This guide covers the complete card issuance workflow from account setup to card activation and management.

Prerequisites​

Before issuing cards, ensure you have:

  • A verified business member in your system
  • Valid API token with card issuance permissions
  • At least one business account with sufficient balance for card fees

Card Issuance Workflow​

Step 1: Get or Create Account​

First, you need an account to link the card to for funding and fee payment.

Get Existing Accounts​

curl -X GET https://api.brighty.codes/business/v1/accounts \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}" \
  -H "Content-Type: application/json"

Response:

{
  "accounts": [
    {
      "id": "acc_12345678-1234-1234-1234-123456789012",
      "name": "Main Business Account",
      "balance": {
        "amount": "5000.00",
        "currency": "USD"
      },
      "type": "CURRENT",
      "openedAt": "2025-07-01T10:00:00Z"
    }
  ]
}

Create New Account (if needed)​

curl -X POST https://api.brighty.codes/business/v1/accounts \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "name": "Card Funding Account",
    "type": "CURRENT"
  }'

Step 2: Get Available Card Designs​

Retrieve available card designs to choose from:

curl -X GET https://api.brighty.codes/business/v1/cards/designs \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}"

Response:

{
  "cardDesigns": [
    {
      "id": "design_12345678-1234-1234-1234-123456789012",
      "code": "VIRTUAL_STANDARD",
      "formFactor": "VIRTUAL",
      "cardNetwork": "MASTERCARD",
      "image": "https://assets.brighty.app/cards/virtual-standard.png",
      "previewImage": "https://assets.brighty.app/cards/virtual-standard-preview.png",
      "status": "AVAILABLE",
      "backgroundColor": "#1e3a8a",
      "foregroundPrimaryColor": "#ffffff",
      "foregroundSecondaryColor": "#e5e7eb"
    }
  ]
}

You can hardcode a design ID in your application if you always use the same design.

Step 3: Create Card Intent​

Create an intent to validate the card order and calculate fees:

curl -X POST https://api.brighty.codes/business/v1/cards/order/intent \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "mem_12345678-1234-1234-1234-123456789012",
    "sourceCurrency": "USD",
    "cardDesignId": "design_12345678-1234-1234-1234-123456789012",
    "holderName": "John Doe"
  }'

Response:

{
  "amount": {
    "amount": "5.00",
    "currency": "USD"
  },
  "fees": {
    "CARD_ISSUE": {
      "sourceAmount": {
        "amount": "5.00",
        "currency": "USD"
      },
      "targetAmount": {
        "amount": "5.00",
        "currency": "USD"
      },
      "fx": null
    }
  },
  "remainingLimits": {
    "TOTAL": 10
  },
  "hash": "card_intent_hash_abc123def456789",
  "holderNameValidity": {
    "type": "VALID",
    "holderName": "John Doe"
  }
}

Step 4: Order the Card​

Use the intent data to order the actual card:

curl -X POST https://api.brighty.codes/business/v1/cards/order \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "mem_12345678-1234-1234-1234-123456789012",
    "cardDesignId": "design_12345678-1234-1234-1234-123456789012",
    "sourceAccountId": "acc_12345678-1234-1234-1234-123456789012",
    "hash": "card_intent_hash_abc123def456789",
    "fees": {
      "CARD_ISSUE": {
        "sourceAmount": {
          "amount": "5.00",
          "currency": "USD"
        },
        "targetAmount": {
          "amount": "5.00",
          "currency": "USD"
        }
      }
    },
    "holderName": "John Doe",
    "cardName": "Corporate Card"
  }'

Response:

{
  "card": {
    "id": "card_12345678-1234-1234-1234-123456789012",
    "cardOwnerId": "business_12345678-1234-1234-1234-123456789012",
    "cardHolderId": "mem_12345678-1234-1234-1234-123456789012",
    "status": "CREATED",
    "name": "Corporate Card",
    "type": "DEBIT",
    "network": "MASTERCARD",
    "formFactor": "VIRTUAL",
    "lastFour": "1234",
    "bin": "555544",
    "expirationDate": "2027-12",
    "cardHolderName": "John Doe",
    "securityPolicy": {
      "contactless": false,
      "internet": true,
      "atm": false,
      "location": false,
      "ecommerce": true
    },
    "spendingStrategy": {
      "name": "SINGLE",
      "accountId": "acc_12345678-1234-1234-1234-123456789012",
      "currency": "USD"
    },
    "spendingLimit": {
      "name": "MONTHLY",
      "limit": {
        "amount": "5000.00",
        "currency": "USD"
      },
      "spentAmount": {
        "amount": "0.00",
        "currency": "USD"
      }
    },
    "createdAt": "2025-07-04T15:30:00Z",
    "issuedAt": null,
    "activatedAt": null,
    "limitAmount": {
      "amount": "5000.00",
      "currency": "USD"
    },
    "availableAmount": {
      "amount": "0.00",
      "currency": "USD"
    }
  }
}

Step 5: Wait for Card to Become Issued​

The card starts with status CREATED and moves to ISSUED automatically. Check the card status:

curl -X GET https://api.brighty.codes/business/v1/cards/card_12345678-1234-1234-1234-123456789012 \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}"

Response when issued:

{
  "id": "card_12345678-1234-1234-1234-123456789012",
  "status": "ISSUED",
  "issuedAt": "2025-07-04T15:31:00Z"
  // ... other card properties
}

Step 6: Activate the Card​

Once the card status is ISSUED, activate it to make it ready for transactions:

curl -X POST https://api.brighty.codes/business/v1/cards/card_12345678-1234-1234-1234-123456789012/activate \
  -H "Authorization: Bearer ${BRIGHTY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "id": "card_12345678-1234-1234-1234-123456789012",
  "status": "ACTIVE",
  "activatedAt": "2025-07-04T15:32:00Z",
  "availableAmount": {
    "amount": "5000.00",
    "currency": "USD"
  }
  // ... other card properties
}

Your card is now ready for transactions!

Currency and Exchange Rates​

All Brighty cards have EUR as the base currency. Here's how currency conversion works:

Transaction Processing​

  1. EUR Transactions: If the user pays in EUR, no conversion occurs
  2. USD Transactions: If the user pays in USD, conversion from USD to EUR happens at the Mastercard scheme rate (use 0% bank fee in the Mastercard calculator)
  3. Dynamic Currency Conversion: If the user pays for a USD purchase in EUR (terminal choice), conversion uses the acquiring bank's rate
  4. Card Currency Conversion: If the card is linked to USDC (or another currency), EUR is then converted to the card's currency (e.g., EUR-USDC)

Rate Updates​

After clearing, exchange rates are updated both on the scheme side and Brighty's side. The transaction then receives its final status and final amounts.

Card Status Flow​

CREATED → ISSUED → ACTIVE
  • CREATED: Card ordered, being processed by card provider
  • ISSUED: Card issued by provider, ready for activation
  • ACTIVE: Card activated and ready for transactions

For card management operations like freeze, unfreeze, and terminate, see the Card Management guide.