Foreign ID
A foreign ID is a unique identifier provided by your system to reference objects such as invoices, customers, payments, etc. within Mercoa. Unlike platform-generated IDs, foreign IDs allow you to map your internal records to Mercoa platform objects for easier integration and reconciliation.
API Usage
You can provide foreign IDs when creating, retrieving, or updating objects via supported API endpoints. The following object types support foreign IDs:
- Entity
- Entity Group
- Entity User
- Invoice
- Payment Method (via Bring Your Own Payments)
For each of these object types, the foreign ID can be used in place of the Mercoa object ID, in both URL path parameters as well as query parameters. Foreign IDs are also included in webhook notifications for easier mapping.
Important:
- Each foreign ID must be unique within its specified scope (typically per creator entity/account). Attempting to reuse a foreign ID within the same scope will result in an error.
- Foreign IDs are typically visible to external systems via webhooks and API responses, making them suitable for cross-system mapping.
Use Cases
Using Foreign IDs with the SDK
Traditionally, you would store the Mercoa-generated ID in your database after creating a user or entity. On each later API call, you would then retrieve and use this Mercoa ID.
When using foreign IDs with Mercoa, you skip storing Mercoa IDs entirely. Just use your existing database ID directly — Mercoa handles the mapping internally.
Using Foreign IDs with the API
If you prefer to use the API, the traditional approach is similar: you pass a Mercoa-generated ID in your request URLs.
With Mercoa, you can use your own foreign ID directly in all API routes that accept an entity ID. Just substitute your database’s user ID in place of a Mercoa ID.
Examples
Create a User with a Custom Foreign ID
Retrieve a User by Foreign ID
Update an Entity by Foreign ID
Create a Payment with a Foreign ID
Summary
Mercoa’s API and SDK fully support using your system’s foreign IDs (foreignId
) in place of Mercoa IDs, across major endpoints. This feature streamlines your integration and allows you to build fintech solutions with less overhead and greater flexibility. For the most complete and current list of supported endpoints, see the official Mercoa API Reference documentation.