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-dev.startbutton.tech

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:

{
    "amount": 30000,
    "currency": "",
    "email": "test@customer.com"
}

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": "test@customer.com",
    "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": "test@customer.com",
    "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": "test@customer.com",
    "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"

Last updated