Virtual Terminals

Virtual Terminals turn any counter into a smart payment station.

Built for real shops where staff collect payments and owners are not always present, they eliminate confirmation friction and provide instant payment visibility.

Each Virtual Terminal:

• Has a unique ID
• Generates a dedicated QR code
• Supports multiple payment methods
• Sends real-time WhatsApp notifications
• Tracks transactions per counter or location
• Provides downloadable posters

Create a Virtual Terminal

cURL

curl -X POST "https://api.modempay.com/v1/virtual-terminals" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_api_key>" \
  -d '{
    "name": "Counter 1",
    "whatsapp_numbers": ["[phone]"]
  }'

Parameters

Field	Type	Required	Description
name	string	Yes	Display name for the terminal
whatsapp_numbers	string[]	Yes	Numbers that receive payment notifications

These posters showcase a live payment endpoint that is associated with a specific counter or location.

Retrieve a Terminal

cURL

curl -X GET "https://api.modempay.com/v1/virtual-terminals/f2b9...0243" \
  -H "Authorization: Bearer <your_api_key>"

Update a Terminal

cURL

curl -X PUT "https://api.modempay.com/v1/virtual-terminals/f2b9...0243" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_api_key>" \
  -d '{
    "name": "Main Counter",
    "whatsapp_numbers": ["+220XXXXXXXX"],
    "active": true
  }'

Updatable Fields

• name
• whatsapp_numbers
• active

List Terminals

cURL

curl -X GET "https://api.modempay.com/v1/virtual-terminals?limit=10&term=Counter" \
  -H "Authorization: Bearer <your_api_key>"

Delete a Terminal

cURL

curl -X DELETE "https://api.modempay.com/v1/virtual-terminals/f2b9...0243" \
  -H "Authorization: Bearer <your_api_key>"

Download Terminal Posters

Each terminal comes with a ready-to-print QR poster.

cURL

curl -X GET "https://api.modempay.com/v1/virtual-terminals/download/f2b9...0243" \
  -H "Authorization: Bearer <your_api_key>" --output poster.png

Use the downloaded file to:

• Print and display at checkout
• Share digitally
• Place at multiple store locations

Sample Payment Notifications

Sample Webhook Response

Here’s what a typical webhook payload looks like when a payment is collected at a Virtual Terminal:

{
  "event": "charge.succeeded",
  "data": {
    "id": "88e26728-9e9c-4f18-802f-9d0d7659f795",
    "type": "payment",
    "notes": null,
    "amount": 10,
    "coupon": null,
    "edited": false,
    "source": "online",
    "status": "completed",
    "currency": "GMD",
    "customer": null,
    "discount": null,
    "metadata": {
      "qr_code_url": "https://checkout.modempay.com/pos/9211661",
      "terminal_id": "9211661",
      "terminal_name": "COUNTER 1"
    },
    "auth_mode": "confirm",
    "createdAt": "2026-02-27T00:03:55.078Z",
    "paid_date": null,
    "reference": "cos-238mandcg8wfc",
    "sub_total": null,
    "test_mode": false,
    "updatedAt": "2026-02-27T00:04:07.957Z",
    "account_id": "638c0d3b-9c90-4f20-8d3d-df2a6c6a40a6",
    "risk_score": {},
    "auth_length": 0,
    "business_id": "120c298f-b736-49c1-8220-8a8c84a5d8f3",
    "terminal_id": "f2b29a71-1928-4da2-98f4-3b851ad02b43",
    "customer_name": null,
    "requires_auth": false,
    "customer_email": null,
    "customer_phone": null,
    "failure_reason": null,
    "payment_method": "wave",
    "payment_account": ".... 4725",
    "payment_link_id": null,
    "transaction_fee": 0,
    "payment_intent_id": "cc8122d1-6f00-4773-a6f2-7cfa4797c869",
    "payment_method_id": "d8ec7405-0485-47aa-b58e-ab6d173ba4ef",
    "custom_fields_values": {},
    "transaction_fee_type": "customer",
    "transaction_reference": "MP-20260227-000355-85556EB0",
    "maintain_original_return_url": false
  }
}

Tip: You can configure your webhook URL in the dashboard to receive real-time payment notifications for your Virtual Terminals.

Why Virtual Terminals Matter

Digital payments don’t fail because of infrastructure. They fail because of friction at the counter.

Virtual Terminals eliminate:

• Manual confirmation delays
• Owner verification bottlenecks
• Screenshot fraud
• Staff confusion

They increase:

• Merchant trust
• Transaction speed
• Payment adoption
• Operational visibility

Built for real shops. Not demos.