Virtual Account

Virtual Account Service makes receiving payments from your customer seamless.

Merchants will have to submit KYC upon registration to [e-mail] which the Support team will review before getting the client-id and authorization key.

Request made without the authorization key will fail with a 401 (Service Not Authorize) response code.

Create Static Virtual Account

This allows you to create a virtual account for merchants/agents.

Endpoint to create virtual account

POST {{baseUrl}}/pip/softpos/create-virtual-account

The merchant super-agent can create a virtual account with this endpoint.

Headers

Name	Type	Description
authorization*	String	secret-key
client-id*	String	Merchant Id
Content-Type*	String	application/json

Request Body

Name	Type	Description
address*	String	customer address
customer_identifier*	String	customer's unique identifier
dob*	Date	customer date of birth (dd/mm/yyyy)
email*	String	customer email address
first_name*	String	customer first name
last_name*	String	customer last name
mobile_num*	String	customer's moblie number
gender*	String	customer gender ("1" - MALE, "2" -FEMALE )
bvn*	String	customer's bvn

200: OK Virtual account created successfully

{
    "statusCode": 200,
    "description": "Successful",
    "data": {
        "first_name": "Taofeek",
        "last_name": "Ogunlola",
        "bank_code": "058",
        "virtual_account_number": "0345431014",
        "customer_identifier": "12345",
        "created_at": "2022-11-23T20:35:41.142Z",
        "update_at": null
    }
}

401: Unauthorized Merchant is not authorize to create virtual account

{
    "statusCode": 401,
    "description": "You are not authorized",
    "data": null
}

Create POS Terminal

This allows you to create terminals for different businesses. The terminal is location-based and each location has an Id that you must include.

Endpoint for merchant to create terminal

POST {{baseUrl}}/pip/softpos/create-terminal

Headers

Name	Type	Description
Content-Type*	String	application/json
authorization*	String	secret-key
client-id*	String	Merchant ID

Request Body

Name	Type	Description
name*	String	Name on terminal
email*	String	Email
phone*	String	Phone number on terminal
location_id*	String	The Id of the terminal location
merchantId*	String	The merchant Id

200: OK Terminal created successfully.

{
    "statusCode": 200,
    "description": "Successful",
    "data": {
        "terminalId": null,
        "enabled": false
    }
}

401: Unauthorized Merchant is not authorized to create terminal

{
    "statusCode": 401,
    "description": "You are not authorized",
    "data": null
}

400: Bad Request location_id is missing

{
    "statusCode": 400,
    "description": "Bad request",
    "data": null
}

Initiate Payment Service

This is a service which can be use to recieve payment using card, ussd and transfer. In order to SignUp for this service, the client will provide a wehbook to recieve a payment notification as part of the onboarding process.

Webhook Body

{
    "transaction_reference": "TRX123456789",
    "virtual_account_number": "VA987654321",
    "principal_amount": "10000",
    "transaction_date": "2024-09-01",
    "customer_identifier": "CUST12345",
    "transaction_indicator": "C",
    "remarks": "Payment for invoice #INV1234",
    "currency": "NGN",
    "channel": "Mobile",
    "sender_name": "John Doe"
}

Endpoint to initiate payment

POST {{baseUrl}}/pip/softpos/initiate-transaction

Initiate Transaction endpoint

Headers

Name	Value
Content-Type	application/json
Authorization	authorization
client-id	client-id

Body

{
  "amount": 100,
  "callback_url": "www.payvantage.com.ng",
  "customer_name": "John Doe",
  "email": "[e-mail]",
  "transRef": "20242112"
}

Name	Type	Description
amount	string	Value in Naira
callback_url	String	https://payvantage.com.ng
customer_name	String	Customer full Name
email	String	Customer email
transRef	String	Transaction Reference

Response

200

{
  "statusCode": 200,
  "description": "Success",
  "data": {
    "currency": "NGN",
    "is_recurring": "false",
    "transaction_ref": "bb8b2207-4a35-42a0-8442-ca5fcf84aa77",
    "transaction_amount": "100",
    "authorized_channels": [
      "card",
      "ussd",
      "bank"
    ],
    "checkout_url": "https://pay.squadco.com/bb8b2207-4a35-42a0-8442-c5fcf84aa77"
  }
}

400

{
  "error": "Invalid request"
}

Sample Request

Sample Response

{
  "statusCode": 200,
  "description": "Success",
  "data": {
    "currency": "NGN",
    "is_recurring": "false",
    "transaction_ref": "bb8b2207-4a35-42a0-8442-ca5fcf84aa77",
    "transaction_amount": "100",
    "authorized_channels": [
      "card",
      "ussd",
      "bank"
    ],
    "checkout_url": "https://pay.squadco.com/bb8b2207-4a35-42a0-8442-c5fcf84aa77"
  }
}