# Environments & Base URLs

## Environments & Base URLs

Use the matrix below to target the correct services for your environment. Values shown are the currently active endpoints.

| Area                             | Test / Non-prod                              | Production                                |
| -------------------------------- | -------------------------------------------- | ----------------------------------------- |
| **Payment Service API base URL** | `https://api.test.devs.beadpay.io`           | Provided during onboarding                |
| **OIDC / Identity base**         | `https://identity.beadpay.io/realms/nonprod` | `https://identity.beadpay.io/realms/prod` |

### Realms

| Environment     | Realm     |
| --------------- | --------- |
| Test / Non-prod | `nonprod` |
| Production      | `prod`    |

Token endpoint pattern used for all realms

```
{OIDC_BASE}/protocol/openid-connect/token
```

Explicit token URLs

* Test\
  `https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token`
* Production\
  `https://identity.beadpay.io/realms/prod/protocol/openid-connect/token`

### Authentication

#### Resource Owner Password Credentials for terminals

Terminals authenticate with the ROPC flow to obtain an access token using the terminal-issued username and password.

Token URL Test / Non-prod\
`https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token`

Token URL Production\
`https://identity.beadpay.io/realms/prod/protocol/openid-connect/token`

Form fields

| Field        | Value                      |
| ------------ | -------------------------- |
| `grant_type` | `password`                 |
| `client_id`  | `bead-terminal`            |
| `username`   | `{TERMINAL_ID}@beadpay.io` |
| `password`   | `{TERMINAL_PASSWORD}`      |
| `scope`      | `openid profile email`     |

cURL example Test / Non-prod

```bash
curl -sS -X POST \
  https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=password' \
  --data 'client_id=bead-terminal' \
  --data 'username=YOUR_TERMINAL_ID@beadpay.io' \
  --data 'password=YOUR_TERMINAL_PASSWORD' \
  --data 'scope=openid profile email'
```

cURL example Production

```bash
curl -sS -X POST \
  https://identity.beadpay.io/realms/prod/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=password' \
  --data 'client_id=bead-terminal' \
  --data 'username=YOUR_TERMINAL_ID@beadpay.io' \
  --data 'password=YOUR_TERMINAL_PASSWORD' \
  --data 'scope=openid profile email'
```

Partners using server-to-server integrations can use their assigned OIDC client and flow. Coordinate with your Bead contact to enable.

### Using the API

Include these headers on every request

| Header          | Example                 |
| --------------- | ----------------------- |
| `Authorization` | `Bearer {access_token}` |
| `Content-Type`  | `application/json`      |

#### Example Create a crypto payment in Test / Non-prod

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

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

The response includes a `trackingId` and a `paymentUrls.url` to redirect the buyer.

#### Polling payment status

Retrieve details by tracking id

```
GET {API_BASE}/Payments/tracking/{trackingId}
```

This endpoint returns the current payment object.

### Quick Reference

| Item                     | Value                                        |
| ------------------------ | -------------------------------------------- |
| **Test Payment API**     | `https://api.test.devs.beadpay.io`           |
| **OIDC Test base**       | `https://identity.beadpay.io/realms/nonprod` |
| **OIDC Production base** | `https://identity.beadpay.io/realms/prod`    |
| **Token path**           | `/protocol/openid-connect/token`             |
| **Common auth client**   | `bead-terminal` for terminals                |