Creating Payments

To initiate payments using Bead, integrators generate a secure hosted payment page URL. Customers complete their transactions directly on this hosted page, simplifying integration and ensuring security.

Overview

The Hosted Payment API lets you create unique, secure URLs for each transaction. Your customers follow these links to select their preferred payment method, including crypto and digital wallets.

Step 1: Authenticate

Obtain your access token by authenticating:

Authentication Example:

POST https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=password
client_id=bead-terminal
username=[e-mail]
password=YOUR_TERMINAL_PASSWORD
scope=openid profile email

Authentication Response:

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Use this access_token for subsequent requests.

Step 2: Create a Payment URL

Use the /payments/crypto endpoint to create a hosted payment page.

Request Example:

POST https://api.test.devs.beadpay.io/payments/crypto
Authorization: Bearer YOUR_ACCESS_TOKEN
api-version: 0.2
Content-Type: application/json

{
  "terminalId": "YOUR_TERMINAL_ID",
  "merchantId": "YOUR_MERCHANT_ID",
  "requestedAmount": 100.00,
  "paymentUrlType": "web",
  "reference": "ORDER123",
  "redirectUrl": "https://yourwebsite.com/payment-success"
}

Parameter	Description	Example Value
terminalId	Unique ID of your terminal	"abc123-terminal"
merchantId	Unique ID of the merchant	"merchant-001"
requestedAmount	Amount requested (in fiat)	100.00
paymentUrlType	Type of payment URL (web)	"web"
reference	Your unique order reference	"ORDER123"
redirectUrl	URL customer is redirected after payment	"https://yourwebsite.com/payment-success"

Response Example:

{
  "trackingId": "c10b29e3c8104e0f8dc139c20d9eeb6c",
  "paymentUrls": {
    "type": "web",
    "url": "https://pay.test.devs.beadpay.io/payment-page"
  }
}

Redirect your customer to paymentUrls.url.

Step 3: Handle Customer Redirection

• After payment completion, the customer is redirected back to your specified redirectUrl.

• You should use either Webhooks or Payment Status API to confirm payment status.

Next Steps

• Set up Webhooks for real-time transaction updates.

• Alternatively, use the Payment Status API for polling payment statuses.

For any integration questions, contact [e-mail].