Skip to navigation
Card Issuing

Card API quickstart

Run the full card flow end to end
View as Markdown

This walks through the whole flow against the sandbox (https://public-api.demo.alphax.asia). Set your key and company once:

export ALPHAX_KEY="<YOUR_API_KEY>"
export BASE="https://public-api.demo.alphax.asia/v1"

1. Onboard a company

curl -X POST "$BASE/companies" \
  -H "X-API-Key: $ALPHAX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Ltd",
    "countryCode": "HK",
    "directorName": "Jane Director",
    "directorEmail": "jane@acme.example",
    "directorPhone": "+85251234567",
    "addressLine1": "10 Queens Road",
    "addressLine2": "Central",
    "city": "Hong Kong",
    "state": "Hong Kong",
    "postalCode": "999077",
    "products": ["Card"]
  }'

The response returns the company id — export it as CID and send it as X-Company-Id on the calls below.

export CID="<company id from the response>"

2. Submit KYB

industry is a NAICS code, not free text.

curl -X POST "$BASE/kyb-profiles" \
  -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Acme Ltd",
    "industry": "541511",
    "registrationCountry": "HK",
    "registrationNumber": "12345678",
    "website": "https://acme.example",
    "uboFirstName": "Jane",
    "uboLastName": "Owner",
    "uboGender": "FEMALE",
    "uboCountryCode": "HK",
    "uboIdType": "PASSPORT",
    "uboIdNumber": "P1234567",
    "uboDob": "1990-01-15"
  }'

3. Create a wallet and open a deposit address

curl -X POST "$BASE/wallets" \
  -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID" \
  -H "Content-Type: application/json" \
  -d '{ "currency": "USDC" }'
# Open an address to deposit into (see the sandbox note below for the chain).
curl -X POST "$BASE/wallets/<WALLET_ID>/addresses" \
  -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID" \
  -H "Content-Type: application/json" \
  -d '{ "chain": "ETH" }'

Funding on sandbox uses testnet assets — there is no mock-balance endpoint. For USDC, deposits are only enabled on Ethereum Sepolia (contract 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238). Open an ETH address, get test USDC from a faucet such as faucet.circle.com, and send it to that address. We credit the wallet and fire wallet.deposit_received.

Confirm the balance landed:

curl "$BASE/wallets/<WALLET_ID>" \
  -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID"

4. Top up the spending account

curl -X POST "$BASE/card-spending-account/topups" \
  -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID" \
  -H "Content-Type: application/json" \
  -d '{ "walletCurrency": "USDC", "amount": 100 }'

Check the spending balance any time:

curl "$BASE/card-spending-account" \
  -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID"

5. Create a card holder and a card

curl -X POST "$BASE/card-holders" \
  -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John", "lastName": "Holder",
    "email": "john@acme.example", "dateOfBirth": "1992-05-20",
    "phone": "+14155550123",
    "addressLine1": "1 Market St", "addressLine2": "Suite 200",
    "city": "San Francisco", "state": "CA",
    "countryCode": "US", "postalCode": "94105"
  }'
# Pick a BIN the company can issue on.
curl "$BASE/card-bins" -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID"
curl -X POST "$BASE/cards" \
  -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID" \
  -H "Content-Type: application/json" \
  -d '{
    "cardHolderId": "<CARD_HOLDER_ID>",
    "name": "Marketing Card",
    "category": "MarketingExpenses",
    "bin": "<BIN>"
  }'

6. Reveal the card

POST /v1/cards/{id}/details returns a short-lived token; render it with the card widget to show the PAN, expiry, and CVV.

curl -X POST "$BASE/cards/<CARD_ID>/details" \
  -H "X-API-Key: $ALPHAX_KEY" -H "X-Company-Id: $CID"