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:
-
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. -
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. -
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. -
Query Payments
This service provides the mechanism for Paga to request historical payment(s) records from the biller. This service is optional. -
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 |
| 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 |
Updated about 4 years ago