### Gerät koppeln [#pair-a-device]
Die Kopplung weist einem Tapaya-Gerät eine `externalDeviceId` zu, sodass Sie es beim Auflisten der Geräte finden
und beim Starten einer Zahlung gezielt ansprechen können.
#### Zuweisung aus Ihrer App [#assign-from-your-app]
Ihre Anwendung ruft auf dem Gerät eine Funktion des Accept SDK auf, die ihm seine `externalDeviceId` zuweist. Verwenden Sie
in jedem Aufruf der Cloud Accept API für dieses Gerät dieselbe Kennung.
#### QR-Code scannen [#scan-a-qr-code]
Der Händler öffnet den Kopplungsvorgang in der Tapaya Platform, die einen QR-Code für die
zuzuweisende `externalDeviceId` anzeigt. Der Händler scannt ihn mit der Tapaya-Händler-App auf dem Zielgerät,
und die App schließt die Kopplung ab.
### Zugriffstoken eintauschen [#exchange-an-access-token]
Tauschen Sie Ihr Server Secret Token und das `merchantToken` des Händlers mit
`POST /ecr/auth` gegen ein Zugriffstoken ein. `merchantToken` wird nur hier gesendet; alle späteren Aufrufe senden nur
`Authorization: Bearer
`.
cURL
TypeScript
```bash
curl -X 'POST' 'https://api.tapaya.com/ecr/auth' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer REPLACE_ME' \
-d '{
"merchantToken": "unique_merchant_id_from_your_db"
}'
```
```typescript
const res = await fetch('https://api.tapaya.com/ecr/auth', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${process.env.TAPAYA_SECRET_TOKEN}`,
},
body: JSON.stringify({ merchantToken: 'unique_merchant_id_from_your_db' }),
});
const { accessToken, expiresAt } = await res.json();
```
```json title="200 OK"
{
"accessToken": "...",
"tokenType": "Bearer",
"expiresAt": "2026-01-13T16:30:59Z"
}
```
| Code | Beschreibung |
| ----- | --------------------------------------- |
| `401` | Ungültiges oder abgelaufenes API-Token. |
| `403` | Zugriff auf den Händler nicht erlaubt. |
**Erneuern Sie das Token vor `expiresAt`.** Rufen Sie `POST /ecr/auth/refresh` mit dem aktuellen, noch gültigen
`accessToken` im Header `Authorization` auf. Der Endpoint gibt denselben Body mit einem neuen Token zurück; speichern Sie es
und verwenden Sie ab dann nur noch dieses.
cURL
TypeScript
```bash
curl -X 'POST' 'https://api.tapaya.com/ecr/auth/refresh' \
-H 'Authorization: Bearer ACCESS_TOKEN'
```
```typescript
const res = await fetch('https://api.tapaya.com/ecr/auth/refresh', {
method: 'POST',
headers: { Authorization: `Bearer ${accessToken}` },
});
const renewed = await res.json(); // { accessToken, tokenType, expiresAt }
```
| Code | Beschreibung |
| ----- | ------------------------------------------------------------------------------------------------------------ |
| `401` | Das Zugriffstoken ist ungültig, abgelaufen oder widerrufen. Tauschen Sie mit `POST /ecr/auth` ein neues ein. |
| `403` | Sie haben keinen Zugriff mehr auf den Händler. Es wird kein neues Token ausgestellt. |
### Einsatzbereites Gerät finden [#find-a-ready-device]
Listen Sie die Geräte des Händlers mit `GET /ecr/devices` auf. Mit `?connected=true` lassen Sie
nicht verbundene Geräte weg; ein einzelnes Gerät rufen Sie mit `GET /ecr/devices/{externalDeviceId}` ab.
cURL
TypeScript
```bash
curl 'https://api.tapaya.com/ecr/devices/till-01' \
-H 'Authorization: Bearer ACCESS_TOKEN'
```
```typescript
const res = await fetch('https://api.tapaya.com/ecr/devices/till-01', {
headers: { Authorization: `Bearer ${accessToken}` },
});
const device = await res.json();
const canPay = device.availability === 'ready';
```
```json title="200 OK"
{
"externalDeviceId": "till-01",
"name": "Front counter",
"connected": true,
"availability": "ready",
"lastSeenAt": "2026-01-13T16:30:59Z",
"updatedAt": "2026-01-13T16:30:59Z"
}
```
Senden Sie Zahlungen nur an ein Gerät, dessen `availability` den Wert `ready` hat. Die Liste ist eine Momentaufnahme:
Die Verfügbarkeit wird beim Absenden erneut geprüft, daher kann auch ein Gerät mit `ready` eine Anfrage
ablehnen. Siehe [Geräteverfügbarkeit](#device-availability).
### Zahlungsanfrage senden [#submit-a-payment-request]
Senden Sie den Betrag mit `POST /ecr/payment-requests` an ein Gerät. Tapaya speichert die Anfrage und
benachrichtigt das Gerät, das den Zahlungsbildschirm anzeigt.
cURL
TypeScript
```bash
curl -X 'POST' 'https://api.tapaya.com/ecr/payment-requests' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Idempotency-Key: order-1042-attempt-1' \
-d '{
"externalDeviceId": "till-01",
"amount": 12500,
"tipAmount": 500,
"currency": "CZK"
}'
```
```typescript
const res = await fetch('https://api.tapaya.com/ecr/payment-requests', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${accessToken}`,
'Idempotency-Key': 'order-1042-attempt-1',
},
body: JSON.stringify({
externalDeviceId: 'till-01',
amount: 12500, // 125.00 Kč
tipAmount: 500, // 5.00 Kč
currency: 'CZK',
}),
});
const { requestId } = await res.json(); // 202 Accepted
```
**Parameter:**
| Feld | Typ | Erforderlich | Beschreibung |
| ------------------ | --------- | ------------ | --------------------------------------------------------------------------- |
| `externalDeviceId` | `string` | ✓ | Das gekoppelte Gerät, das die Zahlung anzeigen soll. |
| `amount` | `integer` | ✓ | Betrag in der kleinsten Einheit der Währung (`12500` entspricht 125,00 Kč). |
| `tipAmount` | `integer` | | Trinkgeld in der kleinsten Einheit der Währung. |
| `currency` | `string` | ✓ | ISO-4217-Währungscode. |
| `paymentToken` | `string` | | Eine bestehende Zahlung, an die die Anfrage angehängt werden soll. |
```json title="202 Accepted"
{
"requestId": "...",
"status": "pending",
"paymentToken": null,
"expiresAt": "2026-01-13T16:30:59Z"
}
```
`202 Accepted` bedeutet, dass Tapaya die Anfrage gespeichert hat. Es bedeutet weder, dass das Gerät sie gesehen hat,
noch, dass der Kunde bezahlt hat. Alles, was später fehlschlägt, erreicht Sie als Statusänderung.
**Sichern Sie Wiederholungsversuche ab.** Der Header `Idempotency-Key` ist erforderlich. Wird ein Schlüssel mit demselben Body erneut verwendet,
wird die ursprüngliche Anfrage zurückgegeben, statt eine zweite Zahlung zu starten; wird er mit einem anderen
Body erneut verwendet, wird `409 idempotency_conflict` zurückgegeben. Binden Sie den Schlüssel an den Verkauf und den Versuch, wie bei
`order-1042-attempt-1`.
### Ergebnis verfolgen [#track-the-result]
Verfolgen Sie die Anfrage durch ihre [Status](#request-statuses) mit Webhooks, oder fragen Sie regelmäßig
`GET /ecr/payment-requests/{requestId}` ab. Sobald sie `payment_created` erreicht, enthält die Antwort
das `paymentToken`, und Events vom Typ `payment.updated` melden den Fortschritt der Zahlung selbst.
Um Webhooks zu empfangen, registrieren Sie Ihren HTTPS-Endpoint mit `POST /ecr/webhook-subscriptions` oder legen Sie die
Callback-URL und die Event-Typen für den Händler in der Tapaya Platform fest.
cURL
TypeScript
```bash
curl -X 'POST' 'https://api.tapaya.com/ecr/webhook-subscriptions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
"url": "https://integrator.example.com/webhooks/tapaya",
"events": ["payment_request.updated", "payment.updated"]
}'
```
```typescript
const res = await fetch('https://api.tapaya.com/ecr/webhook-subscriptions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${accessToken}`,
},
body: JSON.stringify({
url: 'https://integrator.example.com/webhooks/tapaya',
events: ['payment_request.updated', 'payment.updated'],
}),
});
const { subscriptionId, signingSecret } = await res.json(); // 201 Created
```
```json title="201 Created"
{
"subscriptionId": "...",
"url": "https://integrator.example.com/webhooks/tapaya",
"events": ["payment_request.updated", "payment.updated"],
"signingSecret": "..."
}
```
`signingSecret` wird nur beim Erstellen des Abonnements zurückgegeben. Speichern Sie es sicher; Sie
benötigen es, um die Signatur eingehender Webhooks zu prüfen.
Ein Abonnement gehört dem Integrator und dem Händler, nicht einem Zugriffstoken, und bleibt daher bei der
Erneuerung des Tokens bestehen. Beantworten Sie jedes Event mit einem `2xx`, sobald Sie es angenommen haben.
Webhooks sind Benachrichtigungen, kein Zahlungsnachweis, und ein Webhook kann verspätet oder gar nicht ankommen. Schließen Sie
einen Verkauf nie allein aufgrund eines Webhooks ab:
* **Wenn ein Webhook ankommt,** bestätigen Sie das endgültige Ergebnis über die API, zum Beispiel mit
[Zahlungsdetails abrufen](/platform-api/reporting#retrieve-payment-details).
* **Wenn kein Webhook ankommt** (innerhalb eines zu Ihrem Bezahlvorgang passenden Timeouts, spätestens jedoch
bis zum `expiresAt` der Anfrage), rufen Sie `GET /ecr/payment-requests/{requestId}` auf, um ihren
aktuellen Status abzufragen, und bestätigen Sie die Zahlung dann wie oben beschrieben über die API.