Card API quickstart | AlphaX

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"