Quickstart

From a sandbox key to a funded virtual card in five requests.

1 · Check your key

curl
curl https://www.primcard.io/api/partner/v1/ping \
  -H "Authorization: Bearer sk_test_YOUR_KEY"
response
{ "ok": true, "partner_id": "…", "partner_name": "Acme", "mode": "test" }

2 · Get sandbox money

Test mode has a faucet instead of deposits. Money-moving calls always need an Idempotency-Key header (any unique string).

curl
curl -X POST https://www.primcard.io/api/partner/v1/test/credit \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Idempotency-Key: fund-001" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 100000 }'   # $1,000.00 — cents, always

3 · Preview the cost

curl
curl -X POST https://www.primcard.io/api/partner/v1/quotes \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "card_issue", "amount": 10000 }'
response
{
  "type": "card_issue", "currency": "USD",
  "card_amount": 10000,
  "total_debited": 15600,
  "fees": [
    { "type": "card_activation", "amount": 5000 },
    { "type": "card_funding", "amount": 600 }
  ]
}

Fees are on top: the card gets $100.00, your balance pays $156.00 (standard rates — your account may have negotiated ones; the quote always shows yours).

4 · Create the card

If your account has more than one BIN enabled, add an optional product_code to choose which one — call GET /products to see your options (each has a product_code, bin, and network). Omit it to use your default.

curl
curl -X POST https://www.primcard.io/api/partner/v1/cards \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Idempotency-Key: card-001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "external_ref": "user-42-card-1",
    "card_name": "Ada'\''s card"
  }'

201 returns the active card; 202 means the network is finishing asynchronously — poll GET /cards/{id} or listen for the card.issued webhook. external_ref is your own id for the card, unique per account — reusing one returns 409 external_ref_taken.

5 · Watch it work

curl
# Simulate a $12.50 purchase (test mode only)
curl -X POST https://www.primcard.io/api/partner/v1/test/cards/CARD_ID/simulate-transaction \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "purchase", "amount": 1250 }'

# …then read it back
curl https://www.primcard.io/api/partner/v1/cards/CARD_ID/transactions \
  -H "Authorization: Bearer sk_test_YOUR_KEY"

Going live is the same code with sk_live_ instead of sk_test_ — plus real funding via POST /funding/deposit-address.