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

Argument Name

Type

Requirement

Description

isTest

Boolean

Required

Indication whether the service call is a test call (true) or live call (false). Merchant services must honour this flag in order to provide a continuous way of testing merchant services without impacting live systems.

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

Argument Name

Type

Requirement

Description

services

IntegrationService (restricted string) list

Required (0 or more items)

List of IntegrationService types (string) indicating which integration services are supported

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

Argument Name

Type

Requirement

Description

isTest

Boolean

Required

Indication whether the service call is a test call (true) or live call (false). Merchant services must honour this flag in order to provide a continuous way of testing merchant services without impacting live systems.

customerAccountNumber

String

Optional

Account number identifying the customer at the merchant

customerFirstName

String

Optional

Customer's first name

customerLastName

String

Optional

Customer's last name

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

Argument Name

Type

Requirement

Description

status

Status

Required

The status of the payment attempt. See Status object described below.

message

String

Optional

A transaction result message generated by the Merchant.

isValid

Boolean

Required

Whether the customer information provided represents a valid customer or not.

firstName

String

Optional

The customer's first name.

lastName

String

Optional

The customer's last name.

lastPaymentDate

date

Optional

date of last payment by customer

accountStatus

CustomerAccountStatus

Optional

status of customer see CustomerAccountStatus object below.

paymentDueDate

date

Optional

date of next due payment

isDisplayed

Boolean

Optional

this flag allow the system to display the customer information on the portal

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

Argument Name

Type

Requirement

Description

isTest

Boolean

Required

Indication whether the service call is a test call (true) or live call (false). Merchant services must honour this flag in order to provide a continuous way of testing merchant services without impacting live systems.

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

Argument Name

Type

Requirement

Description

services

Merchant Service List

Required

List of MerchantService objects indicating which merchant service offerings provided by the merchant. See the Merchant Service List Below.

Status

Status

Required

The status of the payment attempt. See Status object described below.

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

Argument Name

Type

Requirement

Description

isTest

Boolean

Required

Indication whether the service call is a test call (true) or live call (false). Merchant services must honour this flag in order to provide a continuous way of testing merchant services without impacting live systems.

Transaction

Transaction

Required

The Transaction object providing the payment transaction details. See Transaction object below.

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

Argument Name

Type

Requirement

Description

status

Status

Required

The status of the payment attempt. See Status object described below.

uniqueTransactionId

String

Optional

The unique transaction id of the payment transaction. If one is provided as part of the payment request, this must be the same one, otherwise, one can be generated and provided as part of this response by the Merchant system.

customerReference

String

Optional

The Merchant's customer reference number for the customer affected by this payment. This may have been provided as part of the request transaction.

merchantStatus

String

Optional

A merchant-specific status code generated by the merchant coding the result of the transaction

message

String

Optional

A transaction result message generated by the Merchant

confirmationCode

String

Optional

A confirmation value or reference to be provided to the customer in reference to a successful transaction

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.

Value

Description

SUCCESS

The execution was processed successfully

CLIENT_ERROR

The execution failed due to some invalid parameters or other aspect of information provided by the client in the request

SERVER_EROR

The execution failed due to an error on the Merchant system side (usually accompanied by a merchant error status code and/or a message)

Transaction Object.

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

Argument Name

Type

Requirement

Description

utcTransactionDatetime

dateTime

Optional (required for submission)

The date/time stamp of the transaction, in UTC (GMT) time-zone.

transactionType

TransactionType

Optional (required for submission)

The enumerated transaction type

totalAmount

Double

Optional (required for submission)

The total amount value of the transaction

merchantAmount

Double

Optional (required for submission)

The gross amount paid to the Merchant as part of this transaction

isCredit

Boolean

Optional (required for submission)

Whether the transaction credits the sending customer (true) or debits (false) - This will be true for payment transactions

pagaTransactionId

String

Optional (required for submission)

A common Paga transaction id identifying the transaction. As part of a transaction submission this will be provided by the Paga platform to uniquely identify the transaction to the Merchant. This transaction id is shared with all parties involved in this transaction

merchantTransactionId

String

Optional

A unique transaction id identifying the transaction on the Paga System. this may be provided by the merchant in response to a transaction submission in order to provide a reference to Paga for the transaction.

currency

String

Optional

ISO 4217 currency code of currency in which transaction occurs

customerReference

String

Optional

A reference number identifying the customer at the merchant. This may be an account number or other merchant-specific identifier

customerFirstName

String

Optional

The first name of the customer subject of the transaction

customerLastName

String

Optional

The last name of the customer subject of the transaction

channel

Channel

Required

The communication channel (eg. SMS, ONLINE etc.) by which the customer initiated the transaction. See Channel object described.

description

String

Optional

A description of the transaction

customerPhoneNumber

String

Optional

The phone number of the customer that performed the operation

services

MerchantService list

Required

List of MerchantService objects indicating which merchant service offerings provided by the merchant. See the Merchant Service List Below.

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)

Argument Name

Tyoe

Requirment

Description

name

String

Required

The displayed human-readable name of the merchant service

price

double

Required

The price for this service

shortCode

String

Required

The short-code for this service offering - this is just an arbitrary code that must be 5 characters or less which will be used to identify the service on some channels (such as SMS). Each short code must be unique for all services provided by the Merchant

productCode

String

Required

This is a product code which identifies the service in the Merchants systems. This provides the merchant-specific code for the service which will be sent to the merchant system as part of the transaction in order to help identify the service on the Merchant systems.

isPublic

boolean

Required

This is a flag identifying whether this service should be exposed to customers for selection or not.

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.

Value

Description

SMS

Service methods initiated by SMS on the Paga platform

ONLINE

Service methods initiated online on the Paga platform

VOICE

Service methods initiated by voice telephony on the Paga platform

EMAIL

Service methods initiated by email on the Paga platform

USSD

Service methods initiated by USSD on the Paga platform

E_WIDGET

Service methods integrated by an integrated e-widget (Paga e-widget integrated in third-party online platform)

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

Value

Description

BILL_PAY

A bill payment transaction

CustomerAccountStatus [Enumeration]

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

Value

Description

ACTIVE

Customer's account is Active

INACTIVE

Customer's account is Inactive