Push Payment Request (API Reference)
- Olorunferanmi Joel
- nengimote.goodman
Highlighted below are instructions for establishing a connection between the payment terminal and your application using APIs.
To integrate, you have to be familiar with APIs and know how to make API calls.
How it works
The integration APIs allow your software to establish a connection with the POS terminal. Once the connection has been established, you can push transactions to the POS terminal.
To get started, you must have created a Moniepoint account and obtained the required credentials for integrating with the APIs as shown here. The APIs are secured using OAuth (Bearer token).
You must also enable ERP integration under your Moniepoint account settings. Navigate to POS terminal configuration > POS Terminal features to enable this feature.
Supported terminal app version: 1.7.2 or higher
Moniepoint Environments
Base URL (base_url): https://channel.moniepoint.com
Authentication
Your API requests are authenticated using API keys that can be generated from your Moniepoint account settings. You can generate a client that has an ID and a secret key that is kept and stored confidentially. This ID and secret are used to generate an access token that authorises all API calls. In case of exposure, the client ID and secret can be reset from your account settings.
Generate Access token
POST {{base_url}}/v1/authAuthorization: None
Content-Type: application/json
Request body:
{
"clientId": "xyz",
"clientSecret": "xyz-secret"
}Field Name | Description | Data Type | Required |
clientId | A valid generated client ID | String | true |
clientSecret | A valid generated client secret | String | true |
Sample success response
{
"accessToken": "hrPwtuF",
"tokenType": {
"value": "bearer"
},
"expiresIn": 8699,
"scope": "profile",
"jti": "f884300f-13b8-88bc-hgfhjf82d09e"
}Access token generated has expiry time. Check the field expiresIn
Sample failed response
{
"message": "Invalid credentials",
"errors": [
"Invalid credentials"
],
"timestamp": "2023-11-15T01:13:59.659193234",
"status": "UNAUTHORIZED"
}
Transactions
Push a payment request
This endpoint pushes transaction to the terminal
POST {{base_url}}/v1/transactionsAuthorization: Bearer token required (generate here)
Content-Type: application/json
Request body
{
"terminalSerial": "P260xyz",
"amount": 11000,
"merchantReference": "12345",
"transactionType": "PURCHASE",
"paymentMethod": "CARD_PURCHASE"
}Field Name | Description | Data Type | Required |
terminalSerial | The unique terminal serial number gotten from dashboard or terminal device information | String | true |
amount | Amount to be paid | int | true |
merchantReference | Any unique string of characters that can be used to identify a transaction | String | true |
transactionType | The type of transaction | Enum (PURCHASE) | true |
paymentMethod | The preferred method of payment on the terminal | Enum (CARD_PURCHASE, POS_TRANSFER, ANY) | false |
Sample success response
Code: 202
Description: AcceptedSample failed responses
Code: 401
Description: Unauthorized
{
"timestamp": 1700011838927,
"status": 401,
"error": "Unauthorized",
"path": "/v1/transactions"
}Code: 400
Description: Bad Request
{
"message": "Transaction exists",
"errors": [
"Transaction exists"
],
"timestamp": "2023-11-15T01:31:33.375303704",
"status": "BAD_REQUEST"
}
Get Transaction Status
This endpoint queries the status of a specific transaction using the merchant reference
GET {{base_url}}/v1/transactions/merchants/{merchantReference}Authorization: Bearer token required (generate here)
Content-Type: application/json
Path Parameters
Field Name | Description | Data Type | Required |
merchantReference | Unique reference generated by merchant to identify the transaction | String | true |
Sample success response
Code: 200
Description: OK
{
"clientId": "api-client-xyz",
"businessOwnerId": 1,
"terminalSerial": "P260xyz",
"requestAmount": 11000,
"transactionReference": "",
"merchantReference": "Any Unique Reference",
"transactionType": "ANY",
"requestPaymentMethod": "CARD_PURCHASE",
"actualPaymentMethod": null,
"actualAmount": null,
"processingStatus": "PENDING",
"responseCode": null,
"responseMessage": null,
"metaData": null
}Field Name | Description | Data Type |
clientId | The client ID | String |
businessOwnerId | The business owner ID | int |
terminalSerial | The terminal serial | String |
requestAmount | The amount sent with payment request | int |
transactionReference | Unique transaction reference generated for each transaction | String |
merchantReference | Unique reference generated by merchant to identify the transaction | String |
transactionType | The transaction type | Enum (PURCHASE) |
requestPaymentMethod | The payment method sent with payment request | Enum (CARD_PURCHASE, POS_TRANSFER, ANY) |
actualPaymentMethod | The actual payment method used on the terminal | Enum (CARD_PURCHASE, POS_TRANSFER, ANY) |
actualAmount | The actual amount paid on the terminal | int |
processingStatus | The request status for the transaction | Enum (PROCESSED, CANCELLED, PENDING) |
responseCode | The transaction response code | String |
responseMessage | The transaction response message | String |
metaData | The metadata of the transaction carried out | String |
Sample failed responses
Code: 401
Description: Unauthorized
{
"timestamp": 1700011838927,
"status": 401,
"error": "Unauthorized",
"path": "/v1/transactions"
}Code: 404
Description: Not Found
{
"message": "Transaction does not exist",
"errors": [
"Transaction does not exist"
],
"timestamp": "2023-11-15T01:44:01.099192862",
"status": "NOT_FOUND"
}