1. The body of requests made to Fapshi's APIs must be JSON encoded.
2. All GET requests should have empty bodies, else an error will be automatically returned.
API credentials are used to make requests to all Fapshi endpoints available to developers. Failing to provide or providing wrong credentials will therefore lead to errors being returned in the response of your requests.
The credentials of the testing environment (sandbox) are available to all Fapshi users (on the dashboard), however, only verified Fapshi users have access to the live credentials, after creating a service.
The credentials should be added to the header of every request using the parameters apiuser and apikey as shown below.
The apikey of the live environment is given to you once and should be copied and stored safely. However, it is possible (and advisible) to generate a new apikey should you suspect that your current apikey has been compromised. This will invalidate the previous apikey.
When in live mode, the base URL is same for all endpoints. However, the sandbox environment has a different base URL.
In both environments, the URL paths are the same, just the base URL changes.
Live Base URL: https://live.fapshi.com
Sandbox Base URL: https://sandbox.fapshi.com
If any request made to the Fapshi payment API fails, the response will have a status code of 4XX (400, 403, 404) depending on the nature of the error and the body of the response will have a message parameter containing the reason for the failure.
However, a successful request will have, in its response, a status code of 200 and the content of its body will depend on the nature of the request.
The sandbox environment is used to test or better understand the functioning of the Fapshi payments API. Here, no real money is involved, however, it behaves in exactly the same way as if the money used were real. This is to help developers easily integrate our payments API on their application while still in development.
The sandbox or test environment works in the same way as the live environment. However, the credentials of the sandbox environment won’t work on the live and vice versa. Also, the base URL of the sandbox environment is different from of the live. See the Base URL section above.
On the sandbox, if you want to simulate payments with a local payment method, depending on the phone number chosen, you will either have a SUCCESSFUL or FAILED transaction status.
|MTN||670000000, 670000002, 650000000|
|ORANGE||690000000, 690000002, 656000000|
|MTN||670000001, 670000003, 650000001|
|ORANGE||690000001, 690000003, 656000001|
If you choose to pay with a number not among one of these, the transaction status will be decided in a random manner.
For international payment methods, the following card numbers will simulate SUCCESSFUL and FAILED transactions respectfully.
|5555 5582 6555 4449||Any 3 digits||Any future date|
|4000 0075 6000 0009||Any 3 digits||Any future date|
|4000 0048 4000 8001||Any 3 digits||Any future date|
|4000 0000 0000 9987||Any 3 digits||Any future date|
|4000 0000 0000 0069||Any 3 digits||Any future date|
|4100 0000 0000 0019||Any 3 digits||Any future date|
Moving from the test to the live environment will require you to replace your test keys with your live keys and switch the base URL of your request from the Sandbox Base URL to the Live Base URL. If done correctly, you are good go!
transId is the Id returned in the response of request (1) above. The status of a transaction can be:
CREATED: This means a payment attempt has not yet been made.
PENDING: This means the user is in the process of making a payment. Usually, the status of such a transaction will change to SUCCESSFUL or FAILED immediately the transaction is completed.
SUCCESSFUL: This means the payment attempt has been successful.
FAILED: This means the payment attempt failed.
EXPIRED: This means 24 hours have passed since the payment link was generated and no successful payment attempt was made in that time interval OR the link got manually expired like in (3) below to prevent payment.
Once the status of a payment is SUCCESSFUL or EXPIRED, no other payments can be made using its link.
Expiring a payment transaction will make it impossible for a payment to be made via the transaction link.
transId: required | string, this is the id returned while creating the transaction.
If the request is successful, the body of the response will contain the details of the payment of the EXPIRED transaction.
If a request is made to expire an already expired transaction, it will return an error with a 400-status code and a message: "Link already expired.""
If any of the payment requests in (1) above contains a user Id, then it is possible to get all transactions associated to this user Id. This request returns an array of objects containing the information related to the payments associated to the user Id passed in the URL of this request.
Fapshi offers the possibility to initiate a payment request directly to a user’s mobile device. However, the developer bares full responsibility over the user’s payment process i.e., from building a custom checkout form where user details are collected to verifying the final payment status of a transaction (SUCCESSFUL or FAILED).
This request, if successfully initiated, will directly prompt the user with the phone number specified in the request to confirm the transaction after which the developer will be notified with the details of the payment via his/her webhook if he/she had set one on his/her dashboard or will simply have to use (2) above to get the transaction details.
The image below shows the sequence...
1 - An external application with API credentials initiates a payment request to Fapshi’s API
2 - Request is validated and sent to the appropriate operator for processing
3 - User is prompted to validate payment by entering his/her PIN
4 - User approves or declines payment
5 - Operator notifies Fapshi with status of payment transaction
6 - Fapshi notifies external application (via the app’s webhook) with the final status of the transaction
On live mode, this endpoint is blocked by default. Contact support if needed.
Below are the body parameters required to perform a successful transaction.
amount: required | integer >= 100, amount to be paid by the user.
phone: required | string, phone number to which the request will be performed e.g., 67XXXXXXX, 69XXXXXXX, 65XXXXXXX.
medium: optional | string in [“mobile money”, “orange money”], this parameter can either be “mobile money” for MTN numbers or “orange money” for Orange numbers. However, if the operator the user wants to make the transaction with is not known, this parameter can simply be omitted and Fapshi will automatically detect and perform the request using the appropriate payment method.
name: optional | string, name of the user performing the payment.
email: optional | string, email of the user performing the payment. If the email is set, a payment confirmation receipt will be sent to this email.
userId: optional | string | length between (1, 100) | characters allowed [a-zA-Z0-9-_], if the user making the payment is known by your system, his id should be passed giving the possibility of later querying the payment history of this user.
externalId: optional | string | length between (1, 100) | characters allowed [a-zA-Z0- 9-_], this can be a transaction id, an order id or anything that can be used to reconcile this payment transaction to your application.
message: optional | string, contains a message describing the reason for the payment.
Direct payment transactions cannot and do not get expired. Consequently, their final state is either SUCCESSFUL or FAILED.
Make sure to take all necessary precautions to avoid the misusage of this endpoint. Should any complain be made, your account will be blocked as per our Terms & Conditions
Fapshi processes payments for multiple merchants. When your debit alert reads Fapshi Inc, it simply means that the transaction was made to a business or vendor that uses Fapshi for collections.
You do not need to pay to use Fapshi; all you need do is create an account (it's free). However, Fapshi offers some services which will deduct a minute percentage of your revenue when you use them.
No, you do not. Fapshi users can send money to people who do not have Fapshi accounts through payouts, provided the non-Fapshi users have an account on one of our supported operators. The procedure is simple and seamless.
Fapshi does not keep its users' money. All account balances, are kept with our partner operators. They are the ones who have entities to keep, preserve, and secure your money.
Verifying your account permits us to know who you are. With this, we can better serve you and give you personalized experiences on Fapshi.
We need to be sure of who you are and what your business does; this helps us to propose the best services to you and your clients. Our partners and regulatory bodies also require that we know who our clients are.
Fapshi is a set of tools that helps you to collect payments globally. We have prebuilt SDKs to help you integrate our APIs on your websites, web apps, or mobile apps. Fapshi users can collect all forms of payment through easy-to-create, self-managed payment links. You can equally create links for an invoice or product, and own an easy-to-customize online store.
If you forget your password, you can change it by accessing the login page. There, you can click on the “forgot password” link. Check this guide to see how to change your password if you forget it.
Your pin is a code that you use for money transfers and payouts on Fapshi; when you create an account, you'd see the option to create this code. If for some reason you lose your code, you'd have to submit a support ticket with your email and Support pin (can be seen on your account).
This tutorial shows how to contact support to reset/change your pin.