Skip to main content
Webhooks let you receive instant HTTP notifications when events happen — a KYC is approved, a card transaction occurs, a wallet deposit is received, etc. Instead of polling our API, we push the data to your server.
You must configure at least one active webhook endpoint before you can create customers. This ensures you can receive important notifications about your customers’ activity.

How webhooks work

Step 1: Set up your server

Before creating a webhook, your server must be ready to receive POST requests. Here’s a minimal example:
Your endpoint must return a 2xx status code to acknowledge receipt. Any other status code will be treated as a failure and trigger retries.

Step 2: Register your webhook

Once your server is ready, register your endpoint:
1

We validate your URL

Must start with https://. HTTP URLs are rejected.
2

We send a ping

A ping event is POSTed immediately to your URL (header X-KemyCard-Event: ping, 10-second timeout). Answer it with 200.This ping is signed, but with the secret you only receive in the response to this request, so you cannot verify it yet. A ping carries no data: acknowledge it without verification, as in the examples above. If your server rejects it with 401 or 403 because the signature cannot be checked, registration still succeeds (your URL is reachable). Any other status, a timeout or an invalid TLS certificate makes registration fail.
3

Endpoint is created

If the ping succeeds, the endpoint is created and the response includes your secret — this is the only time the secret is shown. Store it securely.
Response:
Once your secret is stored, call POST /v1/webhooks/{code}/ping to receive a ping you can verify, and test your signature check end to end. This manual ping expects a 2xx response.
Save the secret immediately! It is only shown once, at creation time. You need it to verify webhook signatures. If you lose it, use the /rotate-secret endpoint to generate a new one (the old one becomes invalid immediately).

Step 3: You’re ready

That’s it. From now on, every time an event you subscribed to occurs, we’ll POST it to your URL with the full payload and signature headers.

Available events (45)

Subscribe to specific events, or use "*" to receive everything.

Webhook payload format

Every webhook delivery is wrapped in this envelope:

Event payloads

Below is the detailed data payload for each event, along with when it is triggered.

KYC events

Triggered when: The customer’s identity verification is approved. The customer reaches the verified level. The verification is billed at this moment (see balance.debited, reason: kyc_verification).
verified_identity is the identity read on the document. identity_mismatch is true when it differs from the identity you declared for this customer (name or date of birth). In that case status is restricted and a kyc.identity_mismatch event follows.
Triggered when: A KYC is approved but the identity read on the document differs from the one you declared. The customer is restricted by KemyCard and cannot be used until you call POST /kyc/{customerCode}/synchronize. The activate endpoint does not lift this restriction.
Triggered when: You called POST /kyc/{customerCode}/synchronize. The declared identity now matches the verified identity and the restriction is lifted.
Triggered when: The verification is declined (unreadable document, blurry photo, fraud detected, etc.) or abandoned by the customer. Request a new link with POST /kyc/{customerCode}/link to let the customer retry.
Triggered when: The verification session expired before the customer completed it. Request a new link to restart.
Triggered when: The submitted documents are insufficient and the customer must submit again. Request a new link and redirect the customer.
Triggered when: The verification has been submitted and requires a manual review. No action needed: a final kyc.approved or kyc.rejected event follows.

POA events

Triggered when: The customer’s proof of address is approved. The customer reaches the full level. The verification is billed at this moment (see balance.debited, reason: poa_verification).
Triggered when: The proof of address is rejected (name or address does not match, document too old, unreadable document, etc.). The customer stays verified. Submit a new document with POST /poa/{customerCode}/document to retry. If the document is genuine but does not show the customer’s full name, open a support ticket from your secure KemyCard account with the customer_code (priority channel); to follow up, email hi@kemycard.com with your ticket number.

Card events

Every card event carries the same base fields, plus the fields specific to the event:
Triggered when: A card requested with POST /cards has been issued and is ready to use. Call GET /cards/{code}/sensitive to get its number, CVV and expiry.
Triggered when: A card requested with POST /cards could not be issued. The card is failed and everything that was debited (initial load and fees) is refunded to the same cards_visa or cards_mastercard balance.
Triggered when: A top-up requested with POST /cards/{code}/topup has been applied. balance is the new card balance.
Triggered when: A top-up could not be applied, for example because the card was terminated in the meantime. The amount and the fee are refunded to the same cards_visa or cards_mastercard balance.
Triggered when: An operation occurs on the card: payment, declined payment, merchant refund or fee. The transaction object has the same format as GET /cards/{code}/transactions; balance is the card balance after the operation.
transaction.type values: settle (payment), auth, decline, refund, fee, auth_fee, fx_fee.
Triggered when: A merchant asks for a 3-D Secure confirmation of an online payment. A code asked when the card is added to Apple Pay or Google Pay is sent with card.wallet_activation_code instead. The event carries the one-time code your customer must enter on the merchant page: relay it to your customer immediately, it is only valid for a few minutes. KemyCard does not send it to your customer.
Triggered when: Your customer adds the card to Apple Pay, Google Pay or Samsung Pay by hand (typing the card details), and the wallet asks for a verification code. Your customer chooses in the wallet to receive it by email or by text message; the code is then sent to you with this event. Relay it to your customer immediately, by email or by a notification in your app: it is only valid for a few minutes, and KemyCard does not send it to your customer. last_four and external_reference tell you which card and which customer it is for. digital_wallet is Apple Pay, Google Pay or Samsung Pay when the wallet is known, otherwise null.
The wallet decides whether a code is needed: when an addition is approved without one, no event is sent.
Triggered when: The next year of a 493 ATM card has been debited on the card anniversary. The fee is billed to you, never to the cardholder: it is debited from your cards_visa balance at the price of your plan, even if the balance is too low. annual_fee.balance_after can therefore be negative, which suspends your account (see Negative balance and suspension).
Triggered when: You froze the card with POST /cards/{code}/freeze. Payments are declined until it is unfrozen. The payload is the base card payload, with status: frozen.
Triggered when: You unfroze the card with POST /cards/{code}/unfreeze. The payload is the base card payload, with status: active.
Triggered when: A withdrawal requested with POST /cards/{code}/withdraw is completed. The base card payload (with the new balance) plus withdrawal_id, amount (withdrawn from the card), fee (card withdrawal fee of your plan), net_amount (credited to your balance) and credited_balance (cards_visa or cards_mastercard).
Triggered when: A withdrawal could not be completed by the card provider after it was accepted. Nothing was credited and the card balance is unchanged.
Triggered when: You requested the termination with POST /cards/{code}/terminate, or the card provider started closing the card. The card is cancelling: no more top-ups. You receive card.terminated once it is closed.
Triggered when: The card has been terminated and can no longer be used. Its remaining balance is returned to your cards_visa or cards_mastercard balance, minus the card provider fee and, if you requested the termination, the card termination fee of your plan; any top-up still in progress is refunded (see card.topup.failed). Use card_code, customer_code and your external_reference to update the right customer in your system. Extra fields: refunded_amount (credited to your balance), card_balance_at_closure, provider_fee, termination_fee.

Wallet events

Triggered when: A deposit has been received on the wallet of one of your customers. The net amount has been credited to the balance of this wallet.
customer_code and external_reference are null for a deposit sent directly to your former collection address (before October 22, 2026). In that case balance is the balance of that former collection account.Collect wallet: fee is always 0 and net_amount equals amount. balance is the balance right after the deposit: if it reaches $3, the whole balance is forwarded right away and you receive wallet.forward_completed.
Triggered when: A withdrawal from the wallet of one of your customers, requested with POST /wallets/{code}/withdrawals, has been sent on the blockchain.
Triggered when: A withdrawal that was never sent on the blockchain is cancelled by our team. The full amount, fees included, is credited back to the wallet. A temporary sending problem does not trigger this event: the withdrawal stays processing and is retried automatically.
The other fields are the same as in wallet.withdrawal_completed.
Triggered when: The balance of a collect wallet has been forwarded to its destination address (on Base, when the transaction is sent on the blockchain; on Solana, when it is confirmed).
Triggered when: A forward could not be completed automatically. Our team is notified and handles it; no action is needed on your side. You receive wallet.forward_completed once it is sent.
The other fields are the same as in wallet.forward_completed. A forward is never sent twice: while it is under_review, nothing is sent again automatically.
Triggered when: The destination address of a collect wallet has been changed with PATCH /wallets/{code}/destination. An email is also sent to the email address of your account.
If you did not make this change, set the right address again, regenerate your API keys, check your allowed IP addresses and contact hi@kemycard.com.

Virtual account events

Every virtual account event carries virtual_account_code, customer_code, external_reference and currency. See Create a virtual account for the statuses and List deposits for the deposit flow.
Triggered when: Your customer must accept the terms of our banking partner before the account can be opened. Send them to tos_url: they must accept the terms themselves. If you gave a tos_redirect_url, they are sent back to it afterwards. Sent once per account. The redirect is not a confirmation: wait for virtual_account.activated.
Triggered when: The account is open. The payload is the full virtual account, with deposit_instructions: the bank details to share with the payer.
Triggered when: The account was refused. The creation fee is refunded to your others ops balance.
Triggered when: The account was closed with POST /virtual-accounts/{code}/close. It no longer accepts deposits.
creation_fee_refunded is the creation fee when the account was closed before its bank details were issued, 0 otherwise.
Triggered when: A bank transfer has been received on the virtual account of one of your customers. It will now be converted to USDC.
Triggered when: The USDC of a deposit has arrived, the KemyCard fee has been taken, and the net amount has been credited (wallet destination) or sent on-chain and confirmed by the blockchain (external_address destination). Until the transaction is confirmed, the deposit stays sending.
Triggered when: The net amount of a deposit could not be sent to the external address (external_address destination), or the blockchain rejected the transaction. The funds did not leave. Our team is notified and retries the transfer.

Gift card events

Triggered when: A gift card order has been fulfilled successfully. The gift card code is available.
Triggered when: A gift card order has failed (product unavailable, provider error, etc.).
Triggered when: A failed gift card order has been refunded. The amount has been credited back to your ops balance.

Payout events

The data of every payout event is the payout object, the same as GET /payouts/{code}. The same events are sent for SEPA payouts (rail sepa) and ACH payouts to the United States (rail ach). For an ACH payout, received_currency is USD, amount_eur and exchange_rate are null, balance_type is others and the beneficiary shows account_number_masked and routing_number instead of iban_masked. See the Payouts guide. The examples below are SEPA payouts.
Triggered when: The payout has been sent to the bank. Status processing. With SEPA Instant, funds usually arrive within minutes. An ACH transfer can take a few business days.
Triggered when: The payout has been credited to the beneficiary’s bank. Status completed, completed_at is set.
Triggered when: The bank transfer could not be completed. Status failed. The refund to the balance that paid the payout (Payout SEPA, or Ops Others for ACH) follows automatically, with payout.refunded.
Triggered when: The amount and the fee of a failed payout (total_debited_usd) have been credited back to the balance that paid the payout (Payout SEPA, or Ops Others for ACH). failure_reason names that balance. Status refunded, refunded_at is set. This is also the case when the amount received of a renewed quote would be more than 1% lower than the quote you accepted.

Balance events

Triggered when: One of your ops balances is credited, either by a USDC (Solana) deposit confirmed on its deposit address, or by a KemyCard API gift card redeemed from your dashboard.USDC deposit:
Gift card redemption (same top-up fees as a USDC deposit, no on-chain fields):
The source field is only present for gift card redemptions. A gift card is issued for one specific ops balance and always credits that balance. gross_amount is the gift card value, fee the top-up fee of that balance and amount the net amount credited.
Triggered when: An automatic debit occurs on your ops balance — card creation, card top-up, card annual fee, plan payment, gift card purchase, etc. Sent for every paid operation.
Possible reason values:Additional fields (e.g. brand, customer_code, product, billing_cycle) vary depending on the reason.
Triggered when: Your ops balance drops below the threshold you configured (lowBalanceThreshold, default $100). This is triggered in two ways:
  • Real-time — immediately after a debit that pushes the balance below the threshold
  • Scheduled — every 4 hours, a CRON job checks all active partners
An alert email is also sent to your registered email address.
Balance types:

Signature verification

Every delivery includes these headers: How to verify:
1

Extract the timestamp and signature

Parse X-KemyCard-Signature: split by ,, extract t= and v1= values.
2

Compute expected signature

Concatenate {timestamp}.{raw_body} and compute HMAC-SHA256 using your webhook secret.
3

Compare signatures

Use constant-time comparison (e.g. crypto.timingSafeEqual in Node.js, hash_equals in PHP).
4

Reject old timestamps

If the timestamp is more than 5 minutes old, reject the request to prevent replay attacks.

Retry policy

If your endpoint doesn’t respond with a 2xx status code, we retry with exponential backoff: After 7 failed attempts, the delivery is marked as failed and no further retries are made.
If your endpoint accumulates 100 consecutive failures, it will be automatically deactivated. You can reactivate it via PATCH /webhooks/{code} with {"is_active": true}.
While your account is suspended because an ops balance is negative, webhooks keep being sent for 24 hours, then stop until the balance is regularized. Events of the cut period are not resent: re-synchronize by reading your transaction history through the API. See Negative balance and suspension.

Managing endpoints

The number of active endpoints depends on your plan: 1 on Découverte, 10 on Starter, Business and Premium. Creating an endpoint beyond this number returns 403 PLAN_LIMIT_REACHED. If your account returns to Découverte, your endpoints are kept but only the oldest one keeps working.

Update an endpoint

If you change the URL, we send a new ping to validate it. The update is rejected if the new URL doesn’t respond with 2xx.

Disable / re-enable an endpoint

Endpoints can never be deleted — only disabled. This preserves the delivery history.

Rotate the secret

If your secret is compromised, generate a new one immediately:
The old secret is invalidated instantly. Update your server code with the new secret before any pending deliveries arrive.

Test your endpoint

Send a manual ping to verify your endpoint is working:

View delivery history

Check the delivery status for a specific endpoint:
Each delivery shows: event type, status (delivered/failed/pending), HTTP response code, attempt number, duration, and idempotency key.

Best practices

Never trust a webhook payload without verifying the HMAC signature. This prevents attackers from sending fake events to your endpoint.
Store the X-KemyCard-Idempotency-Key header value and check it before processing. Due to retries, you may receive the same event multiple times. Idempotency keys let you safely deduplicate.
Process webhook events asynchronously. Return a 200 response immediately, then handle the event in a background job. If your endpoint takes too long (>10 seconds), the request will time out and trigger a retry.
Don’t use "*" unless you truly need every event. Subscribing to specific events reduces noise and unnecessary load on your server.
Check your webhook dashboard regularly. If you see failures, investigate and fix your endpoint before it reaches the 100-failure auto-deactivation threshold.
When rotating secrets, your server should temporarily accept both the old and new secret during the transition window.