Crypto Payment Gateway Security Checklist: 2FA, Webhooks and Custody

What security features should a crypto payment gateway have?

A crypto payment gateway should help you secure four layers: your account, with two-factor login and a list of active sessions; your API keys, kept on your server and easy to revoke; your webhooks, signed so you can prove they came from the gateway; and your funds, paid to a wallet you control or held so the provider cannot move them alone. Here is a checklist for each layer, with how to do it on BlockBee.

On BlockBee, each layer has a matching feature: authenticator-app and FIDO WebAuthn 2FA, key revocation, RSA-signed webhooks, and forwarding to your own address or a Self-Custodial Wallet secured with TSS.

How do you secure the account?

Start with the login, because whoever controls the dashboard controls your settings. In February 2024 BlockBee announced new two-factor authentication (2FA) options: time-based one-time passwords (TOTP) from an authenticator app, and the FIDO WebAuthn standard, which works with devices such as FaceID, TouchID and YubiKey. The same announcement added a view of all active sessions in the Security tab, where you can close any session you no longer need or don't recognize.

• Turn on 2FA, with an authenticator app, a security key or biometrics.
• Review active sessions now and then, and close any you don't recognize.
• Don't share logins. BlockBee's Terms make you responsible for securing your account, ask you not to share your credentials, and ask you to report any unauthorized use as soon as possible. Our guide to support channels and hours lists how to reach BlockBee.

How should you handle API keys?

An API key is a password for your integration. BlockBee's authentication docs say to never expose it in client-side code or public repositories, to use HTTPS, to rotate keys periodically and, if a key is compromised, to revoke it on the API Keys page and generate a new one. Keep keys out of callback URLs and logs too. BlockBee also accepts the key in an apikey header, which keeps it out of URLs that end up in logs.

BlockBee issues two kinds of key:

• V1 is for receiving payments. BlockBee receives the funds and forwards them to the wallet set in your dashboard, and resetting the key does not affect your funds.
• V2 adds the Self-Custodial Wallet and payouts. When you create it, BlockBee also generates a Recovery Key, which you need to regenerate the API key if you lose it.

Store the V2 key and its Recovery Key somewhere safe. If you lose both, the Self-Custodial Wallet's funds become permanently inaccessible, and BlockBee cannot recover them. Guard a V2 key like a wallet key: BlockBee's announcement of the wallet says payouts need "just your API key". The docs say to stay on V1 if you only need to receive payments and are fine with BlockBee receiving funds before forwarding them.

How do you make sure a webhook really came from the gateway?

Your webhook endpoint is public, so anyone can send it a fake "payment received" message. Use these checks together:

1. Verify the signature. BlockBee signs every webhook with RSA SHA256 (PKCS1v15 padding). The base64-encoded signature arrives in the x-ca-signature header; check it against BlockBee's public key at https://api.blockbee.io/pubkey/. For GET requests the full URL is signed; for POST requests, the raw body.
2. Add a nonce. BlockBee's docs suggest adding an unguessable value, unique to each payment, to your webhook URL (callback in the Custom Payment Flow, notify_url in Checkout and deposits) and storing it. BlockBee returns it unchanged, so you can reject any webhook whose value you don't recognize. Use it with signature checks, not instead of them.
3. Process each uuid once. BlockBee retries failed deliveries, so the same webhook can arrive more than once.
4. Use HTTPS. BlockBee requires your endpoint to be publicly reachable over HTTPS.
5. Allowlist the callback IPs if your firewall needs it. BlockBee's docs, checked on 26 October 2026, list 51.77.105.132 and 135.125.112.47. These have changed before: in January 2025 BlockBee announced it was replacing 145.239.119.223 with 51.77.105.132, so check the docs before you change a firewall rule.

Also match each webhook's amount, coin and order against what your system created. BlockBee's signature verification guide has example code, and our webhooks guide covers the full handler.

Who holds the funds, and why does it matter for security?

Custody decides what an attacker would go after. With a custodial gateway, your money sits in the provider's wallets, and our guide to custodial vs non-custodial gateways notes that attackers "may target dashboard credentials, API keys, or withdrawal settings".

BlockBee forwards instead. Each on-chain payment goes to your address once it confirms; Bitcoin Lightning payments, available through Checkout and the Point of Sale (PoS) only, settle once a day at 00:00 UTC. BlockBee's quickstart asks you to configure a receiving address. Keep your seed phrase private; protecting it is your job.

For payouts, the Self-Custodial Wallet is secured with TSS, so BlockBee cannot move funds without your API key. The system creates three key shares and needs at least two to sign: BlockBee holds one, and you hold two, the API Key V2 and the Recovery Key. That is why losing both makes the funds permanently inaccessible.

Security checklist

Frequently asked questions

Does BlockBee support two-factor authentication?

Yes. In February 2024 BlockBee announced TOTP through authenticator apps and FIDO WebAuthn, which works with devices such as FaceID, TouchID and YubiKey.

How do I verify a BlockBee webhook?

Check the base64 signature in the x-ca-signature header against BlockBee's public key at https://api.blockbee.io/pubkey/, using RSA SHA256. Reject the request if the check fails.

What should I do if my API key leaks?

Revoke it on the API Keys page, generate a new one and update your server. Act at once if it is a V2 key, because payouts need only that key.

Can BlockBee move funds in my Self-Custodial Wallet?

Not on its own. The wallet is secured with TSS, so BlockBee cannot move funds without your API key: signing needs two of three key shares, and BlockBee holds one.

Is a non-custodial crypto payment gateway more secure?

It reduces the risk that a processor controls or freezes merchant funds, but shifts responsibility to the business. Our custodial guide says a non-custodial setup is safer "only if the merchant has strong wallet security, access controls, backups, and reconciliation processes".

To set up 2FA and your keys, create a BlockBee account and work through the checklist above.