Recurrences

Recurrences are transactions that are executed automatically using a predefined schedule based on the recurrenceFrequency parameter. The recurrence is started at the startDate and stops when the endDate is reached.

Recurrences are executed starting a midnight UTC.

Creating a Recurrence

Creating a Recurrence using a Mandate uses the same Recurrence element as specified in One-time or periodically recurring payment, with the addition of a mandateReference. Also, the currency element is mandatory here.

Url: https://sandbox.globadyme.com/api/globadymeGateway/recurrence/createRecurring

Authorization: JWT

Request example:

{
    "recurrenceFrequency" : "YEARLY",
    "recurrenceAmount" : 51,
    "currency" : "EUR",
    "startDate": "2101-01-01",
    "endDate": "2102-01-01",
    "description": "Recurrence description",
    "mandateReference": "6AN5A542"
}

Properties for request:

Name	Description	Type	M/O/C
recurrenceFrequency	The frequency at which recurrences should be executed. Possible values: DAILY WEEKLY MONTHLY QUARTERLY YEARLY	String	Mandatory
recurrenceAmount	The amount to be paid on each recurrence. Can have a maximum of 2 decimals	float	Mandatory
currency	The currency of the recurrenceAmount. Should be in ISO 4217 three-letter code.	String	Mandatory
startDate	The date at which the first recurrence is to be executed.	Date	Mandatory
endDate	The date after which this recurrence can not be executed	Date	Optional
description	The description to be used for all executions of this recurrence.	String	Mandatory
mandateReference	Consumer’s full name	String	Mandatory
consumerAddress	Consumer’s address	String	Mandatory
paymentMethod	Payment method to be used for this Mandate. Can be SEPA or CREDITCARD	String	Mandatory
country	Country where the Consumer lives.	String	Mandatory

Response example:

{
    "message": "recurrence",
    "details": {
        "recurrence": {
            "recurrenceFrequency": "YEARLY",
            "recurrenceStatus": "ACTIVE",
            "created": "2025-01-24T16:51:06.191969346Z",
            "startDate": "2101-01-01",
            "recurrenceAmount": 51,
            "currency": "EUR",
            "description": "newerererer recurrence description",
            "id": 123,
            "mandateReference": "5cc00a5f5d714a0ba902c6e58a268328",
            "timesExecuted": 0,
            "nextRunDate": "2101-01-01"
        }
    }
}

The only fields present in the response which were not part of the request are:

Name	Description	Type
merchantId	Merchant’s merchantId	String
mandateReference	The reference to be used for this Mandate. This is the one you’ll want to store	String
mandateCreated	Timestamp when this Mandate was created	String

In this case one can check if there is any transaction with a “PROCESSED” status to confirm that a successful payment has been made.

Stopping recurrences

This endpoint facilitates the stopping of a recurrence. Note: this request requires you send a bearer token in the Authorization header.

Url: https://sandbox.globadyme.com/api/globadymeGateway/recurrence/stopRecurring

Example:

{
    "id": 1
}

Mandatory fields:

id: The ID of the recurrence to be stopped.

Example response:

{
    "message": "recurrence",
    "details": {
        "id": 1
    }
}

Triggering a recurrence

This endpoint facilitates the triggering of a recurrence. This means that a new payment is instantiated using the properties from the existing periodic recurrence (and using the Mandate created based on the initial payment), overwriting them with the amount and description provided in the request body.

Note

This request requires you send a bearer token in the Authorization header.

Note

If the Mandate supporting this recurrence has been stopped or has expired, a new payment will not be created. See the Mandates page for more information about Mandates.

Note

Triggering a recurrence has no effect on the scheduling of the recurrence.

Url: https://sandbox.globadyme.com/api/globadymeGateway/recurrence/triggerRecurring

Example:

{
    "recurrenceId": 2,
    "amount": 11.22,
    "description": "test of triggerRecurring"
}

Mandatory fields:

recurrenceId: The ID of the recurrence to be triggered.
amount: The amount to be transfered in this new payment.
description: The description to be

Example response:

{
    "message": "payment",
    "details": {
        "transactionId": "8ee67b0c-0056-44b5-b56b-cf952589582f"
    }
}

Receive a callback from Globadyme.

After execution of a recurrence, you will receive a callback from Globadyme.

This will be POSTed to the (https) endpoint you specified in your Globadyme Merchant dashboard.

The callback will contain status information about your transaction.

It will also contain a requestId, which will be the same as the requestId you received as a response to the requestPayment call. You can use this requestId to match the callback to a request you sent. RequestId will never show up on any bank statements.

The message contains a signature header. This header is a SHA-512 hash of the JSON body and the callback secret (which is provided by Globadyme). You should use this to verify the authenticity of the message.

Example

signatureHash = bytesToHex(digest.digest((notification + notifySecret).getBytes()));

Example of a callback:

{
    "id": "055ff314-6399-4350-8b8b-c9cd1e22a065",
    "amount": 10.00,
    "status": "PROCESSED",
    "paymentMethod": "SEPA",
    "currency": "EUR",
    "country": "NL",
    "description": "TestPayment",
    "feeCalculation": {
        "sellPercentage": 0.00,
        "sellCents": 15
    },
    "timestamp": "2024-01-20T13:05:51.948873470Z",
    "requestId": "852f0c72-0024-4070-9ac7-563eeb4755f6",
    "settled": true,
    "settlementDate": "2024-01-28T06:00:00.572957294Z",
    "settlementId": "1-912-W-2024-3-C0",
    "originalTransactionId": "fd6239c8-db15-41af-9f3d-f5f81a264015", 
    "mandateReference": "ORbTEJhzs04", 
    "transactionRecurrenceType": "RECURRING"
}