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.

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.

Request:

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

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

Response:

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

{
  "Payment": {
    "ID": 3005333,
    "SkinID": null,
    "ClientIP": null,
    "Created": "20170802140554",
    "MerchantTransactionID": "s2ptest_g20",
    "OriginatorTransactionID": null,
    "Amount": 11,
    "Currency": "CNY",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "",
    "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": {
      "ID": 291,
      "City": null,
      "ZipCode": null,
      "State": null,
      "Street": null,
      "StreetNumber": null,
      "HouseNumber": null,
      "HouseExtension": null,
      "Country": "CN"
    },
    "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=zbGt6m4"
    },
    "CustomParameters": null,
    "PreapprovalID": null,
    "Status": {
      "ID": 1,
      "Info": "Open",
      "Reasons": null
    },
    "MethodTransactionID": null,
    "TokenLifetime": 10,
    "Capture": null,
    "PreapprovalDetails": null,
    "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=0C79E6488FDB5F2C1264EEC399243A2C.3005333"
  }
}

In order to initiate a 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_g21",
    "Amount": 11,
    "Currency": "CNYY",      
    "MethodID": 1066,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",      
    "TokenLifetime": 10,
    "Customer": {    
      "Email": "youremail@email.com"   
    },
    "BillingAddress": {
      "Country": "CN"
    }
  }
}

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_g21",
    "OriginatorTransactionID": null,
    "Amount": 11,
    "Currency": "CNYY",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": null,
    "MethodID": 1066,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": null,
    "NotificationDateTime": null,
    "Customer": null,
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Details": null,
    "ReferenceDetails": null,
    "CustomParameters": null,
    "PreapprovalID": null,
    "Status": {
      "ID": null,
      "Info": null,
      "Reasons": [
        {
          "Code": "2",
          "Info": "Validation failed - Currency (RegEx: ^[A-Z]{3}$)"
        }
      ]
    },
    "MethodTransactionID": null,
    "TokenLifetime": null,
    "Capture": null,
    "PreapprovalDetails": null,
    "RedirectURL": null
  }
}

When the validation fails for a 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 visit our section: Create a complex payment in order to see a full example of a payment with all the parameters needed for the request. The parameters are sent in the message body as a JSON object.