Security Enhancement: Content-Type and inquiry_key Validation

December 7, 2025 · 9 min read

Technical Documentation Team

Effective December 7, 2025

We have implemented a security enhancement to strengthen our merchant transaction processing. This update improves our ability to detect and handle mismatched request formats and invalid parameter formats, helping maintain accurate and consistent transaction data.

What's Changed

As part of our ongoing security and data consistency improvements, we've enhanced validation for API requests. Some merchants may receive validation errors if their requests don't follow the proper format. If you follow our API technical documentation, your integration should work without issues.

🧪 Test Before Production

We've created a simulator to help you test these validations before they impact your production system:

Interactive Simulator UI - Test in your browser
API Endpoints - Integrate into your backend (see Testing Your Integration section below)

Important Note About idempotency_key

While this announcement focuses on Content-Type and inquiry_key validations deployed on December 7, 2025, we've also updated our documentation to clarify that the idempotency_key parameter (used in money transfer endpoints) follows the same character restrictions: only alphanumeric characters and hyphens are allowed. This is part of our API best practices and has been in effect. Please review your idempotency_key values to ensure compliance.

New Validation Rules

1. Content-Type Must Match Request Body Format

Your API requests must now have the Content-Type header properly matching the request body format:

✅ Valid Configurations

JSON Requests:

Content-Type: application/json

# Body must be valid JSON
{
  "bank_code": "bni",
  "account_number": "1234567890",
  "inquiry_key": "TRX-001"
}

Form-Encoded Requests:

Content-Type: application/x-www-form-urlencoded

# Body must be form-encoded
bank_code=bni&account_number=1234567890&inquiry_key=TRX-001

❌ Invalid Configurations

Setting Content-Type: application/json but sending form-encoded body
Setting Content-Type: application/x-www-form-urlencoded but sending JSON body
Missing or incorrect Content-Type header

2. inquiry_key Character Restrictions

The inquiry_key parameter now only accepts alphanumeric characters and hyphens (-).

✅ Valid inquiry_key Examples

# Alphanumeric with hyphens
inquiry_key=TRX-12345
inquiry_key=ORDER-123
inquiry_key=transaction_abc_123

❌ Invalid inquiry_key Examples

The following characters are no longer accepted:

Character	Example	Status
At sign `@`	`inv@456`	❌ Rejected
Underscore`_`	`inv_456`	❌ Rejected
Period `.`	`trx.789`	❌ Rejected
Hash `#`	`order#123`	❌ Rejected
Dollar `$`	`trx$456`	❌ Rejected
Other special symbols	`trx&123`, `inv%456`	❌ Rejected

Note: Only alphanumeric characters (A-Z, a-z, 0-9) and hyphens (-) are allowed.

Error Responses

If your request doesn't meet the new validation requirements, you will receive validation error responses:

Content-Type Mismatch Error

When the Content-Type header doesn't match the request body format:

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "attribute": "account_number",
      "code": 1001,
      "message": "Account number cannot be empty"
    },
    {
      "attribute": "bank_code",
      "code": 1001,
      "message": "Bank code cannot be empty"
    }
  ]
}

Note: This error appears when parameters cannot be parsed due to Content-Type mismatch, even though the parameters are actually present in the request.

Invalid inquiry_key Error

When the inquiry_key contains invalid characters:

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "attribute": "inquiry_key",
      "code": 1002,
      "message": "Inquiry key is invalid"
    }
  ]
}

Cause: The inquiry_key contains special characters other than alphanumeric and hyphens (e.g., @, ., #, _).

Invalid idempotency_key Error

When the idempotency_key contains invalid characters (applicable to money transfer endpoints):

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "attribute": "idempotency-key",
      "code": 1042,
      "message": "idempotency-key is invalid"
    }
  ]
}

Cause: The idempotency_key contains special characters other than alphanumeric and hyphens (e.g., @, ., #, _).

Migration Guide

Step 1: Review Your API Requests

Check all your API calls to Flip endpoints and ensure:

Content-Type header is set correctly:
- Using JSON? Set Content-Type: application/json
- Using form data? Set Content-Type: application/x-www-form-urlencoded
Request body matches the Content-Type:
- JSON header → JSON body
- Form header → Form-encoded body

Step 2: Update inquiry_key Format

Review all places where you generate or send inquiry_key values:

Before (may fail):

// ❌ Contains @ symbol
const inquiryKey = `invoice@${customerId}`;

// ❌ Contains period
const inquiryKey = `trx.${timestamp}`;

// ❌ Contains hash
const inquiryKey = `order#${orderId}`;

// ❌ Uses underscore
const inquiryKey = `invoice_${customerId}`;

After (valid):

// ✅ Uses hyphen
const inquiryKey = `order-${orderId}`;

// ✅ Alphanumeric only
const inquiryKey = `trx${timestamp}`;

Step 3: Review idempotency_key Format (Best Practice)

While the main focus of this update is on Content-Type and inquiry_key, we recommend also reviewing your idempotency_key values to ensure they follow the same character restrictions:

Recommended format:

// ✅ Best practice for idempotency_key
const idempotencyKey = `disb-${timestamp}`;
const idempotencyKey = `mt${transactionId}`;

// ❌ Avoid other special characters
const idempotencyKey = `disb@${timestamp}`; // Contains @
const idempotencyKey = `transfer.${userId}`; // Contains period
const idempotencyKey = `transfer_${userId}`; // Contains underscore

Step 4: Test Your Integration

After making the changes:

Test account inquiry requests with the new inquiry_key format
Verify your Content-Type headers match your request body format
Ensure you receive successful responses without validation errors
(Optional) Test money transfer requests with updated idempotency_key format

Testing Your Integration with the Simulator

We've created a comprehensive simulator to help you test these validation changes before they impact your production environment.

🧪 Interactive Simulator (Web UI)

Access our web-based simulator to test validation in your browser:

👉 Validation Simulator

The simulator provides:

Account Inquiry Testing: Test inquiry_key validation with various formats
Disbursement Testing: Test idempotency-key validation for money transfers
Special Disbursement Testing: Test with sender information
Real-time Validation: See validation errors instantly
Code Examples: Copy-paste ready code in multiple languages

How to use:

Visit the Validation Simulator
Select "Account Inquiry" from the endpoint dropdown
Enter an inquiry_key with special characters (e.g., INQ_12345)
Click "Test API" to see the validation error
Try with valid format (e.g., INQ-12345) to see success

🔌 API Simulator Endpoints (Direct Integration)

You can also test directly from your backend, or any HTTP client using this CURL:

Base URL:

https://asia-southeast2-flip-stg-pon-c820.cloudfunctions.net/flipCheckoutDemo/simulator

Available Endpoints:

1. Test Account Inquiry + inquiry_key Validation

# Valid inquiry_key
curl -X POST 'https://asia-southeast2-flip-stg-pon-c820.cloudfunctions.net/flipCheckoutDemo/simulator/account-inquiry' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'account_number=5465327020' \
  -d 'bank_code=bca' \
  -d 'inquiry_key=INQ-12345'

# Invalid inquiry_key (will return error 1002)
curl -X POST 'https://asia-southeast2-flip-stg-pon-c820.cloudfunctions.net/flipCheckoutDemo/simulator/account-inquiry' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'account_number=5465327020' \
  -d 'bank_code=bca' \
  -d 'inquiry_key=INQ@12345'

2. Test Disbursement + idempotency-key Validation

# Valid idempotency-key
curl -X POST 'https://asia-southeast2-flip-stg-pon-c820.cloudfunctions.net/flipCheckoutDemo/simulator/disbursement/create' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'idempotency-key: DISB-12345' \
  -d 'account_number=1122333300' \
  -d 'bank_code=bni' \
  -d 'amount=10000'

# Invalid idempotency-key (will return error 1042)
curl -X POST 'https://asia-southeast2-flip-stg-pon-c820.cloudfunctions.net/flipCheckoutDemo/simulator/disbursement/create' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'idempotency-key: DISB@12345' \
  -d 'account_number=1122333300' \
  -d 'bank_code=bni' \
  -d 'amount=10000'

Full API Documentation: See SIMULATOR_API_GUIDE.md for complete integration examples in Node.js, Python, PHP, Go, and more.

Integration Testing Example

// Test your error handling before production
async function testValidation() {
  // Test 1: Valid inquiry_key
  const validResponse = await fetch('https://asia-southeast2-flip-stg-pon-c820.cloudfunctions.net/flipCheckoutDemo/simulator/account-inquiry', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      account_number: '5465327020',
      bank_code: 'bca',
      inquiry_key: 'INQ-12345'
    })
  });
  console.log('Valid:', await validResponse.json());

  // Test 2: Invalid inquiry_key (should return error 1002)
  const invalidResponse = await fetch('https://asia-southeast2-flip-stg-pon-c820.cloudfunctions.net/flipCheckoutDemo/simulator/account-inquiry', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      account_number: '5465327020',
      bank_code: 'bca',
      inquiry_key: 'INQ@12345'  // Contains @ symbol
    })
  });
  const error = await invalidResponse.json();
  console.log('Invalid:', error);
  // Expected: { code: "VALIDATION_ERROR", errors: [{ attribute: "inquiry_key", code: 1002, ... }] }
}

Affected Endpoints

Content-Type Validation

The Content-Type validation applies to all API endpoints:

All disbursement/money transfer endpoints
All virtual account endpoints
All payment/accept payment endpoints
All inquiry endpoints
All other Flip API endpoints

Impact: Every API request must have a Content-Type header that matches the request body format.

inquiry_key Validation

The inquiry_key character restriction applies only to:

Account Inquiry API endpoint

Impact: The inquiry_key parameter in account inquiry requests must only contain alphanumeric characters and hyphens (-). Other API endpoints are not affected by this specific validation.

About idempotency_key (Documentation Update)

We've updated our API documentation to clarify that the idempotency_key parameter should follow the same best practices regarding character restrictions. This applies to money transfer endpoints:

Create Disbursement - Standard money transfer
Create Special Money Transfer - Special disbursement
Create Agent Disbursement - Agent-based disbursement
Create International Transfer - International remittance
Create B2B International Transfer - B2B international remittance

Note: While not part of the December 7, 2025 deployment, we recommend following the same character restrictions (alphanumeric and hyphens) for idempotency_key as a best practice.

Need more time to handle this changes?

If your system is not ready yet or experiencing validation errors with this update, please contact us to request temporary whitelisting while you prepare the migration.

To request whitelisting, contact:

Flip Support
Email: [email protected]
Subject: Request whitelist to bypass inquiry_key and Content-Type validation

Include in your request:

Business Id (optional)
Email account for Flip for Business
Reason for whitelisting
Expected timeline for migration

Why This Matters

This update is part of our ongoing commitment to:

Enhanced Security: Prevent request format vulnerabilities
Data Consistency: Ensure accurate transaction data processing
Better Validation: Detect and reject malformed requests early
API Reliability: Maintain high-quality API standards

If mismatches or invalid formats are detected, this is expected behavior under the enhanced validation rules.

Documentation Updates

Our API documentation has been updated to reflect these requirements. Please refer to:

Support

If you experience issues or have questions about this update:

Contact Support

Email: [email protected]
Subject Line: "Content-Type and inquiry_key Validation Enhancement Support"

Checklist for Merchants

Ensure your integration is compliant:

☑️ Verify Content-Type header matches request body format in all API calls
☑️ Update inquiry_key generation to use only alphanumeric and hyphen characters
☑️ Remove special characters (@, ., #, etc.) from inquiry_key values
☑️ Test with the Validation Simulator to verify your changes
☑️ Test account inquiry requests with updated inquiry_key format in sandbox
☑️ Review error handling for validation errors (codes 1002 and 1042)
☑️ (Optional) Update idempotency_key format to follow best practices
☑️ Update any stored inquiry_key patterns in your system
☑️ Run integration tests using the simulator API endpoints
☑️ Deploy updates to production
☑️ Monitor for validation errors after deployment

Thank you for your cooperation in maintaining secure and reliable API integrations with Flip for Business!

What's Changed​

🧪 Test Before Production​

New Validation Rules​

1. Content-Type Must Match Request Body Format​

✅ Valid Configurations​

❌ Invalid Configurations​

2. inquiry_key Character Restrictions​

✅ Valid inquiry_key Examples​

❌ Invalid inquiry_key Examples​

Error Responses​

Content-Type Mismatch Error​

Invalid inquiry_key Error​

Invalid idempotency_key Error​

Migration Guide​

Step 1: Review Your API Requests​

Step 2: Update inquiry_key Format​

Step 3: Review idempotency_key Format (Best Practice)​

Step 4: Test Your Integration​

Testing Your Integration with the Simulator​

🧪 Interactive Simulator (Web UI)​

🔌 API Simulator Endpoints (Direct Integration)​

1. Test Account Inquiry + inquiry_key Validation​

2. Test Disbursement + idempotency-key Validation​

Integration Testing Example​

Affected Endpoints​

Content-Type Validation​

inquiry_key Validation​

About idempotency_key (Documentation Update)​

Need more time to handle this changes?​

Why This Matters​

Documentation Updates​

Support​

Contact Support​

Checklist for Merchants​