🎉

Integrate Fapshi's APIs to collect payments globally...

Introduction Lastly updated on: 29-10-2022

The Fapshi developer API is used to programmatically generate links that are used to collect payments. Depending on your level of account verification, the links generated by a developer may have different payment options. This documentation explains how to leverage the API to receive payments on any application. But first, some basic knowledge required to get started.

Note

Here, we assume that you've already gone through the API section of the documentation. If you haven't, please do so and Activate your Fapshi account.

Preliminary Knowledge

This section explains a few things you must know in order to use the APIs effectively.

Note!

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

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.

These credentials (apiuser and apikey) can be obtained on the Fapshi dashboard after some prior account verification (See the Activate your Fapshi account section).

The credentials should be added to the header of every request using the parameters apiuser and apikey as shown below.

Postman using the API credentials

Attention!

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.

The combination of your apiuser and apikey should be kept extremely jealously because they essentially serve as a username and password which are used to authenticate developers in our system and should in no case be shared or made public. You bare full responsibility should your credentials be used in a way that violates our Terms & Conditions or Privacy Policy.

Base URL

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

Failed and Successful Requests

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.

Failed request example

Live Vs Sandbox Environment

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.

Numbers for Successful Transactions:
MTN 670000000, 670000002, 650000000
ORANGE 690000000, 690000002, 656000000
Numbers for Failed Transactions:
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.

Details for Successful Transactions:
Number CVC Date
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
Details for Failed Transactions:
Number CVC 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

Note!

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!

Ready to get started?

We have done all necessary to help you quickly setup and integrate the API on your platform. Check our SDKs and sample code to get going.

Payment Endpoints

The endpoints below can be used to integrate and monitor the payment of users on your application. Feel free to get in touch with us for:

1. Support: https://fapshi.com/support

2. Inquiries: https://fapshi.com/contact or join our Slack channel and place your inquiry.

3. Feedback/Suggestions: Send an email to feedback@fapshi.com or hello@fapshi.com, call us (+237 673 669 111) or join our Slack channel

SDKs to help you

The implementation of the endpoints in this section in various languages can be found on GitHub at https://github.com/Fapshi/SDKs.

2. Get Payment Transaction Status

Endpoint: /payment-status/:transId (GET)

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.

Note!

Once the status of a payment is SUCCESSFUL or EXPIRED, no other payments can be made using its link.

Payment status response example

3. Expire a Payment Transaction

Endpoint: /expire-pay (POST)

Expiring a payment transaction will make it impossible for a payment to be made via the transaction link.

Parameters:

transId: required | string, this is the id returned while creating the transaction.

Return:

If the request is successful, the body of the response will contain the details of the payment of the EXPIRED transaction.

Note!

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.""

Transaction expiration request and response example

4. Get Transactions with the Same User ID

Endpoint: /transaction/:userId (GET)

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.

User transaction history response example

5. Initiate a Direct Payment Request

Endpoint: /direct-pay (POST)

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...

Direct payment sequence diagram

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

Note!

On live mode, this endpoint is blocked by default. Contact support if needed.

Below are the body parameters required to perform a successful transaction.

Parameters:

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.

Return:

  • If the request is successful, the response will have a status code of 200 and its body will contain a transId variable. This transId is the id of the payment transaction and can be used to get its status, hence, it is judicious to store this transId on your system.
  • If the request fails, the response will have a status code of 4XX depending on the reason for the failure and a message property describing the reason for the failure.

Note!

Direct payment transactions cannot and do not get expired. Consequently, their final state is either SUCCESSFUL or FAILED.

Direct payment request and response example

Attention!

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

Ready to get started?

We have done all necessary to help you quickly setup and integrate the API on your platform. Check our SDKs and sample code to get going.

Using Web Hooks

A webhook is an API endpoint made available to external applications that can be called to notify your application whenever a significant event occurs. This gives your application the ability to respond or react to these events.

It is possible to set a webhook per service on your Fapshi dashboard. If the webhook is set, a POST request will be made to this webhook URL every time the status of a payment changes to SUCCESSFUL, FAILED or EXPIRED. The body of this request will be the same as the body of the response received when querying the status of a transaction. See the Get Transaction Status section above.

On Fapshi, a webhook call is triggered when:

  • A payment attempt is successfully completed.
  • When a payment attempt is made but fails. This will occur only when the user tries to pay with operator networks like MTN Mobile Money or Orange Money.
  • A payment link expires. That is, if 24 hours after generating a payment link no successful attempt has been made, the webhook call will be triggered.

Here's what a webhook response looks like.

Body of a webhook format

Note

Your server response time should be as short as possible to avoid timeout errors, since just ONE request is made to your webhook per event, irrespective of whether your server responds or not.

FAQs

Here's a list of frequently asked questions; if you don't find an answer to your query here, please contact us for help. If your query is technical, send us a support request instead, or join our community on Slack and pose your question.

Payments (payment-related questions)

Why was I debited?

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.

Do I need to pay to use Fapshi?

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.

Do I need to have a Fapshi account for someone to send me money?

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.

Does Fapshi keep my money?

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.

Account

Why must I verify my account?

Verifying your account permits us to know who you are. With this, we can better serve you and give you personalized experiences on Fapshi.

Why do I need to verify my business?

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.

General (general questions on using Fapshi)

What is Fapshi?

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.

What do I do if I forget my password?

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.

What do I do if I forget my pin?

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.