S2S Integration for Cards

Our S2S card APIs process sensitive customer data, so PCI DSS certification is mandatory. Currently, only Nigerian Naira payments are supported, with Mastercard, Visa, and Verve accepted

To access this API, please contact [e-mail] or reach out to your assigned representative through your usual communication channel to have it enabled. Otherwise, all requests will not go through.

Charging a customer’s card involves two main steps:

1. Initiate Charge Submit the transaction details along with the customer’s card and payment information to the initialize card endpoint

2. Verify Charge Depending on the card and issuer requirements, additional authorization may be required. We will return the specific information you need to collect from the customer, which should then be sent to the authorize charge endpoint. This serves as an added security layer. For example, you may need to pass an OTP provided by the customer to complete the authorization.

Additionally, we advise you perform a status query using our TSQ endpoint to confirm the final transaction status before delivering any value to the customer.

Initiate Charge

To charge a card, you must first collect the required card and payment details from the customer and structure your request payload accordingly.

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

BaseUrl

Sandbox/PROD : https://api.startbutton.tech

Endpoint

POST - {{baseurl}}/transaction/initialize/s2s/card

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.

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 value is: NGN
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

Sample request & sample response

Sample request:

{
    "amount": 25000,
    "email": "[e-mail]",
    "currency": "NGN",
    "card": {
        "cvv": "081",
        "number": "507850785078507812",
        "expiryMonth": "11",
        "expiryYear": "26"
    }
}

Sample response

Pin

{
    "success": true,
    "message": "Payment Request Successful",
    "data": {
        "reference": "66caxxxxxxxx",
        "nextStep": "pin",
        "message": "Validate card pin"
    }
}

OTP

3DS Authorisation

To complete 3DS authorization, simply redirect the user to the provided redirect URL (nextStep). The user will complete the authorization with their bank, after which we’ll redirect them back to the redirect URL you specified on your dashboard or when initiating the charge.

Verify Charge

The verification flow varies based on the card type being charged and is determined by the nextStep as returned above. After a charge is initiated, the customer may be required to authorize the transaction. Common authorization methods include one or more of the following:

PIN: The customer enters the card’s PIN.

One-time password (OTP): An OTP is sent to the phone number or email address linked to the customer’s bank account.

Endpoint

POST - {{baseurl}}/transaction/initialize/s2s/card/verify/:nextStep

Replace the path variable with the nextStep gotten from your request

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

Sample request & sample response

Sample request:

{
    "reference": "6abxxxxxxxx",
    "value": "770221"
} 

The value parameter should be populated with customer input according to the specified nextStep. For instance, when the nextStep is PIN, the customer’s PIN should be passed as the value.

Sample response

{
    "success": true,
    "message": "Charge attempted",
    "data": {
        "reference": "9e9cxxxxxx",
        "status": "success"
    }
}