Migrate to V2

TL;DR

The X-Trace-Version header with value 2 must be used for the Create Transaction by DICT Key and Create QR Code Transaction endpoints to enable V2.
Transactions in V2 are processed asynchronously, returning an initial REQUESTED status with some missing or null data fields.
The new TRANSACTION_REQUESTED webhook has been added to notify clients of transactions in the REQUESTED state.
DICT Key lookups are now handled asynchronously within the transaction process, and the DICT Key Lookup endpoint will be deprecated.
During the transaction creation process, you can specify validations that must be passed.
Clients should rely on the TRANSACTION_COMPLETED webhook to ensure that a transaction has been fully enriched and completed.

How to Migrate

To begin using V2, you need to version specific endpoints by including the X-Trace-Version header with value 2. This applies to the following endpoints:

For other endpoints, sending this header is not required, as they have not undergone any changes that would necessitate versioning. Please refer to the Versioning section for more details.

Additionally, DICT Key lookups are no longer necessary, and we kindly discourage using this API. For more details, please refer to the DICT Key lookups section

What's New in V2

In V2, significant changes were introduced to improve transaction processing. Below are the key changes:

1. Asynchronous Transaction Processing

Transaction processing is no longer synchronous. Transaction endpoints have been modified to create transactions without performing third-party system lookups at the time of creation. In this initial phase, the transaction is returned with status REQUESTED and missing some essential information, which will be filled in asynchronously later.

For details on which fields will be present and which will be null in the initial response, please consult the API documentation.

2. Status Changes

After a transaction is created with the REQUESTED status, it can follow one of two paths:

CREATED: If the asynchronous enrichment process completes successfully.
FAILED: If any errors occur during the enrichment process.

3. New Webhook: `TRANSACTION_REQUESTED`

A new webhook, TRANSACTION_REQUESTED, has been added, allowing clients to track the progress of a transaction even before it is fully enriched.

While the majority of transaction data is typically available in the TRANSACTION_CREATED webhook, it is important to note that this is not always guaranteed. For a fully enriched and finalized transaction, clients should rely on the TRANSACTION_COMPLETED webhook.

4. DICT Key Lookups

It is no longer necessary to perform a DICT Key lookup before creating a transaction by DICT key. Now, the lookup is done internally and asynchronously, and the information is added to the transaction automatically. As a result, our DICT Key Lookup endpoint will be deprecated.

5. Validations

During the debit transaction creation process, you can include a set of validations that the transaction must pass. Please consult the Transaction Validations section for more details.