Skip to main content

MoneyTransfer: Transaction ID Format Change

· 9 min read
Flip Technical Team
Flip Technical Team
Technical Documentation Team

Action Required by December 8, 2025

A quick reminder that the new 19-digit Money Transfer Transaction ID format will go live on December 8, 2025 - approximately 1.5 months from now.

🧪 Test the New Format Now!​

We've created an interactive simulator to help you test and prepare for the new 19-digit ID format:

👉 Access MT ID Simulator

  • ✅ Test API endpoints with 19-digit IDs
  • ✅ Send test callbacks to your webhook
  • ✅ Validate your data type compatibility
  • ✅ Get code examples for your integration

What's Changing​

The Money Transfer (Disbursement) transaction ID response format is being updated from Integer to BigInteger (19-digit format).

Current Format​

{
  "id": 123456789  // Integer format
}

New Format (After December 8, 2025)​

{
  "id": 1234567890123456789  // BigInteger format (19 digits)
}

Do You Need to Take Action?​

✅ You Can Safely Ignore This Change If:​

Your system is already prepared if you meet any of the following conditions:

  1. Using String/VARCHAR for IDs

    • Your database stores transaction IDs as VARCHAR, TEXT, or STRING type
    • Your application code treats IDs as strings

  2. Using BigInteger/BIGINT Data Types

    • Your database column type is BIGINT, LONG, or equivalent 64-bit integer
    • Your application uses BigInteger, Long, Int64, or similar data types

  3. System Handles 64-bit Integers

    • Your system architecture already supports large numbers (64-bit integers)
    • You can store numbers up to 9,223,372,036,854,775,807

If any of the above applies to you, no action is needed. Your integration will continue to work seamlessly.

⚠️ You MUST Take Action If:​

  • Using INT, INTEGER, or 32-bit integer types in your database
  • Using int, Integer, int32, or similar in your application code
  • Your system has a limitation on integer size (< 19 digits)
  • Using JavaScript, TypeScript, or Node.js (see below — silent rounding risk)
  • Unsure about your current implementation

⚠️ Language-Specific Considerations​

Different programming languages handle large integers differently. This section highlights the most important pitfalls to watch out for.

🚨 JavaScript / TypeScript / Node.js (Critical)​

JavaScript's Number type is a 64-bit floating-point (IEEE 754), which can only safely represent integers up to Number.MAX_SAFE_INTEGER = 9,007,199,254,740,991 (16 digits). Any 19-digit ID parsed with the default JSON.parse() will be silently rounded — no error, no warning, just wrong data.

// ❌ This silently corrupts the ID
const response = JSON.parse('{"id": 1234567890123456789}');
console.log(response.id); // 1234567890123456800 — last digits changed!

// ✅ Recommended: use a JSON library that preserves big numbers
// npm install json-bigint
const JSONbig = require('json-bigint')({ storeAsString: true });
const response = JSONbig.parse('{"id": 1234567890123456789}');
console.log(response.id); // "1234567890123456789" — safe as string

Why this is dangerous: The API call succeeds with HTTP 200, but the stored ID is wrong. You won't notice until you try to reconcile the transaction with Flip and the IDs don't match.

Recommended approach:

  • Use json-bigint (with storeAsString: true) or similar library
  • Treat all transaction IDs as strings throughout your application
  • Never compare IDs using === after default JSON parsing

Java / Kotlin​

  • ❌ Avoid: int (32-bit, max ~2.1 billion)
  • ✅ Use: long (64-bit, max ~9.2 quintillion — handles 19 digits) or java.math.BigInteger
  • Jackson/Gson default to long for whole numbers within range, but verify your POJO field types

Python​

  • ✅ No action needed: Python's int is arbitrary-precision. 19-digit IDs work natively with json.loads().
  • Just confirm your database column type is BIGINT if you persist the ID.

Go​

  • ❌ Avoid: int32
  • ✅ Use: int64 or string. encoding/json decodes JSON numbers into float64 by default — declare your struct field as int64 or use json.Number to preserve precision.

PHP​

  • 64-bit builds (most modern Linux/macOS deployments): native int handles 19 digits — no action needed.
  • 32-bit builds: int overflows at ~2.1 billion → cast IDs to string with JSON_BIGINT_AS_STRING: 
    $response = json_decode($body, true, 512, JSON_BIGINT_AS_STRING);

.NET / C#​

  • ❌ Avoid: int (Int32)
  • ✅ Use: long (Int64) or System.Numerics.BigInteger
  • System.Text.Json deserializes whole numbers into long if the target property type is long.

Ruby​

  • ✅ No action needed: Ruby's Integer is unbounded. Standard JSON.parse handles 19-digit IDs correctly.

📢 Important: Notify Your Sales Team​

Once your system is ready for the new ID format, please inform your Flip Sales team.

We want to ensure your system is fully prepared and that this change will not impact your operations. Your Sales team will:

  • Confirm your readiness status
  • Provide additional support if needed
  • Track the migration progress
  • Help coordinate if any special considerations

Contact your dedicated Flip Sales representative or email [email protected] with:

  • Your company name
  • Your email accoount Flip for Business
  • Confirmation that your system has been updated for this changes
  • Any concerns or questions about the migration

This helps us ensure a smooth transition for all merchants and allows us to provide targeted support where needed.

Why This Change?​

This upgrade is part of our new architecture deployment that will:

  • Support higher transaction volumes
  • Improve system scalability
  • Enhance data integrity
  • Prevent ID collision as our platform grows

⚠️ Action Required​

All API merchants must update their systems before December 8, 2025 to avoid service disruptions.

Required Changes​

  1. Update Data Storage

    • Change database column type from INT to BIGINT or VARCHAR
    • Ensure your database can store 19-digit numbers

  2. Update Application Code

    • Store Money Transfer IDs as BigInteger or String (not Integer)
    • Review any code that parses or processes transaction IDs
    • Update any ID validation logic

  3. Update API Integration

    • Ensure your API client can handle 19-digit integers

Affected Endpoints​

The following endpoints will return IDs in the new format:

Please review the following documentation pages for detailed information about the affected endpoints and integration:

API Reference:

Integration Guides:

These pages contain the current API specifications and will be updated to reflect the new ID format once the change is deployed on December 8, 2025.

Testing Your Integration​

🧪 Test with Our Simulator​

To help you prepare for the new ID format, we've created a Money Transfer ID Simulator where you can test the new 19-digit format before the December 8, 2025 rollout.

👉 Access the MT ID Simulator

The simulator provides:

  1. Live API Testing

    • Test endpoints that return responses with new 19-digit BigInteger IDs
    • Call directly from your backend to verify integration
    • No authentication required for testing

  2. Available Endpoints

    • Regular Disbursement: Test standard money transfer creation
    • Special Disbursement: Test special money transfer with sender information
    • List & Get by ID: Test retrieval operations with new ID format

  3. Callback/Webhook Testing

    • Send test callbacks to your webhook URL
    • Verify your system can receive and process 19-digit IDs
    • Uses actual Flip callback format (application/x-www-form-urlencoded)
    • Test with different transaction statuses (PENDING, DONE, CANCELLED)

  4. Data Type Validation

    • Check if your current database data type can handle 19-digit numbers
    • Get recommendations for required changes
    • Interactive compatibility checker

Code Examples​

The simulator provides ready-to-use code examples in multiple languages:

  • cURL commands for quick testing
  • Node.js/JavaScript integration examples
  • Python integration examples

👉 Start Testing Now

  1. Update Data Types First

    • Modify your database schema to support BIGINT or VARCHAR for ID fields
    • Update your application code to handle BigInteger or String types
    • Ensure your system can store and process 19-digit numbers

  2. Test with Simulator

    • Use the API endpoints to test your backend integration
    • Verify your system can parse 19-digit IDs correctly
    • Test your webhook handler with the callback simulator
    • Ensure your UI can display long transaction IDs

  3. Code Review & Validation

    • Review all code that handles transaction IDs
    • Check for any hardcoded assumptions about ID length
    • Verify that your parsing logic can handle larger numbers
    • Update any display or formatting logic

  4. End-to-End Testing

    • Test complete transaction flows with the new ID format
    • Verify database storage and retrieval
    • Check reporting and analytics systems
    • Validate any third-party integrations

What to Verify​

Before December 8, 2025, ensure you have:

  • ✅ Updated database schema to support 19-digit integers
  • ✅ Modified application code to use BigInteger/String for IDs
  • ✅ Reviewed all ID parsing and validation logic
  • ✅ Updated webhook/callback handling code
  • ✅ Verified ID display in your UI can handle longer numbers
  • ✅ Tested database storage and retrieval with large numbers
  • ✅ Tested your integration using the MT ID Simulator
  • ✅ Verified your webhook can receive callbacks with 19-digit IDs

Potential Issues if Not Updated​

If you don't update your systems by December 8, 2025, you may experience:

  • ❌ ID Truncation: Transaction IDs may be truncated, causing data loss
  • ❌ Mismatched Data: Unable to match transactions between systems
  • ❌ Failed Queries: Queries using truncated IDs will fail
  • ❌ Integration Errors: API responses may fail to parse correctly
  • ❌ Database Errors: Storage failures due to overflow

Timeline​

  • October 22, 2025: Announcement published
  • November 2025: Grace period for testing and updates
  • December 8, 2025: New format goes live

Need Help?​

Our technical team is here to assist you with the migration:

Support Resources​

Please contact our technical team at [email protected] with subject line: "MT ID Format Migration Support"

Preparation Checklist​

Use this checklist to ensure you're ready:

  1. ☑️ Review current implementation of transaction ID handling
  2. ☑️ Use the Data Type Validator to check compatibility
  3. ☑️ Update database schema to support BigInteger or VARCHAR
  4. ☑️ Modify application code to handle 19-digit IDs
  5. ☑️ Test API integration using the MT ID Simulator
  6. ☑️ Test your webhook using the Callback Simulator
  7. ☑️ Verify webhook handling with large IDs
  8. ☑️ Update any stored procedures or queries
  9. ☑️ Test end-to-end transaction flow with simulator
  10. ☑️ Document changes in your system
  11. ☑️ Deploy changes to production before December 8, 2025
  12. ☑️ Notify your Flip Sales team that you're ready

Thank you for your cooperation in ensuring a smooth transition. We appreciate your partnership with Flip for Business!

Did this answer your question?