S3P API Concepts
Glossary
S3P API | Smobilpay Third Party (S3P) API |
Merchant | A Merchant is a service provider (business entity) that its offers services for distribution or payment over the Smobilpay platform. Examples:
|
Service | A service is a generic term used to describe anything that can be paid for in Smobilpay. This API provides access to services of the type "Bill Payments". Other service types shall be added in due course. |
Bill | Payment Item referring to the payment of already consumed or invoiced services by a consumer.
|
Product | Much like real world products, payment items of this kind consist of the purchase of a digital or physical good or service |
Topup | This is a special subtype of a product payment item that will recharge (topup) an account – usually with a mobile network provider. Depending on the service provider some may return a digital code (PIN or serial number) which can then be redeemed with the respective service provider it was purchased for. |
Voucher | A special subtype of a product payment that will return a digital code (PIN or serial number) which can then be redeemed with the respective service provider it was purchased for. |
Subscription | Payment Item referring with a direct reference to an account/customer registered with the subscription provider without a direct payment obligation. |
PTN | Unique Smobilpay payment transaction number. Identifier used throughout Smobilpay to identify and track a payment. |
Cash-In | Payment service that allows customers to deposit money in their mobile wallets |
Cash-Out | Payment service that allows customers to withdraw (or transfer) money from their mobile wallets |
Quote | A quote is a request to the system that returns the costs involved in a payment collection |
Payment Item Id | Identifier used to clearly identify a payment item in Smobilpay |
Smobilpay | Maviance payment solution |
Dynamic API Masterdata
As Smobilpay constantly expands its network of supported integrations and services, it is necessary to offer an API that allows it to grow without having to constantly extend and change it’s interface to include new service providers.
To relay this dynamic nature, the S3P API provides access to all of it’s services via dynamic master data in form of context constructs called merchants and services which are served by the API in form of dynamic data.
Changes to the availability of services or the addition of new services and merchants do not require an update of the API integration, but merely a refresh of the related data endpoints.
Merchants and services
Smobilpay structures information based on a so called merchant (which identifies the actual company) and its dependent services (which contains information about the configuration).
For example:
a single utility company (e.g. ENEO) offers multiple services: the collection of electricity bills as well as prepaid meter purchases
a single MNO (e.g. Orange or MTN) offer multiple services: cashin, cashout, airtime topup
Regardless of which service is being offered, the company and it’s metadata like name, location, logo, etc. stay the same.
However, each service has different requirements: One service may enable Bill Payment Transaction while the other one offers Voucher Purchase Transaction and thus require different payment flows.
Each service also has a set of different criteria ranging from required data during the payment processes to hints and validation support in order to improve the user experience.
Each service is categorized into “Service types” which indicate what kind of service products are offered and how to retrieve the Payment Item Id required for payment collection.
Service Type | Endpoint to call to get available PayItemId | Description | When to call |
SEARCHABLE_BILL | GET /bill | Search for bills by a . the result set will contain a list of all open bills for the selected service number. Each bill has its own Payment Item Identifier. | On demand during Bill Payment Transaction |
NON_SEARCHABLE_BILL | GET /bill | Search for non-searchable bills, the result set will always contain a single bill item with a Payment Item ID to perform the collection for the provided service number. | On demand during Bill Payment Transaction |
PRODUCT | GET /product | This service provides a list of all available products for all services. | Once during Initialization |
TOPUP | GET /topup | This service provides a list of all available topup packages. DEPRECTATED: Some providers will return a digital code for manual redeeming. This code will be provided in the response object of a successful collection. This functionality has been moved into the /voucher endpoint and will be removed in the next version of this API | Once during Initialization |
SUBSCRIPTION | GET /subscription | When calling the endpoint the result set will contain a list of all available subscriptions registered under the provided service number. Each subscription has its own Payment Item Identifier. | On demand during Subscription Payment Transaction |
CASHIN | GET /cashin | This service provides available cashin packages to be made to the system. | Once during Initialization |
CASHOUT | GET /cashout | This service provides available cashout packages to be made to the system. | Once during Initialization |
VOUCHER | GET /voucher | This service provides a list of all available vouchers for all services. A purchase of a voucher will return a digital code for manual redeeming. This code will be provided in the response object of a successful collection. | Once during Initialization |
Initialization of Masterdata
As stated before, service and merchant information, as well as information about payable products are dynamic in nature but can be considered masterdata with long times between changes. They should be called and refreshed during application initialization or regular intervals.
Service number verification
Some service providers allow the pre-collection verification of the entered service number in order to ensure that it is valid. Services supporting this feature have the "isVerifiable" attribute set to true. This feature can be accessed via the /verify endpoint.
Local and System currency
Smobilpay distinguishes between two types of currency: System and Local currency:
Local currency: Currency of products offered by a service. If payments are collected to e.g. pay a bill for a Nigerian service, then the amount would be presented in NGN.
System currency: This is the currency Smobilpay is keeping it’s accounts in (XAF). The system currency will be returned in every call along with the local currency. An agent account is always kept in the system currency and will always be charged in the system currency by the converted amount.
Payment Flow
1. Retrieve the Payment Item Id
A payment item id is an attribute used to clearly identify a payment item in Smobilpay. The payment item id is retrieved when requesting a payment items details and needs to be provided when requesting a quote and performing the subsequent collection.
2. Request a quote
In order to execute the payment collection a "quote" needs to be requested from Smobilpay for the selected payment item id and the amount to be collected by calling the /quotestd endpoint.
The quote endpoint responds with the price for the collection (basic service amount + Smobilpay service fee) as well as a unique quote identifier, which needs to be provided in the payment collection request to finalize the process.
The price is the amount that will be deducted from the API user agent account for the successful collection of a payment.
Restrictions:
A quote is only valid for a short period of time and will then expire. Using an expired quote id will result in an error.
A quote is only valid for a single collection. Using the same quote id again for another payment will result in an error.
3. Execute Payment Collection
The payment collection is triggered by calling the /collectstd endpoint with the quote id.
Depending on regulations and service configuration the input parameters vary and need to heed the configuration of a service as outlined in the section “Dynamic API Masterdata”.
The payment collection allows the injection of a custom transaction identifier (txid).
Each payment collection is uniquely identified by a payment transaction number (PTN) which is returned in the payment collection response. This identifier must be maintained for reconciliation and status tracking.
4. Request payment status
The current payment status can be retrieved by calling GET /verifytx
This endpoint can be called with either:
payment transaction number (PTN) genertated by Smobilpay
custom transaction identifier (txid) that was provided during the collection request
To provide tractability each payment transaction has a status indicating its state. The following statuses are supported:
Status | Description |
PENDING | Payment has been sent to service provider, but confirmation has not yet been received. This is the default status. |
ERRORED | Payment has failed |
SUCCESS | Payment was properly processed and confirmed by service provider |
REVERSED | Payment has been reversed (will only occur during reconciliation process) |
IMPORTANT: Only payments with status SUCCESS have been completely processed and confirmed. We recommend not to charge customers until the payment has this status.