Recurring payments

Before integrating recurring payments, here are some things you need to know:

  1. For each recurring transaction it is required to obtain a prior express recurring Transaction consent from the consumer (including specifically the Cardholder), at the point of checkout, for your products /services sold using our widget.

  2. Information that is needed to provide before obtaining a consent:

    1. the amount of the recurring transaction;
    2. whether the amount is fixed or variable;
    3. the date of the recurring transaction (if it is in the future or else show it as today);
    4. whether the date is fixed or variable;
    5. an agreed method of communication for all future correspondence with the consumer.

  3. Using the agreed method of communication, you need to provide consumer with a confirmation that a recurring Transaction agreement has been entered into. This confirmation must be provided within two (2) business days of entering that recurring transaction agreement, which must be separate from the sales agreement.

  4. You must notify consumer that this recurring transaction consent is subject to cancellation by the consumer at any time, and you should not debit or attempt to debit the consumer’s card or any other payment method account after being notified of the cancellation of the Recurring Transaction consent.

  5. You must notify the consumer in writing of the amount to be debited and the due date of the debit at least 14 days prior to each subsequent debit (unless the recurring transaction consent sets out the amounts payable and the due dates and none of these have changed or other objective criteria are agreed with the consumer for calculating the due dates).

  6. You must retain the recurring transaction consent for the duration of the Recurring Transactions, and for a period of 18 months after the final payment that is made pursuant to it. You should be able to produce the recurring transaction consent to us on first demand.

Recurring payment’s parameters

Currently, only card payments can be recurring. We support 2 types of recurring card payments - merchant initiated transactions without schedule (unscheduled MITs) and regular scheduled payments (also known as subscriptions).

How does it work?

  1. You provide details to your customer for recurring payments (conditions, procedure how to cancel it etc.) before initiating a payment (in your checkout page), take their consent. Soon we will have an option to show details on our widget also.

  2. First payment is initiated with mandatory 3DS authentication, if successful, recurrence ID is created.

  3. With received recurrence ID you can initiate subsequent payments (if they are unscheduled MITs) or these subsequent payments are initiated by us following details frequency details you provided in initial’s payment request).

  4. You can see full history of all payments with particular recurrence ID using our separate Get recurrence details API.

Initiate a payment with recurrence details

For first payment use our Initiate Payment API with recurrence parameters:

Parameter

Description

Mandatory?

recurrence.type

Recurrent payment type.

unscheduled - used for MITs without other details, initiated on your demand (cardholder not present)

recurring - used for subscriptions and regular based payments.

Yes

frequency.interval

Recurrent payment frequency interval type.
Possible values: monthly, custom

If interval=monthly, then frequency.days parameter is ignored and becomes irrelevant

If interval=custom, frequency.days parameter is mandatory

Yes

recurrence.frequency.days

Integer, conditional mandatory if recurrence.type is recurring and if frequency.interval is custom.

Period between payments.

Min value: 1
Max value: 366

No - for unscheduled MITs

Yes - for recurring payments with custom interval.

recurrence.endDate

Date format. Last date of recurring payment. Only future date can be used. No longer than 4 years from the date of a request.

No

For complete working sample, please check Pre-request script of Initiate Payment API in our Postman collection.

Request example:

POST /merchant/payments HTTP/1.1
Host: api2-stage.connectpay.com

X-Request-ID: ce9db1f3-4c19-4447-a717-0239b15bb049
Accept: application/json;version=2
Content-Type: application/json
X-Signature: IzfqLFmHTkszikfbJ9fJgJDAI9uD+fVHoS9pPGl3avBJ5nZKuaxQsqLlwDwNGRfMCHHwP/9q+cP9DLahwLGkSI1e61I1TLxeVINcflyehypdF5rtEL/Xx5TguHdXgLqV60hVME0BArB1jAro8imAoey9sDkxfuyesm3bizqyYwVTVLKbpCX5tBrcOVbRC6MboG9z+H6jqGLBJSCxMz3QTzQ7ieWb0woW0Ex/AyHW5UN3vrBwPnlOBbTovWe82dklia7xAIpiL6mhzGz5JCwmscVcUqhv9sxOwXxhHCBydM0Xal7WiRWmJ0fd0It+V6uoJYW7RldmTRvjK84EwFULcA==
Authorization: Basic NTQxOThmNTItN2Q5Mi0zZjk4LTk5ZmEtOTE5OTE2NWEzZDQ3OjdmMGVhYjExLWVjZDEtM2UwZi05OTgzLWQ3OWIwNjYyYTZkYw==
{
    "merchant": {
        "brandId": "6ce66290-71a3-4376-be87-77f16cf6fe19",
        "redirectUrl": "https://localhost",
        "notificationUrl": "https://localhost",
        "language": "EN"
    },
    "payment": {
        "paymentMethod": ["CARD"],
        "providerCountryCode": "LT",
        "debtorName": "Wehner, Padberg and Pfannerstill",
        "instructedAmount": {
            "amount": "10.23",
            "currency": "EUR"
        },
        "remittanceInformationUnstructured": "Multi-tiered global leverage"
    },
    "recurrence": {
        "type": "recurring",
        "frequency": {
            "interval": "custom",
            "days": 15
        },
        "endDate":"2022-12-11"
    },
    "identifiers": {
        "merchantReference": "a983cef4-4969-487a-b7fb-0308e2038d27",
        "endToEndId": "3zNK8E5NpDsVrYdUknF988RPud",
    },
    "consumer": {
        "firstName": "Darrel",
        "lastName": "Keeling",
        "ipAddress": "235.114.187.1",
        "phoneNo": "37066666666",
        "email": "customer-email@domain.com"
    }
}

Receive recurrence ID

After payment initiation, you’ll receive recurrence ID in Initiate payment API response. Use it for further subsequent payments.

Response example:

{
  "merchant": {
    "generic1": "B2C",
    "generic2": "infomediaries",
    "generic3": "visualize"
  },
  "payment": {
    "paymentId": "44812d69-2cac-45b8-a866-02057a973a1f",
    "redirectUrl": "https://pay-stage.connectpay.com?key=eca83a69-6005-48e9-a36f-a35886f53a2c",
    "recurrenceId": "700f6eda-1af5-4a77-9605-988845aac875"
  }
}

Unscheduled MITs

For subsequent merchant-initiated transactions (cardholder is not present) you’ll need to use our recurrence ID and dedicated Initiate Recurring Payment API. Valid recurrence ID allows you to initiate a payment based on cardholder’s consent without him/her being present.

You can change payment amount, description, reference.

A. If you are a single merchant, use this PATH: /merchant/recurrences/{RecurrenceId} and authorization requirements provided here.

B. If you are a platform using BaaS APIs, use this PATH: baas/merchant/recurrences/{RecurrenceId} and authorization requirements provided here.

Request example:

POST 'https://.connectpay.com/merchant/recurringpayments/' \
--header 'X-Request-ID: e2d91614-0738-461f-913b-ce11bae4ce83' \
--header 'Accept: application/json;version=1' \
--header 'Content-Type: application/json' \
--header 'X-Signature;' \
--header 'Authorization;' \
--data-raw '{
	"merchant": {
		"generic1": "dot-com",
		"generic2": "partnerships",
		"generic3": "repurpose"
	},
	"payment": {
		"instructedAmount": {
			"amount": "3.23",
			"currency": "EUR"
		},
		"remittanceInformationUnstructured": "Secured local migration"
	},
	"identifiers": {
		"merchantReference": "a239fc82-5a1b-448a-98cc-7dfc54656b84",
		"endToEndId": "3DAYfukinBVaqVW7SJVNjq2hDW"
	}
}'

Response example:

{
   "payment": {
    "paymentId": "ea969247-c1f8-4169-9ea6-2497e3bff6bc"
  }
}

To check payment status, use Get Payment details API with paymentId provided in a response.

Scheduled recurring payments (subscriptions)

Scheduled card payments are initiated by merchant gateway following recurrence details you provided to us in initial’s payment request. You don’t need to create a separate request. After a payment is initiated, we will send you a notification with payment details.

Recurrence details

To receive all payments related to particular recurrence ID, please call Get Recurrence Details API using recurrenceId received in initial’s payment response. With this API you will be able to see how many payments were initiated with one recurrence ID, what is the status of that recurrence ID and all previous historical payments.

A. If you are a single merchant, use this PATH: /merchant/recurrences/{RecurrenceId} and authorization requirements provided here.

B. If you are a platform using BaaS APIs, use this PATH: baas/merchant/recurrences/{RecurrenceId} and authorization requirements provided here.

Response example:

{
  "recurrence": {
    "type": "unscheduled",
    "initialpaymentId": "3c0e3876-caaf-41d1-9714-e8f7377fda8d"
  },
  "payments": [
    {
      "merchant": {
        "generic1": "ubiquitous",
        "generic2": "portals",
        "generic3": "leverage"
      },
      "payment": {
        "paymentMethod": "CARD",
        "providerName": "VISA",
        "creditorAccount": {
          "iban": "LT833740020000000846"
        },
        "creditorName": "Gravelbox Inc.",
        "instructedAmount": {
          "amount": "1.23",
          "currency": "EUR"
        },
        "remittanceInformationUnstructured": "Up-sized mobile website",
        "debtorAccount": {}
      },
      "recurrence": {
        "type": "unscheduled",
        "initialpaymentId": "3c0e3876-caaf-41d1-9714-e8f7377fda8d",
        "recurrenceId": "867e6964-5b40-4ad2-a2fa-375ff03ba569"
      },
      "identifiers": {
        "merchantReference": "ef7c5ebd-5b24-4ec4-ab1a-98f82d93f96f",
        "creditorReference": "RF12334567",
        "endToEndId": "17UVnDTzDQFNbW7m5w4Ft8imxgB"
      },
      "consumer": {
        "firstName": "Alfreda",
        "lastName": "Will",
        "consumerId": "dbf23d50-236e-4adc-8924-c4069800a355",
        "ipAddress": "219.197.116.8",
        "email": "asdf@0x6d6a.com"
      },
      "status": {
        "isTerminal": true,
        "createdAt": "2022-11-24T12:05:49.220Z",
        "code": "Approved",
        "lastUpdatedAt": "2022-11-24T12:09:10.000Z",
        "details": {
          "providerStatusCode": null,
          "providerMessage": null,
          "errorMessage": null
        }
      }
    }
  ]
}
Undefined