Telr

​

Architecture

                ┌────────────────────────────────┐
                │  Merchant store on Droplinked  │
                │  (selects Telr in settings)    │
                └────────────────┬───────────────┘
                                 │
   POST /telr/payment            │
   ───────────────────────────▶  │   creates Telr order via Gateway API
                                 │   (store_id + auth_key)
                                 ▼
                ┌────────────────────────────────┐
                │      Telr hosted page          │
                │  (PCI scope stays on Telr)     │
                └────────────────┬───────────────┘
                                 │ customer pays
                                 ▼
   POST /telr/webhook            │   transaction-advice POST
   ◀───────────────────────────  │   form-encoded, signed with SHA1
                                 │
   GET /telr/transactions/:id/status   ← merchant or backend poll
   POST /telr/transactions/:id/refund  ← merchant-initiated refund

​

Endpoints

​

Webhook signature scheme

hash = SHA1( store_id : auth_key : order_ref : amount : currency : status )

• Colon-joined, raw bytes, no trailing newline
• Compared with crypto.timingSafeEqual (side-channel safe)
• Mismatch returns HTTP 401 (not 400) so attackers can’t probe whether a cartId exists

​

Required form fields posted to /telr/webhook

​

Status mapping

​

Idempotency + state-machine guarantees

• Every webhook event is persisted by signature into telrTransaction.webhookEventIds
• State transitions run through a canTransition check — irreversibly forward-only
• A stale AUTHORIZED event arriving after CAPTURED is dropped (state never rewinds)
• The DB update + idempotency-list push run inside a single transaction so partial failures don’t desync state

​

Refund flow

POST /telr/transactions/:transactionId/refund

{
  "amount": "25.00",
  "reason": "Customer cancelled within 24h"
}

• Requires the merchant JWT for the shop that owns the transaction
• Calls Telr’s Order API with ivp_method=refund, tran_ref, tran_amount, tran_currency
• Successful refunds are recorded as child entries in telrTransaction.refunds[]
• Partial refunds supported (amount < captured_amount); subsequent attempts validate cumulative_refunded ≤ captured

​

Test mode

• Toggled by env: TELR_TEST_MODE=true (sends ivp_test=1 on the order body)
• Telr issues a separate store_id / auth_key pair for sandbox; same base URL (https://secure.telr.com)

​

Configuration

​

Supported currencies

​

Production checklist

• Telr merchant onboarding complete
• Webhook URL registered with Telr: https://apiv3.droplinked.com/telr/webhook
• HMAC verification + idempotency live
• Refund flow tested
• State-machine prevents status rollback
• Sandbox store_id + auth_key provisioned for apiv3dev.droplinked.com

​

Related

• Order lifecycle — how Telr fits the broader payment flow.
• Checkout stability — cross-PSP test matrix.