Documentation

Quickly integrate SmartPayLive into your platform.

Custom API Integration

Integrate and receive payments securely from our payment platform.

Introduction
Common request structure
Common response structure
Authentication
Request payment
Check payment status
Cancel payment
Webhook
Conduct security checks
Class libraries

Introduction

The SmartPayLive API is organized around REST and all API calls are POST requests. The POST body contains credentials as well as the request parameters, formatted in JSON. The response is a JSON-formatted string containing status codes as well as the response data.

Base URL
https://api.smartpaylive.com/api/V1/
Sandbox URL
http://devapi.smartpaylive.com/api/V1/
Common request structure

The common request structure is laid out as follows:

Credentials Object Required
This field is used for authentication.
OriginatingIpAddress String Optional
If the caller is forwarding a request from an external client (e.g., the API caller is a web application, receiving instructions from a user in a browser), then the caller should populate this field with the IP address of the logged in user.
ClientVersion String Optional
This field should be set to the version of the software that is calling the backend API.
Request Object Required
The request body.
Common request structure
{
  "Credentials": {
    "ChannelName": "<Channel-Name>",
    "ChannelHash": "<Channel-Hash>",
    "Timestamp": "<Current-Timestamp>",
    "RequestReference": "<Request-Reference>"
  },
  "OriginatingIpAddress": "<Client-IP>",
  "ClientVersion": "<Client-Version>",
  "Request": {}
}
Common response structure

The common response structure is laid out as follows:

Succeeded Boolean
This field indicates whether the request was successful or not.
ErrorCode Integer
This field indicates the reason of the failure.
ErrorMessage String
This field indicates the reason of the failure.
RequestId String
The request identifier. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.
ProcessingTimeMS Integer
This field contains the time spent within the backend API while servicing the request.
Response Object
The response body.
Common response structure
{
  "Response": {},
  "Succeeded": true,
  "ErrorCode": null,
  "ErrorMessage": null,
  "RequestId": "3dde5697-c576-42fb-af4f-9c5cbe26bb32",
  "ProcessingTimeMS": 62
}
Authentication

Authentication is done by providing credentials object with each API request. The credentials object consists of following fields:

ChannelName String Required
The channel name as provided by SmartPayLive system.
ChannelPassword
The channel password as provided by SmartPayLive system.
Timestamp String Required
The current timestamp (YYYY-MM-DD HH:MM:SS.FFF).
RequestReference String Required
Unique value for every request. A GUID is suitable here.
ChannelHash String Required
This field is used to validate the channel credentials. The algorithm for generating ChannelHash is: 
UpperCaseString(SHA256(AES192CBC(ChannelName + Timestamp + ChannelPassword + RequestReference, ChannelPassword)))
Generate channel hash
PHP
function generateChannelHash($channelName, $channelPassword, $timestamp, $requestReference) {
  $data = $channelName . $timestamp . $channelPassword . $requestReference;
  
  $encryptionMethod = "aes-192-cbc";
  $iv = str_repeat(chr(0x0), 16);
  $encryptedData = openssl_encrypt($data, $encryptionMethod, $channelPassword, OPENSSL_RAW_DATA, $iv);
  
  return strtoupper(hash("sha256", $encryptedData));
}
Request payment

This API provides Merchants with the ability to receive money from their customers.

Request parameters

IntegratorTransactionReference String Required
The transaction reference number for this transaction on the Merchant’s system.
IntegratorCustomerId String Required
The customer identifier from the Merchant’s system.
Amount Float Required
The amount to be requested from the customer.
IntegratorRedirectUrl String Required
The URL that the customer will be redirected to once the transaction has completed.
CustomerEmailAddress String Optional
Email address of the customer. Required if the payment is a recurring payment.
CancelRedirectUrl String Required
The URL that the customer will be redirected to, if the payment is cancelled or failed.

Response

PaymentRequestId String
The transaction reference for this payment request on the payment gateway.
PaymentUrl String
The URL that the customer must be redirected to, in order to begin the payment process.
PaymentReference String
The payment reference number for this transaction. Appears on payment processing page.
POST /RequestPayment
Sample payment request body
{
  "Credentials": {
    "ChannelName": "<Channel-Name>",
    "ChannelHash": "<Channel-Hash>",
    "Timestamp": "<Current-Timestamp>",
    "RequestReference": "<Request-Reference>"
  },
  "OriginatingIpAddress": "<Client-IP>",
  "ClientVersion": "<Client-Version>",
  "Request": {
    "IntegratorTransactionReference": "1122334455",
    "IntegratorCustomerId": "321321",
    "Amount": "100",
    "IntegratorRedirectUrl": "http://example.com/complete",
    "CustomerEmailAddress": "customer-name@example.com",
    "CancelRedirectUrl": "http://example.com/cancel"
  }
}
POST /RequestPayment
Sample response
{
  "Response": {
    "PaymentRequestId": "0cc9ad66-9758-4279-a022-9b26f720ba7c",
    "PaymentUrl": "http://devweb.smartpaylive.com/payment/0cc9ad66-9758-4279-a022-9b26f720ba7c",
    "PaymentReference": "OP007H9W"
  },
  "Succeeded": true,
  "ErrorCode": null,
  "ErrorMessage": null,
  "RequestId": "d9796ff5-b6ee-46a3-9fa1-b85c9fe5d2cd",
  "ProcessingTimeMS": 106
}
Check payment status

This API helps Merchants check the payment status.

Request parameters

PaymentRequestId String Required
The payment gateway generated transaction reference that is being queried.

Response

Status Integer
Represents the current state of the transaction. Following is the list of possible payment statuses:
  • 1: Requested
  • 2: In Progress
  • 3: Completed Successfully
  • 4: Canceled
  • 5: Failed
AmountRequested Float
The amount requested to be paid.
RequestedByIntegratorName String
The name of the Merchant who requested the payment.
IntegratorTransactionReference String
The reference number supplied by the merchant for the payment.
IntegratorLogoUrl String
Merchant’s logo URL.
RedirectUrl String
The redirect URL generated when the payment was initially requested. It is included to allow the transaction to be resumed if necessary.
PaymentReference String
The payment reference number for the transaction.
PaymentUrl String
The URL that the customer must be redirected to, in order to begin the payment process.
CancelRedirectUrl String
The URL will-be/was used to redirect the customer, if the payment is cancelled or failed.
RecurringPaymentsRequested Integer
If the payment is recurring, the number of requested payments.
RecurringPaymentsCompleted Integer
If the payment is recurring, the number of successful payments that has been completed.
RecurringPaymentsRemaining Integer
If the payment is recurring, the number of remaining payments.
POST /QueryStatus
Sample request body
{
  "Credentials": {
    "ChannelName": "<Channel-Name>",
    "ChannelHash": "<Channel-Hash>",
    "Timestamp": "<Current-Timestamp>",
    "RequestReference": "<Request-Reference>"
  },
  "OriginatingIpAddress": "<Client-IP>",
  "ClientVersion": "<Client-Version>",
  "Request": {
    "PaymentRequestId": "f04e76c3-2290-4a1e-8195-d9727678c2a8"
  }
}
POST /QueryStatus
Sample response
{
  "Response": {
    "Status": 3,
    "AmountRequested": 100.00,
    "RequestedByIntegratorName": "<Channel-Name>",
    "IntegratorTransactionReference": "1122334455",
    "IntegratorLogoUrl": "http://devapi.smartpaylive.com/media/defaultmerchant.png",
    "RedirectUrl": "http://example.com/complete",
    "PaymentReference": "OP007H9W",
    "PaymentUrl": "http://devweb.smartpaylive.com/payment/0cc9ad66-9758-4279-a022-9b26f720ba7c",
    "CancelRedirectUrl": "http://example.com/cancel",
    "RecurringPaymentsRequested": 0,
    "RecurringPaymentsCompleted": 0,
    "RecurringPaymentsRemaining": 0
  },
  "Succeeded": true,
  "ErrorCode": null,
  "ErrorMessage": null,
  "RequestId": "0f677604-e38d-4840-a466-5f246488bb33",
  "ProcessingTimeMS": 16
}
Cancel payment

This API provides Merchants with the ability to cancel the payment. If the payment still has a number of recurring requests remaining, these will no longer be requested.

Request parameters

PaymentRequestId String Required
The payment gateway generated transaction reference that is being cancelled.
CancellationReason String Optional
The reason for cancelling the payment.
POST /CancelPayment
Sample request body
{
  "Credentials": {
    "ChannelName": "<Channel-Name>",
    "ChannelHash": "<Channel-Hash>",
    "Timestamp": "<Current-Timestamp>",
    "RequestReference": "<Request-Reference>"
  },
  "OriginatingIpAddress": "<Client-IP>",
  "ClientVersion": "<Client-Version>",
  "Request": {
    "PaymentRequestId": "2dcd39c4-c18e-45f9-b459-60ea57fc6e4f",
    "CancellationReason": "Your reason for cancellation"
  }
}
POST /CancelPayment
Sample response
{
  "Response": {},
  "Succeeded": true,
  "ErrorCode": null,
  "ErrorMessage": null,
  "RequestId": "3dde5697-c576-42fb-af4f-9c5cbe26bb32",
  "ProcessingTimeMS": 62
}
Webhook

When a payment is successfully completed, the payment gateway will notify the Merchant by performing an HTTP POST to an endpoint in the Merchant’s environment. This allows the Merchant to be notified of payments without having to query the status of each pending payment. The information posted to the webhook endpoint is as follows:

Arguments

PaymentRequestId String
The payment gateway generated transaction reference.
IntegratorTransactionReference String
The reference number supplied by the merchant for the payment.
PaymentStatus Integer
Represents the current state of the transaction. Following is the list of possible payment statuses:
  • 1: Requested
  • 2: In Progress
  • 3: Completed Successfully
  • 4: Canceled
  • 5: Failed
AmountRequested Float
The amount requested to be paid.
Fee Float
The payment processing fee.
NetAmount Float
The amount that will be credited to Merchant’s account.
DateCompletedUTC String
The payment completion date.
PaymentMethod Integer
The payment method.
NumRecurringPaymentsRemaining Integer
The number of recurring payments that are remaining.
Webhook payload
{
  "PaymentRequestId": "0cc9ad66-9758-4279-a022-9b26f720ba7c",
  "IntegratorTransactionReference": "1122334455",
  "PaymentStatus": 3,
  "AmountRequested": 100.00,
  "Fee": 2.3,
  "NetAmount": 97.7,
  "DateCompletedUTC": "2021-04-20T12:14:01.7878431Z",
  "PaymentMethod": 2,
  "NumRecurringPaymentsRemaining": 0
}
Conduct security checks

Conduct following four security checks to ensure that the data you are receiving in webhook is correct, from the correct source and has not been altered; you should not continue the process if a test fails!

  • Check if payment was requested by your (Merchant’s) system
    Validate request identifier
    PHP
    function validateRequestId($paymentRequestId, $orderPaymentRequestId) {
  return $paymentRequestId === $orderPaymentRequestId;
}
  • Compare payment amount
    Validate payment amount
    PHP
    function validatePaymentAmount($amountRequested, $orderTotal) {
  return (float)$amountRequested == (float)$orderTotal;
}
  • Check that the notification has come from a valid SmartPayLive domain
    Validate IP
    PHP
    function validateIP() {
  $validSmartPayIPs = [
    '41.185.80.146',
    '41.185.18.98',
    '41.185.18.99'
  ];

  $referrerIP = $_SERVER['REMOTE_ADDR'];

  return in_array($referrerIP, $validSmartPayIPs, true);
}
  • Perform server request to /QueryStatus API to confirm the details
    Validate payment status
    PHP
    function validatePaymentStatus($channelName, $channelPassword, $paymentRequestId, $paymentStatus) {
  // SmartPay class is available in our PHP class library, you can download it from https://smartpaylive.com/downloads/SmartPay.zip
  $smartPay = new SmartPay($channelName, $channelPassword);
  $status = $smartPay->queryStatus($paymentRequestId);
  if (!is_null($status) && $status->Succeeded == true) {
    if ($status->Response->Status == $paymentStatus && $paymentStatus == 3) {
      return true;
    }
  }
  return false;
}
    Bringing all the checks together
    PHP
    $requestIdCheck = validateRequestId($webhookPayload->PaymentRequestId, $orderDetails->PaymentRequestId);
$paymentAmountCheck = validatePaymentAmount($webhookPayload->AmountRequested, $orderDetails->OrderTotal);
$validIpCheck = validateIP();
$validPaymentStatusCheck = validatePaymentStatus($channelName, $channelPassword, $webhookPayload->PaymentRequestId, $webhookPayload->PaymentStatus);

if ($requestIdCheck && $paymentAmountCheck && $validIpCheck && $validPaymentStatusCheck) {
  // All checks have passed
} else {
  // Some checks have failed, check payment manually and log for investigation
}
Class libraries
Download PHP class library