Virtual Terminal
A collection of endpoints for building in-person payments without a physical terminal
Endpoints
- GET/virtual_terminal
- POST/virtual_terminal
- GET/virtual_terminal/{code}
- PUT/virtual_terminal/{code}
- PUT/virtual_terminal/{code}/deactivate
- POST/virtual_terminal/{code}/destination/assign
- POST/virtual_terminal/{code}/destination/unassign
- PUT/virtual_terminal/{code}/split_code
- DELETE/virtual_terminal/{code}/split_code
Copy link List Virtual Terminals
List Virtual Terminals on your integration
Query Parameters
The number of records to fetch per request
The offset to retrieve data from
Response
200Virtual Terminal Lists response
5 object properties
GET
/virtual_terminalcurl https://api.paystack.co/virtual_terminal \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.virtualTerminal.list({
perPage: 75,
page: 100
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.virtual_terminal.list({
per_page: 75,
page: 100
})
puts response.dataResponse
{
"status": true,
"message": "Virtual Terminals retrieved",
"data": [
{
"id": 26740,
"code": "VT_SOUAPKJZ",
"name": "Sales Point #3",
"integration": 530790,
"domain": "test",
"paymentMethods": [],
"active": true,
"created_at": "2025-01-16T14:09:11.000Z",
"currency": "ZAR"
},
{
"id": 26592,
"code": "VT_NG3LPU2I",
"name": "Sales Point #4",
"integration": 530790,
"domain": "test",
"paymentMethods": [],
"active": true,
"created_at": "2025-01-14T16:35:58.000Z",
"currency": "ZAR"
}
],
"meta": {
"next": null,
"previous": null,
"perPage": 50
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Create Virtual Terminal
Create a Virtual Terminal on your integration
Request Body
The name of the virtual terminal
Array of objects containing recipients for payment notifications for the Virtual Terminal.
Split code to associate with the virtual terminal
Additional custom data as key-value pairs
Response
200Virtual Terminal Create response
10 object properties
POST
/virtual_terminalcurl https://api.paystack.co/virtual_terminal \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Sample Terminal",
"destinations": []
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.virtualTerminal.create({
name: "Sample Terminal",
destinations: []
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.virtual_terminal.create({
name: "Sample Terminal",
destinations: []
})
puts response.dataResponse
{
"status": true,
"message": "Virtual Terminal created",
"data": {
"id": 27691,
"name": "Sample Terminal",
"integration": 530700,
"domain": "test",
"code": "VT_LJK5892Z",
"paymentMethods": [],
"active": true,
"metadata": null,
"destinations": [
{
"target": "+27639022319",
"type": "whatsapp",
"name": "Phone Destination"
}
],
"currency": "ZAR"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Fetch Virtual Terminal
Fetch a Virtual Terminal on your integration
Path Parameters
Code of the Virtual Terminal
Response
200Virtual Terminal Fetch response
11 object properties
GET
/virtual_terminal/{code}curl https://api.paystack.co/virtual_terminal/VT_MCK5292Z \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.virtualTerminal.fetch("VT_MCK5292Z");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.virtual_terminal.fetch("VT_MCK5292Z")
puts response.dataResponse
{
"status": true,
"message": "Virtual Terminal retrieved",
"data": {
"id": 27691,
"code": "VT_MCK5292Z",
"name": "Sample Terminal",
"integration": 730720,
"domain": "test",
"paymentMethods": [],
"active": true,
"created_at": "2025-02-04T12:56:56.000Z",
"connect_account_id": null,
"destinations": [
{
"target": "+27639091249",
"type": "whatsapp",
"name": "Sales Point #1",
"created_at": "2025-02-04T12:56:56.000Z"
}
],
"currency": "ZAR"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Update Virtual Terminal
Update a Virtual Terminal on your integration
Path Parameters
Code of the Virtual Terminal
Request Body
Name of the virtual terminal
Response
200Virtual Terminal Update response
11 object properties
PUT
/virtual_terminal/{code}curl https://api.paystack.co/virtual_terminal/VT_MCK5292Z \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Lagos_Mainland_Zone_1"
}' \
-X PUTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.virtualTerminal.update("VT_MCK5292Z", {
name: "Lagos_Mainland_Zone_1"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.virtual_terminal.update("VT_MCK5292Z", {
name: "Lagos_Mainland_Zone_1"
})
puts response.dataResponse
{
"status": true,
"message": "Request successful",
"data": {
"id": 0,
"code": "string",
"name": "string",
"integration": 0,
"domain": "string",
"paymentMethods": [],
"active": true,
"created_at": "string",
"connect_account_id": "string",
"destinations": [],
"currency": "string"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Deactivate Virtual Terminal
Deactivate a Virtual Terminal on your integration
Path Parameters
Code of the Virtual Terminal
Response
200Virtual Terminal Deactivate response
PUT
/virtual_terminal/{code}/deactivatecurl https://api.paystack.co/virtual_terminal/VT_MCK5292Z/deactivate \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-X PUTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.virtualTerminal.deactivate("VT_MCK5292Z");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.virtual_terminal.deactivate("VT_MCK5292Z")
puts response.dataResponse
{
"status": true,
"message": "Terminal set to inactive"
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Assign Destination to Virtual Terminal
Add a destination (WhatsApp number) to a Virtual Terminal on your integration
Path Parameters
Code of the Virtual Terminal
Request Body
Array of objects containing recipients for payment notifications for the Virtual Terminal.
Response
200Virtual Terminal Deactivate response
POST
/virtual_terminal/{code}/destination/assigncurl https://api.paystack.co/virtual_terminal/VT_MCK5292Z/destination/assign \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"destinations": []
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.virtualTerminal.destinationAssign("VT_MCK5292Z", {
destinations: []
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.virtual_terminal.destination_assign("VT_MCK5292Z", {
destinations: []
})
puts response.dataResponse
{
"status": true,
"message": "Destinations assigned successfully",
"data": [
{
"integration": 530700,
"target": "2341234567890",
"name": "Another one",
"type": "whatsapp",
"id": 27934,
"createdAt": "2025-02-04T13:26:35.278Z",
"updatedAt": "2025-02-04T13:26:35.278Z"
}
]
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Unassign Destination from Virtual Terminal
Unassign a destination (WhatsApp Number) from a Virtual Terminal on your integration
Path Parameters
Code of the Virtual Terminal
Request Body
Array of destination targets to unassign
Response
200Virtual Terminal unassign response
POST
/virtual_terminal/{code}/destination/unassigncurl https://api.paystack.co/virtual_terminal/VT_MCK5292Z/destination/unassign \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"targets": []
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.virtualTerminal.destinationUnassign("VT_MCK5292Z", {
targets: []
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.virtual_terminal.destination_unassign("VT_MCK5292Z", {
targets: []
})
puts response.dataResponse
{
"status": true,
"message": "Destination deleted successfully"
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Add Split Code to Virtual Terminal
Add Split Code to Virtual Terminal
Path Parameters
Code of the Virtual Terminal
Request Body
The split code to assign to the virtual terminal
Response
200Virtual Terminal Split Assign response
15 object properties
PUT
/virtual_terminal/{code}/split_codecurl https://api.paystack.co/virtual_terminal/VT_MCK5292Z/split_code \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"split_code": "SPL_1234567890abcdef"
}' \
-X PUTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.virtualTerminal.addSplitCode("VT_MCK5292Z", {
split_code: "SPL_1234567890abcdef"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.virtual_terminal.add_split_code("VT_MCK5292Z", {
split_code: "SPL_1234567890abcdef"
})
puts response.dataResponse
{
"status": true,
"message": "Split code assigned",
"data": {
"id": 3025782,
"name": "Dynamic Split at 1729681745076",
"type": "flat",
"currency": "ZAR",
"integration": 530700,
"domain": "test",
"split_code": "SPL_HBaFCbbiyI",
"active": true,
"bearer_type": "subaccount",
"bearer_subaccount": 854043,
"createdAt": "2024-10-23T11:09:05.000Z",
"updatedAt": "2024-10-23T11:09:05.000Z",
"is_dynamic": true,
"subaccounts": [
{
"subaccount": {
"id": 523210,
"subaccount_code": "ACCT_r56edei4okmllle",
"business_name": "ABC Ventures",
"description": "ABC Ventures",
"primary_contact_name": null,
"primary_contact_email": null,
"primary_contact_phone": null,
"metadata": null,
"settlement_bank": "African Bank Limited",
"currency": "ZAR",
"account_number": "00000000000"
},
"share": 1600
},
{
"subaccount": {
"id": 854043,
"subaccount_code": "ACCT_n8m5vz2itt8y0f1",
"business_name": "Best Logistics",
"description": "Best Logistics",
"primary_contact_name": null,
"primary_contact_email": null,
"primary_contact_phone": null,
"metadata": null,
"settlement_bank": "Capitec Bank Limited",
"currency": "ZAR",
"account_number": "1051366984"
},
"share": 98400
}
],
"total_subaccounts": 2
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Remove Split Code from Virtual Terminal
Remove Split Code from Virtual Terminal
Path Parameters
Code of the Virtual Terminal
Request Body
The split code to assign to the virtual terminal
Response
200Virtual Terminal Split Remove response
DELETE
/virtual_terminal/{code}/split_codecurl https://api.paystack.co/virtual_terminal/VT_MCK5292Z/split_code \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"split_code": "SPL_1234567890abcdef"
}' \
-X DELETEimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.virtualTerminal.deleteSplitCode("VT_MCK5292Z", {
split_code: "SPL_1234567890abcdef"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.virtual_terminal.delete_split_code("VT_MCK5292Z", {
split_code: "SPL_1234567890abcdef"
})
puts response.dataResponse
{
"status": true,
"message": "Request successful"
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}