Scenario A: Collect varying amounts at specific month #
i) For this example, we will pretend to be a merchant that wants to collect a fixed amount for the first 23 months, followed by collection of different amount only for the final month.
- I have created a Direct Debit mandate for 24 months, where each month collection is fixed at RM300.00.
- Now I need to collect only RM150.50 for the final month. How can I update it for the final month via Payex API?
Few ways to do it via Update Mandate Collection Settings Request endpoint /api/v1/mandates/collectionSettings/reference_number: #
Option 1: Mandate setting for auto collection to ‘false’ #
- If auto = false, Payex will wait for your instructions before next deduction
- You would need to create one mandate and 24 collections
- Create collections for 23 months for RM300.00, and final month RM150.50
Option 2: Mandate setting for auto collection to ‘true’ #
- If auto = true, system will auto collect every month
- After 23rd month collection or before 24th month collection, you need to change collection amount to RM150.50
Option 3: Mandate setting for auto collection to ‘true’ #
- If auto = true, system will auto collect every month
- Create collection for the 24th month for RM150.50, then Payex auto collection schedule will skip the 24th month when the time comes
- For example, if mandate’s effective date 1st Jan 2024, for 24 months period the last collection will be 1st Dec 2025. So, you need to create collection for 1st Dec 2025 as RM150.50, the rest of months will follow auto collection schedule.
ii) For this example, we will pretend to be a merchant that wants to collect a different amount only for the first month, followed by a fixed amount for the next 11 months.
Few ways to do it via Create Mandate Request endpoint /api/v1/Mandates: #
Option 1: Mandate for auto collection to ‘false’ #
- Call create mandates endpoint to authorise (max amount = RM300, auto=false)
- Call create collection endpoint to collect RM100 for 1st month
- Call create collection endpoint to collect RM300 for 2nd to 12month
Option 2: Mandate for auto collection to ‘true’ #
- Call create mandates endpoint to authorise (max amount = RM300, auto=true)
- Call create collection endpoint to collect RM100 for 1st month
- RM300 collection will be auto created for 2nd to 12month
Option 3: Mandate for auto collection to ‘true’ #
- Call create mandates endpoint to authorise (max amount = RM300, auto=true)
- Call payment intent endpoint to collect RM100 for 1st month using one time payment
- RM300 collection will be auto created for 2nd to 12month
Scenario B: Terminate collection halfway through #
For this example, we will pretend to be a merchant that wants to stop all collection from the customer who has decided to pay down all dues / early settle the outstanding amount
- I have created a Direct Debit mandate for 60 months, where each month collection is fixed at RM300.00.
- Customer started paying for January and in February decides to pay down all outstanding amount. Which API can I use to instruct Payex to stop collecting funds from my customer in March onwards?
Option 1: Use Update Mandate Collection Settings Request endpoint #
/api/v1/mandates/collectionSettings/reference_number
curl --location --request PUT '/api/v1/Mandates/CollectionSettings/MNxxxxx' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxx' \
--data '{
"active": false
}'- Note: Reference number is path instead of query param
Option 2: Use Delete Mandates Request endpoint #
- If delete mandate then all collections under the mandate will be deactivated
- You can still delete mandates although some collections are active
- Delete mandate endpoint will need customer to authorise the termination link
Scenario C: Collect at varying dates for different customers #
For this example, we will pretend to be a merchant that wants to initiate two types of subscription plan depending on the customer’s subscription start date
- Subscription Plan A: When customer subscribes on any date between 1st to 29th April; the next payment i.e. 2nd payment = 1st May
- Through Payex API
- Set the param “day” to whichever day of month as anchor day, so if 1st of May then set day=1
- Effective date can remain as any date from 1st to 29th April (e.g. 20240415). So next billing will be 1st of every month.
- Once setup, Payex system will automatically charge the customer if the setting for auto=true
- Alternatively if auto=false, then you can send collection request to Payex on whichever date and Payex will process accordingly
- Subscription Plan B: When customer subscribes on 30th April (last day of the month); the next payment i.e. 2nd payment = 1st June
- Option 1: You will have to call Payex API to make “inactive” the mandate and activate again on 1st June
- Option 2: For these types of non-standard collection schedule, will be better to use your own schedule (set auto=false)
