API reference

Issue a card

POST/cards

Issues a virtual card to a cardholder. The issuance fee, KYC fee and any initial load plus its top-up fee are debited from your USD wallet in the same environment. Requires an Idempotency-Key. In Live, the account must be activated and approved for Live.

Required scope: cards:write
Idempotency-Key: Required
Environments: Sandbox; Live when authorized

In Live this endpoint returns live_operations_disabled or provider_not_configured until a payment provider is authorized for this deployment.

Request body

productenumrequired
Card product id. See the pricing page for fees and limits.
"visa-400", "visa-404", "visa-493-premium", "visa-493-atm", "visa-536"
cardholderobjectrequired
cardholder.first_namestringrequired
min length 1 · max length 50 · pattern ^[\p{L} '\-.]+$/u
cardholder.last_namestringrequired
min length 1 · max length 50 · pattern ^[\p{L} '\-.]+$/u
cardholder.emailstringrequired
max length 254 · email
initial_loadintegeroptional
Optional amount to load at creation, in USD cents ($10.00–$2,500.00). Not available for every product.
min 1000 · max 250,000
referencestringoptional
max length 64
metadatamap of stringoptional
Up to 20 string key/value pairs stored with the object.

Example request

curl -X POST "https://api.gloresend.com/sandbox/v1/cards" \
  -H "Authorization: Bearer $GLORESEND_TEST_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "visa-404",
    "cardholder": {
      "first_name": "Ada",
      "last_name": "Example",
      "email": "ada@example.com"
    },
    "initial_load": 5000,
    "reference": "EMP-0042"
  }'

Response · 201

201 · application/json

{
  "id": "card_9f8e7d6c5b4a3f2e1d0c",
  "object": "card",
  "environment": "sandbox",
  "product": "visa-404",
  "network": "Visa",
  "currency": "USD",
  "status": "active",
  "cardholder": {
    "first_name": "Ada",
    "last_name": "Example",
    "email": "ada@example.com"
  },
  "last4": "4242",
  "expiry_month": "10",
  "expiry_year": "2029",
  "balance": 5000,
  "reference": "EMP-0042",
  "metadata": {},
  "created_at": "2026-10-15T09:30:00.000Z",
  "test_data": true,
  "issuance": {
    "initial_load": 5000,
    "fee": 230,
    "fee_breakdown": {
      "issuance": 65,
      "kyc": 65,
      "topup": 100
    }
  }
}

Response fields

None.

Errors

401authentication_requiredNo credentials were supplied. Send Authorization: Bearer <api key>.
401invalid_api_keyThe API key is unknown, revoked or expired.
401environment_mismatchThe API key belongs to a different environment than the base URL you called. Sandbox keys (gs_test_) only work against the Sandbox base URL, Live keys (gs_live_) only against the Live base URL.
429rate_limitedToo many requests. Wait for the number of seconds in the Retry-After header.
400validation_errorThe request body, query or headers failed validation. param points at the first invalid field.
400idempotency_key_requiredThis endpoint can create side effects and requires an Idempotency-Key header.
422idempotency_key_reuseThe Idempotency-Key was already used with a different request body or endpoint.
403insufficient_scopeThe API key does not have the scope required for this endpoint.
400product_unavailableThe requested card product is not available through the API for this environment.
402insufficient_fundsThe wallet's available balance is lower than the amount plus fees.
403activation_requiredLive card programs require an activated account (business verification and setup fee).
503live_operations_disabledLive money movement is not enabled on this deployment. No provider has been authorized yet.
503provider_not_configuredNo payment provider is configured for this environment and operation.
502provider_errorThe downstream provider returned an error. The transfer was marked as failed and reserved funds were released.
504provider_timeoutThe downstream provider did not answer in time. The transfer was marked as failed and reserved funds were released.