Notification Services

The Merchant Web-Services Platform enables merchants to integrate with the Paga platform. This enables Paga to process automated real-time payment transactions with the Merchant's systems using secure RestFul Web Services. This specification describes the RestFul web-services that the merchant must implement for automated integration.

The services that are described in this specification are:

1. Get Supported Integration Services
   This service allows Paga to verify which of the integration services the merchant implementation supports in order to configure subsequent interaction with the merchant platform. This service is mandatory.

2. Payment Execution
   This service provides the mechanism for Paga to submit a payment notification to the merchant systems and receive confirmation of its approval. This service is mandatory.

3. Customer Validation
   This service allows Paga to verify the existence of a customer in good standing with the merchant using several customer properties. This service is optional.

4. Query Payments
   This service provides the mechanism for Paga to request historical payment(s) records from the biller. This service is optional.

5. Get Merchant Services
   This service provides the mechanism for Paga to request a list of named merchant services and associated service properties provide by the merchant. This service is optional.

1. Get Supported Integration Services

This service is mandatory.
This service allows Paga to verify which of the integration services the merchant implementation supports in order to configure subsequent interaction with the merchant platform.
The web service must implement this service in order to provide a list of the services that it supports. The response from the server will include a list of any of the string provided by the integration service simple type list.

Service name: getIntegrationServices

Request Parameters

url: the url should end with /getIntegrationServices

Headers:
Authorization: "Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Content-Type: "application/json"
Accept: "application/json"

Body:
{  
   "isTest":true
}

{  
   "services":[
          "SUBMIT_PAYMENT",
          "VALIDATE_CUSTOMER",
          "QUERY_PAYMENTS"
        ]
}

Response Parameters

2. Customer Validation

This service is optional.
This service allows Paga to verify the existence of a customer in good standing with the merchant using several customer properties.

Service name: validateCustomer

Request Parameters

url: the url should end with /validateCustomer

Headers:
Authorization: "Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Content-Type: "application/json"
Accept: "application/json"

Body:
{  
   "isTest":true,
   "customerFirstName":"",
   "customerLastName":"",
   "customerAccountNumber":"1234567"
}

{  
   "status":"SUCCESS",
   "message":"Notification processed successfully",
   "isValid":true,
   "firstName":"john",
   "lastName":"doe",
   "lastPaymentDate":"ISO date",
   "accountStatus":"active",
   "paymentDueDate":"ISO Date",
   "isDisplayed":true
}

Response Parameters

3. Get Merchant Services

This service provides the mechanism for Paga to request a list of named merchant services and associated service properties provided by the merchant.

Service name: getMerchantServices

Request Parameters

url: the url should end with /getMerchantServices

Headers:
Authorization: "Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Content-Type: "application/json"
Accept: "application/json"

Body:
{  
   "isTest":true
}

{  
   "status":"SUCCESS",
   "services":[  
      {  
         "name":"SILVER PLAN",
         "price":"32000.0",
         "shortCode":"SP",
         "productCode":"XS_SP",
         "isPublic":"true"
      },
      {  
         "name":"GOLD PLAN",
         "price":"50000.0",
         "shortCode":"GP",
         "productCode":"XS_GP",
         "isPublic":"true"
      }
   ]
}

Response Parameters

4. Submit Transaction Execution

This service is mandatory.
This service provides the mechanism for Paga to submit a payment notification to the merchant systems and receive confirmation of its approval.
Execution of this service should trigger payment logic in merchant system and then provide response including success/fail result and other properties to Paga system.

Service name: submitTransaction

Request Parameters

url: the url should end with /submitTransaction

Headers:
Authorization: "Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Content-Type: "application/json"
Accept: "application/json"
Body:

{  
   "isTest":true,
   "transaction":{  
      "utcTransactionDateTime":"2018-06-13T15:27:32",
      "transactionType":"BILL_PAY",
      "totalAmount":500,
      "merchantAmount":492.5,
      "isCredit":"true",
      "pagaTransactionId":"XBFJX",
      "merchantTransactionId":"BP-C_2018061315273249_1448479_XBFJX",
      "currency":"NGN",
      "customerReference":"70000587",
      "customerFirstName":"ShawnUniquw",
      "customerLastName":"Storm",
      "channel":"ONLINE",
      "description":"CUSTOMER_BILL_PAY.description",
      "customerPhoneNumber":"+2348177777087",
      "services":[  
         {  
            "isPublic":true,
            "name":"Fruit and Nut Mix",
            "price":500,
            "shortCode":"Fru"
         }
      ]
   }
}

{
   "status": "SUCCESS",
   "uniqueTransactionId": "172a56a0-3dde-4837-986b-bc8965b1d35f",
   "customerReference": "000000456",
   "merchantStatus": "1000",
   "message": "Successfully executed payment",
   "confirmationCode": "XHSUR-23724-FSR4"
}

Response Parameters

5. JSON Schema Objects

Status Enumeration

The status enumeration provides a standard set of status codes by which the Merchant system can respond to to indicate the success or failure state of the attempted service call.

Transaction Object.

The transaction object captures all the details of a financial transaction.

MerchantService

The MerchantService object describes a merchant-specific service offering along with pricing and coding information.
A MerchantService may be made up of other Merchant services (such as when service offerings are grouped and potentially priced differently in their groupings)

Channel [Enumeration]

The channel enumeration list all the possible channels through which transactions and other service calls may be initiated on the Paga platform. For some service calls, the initiating channel may be submitted to the Merchant platform.

TransactionType [Enumeration]
The status enumeration provides a standard set of transaction type codes by which indicate the type of transaction executed.

CustomerAccountStatus [Enumeration]

This status enumeration provides a standard set of status codes by which indicate a customer's account status.