Create a Payment

Definition: POST /v1/payments

To initiate a payment, you must create a payment object. The parameters of the payment are sent in the message body as a JSON object.

A 201 HTTP response (Created) is returned if the payment was correctly initialized.

Request: 

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

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_g2",
    "Amount": 11,
    "Currency": "CNY",      
    "MethodID": 1066,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",      
    "TokenLifetime": 10,
    "Customer": {    
      "Email": "youremail@email.com"   
    } 
  }
}

Response:

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

{
  "Payment": {
    "ID": 2677982,
    "SkinID": null,
    "ClientIP": null,
    "Created": "20161107092103",
    "MerchantTransactionID": "s2ptest_g2",
    "OriginatorTransactionID": null,
    "Amount": 11,
    "Currency": "CNY",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": null,
    "MethodID": 1066,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": 30201,
    "NotificationDateTime": null,
    "Customer": {
      "ID": 473,
      "MerchantCustomerID": null,
      "Email": "youremail@email.com",
      "FirstName": null,
      "LastName": null,
      "Gender": null,
      "SocialSecurityNumber": null,
      "Phone": null,
      "Company": null,
      "DateOfBirth": null
    },
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Details": null,
    "ReferenceDetails": {
      "BankCode": null,
      "BankName": null,
      "EntityID": null,
      "EntityNumber": null,
      "ReferenceID": null,
      "ReferenceNumber": null,
      "SwiftBIC": null,
      "AccountCurrency": null,
      "AccountNumber": null,
      "AccountHolder": null,
      "IBAN": null,
      "QRCodeURL": "weixin://wxpay/bizpayurl?pr=ad7EqGN"
    },
    "CustomParameters": null,
    "PreapprovalID": null,
    "Status": {
      "ID": 1,
      "Info": "Open",
      "Reasons": null
    },
    "MethodTransactionID": null,
    "TokenLifetime": 10,
    "Capture": null,
    "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=8455FA9767A0795E6DDAD87775B8B10E.2677982"
  }
}

In order to initiate a Direct Card payment, the payment object must contain the necessary card details.

Request:

POST https://securetest.smart2pay.com/v1/payments
Authorization: Basic MTAxMDpnYWJp

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_h2",
    "Amount": 2000,
    "Currency": "EUR",
    "Card": {
      "HolderName": "John Doe",
      "Number": "4111111111111111",
      "ExpirationMonth": "02",
      "ExpirationYear": "2018",
      "SecurityCode": "312"
    },		
     "Capture": true
  }
}

Response:

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

{
  "Payment": {
    "ID": 202230,
    "ClientIP": null,
    "SkinID": null,
    "Created": "20161205084103",
    "MerchantTransactionID": "s2ptest_h2",
    "OriginatorTransactionID": null,
    "Amount": 2000,
    "Currency": "EUR",
    "CapturedAmount": 2000,
    "ReturnURL": null,
    "Description": null,
    "StatementDescriptor": null,
    "MethodID": 6,
    "MethodOptionID": null,
    "SiteID": 1010,
    "NotificationDateTime": null,
    "Customer": null,
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Card": {
      "HolderName": "John Doe",
      "Number": "VISA-1111",
      "ExpirationMonth": "02",
      "ExpirationYear": "2018"
    },
    "CreditCardToken": null,
    "Status": {
      "ID": 11,
      "Info": "Captured",
      "Reasons": []
    },
    "MethodTransactionID": null,
    "PaymentTokenLifetime": null,
    "Capture": true,
    "Retry": false,
    "RedirectURL": null,
    "3DSecure": 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
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_g2",
    "Amount": 11,
    "Currency": "CNY",      
    "MethodID": 1066,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",      
    "TokenLifetime": 10,
    "Customer": {    
      "Email": "youremail@email.com"
    } 
  }
}

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "Payment": {
    "ID": null,
    "SkinID": null,
    "ClientIP": null,
    "Created": null,
    "MerchantTransactionID": "s2ptest_g2",
    "OriginatorTransactionID": null,
    "Amount": 11,
    "Currency": "CNY",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": null,
    "MethodID": 1066,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": null,
    "NotificationDateTime": null,
    "Customer": {
      "ID": 473,
      "MerchantCustomerID": null,
      "Email": "youremail@email.com",
      "FirstName": null,
      "LastName": null,
      "Gender": null,
      "SocialSecurityNumber": null,
      "Phone": null,
      "Company": null,
      "DateOfBirth": null
    },
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Details": null,
    "ReferenceDetails": null,
    "CustomParameters": null,
    "PreapprovalID": null,
    "Status": {
      "ID": null,
      "Info": null,
      "Reasons": [
        {
          "Code": "20",
          "Info": "MerchantTransactionID is duplicated - s2ptest_g2"
        }
      ]
    },
    "MethodTransactionID": null,
    "TokenLifetime": null,
    "Capture": null,
    "RedirectURL": null
  }
}

When the validation fails for a Direct Card payment, an invalid request is inserted in the database and the ID of the newly inserted invalid request is sent in the Payment response. The value of the element InvalidRequestID is prefixed with ”i” to not be confused with the Payment ID.

Request:

POST https://securetest.smart2pay.com/v1/payments
Authorization: Basic MTAxMDpnYWJp

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_h2",
    "Amount": 2000,
    "Currency": "EUR",
    "Card": {
      "HolderName": "John Doe",
      "Number": "4111111111111111",
      "ExpirationMonth": "02",
      "ExpirationYear": "2018",
      "SecurityCode": "312"
    },		
     "Capture": true
  }
}

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "Payment": {
    "InvalidRequestID": "i3065",
    "ID": null,
    "ClientIP": null,
    "SkinID": null,
    "Created": null,
    "MerchantTransactionID": "s2ptest_h2",
    "OriginatorTransactionID": null,
    "Amount": 2000,
    "Currency": "EUR",
    "CapturedAmount": 0,
    "ReturnURL": null,
    "Description": null,
    "StatementDescriptor": null,
    "MethodID": 6,
    "MethodOptionID": null,
    "SiteID": 1010,
    "NotificationDateTime": null,
    "Customer": null,
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Card": {
      "HolderName": "John Doe",
      "Number": "Ends with 1111",
      "ExpirationMonth": "02",
      "ExpirationYear": "2018"
    },
    "CreditCardToken": null,
    "Status": {
      "ID": null,
      "Info": null,
      "Reasons": [
        {
          "Code": "20",
          "Info": "Key is duplicated"
        }
      ]
    },
    "MethodTransactionID": null,
    "PaymentTokenLifetime": null,
    "Capture": true,
    "Retry": false,
    "RedirectURL": null,
    "3DSecure": null
  }
}

Please note that we recommend that the billing country (Payment.BillingAddress.Country) parameter to be sent. If this parameter is not sent the country is determined using IP detection, which is not always reliable. This parameter is used in various scenarios and an accurate value will increase conversion.

See our section: Create a complex payment for a more complex example of a payment.

Capture a Payment

Definition: POST /v1/payments/{id}/capture

Where:
  • {id} – GlobalPay Payment ID

A payment can only be captured if it has an Authorized status. The Authorized status can only be obtained for Cards, Klarna methods, Paysafecard and UnionPay International Cards.

A 200 HTTP response (OK) is returned if the request was completed successfully.

Request:

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

Response:

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

{
  "Payment": {
    "ID": 2427069,
    "SkinID": 11,
    "Created": "20160314093342",
    "MerchantTransactionID": "s2ptest_2",
    "Amount": 980,
    "Currency": "EUR",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": null,
    "MethodID": 75,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": 30201,
    "NotificationDateTime": "20160314094102",
    "Customer": {
      "ID": 410,
      "MerchantCustomerID": "0125",
      "Email": "youremail@email.com",
      "FirstName": "Example",
      "LastName": "Test",
      "Gender": "1",
      "SocialSecurityNumber": "410321-9202",
      "Phone": "0765260000",
      "Company": "S2P"
    },
    "BillingAddress": {
      "ID": 340,
      "City": "Ankeborg",
      "ZipCode": "12345",
      "State": "Iasi",
      "Street": "Stargatan",
      "StreetNumber": "1",
      "HouseNumber": "22",
      "HouseExtension": "25",
      "Country": "SE"
    },
    "ShippingAddress": {
      "ID": 340,
      "City": "Ankeborg",
      "ZipCode": "12345",
      "State": "Iasi",
      "Street": "Stargatan",
      "StreetNumber": "1",
      "HouseNumber": "22",
      "HouseExtension": "25",
      "Country": "SE"
    },
    "Articles": [
      {
        "MerchantArticleID": "1231",
        "Name": "TEST",
        "Quantity": 1,
        "Price": 1000,
        "VAT": 1000,
        "Discount": 200,
        "Type": 1
      }
    ],
    "Details": null,
    "ReferenceDetails": null,
    "CustomParameters": null,
    "PreapprovalID": null,
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": null
    },
    "MethodTransactionID": null,
    "TokenLifetime": 10,
    "Capture": null,
    "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=F3079CC6F820D543AEBA6EAF8912E638.2427069"
  }
}

For Direct Card payments the Authorized status can only be obtained when a payment is initiated with the Capture parameter set to false.

Once the payment has an Authorized status, you can capture either a partial amount or the full amount of the initial authorized amount for the transaction.

Full capture means you capture the entire authorized amount for the initial transaction.

Partial capture means you have the possibility to capture a smaller amount than the one from the initial authorized transaction.

You can perform only one partial capture for an authorized transaction with the limitation that the amount of the partial capture to be smaller or equal than the initial authorized amount.

You need to specify the captured amount parameter in the query string, in order to partially capture a payment.

Request:

POST https://securetest.smart2pay.com/v1/payments/202239/capture?amount=1000
Authorization: Basic MTAxMDpnYWJp

Response:

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

{
  "Payment": {
    "ID": 202239,
    "ClientIP": null,
    "SkinID": null,
    "Created": "20161205091934",
    "MerchantTransactionID": "s2ptest_h10",
    "OriginatorTransactionID": null,
    "Amount": 2000,
    "Currency": "EUR",
    "CapturedAmount": 1000,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "payment product",
    "StatementDescriptor": "bank statement message",
    "MethodID": 6,
    "MethodOptionID": null,
    "SiteID": 1010,
    "NotificationDateTime": null,
    "Customer": {
      "ID": 115,
      "MerchantCustomerID": "null",
      "Email": "customer@test.com",
      "FirstName": "John",
      "LastName": "Doe",
      "Gender": "1",
      "SocialSecurityNumber": "45908-28324",
      "Phone": "0744-783322",
      "Company": "S2P"
    },
    "BillingAddress": {
      "ID": 253,
      "City": "Iasi",
      "ZipCode": "7000-49",
      "State": "Iasi",
      "Street": "Sf Lazar",
      "StreetNumber": "37",
      "HouseNumber": "5A",
      "HouseExtension": "-",
      "Country": "RO"
    },
    "ShippingAddress": {
      "ID": 87,
      "City": "Iasi",
      "ZipCode": "700049",
      "State": "Iasi",
      "Street": "Sf Lazar",
      "StreetNumber": "37",
      "HouseNumber": "-",
      "HouseExtension": "-",
      "Country": "RO"
    },
    "Articles": null,
    "Card": null,
    "CreditCardToken": null,
    "Status": {
      "ID": 35,
      "Info": "PartiallyCaptured",
      "Reasons": []
    },
    "MethodTransactionID": null,
    "PaymentTokenLifetime": null,
    "Capture": false,
    "Retry": true,
    "RedirectURL": null,
    "3DSecure": 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/2429754/capture
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "Payment": {
    "ID": 2429754,
    "SkinID": null,
    "Created": "20160316100249",
    "MerchantTransactionID": null,
    "Amount": null,
    "Currency": null,
    "ReturnURL": null,
    "Description": null,
    "MethodID": 46,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": 30201,
    "NotificationDateTime": "20160316100333",
    "Customer": null,
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Details": null,
    "ReferenceDetails": null,
    "CustomParameters": null,
    "PreapprovalID": null,
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": [
        {
          "Code": 17,
          "Info": "Payment is invalid - 2429754"
        }
      ]
    },
    "MethodTransactionID": null,
    "TokenLifetime": null,
    "Capture": null,
    "RedirectURL": null
  }
}

Cancel a Payment

Definition: POST /v1/payments/{id}/cancel

Where:
  • {id} – GlobalPay Payment ID

A payment can be cancelled if it has an Authorized status. The Authorized status can only be obtained for Cards, Klarna methods and Paysafecard.

There is one more situation when you can cancel a payment. That is when the payment has been initiated but the customer hasn’t accessed the RedirectURL or the customer didn’t get to the provider’s side (for the offline payment methods: the customer hasn’t yet received the payment details).

A 200 HTTP response (OK) is returned if the request was completed successfully.

Request:

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

Response:

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

{
  "Payment": {
    "ID": 2427073,
    "SkinID": 11,
    "Created": "20160314094121",
    "MerchantTransactionID": "s2ptest_4",
    "Amount": 980,
    "Currency": "EUR",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": null,
    "MethodID": 75,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": 30201,
    "NotificationDateTime": "20160314094220",
    "Customer": {
      "ID": 410,
      "MerchantCustomerID": "0125",
      "Email": "youremail@email.com",
      "FirstName": "Example",
      "LastName": "Test",
      "Gender": "1",
      "SocialSecurityNumber": "410321-9202",
      "Phone": "0765260000",
      "Company": "S2P"
    },
    "BillingAddress": {
      "ID": 340,
      "City": "Ankeborg",
      "ZipCode": "12345",
      "State": "Iasi",
      "Street": "Stargatan",
      "StreetNumber": "1",
      "HouseNumber": "22",
      "HouseExtension": "25",
      "Country": "SE"
    },
    "ShippingAddress": {
      "ID": 340,
      "City": "Ankeborg",
      "ZipCode": "12345",
      "State": "Iasi",
      "Street": "Stargatan",
      "StreetNumber": "1",
      "HouseNumber": "22",
      "HouseExtension": "25",
      "Country": "SE"
    },
    "Articles": [
      {
        "MerchantArticleID": "1231",
        "Name": "TEST",
        "Quantity": 1,
        "Price": 1000,
        "VAT": 1000,
        "Discount": 200,
        "Type": 1
      }
    ],
    "Details": null,
    "ReferenceDetails": null,
    "CustomParameters": null,
    "PreapprovalID": null,
    "Status": {
      "ID": 3,
      "Info": "Cancelled",
      "Reasons": null
    },
    "MethodTransactionID": null,
    "TokenLifetime": null,
    "Capture": null,
    "RedirectURL": null
  }
}

For Direct Card payments the Authorized status can only be obtained when payment are initiated with the Capture parameter set to false.

Request:

POST https://securetest.smart2pay.com/v1/payments/202237/cancel
Authorization: Basic MTAxMDpnYWJp

Response:

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

{
  "Payment": {
    "ID": 202237,
    "ClientIP": null,
    "SkinID": null,
    "Created": "20161205091456",
    "MerchantTransactionID": "s2ptest_h8",
    "OriginatorTransactionID": null,
    "Amount": 2000,
    "Currency": "EUR",
    "CapturedAmount": 0,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "payment product",
    "StatementDescriptor": "bank statement message",
    "MethodID": 6,
    "MethodOptionID": null,
    "SiteID": 1010,
    "NotificationDateTime": null,
    "Customer": {
      "ID": 115,
      "MerchantCustomerID": "null",
      "Email": "customer@test.com",
      "FirstName": "John",
      "LastName": "Doe",
      "Gender": "1",
      "SocialSecurityNumber": "45908-28324",
      "Phone": "0744-783322",
      "Company": "S2P"
    },
    "BillingAddress": {
      "ID": 253,
      "City": "Iasi",
      "ZipCode": "7000-49",
      "State": "Iasi",
      "Street": "Sf Lazar",
      "StreetNumber": "37",
      "HouseNumber": "5A",
      "HouseExtension": "-",
      "Country": "RO"
    },
    "ShippingAddress": {
      "ID": 87,
      "City": "Iasi",
      "ZipCode": "700049",
      "State": "Iasi",
      "Street": "Sf Lazar",
      "StreetNumber": "37",
      "HouseNumber": "-",
      "HouseExtension": "-",
      "Country": "RO"
    },
    "Articles": null,
    "Card": null,
    "CreditCardToken": null,
    "Status": {
      "ID": 3,
      "Info": "Cancelled",
      "Reasons": []
    },
    "MethodTransactionID": null,
    "PaymentTokenLifetime": null,
    "Capture": false,
    "Retry": true,
    "RedirectURL": null,
    "3DSecure": 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/2429737/cancel
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "Payment": {
    "ID": 2429737,
    "SkinID": null,
    "Created": "20160316091233",
    "MerchantTransactionID": null,
    "Amount": null,
    "Currency": null,
    "ReturnURL": null,
    "Description": null,
    "MethodID": 1053,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": 30201,
    "NotificationDateTime": "20160316091945",
    "Customer": null,
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Details": null,
    "ReferenceDetails": null,
    "CustomParameters": null,
    "PreapprovalID": null,
    "Status": {
      "ID": 3,
      "Info": "Cancelled",
      "Reasons": [
        {
          "Code": 17,
          "Info": "Payment is invalid - 2429737"
        }
      ]
    },
    "MethodTransactionID": null,
    "TokenLifetime": null,
    "Capture": null,
    "RedirectURL": null
  }
}

Payment Notification

Whenever a payment process is completed, we notify you of the event and whether it was successful or not. GlobalPay will send a POST message to the notification URL you setup in the Merchant Dashboard.

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

Also it is highly recommended to match the values for notification Amount and Currency with the ones from your database!

In exceptional cases it is possible to receive duplicate notifications and your system should be able to handle such situations. If a duplicate is received with success status it overwrites any previous notification.

If you do not respond to the notifications of type Payment our system will keep sending the notifications until it receives a response. At first you will be notified more often. Once the time passes the notifications from our system will be rare and they will eventually stop (after a period of time defined in our system, currently set to 7 days).

Payment Notification Format

We will notify you about the new status of the payment to the Notification URL you setup in the Merchant Dashboard.

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

Payment notification format:

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=



{
  "Payment": {
    "ID": 2427068,
    "SkinID": null,
    "Created": "20160314092716",
    "MerchantTransactionID": "s2ptest_1",
    "Amount": 100,
    "Currency": "EUR",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "",
    "MethodID": 2,
    "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": null,
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": null
    },
    "MethodTransactionID": null,
    "TokenLifetime": 1,
    "Capture": null,
    "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=4BF7A868E5B33A34C2206E2E4C4CE62A.2427068"
  }
}

Response:

204 No Content

Payment Notification Security

You will receive a notification whenever a payment process is completed, successful or not. GlobalPay will send a POST message to the Notification URL you initially setup in the Merchant Dashboard.

To ensure that a payment has been securely processed you will need to validate the authorization header using your SiteID and API Key in the same manner you compute the authorization header for a request. For more details, please go to Authentication section.

Also, you will have to whitelist Smart2Pay’s IPs for Test and Live Environment.
Here you will find the complete list of GlobalPay’s Environments and IPs.

Redirection status vs. Notification status

After a payment flow is completed, the customer will be redirected to the ReturnURL you provided in the initial request. We will append to the URL a redirection status, called data, in case you want to display customized messages to the customer (recommended as best practice).

However, a successful redirection status does not guarantee that the transaction will have a success notification status. Please be aware that only based on our successful notification status you should release the goods or services!

We are also appending the MerchantTransactionID so you can link it with a payment in your system.

Example: http://www.merchant.com/redirect.php?data=2&MerchantTransactionID=215

REDIRECTION STATUS
Data Description
2 Success
3 Cancelled
4 Failed
7 Processing
9 Authorized

Get information on a specific payment

You can get information about a one-off payment or a recurring payment by using a few actions based on GET HTTP request.

The details about a recurring payment can be retrieved in the exact same manner you do for one-off payments.

Definition: GET /v1/payments/{id}

Where:
  • {id} – GlobalPay Payment ID

Request:

GET https://paytest.smart2pay.com/v1/payments/2427075
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

Response:

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

{
  "Payment": {
    "ID": 2427075,
    "SkinID": null,
    "Created": "20160314094549",
    "MerchantTransactionID": "s2ptest_5",
    "Amount": 100,
    "Currency": "EUR",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": null,
    "MethodID": 2,
    "MethodOptionID": 37,
    "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": null,
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": null
    },
    "MethodTransactionID": null,
    "TokenLifetime": 1,
    "Capture": null,
    "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=4F35965A546A94DE14C0126A4946B7DA.2427075"
  }
}

Get a list of payments

Without specifying any parameters a list of payments is returned. Please be aware that only a limited amount of details for each payment will be provided.

Definition: GET /v1/payments

Request:

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

Response:

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

{
  "Payments": [
    {
      "ID": 2427075,
      "SkinID": null,
      "Created": "20160314094549",
      "MerchantTransactionID": "s2ptest_5",
      "Amount": 100,
      "Currency": "EUR",
      "ReturnURL": "http://demo.smart2pay.com/redirect.php",
      "Description": null,
      "MethodID": 2,
      "MethodOptionID": 37,
      "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": null,
      "Status": {
        "ID": 2,
        "Info": "Success",
        "Reasons": null
      },
      "MethodTransactionID": null,
      "TokenLifetime": null,
      "Capture": null,
      "RedirectURL": null
    },
    {
      "ID": 2427073,
      "SkinID": 11,
      "Created": "20160314094121",
      "MerchantTransactionID": "s2ptest_4",
      "Amount": 980,
      "Currency": "EUR",
      "ReturnURL": "http://demo.smart2pay.com/redirect.php",
      "Description": "test smart2pay",
      "MethodID": 75,
      "MethodOptionID": null,
      "IncludeMethodIDs": null,
      "ExcludeMethodIDs": null,
      "PrioritizeMethodIDs": null,
      "SiteID": 30201,
      "NotificationDateTime": "20160314094220",
      "Customer": null,
      "BillingAddress": null,
      "ShippingAddress": null,
      "Articles": null,
      "Details": null,
      "ReferenceDetails": null,
      "CustomParameters": null,
      "PreapprovalID": null,
      "Status": {
        "ID": 3,
        "Info": "Cancelled",
        "Reasons": null
      },
      "MethodTransactionID": null,
      "TokenLifetime": null,
      "Capture": null,
      "RedirectURL": null
     }
  ]
}

Get a list of payments (filtered)

You can specify various filters as parameters in the query string in order to get a customized list of payments.

Requests:

GET https://paytest.smart2pay.com/v1/payments?limit=3
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
GET https://securetest.smart2pay.com/v1/payments?startDate=20160803150000&endDate=20161003140000
Authorization: Basic MTAxMDpnYWJp

The following table describes the possible filters you can use. You can mix the filters so you can obtain the desired results.

FILTERS
Field Description Data type
limit The maximum number of items that will be returned Long
offset A list of payments starting with the value of the offset parameter will be returned. The offset parameter can also be used together with the limit parameter to select specific entries within a list of payments. String
startDate The date and time after which the payments are returned DateTime (YYYYMMDDHHMMSS)
endDate The date and time until which the payments are returned DateTime (YYYYMMDDHHMMSS)
methodID Only the transactions having this methodID will be returned Long
country Only the transactions having this country code will be returned String (ISO 3166-1-alpha-2)
currency Only the transactions having this currency code will be returned String (ISO 4217)
minimumAmount Only the payments with an amount higher than this will be returned Integer (last 2 digits representing the decimal part)
maximumAmount Only the payments with an amount lower than this will be returned Integer (last 2 digits representing the decimal part)
merchantTransactionID Only the payment having this merchantTransactionID will be returned String

^[0-9a-zA-Z_-]{1,50}$

statusID Only the transactions having this statusID will be returned. Integer

The ID of the payment status can have the following values: 1 – Open, 2 – Success, 3 – Cancelled, 4 – Failed, 5 – Expired, 9 – Authorized.

methodTransactionID Only the payments having this methodTransactionID will be returned. This transaction ID from the payment method provider can be used for customer support. String

^[0-9a-zA-Z_-]{1,50}$

typeID Only the transactions having this typeID will be returned. Integer

The typeID filter can have the following values: 1 – Payments, 2 – Recurring payments.

Here is an example of a request with the limit filter set to 3.

Request:

GET https://paytest.smart2pay.com/v1/payments?limit=3
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

Response:

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

{
  "Payments": [
    {
      "ID": 2427075,
      "SkinID": null,
      "Created": "20160314094549",
      "MerchantTransactionID": "s2ptest_5",
      "Amount": 100,
      "Currency": "EUR",
      "ReturnURL": "http://demo.smart2pay.com/redirect.php",
      "Description": null,
      "MethodID": 2,
      "MethodOptionID": 37,
      "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": null,
      "Status": {
        "ID": 2,
        "Info": "Success",
        "Reasons": null
      },
      "MethodTransactionID": null,
      "TokenLifetime": null,
      "Capture": null,
      "RedirectURL": null
    },
    {
      "ID": 2427073,
      "SkinID": 11,
      "Created": "20160314094121",
      "MerchantTransactionID": "s2ptest_4",
      "Amount": 980,
      "Currency": "EUR",
      "ReturnURL": "http://demo.smart2pay.com/redirect.php",
      "Description": "test smart2pay",
      "MethodID": 75,
      "MethodOptionID": null,
      "IncludeMethodIDs": null,
      "ExcludeMethodIDs": null,
      "PrioritizeMethodIDs": null,
      "SiteID": 30201,
      "NotificationDateTime": "20160314094220",
      "Customer": null,
      "BillingAddress": null,
      "ShippingAddress": null,
      "Articles": null,
      "Details": null,
      "ReferenceDetails": null,
      "CustomParameters": null,
      "PreapprovalID": null,
      "Status": {
        "ID": 3,
        "Info": "Cancelled",
        "Reasons": null
      },
      "MethodTransactionID": null,
      "TokenLifetime": null,
      "Capture": null,
      "RedirectURL": null
    },
    {
      "ID": 2427069,
      "SkinID": 11,
      "Created": "20160314093342",
      "MerchantTransactionID": "s2ptest_2",
      "Amount": 980,
      "Currency": "EUR",
      "ReturnURL": "http://demo.smart2pay.com/redirect.php",
      "Description": "test smart2pay",
      "MethodID": 75,
      "MethodOptionID": null,
      "IncludeMethodIDs": null,
      "ExcludeMethodIDs": null,
      "PrioritizeMethodIDs": null,
      "SiteID": 30201,
      "NotificationDateTime": "20160314094102",
      "Customer": null,
      "BillingAddress": null,
      "ShippingAddress": null,
      "Articles": null,
      "Details": null,
      "ReferenceDetails": null,
      "CustomParameters": null,
      "PreapprovalID": null,
      "Status": {
        "ID": 2,
        "Info": "Success",
        "Reasons": null
      },
      "MethodTransactionID": null,
      "TokenLifetime": null,
      "Capture": null,
      "RedirectURL": null
    }
  ]
}

You can also mix various filters to get specific results. Here is an example of a request with the limit filter set to 2 and the offset 3. This means that it will return two payments entries starting with the third one.

Request:

GET https://paytest.smart2pay.com/v1/payments?limit=2&offset=3
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

Response:

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

{
 "Payments": [
 {
   "ID": 2459122,
   "SkinID": null,
   "Created": "20160411140447",
   "MerchantTransactionID": "WPD_1460383484_8795_5000",
   "Amount": 100,
   "Currency": "BAM",
   "ReturnURL": "https://docs.smart2pay.com/wp-content/plugins/smart2pay-api/views/funcs/demo_clean_return.php",
   "Description": null,
   "MethodID": 79,
   "MethodOptionID": null,
   "IncludeMethodIDs": null,
   "ExcludeMethodIDs": null,
   "PrioritizeMethodIDs": null,
   "SiteID": 30201,
   "NotificationDateTime": "20160411140522",
   "Customer": null,
   "BillingAddress": null,
   "ShippingAddress": null,
   "Articles": null,
   "Details": null,
   "ReferenceDetails": null,
   "CustomParameters": null,
   "PreapprovalID": null,
   "Status": {
     "ID": 1,
     "Info": "Open",
     "Reasons": null
   },
   "MethodTransactionID": null,
   "TokenLifetime": null,
   "Capture": null,
   "RedirectURL": null
   },
   {
   "ID": 2459118,
   "SkinID": null,
   "Created": "20160411125607",
   "MerchantTransactionID": "WPD_1460379365_1783_6355",
   "Amount": 1100,
   "Currency": "NGN",
   "ReturnURL": "https://docs.smart2pay.com/wp-content/plugins/smart2pay-api/views/funcs/demo_clean_return.php",
   "Description": null,
   "MethodID": null,
   "MethodOptionID": null,
   "IncludeMethodIDs": null,
   "ExcludeMethodIDs": null,
   "PrioritizeMethodIDs": null,
   "SiteID": 30201,
   "NotificationDateTime": "20160411125629",
   "Customer": null,
   "BillingAddress": null,
   "ShippingAddress": null,
   "Articles": null,
   "Details": null,
   "ReferenceDetails": null,
   "CustomParameters": null,
   "PreapprovalID": null,
   "Status": {
     "ID": 3,
     "Info": "Cancelled",
     "Reasons": null
   },
   "MethodTransactionID": null,
   "TokenLifetime": null,
   "Capture": null,
   "RedirectURL": null
    }
  ]
}

Get the Status of a Direct Card Payment

You can get the status of a direct card payment by using the following GET HTTP request.

Please note that this method sends only the status information about the payment. To receive more information about the payment go to Get information on a specific payment section.

Definition: GET /v1/payments/{id}/status

Where:
  • {id} – GlobalPay Payment ID

Request:

GET https://securetest.smart2pay.com/v1/payments/202230/status
Authorization: Basic MTAxMDpnYWJp

Response:

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

{
  "Payment": {
    "ID": 202230,
    "MerchantTransactionID": "s2ptest_h2",
    "Status": {
      "ID": 11,
      "Info": "Captured",
      "Reasons": []
    }
  }
}