Cards - KemyCard Dev API

The card products

Where do I find the characteristics of a card?

Everything about a card product is returned by GET /cards/products: network, currency, Apple Pay and Google Pay, ATM, limits, validity, initial load and the fees of your plan. This endpoint is the reference: it is always up to date, and you can display its values to your users.Example of a product, as returned on the Starter plan:

curl https://api.kemycard.com/v1/cards/products \
  -H "Authorization: Bearer sk_live_..."

{
  "success": true,
  "data": [
    {
      "code": "01a0e7f7-390b-7e21-add2-259ea0eb9019",
      "name": "404-BIN",
      "description": "404-BIN",
      "brand": "VISA",
      "currency": "USD",
      "type": "virtual",
      "is_issuable": true,
      "is_reloadable": true,
      "required_level": "basic",
      "required_kyc_level": 1,
      "limits": {
        "max_balance": 50000,
        "min_reload": 5,
        "max_reload": 3000,
        "spend_limit_monthly_kyc_level_1": 5000,
        "spend_limit_monthly_kyc_level_2": 1000000,
        "max_card_per_user_kyc_level_1": 5,
        "max_card_per_user_kyc_level_2": 0,
        "unlimited_cards": true,
        "period_of_validity_months": 36
      },
      "features": {
        "google_pay": true,
        "apple_pay": true,
        "atm_available": false,
        "addons": false
      },
      "initial_load": {
        "required": true,
        "min": 10,
        "max": 2500
      },
      "fees": {
        "plan": "starter",
        "creation_fee": 3.5,
        "annual_fee": null,
        "monthly_fee": null,
        "reload_fee": { "fixed": 1, "percent": 2 },
        "auth_fee": 0.3,
        "fx_cross_border_fee_percent": 2.5
      }
    }
  ],
  "meta": {
    "request_id": "8f3c1a2b4d5e6f70",
    "timestamp": "2026-10-17T10:00:00+00:00",
    "mode": "live"
  },
  "pagination": { "total": 3 }
}

Field	What it tells you
`brand`, `currency`, `type`	Network (Visa or Mastercard), card currency, virtual card
`is_reloadable`	Whether the card can be topped up after its creation. A non-reloadable card is a prepaid card: it is loaded once, at creation
`required_kyc_level`	The KYC level the customer needs to receive this card
`limits`	Maximum card balance, minimum and maximum top-up, spend per month and number of cards per customer by KYC level, validity in months
`features`	Apple Pay, Google Pay, ATM withdrawals and add-ons
`initial_load`	Whether an amount must be loaded at creation, with its minimum and maximum
`fees`	The fees of your plan for this product (see Plans)

Visa or Mastercard?

Both networks are available, as virtual cards. Each network has its own ops balance: a Visa card is funded from cards_visa, a Mastercard from cards_mastercard. The list of products and their network is returned by GET /cards/products.

In which currency are the cards?

The currency of each product is in its currency field. Payments in another currency are converted, with the cross-border fee of the product (fx_cross_border_fee_percent).

Do the cards work with Apple Pay and Google Pay?

Yes when features.apple_pay and features.google_pay are true for the product.

Can I choose the BIN or the issuing country?

Our cards are issued by banks in the United States, from a pool of BINs that varies from one card to another. We do not commit to a specific BIN or BIN country in advance.

How long is a card valid?

The validity is in limits.period_of_validity_months. The exact expiry date of each card is returned with its details once it is active.

Cardholders

Which countries are supported?

Cardholders residing in every country are supported, except Libya, Iran, North Korea and Iraq.

What information is required for a cardholder?

You create the customer through the API with their identity details: first name, last name, date of birth, email, phone number and full address. All of them are required. The email must be the real, working address of the cardholder. See Create a customer.

Is identity verification required?

The KYC level a customer needs for a product is in required_kyc_level, and the limits per level are in limits. Identity verification is done on a government-issued identity document with a liveness check, through a hosted link returned by the API. See KYC levels and KYC flow.You are responsible for the accuracy of the data you submit, and your product must never present the cards as anonymous or as available without identity checks.

How many cards can a customer have?

It depends on the product and on the KYC level of the customer: max_card_per_user_kyc_level_1 and max_card_per_user_kyc_level_2. When unlimited_cards is true, the number of cards is not limited from KYC level 2.

Can the cards be issued under my brand?

Yes. You offer the cards in your own interface, under your own brand. Your users never open a KemyCard account. Any use of the KemyCard name or logo in your product must be agreed with us beforehand.

Funding a card

How is a card funded?

From your ops balance of the card network. When your user asks for a top-up, you debit them in your own system and call POST /cards/{code}/topup. The amount and the fee are debited from your cards_visa or cards_mastercard balance; the request is refused if the balance is insufficient. See Top up a card and Ops balance.

Is the top-up fee deducted from the card?

No. The fee is added to the amount and debited from your ops balance: the card receives the full amount you top up.

Why are there two fees, on the ops balance deposit and on the top-up?

They are two distinct operations. The ops balance deposit fee is charged when you add funds to your balance. The top-up fee is charged each time a card is loaded from that balance. Fund your ops balance in batches, sized to your expected top-up volume, rather than once per top-up. See Plans.

What happens if a top-up fails?

The amount and its fee are refunded automatically to your ops balance, and you receive card.topup.failed.

Using the card

Which fees does the cardholder pay when using the card?

These fees are debited from the card balance itself, not from your ops balance: the authorization fee (auth_fee) on each payment, and the cross-border fee (fx_cross_border_fee_percent) on payments in another currency or with a foreign merchant. There is no monthly fee, except on products with an annual_fee.

Where can the cards be used?

The cards are made for international online payments. Recurring subscriptions (SaaS, AI tools, cloud and digital services) and advertising platforms (Google Ads, Facebook Ads, X Ads and similar) are part of their normal use. Video games and gaming platforms are fine.No issuer can guarantee that a given merchant accepts a card.

Which merchants are not allowed?

The cards must not be used with money transfer and remittance services, casinos and gambling, or for drugs and any illegal goods or services. These payments are declined, and repeated attempts can lead to the termination of the card.

What happens after repeated declined payments?

A card that records 12 declined transactions within one week is terminated, and its remaining balance is returned to your ops balance. This happens most often with subscriptions charged on an empty card: warn your users before a renewal date, and ask them to keep enough balance for the payment and its fees.

Which billing address should the cardholder enter at the merchant?

No billing address is imposed on the card. The cardholder can enter the address of their choice; you can suggest the one you hold for that customer.

How does 3-D Secure work?

When a merchant asks for a 3-D Secure confirmation, you receive the card.3ds_request webhook with the one-time code, the merchant, the amount and the currency. Relay the code to your user immediately in your interface: it is valid for a few minutes, and KemyCard does not send it to your user.

How are merchant refunds handled?

A merchant refund or a reversal is credited to the card. You receive it through the card.transaction webhook (type refund) with the card reference, to reconcile it with the right user.

How do I follow the card transactions?

In real time with the card.transaction webhook, and on demand with GET /cards/{code}/transactions. Each movement has a type (settle, auth, decline, refund, fee, auth_fee, fx_fee), a status, the merchant, the amount and the balance after the movement.

How do I show the card number, expiry and CVV to my user?

With GET /cards/{code}/sensitive, called from your server at the moment your user needs to see the card. Never store or log the response. See Compliance and security.

Can a card be frozen?

Yes, with POST /cards/{code}/freeze and POST /cards/{code}/unfreeze. A frozen card declines payments; its balance is kept.

Withdrawing and terminating

Can I move funds from a card back to my balance?

Yes, with POST /cards/{code}/withdraw. The amount is credited to the ops balance of the card network, minus the card withdrawal fee of your plan.

Minimum 5 USD per withdrawal.
At least 5 USD must remain on the card: you can withdraw up to the card balance minus 5 USD.
The card balance is read in real time from the card provider before the withdrawal.

How do I terminate a card and recover its whole balance?

With POST /cards/{code}/terminate. The card becomes cancelling (card.termination_pending): it can no longer be topped up. Once the card provider has closed it, its remaining balance is returned to your ops balance, minus the card provider fee and the termination fee of your plan, and you receive card.terminated with the refunded amount.

Can a card be terminated without my request?

Yes: after 12 declined transactions within one week, or by the card provider. You receive card.terminated, and the remaining balance is returned to your ops balance. No termination fee is charged when you did not request it.

​The card products

​Cardholders

​Funding a card

​Using the card

​Withdrawing and terminating

The card products

Cardholders

Funding a card

Using the card

Withdrawing and terminating