Changes in the release on 23/05/2023

Below you can find manuals regarding two main functionality enhancements in the upcoming release:

• Fee enhancements

• Charges

Fee enhancements

These enhancements have impact on current implementation, so please make sure to get acquainted with it thoroughly. We encourage you to focus on the 'Use cases' section and to prepare/create the data ASAP to validate them later after migration run on Staging on Wednesday afternoon (17/05/2023).

Changes:

1. "CURRENCY_MARKUP" is renamed to "PURCHASE_FOREIGN_CURRENCY"

2. "PURCHASE_FOREIGN_CURRENCY" is applicable to "PURCHASES" in foreign currencies

3. Introduced a new enum "WITHDRAWAL_FOREIGN_CURRENCY" for transaction type in Fees APIs and it is applicable to "WITHDRAWALS" in foreign currencies

4. Allowed definition of fee with currency value as *** (*** stands for any currency other than the one(s) supported by the card product)

5. Added description in "transaction_origin" field that this field is applicable for transaction types WITHDRAWALS, PURCHASES, PURCHASE_FOREIGN_CURRENCY & WITHDRAWAL_FOREIGN_CURRENCY

6. Added description in "currency" field that *** is applicable for transaction type "PURCHASE_FOREIGN_CURRENCY" & WITHDRAWAL_FOREIGN_CURRENCY

Example:

Single currency card product with base currency of AED.

Fee plan of "transaction_type": "PURCHASE_FOREING_CURRENCY" is linked to the card product, where:
"currency": "***" , 
"type": "FLAT", 
"amount": 5,
"transaction_origin": "ANY".

PURCHASE transaction of amount USD 50 is received.

Transaction amount (USD 50) is converted into AED and deducted from the AED account. Similarly, fee amount (USD 5) is converted into AED and deducted from the AED account.

What to expect after migration run:

1. "CURRENCY_MARKUP" enum will be changed to "PURCHASE_FOREIGN_CURRENCY". It will take on the default currency of ***.

2. A new fee plan (unique ID) of type "WITHDRAWAL_FOREIGN_CURRENCY" is created and linked to the same product to which "PURCHASE_FOREIGN_CURRENCY" is initially linked to. It will take on the default currency of ***.

3. The new fee plan "WITHDRAWAL_FOREIGN_CURRENCY" will inherit the same details as that of the existing fee plan "PURCHASE_FOREIGN_CURRENCY" except that the fee plan corresponding to "WITHDRAWALS" will have an extra string "_WITHDRAWAL" in the description field.

Use cases:

• A card product with fee plan of type PURCHASE linked to it

After the migration: no impact (fee will be applied on PURCHASE transactions done in base currency - business as usual)

• A card product with multiple fee plans linked to it among which are PURCHASE and CURRENCY_MARKUP

After the migration:

- CURRENCY_MARKUP is updated to PURCHASE_FOREIGN_CURRENCY

- a new fee plan of type "WITHDRAWAL_FOREIGN_CURRENCY is created and linked to the same card product

- perform PURCHASE transactions in base currency and confirm the correct fee is being applied [speaking of "PURCHASE" fee plan]

- perform PURCHASE transactions in foreign currencies and confirm the correct fee is being applied [speaking of PURHCASE_FOREIGN_CURRENCY]

- perform WITHDRAWAL transactions in foreign currencies and confirm the correct fee is being applied [speaking of WITHDRAWAL_FOREIGN_CURRENCY]

• "CURRENCY_MARKUP" is linked to more than one product

After the migration: everything will continue to work normally except that different fee plans of type "WITHDRAWAL_FOREIGN_CURRENCY" will be created and linked to the different card products

Charges

This is new functionality, so it does not have impact on current implementation.

We added an ability to post card issuance charges so that it can be applied to respective cardholder's account. This will be applied one time only for every new card that is issued.

In Scope:

1) Personalized physical card is issued first time

2) Personalized virtual card is issued first time

3) Bulk card is linked to the user

Out of Scope:

If card is replaced then issuance charges shall not be considered.

API Catalog:

The below APIs are exposed in API Catalog:

• Create charge
• Update charge
• Get a specific charge
• Get list of charges
• Link charges to card product (you can link multiple charges at once)
• Unlink charges from card product (you can unlink multiple charges at once)
• Get list of charges related to card product

Note, that supported enums for 'charge_type' are "PHYSICAL_CARD_ISSUANCE" & "VIRTUAL_CARD_ISSUANCE".

Webhooks

New webhook event/enum "CHARGE_APPLIED" is addded. Below you can find webhook sample:

{
  "event": "CHARGE_APPLIED",
  "charge_applied": {
    "id": "0fcf8c07-ae35-4243-890d-0a39b2618578",
    "description": "charges dev 28",
    "currency": "AED",
    "amount": 2,
    "card_id": "f3bd66fd-80d5-4c7c-90e2-ac062c923ff0",
    "account_id": "f3bd66fd-80d5-4c7c-90e2-ac062c923ff0",
    "charge_id": "CHARGEAHSAN19",
    "charge_type": "PHYSICAL_CARD_ISSUANCE"
  }
}

Cron Job:

A cron will run on a daily basis to pick up those charges in "PENDING" status and apply the charge amount to cardholders' accounts.