Skip to content
BaxPayDevelopers

In-store integration

Connections & credentials

A connection is how a merchant POS system authenticates to BaxPay. One per till or pump lane, scoped to exactly what it needs.

Create connections with your API key, or from the Business dashboard under Developers → Connections. Each connection issues a bearer credential (bxc_…) used on every in-store Session API call. A connection created with a bx_test_ key is a test connection, and only ever opens test sessions.

Anatomy of a connection

labelrequired

A name you'll recognise later, 2–120 characters: Lane 4, Pump 3 controller.

systemTyperequired

ECR · FORECOURT · ECOMMERCE: what's on the other end. (ERP is provisioned from Accounting.)

terminalId

The BaxPay terminal this connection's sessions go to. Without it, sessions are created but no terminal picks them up, so only the sandbox simulate call can complete them.

protocol

NATIVE (default) · NEXO · OPI · IFSF: which message dialect it speaks. Anything other than NATIVE is routed through the matching adapter.

topology

LOCAL (default: you poll for the result) or CLOUD (we POST it to your callbackUrl).

callbackUrlcloud only

Where signed session results are delivered. A CLOUD connection without one is refused with 403.

saleSystemId · poiIdnexo

Identifiers your nexo estate already uses for the sale system and the point of interaction.

Provisioning

POST/connectionswith your API key
GET/connectionslist this mode's connections
DEL/connections/{id}revoke (204)
curl -X POST https://sandbox-api.baxpay.com/v1/connections \
  -H "Authorization: Bearer $BAXPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Lane 4",
    "systemType": "ECR",
    "terminalId": "TERM-PARIS-04"
  }'
{
  "success": true,
  "data": {
    "connectionId": "358f1a7a-…",
    "credential": "bxc_hwsOcP3Y65z9G1X4…"
  }
}

A CLOUD connection's response also carries callbackSecret.

A cloud connection gets its result pushed. Open a sale on the cloud connection and, in sandbox, approve it: the signed callback reaches callbackUrl.

SESSION=$(curl -s -X POST https://sandbox-api.baxpay.com/v1/integration/sessions \
  -H "Authorization: Bearer bxc_hwsOcP3Y65z9G1X4…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "saleReferenceId": "cloud-receipt-1", "amountMinor": 990 }' | jq -r .data.sessionId)
 
curl -X POST "https://sandbox-api.baxpay.com/v1/integration/sessions/$SESSION/simulate" \
  -H "Authorization: Bearer bxc_hwsOcP3Y65z9G1X4…" -H "Content-Type: application/json" \
  -d '{ "outcome": "APPROVED" }'

Using and revoking

Send the credential as a bearer token on every in-store call:

Authorization: Bearer bxc_hwsOcP3Y65z9G1X4…

To rotate, create the new connection first, cut the till over to it, then revoke the old one, in that order, so no lane is ever without a working credential.

curl https://sandbox-api.baxpay.com/v1/connections \
  -H "Authorization: Bearer $BAXPAY_API_KEY"

Newest first:

{
  "success": true,
  "data": [
    {
      "id": "9c41d0e2-…",
      "label": "Head office (cloud)",
      "livemode": false,
      "systemType": "ECR",
      "protocol": "NATIVE",
      "topology": "CLOUD",
      "status": "ACTIVE",
      "terminalId": null,
      "callbackUrl": "https://pos.mystore.com/baxpay",
      "createdAt": "2026-07-16T14:00:00.000Z"
    }
  ]
}
curl -X DELETE https://sandbox-api.baxpay.com/v1/connections/358f1a7a-… \
  -H "Authorization: Bearer $BAXPAY_API_KEY"

Revocation is immediate: the next call with that credential gets 401.