Getting Started - Card Issuance

What you'll build: a virtual card issued against a customer wallet, with a PIN set and card activity confirmed.

Time: under 10 minutes.

Prerequisites:

Sandbox credentials. See Sandbox Environment.
A customer with an active digital wallet. Follow Getting Started: Digital Wallets and KYC first if you don't have one.

Step 1 — Authenticate

POST {baseUrl}/eclipse-conductor/rest/v1/login
Content-Type: application/json

{
  "identity": "[email protected]",
  "password": "YourPassword123!"
}

Response:

{
  "headerName": "Authorization",
  "headerValue": "Bearer eyJhbGciOiJSUzI1NiJ9...",
  "tenantId": 42,
  "expires": "2026-05-19T10:30:00+00:00",
  "roles": ["TENANT_SYSTEM"]
}

Use headerValue as the value for the headerName header on every subsequent request. Check expires before each request and re-authenticate before the token expires.

API Reference →

Step 2 — Check the Wallet

Confirm the wallet is active before issuing a card against it.

GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}
Authorization: Bearer {jwt}

Response:

{
  "walletId": 1092847,
  "customerId": 3847291,
  "status": "ACTIVE",
  "currency": "ZAR",
  "currentBalance": 500.00,
  "availableBalance": 500.00
}

The wallet type must have card issuance enabled. If you're unsure, check the wallet type config: GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/wallet-types.

Step 3 — Issue a Virtual Card

POST {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/cards
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "externalUniqueId": "card-issue-00000001",
  "cardType": "VIRTUAL",
  "operationType": "PRIMARY_CARD",
  "cardRules": {
    "ecommerceTransactionsEnabled": true,
    "internationalTransactionsEnabled": false
  }
}

Response:

{
  "cardId": 72841903,
  "customerId": 3847291,
  "walletId": 1092847,
  "status": "ACTIVE",
  "cardType": "VIRTUAL",
  "pan": "512345******9012",
  "expires": "2031-05-31T23:59:59.999Z",
  "cardHolderName": "Sipho Dlamini",
  "cardRules": {
    "ecommerceTransactionsEnabled": true,
    "internationalTransactionsEnabled": false
  },
  "created": "2026-05-19T09:00:00.000Z"
}

Save the cardId. The pan is always returned masked — Eclipse never returns the full PAN in API responses.

A few notes on the request fields:

The wallet must have a card-enabled wallet type. Issuing against a non-card wallet type returns 400.
operationType: "PRIMARY_CARD" is for the first card on a wallet. Use "SUPPLEMENTARY_CARD" for additional cards on the same wallet.
internationalTransactionsEnabled: false is a safe default for new cards — it can be updated later.
externalUniqueId must be unique per card issuance.

API Reference →

Step 4 — Set a PIN

PUT {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/cards/{cardId}
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "pin": "1234"
}

Response: 200 OK with the updated card object.

In production, PIN entry is typically handled through a secure PIN pad or a mobile SDK — the PIN is never entered or stored in plaintext on application servers. This direct API approach is for sandbox testing only.

API Reference →

Step 5 — Retrieve the Card

Confirm the card is active and the details are correct.

GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/cards/{cardId}
Authorization: Bearer {jwt}

Response:

{
  "cardId": 72841903,
  "customerId": 3847291,
  "walletId": 1092847,
  "status": "ACTIVE",
  "cardType": "VIRTUAL",
  "pan": "512345******9012",
  "expires": "2031-05-31T23:59:59.999Z",
  "cardHolderName": "Sipho Dlamini",
  "cardRules": {
    "ecommerceTransactionsEnabled": true,
    "internationalTransactionsEnabled": false
  }
}

API Reference →

Step 6 — Check Card Activity

Once a test transaction has been processed against the card, retrieve the activity:

GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/cards/{cardId}/activities
    ?dateFromIncl=2026-05-19T00:00:00.000Z
    &dateToExcl=2026-05-20T00:00:00.000Z
    &dateFilterOn=transactionDate
    &limit=20
    &offset=0
Authorization: Bearer {jwt}

Response:

[
  {
    "cardHistoryId": 50001,
    "maskedPan": "512345******9012",
    "transactionType": "00",
    "responseCode": "00",
    "merchantLocation": "TAKEALOT ONLINE ZA",
    "transactionAmount": 299.00,
    "transactionCurrencyCode": "710",
    "transactionDate": "2026-05-19T09:45:00.000Z"
  }
]

responseCode: "00" is a successful authorisation. See Application Error Codes for the full list of response codes.

Updating Card Status

To block, stop, or re-activate a card:

PUT {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/cards/{cardId}
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "status": "STOPPED",
  "reason": "LOST"
}

Valid status values: ACTIVE, STOPPED, CANCELLED. Valid reason values include LOST, STOLEN, DAMAGED, FOUND.

Next Steps

Topic	Where to go
Process a card payment (e-commerce)	Getting Started: E-Commerce Acquiring
Full card lifecycle management	Card Use Cases
Physical card ordering and personalisation	Card Use Cases
Card limits and controls	Card Use Cases
Wallet transfers and withdrawals	Wallet Use Cases