Remote Terminal Payments

Device-led payment

Operating model

Your backend sends commands to a qualified terminal through Payrallel Orchestration. The command channel is one-way and fire-and-forward: a request may be accepted while the device is offline, but delivery and execution require the terminal to be online and in API Mode.

Terminal setup: enable API Mode

1. On the terminal main screen, scroll upward with two fingers.
2. Authenticate with the authorised six-digit terminal PIN.
3. Open Operating Mode / Home Mode and select API.
4. Confirm the setting and return to the payment application.
5. Verify network connectivity and correct device date/time.

Commands execute only when the terminal is online and in API Mode. An accepted orchestration request does not by itself prove that the device received or completed it.

Authentication and data conventions

Authorization: {AUTHORIZATION_VALUE}
Content-Type: application/json; charset=UTF-8

• One access token maps to one terminal Sales Channel.
• Requests and responses use UTF-8 JSON.
• Amounts use integer minor units such as cents.
• Timestamps use UTC ISO 8601 unless specified otherwise.
• Store tokens in a secret manager and rotate them if compromised.

1. Create a sale request

POST {PAYRALLEL_API_BASE_URL}/terminal/payment-request/sale

{
  "amountInCents": 1500,
  "customOrderId": "{TRANSACTION_REFERENCE}"
}

2. Query transaction status

POST {PAYRALLEL_API_BASE_URL}/transactions/actions/query

{ "customOrderId": "{TRANSACTION_REFERENCE}" }

Representative response

{
  "success": true,
  "transaction": {
    "transactionId": "{TRANSACTION_REFERENCE}",
    "status": "processing",
    "paymentMethod": "paynow"
  }
}

Recommended polling cadence

• Poll every 1–2 seconds for approximately the first 10 seconds.
• Then back off to approximately 3–5 seconds.
• Stop after the project-defined timeout, typically within a 2–5 minute window, or when expiry is known.

For card payments, the transaction may not exist until the customer presents the card. A temporary “Transaction Not Found” response can therefore occur before payment; continue only within the approved polling window.

3. Pre-authorisation and capture

Create pre-authorisation

POST {PAYRALLEL_API_BASE_URL}/terminal/payment-request/preauth

{
  "amountInCents": 1500,
  "customOrderId": "{TRANSACTION_REFERENCE}"
}

Capture a pre-authorised transaction

POST {PAYRALLEL_API_BASE_URL}/transactions/card/capture

{
  "amountInCents": 1500,
  "customOrderId": "{TRANSACTION_REFERENCE}"
}

Query the pre-authorisation status before capture, and apply the project-specific rules for partial or full capture, timeout and reconciliation.

4. Cancel and void

Cancel the active terminal request

POST {PAYRALLEL_API_BASE_URL}/terminal/payment-request/cancel

Cancellation exits the active payment screen and returns the terminal to Ready or Idle when supported.

Void an approved transaction

POST {PAYRALLEL_API_BASE_URL}/transactions/actions/void

{ "customOrderId": "{TRANSACTION_REFERENCE}" }

Void is processed against the transaction’s original gateway; it is not rerouted to another provider. Reconcile failed or uncertain void attempts before retrying.

5. Query terminal status

POST {PAYRALLEL_API_BASE_URL}/terminal/status

Representative response

{
  "success": true,
  "status": "online",
  "state": "ready"
}

Minimal integration checklist

• Obtain and securely store the token for the terminal Sales Channel.
• Put the terminal into API Mode and verify network and time settings.
• Implement sale or pre-authorisation and capture as required.
• Implement transaction query using customOrderId.
• Implement terminal status and distinguish connectivity from payment outcome.
• Handle approved, declined, timeout and temporarily-not-found states.
• Implement cancel and void only where required and supported.
• Add bounded retries, backoff and an explicit reconciliation workflow.
• Test offline terminal, delayed delivery, duplicate requests and recovery.

Never expose terminal credentials or signing material in a browser, POS display, repository, log or support transcript.