Recurring Payments API

The recurring payments API allows you, with an explicit authorization (preapproval) from your customers, to charge them any time that is needed, without the buyers having to perform a new payment flow for each new purchase.

The payment methods that support recurring payments are: MercadoPago (46), QIWI Wallet (1003), SEPA Direct Debit (84), Cards (69), Klarna Invoice (75) and Skrill 1-TAP (78).

For MercadoPago (46), QIWI Wallet (1003) and SEPA Direct Debit (84) you can initiate recurring payments by creating first a preapproval approved by the customer. Having an open preapproval, means you have the possibility to charge the customer when and how many times it is necessary. This authorization is valid until the customer or you revoke this preapproval/authorization.

For Cards (69) and Klarna Invoice (75), you do not need a preapproval, you only need to send in the preapprovalID field the initial GlobalPay PaymentID received in notification of the initial successful one-off payment that the customer has made. To initiate a recurring payment for Cards (69) and Klarna Invoice (75), please skip to Create a Recurring Payment.

For Skrill 1-TAP (78), you do not need to create a preapproval. After the first successful one-off payment, you will receive a Notification from our system containing the Preapproval ID which you need to use for recurring payments. In order to see a full example of a payment request and all the parameters needed for Skrill 1-TAP payment method go to our section Skrill 1-TAP Payment Request.

A typical recurring payment scenario via GlobalPay for the alternative payment methods MercadoPago (46), Qiwi Wallet (1003) and SEPA Direct Debit (84) is described next:

  1. The merchant creates a preapproval in GlobalPay and redirects the customer to GlobalPay.
  2. GlobalPay is redirecting the customer to provider.
  3. The customer enters the data specific to each payment method and approves the automatic debit.
  4. The customer is redirected to the returnURL specified by the merchant.
  5. GlobalPay notifies you about the preapproval status.
  6. Having an open preapproval, you can instruct GlobalPay system to charge the customer, whenever it is necessary (e.g. immediately or according to a subscription plan that the customer approved on your website), by only specifying the amount and currency.
  7. GlobalPay notifies you about the recurring payment status.

You need to work with two types of resources: preapprovals and recurring payments.

Create a Preapproval

Definition: POST /v1/preapprovals

To initiate a preapproval, you must create a preapproval object. The parameters of the preapproval are sent in the message body as a JSON object. Below you can see 2 examples of a preapproval request: one for MercadoPago (46) and one for SEPA Direct Debit (84).

  • Checkout the below example of a preapproval request for MercadoPago (46):

    A 201 HTTP response (Created) is returned if the payment was correctly initialized.

    Request:

    POST https://paytest.smart2pay.com/v1/preapprovals
    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
    
    {
     "Preapproval": {
       "MerchantPreapprovalID": "s2ptest_g107",
       "Description": "1 year subscription",
       "ReturnURL": "http://demo.smart2pay.com/redirect.php",
       "MethodID": 46, 
       "Customer": {
          "FirstName": "John",
          "LastName": "Doe",
          "Email": "test_user_83022133@testuser.com",
          "Phone": "0765260000"
         },
       "BillingAddress": {
          "Street": "Tonelero",
          "StreetNumber": "1",
          "ZipCode": "23900-000",
          "City": "Rio de Janeiro",
          "Country": "BR"
          }
       }
    }

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
      "Preapproval": {
        "ID": 4217,
        "Created": "20170804065155",
        "MethodID": 46,
        "SiteID": 30201,
        "MerchantPreapprovalID": "s2ptest_g107",
        "RecurringPeriod": 0,
        "PreapprovedMaximumAmount": null,
        "Currency": null,
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "1 year subscription",
        "Customer": {
          "ID": 3627,
          "MerchantCustomerID": null,
          "Email": "test_user_83022133@testuser.com",
          "FirstName": "John",
          "LastName": "Doe",
          "Gender": null,
          "SocialSecurityNumber": null,
          "Phone": "0765260000",
          "Company": null,
          "DateOfBirth": null
        },
        "BillingAddress": {
          "ID": 1257,
          "City": "Rio de Janeiro",
          "ZipCode": "23900-000",
          "State": null,
          "Street": "Tonelero",
          "StreetNumber": "1",
          "HouseNumber": null,
          "HouseExtension": null,
          "Country": "BR"
        },
        "Status": {
          "ID": 1,
          "Info": "Pending",
          "Reasons": null
        },
        "RedirectURL": "https://europaytest.smart2pay.com/MercadoPago2/Landing/PreapprovalLanding.aspx?ID=628&Hash=47CEEF7559CDD192E188D91F0C7B7978",
        "MethodOptionID": 0,
        "PreapprovedFrequency": null,
        "MandateReference": null
      }
    }

    Redirect the customer to the RedirectURL where he will approve the automatic debit.

  • Checkout the below example of a preapproval request for SEPA Direct Debit (84):

    For SEPA Direct Debit preapproval requests MethodOptionID parameter is mandatory to be sent in the initial payment request.

    Please note that if you have a Company, you also need to send the Company parameter in the request.

    A 201 HTTP response (Created) is returned if the payment was correctly initialized.

    Request: 

    POST https://paytest.smart2pay.com/v1/preapprovals
    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
    
    {
      "Preapproval": {
        "MerchantPreapprovalID": "s2ptest_h11",
        "Description": "SEPA DD preapproval request",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "MethodID": 84,
        "Customer": {
          "FirstName": "John",
          "LastName": "Doe",
          "Email": "youremail@gmail.com",
          "Phone": "+31651111111"
        },
        "BillingAddress": {
          "Street": "Brink",
          "StreetNumber": "27c",
          "ZipCode": "1251",
          "City": "Laren",
          "Country": "NL"
        },
        "MethodOptionID": 1
      }
    }

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
        "Preapproval": {
            "ID": 13199,
            "Created": "20181101142508",
            "MethodID": 84,
            "SiteID": 30201,
            "MerchantPreapprovalID": "s2ptest_h11",
            "RecurringPeriod": 0,
            "PreapprovedMaximumAmount": null,
            "Currency": null,
            "ReturnURL": "http://demo.smart2pay.com/redirect.php",
            "Description": "SEPA DD preapproval request",
            "Customer": {
                "ID": 135127,
                "MerchantCustomerID": null,
                "Email": "youremail@gmail.com",
                "FirstName": "John",
                "LastName": "Doe",
                "Gender": null,
                "SocialSecurityNumber": null,
                "SocialSecurityNumber2": null,
                "Phone": "+31651111111",
                "Company": null,
                "DateOfBirth": null
            },
            "BillingAddress": {
                "ID": 5103,
                "City": "Laren",
                "ZipCode": "1251",
                "State": null,
                "Street": "Brink",
                "StreetNumber": "27c",
                "HouseNumber": null,
                "HouseExtension": null,
                "Country": "NL"
            },
            "Status": {
                "ID": 1,
                "Info": "Pending",
                "Reasons": null
            },
            "RedirectURL": "https://europaytest.smart2pay.com/SlimPay/Landing/PreapprovalLanding.aspx?ID=10084&Hash=CD71CA781BD1F59F52F8F0B2D20A807E",
            "MethodOptionID": 1,
            "PreapprovedFrequency": null,
            "MandateReference": null
        }
    }

    Redirect the customer to the RedirectURL where he will approve the automatic debit. Once the Customer approves the debit, he will receives via email the digital signed mandate.

Preapproval Notification

Upon successful approval, we will notify you about the new status of the preapproval to the URL you setup in the Merchant Dashboard.

You need to respond with HTTP Status 204 (No Content)!

Preapproval notification format for MercadoPago:

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Preapproval": {
    "ID": 4217,
    "Created": "20170804065155",
    "MethodID": 46,
    "SiteID": 30201,
    "MerchantPreapprovalID": "s2ptest_g107",
    "RecurringPeriod": 0,
    "PreapprovedMaximumAmount": null,
    "Currency": null,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "1 year subscription",
    "Customer": {
      "ID": 3627,
      "MerchantCustomerID": null,
      "Email": "test_user_83022133@testuser.com",
      "FirstName": "John",
      "LastName": "Doe",
      "Gender": null,
      "SocialSecurityNumber": null,
      "Phone": "0765260000",
      "Company": null,
      "DateOfBirth": null
    },
    "BillingAddress": {
      "ID": 1257,
      "City": "Rio de Janeiro",
      "ZipCode": "23900-000",
      "State": null,
      "Street": "Tonelero",
      "StreetNumber": "1",
      "HouseNumber": null,
      "HouseExtension": null,
      "Country": "BR"
    },
    "Status": {
      "ID": 2,
      "Info": "Open",
      "Reasons": null
    },
    "RedirectURL": null,
    "MethodOptionID": 0,
    "PreapprovedFrequency": null,
    "MandateReference": null
  }
}

Response:

204 No Content

Preapproval notification format for SEPA Direct Debit:

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Preapproval": {
    "ID": 13199,
    "Created": "20181101142508",
    "MethodID": 84,
    "SiteID": 30201,
    "MerchantPreapprovalID": "s2ptest_h11",
    "RecurringPeriod": 0,
    "PreapprovedMaximumAmount": null,
    "Currency": null,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "SEPA DD preapproval request",
    "Customer": {
      "ID": 135127,
      "MerchantCustomerID": null,
      "Email": "youremail@gmail.com",
      "FirstName": "John",
      "LastName": "Doe",
      "Gender": null,
      "SocialSecurityNumber": null,
      "SocialSecurityNumber2": null,
      "Phone": "+31651111111",
      "Company": null,
      "DateOfBirth": null
    },
    "BillingAddress": {
      "ID": 5103,
      "City": "Laren",
      "ZipCode": "1251",
      "State": null,
      "Street": "Brink",
      "StreetNumber": "27c",
      "HouseNumber": null,
      "HouseExtension": null,
      "Country": "NL"
    },
    "Status": {
      "ID": 2,
      "Info": null,
      "Reasons": null
    },
    "RedirectURL": null,
    "MethodOptionID": 0,
    "PreapprovedFrequency": null,
    "MandateReference": "SLMP004606504"
  }
}

Response:

204 No Content

The message contains a Preapproval object with an updated Status, which can have the following meanings:

PREAPPROVAL STATUS
ID Info Description
1 Pending The customer needs to confirm the preapproval
2 Open The customer confirmed and you can use the preapproval to initiate recurring payments
4 ClosedByCustomer The preapproval is closed and can no longer be used to initiate recurring payments

Change a Preapproval

Definition: PATCH /v1/preapprovals/{id}

Where:
  • {id} – GlobalPay Preapproval ID

You can change the attributes of an already created preapproval by applying a PATCH.

Request:

PATCH https://paytest.smart2pay.com/v1/preapprovals/4217
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
 "Preapproval": {
   "MerchantPreapprovalID": "s2ptest_g107",
   "Description": "1 year subscription update1",
   "ReturnURL": "http://demo.smart2pay.com/redirect.php",
   "MethodID": 46, 
   "Customer": {
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "test_user_83022133@testuser.com",
      "Phone": "0765260000"
     },
   "BillingAddress": {
      "Street": "Tonelero",
      "StreetNumber": "1",
      "ZipCode": "23900-000",
      "City": "Rio de Janeiro",
      "Country": "BR"
      }
   }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "Preapproval": {
    "ID": 4217,
    "Created": "20170804065155",
    "MethodID": 46,
    "SiteID": 30201,
    "MerchantPreapprovalID": "s2ptest_g107",
    "RecurringPeriod": 0,
    "PreapprovedMaximumAmount": null,
    "Currency": null,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "1 year subscription update1",
    "Customer": {
      "ID": 3627,
      "MerchantCustomerID": null,
      "Email": "test_user_83022133@testuser.com",
      "FirstName": "John",
      "LastName": "Doe",
      "Gender": null,
      "SocialSecurityNumber": null,
      "Phone": "0765260000",
      "Company": null,
      "DateOfBirth": null
    },
    "BillingAddress": {
      "ID": 1257,
      "City": "Rio de Janeiro",
      "ZipCode": "23900-000",
      "State": null,
      "Street": "Tonelero",
      "StreetNumber": "1",
      "HouseNumber": null,
      "HouseExtension": null,
      "Country": "BR"
    },
    "Status": {
      "ID": 2,
      "Info": "Open",
      "Reasons": null
    },
    "RedirectURL": "https://europaytest.smart2pay.com/MercadoPago2/Landing/PreapprovalLanding.aspx?ID=628&Hash=47CEEF7559CDD192E188D91F0C7B7978",
    "MethodOptionID": 0,
    "PreapprovedFrequency": null,
    "MandateReference": null
  }
}

Close a Preapproval

Definition: DELETE /v1/preapprovals/{id}

Where:
  • {id} – GlobalPay Preapproval ID

To close a preapproval, you must send a DELETE action for an existing preapproval object. See below our 2 examples for closing a preapproval for MercadoPago (46) and SEPA Direct Debit (84).

    • Checkout the below example to close a preapproval for MercadoPago (46):

      Request:

      DELETE https://paytest.smart2pay.com/v1/preapprovals/4217
      Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

      Response:

      HTTP/1.1 200 OK
      Content-Type: application/json; charset=utf-8
      
      {
        "Preapproval": {
          "ID": 4217,
          "Created": "20170804065155",
          "MethodID": 46,
          "SiteID": 30201,
          "MerchantPreapprovalID": "s2ptest_g107",
          "RecurringPeriod": 0,
          "PreapprovedMaximumAmount": null,
          "Currency": null,
          "ReturnURL": "http://demo.smart2pay.com/redirect.php",
          "Description": "1 year subscription update1",
          "Customer": {
            "ID": 3627,
            "MerchantCustomerID": null,
            "Email": "test_user_83022133@testuser.com",
            "FirstName": "John",
            "LastName": "Doe",
            "Gender": null,
            "SocialSecurityNumber": null,
            "Phone": "0765260000",
            "Company": null,
            "DateOfBirth": null
          },
          "BillingAddress": {
            "ID": 1257,
            "City": "Rio de Janeiro",
            "ZipCode": "23900-000",
            "State": null,
            "Street": "Tonelero",
            "StreetNumber": "1",
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "BR"
          },
          "Status": {
            "ID": 4,
            "Info": "ClosedByCustomer",
            "Reasons": null
          },
          "RedirectURL": null,
          "MethodOptionID": 0,
          "PreapprovedFrequency": null,
          "MandateReference": null
        }
      }
    • Checkout the below example to close a preapproval for SEPA Direct Debit (84):

      Request:

      DELETE https://paytest.smart2pay.com/v1/preapprovals/12351
      Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

      Response:

      HTTP/1.1 200 OK
      Content-Type: application/json; charset=utf-8
      
      {
        "Preapproval": {
          "ID": 12351,
          "Created": "20180912102819",
          "MethodID": 84,
          "SiteID": 30201,
          "MerchantPreapprovalID": "s2ptest_f102",
          "RecurringPeriod": 0,
          "PreapprovedMaximumAmount": null,
          "Currency": null,
          "ReturnURL": "http://demo.smart2pay.com/redirect.php",
          "Description": "SEPA DD preapproval request",
          "Customer": {
            "ID": 114724,
            "MerchantCustomerID": null,
            "Email": "youremail@gmail.com",
            "FirstName": "John",
            "LastName": "Smith",
            "Gender": null,
            "SocialSecurityNumber": null,
            "SocialSecurityNumber2": null,
            "Phone": "+4976526000",
            "Company": "Smart2Pay",
            "DateOfBirth": null
            },
          "BillingAddress": {
            "ID": 4796,
            "City": "Oyenhausen",
            "ZipCode": "32547",
            "State": null,
            "Street": "Schulstrasse",
            "StreetNumber": "4",
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "DE"
            },
          "Status": {
            "ID": 4,
            "Info": "ClosedByCustomer",
            "Reasons": null
            },
          "RedirectURL": null,
          "MethodOptionID": 0,
          "PreapprovedFrequency": null,
          "MandateReference": null
        }
      }

Get information on a specific Preapproval

You can get more information about a specific Preapproval by using an action based on GET HTTP request.

Definition: GET /v1/preapprovals/{id}

Where:
  • {id} – GlobalPay Preapproval ID

Request:

GET https://paytest.smart2pay.com/v1/preapprovals/4217
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "Preapproval": {
    "ID": 4217,
    "Created": "20170804065155",
    "MethodID": 46,
    "SiteID": 30201,
    "MerchantPreapprovalID": "s2ptest_g107",
    "RecurringPeriod": 0,
    "PreapprovedMaximumAmount": null,
    "Currency": null,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "1 year subscription update1",
    "Customer": {
      "ID": 3627,
      "MerchantCustomerID": null,
      "Email": "test_user_83022133@testuser.com",
      "FirstName": "John",
      "LastName": "Doe",
      "Gender": null,
      "SocialSecurityNumber": null,
      "Phone": "0765260000",
      "Company": null,
      "DateOfBirth": null
    },
    "BillingAddress": {
      "ID": 1257,
      "City": "Rio de Janeiro",
      "ZipCode": "23900-000",
      "State": null,
      "Street": "Tonelero",
      "StreetNumber": "1",
      "HouseNumber": null,
      "HouseExtension": null,
      "Country": "BR"
    },
    "Status": {
      "ID": 2,
      "Info": "Open",
      "Reasons": null
    },
    "RedirectURL": null,
    "MethodOptionID": 0,
    "PreapprovedFrequency": null,
    "MandateReference": null
  }
}

Get all payments associated with a preapproval

You can get all payments associated with a Preapproval by using an action based on GET HTTP request.

Definition: GET /v1/preapprovals/{id}/payments

Where:
  • {id} – GlobalPay Preapproval ID

Request:

GET https://paytest.smart2pay.com/v1/preapprovals/4217/payments
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "Payments": [
  {
    "ID": 3009284,
    "SkinID": null,
    "ClientIP": null,
    "Created": "20170804070219",
    "MerchantTransactionID": "aaaaaaaaaaaaaaa1-_AA",
    "OriginatorTransactionID": null,
    "Amount": "100",
    "Currency": "BRL",
    "CapturedAmount": null,
    "ReturnURL": "",
    "Description": null,
    "MethodID": 46,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": 30201,
    "NotificationDateTime": "20170804070222",
    "Customer": null,
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Details": null,
    "ReferenceDetails": null,
    "CustomParameters": null,
    "PreapprovalID": 4217,
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": null
      },
    "MethodTransactionID": null,
    "TokenLifetime": null,
    "Capture": null,
    "PreapprovalDetails": null,
    "RedirectURL": null
    },
    {
    "ID": 3009283,
    "SkinID": null,
    "ClientIP": null,
    "Created": "20170804065834",
    "MerchantTransactionID": "s2ptest_fg109",
    "OriginatorTransactionID": null,
    "Amount": "100",
    "Currency": "BRL",
    "CapturedAmount": null,
    "ReturnURL": "",
    "Description": null,
    "MethodID": 46,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": 30201,
    "NotificationDateTime": "20170804065838",
    "Customer": null,
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Details": null,
    "ReferenceDetails": null,
    "CustomParameters": null,
    "PreapprovalID": 4217,
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": null
      },
    "MethodTransactionID": null,
    "TokenLifetime": null,
    "Capture": null,
    "PreapprovalDetails": null,
    "RedirectURL": null
    },
    {
    "ID": 3009261,
    "SkinID": null,
    "ClientIP": null,
    "Created": "20170804065721",
    "MerchantTransactionID": "s2ptest_g108",
    "OriginatorTransactionID": null,
    "Amount": "100",
    "Currency": "BRL",
    "CapturedAmount": null,
    "ReturnURL": "",
    "Description": null,
    "MethodID": 46,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": 30201,
    "NotificationDateTime": "20170804070800",
    "Customer": null,
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Details": null,
    "ReferenceDetails": null,
    "CustomParameters": null,
    "PreapprovalID": 4217,
    "Status": {
      "ID": 4,
      "Info": "Failed",
      "Reasons": null
      },
    "MethodTransactionID": null,
    "TokenLifetime": null,
    "Capture": null,
    "PreapprovalDetails": null,
    "RedirectURL": null
    }
    ],
    "Count": 3,
    "TotalPages": 1,
    "TotalCount": 3,
    "PageIndex": 1,
    "PageSize": 10
}

Get a list of preapprovals

You can get information about all the Preapprovals you have created per SiteID by using an action based on GET HTTP request. Please be aware that only a limited amount of details for each preapproval will be provided.

The default number of preapprovals returned by this request is 50, but you can get a customized list of preapprovals by adding the limit parameter to the URL.

Definition: GET /v1/preapprovals

Request:

GET https://paytest.smart2pay.com/v1/preapprovals
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "Preapprovals": [
    {
      "ID": 4217,
      "Created": "20170804065155",
      "MethodID": 46,
      "SiteID": 30201,
      "MerchantPreapprovalID": "s2ptest_g107",
      "RecurringPeriod": 0,
      "PreapprovedMaximumAmount": null,
      "Currency": null,
      "ReturnURL": "http://demo.smart2pay.com/redirect.php",
      "Description": "1 year subscription update1",
      "Customer": null,
      "BillingAddress": null,
      "Status": {
        "ID": 2,
        "Info": "Open",
        "Reasons": null
      },
      "RedirectURL": null,
      "MethodOptionID": 0,
      "PreapprovedFrequency": null,
      "MandateReference": null
    },
    {
      "ID": 4103,
      "Created": "20170714123423",
      "MethodID": 78,
      "SiteID": 30201,
      "MerchantPreapprovalID": "1122991392222",
      "RecurringPeriod": 0,
      "PreapprovedMaximumAmount": "500",
      "Currency": "EUR",
      "ReturnURL": null,
      "Description": "PreapprovalDescription",
      "Customer": null,
      "BillingAddress": null,
      "Status": {
        "ID": 2,
        "Info": "Open",
        "Reasons": null
      },
      "RedirectURL": null,
      "MethodOptionID": 0,
      "PreapprovedFrequency": null,
      "MandateReference": null
    },
    {
      "ID": 1744,
      "Created": "20160913144228",
      "MethodID": 46,
      "SiteID": 30201,
      "MerchantPreapprovalID": "s2ptest_f25",
      "RecurringPeriod": 0,
      "PreapprovedMaximumAmount": null,
      "Currency": null,
      "ReturnURL": "http://demo.smart2pay.com/redirect.php",
      "Description": "1 year subscription update1",
      "Customer": null,
      "BillingAddress": null,
      "Status": {
        "ID": 4,
        "Info": "ClosedByCustomer",
        "Reasons": null
      },
      "RedirectURL": null,
      "MethodOptionID": 0,
      "PreapprovedFrequency": null,
      "MandateReference": null
    },
    {
      "ID": 1743,
      "Created": "20160913120451",
      "MethodID": 46,
      "SiteID": 30201,
      "MerchantPreapprovalID": "s2ptest_f23",
      "RecurringPeriod": 0,
      "PreapprovedMaximumAmount": null,
      "Currency": null,
      "ReturnURL": "http://demo.smart2pay.com/redirect.php",
      "Description": "1 year subscription",
      "Customer": null,
      "BillingAddress": null,
      "Status": {
        "ID": 4,
        "Info": "ClosedByCustomer",
        "Reasons": null
      },
      "RedirectURL": null,
      "MethodOptionID": 0,
      "PreapprovedFrequency": null,
      "MandateReference": null
    }
  ]
}

Create a Recurring Payment

Definition: POST /v1/payments/recurrent

A recurring payment is created in the same manner a one-off payment is created. In addition, you need to send the PreapprovalID (the PreapprovalID or Mandate received when you created/opened a preapproval) and the information specific to each payment method.

For recurring Card payments (69) and Klarna Invoice (75), you do not need a preapproval, you only need to send in the preapprovalID field the initial GlobalPay PaymentID.

If you want to get more information about a recurring payment you can use the same actions like for a one-off payment. Please check Get information on a specific payment, for more details.

  • Checkout the below example of a recurring payment request for MercadoPago (46):

    Request:

    POST https://paytest.smart2pay.com/v1/payments/recurrent
    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
    
    {
     "Payment": {
       "PreapprovalID":4217,
       "MerchantTransactionID": "s2ptest_fg109",
       "Amount": 100,
       "Currency": "BRL",
       "MethodID": 46,
       "Customer": {  
         "Email" : "test_user_83022133@testuser.com"
        },
       "BillingAddress":{
         "Country": "BR"
          }
       }
    }

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
      "Payment": {
        "ID": 3009283,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20170804065834",
        "MerchantTransactionID": "s2ptest_fg109",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "BRL",
        "CapturedAmount": null,
        "ReturnURL": null,
        "Description": "",
        "MethodID": 46,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30201,
        "NotificationDateTime": null,
        "Customer": {
          "ID": 1196,
          "MerchantCustomerID": null,
          "Email": "test_user_83022133@testuser.com",
          "FirstName": null,
          "LastName": null,
          "Gender": null,
          "SocialSecurityNumber": null,
          "Phone": null,
          "Company": null,
          "DateOfBirth": null
        },
        "BillingAddress": {
          "ID": 335,
          "City": null,
          "ZipCode": null,
          "State": null,
          "Street": null,
          "StreetNumber": null,
          "HouseNumber": null,
          "HouseExtension": null,
          "Country": "BR"
        },
        "ShippingAddress": null,
        "Articles": null,
        "Details": null,
        "ReferenceDetails": null,
        "CustomParameters": null,
        "PreapprovalID": 4217,
        "Status": {
          "ID": 2,
          "Info": "Success",
          "Reasons": null
        },
        "MethodTransactionID": null,
        "TokenLifetime": null,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": null
      }
    }

    In case of an API error, an HTTP 4xx (you did something wrong) or HTTP 5xx (we did something wrong) response is returned.

    For more information about the reasons of a wrong request response see our section GlobalPay Return Codes.

    Request:

    POST https://paytest.smart2pay.com/v1/payments/recurrent
    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
    
    {
     "Payment": {
       "PreapprovalID":4217,
       "MerchantTransactionID": "s2ptest_g108",
       "Amount": 100,
       "Currency": "BRL",
       "MethodID": 46,
       "Customer": {  
         "Email" : "test_user_4432956@testuser.com"
        },
       "BillingAddress":{
         "Country": "BR"
          }
       }
    }

    Response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json; charset=utf-8
    
    {
      "Payment": {
        "ID": 3009261,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20170804065721",
        "MerchantTransactionID": "s2ptest_g108",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "BRL",
        "CapturedAmount": null,
        "ReturnURL": null,
        "Description": null,
        "MethodID": 46,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30201,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": null,
        "Details": null,
        "ReferenceDetails": null,
        "CustomParameters": null,
        "PreapprovalID": 4217,
        "Status": {
          "ID": 4,
          "Info": "Failed",
          "Reasons": [
            {
              "Code": 114,
              "Info": "Invalid preapproval details received"
            }
          ]
        },
        "MethodTransactionID": null,
        "TokenLifetime": null,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": null
      }
    }

  • Checkout the below example of a recurring payment request for SEPA Direct Debit (84) that is based on the PreapprovalID (also send in the payment request the Description parameter and Country parameter – should be the same with the one sent in the Preapproval request):

    Request:

    POST https://paytest.smart2pay.com/v1/payments/recurrent
    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
    
    {
     "Payment": {
       "PreapprovalID":13199,
       "MerchantTransactionID": "s2ptest_h13",
       "Amount": 100,
       "Currency": "EUR",
       "MethodID": 84,
       "Description":"SEPA DD recurrent payment",
       "BillingAddress": {
         "Country": "NL"
        }
      }
    }

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
        "Payment": {
            "ID": 4167022,
            "SkinID": null,
            "ClientIP": null,
            "Created": "20181101145456",
            "MerchantTransactionID": "s2ptest_h13",
            "OriginatorTransactionID": null,
            "Amount": "100",
            "Currency": "EUR",
            "CapturedAmount": null,
            "ReturnURL": null,
            "Description": "SEPA DD recurrent payment",
            "MethodID": 84,
            "MethodOptionID": null,
            "IncludeMethodIDs": null,
            "ExcludeMethodIDs": null,
            "PrioritizeMethodIDs": null,
            "SiteID": 30201,
            "NotificationDateTime": null,
            "Customer": null,
            "BillingAddress": {
                "ID": 309,
                "City": null,
                "ZipCode": null,
                "State": null,
                "Street": null,
                "StreetNumber": null,
                "HouseNumber": null,
                "HouseExtension": null,
                "Country": "NL"
            },
            "ShippingAddress": null,
            "Articles": null,
            "Details": null,
            "ReferenceDetails": null,
            "CustomParameters": null,
            "PreapprovalID": 13199,
            "Status": {
                "ID": 1,
                "Info": "Open",
                "Reasons": null
            },
            "MethodTransactionID": null,
            "TokenLifetime": null,
            "Capture": null,
            "PreapprovalDetails": null,
            "RedirectURL": null
        }
    }

    When the Direct Debit is successfully executed by the bank (1-2 banking days), you will receive a similar notification with Success Status (StatusID = 2) so you can send the product to the customer.

    You need to respond with HTTP code 204 (No Content)!

    Payment notification format:

    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
    
    {
      "Payment": {
        "ID": 4167022,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20181101145458",
        "MerchantTransactionID": "s2ptest_h13",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "EUR",
        "ReturnURL": "",
        "Description": null,
        "MethodID": 84,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30201,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": null,
        "Details": null,
        "ReferenceDetails": null,
        "CustomParameters": null,
        "PreapprovalID": 13199,
        "Status": {
          "ID": 2,
          "Info": "Success",
          "Reasons": null
        },
        "MethodTransactionID": null,
        "TokenLifetime": null,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": null
      }
    }