Bank API Integration Checklist: AES-256-GCM Encryption and HMAC Signing

Why bank integrations are different

Bank APIs rarely accept plain JSON. Requests are usually encrypted, signed and tied to a timestamp, and responses come back encrypted too. A single wrong byte gives you a generic error with no hint about what went wrong.

1. Confirm the exact key format

Check whether the key is shared as raw bytes, hex or Base64, and decode it to exactly 32 bytes for AES-256. Many failures start with a key that was used as a text string instead of decoded bytes.

2. Get the IV and tag layout right

AES-GCM needs an IV (often 12 bytes) and produces an authentication tag (usually 16 bytes). Confirm with the bank how they expect these packed: IV first, tag at the end, everything Base64-encoded together, or sent as separate fields.

3. Sign exactly what the bank signs

HMAC-SHA256 has to be calculated over the exact string the bank expects: sometimes the encrypted payload, sometimes the plain JSON, sometimes fields joined in a fixed order. Match whitespace, field order and encoding character for character.

4. Log safely in UAT

Log the plaintext request, the encrypted payload, the signature and the raw response in UAT so you can compare them with the bank's sample values. Remove sensitive logs before production.

5. Plan for status enquiry

Payouts and beneficiary requests are not always final immediately. Build an enquiry job that checks pending records and updates their status, so your records always match the bank's.

Working on a bank or AEPS integration that keeps returning errors? I have debugged these in UAT and can help you get to production.