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_f25",
   "Description": "1 year subscription",
   "ReturnURL": "http://demo.smart2pay.com/redirect.php",
   "MethodID": 46, 
   "Customer": {
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "test_user_4432956@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": 1744,
    "Created": "20160913144228",
    "MethodID": 46,
    "SiteID": null,
    "MerchantPreapprovalID": "s2ptest_f25",
    "RecurringPeriod": 0,
    "PreapprovedMaximumAmount": null,
    "Currency": null,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "1 year subscription",
    "Customer": {
      "ID": 1579,
      "MerchantCustomerID": null,
      "Email": "test_user_4432956@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=631&Hash=3392DBAB87BC4DED0517BD60C0925C12"
  }
}

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": 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",
    "Customer": {
      "ID": 1579,
      "MerchantCustomerID": null,
      "Email": "test_user_4432956@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
  }
}

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/1723
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=



{
 "Preapproval": {
   "MerchantPreapprovalID": "s2ptest_f25",
   "Description": "1 year subscription update1",
   "ReturnURL": "http://demo.smart2pay.com/redirect.php",
   "MethodID": 46, 
   "Customer": {
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "test_user_4432956@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": 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": {
      "ID": 1579,
      "MerchantCustomerID": null,
      "Email": "test_user_4432956@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=631&Hash=3392DBAB87BC4DED0517BD60C0925C12"
  }
}

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/1744
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

Response:

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


{
  "Preapproval": {
    "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": {
      "ID": 1579,
      "MerchantCustomerID": null,
      "Email": "test_user_4432956@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
  }
}

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/1744
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

Response:

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

{
  "Preapproval": {
    "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": {
      "ID": 1579,
      "MerchantCustomerID": null,
      "Email": "test_user_4432956@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
  }
}

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/1744/payments
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

Response:

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

{
  "Payments": [
    {
      "ID": 2610858,
      "SkinID": null,
      "ClientIP": null,
      "Created": "20160913150115",
      "MerchantTransactionID": "s2ptest_f27",
      "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": 1744,
      "Status": {
        "ID": 2,
        "Info": "Success",
        "Reasons": null
      },
      "MethodTransactionID": null,
      "TokenLifetime": null,
      "Capture": null,
      "RedirectURL": null
    },
    {
      "ID": 2610856,
      "SkinID": null,
      "ClientIP": null,
      "Created": "20160913150102",
      "MerchantTransactionID": "s2ptest_f26",
      "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": 1744,
      "Status": {
        "ID": 2,
        "Info": "Success",
        "Reasons": null
      },
      "MethodTransactionID": null,
      "TokenLifetime": null,
      "Capture": 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": 1721,
      "Created": "20160902112825",
      "MethodID": 46,
      "SiteID": 30201,
      "MerchantPreapprovalID": "s2ptest_f12",
      "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
    },
    {
      "ID": 1539,
      "Created": "20160718125803",
      "MethodID": 46,
      "SiteID": 30201,
      "MerchantPreapprovalID": "s2ptest_12a",
      "RecurringPeriod": 0,
      "PreapprovedMaximumAmount": null,
      "Currency": null,
      "ReturnURL": "http://demo.smart2pay.com/redirect.php",
      "Description": "1 year subscription",
      "Customer": null,
      "BillingAddress": null,
      "Status": {
        "ID": 2,
        "Info": "Open",
        "Reasons": null
      },
      "RedirectURL": null,
      "MethodOptionID": 0
    },
    {
      "ID": 1495,
      "Created": "20160708074534",
      "MethodID": 46,
      "SiteID": 30201,
      "MerchantPreapprovalID": "s2ptest_DIFUSION",
      "RecurringPeriod": 0,
      "PreapprovedMaximumAmount": null,
      "Currency": null,
      "ReturnURL": "http://demo.smart2pay.com/redirect.php",
      "Description": "1 year subscription",
      "Customer": null,
      "BillingAddress": null,
      "Status": {
        "ID": 2,
        "Info": "Open",
        "Reasons": null
      },
      "RedirectURL": null,
      "MethodOptionID": 0
    },
    {
      "ID": 1299,
      "Created": "20160314131438",
      "MethodID": 46,
      "SiteID": 30201,
      "MerchantPreapprovalID": "s2ptest_41",
      "RecurringPeriod": 0,
      "PreapprovedMaximumAmount": null,
      "Currency": null,
      "ReturnURL": "http://demo.smart2pay.com/redirect.php",
      "Description": "1 year subscription",
      "Customer": null,
      "BillingAddress": null,
      "Status": {
        "ID": 1,
        "Info": "Pending",
        "Reasons": null
      },
      "RedirectURL": null,
      "MethodOptionID": 0
    },
    {
      "ID": 1016,
      "Created": "20151001120305",
      "MethodID": 46,
      "SiteID": 30201,
      "MerchantPreapprovalID": "101010",
      "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
    }
  ]
}