Copy link List Virtual Terminals

List Virtual Terminals on your integration

Query Parameters

perPageinteger
The number of records to fetch per request
pageinteger
The offset to retrieve data from

Response

200Virtual Terminal Lists response
statusboolean
messagestring
dataarray[object]
metaobject
5 object properties
totalinteger
skippedinteger
perPagestring
pageinteger
pageCountinteger
GET/virtual_terminal
curl 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.data
Response
{
  "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

namerequiredstring
The name of the virtual terminal
destinationsrequiredarray[object]
Array of objects containing recipients for payment notifications for the Virtual Terminal.
split_codestring
Split code to associate with the virtual terminal
metadataobject
Additional custom data as key-value pairs

Response

200Virtual Terminal Create response
statusrequiredboolean
messagerequiredstring
datarequiredobject
10 object properties
idrequiredinteger
namerequiredstring
integrationrequiredinteger
domainrequiredstring
coderequiredstring
paymentMethodsrequiredarray[object]
activerequiredboolean
metadatarequiredstring
destinationsrequiredarray[object]
currencyrequiredstring
POST/virtual_terminal
curl https://api.paystack.co/virtual_terminal \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sample Terminal",
    "destinations": []
  }' \
  -X POST
import { 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.data
Response
{
  "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

coderequiredstring
Code of the Virtual Terminal

Response

200Virtual Terminal Fetch response
statusrequiredboolean
messagerequiredstring
datarequiredobject
11 object properties
idrequiredinteger
coderequiredstring
namerequiredstring
integrationrequiredinteger
domainrequiredstring
paymentMethodsrequiredarray[object]
activerequiredboolean
created_atrequiredstring
connect_account_idrequiredstring
destinationsrequiredarray[object]
currencyrequiredstring
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.data
Response
{
  "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

coderequiredstring
Code of the Virtual Terminal

Request Body

namerequiredstring
Name of the virtual terminal

Response

200Virtual Terminal Update response
statusrequiredboolean
messagerequiredstring
datarequiredobject
11 object properties
idrequiredinteger
coderequiredstring
namerequiredstring
integrationrequiredinteger
domainrequiredstring
paymentMethodsrequiredarray[object]
activerequiredboolean
created_atrequiredstring
connect_account_idrequiredstring
destinationsrequiredarray[object]
currencyrequiredstring
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 PUT
import { 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.data
Response
{
  "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

coderequiredstring
Code of the Virtual Terminal

Response

200Virtual Terminal Deactivate response
statusrequiredboolean
messagerequiredstring
PUT/virtual_terminal/{code}/deactivate
curl https://api.paystack.co/virtual_terminal/VT_MCK5292Z/deactivate \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -X PUT
import { 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.data
Response
{
  "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

coderequiredstring
Code of the Virtual Terminal

Request Body

destinationsrequiredarray[object]
Array of objects containing recipients for payment notifications for the Virtual Terminal.

Response

200Virtual Terminal Deactivate response
statusrequiredboolean
messagerequiredstring
datarequiredarray[object]
POST/virtual_terminal/{code}/destination/assign
curl https://api.paystack.co/virtual_terminal/VT_MCK5292Z/destination/assign \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinations": []
  }' \
  -X POST
import { 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.data
Response
{
  "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

coderequiredstring
Code of the Virtual Terminal

Request Body

targetsrequiredarray[string]
Array of destination targets to unassign

Response

200Virtual Terminal unassign response
statusrequiredboolean
messagerequiredstring
POST/virtual_terminal/{code}/destination/unassign
curl https://api.paystack.co/virtual_terminal/VT_MCK5292Z/destination/unassign \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": []
  }' \
  -X POST
import { 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.data
Response
{
  "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

coderequiredstring
Code of the Virtual Terminal

Request Body

split_coderequiredstring
The split code to assign to the virtual terminal

Response

200Virtual Terminal Split Assign response
statusrequiredboolean
messagerequiredstring
datarequiredobject
15 object properties
idrequiredinteger
namerequiredstring
typerequiredstring
currencyrequiredstring
integrationrequiredinteger
domainrequiredstring
split_coderequiredstring
activerequiredboolean
bearer_typerequiredstring
bearer_subaccountrequiredstring
createdAtrequiredstring
updatedAtrequiredstring
is_dynamicrequiredboolean
subaccountsrequiredarray[object]
total_subaccountsrequiredinteger
PUT/virtual_terminal/{code}/split_code
curl 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 PUT
import { 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.data
Response
{
  "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

coderequiredstring
Code of the Virtual Terminal

Request Body

split_coderequiredstring
The split code to assign to the virtual terminal

Response

200Virtual Terminal Split Remove response
statusrequiredboolean
messagerequiredstring
DELETE/virtual_terminal/{code}/split_code
curl 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 DELETE
import { 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.data
Response
{
  "status": true,
  "message": "Request successful"
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}