Skip to main content

Payment Callback

Overview​

The possible values for status are COMPLETED and FAILED

the key field that you set when you create a payment intent.

Response:
{
  "reference": "1cbfffbc-b365-45f6-9e5d-13e445c125cd",
  "status": "COMPLETED",
  "payload": {
    "billingAddress": {
      "firstName": "",
      "lastName": "",
      "address1": "",
      "locality": "",
      "administrativeArea": "",
      "postalCode": "",
      "country": "",
      "email": "",
      "phoneNumber": ""
    }
  },
  "amount": 1,
  "key": "",
  "currency": "KES",
  "provider": "MPESA",
  "date": "2025-02-03T13:49:46.000Z"
}

Verifying Webhook Signatures​

Little Pay Gateway uses asymmetric signing (RSA-SHA256) to ensure the authenticity and integrity of the callbacks sent to your server.

Security Headers​

Every webhook request includes two security headers:

  • X-LittlePay-Signature: A Base64-encoded RSA-SHA256 signature.
  • X-LittlePay-Timestamp: The UNIX timestamp (in seconds) when the signature was generated.

Signature Generation​

The signature is generated by signing a string composed of the timestamp and the JSON payload, joined by a period (.):

data_to_verify = timestamp + "." + JSON.stringify(payload)

Little Pay Public Key​

Use the following public key to verify the signatures:

Public Key
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAlU1L1fPzOO9Y3qFsP9K+
0iqCrN9xpDf/SG7a9O2Ma8mJSpvxpBq2lyjP0ncJiBCqgjMEIQIqWr4fbG7gErJp
MuKobiuGo9zS+CpjCY9tJxQgfx7fAGkL1sKN0E1UR9NqQmIAOEfPLCEbIRDC6n0F
1wpTEPiixmdAsJKm1aWlftubOBQjMlJucnksoXK7LHd5Tc6Pne6UhFNgt24Nt2Tu
zYKeWVtqnlP3cw66FVytrPsynQuVN4s7iQai0HxD4loEuX19hrT2AAFZT5P6xRac
wzb/eBPp3yAa/96JFkG3AcUVrjtHlltNWQ9aWvbA9Qx2BNEEmhkzdWfN/ARwv4Wh
NQIDAQAB
-----END PUBLIC KEY-----

Verification Examples​

const crypto = require('crypto');

function verifyWebhook(payload, signature, timestamp, publicKey) {
  const dataToVerify = \`\${timestamp}.\${JSON.stringify(payload)}\`;
  
  const verify = crypto.createVerify('SHA256');
  verify.update(dataToVerify);
  verify.end();

  return verify.verify(publicKey, signature, 'base64');
}
Replay Attacks

The X-LittlePay-Timestamp header is provided to help prevent replay attacks. We recommend verifying that the timestamp is recent (e.g., within the last 5 minutes) before processing the webhook.