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) and Klarna Invoice (75).

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.

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.

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
  }
}

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

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:

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
  }
}

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
  }
}

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.

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
  }
}

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
  }
}

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": "s2ptest_fg110",
      "OriginatorTransactionID": null,
      "Amount": 100,
      "Currency": "BRL",
      "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",
      "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",
      "ReturnURL": "",
      "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": null
      },
      "MethodTransactionID": null,
      "TokenLifetime": null,
      "Capture": null,
      "PreapprovalDetails": null,
      "RedirectURL": null
    }
  ]
}

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
    },
    {
      "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
    },
    {
      "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
    },
    {
      "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
    }
  ]
}

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 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.

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",
    "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",
    "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
  }
}