Changelog

The Integration API is not yet generally available. Until it is, a change within v1 can break an existing integration, and each one is marked Breaking below. Other changes are additive. Before anything is removed, it is announced here and marked with a Deprecation response header.

v1Copy Anchor Link

• First release of the Integration API at /integration/v1.
• The earlier /api/v1/integration/devices, /transactions and /device-models reads are deprecated. Their responses carry a Deprecation header and a Link to the /integration/v1 replacement. They will be removed once no integration calls them.
• Added q, match and sort to the enterprise, company and trading lists.
• Added sort to the acquirer list.
• Added sort to the device list.
• Added sort to the trading enrollment list. With sort=updated_at or sort=-updated_at and no status, ended enrollments are listed too, so a refresh sees an enrollment end.
• Transactions carry received_at and updated_at, and the transaction list takes sort=updated_at or -updated_at, so a void or a late upload shows up without re-reading old capture windows.
• Added POST /integration/v1/devices/{id}/decommission, which retires a device permanently. A device still set up for a product is refused with 409.
• A decommissioned device gives up its device_identifier, so the same serial can be registered again as a new device. The decommissioned device keeps its id and history, so filtering the device list by device_identifier can return both.
• Reorganised the reference into Merchants, Catalogue, Enrollments, Devices and Reporting, and named devices consistently. Reference page addresses changed with the new section names.
• Added GET /integration/v1/applications, to find the application_id the device parameter operations take. Filter by product_code and acquirer_id to find the application a device runs once it is set up for them.
• The application list's acquirer_id and acquirer_external_ref filters match only applications bound to that acquirer. Applications for every acquirer (acquirer_id null) no longer appear under an acquirer filter; list them without one.
• Added GET /integration/v1/applications/{id}, which returns one application in the same shape as the list.
• Renamed the device parameter operations to "application parameter overrides" (the device's own values) and "resolved application parameters" (the values it runs). Paths and fields are unchanged.
• Breaking: before general availability, aligned the device endpoints with the API's conventions. These change field names:
  • The device parameter operations take and return last_modified_at and applied_last_modified_at, which were last_modified_date and applied_last_modified_date.
  • The resolved parameters report the device's state as device, which was terminal.
  • A device's applications list pages like every other list, and each entry names the application by id, which was application_id.
• Every operation now documents 429 and 500.
• Documented the conventions: timestamps end in _at, amounts are integers in the minor unit of their currency, and responses can gain fields and enum values within v1.
• An activation code refused with 409 now says in detail whether the device is suspended or decommissioned.
• Documented the default rate limit: 5 requests per second per key, with bursts of up to 20. A key's limit can be raised on request.
• Clarified the reference for readers new to Narya: the steps to put a device into service, what each device status means, the transaction fields, and when a list's total_count is capped. No request or response changed.
• The device list is no longer capped at 10,000: every page can be read and total_count is exact. Added status, trading_id and trading_external_ref filters to it.
• Added POST /integration/v1/devices and POST /integration/v1/devices/batch, to register devices one at a time or up to 1,100 of one model at once.
• A device's device_identifier is unique within your organisation ignoring letter case: sn-0001 and SN-0001 are the same serial.
• Companies carry enterprise, and tradings carry company and enterprise, each with id, external_ref and current name. Renaming a parent does not change its children's updated_at.
• An acquirer's external_ref can be changed, and null clears it. A key limited to one acquirer cannot change it.
• Added contact_email to the company and trading lists.
• Setting a device up for a product, or releasing it, updates the device's updated_at, so a refresh picks up the change to its trading_ids.
• The enterprise, company, trading and acquirer lists take include_deleted, updated_after and updated_after_id, and each record carries deleted_at, so you can sync them from your last position, deletions included. With updated_after or sort=updated_at, changes from the last 30 seconds are left out until they are saved. See Syncing data.
• Breaking: companies no longer carry enterprise, and tradings no longer carry company or enterprise. Tradings now carry enterprise_id, and a company's enterprise_id is always present, null when it has none. Take names from the enterprise and company lists and join by id. Moving a company to another enterprise updates its tradings' updated_at.