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 an example of a preapproval request for PayWithMyBank (58).
With PayWithMyBank, you can create preapprovals that can allow you to form subsequent recurrent payments. This is the most flexible type and allows the merchant to fully control when to initiate the money transfer(s) between the end user’s account and the merchant’s account (credits or debits). The Preapproval call basically creates a transaction representing the end user’s authorization to use their account for payments on the terms set in the request.
A transaction ID is returned to the merchant within the return URL in the Preapproval response/notification. The merchant must store this transaction ID in the end user’s payment profile to allow future recurrent requests. The amount sent on the initial call defines the maximum aggregate amount that can be captured from the end user’s account across all recurrent calls. A zero-amount value on the Preapproval call removes this upper bound limit. With that setting, the merchant can enable open-ended recurrent scenarios.
For PayWithMyBank preapproval requests CustomerName and CustomerEmail parameters are mandatory in the initial payment request.
Request:
POST https://paytest.smart2pay.com/v1/preapprovals
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
{
"Preapproval": {
"MerchantPreapprovalID": "s2ptest_h-1",
"PreapprovedMaximumAmount": 20,
"Currency": "USD",
"Description": "1 year subscription",
"ReturnURL": "http://demo.smart2pay.com/redirect.php",
"MethodID": 58,
"Customer": {
"FirstName": "John",
"LastName": "Doe",
"Email": "jdoe@gmail.com"
},
"BillingAddress": {
"Country": "US"
}
}
}
{"Preapproval":{"hint":"Preapproval structure","regexp":"","type":"object","MerchantPreapprovalID":{"hint":"Merchant Preapproval ID, a number that uniquely identifies a preapproval in your system.","regexp":"","type":"string"},"MethodID":{"hint":"The ID of the payment method.","regexp":"^\\d{1,12}$","type":"int"},"MethodOptionID":{"hint":"The ID of the payment option; can be used when the payment method has multiple payment options (e.g. ING bank is an option for iDEAL).","regexp":"^([0-9]{1,10})$","type":"int"},"ExecutionDate":{"hint":"Executed at a specific date","regexp":"","type":"date"},"RecurringPeriod":{"hint":"Preapproval recurring period","regexp":"^\\d{1,12}$","type":"int"},"Description":{"hint":"Text describing the subscription sold; will be displayed on the automatic debit confirmation page.","regexp":"^.{1,255}$","type":"string"},"PreapprovedMaximumAmount":{"hint":"Preapproval maximum amount. Please be aware that data type string is also accepted as long as it contains only digits.","regexp":"^\\d{1,12}$","type":"int"},"Currency":{"hint":"The currency in which you sell the services or products. Format is according to ISO 4217, a three-letter code.","regexp":"^[A-Z]{3}$","type":"string"},"ReturnURL":{"hint":"An URL where the customer will be redirected after the approval process ends.","regexp":"^(http(s)?(:\\\/\\\/|%3A%2F%2F).+){1,512}$","type":"string"},"Customer":{"hint":"Customer details","regexp":"","type":"object","ID":{"hint":"Customer ID, a unique number that identifies the customer in the GlobalPay system.","regexp":"^\\d{1,12}$","type":"int"},"MerchantCustomerID":{"hint":"The ID of the customer in your system.","regexp":"^([0-9a-zA-Z_-]{1,50})?$","type":"string"},"Email":{"hint":"Customer\u2019s email","regexp":"^[a-zA-Z0-9\\._%+-]{1,100}@[a-zA-Z0-9\\.-]{1,40}\\.[a-zA-Z]{1,8}$","type":"string"},"FirstName":{"hint":"Customer\u2019s first name","regexp":"","type":"string"},"LastName":{"hint":"Customer\u2019s last name","regexp":"","type":"string"},"Gender":{"hint":"Customer\u2019s gender. It can have the following values: 1 - Male, 2 - Female.","regexp":"","type":"string"},"DateOfBirth":{"hint":"Customer date of birth","regexp":"^(((19|20)\\d\\d)(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01]))$","type":"date"},"SocialSecurityNumber":{"hint":"Customer\u2018s social or fiscal identifier","regexp":"","type":"string"},"Phone":{"hint":"Customer\u2019s phone including prefix","regexp":"","type":"string"},"Company":{"hint":"Company name (for legal entities)","regexp":"","type":"string"},"InputDateTime":{"hint":"Customer creation date","regexp":"","type":"datetime"}},"BillingAddress":{"hint":"Billing Address details","regexp":"","type":"object","ID":{"hint":"Address ID, a unique number that identifies an address in the GlobalPay system.","regexp":"^\\d{1,12}$","type":"int"},"Country":{"hint":"Customer\u2018s country. Recommended to be sent in order to increase the conversion. If MethodID is missing, this field (taken from BillingAddress object) controls which payment methods are shown on the hosted payment pages. Format is according to ISO-3166-1 alpha-2, a two-letter code.","regexp":"^([A-Za-z]{2})?$","type":"string"},"City":{"hint":"City name","regexp":"^(.{1,255})?$","type":"string"},"ZipCode":{"hint":"Postal code","regexp":"^(.{1,255})?$","type":"string"},"State":{"hint":"State name","regexp":"^(.{1,255})?$","type":"string"},"Street":{"hint":"Street name","regexp":"^(.{1,255})?$","type":"string"},"StreetNumber":{"hint":"Street Number","regexp":"^(.{1,255})?$","type":"string"},"HouseNumber":{"hint":"House Number","regexp":"^(.{1,255})?$","type":"string"},"HouseExtension":{"hint":"House Extension","regexp":"^(.{1,255})?$","type":"string"}}}}
Response:
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{
"Preapproval": {
"ID": 19800,
"Created": "20190729134913",
"MethodID": 58,
"SiteID": 30201,
"MerchantPreapprovalID": "s2ptest_h-1",
"RecurringPeriod": 0,
"PreapprovedMaximumAmount": "20",
"Currency": "USD",
"ReturnURL": "http://demo.smart2pay.com/redirect.php",
"Description": "1 year subscription",
"Customer": {
"ID": 2625948,
"MerchantCustomerID": null,
"Email": "jdoe@gmail.com",
"FirstName": "John",
"LastName": "Doe",
"Gender": null,
"SocialSecurityNumber": null,
"Phone": null,
"Company": null,
"DateOfBirth": null
},
"BillingAddress": {
"ID": 520,
"City": null,
"ZipCode": null,
"State": null,
"Street": null,
"StreetNumber": null,
"HouseNumber": null,
"HouseExtension": null,
"Country": "US"
},
"Status": {
"ID": 1,
"Info": "Pending",
"Reasons": null
},
"RedirectURL": "https://europaytest.smart2pay.com/PWMB/Landing/PreapprovalLanding.aspx?ID=15351&Hash=CD3F91C3DF49E901E91240FA42D89A64",
"MethodOptionID": 0,
"PreapprovedFrequency": null,
"MandateReference": null,
"Details": null
}
}
{"Preapproval":{"hint":"Preapproval structure","regexp":"","type":"object","ID":{"hint":"GlobalPay preapproval ID, a unique number that identifies the preapproval in the GlobalPay system; you will need to store this id in order to initiate recurring payments.","regexp":"^\\d{1,12}$","type":"int"},"Created":{"hint":"Date and time when the preapproval was created.","regexp":"","type":"datetime"},"MethodID":{"hint":"The ID of the payment method.","regexp":"^\\d{1,12}$","type":"int"},"SiteID":{"hint":"The ID of the site","regexp":"^\\d{1,12}$","type":"int"},"MerchantPreapprovalID":{"hint":"Merchant Preapproval ID, a number that uniquely identifies a preapproval in your system.","regexp":"","type":"string"},"RecurringPeriod":{"hint":"Preapproval recurring period","regexp":"^\\d{1,12}$","type":"int"},"PreapprovedMaximumAmount":{"hint":"Preapproval maximum amount. Please be aware that data type string is also accepted as long as it contains only digits.","regexp":"^\\d{1,12}$","type":"int"},"Currency":{"hint":"The currency in which you sell the services or products. Format is according to ISO 4217, a three-letter code.","regexp":"^[A-Z]{3}$","type":"string"},"ReturnURL":{"hint":"An URL where the customer will be redirected after the approval process ends.","regexp":"^(http(s)?(:\\\/\\\/|%3A%2F%2F).+){1,512}$","type":"string"},"Description":{"hint":"Text describing the subscription sold; will be displayed on the automatic debit confirmation page.","regexp":"^.{1,255}$","type":"string"},"Customer":{"hint":"Customer details","regexp":"","type":"object","ID":{"hint":"Customer ID, a unique number that identifies the customer in the GlobalPay system.","regexp":"^\\d{1,12}$","type":"int"},"MerchantCustomerID":{"hint":"The ID of the customer in your system.","regexp":"^([0-9a-zA-Z_-]{1,50})?$","type":"string"},"Email":{"hint":"Customer\u2019s email","regexp":"^[a-zA-Z0-9\\._%+-]{1,100}@[a-zA-Z0-9\\.-]{1,40}\\.[a-zA-Z]{1,8}$","type":"string"},"FirstName":{"hint":"Customer\u2019s first name","regexp":"","type":"string"},"LastName":{"hint":"Customer\u2019s last name","regexp":"","type":"string"},"Gender":{"hint":"Customer\u2019s gender. It can have the following values: 1 - Male, 2 - Female.","regexp":"","type":"string"},"DateOfBirth":{"hint":"Customer date of birth","regexp":"^(((19|20)\\d\\d)(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01]))$","type":"date"},"SocialSecurityNumber":{"hint":"Customer\u2018s social or fiscal identifier","regexp":"","type":"string"},"Phone":{"hint":"Customer\u2019s phone including prefix","regexp":"","type":"string"},"Company":{"hint":"Company name (for legal entities)","regexp":"","type":"string"},"InputDateTime":{"hint":"Customer creation date","regexp":"","type":"datetime"}},"BillingAddress":{"hint":"Billing Address details","regexp":"","type":"object","ID":{"hint":"Address ID, a unique number that identifies an address in the GlobalPay system.","regexp":"^\\d{1,12}$","type":"int"},"Country":{"hint":"Customer\u2018s country. Recommended to be sent in order to increase the conversion. If MethodID is missing, this field (taken from BillingAddress object) controls which payment methods are shown on the hosted payment pages. Format is according to ISO-3166-1 alpha-2, a two-letter code.","regexp":"^([A-Za-z]{2})?$","type":"string"},"City":{"hint":"City name","regexp":"^(.{1,255})?$","type":"string"},"ZipCode":{"hint":"Postal code","regexp":"^(.{1,255})?$","type":"string"},"State":{"hint":"State name","regexp":"^(.{1,255})?$","type":"string"},"Street":{"hint":"Street name","regexp":"^(.{1,255})?$","type":"string"},"StreetNumber":{"hint":"Street Number","regexp":"^(.{1,255})?$","type":"string"},"HouseNumber":{"hint":"House Number","regexp":"^(.{1,255})?$","type":"string"},"HouseExtension":{"hint":"House Extension","regexp":"^(.{1,255})?$","type":"string"}},"Status":{"hint":"Preapproval status","regexp":"","type":"object","ID":{"hint":"The ID of the preapproval status. It can have the following values: 1 - Pending, 2 - Open, 4 - Closed.","regexp":"","type":"int"},"Info":{"hint":"The description of the status","regexp":"","type":"string"},"Reasons":{"hint":"The reasons why the payment got to this status.","regexp":"","type":"array of objects","Code":{"hint":"The id of the message type transmitted in the response. See our section GlobalPay Return Codes for a complete description.","regexp":"","type":"int"},"Info":{"hint":"The message body","regexp":"","type":"string"}}},"RedirectURL":{"hint":"The URL where you need to redirect the customer in order to approve the automatic debit.","regexp":"^(http(s)?(:\\\/\\\/|%3A%2F%2F).+){1,512}$","type":"string"},"MethodOptionID":{"hint":"The ID of the payment option; can be used when the payment method has multiple payment options (e.g. ING bank is an option for iDEAL).","regexp":"^([0-9]{1,10})$","type":"int"},"PreapprovedFrequency":{"hint":"Preapproved frequency - how often is the customer going to be billed. It can be onetime\/daily\/weekly\/monthly depending on the country and the mobile carrier.","regexp":"","type":"string"},"MandateReference":{"hint":"Preapproval mandate reference","regexp":"","type":"string"}}}
