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

{% hint style="info" %}
Post a request to the URL below, where the base URL is determined by the environment you are in.
{% endhint %}

<details>

<summary>BaseUrl</summary>

Sandbox/PROD : <https://api.startbutton.tech&#x20>;

</details>

{% tabs %}
{% tab title="Endpoint" %}
POST - `{{baseurl}}/transaction/initialize`
{% endtab %}
{% endtabs %}

<table><thead><tr><th width="167">Authorization</th><th>Set value to `Bearer PUBLIC_KEY`</th></tr></thead><tbody><tr><td>Content-type</td><td>Set value to <code>application/json</code></td></tr></tbody></table>

{% hint style="info" %}
The public key can be gotten from the 'Settings' page on your Startbutton dashboard.
{% endhint %}

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:**

{% tabs %}
{% tab title="Required parameters" %}

<pre><code>{
    "amount": 30000,
    "currency": "<a data-footnote-ref href="#user-content-fn-1">GHS</a>",
    "email": "test@customer.com"
}
</code></pre>

{% endtab %}

{% tab title="Optional parameters included" %}

<pre><code>{
    "amount": 30000,
    "currency": "GHS",
    "email": "test@customer.com",
    <a data-footnote-ref href="#user-content-fn-2">"reference": "be6eaxxxxxxx"</a>
}
</code></pre>

{% endtab %}

{% tab title="Passing metadata" %}

```
{
    "amount": 30000,
    "currency": "KES",
    "email": "test@customer.com",
    "reference": "BUY781",
    "metadata": {
       "name": "ade",
       "location": "Nigeria"
    }
}
```

{% endtab %}
{% endtabs %}

#### Sample response:

<pre><code><strong>{
</strong><strong>    "success": true,
</strong>    "message": "Encrypted",
    "data": "pay.startbuton.tech/#/{paymentCode}"
}
</code></pre>

#### 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.](#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.

### Custom 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](https://startbutton.gitbook.io/startbutton-product-api/available-currencies#for-collections).

The following are the payment methods for each of the currencies

<table><thead><tr><th width="154">Currency</th><th>Payment methods</th></tr></thead><tbody><tr><td>NGN</td><td><code>"bank"</code>, <code>"card"</code>, <code>"bank_transfer"</code>, <code>"ussd"</code>, <code>"payattitude"</code></td></tr><tr><td>GHS</td><td><code>"card"</code>, <code>"mobile_money"</code></td></tr><tr><td>ZAR</td><td><code>"eft"</code>, <code>"qr"</code>, <code>"card"</code></td></tr><tr><td>KES</td><td><code>"card"</code>, <code>"mobile_money"</code></td></tr><tr><td>UGX </td><td><code>"card"</code>, <code>"mobile_money"</code></td></tr><tr><td>RWF</td><td><code>"mobile money"</code></td></tr><tr><td>XOF and XAF</td><td> <code>"mobile_money"</code></td></tr></tbody></table>

[^1]: Allowed values are: NGN, USD, GHS, KES, ZAR, TZS, UGX, RWF, USDC, USDT, XOF

[^2]: Your reference will be returned in the webhook response as "userTransactionRef"