Crypto Utilities

The SDK exports its crypto primitives directly, useful when you need to verify signatures server-side or implement gateway integration in a language other than Node.js.

encrypt(payload, keyHex, aad)

Encrypt a JSON payload using AES-256-GCM.

const { encrypt } = require('@bucksbox/sdk');

const { ciphertext, iv, tag } = encrypt(
  { amount: 500 },
  '0102030405...64hexchars',
  `${clientId}.${timestamp}`
);

// Send as:
// Body:    { payload: ciphertext }
// Headers: X-IV: iv, X-Tag: tag

Returns: { ciphertext: string, iv: string, tag: string } — all base64

decrypt(ciphertextB64, ivB64, tagB64, keyHex, aad)

Decrypt a gateway response. Throws if the GCM auth tag is invalid.

const { decrypt } = require('@bucksbox/sdk');

const plaintext = decrypt(
  responseBody.payload,
  response.headers['x-iv'],
  response.headers['x-tag'],
  aesKeyHex,
  `${clientId}.${response.headers['x-timestamp']}`
);

const data = JSON.parse(plaintext);

checksum(timestamp, clientId, rawBody, secret)

Compute the HMAC-SHA256 X-Checksum header value.

const { checksum } = require('@bucksbox/sdk');

const cs = checksum(
  Math.floor(Date.now() / 1000),  // number
  'your-client-id',
  JSON.stringify(body),
  'your-hmac-secret'
);

// Set header: X-Checksum: cs

Canonical string: "<timestamp>\n<clientId>\n<rawBody>"