Integrity Checksum

Generate security checksums to verify payment integrity

Overview

The IntegrityChecksum class generates SHA-256 hashes to verify the integrity and authenticity of payment requests. Checksums help prevent tampering and ensure that payment data has not been modified during transmission.

For detailed information about checksums, see the Flutterwave Checksum Documentation.

Class: IntegrityChecksum

Method: integrityChecksum()

Generates a SHA-256 hash of the payment parameters combined with your secret key.

Returns: String - Base64-encoded SHA-256 hash

Properties

All properties must be set before calling integrityChecksum():

Property	Type	Description
amount	String	Payment amount
payment_method	String	Payment method (e.g., “both”, “card”, “account”)
custom_description	String	Custom payment description
custom_logo	String	URL to your custom logo
country	String	Country code (e.g., “NG”)
currency	String	Currency code (e.g., “NGN”)
customer_email	String	Customer’s email address
customer_firstname	String	Customer’s first name
customer_lastname	String	Customer’s last name
customer_phone	String	Customer’s phone number
txref	String	Your unique transaction reference

Usage Example

Setter Methods

All setter methods support method chaining and return the IntegrityChecksum instance:

Payment Details

Customer Information

Customization

How It Works

Checksum Generation Process

1. Parameter Collection: All payment parameters are collected into a HashMap
2. Key Sorting: Parameter keys are sorted alphabetically
3. Concatenation: Values are concatenated in sorted key order
4. Secret Addition: Your secret key is appended to the concatenated string
5. Hashing: The resulting string is hashed using SHA-256
6. Encoding: The hash is Base64-encoded for transmission

The checksum is generated by sorting all parameters alphabetically by key, concatenating their values, appending your secret key, and creating a SHA-256 hash.

When to Use Checksums

Use integrity checksums when:

• Hosted Payment Pages: Verifying that payment page parameters haven’t been tampered with
• Webhook Validation: Confirming that webhook notifications are from Flutterwave
• Payment Verification: Ensuring payment requests match expected values
• Dispute Resolution: Providing proof of original transaction parameters
• Compliance: Meeting security audit requirements

Always validate checksums on your server side. Never rely solely on client-side validation.

Security Considerations

Best Practices

• Generate on Server: Always generate checksums on your backend server
• Never Expose Secret Key: Keep your secret key secure and never include it in client-side code
• Validate Responses: Verify checksums on all incoming webhooks and callbacks
• Use HTTPS: Always transmit checksums over secure connections
• Store Securely: If logging checksums, ensure logs are secured and encrypted

Common Pitfalls

• Parameter Mismatch: Ensure all parameters used in checksum match the actual payment request
• Key Ordering: The library handles key sorting automatically, but be aware of this when debugging
• Encoding Issues: Use UTF-8 encoding consistently
• Missing Parameters: All required parameters must be set before generating the checksum

Payment Method Values

Common payment_method values:

• "card" - Card payments only
• "account" - Bank account payments only
• "both" - Both card and account payments
• "ussd" - USSD payments
• "mobilemoney" - Mobile money payments

Using "both" allows customers to choose their preferred payment method on the payment page.

Example: Full Payment Flow with Checksum

Verification

When receiving webhooks or payment callbacks from Flutterwave:

1. Extract the payment parameters from the response
2. Generate a checksum using the same parameters
3. Compare your generated checksum with the one provided by Flutterwave
4. Only process the payment if the checksums match

Critical: Always regenerate and verify checksums on your server when receiving payment notifications. This prevents fraudulent payment confirmations.

Next Steps

Transaction Verification

Verify payment status securely

Encryption

Learn about payment encryption

Error Handling

Review error handling strategies

Configuration

Secure your API credentials