Version: 10.9.x

Recurrent Payments

A recurrent payment is a payment strategy that splits a whole payment across multiple installments, whose only the first one requires an interaction with the client (its authorization). An example of such payment strategy is paying monthly for a season ticket that covers one year.

Recurrent Payments Support

In the following table are reported which payment providers support recurrent payments strategy alongside which of their payments methods are enabled for it.

Provider	credit-cards	pay-pal	stripe
gestpay (Axerve)	✓	✓
satispay
unicredit
braintree
scalapay
safecharge
soisy
stripe			✓

How it works

Using an enabled provider, a client executes an initial payment where they also authorize the underlying system to perform future payments on their behalf, using the same details of the initial payment. This grant is defined through a token generated by the payments provider once the initial payment is successfully completed and returned to the payment system.

To achieve such behavior it is possible to exploit the endpoint dedicated to recurrent payments, that is

POST /{provider}/{payment-method}/pay/recurrent

This endpoint requires a payload as input, which extends the one of standard payments by adding the recurrentDetails property, which describes how the recurrence strategy should be configured. Recurrence strategy configuration depends on the adopted payment method. However, there is a single property that is shared across all the payment object, which is isFirstInstallment. This property is important to distinguish whether current payment is the initial or a subsequent one. Depending on its value, which can be either true or false respectively, different logics are applied to the request.

note

For an in-depth explanation of each possible request payload it is recommended to read the section dedicated to payment method of interest.

Recurrent Payment With Credit Cards

In this section it is provided an example of how a recurrent payment can be executed using gestpay provider and credit card as payment method.

Initial Payment

To initiate a recurrent payment with credit cards it is required to define in recurrenceDetails object the following properties:

isFirstInstallment: set to true to specify that it is the initial payment
expiresOn: date after which no further transaction shall be performed.
installmentAmount: the amount of money that should be paid in this installment. If not specified it defaults to the one of initial payment.
installmentFrequencyInDays: it indicates the minimum number of days between two transactions of the same plan

Request example:

curl --location --request POST 'http://pgm-base-url/gestpay/credit-cards/pay/recurrent' \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "amount": "2",
      "creditCardToken": "TOKEN-5340971",
      "shopTransactionID": "order-test-pgm-2022-06-17T14:55:43.685Z"
      "recurrenceDetails": {
        "expiresOn": "2022-07-01",
        "installmentAmount": "2",
        "installmentFrequencyInDays": 7,
        "isFirstInstallment": true
      },
    }'

Response example:

{
    "result": "REDIRECT_TO_URL",
    "resultDescription": "8006 Verify By Visa",
    "paymentID": "3289454367809",
    "redirectToUrl": "https://sandbox.gestpay.net/pagam/pagam3d.aspx?a=GESPAY89958&b=717aec0b-014e-4a6b-b4d2-86e9eff2d690&axerve3D=True&IsLightBox=False"
}

where the redirectToUrl is the url where the user should be redirected to end the payment.

Subsequent Payment

In order to execute a subsequent payment it is necessary to specify in the recurrenceDetails object only the following details:

isFirstInstallment, which must be set to false to notify that current payment is a subsequent one
previousPaymentID, which is set to the same value of the paymentID extracted from the response body of a previous payment

Request example:

curl --location --request POST 'http://pgm-base-url/gestpay/credit-cards/pay/recurrent' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "amount": "2",
    "creditCardToken": "TOKEN-5340971",
    "recurrenceDetails": {
      "isFirstInstallment": false,
      "previousPaymentID": "3289454367809"
    },
    "shopTransactionID": "order-test-pgm-2022-06-17T15:02:22.815Z"
  }'

Response example:

{
    "result": "OK",
    "resultDescription": "0 Transazione correttamente effettuata",
    "paymentID": "3289454367810"
}

Recurrent Payment With PayPal

In this section it is provided an example of how a recurrent payment can be executed using gestpay provider and PayPal as payment method.

Initial Payment

To initiate a recurrent payment with PayPal it is required to define in recurrenceDetails object only the isFirstInstallment, setting it to true to specify that it is the initial payment. Moreover, for PayPal recurrent payments it is necessary to specify the field payPalDescription in the root of request body. That attribute is employed to describe the recurrence payment and it is employed by the provider to distinguish a recurrent payment from a single one (where payPalDescription is not provided).

Request Example:

curl --location --request POST 'http://pgm-base-url/gestpay/pay-pal/pay/recurrent' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": "0.05",
  "recurrenceDetails": {
    "isFirstInstallment": true
  },
  "payPalDescription": "What about second breakfast?",
  "shopTransactionID": "order-test-pgm-2022-06-21T16:29:56.565Z"
}'

Response example:

{
    "result": "REDIRECT_TO_URL",
    "resultDescription": "",
    "paymentID": "116816595849",
    "redirectToUrl": "https://sandbox.gestpay.net/pagam/AxePay.aspx?a=GESPAY89958&b=cb0b4812-b87e-4a89-a140-8c565a51cf8c&paymentType=PAYPAL&singlePayment=true"
}

In order to pay the user must be redirected to the url set in redirectToUrl response property. There, they will be able to complete the procedure through PayPal interface. Once the payment is terminated, PayPal will call the specified webhook to notify of the payment status. It is important to define as callback URL the /gestpay/callback endpoint of your Payment Gateway Manager instance, so that your service can be notified with the important data necessary to perform subsequent payments

Callback data example

{
  "isSuccessful": true,
  "methodToken": "PAYPAL-TOKEN",
  "paymentID": "116782595249",
  "paymentType": "UNKNOWN",
  "providerName": "GESTPAY",
  "resultDescription": "Transaction correctly processed",
  "shopTransactionID": "order-test-pgm-2022-06-21T16:29:56.565Z"
}

Aside whether the payment was carried out successfully, it is important to extract from the callback data the methodToken. Such value is necessary to perform all the future payments in the recurrence.

Subsequent Payment

In order to execute a subsequent payment it is necessary to specify in the recurrenceDetails object only the following details:

isFirstInstallment, which must be set to false to notify that current payment is a subsequent one
recurrenceToken, which is extracted from the callback data, where it is referenced as methodToken

Request example:

curl --location --request POST 'http://pgm-base-url/gestpay/pay-pal/pay/recurrent' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": "0.05",
  "recurrenceDetails": {
    "isFirstInstallment": false,
    "recurrenceToken": "PAYPAL-TOKEN"
  },
  "shopTransactionID": "order-test-pgm-2022-06-21T16:40:19.252Z"
}'

Response example:

{
    "result": "REDIRECT_TO_URL",
    "resultDescription": "0 Transazione correttamente effettuata",
    "paymentID": "191108595850",
    "redirectToUrl": "https://sandbox.gestpay.net/pagam/isprisp.aspx"
}