Scheduled Jobs
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"
}
Updated 2 months ago