Accept Payments

Accept Payment

With Startbutton, you can begin accepting payments in NGN, GHS, KES, ZAR, UGX, TZS, RWF, XOF (Côte d'Ivoire, Benin, Togo, Senegal, Mali, Burkina Faso) and XAF (Cameroun) for your business with a single API.

Post a request to the URL below, where the base URL is determined by the environment you are in.

BaseUrls

PROD : https://api.startbutton.tech

DEV/ Staging: https://api.startbutton.builditdigital.co

Endpoint

POST - {{baseurl}}/transaction/initialize

Authorization	Set value to `Bearer PUBLIC_KEY`
Content-type	Set value to application/json

The public key can be gotten from the 'Settings' page on your Startbutton dashboard.

When a customer clicks the payment action button on your website, ‘initialize a transaction’ by making a POST request to our API. Pass the email, amount, and other parameters to the initialize transaction endpoint. The table below lists the parameters that you can pass when initializing a transaction.

Param	Required?	Description
email	Yes	Email address of payer
amount	Yes	This should be in fractional units (kobo for NGN, pesewas for GHS). 300 will be passed as 30000
currency	Yes	Allowed values are: NGN, GHS, KES or ZAR
partner	No	Allowed values depend on what has been configured for you
reference	No	This is a unique identifier for your collection transaction
metadata	No	This allows you to pass your preferred parameters
redirectUrl	No	This allows you pass a Url where your customers will be redirected to after payment

If the API call is successful, we will return an authorization URL which redirects the customer to input their payment information to complete the transaction.

Sample request & sample response

Sample request:

Required parameters

{
    "amount": 30000,
    "currency": "",
    "email": "[e-mail]"
}

Optional parameters included

{
    "amount": 30000,
    "currency": "GHS",
    "email": "[e-mail]",
    
}

Passing metadata

{
    "amount": 30000,
    "currency": "KES",
    "email": "[e-mail]",
    "reference": "BUY781",
    "metadata": {
       "name": "ade",
       "location": "Nigeria"
    }
}

Sample response:

{
    "success": true,
    "message": "Encrypted",
    "data": "pay.startbuton.tech/#/{paymentCode}"
}

Transaction statuses

Currently, we have 6 transaction statuses namely;

Status	Description	Conclusive
initiated	Transaction has been initiated by merchant	No
pending	Transaction has been acknowledged	No
ongoing	Transaction waiting for authorization by the customer. Incase of Mobile money transaction- the customer is yet to input the PIN or OTP to authorize transaction.	No
verified	Payment has been received and verified by the payment processor. At this point, you can go ahead to give value to your customers for their purchase/payment	No
successful	We have been settled by the payment processor and the funds are now in your available balance.	Yes
abandoned	A transaction in the initiated status will be marked as abandoned if the customer does not make a payment after a minimum of one hour.	Yes

Redirect Url

If the transaction is successful, Startbutton will redirect the user back to the redirect url that you set on your Startbutton dashboard. If you do not set a redirect URL on your Startbutton dashboard or in the code, the customer may not be redirected back to your site after payment. See the FAQ segment on how to set your redirect url.

To use a dynamic redirect_url for each collection; pass the redirect URL in your transaction request as displayed below

{
    "amount": 50000,
    "currency": "NGN",
    "email": "[e-mail]",
    "redirectUrl":"https://www.google.com/"
}

Once this is done; the redirect URL you have provided on your dashboard will be overridden to use the URL provided for this particular transaction only.

Webhook Url

You can now include a custom webhook Url for each transaction's request payload. When a webhook Url is included in your request, it takes precedence over the default webhook Url set on your dashboard, which means that instead of a callback going to the default webhook set on the dashboard, it goes to the webhook Url specified in the request for that particular transaction. However, if you do not include this additional parameter, the callback for the transaction is sent to the webhook Url provided on the dashboard.

{
    "amount": 50000,
    "currency": "NGN",
    "email": "[e-mail]",
    "webhookUrl":"https://webhook.site/"
}

Specify payment method

To enable your customers to see only payment method(s) that you want them to use on the payment modal, you can pass "paymentMethods" in your request body. This can be passed as an array. Ensure that you only pass paymentMethods that are available for a particular currency. Here's a sample below:

{
    "amount": 30000,
    "currency": "NGN",
    "email": "[e-mail]",
    "paymentMethods": ["bank_transfer","card","ussd"]
}

Supported Currencies for Collections

Check out the Amount Limits and Settlement Timeline for each currencies here.

The following are the payment methods for each of the currencies

Currency	Payment methods
NGN	"bank", "card", "bank_transfer", "ussd", "payattitude"
GHS	"card", "mobile_money"
ZAR	"eft", "qr", "card"
KES	"card", "mobile_money"
UGX	"card", "mobile_money"
RWF	"mobile money"
XOF and XAF	"mobile_money"