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.
Updated 18 days ago