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.

1
// Your application's user ID
2
const your_DB_id = 'user-123';
3
4
// Retrieve the Mercoa ID from your database
5
const { mercoaId } = await getUser(your_DB_id);
6
7
// Use the Mercoa ID to interact with Mercoa via the SDK
8
const mercoaUser = await mercoa.user.get(mercoaId);

When using foreign IDs with Mercoa, you skip storing Mercoa IDs entirely. Just use your existing database ID directly — Mercoa handles the mapping internally.

1
// Your application's user ID
2
const your_DB_id = 'user-123';
3
4
// Use your DB ID directly with the Mercoa SDK -- no need to store Mercoa IDs
5
const mercoaUser = await mercoa.user.get(your_DB_id);

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.

1
GET /api/users/{mercoaId}
2
Authorization: Bearer <your_api_key>

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.

1
GET /api/users/{foreignId}
2
Authorization: Bearer <your_api_key>

Examples

Create a User with a Custom Foreign ID

1
POST /api/users
2
Content-Type: application/json
3
4
{
5
  "foreignId": "user-123",
6
  "email": "user@example.com",
7
  "name": "John Doe"
8
}

Retrieve a User by Foreign ID

1
GET /api/users/user-123

Update an Entity by Foreign ID

1
PUT /api/entities/user-123
2
Content-Type: application/json
3
4
{
5
  "name": "Acme Corporation",
6
  "address": "123 Main St, Cityville, NY",
7
}

Create a Payment with a Foreign ID

1
POST /api/payments
2
Content-Type: application/json
3
4
{
5
  "foreignId": "payment-321",
6
  "amount": 5000,
7
  "currency": "USD",
8
  "payerEntityId": "entity-456",
9
  "invoiceId": "invoice-789"
10
}

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.