Quickstart

Follow these steps to quickly integrate Bead's Hosted Payment Page into your application. This guide provides a straightforward approach to authenticate, create payments, handle responses, and prepare your integration for production use.

Step 1: Request Sandbox Access

To begin, request sandbox credentials by contacting Bead developer support at [e-mail]. You will receive:

• API Key and API Secret

• Terminal credentials for sandbox testing

Sandbox API Endpoint:

https://api.test.devs.beadpay.io/

Authentication Endpoint:

https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token

Step 2: Authenticate

Authenticate using the provided sandbox credentials to obtain an access token.

Request 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

Response Example

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOiJ...",
  "token_type": "Bearer",
  "scope": "openid profile email"
}

Include this access_token as a bearer token for all subsequent API requests.

Step 3: Create a Payment

Use the /payments/crypto endpoint to generate a hosted payment URL.

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"
}

Response Example

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

Redirect customers to the URL provided in paymentUrls.url.

Step 4: Handle Payment Webhooks

Configure your webhook URL with Bead support or using your boarding API credentials. Webhooks notify your server about transaction status changes.

Example webhook payload:

{
  "trackingId": "4f181348293946cfa39b5846078c9bbc",
  "paymentCode": "bAKbqtcuP5",
  "statusCode": 2,
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 1.02,
        "currency": {
          "code": "USDC",
          "name": "USDC Ethereum"
        }
      },
      "inRequestedCurrency": {
        "amount": 1,
        "currency": {
          "code": "USD",
          "name": "USD"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 1.02,
        "currency": {
          "code": "USDC",
          "name": "USDC Ethereum"
        }
      }
    }
  },
  "reference": "ORDER123",
  "receivedTime": "2024-08-06T06:48:40.7579639",
  "terminalId": "YOUR_TERMINAL_ID",
  "merchantId": "YOUR_MERCHANT_ID"
}

Key statusCode values:

• 2: Completed

• 3: Underpaid

• 4: Overpaid

• 7: Expired

• 8: Invalid

• 9: Cancelled

Respond with 200 OK to acknowledge receipt.

Step 5: Test Integration

Use crypto testnet wallets to complete test transactions in the sandbox environment. Verify:

• Payment URLs redirect correctly.

• Webhooks deliver transaction statuses as expected.

• Payment statuses are properly handled in your application.

Next Steps

Once your integration passes sandbox testing:

• Request production credentials from Bead.

• Update your configuration to use the production API endpoints.

For integration questions, contact [e-mail].