Skip to main content

International Transfer: Transaction ID Format Change

· 8 min read
Flip Technical Team
Flip Technical Team
Technical Documentation Team

Action Required by June 20, 2026

The new 18-digit International Transfer Transaction ID format will go live on June 20, 2026. Please make sure your systems are ready before that date to avoid service disruptions.

What's Changing​

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

Current Format​

{
  "id": 11  // Integer format
}

New Format (After June 20, 2026)​

{
  "id": 123456789012345678  // BigInteger format (18 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 (< 18 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 18-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": 123456789012345678}');
console.log(response.id); // 123456789012345680 — last digits changed!

// ✅ Option 1: Use BigInt with a reviver (Node 10.4+, modern browsers)
const response = JSON.parse(
  '{"id": 123456789012345678}',
  (key, value) => key === 'id' && typeof value === 'number' ? BigInt(value) : value
);
// Note: BigInt won't help if value already lost precision before reviver — use option 2 for safety

// ✅ Option 2: Use a JSON library that preserves big numbers
// npm install json-bigint
const JSONbig = require('json-bigint')({ storeAsString: true });
const response = JSONbig.parse('{"id": 123456789012345678}');
console.log(response.id); // "123456789012345678" — 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 18 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. 18-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 18 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 18-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 account Flip for Business
  • Confirmation that your system has been updated for this change
  • 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 June 20, 2026 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 18-digit numbers

  2. Update Application Code

    • Store International 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 18-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 June 20, 2026.

Testing Your Integration​

  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 18-digit numbers

  2. 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

  3. 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 June 20, 2026, ensure you have:

  • ✅ Updated database schema to support 18-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

Potential Issues if Not Updated​

If you don't update your systems by June 20, 2026, 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​

  • May 14, 2026: Announcement published
  • May – June 2026: Grace period for testing and updates
  • June 20, 2026: 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: "International Transfer ID Format Migration Support"

Preparation Checklist​

Use this checklist to ensure you're ready:

  1. ☑️ Review current implementation of transaction ID handling
  2. ☑️ Update database schema to support BigInteger or VARCHAR
  3. ☑️ Modify application code to handle 18-digit IDs
  4. ☑️ Verify webhook handling with large IDs
  5. ☑️ Update any stored procedures or queries
  6. ☑️ Test end-to-end transaction flow
  7. ☑️ Document changes in your system
  8. ☑️ Deploy changes to production before June 20, 2026
  9. ☑️ 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?