Scheduled Payments Beta
Scheduled Payment orders allow you to plan a payment execution in the future, whether it is a unique operation or recurring ones. Scheduled Payments can be used for both Payouts (SCTE) and Wallet-to-Wallet Transfers.
The steps are as follows:
- You create a Scheduled Payment order with the desired settings (type, dates, etc.)
- The resulting Transfer(s) or Payout(s) occur at the scheduled date(s).
Information – Scheduled Payment is a Beta feature
Please contact your Treezor Account Manager if you're interested in this feature.
Attributes
Find below the list of attributes for the Scheduled Payment object.
Attribute | Type | Description |
---|---|---|
id | string | The unique identifier of the Scheduled Payment (UUIDv4). |
status | string | The status of the Scheduled Payment, which is either VALIDATED or CANCELED . |
scheduledPaymentName | string | The label describing the goal of the Scheduled Payment. |
walletId | integer | The unique identifier of the Wallet to debit. |
beneficiaryType | string | The type of beneficiary for the operation, which can be:
|
beneficiary | integer | The unique identifier of the beneficiary of the Scheduled Payment, which can be either beneficiaryId for Payouts or beneficiaryWalletId for Wallet-to-Wallet transfers. |
amount | float | The amount of the Scheduled Payment. |
type | string | The type of Scheduled Payment, which can be:
|
execAt | string | The date on which the a oneshot Scheduled Payment is to be executed. This date must be set at least one day in the future. Format: YYYY-MM-DD. |
startAt | string | The date from which a periodic Scheduled Payment execution starts. This date must be set at least one day in the future. Format: YYYY-MM-DD. |
endAt | string | The date on which a periodic Scheduled Payment ends. This date must be set after the startAt date. Format: YYYY-MM-DD. |
creationDate | string | The date and time at which the Scheduled Payment was created. |
period | string | The frequency at which a periodic Scheduled Payment is to occur. Can be: weekly , monthly , quarterly , bi-annual , or annual . |
beneficiaryLabel | string | The label that will be displayed for the Scheduled Payments, regardless of the type. Max. 140 characters. |
currency | string | The currency of the Scheduled Payments. Can only be EUR . |
userId | integer | The unique identifier of the User owning the Wallet to debit. |
amr | array | The type of SCA for per-operation SCA (e.g., CLOUD_PIN , HYBRID_PIN , DEVICE_BIOMETRIC ). |
failedPayment | object | Additional information in case of a failed payment (date, error code and error message). |
endToEndId | string | The end-to-end identifier, for Payouts only. Max. 24 characters. Allowed characters: alphanumeric and / - ? : ( ) . , + (space). Mustn't start nor end with / , and mustn't contain // . |
Structure of a Scheduled Payment
json
{
"id":"string",
"status":"string",
"scheduledPaymentName":"string",
"walletId":integer,
"beneficiaryType":"string",
"beneficiary":integer,
"amount":float,
"type":"string",
"execAt":"string",
"startAt":"string",
"endAt":"string",
"creationDate":"string",
"period":"string",
"beneficiaryLabel":"string",
"currency":"string",
"userId":integer,
"amr":["string"],
"failedPayment":[
{
"date": "string",
"errorCode": "string",
"errorMessage": "string"
}
],
"endToEndId":"string"
}
Creating a Scheduled Payment order
The required parameters to create a Scheduled Payment order vary depending on the type:
Schedule a one-time payment
Attribute | Type | Description |
---|---|---|
scheduledPaymentName | string | The label describing the goal of the Scheduled Payment. |
walletId | integer | The unique identifier of the Wallet to debit. |
beneficiaryType | string | The type of beneficiary for the operation, which can be:
|
beneficiary | integer | The unique identifier of the beneficiary of the Scheduled Payment, which can be either beneficiaryId for Payouts or beneficiaryWalletId for Wallet-to-Wallet transfers. |
amount | float | The amount of the Scheduled Payment. |
type | string | The type of Scheduled Payment, which can be:
|
execAt | string | The date on which the oneshot Scheduled Payment is to be executed. This date must be set at least one day in the future. Format: YYYY-MM-DD. |
beneficiaryLabel | string | The label that will be displayed for the Scheduled Payments, regardless of the type. Max. 140 characters. |
currency | string | The currency of the Scheduled Payments. Can only be EUR . |
endToEndId | string | The end-to-end identifier, for Payouts only. Max. 24 characters. |
You can use the following request to create your scheduled payment order.
bash
curl -X POST {baseUrl}/core-connect/scheduledPayment \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'
Here is an example of {payload}
:
json
{
"scheduledPaymentName":"gas",
"walletId":2695112,
"beneficiaryType":"payout",
"beneficiary":434403,
"amount":10,
"type":"oneshot",
"execAt":"2024-02-27",
"beneficiaryLabel":"one-time payment",
"currency":"EUR",
"userId":100165322,
"endToEndId":"GwZzGqwc"
}
Returns the Scheduled Payment object:
json
{
"id":"6492e280-16be-4c15-81c3-13d4c82d111x",
"status":"VALIDATED",
"scheduledPaymentName":"gas",
"walletId":2695112,
"beneficiaryType":"payout",
"beneficiary":434403,
"amount":10,
"type":"oneshot",
"execAt":"2024-02-27",
"startAt":null,
"endAt":null,
"creationDate":"2024-02-26T01:50:08+00:00",
"period":null,
"beneficiaryLabel":"one-time payment",
"currency":"EUR",
"userId":100165322,
"amr":[
],
"failedPayment":[
],
"endToEndId":"GwZzGqwc"
}
Schedule a periodic payment
Attribute | Type | Description |
---|---|---|
scheduledPaymentName | string | The label describing the goal of the Scheduled Payment. |
walletId | integer | The unique identifier of the Wallet to debit. |
beneficiaryType | string | The type of beneficiary for the operation, which can be:
|
beneficiary | integer | The unique identifier of the beneficiary of the Scheduled Payment, which can be either beneficiaryId for Payouts or beneficiaryWalletId for Wallet-to-Wallet transfers. |
amount | float | The amount of the Scheduled Payment. |
type | string | The type of Scheduled Payment, which can be:
|
startAt | string | The date from which a periodic Scheduled Payment execution starts. This date must be set at least one day in the future. Format: YYYY-MM-DD. |
endAt | string | The date on which a periodic Scheduled Payment ends. This date must be set after the startAt date. Format: YYYY-MM-DD. |
period | string | The frequency at which a periodic Scheduled Payment is to occur. Can be: weekly , monthly , quarterly , bi-annual , or annual . |
beneficiaryLabel | string | The label that will be displayed for the Scheduled Payments, regardless of the type. Max. 140 characters. |
currency | string | The currency of the Scheduled Payments. Can only be EUR . |
endToEndId | string | The end-to-end identifier, for Payouts only. Max. 24 characters. |
You can use the following request to create your scheduled payment order.
bash
curl -X POST {baseUrl}/core-connect/scheduledPayment \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'
Here is an example of {payload}
:
json
{
"scheduledPaymentName": "gas",
"walletId":2695112,
"beneficiaryType":"payout",
"beneficiary":434403,
"amount":10,
"type":"periodic",
"startAt":"2024-02-27",
"endAt":"2024-12-31",
"period":"weekly",
"beneficiaryLabel":"subscription",
"currency":"EUR",
"endToEndId":"GwZzGqwc"
}
Returns the Scheduled Payment object:
json
{
"id":"6492e280-16be-4c15-81c3-13d4c82d111x",
"status":"VALIDATED",
"scheduledPaymentName":"gas",
"walletId":2695112,
"beneficiaryType":"payout",
"beneficiary":434403,
"amount":10,
"type":"periodic",
"execAt":null,
"startAt":"2024-02-27",
"endAt":"2024-12-31",
"creationDate":"2024-02-26T01:50:08+00:00",
"period":"weekly",
"beneficiaryLabel":"subscription",
"currency":"EUR",
"userId":100165322,
"amr":[
],
"failedPayment":[
],
"endToEndId":"GwZzGqwc"
}
Retrieving the executed payments
To see all the operations linked to a given Scheduled Payment order, you can use the following request (which supports cursor-based pagination).
bash
curl -X GET {baseUrl}/core-connect/scheduledPayment/{scheduledPaymentId}/payments \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
Returns an array of payment objects, along with a cursor if some payments have already been made against the order.
json
{
"cursor":
{
"current": "string",
"next": "string",
"prev": "string"
},
"payments":
[
{
"date": "2024-02-27 08:15:51",
"amount": "10.00",
"currency": "EUR",
"label": "school fees",
"status": "PENDING",
"paymentId": "184427",
"errorCode": "",
"errorMessage": "",
"endToEndId": "yqCqGiMU-2024-02-27"
}
]
}
If no payment have been made against the Scheduled Payment order, an HTTP 204 is returned with an empty list.
Cancelling a Scheduled Payment
You may want to cancel a Scheduled Payment order, especially in the case of recurring payments with no end dates.
You can use the following request:
bash
curl -X DELETE {baseUrl}/core-connect/scheduledPayment/{scheduledPaymentId} \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
Returns the corresponding Scheduled Payment object with a status
set to CANCELED
.
json
{
"id":"6492e280-16be-4c15-81c3-13d4c82d111x",
"status":"CANCELED",
"scheduledPaymentName":"gas",
"walletId":2695112,
"beneficiaryType":"payout",
"beneficiary":434403,
"amount":10,
"type":"oneshot",
"execAt":"2024-02-27",
"startAt":null,
"endAt":null,
"creationDate":"2024-02-26T01:50:08+00:00",
"period":null,
"beneficiaryLabel":"one-time payment",
"currency":"EUR",
"userId":100165322,
"amr":[
],
"failedPayment":[
],
"endToEndId":"GwZzGqwc"
}
Endpoints
Endpoint | Scope |
---|---|
/core-connect/scheduledPayment Create a Scheduled Payment | read_write |
/core-connect/scheduledPayment Retrieve Scheduled Payments based on the userId and/or walletId | read_only |
/core-connect/scheduledPayment/{scheduledPaymentId} Cancel a Scheduled Payment order | read_write |
/core-connect/scheduledPayment/{scheduledPaymentId}/payments Retrieve the list of executed payments for a given Scheduled Payment order | read_write |