# 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 {% hint style="warning" %} To access this API, please contact or reach out to your assigned representative through your usual communication channel to have it enabled. Otherwise, all requests will not go through. {% endhint %} 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. {% hint style="info" %} Post a request to the URL below, where the base URL is determined by the environment you are in. {% endhint %}
BaseUrl Sandbox/PROD : ;
{% tabs %} {% tab title="Endpoint" %} POST - `{{baseurl}}/transaction/initialize/s2s/card` {% endtab %} {% endtabs %}
AuthorizationSet value to `Bearer SECRET_KEY`
Content-typeSet value to application/json
{% hint style="info" %} The secret key can be gotten from the 'Settings' page on your Startbutton dashboard. {% endhint %} | 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": "text-card-ghs@yopmail.com", "currency": "NGN", "card": { "cvv": "081", "number": "507850785078507812", "expiryMonth": "11", "expiryYear": "26" } } ``` Sample response {% tabs %} {% tab title="Pin" %} ```json { "success": true, "message": "Payment Request Successful", "data": { "reference": "66caxxxxxxxx", "nextStep": "pin", "message": "Validate card pin" } } ``` {% endtab %} {% tab title="OTP" %} ``` { "success": true, "message": "Payment Request Successful", "data": { "reference": "66caxxxxxxxx", "nextStep": "otp", "message": "Validate card pin" } } ``` {% endtab %} {% tab title="3DS Authorisation" %} ```json { "success": true, "message": "Payment Request Successful", "data": { "reference": "5f42xxxxxxxx", "nextStep": "https://standard.xxxxx.co/charge/auth/d5e0bb4fi80410a4225?selected_currency=0&lang=en", "message": "Open the provided URL" } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} 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. {% endhint %} ## **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. {% tabs %} {% tab title="Endpoint" %} POST - `{{baseurl}}/transaction/initialize/s2s/card/verify/:nextStep` {% endtab %} {% endtabs %} > Replace the path variable with the nextStep gotten from your request
AuthorizationSet value to `Bearer PUBLIC_KEY`
Content-typeSet value to application/json
#### Sample request & sample response **Sample request:** ``` { "reference": "6abxxxxxxxx", "value": "770221" } ``` {% hint style="info" %} 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`. {% endhint %} Sample response ``` { "success": true, "message": "Charge attempted", "data": { "reference": "9e9cxxxxxx", "status": "success" } } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://startbutton.gitbook.io/startbutton-product-api/startbutton-api-doc/server-to-server-integration/s2s-integration-for-cards.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.