Accept session claim

Lets your users pay at a Taappa merchant terminal by scanning a QR code.

How it works

A merchant terminal displays a QR code containing a deep link: taappa://accept/{session_id}.
Your app scans the QR and extracts the session_id.
Your server (or app) calls this endpoint with the session_id, the user's wallet_id, and their active card_series.
Taappa links the card to the terminal session and the payment completes.

That's it. One scan, one API call.

POST/partner/v1/accept-session-claims

Request

http

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
Idempotency-Key: <optional>

Field	Type	Required	Description
`session_id`	string	Yes	Extracted from the terminal QR deep link (`taappa://accept/{session_id}`)
`wallet_id`	string	Yes	The user's partner wallet ID
`card_series`	string	Yes	Series of the user's current active digital card

json

{
  "session_id": "6a959342454db4ecdc9fef5d",
  "wallet_id": "7b0a1c2d3e4f5a6b7c8d9e0f",
  "card_series": "3GGEN3QVVV"
}

Response

json

{
  "id": "6a959342454db4ecdc9fef5d",
  "status": "ready",
  "amount": 42.0,
  "currency": "ETB",
  "expires_at": "2026-09-02T18:05:00.000000",
  "created_at": "2026-09-02T18:00:00.000000",
  "wallet_id": "7b0a1c2d3e4f5a6b7c8d9e0f",
  "card_series": "3GGEN3QVVV",
  "masked_card_number": "•••• •••• •••• 7890",
  "partner_slug": "telebirr",
  "environment": "live",
  "provider": "telebirr",
  "phone_e164": "+251911234567",
  "cardholder_name": "Amina Hassan"
}

The full PAN is never returned. If the same card already claimed the session, the API returns 200 with status: "ready" (idempotent).

Errors

Status	Detail
`400`	`Active digital card required`
`400`	`card_series does not match wallet`
`400`	`card_series must be 10 characters`
`400`	`Session expired` / `Session already used` / `Session already claimed`
`404`	`Wallet not found`
`404`	`Session not found`
`401`	`Not authenticated` / `Invalid API key`

Example

bash

curl https://api.taappa.com/partner/v1/accept-session-claims \
  -H "Authorization: Bearer $TAAPPA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "6a959342454db4ecdc9fef5d",
    "wallet_id": "7b0a1c2d3e4f5a6b7c8d9e0f",
    "card_series": "3GGEN3QVVV"
  }'