đź“š API Docs

Welcome to Bancwild Payment Gateway Documentation

Your trusted solution for secure and seamless payments in South Africa.

What We Offer:

  • **EFT Integration**: Simplify payments with real-time electronic funds transfer.
  • **Bank Support**: Compatible with all major South African banks.
  • **Secure Transactions**: State-of-the-art encryption and compliance with local regulations.
  • **Comprehensive APIs**: Designed for developers to integrate effortlessly into your applications.

Getting Started:

Dive into our comprehensive documentation to get started with integrating Bancwild into your application. Whether you’re building a marketplace, e-commerce store, or any platform requiring payment solutions, Bancwild has you covered.

Start Integration Now →

Installation

Follow these steps to integrate Bancwild’s APIs into your application seamlessly.

Step 1: Requirements

  • Active Bancwild account with API credentials (Client ID & Secret)
  • REST client like Postman or cURL for testing API requests
  • Programming language or framework with HTTP request support (e.g., Axios in JavaScript)

Step 2: Base URL and API Credentials

Use the following base URLs depending on the environment:

Sandbox: https://stagingapi.bancwild.com/api
Production: https://api.bancwild.com/api

Obtain your Client ID and Client Secret from the Bancwild developer portal.

Step 3: Authentication

Authenticate by sending a POST request to the authentication endpoint to obtain an access token:

POST https://stagingapi.bancwild.com/api/auth/token

Headers:
Content-Type: application/json
Authorization: Basic base64(client_id:client_secret)

The response will include an access token:

{
  "access_token": "your-access-token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use this token in the Authorization header for subsequent API requests:

Authorization: Bearer your-access-token

Step 5: Next Steps

Now that you’re authenticated and have made your first API request, explore the other sections of this documentation to learn about processing payments, handling refunds, and retrieving transactions.

Proceed to Payment API →

Authentication

To interact with Bancwild’s APIs, you need to authenticate using your **Client ID** and **Client Secret**. Follow the steps below to obtain these credentials and start integrating.

Step 1: Sign Up

Create an account on the Bancwild Platform. Use a valid email address and set up your profile.

1. Go to https://bancwild.com
2. Enter your email and create a password.
3. Verify your email to activate your account.

Step 2: Request a Merchant Account

After signing up, you need to request a **Merchant Account**. This account allows you to process payments via Bancwild’s platform.

  1. Log in to your Bancwild account.
  2. Navigate to the Merchant Dashboard.
  3. Click on "Request Merchant Account".
  4. Provide the required business details, including:
    • Business Name
    • Company Registration Number
    • Banking Information
    • Contact Information
  5. Submit your request for review.

Once your request is approved, you’ll receive an email with confirmation.

Step 3: Obtain Client ID and Client Secret

After your Merchant Account is approved, you can generate your **Client ID** and **Client Secret**:

1. Log in to your Bancwild account.
2. Go to "API Credentials" in the Developer section.
3. Click "Generate Credentials".
4. Your Client ID and Client Secret will be displayed.
   - Client ID: Used to identify your application.
   - Client Secret: Keep this confidential and secure.

Store these credentials securely, as they are required for authenticating your API requests.

Step 4: Secure Your Credentials

Ensure your **Client Secret** is never exposed in public repositories or client-side applications. We recommend storing it in environment variables or a secure key management system.

# Example .env file
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret

Step 5: Next Steps

Now that you have your API credentials, you can authenticate with Bancwild’s API and begin making requests. Proceed to the next section to learn about generating an access token.

Generate Access Token →

Generate Access Token

To authenticate with Bancwild’s APIs, you need to generate an **Access Token**. This requires sending your **Client ID** and **Client Secret** in the `Authorization` header as a Base64-encoded string.

Authentication Endpoint

Use the following endpoint to obtain your access token:

POST https://stagingapi.bancwild.com/api/authorize/token

Request Format

Send a POST request with the following headers and body:

Headers:

Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

Body:

grant_type=client_credentials

Example Request

Here’s an example using cURL:

curl -X POST https://stagingapi.bancwild.com/api/auth/token \
-H "Authorization: Basic base64encoded(client_id:client_secret)" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials"

Or using Axios in JavaScript:

import axios from 'axios';

const clientId = 'your-client-id';
const clientSecret = 'your-client-secret';
const base64Credentials = btoa(`${clientId}:${clientSecret}`);

const response = await axios.post('https://stagingapi.bancwild.com/api/auth/token', 
  'grant_type=client_credentials', {
  headers: {
    Authorization: `Basic ${base64Credentials}`,
    'Content-Type': 'application/x-www-form-urlencoded',
  },
});

console.log(response.data);

Response Example

If your request is successful, you will receive a response like this:

{
  "access_token": "your-access-token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Save the access_token. Use it in the Authorization header for subsequent API requests.

Authorization: Bearer your-access-token

Error Handling

If the request fails, you will receive an error response. For example:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Ensure your **Client ID** and **Client Secret** are correct and that you are using the correct Base64-encoded format.

Next Steps

Now that you have your access token, you can start making API requests. Learn how to process payments in the next section.

Proceed to Payment API →

Create Checkout URL

Generate a checkout URL to redirect your customers to Bancwild's secure payment page. Use this endpoint to create a payment session.

Endpoint

POST https://stagingapi.bancwild.com/api/payment/checkout

Request Format

Send a POST request with the following headers and body:

Headers:

Authorization: Bearer your-access-token
Content-Type: application/json

Body:

{
  "amount": 1000,
  "callbackUrl": "https://your-website.com/payment-success",
  "webhookUrl": "https://your-website.com/payment-cancel",
  "description": "Order #12345",
  "reference": "order-12345",
  "metadata": {
    "order_id": "12345",
    "customer_email": "customer@example.com"
  }
}

Example Request

Here’s an example using Axios in JavaScript:

import axios from 'axios';

const response = await axios.post(
  'https://stagingapi.bancwild.com/api/checkout',
  {
    amount: 1000,
    callbackUrl: 'https://your-website.com/payment-success',
    webhookUrl: 'https://your-website.com/payment-cancel',
    description: 'Order #12345',
    reference: 'order-12345',
    metadata: {
      order_id: '12345',
      customer_email: 'customer@example.com',
    },
  },
  {
    headers: {
      Authorization: 'Bearer your-access-token',
      'Content-Type': 'application/json',
    },
  }
);

console.log(response.data);

Response Example

If your request is successful, you will receive a response like this:

{
  "checkout_url": "https://stagingapi.bancwild.com/checkout/session-id",
  "expires_in": 3600,
  "status": "pending"
}

Redirect your customer to the checkout_url to complete their payment.

Error Handling

If the request fails, you will receive an error response. For example:

{
  "error": "invalid_request",
  "error_description": "Amount is required"
}

Ensure all required fields are provided and correctly formatted.

Next Steps

After the customer completes the payment, you can verify the transaction status by querying the Payment Status API.

Verify Payment Status →

Webhook Response

Bancwild will send a POST request to the webhook URL you provided during checkout to notify you about payment events. This ensures real-time updates for your transactions.

Webhook URL Setup

When creating a checkout session, include your webhook URL in the callback_url field. Bancwild will use this URL to send updates about the payment status.

Webhook Payload

After a payment is processed, Bancwild will send a POST request to your webhook URL with the following payload structure:

{
  "event": "payment_completed",
  "data": {
    "payment_id": "payment-id-12345",
    "status": "success",
    "amount": 1000,
    "currency": "ZAR",
    "description": "Order #12345",
    "metadata": {
      "order_id": "12345",
      "customer_email": "customer@example.com"
    },
    "created_at": "2025-01-01T12:34:56Z",
    "updated_at": "2025-01-01T12:40:00Z"
  }
}

Error Handling

If your server fails to respond with a 200 OK, Bancwild will retry the webhook delivery up to 3 times with exponential backoff.

Verify Payment Status

Use this endpoint to verify the status of a payment after your customer completes the checkout process.

Endpoint

GET https://stagingapi.bancwild.com/api/payments/{payment_id}

Request Format

Send a GET request with the following headers:

Headers:

Authorization: Bearer your-access-token
Content-Type: application/json

Example Request

Replace `{payment_id}` with the ID of the payment you want to verify. Here’s an example using Axios in JavaScript:

import axios from 'axios';

const response = await axios.get(
  'https://stagingapi.bancwild.com/api/payments/payment-id-12345',
  {
    headers: {
      Authorization: 'Bearer your-access-token',
      'Content-Type': 'application/json',
    },
  }
);

console.log(response.data);

Response Example

If your request is successful, you will receive a response like this:

{
  "payment_id": "payment-id-12345",
  "status": "success",
  "amount": 1000,
  "currency": "ZAR",
  "description": "Order #12345",
  "created_at": "2025-01-01T12:34:56Z",
  "updated_at": "2025-01-01T12:40:00Z"
}

The `status` field will indicate the current status of the payment. Common statuses include:

  • pending: Payment is still in progress.
  • success: Payment was completed successfully.
  • failed: Payment could not be processed.

Error Handling

If the request fails, you will receive an error response. For example:

{
  "error": "not_found",
  "error_description": "Payment ID does not exist"
}

Ensure the `payment_id` is valid and that you have the necessary permissions to access it.