Terminal Management

Terminals represent payment acceptance points for merchants using Bead. Each terminal is configured individually, allowing integrators to manage supported payment methods and configure webhook URLs for real-time transaction notifications.

Overview

The Terminal Management API enables integrators to:

• Create terminals to enable payment acceptance for merchants.

• Retrieve terminal details to confirm configurations.

• Set or update webhook URLs to receive real-time transaction status updates.

---

Authentication

Terminal Management API requires username/password-based OAuth2 authentication. See Authentication for details.

---

Creating a Terminal

Creates a new terminal for a merchant, returning terminal credentials and configurations.

Request Example

POST https://api.test.devs.beadpay.io/terminals
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "merchantId": "merchant-001",
  "terminalName": "Online Checkout",
  "paymentMethods": ["crypto", "digital_wallet"]
}

Response Example

{
  "terminalId": "terminal-123",
  "username": "[e-mail]",
  "password": "generated-terminal-password",
  "paymentMethods": ["crypto", "digital_wallet"],
  "createdAt": "2025-03-04T12:30:00Z"
}

Store these terminal credentials securely for authentication in Payment API calls.

---

Loading Terminal Details

Retrieves details of an existing terminal.

Request Example

GET https://api.test.devs.beadpay.io/terminals/{terminalId}
Authorization: Bearer {access_token}

Response Example

{
  "terminalId": "terminal-123",
  "merchantId": "merchant-001",
  "terminalName": "Online Checkout",
  "paymentMethods": ["crypto", "digital_wallet"],
  "webhookUrl": "https://yourserver.com/webhooks/payment-notifications",
  "createdAt": "2025-03-04T12:30:00Z"
}

---

Configuring Terminal Webhooks

Set or update the webhook URL where Bead sends real-time transaction status updates.

Request Example

PUT https://api.test.devs.beadpay.io/terminals/{terminalId}/set-webhook-url
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "webhookUrl": "https://yourserver.com/webhooks/payment-notifications"
}

Successful Response Example

{
  "terminalId": "terminal-123",
  "webhookUrl": "https://yourserver.com/webhooks/payment-notifications",
  "updated": "2025-03-04T12:45:00Z"
}

---

Next Steps

• Proceed to Merchant Onboarding to understand merchant setup.

• Refer to the Payment Webhooks documentation to handle webhook payloads effectively.

For integration assistance, contact [e-mail].