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:

  1. You create a Scheduled Payment order with the desired settings (type, dates, etc.)
  2. The resulting Transfer(s) or Payout(s) occur at the scheduled date(s).
Info icon

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.

AttributeTypeDescription
idstringThe unique identifier of the Scheduled Payment (UUIDv4).
statusstringThe status of the Scheduled Payment, which is either VALIDATED or CANCELED.
scheduledPaymentNamestringThe label describing the goal of the Scheduled Payment.
walletIdintegerThe unique identifier of the Wallet to debit.
beneficiaryTypestringThe type of beneficiary for the operation, which can be:
  • payout – The Scheduled Payment targets an external account.
  • walletTransfer – The Scheduled Payment targets another Wallet in your Treezor environment.
beneficiaryintegerThe unique identifier of the beneficiary of the Scheduled Payment, which can be either beneficiaryId for Payouts or beneficiaryWalletId for Wallet-to-Wallet transfers.
amountfloatThe amount of the Scheduled Payment.
typestringThe type of Scheduled Payment, which can be:
  • oneshot – The payment will occur only once.
  • periodic – The payment will occur periodically over a defined timeframe.
execAtstringThe 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.
startAtstringThe 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.
endAtstringThe date on which a periodic Scheduled Payment ends. This date must be set after the startAt date. Format: YYYY-MM-DD.
creationDatestringThe date and time at which the Scheduled Payment was created.
periodstringThe frequency at which a periodic Scheduled Payment is to occur. Can be: weekly, monthly, quarterly, bi-annual, or annual.
beneficiaryLabelstringThe label that will be displayed for the Scheduled Payments, regardless of the type. Max. 140 characters.
currencystringThe currency of the Scheduled Payments. Can only be EUR.
userIdintegerThe unique identifier of the User owning the Wallet to debit.
amrarrayThe type of SCA for per-operation SCA (e.g., CLOUD_PIN, HYBRID_PIN, DEVICE_BIOMETRIC).
failedPaymentobjectAdditional information in case of a failed payment (date, error code and error message).
endToEndIdstringThe 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 ​

AttributeTypeDescription
scheduledPaymentNamestringThe label describing the goal of the Scheduled Payment.
walletId integerThe unique identifier of the Wallet to debit.
beneficiaryType stringThe type of beneficiary for the operation, which can be:
  • payout – The Scheduled Payment targets an external account.
  • walletTransfer – The Scheduled Payment targets another Wallet in your Treezor environment.
beneficiary integerThe unique identifier of the beneficiary of the Scheduled Payment, which can be either beneficiaryId for Payouts or beneficiaryWalletId for Wallet-to-Wallet transfers.
amount floatThe amount of the Scheduled Payment.
type stringThe type of Scheduled Payment, which can be:
  • oneshot – The payment will occur only once.
  • periodic – The payment will occur periodically over a defined timeframe.
execAt stringThe 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.
beneficiaryLabelstringThe label that will be displayed for the Scheduled Payments, regardless of the type. Max. 140 characters.
currency stringThe currency of the Scheduled Payments. Can only be EUR.
endToEndIdstringThe 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 ​

AttributeTypeDescription
scheduledPaymentNamestringThe label describing the goal of the Scheduled Payment.
walletId integerThe unique identifier of the Wallet to debit.
beneficiaryType stringThe type of beneficiary for the operation, which can be:
  • payout – The Scheduled Payment targets an external account.
  • walletTransfer – The Scheduled Payment targets another Wallet in your Treezor environment.
beneficiary integerThe unique identifier of the beneficiary of the Scheduled Payment, which can be either beneficiaryId for Payouts or beneficiaryWalletId for Wallet-to-Wallet transfers.
amount floatThe amount of the Scheduled Payment.
type stringThe type of Scheduled Payment, which can be:
  • oneshot – The payment will occur only once.
  • periodic – The payment will occur periodically over a defined timeframe.
startAt stringThe 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.
endAtstringThe date on which a periodic Scheduled Payment ends. This date must be set after the startAt date. Format: YYYY-MM-DD.
period stringThe frequency at which a periodic Scheduled Payment is to occur. Can be: weekly, monthly, quarterly, bi-annual, or annual.
beneficiaryLabelstringThe label that will be displayed for the Scheduled Payments, regardless of the type. Max. 140 characters.
currency stringThe currency of the Scheduled Payments. Can only be EUR.
endToEndIdstringThe 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 ​

EndpointScope
/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