Accept Payment: Link ID Format Change

Action Required before April 10, 2026

Our system now migrating to 19-digit IDs. All merchants are expected to be ready by April 10, 2026, but you can start the rollout immediately if your system is already compatible by contacting your sales representative or our Support Team

---

What's Changing

The link_id field in API responses/requests and bill_link_id field in callback payloads will change from a variable-length value to exactly 19 digits.

Field Changes

Field	Location	Before	After
link_id	API Response	1-10 digits	Exactly 19 digits
link_id	URL Path Parameter	1-10 digits	Exactly 19 digits
bill_link_id	Callback Payload	1-10 digits	Exactly 19 digits

Format Details

Attribute	Before	After
Type	Integer	Integer
Format	Sequential auto-increment	Timestamp-based unique ID
Length	1-10 digits (variable)	Exactly 19 digits
Example	1797	2502091430251230005

Current Format

{
  "link_id": 1797,  // Variable length (1-10 digits)
  "bill_link_id": 1797
}

New Format

{
  "link_id": 2502091430251230005,  // Fixed 19 digits
  "bill_link_id": 2502091430251230005
}

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 link 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). The new 19-digit link_id / bill_link_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('{"link_id": 2502091430251230005}');
console.log(response.link_id); // 2502091430251230000 — 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('{"link_id": 2502091430251230005}');
console.log(response.link_id); // "2502091430251230005" — 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 payment link with Flip and the IDs don't match.

Recommended approach:

• Use json-bigint (with storeAsString: true) or similar library
• Treat link_id / bill_link_id as strings throughout your application
• Update TypeScript interfaces from number to string
• Use VARCHAR in your database (not numeric types that might auto-convert)
• 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 are needed

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

• Your company name
• Your email account for 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 infrastructure enhancement that will:

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

⚠️ Action Required

All API merchants must update their systems expected before April 10, 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 19-digit numbers

2. Update Application Code

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

3. Update API Integration

   • Ensure your API client can handle 19-digit integers
   • Update URL path parameter handling for bill_id

Affected Endpoints

The following endpoints will return IDs in the new format:

V2 API Endpoints

• Create Bill - link_id in response
• Get All Bills - link_id in response
• Get Bill / Payment Link - bill_id as path parameter
• Edit Bill / Payment Link - bill_id as path parameter
• Get Payment - bill_id as path parameter, link_id in response
• Get All Payment - link_id in response

V3 API Endpoints

• Create Bill - link_id in response
• Get All Bills - link_id in response
• Get Bill / Payment Link - bill_id as path parameter
• Edit Bill / Payment Link - bill_id as path parameter
• Get Payment - bill_id as path parameter, link_id in response
• Get All Payment - link_id in response

Callback

• Accept Payment Callback - bill_link_id in payload

Related Documentation

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

API Reference:

• Accept Payment API Reference
• V2 Integration Guide
• V3 Checkout Integration
• Direct API Integration

These pages contain the current API specifications and will be updated to reflect the new ID format once the change is deployed on April 10, 2026.

Testing Your Integration

Recommended Testing Approach

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 Sample Data

   • Create test records with 19-digit IDs (e.g., 2502091430251230005)
   • Verify your system can parse and store these values correctly
   • Test all API integrations with large ID values
   • JavaScript developers: Test that typeof linkId === "string" after parsing API responses

3. Code Review & Validation

   • Review all code that handles link IDs or bill link 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 payment flows with the new ID format
   • Verify database storage and retrieval
   • Check reporting and analytics systems
   • Validate webhook/callback handling

What to Verify

Before April 10, 2026, ensure you have:

• ✅ Updated database schema to support 19-digit integers (use VARCHAR for JavaScript/Node.js)
• ✅ Modified application code to use BigInteger/String for IDs
• ✅ JavaScript/Node.js: Changed all link_id and bill_link_id to String type (not Number)
• ✅ JavaScript/Node.js: Updated TypeScript interfaces from number to string
• ✅ JavaScript/Node.js: Verified API responses return IDs as strings in JSON (not numbers)
• ✅ JavaScript/Node.js: Removed all parseInt(), Number(), or numeric parsing of these 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 all affected API endpoints with 19-digit values
• ✅ Verified callback payload processing

Potential Issues if Not Updated

If you don't update your systems by April 10, 2026, you may experience:

• ❌ ID Truncation: Link IDs may be truncated, causing data loss
• ❌ JavaScript Integer Overflow: Numbers silently lose precision (19 digits → 16 digits)
• ❌ Mismatched Data: Unable to match payments between systems due to corrupted IDs
• ❌ Failed Queries: Queries using truncated IDs will fail
• ❌ Integration Errors: API responses may fail to parse correctly
• ❌ Database Errors: Storage failures due to overflow
• ❌ Callback Failures: Unable to process payment callbacks correctly
• ❌ Silent Data Corruption: JavaScript may not throw errors, just silently corrupt the ID values

Timeline

• February 11, 2026: Announcement published
• February - April 2026: Grace period for testing and updates
• April 10, 2026: All merchants are expected to comply with this change
• Rollout: We will proceed with the rollout for merchants who have confirmed compatibility and do not require any adjustments on merchant end

Need Help?

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

Support Resources

• Email: [email protected]
• Documentation: Accept Payment Integration Guide
• API Reference: Accept Payment API

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

Preparation Checklist

Use this checklist to ensure you're ready:

General Checklist (All Languages)

1. ☑️ Review current implementation of link ID handling
2. ☑️ Identify all database tables storing link_id or bill_link_id
3. ☑️ Update database schema to support BigInteger or VARCHAR
4. ☑️ Modify application code to handle 19-digit IDs
5. ☑️ Test API integration with sample 19-digit values
6. ☑️ Test callback handling with large IDs
7. ☑️ Update any stored procedures or queries
8. ☑️ Verify URL path parameter handling
9. ☑️ Test end-to-end payment flow
10. ☑️ Document changes in your system
11. ☑️ Deploy changes to production before April 10, 2026
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!