Card Payments

Ideal for: The widest reach online — Mastercard, Visa and Verve, with PIN, OTP or 3-D Secure depending on the card and issuer.

PCI DSS certification is required for this endpoint

This endpoint receives raw card details — cardNumber, cvv, expiryMonth, expiryYear and pin — on your server. You must hold a valid PCI DSS certification to use it, and SeerBit will not enable it for your account without one.Not certified? Use Simple Checkout, Standard Checkout or an SDK instead. Card details go straight to SeerBit, never touch your servers, and no certification is needed.

Cards are one of the most popular ways to make payments online with a large global reach. SeerBit supports the most popular card types with a simple implentation.

Which flow will I get?

A card charge does not always complete in one call. Which of the three flows below you get depends on the card and the issuer, so your integration must handle all three:

Flow	Triggered by	What your server does
PIN and OTP	Verve cards	Collect the PIN, then the OTP, and validate each.
3-D Secure	Mastercard and Visa	Receive code `S20` with a `redirectUrl`, send the customer there, and read the result when they return.
PIN only	Cards that need no further step-up	Collect the PIN; the charge resolves with code `00`.

Because a 3-D Secure charge redirects the customer away, always pass a redirectUrl in your request so SeerBit knows where to return them. Confirm the outcome with payment verification once they are back — the redirect alone is not proof of payment.

Card Payment Process

Customers enters card details on merchant website.
SeerBit checks that the details provided are valid (e.g the expiry date entered is not in the past)
Authentication : Some cards may prompt the card holder to enter a pin or a one time password sent to the card holder’s phone or email to authenticate the transaction.
Authorization : The bank checks for sufficient funds on the card holder’s account. if successful the amount is held in the customers account and released to the merchant on capture
Capture : The money moves from the card holder’s account (issuing bank) to the merchant account immediately after authorization

Note: By default, all card payments are captured immediately after authorization unless a capture delay or manual capture has been setup by the merchant. Read on how to setup a pre-authorized payment

How it works

Collect the customers details (Fullname, Email and Mobile Number) and Card details.
Make a request to the payment service with the payment/initiates endpoint.
Based on the cardholders card type the seerBit selects an auth method.

Before you use these endpoints

These endpoints are for merchants who want to build their own checkout. You collect the payment details in your own interface and send them to SeerBit, deciding for yourself how the payment experience looks. If you would rather not build and maintain that, use Simple Checkout or Standard Checkout instead — SeerBit renders the payment interface, supports every method, and takes on the compliance burden.

You calculate the fee, not SeerBit

The hosted checkout works out the transaction fee and shows it to the customer. These endpoints do not. SeerBit charges exactly the amount you send. So if your dashboard is set so the customer bears the fee, you must calculate that fee and include it yourself. If you don’t, the fee comes out of your settlement instead — you will receive less than you charged.

Fee bearer	Hosted checkout	These endpoints
Merchant	Send your amount; the fee is deducted at settlement	Send your amount; the fee is deducted at settlement
Customer	Checkout adds the fee for you	You add the fee yourself

Set the fee bearer in your dashboard settings, and see transaction fees for how the two models differ.

How methods are selected

Every payment method uses the same endpoint — what changes is the paymentType you send and the extra fields that method needs.

POST https://seerbitapi.com/api/v2/payments/initiates

Method	`paymentType`	Extra fields
Card	`CARD`	`cardNumber`, `cvv`, `expiryMonth`, `expiryYear`, `pin`
Transfer	`TRANSFER`	—
USSD	`USSD`	`bankCode`
Mobile money	`MOMO`	`network`, `voucherCode`
Bank account	`ACCOUNT`	`clientAppCode`, `redirectUrl`

Authentication

All payment method calls are authenticated with a bearer token, generated from your public and secret keys.

POST https://seerbitapi.com/api/v2/encrypt/keys

Authentication

How to generate the token, and which credential every other SeerBit API expects.

Initializing a Card Payment

For the full specification, see our API Reference POST

https://seerbitapi.com/api/v2/payments/initiates

Request Sample

The code snippet below shows an example response

curl --location 'https://seerbitapi.com/api/v2/payments/initiates' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ENCRYPTED_KEY' \
--data-raw '{
	
		"publicKey":"YOUR_PUBLIC_KEY",
		"amount":"100.00",
		"fee":"10",
		"fullName":"John Doe",
		"mobileNumber":"08032000001",
		"currency":"NGN",
		"country":"NG",
		"paymentReference":"LKJHGFDR123UI23992JN23R",
		"email":"johndoe@gmail.com",
		"productId":"Foods",
		"productDescription":"RASPBERRY",
		"clientAppCode":"kpp64",
		"redirectUrl":"",
		"paymentType":"CARD",
		"channelType":"Mastercard",
		"deviceType":"Apple Laptop",
	  	"sourceIP":"127.0.0.1:3456",
		"cardNumber":"5000550000000029",
		"cvv":"072",
		"expiryMonth":"08",
		"expiryYear":"28",
		"pin":"0000",
		"retry":"false"
}'

var request = require('request');
var options = {
  method: 'POST',
  url: 'https://seerbitapi.com/api/v2/payments/initiates',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer YOUR_ENCRYPTED_KEY'
  },
  body: JSON.stringify({
    publicKey: 'YOUR_PUBLIC_KEY',
    amount: '100.00',
    fee: '10',
    fullName: 'John Doe',
    mobileNumber: '08032000001',
    currency: 'NGN',
    country: 'NG',
    paymentReference: 'LKJHGFDR123UI23992JN23R',
    email: 'johndoe@gmail.com',
    productId: 'Foods',
    productDescription: 'RASPBERRY',
    clientAppCode: 'kpp64',
    redirectUrl: '',
    paymentType: 'CARD',
    channelType: 'Mastercard',
    deviceType: 'Apple Laptop',
    sourceIP: '127.0.0.1:3456',
    cardNumber: '5000550000000029',
    cvv: '072',
    expiryMonth: '08',
    expiryYear: '28',
    pin: '0000',
    retry: 'false'
  })
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://seerbitapi.com/api/v2/payments/initiates',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{

		"publicKey":"YOUR_PUBLIC_KEY",
		"amount":"100.00",
		"fee":"10",
		"fullName":"John Doe",
		"mobileNumber":"08032000001",
		"currency":"NGN",
		"country":"NG",
		"paymentReference":"LKJHGFDR123UI23992JN23R",
		"email":"johndoe@gmail.com",
		"productId":"Foods",
		"productDescription":"RASPBERRY",
		"clientAppCode":"kpp64",
		"redirectUrl":"",
		"paymentType":"CARD",
		"channelType":"Mastercard",
		"deviceType":"Apple Laptop",
	  	"sourceIP":"127.0.0.1:3456",
		"cardNumber":"5000550000000029",
		"cvv":"072",
		"expiryMonth":"08",
		"expiryYear":"28",
		"pin":"0000",
		"retry":"false"

}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer YOUR_ENCRYPTED_KEY'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response Sample

The code snippet below shows an example request for initialising this payment

{
  "status": "SUCCESS",
  "data": {
    "code": "S20",
    "payments": {
      "paymentReference": "LKJHGFDR123UI23992JN23R",
      "linkingReference": "F468778061587905955047"
    },
    "message": "Kindly enter OTP"
  }
}

Scenario 1: PIN and OTP (Verve)

The customers gets prompted to enter card pin.
After the customer enters the card pin, call the payment service again using payment/initiates endpoint.
An OTP (one time password) is sent to the cardholders registered phone number or email to validate the transaction.
To Validate the transaction Call the Validate OTP payments/otp endpoint with the customers OTP and Pass the transactions linking reference in the request body.

Request with PIN

The code snippet below shows the sample request after passing the PIN

curl --location 'https://seerbitapi.com/api/v2/payments/initiates' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ENCRYPTED_KEY' \
--data '{
	"transaction":
		{
		 "linkingreference":"F468778061587905955047",
         "otp":"496865"
         }
}'

var request = require('request');
var options = {
  method: 'POST',
  url: 'https://seerbitapi.com/api/v2/payments/initiates',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer YOUR_ENCRYPTED_KEY'
  },
  body: JSON.stringify({
    transaction: {
      linkingreference: 'F468778061587905955047',
      otp: '496865'
    }
  })
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://seerbitapi.com/api/v2/payments/initiates',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
	"transaction":
					{
						 "linkingreference":"F468778061587905955047",
						 "otp":"496865"
					}
  }',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer YOUR_ENCRYPTED_KEY'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response Sample

The code snippet below shows an example response after entering the OTP

{
  "status": "SUCCESS",
  "data": {
    "code": "00",
    "payments": {
      "reference": "LKJHGFDR123UI23992JN23R",
      "linkingreference": "F468778061587905955047"
    },
    "message": "Successful"
  }
}

Scenario 2: 3-D Secure (Mastercard and Visa)

The occurs for 3D secure card transactions.
After the payment has been initiated, the card holder gets prompted to complete the payment on the card’s bank page.
For a successful initial call, code S20 will be returned with a redirect link in the redirectUrl field, merchant is expected to redirect to the link. Because of this merchant is expected to always pass the redirectUrl link that SeerBit should come back to after the payment is completed on 3Ds site.

Response Sample

The code snippet below shows an example request for initialising this payment

{
  "status": "SUCCESS",
  "data": {
    "code": "S20",
    "payments": {
      "paymentReference": "LKJHGFDR123UI23992JN23R",
      "linkingReference": "F468778061587905955047",
      "redirectUrl": "https://seerbitapigateway.com/seerbit/card-dispatch sredref=F468778061587905955047"
    },
    "message": "Transaction is pending"
  }
}

Scenario 3: PIN only

The customers gets prompted to enter card pin.

Response Sample

The code snippet below shows an example request for initialising this payment

{
  "status": "SUCCESS",
  "data": {
    "code": "00",
    "payments": {
      "paymentReference": "92SQ2A3BCDE42RFR2AS122221",
      "linkingReference": "F611305721592735518716"
    },
    "message": "Successful"
  }
}

Testing your integration

Use any of the SeerBit test cards to complete a payment on the checkout page and confirm your integration end to end. See the full list of test credentials

Get Started

Accept Payments

Payment Methods

After a Payment

Payouts & Wallets

Platforms & Marketplaces

In-Store Payments

Reference

PCI DSS certification is required for this endpoint

Which flow will I get?

Card Payment Process

How it works

Before you use these endpoints

You calculate the fee, not SeerBit

How methods are selected

Authentication

Authentication

Initializing a Card Payment

Request Sample

Response Sample

Scenario 1: PIN and OTP (Verve)

Request with PIN

Response Sample

Scenario 2: 3-D Secure (Mastercard and Visa)

Response Sample

Scenario 3: PIN only

Response Sample

Testing your integration

PCI DSS certification is required for this endpoint

​Which flow will I get?

​Card Payment Process

​How it works

​Before you use these endpoints

​You calculate the fee, not SeerBit

​How methods are selected

​Authentication

Authentication

​Initializing a Card Payment

​Request Sample

​Response Sample

​Scenario 1: PIN and OTP (Verve)

​Request with PIN

​Response Sample

​Scenario 2: 3-D Secure (Mastercard and Visa)

​Response Sample

​Scenario 3: PIN only

​Response Sample

​Testing your integration

Which flow will I get?

Card Payment Process

How it works

Before you use these endpoints

You calculate the fee, not SeerBit

How methods are selected

Authentication

Initializing a Card Payment

Request Sample

Response Sample

Scenario 1: PIN and OTP (Verve)

Request with PIN

Response Sample

Scenario 2: 3-D Secure (Mastercard and Visa)

Response Sample

Scenario 3: PIN only

Response Sample

Testing your integration