Partner External Id

About

The primary use of the partnerExternalId is to allow clients to track and retrieve information about an entity created via the Partner-Api, even if the request’s response was lost, failed, or unprocessed due to unforeseen circumstances.

With partnerExternalId set the API integration can be improved in the following ways:

• Reliability: Disruptions may be handled in a better way, clients can implement checks to ensure the actual state of their data.
• Consistency: Ensures a consistent point of reference between your system and our API, helping to manage asynchronous processes or retry mechanisms.
• Reconciliation: Allows easy reconciliation of records if there are discrepancies or if any flow was left incomplete.

📢 We strongly recommend that partners always include the partnerExternalId when initiating a Charge.

How to use

The majority of our entities support the partnerExternalId, for example, to start a Charge with a partnerExternalId You can do so by sending a POST request to the /charges endpoint with the following payload:

{
  "chargePointId": 1,
  "payingTeamId": 1,
  "partnerExternalId": "MY_INTERNAL_ID_123",
  "partnerCustomPayload": {
    "field1": "1",
    "field2": [1, 2, 3]
  }
}

If You wish to filter changers with the partnerExternalId, it can be done via GET /charges endpoint with the following query parameters:

curl --request GET \
     --url 'https://partner-api.monta.com/api/v1/charges?partnerExternalId=MY_INTERNAL_ID&page=0&perPage=10' \
     --header 'accept application/json'

All endpoints follow the same standard for the partnerExternalId

Benefits

Setting the partnerExternalId is the first step towards improving the reliability and consistency of your API integrations.

Improved Error Recovery

In cases where a response is missing, or it times out, the client can use the partnerExternalId to query the state of an entity, even if the initial API response was not captured. This is particularly useful in payment capture or other time-sensitive transactions.

Data Reconciliation

When reconciling data between the client’s system and our API, the partnerExternalId provides a simple and reliable way to match corresponding records.

Easier Debugging and Support

Including partnerExternalId enables the Partner-Api team, to quickly find a particular resource during investigations.