"External_id" for agreements
- It is possible to update the
external_id
. But the parameter is meant as a unique identifier, chosen by the merchant, which shouldn’t change. On our side we have the "agreement_id
, which never changes regardless of what happens to the agreement. That is the counterpart to theexternal_id
on your side. It should stay the same, so we can trace the full history of the agreement. - The customer can see the
external_id
in the app. - Our recommendation is, that the
external_id
is the users agreement id or reference with you. So that it does not seem confusing for the user. And if they have more than one Subscriptions agreement with you, they should be able to see which Subscriptions agreement is connected to which merchant agreement. - The
external_id
is included in the request body of the success and cancel callback. - Maximum length is 64 characters
external_id
for payments
- When utilizing callbacks, it is important that you evaluate your usage of external_id, as it will be included in the request body of the refund callback, as well in the reference number and bank statement. The merchant is responsible for setting the external_id. If the merchant is using instant transfer, then the reference number will be the external_id for recurring payments and one-off payments. Merchant can set Instant transfers themsleves in the MobilePay Portal. Read more about reconciling subscriptions payments here.
- The customer can also see the payment
external_id
in the app. - Our recommendation is that the
external_id
is unique for each payment. - Maximum length is 30 characters (this will soon be larger).
external_id
for refunds
- You can see how
external_id
for refund is implemented https://mobilepaydev.github.io/MobilePay-Subscriptions/refund - The same goes for the refunds, the
external_id
will be included in the request body of the refund callback
Updating the external_id
- This is done using the PATCH /api/merchants/me/agreements/{agreementId} endpoint.