GCash (Alipay Connect) Preapproval Request

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 GCash (1134).

With GCash, 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.
This ID is active for 2 years and then the token that allows subsequent recurrent payments will be automatically refreshed after this time period.

Request:

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

{
 "Preapproval": {
   "MerchantPreapprovalID": "s2ptest_h-1test52",
   "Currency": "PHP",
   "Description": "1 year subscription",
   "ReturnURL": "http://demo.smart2pay.com/redirect.php",
   "MethodID": 1134,
   "Customer": {
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "jdoe@gmail.com"
     },
   "BillingAddress": {
      "Country": "PH"
      }
   }
}

Response:

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

{
    "Preapproval": {
        "ID": 22256,
        "Created": "20200330101451",
        "MethodID": 1134,
        "SiteID": 30597,
        "MerchantPreapprovalID": "s2ptest_h-1test52",
        "RecurringPeriod": 0,
        "PreapprovedMaximumAmount": null,
        "Currency": "PHP",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "1 year subscription",
        "Customer": {
            "ID": 2622497,
            "MerchantCustomerID": null,
            "Email": "jdoe@gmail.com",
            "FirstName": "John",
            "LastName": "Doe",
            "Gender": null,
            "SocialSecurityNumber": null,
            "Phone": null,
            "Company": null,
            "DateOfBirth": null
        },
        "BillingAddress": {
            "ID": 644,
            "City": null,
            "ZipCode": null,
            "State": null,
            "Street": null,
            "StreetNumber": null,
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "PH"
        },
        "Status": {
            "ID": 1,
            "Info": "Pending",
            "Reasons": null
        },
        "RedirectURL": "https://europaytest.smart2pay.com/AlipayOSP/Preapproval/PreapprovalLanding.aspx?ID=17580&Hash=FC11CEC58D39D2966F2B71603EBA8726",
        "MethodOptionID": 0,
        "PreapprovedFrequency": null,
        "MandateReference": null,
        "Details": null
    }
}

GCash (Alipay Connect) Preapproval Notification

We will notify you about the new status of the preapproval to the Notification URL you setup in the Merchant Dashboard. The format of the received notification has the same structure as the response of the initial request.

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

Preapproval notification format:

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Preapproval": {
    "ID": 22256,
    "Created": "20200330101451",
    "MethodID": 1134,
    "SiteID": 30597,
    "MerchantPreapprovalID": "s2ptest_h-1test52",
    "RecurringPeriod": 0,
    "PreapprovedMaximumAmount": null,
    "Currency": null,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "1 year subscription",
    "Customer": {
      "ID": 2622497,
      "MerchantCustomerID": null,
      "Email": "jdoe@gmail.com",
      "FirstName": "John",
      "LastName": "Doe",
      "Gender": null,
      "SocialSecurityNumber": null,
      "Phone": null,
      "Company": null,
      "DateOfBirth": null
    },
    "BillingAddress": {
      "ID": 644,
      "City": null,
      "ZipCode": null,
      "State": null,
      "Street": null,
      "StreetNumber": null,
      "HouseNumber": null,
      "HouseExtension": null,
      "Country": "PH"
    },
    "Status": {
      "ID": 2,
      "Info": null,
      "Reasons": null
    },
    "RedirectURL": null,
    "MethodOptionID": 0,
    "PreapprovedFrequency": null,
    "MandateReference": null,
    "Details": null
  }
}

GCash (Alipay Connect) 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 received when you created/opened a preapproval) and the information specific to each payment method.

For GCash (1134), you need to send the PreapprovalID (the PreapprovalID received when you created/opened a preapproval) and the Amount to be captured.

Checkout the below example of a recurring payment request for GCash (1134) that is based on the PreapprovalID. Please send in the payment request the Description parameter and Country parameter that should be the same with the ones sent in the Preapproval request.

Request:

POST https://paytest.smart2pay.com/v1/payments/recurrent
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payment": {
    "PreapprovalID": 22256,
    "MerchantTransactionID": "reccuringPayina-AlipayOSP666",
    "Amount": 100,
    "Currency": "PHP",
    "MethodID": 1134,
    "Description": "recurring payment",
    "BillingAddress": {
    "Country": "PH"
    } 
  }
}

Response:

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

{
    "Payment": {
        "ID": 4936892,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20200330102706",
        "MerchantTransactionID": "reccuringPayina-AlipayOSP666",
        "OriginatorTransactionID": null,
        "Amount": 100,
        "Currency": "PHP",
        "CapturedAmount": null,
        "ReturnURL": null,
        "Description": "recurring payment",
        "MethodID": 1134,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30597,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": {
            "ID": 644,
            "City": null,
            "ZipCode": null,
            "State": null,
            "Street": null,
            "StreetNumber": null,
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "PH"
        },
        "ShippingAddress": null,
        "Articles": null,
        "Details": null,
        "ReferenceDetails": null,
        "CustomParameters": null,
        "PreapprovalID": 22256,
        "Status": {
            "ID": 1,
            "Info": "Open",
            "Reasons": null
        },
        "Fraud": null,
        "MethodTransactionID": null,
        "TokenLifetime": null,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": null
    }
}

We will notify you about the new status of the payment to the Notification URL you setup in the Merchant Dashboard. The format of the received notification has the same structure as the response of the initial request.

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

Payment notification format:

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payment": {
    "ID": 4936892,
    "SkinID": null,
    "ClientIP": null,
    "Created": "20200330102706",
    "MerchantTransactionID": "reccuringPayina-AlipayOSP666",
    "OriginatorTransactionID": null,
    "Amount": 100,
    "Currency": "PHP",
    "CapturedAmount": null,
    "ReturnURL": "",
    "Description": "recurring payment",
    "MethodID": 1134,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": 30597,
    "NotificationDateTime": null,
    "Customer": null,
    "BillingAddress": {
      "ID": 644,
      "City": null,
      "ZipCode": null,
      "State": null,
      "Street": null,
      "StreetNumber": null,
      "HouseNumber": null,
      "HouseExtension": null,
      "Country": "PH"
    },
    "ShippingAddress": null,
    "Articles": null,
    "Details": null,
    "ReferenceDetails": null,
    "CustomParameters": null,
    "PreapprovalID": 22256,
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": null
    },
    "Fraud": null,
    "MethodTransactionID": null,
    "TokenLifetime": null,
    "Capture": null,
    "PreapprovalDetails": null,
    "RedirectURL": null
  }
}