Eclipse supports scheduling certain API calls to be executed at defined intervals according to a cron expression. A cron expressions is an expression language that allow you to concisely define complex schedules - for more details including examples please refer here.

Scheduled jobs in Eclipse allow a tenant to easily setup tasks like recurring withdrawals and recurring card payments.

The Eclipse job scheduler offers versatility by enabling the association of scheduled tasks with specific objects based on the provided type. Once a scheduled job is created and the cron expression is configured, the system triggers the associated API calls periodically as per the specified type, adhering to the cron expression. If a startDate is provided, the scheduler will commence operations from that datetime onwards. Similarly, if an endDate is specified, the scheduler will continue to run until that specified date and time, otherwise, it continues indefinitely. Scheduled jobs can be linked with particular entities such as wallets, customers, or organisations, leveraging attributes provided in the request to ensure contextual relevance within the system.

As the Eclipse job scheduler serves as a generic interface, the required attributes for the specific job are specified in the additionalFields field. The attribute key within additionalFields should adhere to the format specified in data model of the task being scheduled (e.g. a withdrawal).

📘

Note

All scheduled jobs are executed by a system user. This means that the permissions to create scheduled jobs should only be given to those who have the permissions to execute the individual job types. The relevant permissions for scheduled jobs are:

• ScheduledJob.CREATE.Allowed
• ScheduledJob.READ.Allowed
• ScheduledJob.UPDATE.Allowed
• ScheduledJob.DELETE.Allowed

Recurring Withdrawals

Prerequisites

• All the relevant tenant config and wallets configured to be able to complete the actual withdrawal. See Withdrawal Use Cases for more details.

Here is an example call to schedule an EFT withdrawal from a particular customer wallet every 5 minutes:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/scheduled-jobs

{
  "additionalFields": [
    {
      "att": "amount",
      "val": "5"
    },
    {
      "att": "bank",
      "val": "TestNedBank EFT"
    },
    {
      "att": "branchCode",
      "val": "111111"
    },
    {
      "att": "accountName",
      "val": "Customer1"
    },
    {
      "att": "accountNumber",
      "val": "123456789012"
    },
    {
      "att": "reference",
      "val": "randomWord"
    },
    {
      "att": "deliverToPhone",
      "val": "27856789876"
    },
    {
      "att": "description",
      "val": "adlkjadjkladlk"
    },
    {
      "att": "externalUniqueId",
      "val": "slkslkjsdkj32897927lk"
    },
    {
      "att": "type",
      "val": "ZA_NEDBANK_EFT"
    },
    {
      "att": "callbackUrl",
      "val": "https://www.google.com"
    }
  ],
  "cron": "*/5 * * * *",
  "description": "EFT withdrawal scheduling",
  "externalUniqueId": "dhsdfksdkh32023080823",
  "relatedTo": [
    {
      "relatedToId": "1025",
      "relatedToType": "wallet"
    },
   {
      "relatedToId": "25",
      "relatedToType": "customer"
    }

  ],
  "tenantId": 2,
  "startDate":"2024-03-11T14:38:26-04:00",
  "endDate":"2024-03-11T14:45:26-04:00",
  "type": "RECURRING_WITHDRAWAL"
}

📘

Note

If the amount field is set to max then the available balance of the wallet will be withdrawn. This is to cater for the common use case where a user wants to clear the balance of a particular wallet to a nominated bank account.

Here is an example call to update a scheduled withdrawal:

PUT  /eclipse-conductor/rest/v1/tenants/{tenantId}/scheduled-jobs/{scheduledJobId}
{ 
	"scheduledJobId":10,
  "additionalFields": [
    {
      "att": "amount",
      "val": "5"
    },
    {
      "att": "bank",
      "val": "TestNedBank EFT"
    },
    {
      "att": "branchCode",
      "val": "111111"
    },
    {
      "att": "accountName",
      "val": "Customer1"
    },
    {
      "att": "accountNumber",
      "val": "123456789012"
    },
    {
      "att": "reference",
      "val": "randomWord"
    },
    {
      "att": "deliverToPhone",
      "val": "27856789876"
    },
    {
      "att": "description",
      "val": "adlkjadjkladlk"
    },
    {
      "att": "externalUniqueId",
      "val": "slkslkjsdkj32897927lk"
    },
    {
      "att": "type",
      "val": "ZA_NEDBANK_EFT"
    },
    {
      "att": "callbackUrl",
      "val": "https://www.google.com"
    }
  ],
  "cron": "*/5 * * * *",
  "description": "EFT withdrawal scheduling",
  "externalUniqueId": "dhsdfksdkh32023080823",
  "relatedTo": [
    {
      "relatedToId": "1025",
      "relatedToType": "wallet"
    },
   {
      "relatedToId": "25",
      "relatedToType": "customer"
    }

  ],
  "tenantId": 2,
  "startDate":"2024-03-11T14:38:26-04:00",
  "endDate":"2024-03-11T14:45:26-04:00",
  "type": "RECURRING_WITHDRAWAL"
}

Recurring Payments

Prerequisites

• All the relevant tenant config and wallets configured to be able to complete the actual payment. See Payment Use Cases for more details.
• For initiating any recurring payments you need to ensure that the customer has opted in for the recurring payment and has the ability to opt out.
• When storing the card of file an authenticated transaction should be performed to ensure that 3DS has been completed. When calling the cards on file endpoint make sure to set the authenticated field to true.

Here is an example call to schedule an card payment every 5 minutes:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/scheduled-jobs
{
  "additionalFields": [
    {
      "att": "amount",
      "val": "1.1"
    },
    {
      "att": "currency",
      "val": "ZAR"
    },
    {
      "att": "paymentMechanism",
      "val": "CARD"
    },
    {
      "att": "paymentData",
      "val": "197166"
    },
    {
      "att": "phone",
      "val": "9723512382"
    },
    {
      "att": "description",
      "val": "Wallet payment shceduler-1"
    },
    {
      "att": "externalUniqueId",
      "val": "data-external-unique-id-"
    },
    {
      "att": "type",
      "val": "GLOBAL_WALLET"
    },
    {
      "att": "cardOnFileId",
      "val": "724dacdb-ae57-40fe-8661-5d830354d49a"
    },
    {
      "att": "unattended",
      "val": "true"
    }
  ],
  "cron": "*/5 * * * *",
  "startDate": "2024-04-23T05:05:26-00:00", 
  "endDate": "2024-04-30T10:45:26-00:00", 
  "description": "GLOBAL WALLET Payment scheduling",
  "externalUniqueId": "outer-external-unique-id-",
  "relatedTo": [
    {
      "relatedToId": "1126",
      "relatedToType": "customer"
    }
  ],
  "type": "RECURRING_PAYMENT"
}

Updating a Scheduled Job

There will often be requirements to modify the scheduler, whether it involves adjusting the startDate, endDate, cron expression, description, and so forth. Eclipse facilitates the alteration of existing schedulers at any given time. However, it's crucial to exercise caution, particularly with two attributes: additionalFields and relatedTo.

Regarding additionalFields, these are instrumental in dictating the behavior of the scheduler based on the specified type. If new additionalFields are supplied, they may alter the behavior of the existing scheduler in accordance with the provided fields. Therefore, it's imperative to include all relevant fields when updating.

Concerning relatedTo, this attribute determines the mapping of the scheduler. When updating, if new mappings are provided, they will replace all existing mappings to accommodate the new ones. To retain the existing mappings, it's necessary to include all current mappings alongside the new ones. Omitting to include relatedTo in the update request will leave the existing mappings unchanged.

Here is an example call to update a scheduled withdrawal:

PUT  /eclipse-conductor/rest/v1/tenants/{tenantId}/scheduled-jobs/{scheduledJobId}
{ 
	"scheduledJobId":10,
  "additionalFields": [
    {
      "att": "amount",
      "val": "5"
    },
    {
      "att": "bank",
      "val": "TestNedBank EFT"
    },
    {
      "att": "branchCode",
      "val": "111111"
    },
    {
      "att": "accountName",
      "val": "Customer1"
    },
    {
      "att": "accountNumber",
      "val": "123456789012"
    },
    {
      "att": "reference",
      "val": "randomWord"
    },
    {
      "att": "deliverToPhone",
      "val": "27856789876"
    },
    {
      "att": "description",
      "val": "adlkjadjkladlk"
    },
    {
      "att": "externalUniqueId",
      "val": "slkslkjsdkj32897927lk"
    },
    {
      "att": "type",
      "val": "ZA_NEDBANK_EFT"
    },
    {
      "att": "callbackUrl",
      "val": "https://www.google.com"
    }
  ],
  "cron": "*/5 * * * *",
  "description": "EFT withdrawal scheduling",
  "externalUniqueId": "dhsdfksdkh32023080823",
  "relatedTo": [
    {
      "relatedToId": "1025",
      "relatedToType": "wallet"
    },
   {
      "relatedToId": "25",
      "relatedToType": "customer"
    }

  ],
  "tenantId": 2,
  "startDate":"2024-03-11T14:38:26-04:00",
  "endDate":"2024-03-11T14:45:26-04:00",
  "type": "RECURRING_WITHDRAWAL"
}

Withdrawal Threshold

Standard Withdrawal Threshold

The withdrawal threshold functionality enables a recurring withdrawal to be paid to a beneficiary only once the value in the customer wallet exceeds a certain amount. The attributes needed to enable the withdrawal threshold functionality are set on a wallet type level.

The withdrawal threshold functionality requires that a batch scheduled withdrawal is captured for the tenant using the scheduled job functionality. Note: A withdrawal will not process for a customer if the withdrawal threshold amounts are higher than the amount defined on the scheduler.

To enable standard withdrawal threshold functionality, the following wallet type attributes should be set:

Note: If multiple beneficiaries are captured on a customer, Eclipse will process the payment to the beneficiary captured with the alias "MyAccount".

Should a customer need to be excluded from the batch withdrawal functionality, the wallet update API can be called to update batchAutoWithdrawalAllowed to false.

Initial Phase Withdrawal Threshold

If it is necessary to have a different withdrawal threshold amount applied to the wallet initially for a certain period, then the initial phase withdrawal threshold can be set. This defines the initial withdrawal threshold amount to be used, which is used in place of the standard withdrawal threshold amount, as well as the number of days the initial phase withdrawal threshold should be enabled for. To enable initial phase withdrawal functionality, the following wallet type attributes should be set:

Dormancy

If a wallet does not reflect a transaction after a certain number of days, the customer can be treated as a dormant customer. The wallet balance will pay to the beneficiary on record once the number of days have been reached. The days between the last transaction in the customer wallet and the dormancy payment are defined according to the following wallet type attributes: