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. See below a standard example of a preapproval request for MercadoPago (46).

For more details on the other payment methods that support recurring payments, click on the appropriate link: SEPA Direct Debit; PayWithMyBank; GCash; Kakaopay and Dana.

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.

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.

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

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