---
name: payguru-one-api-integration
description: Integrates a merchant system with the Payguru ONE API (tpay ONE API, Turkey) for DCB, Open Banking (OB), Bank Transfer (BT), refunds and DCB subscriptions. Use it when the merchant wants to add Payguru payments to their backend, write the test cases, try them in the sandbox and prepare the go-live. It never goes to production by itself, production needs a finished onboarding and production keys issued by Payguru.
---

# Payguru ONE API integration

You are integrating the merchant's own backend with the Payguru ONE API. Work in the merchant's repository, in their language and framework, and follow their code style. The sandbox is `https://sandbox.payguru.com`.

## Sources of truth

Fetch these first and read them fully. Do not rely on memory, the contract changes.

| What | URL |
|---|---|
| Integration guide (flow, signing, webhooks, results, go-live) | `https://sandbox.payguru.com/docs/integration-guide.md` |
| API reference (every endpoint and field) | `https://sandbox.payguru.com/docs/openapi.yaml` |
| Sandbox console (keys, webhook log, pending items) | `https://sandbox.payguru.com/sandbox/` |

If the guide and this file disagree, the guide wins.

## Ground rules

1. **Never handle production credentials.** Production keys are issued by Payguru after onboarding. Do not ask for them in the chat, do not write them to a file in the repository, do not put them in a test. The code reads keys and base URL from environment variables, nothing else changes between sandbox and production.
2. **The private key stays on the merchant's server.** Sessions are signed server side. Never expose the key to a browser, a mobile app, a log line or the repository. Keep sandbox keys in an untracked `.env` file and add it to `.gitignore`.
3. **The webhook is the source of truth.** Never fulfil an order from a redirect to `successUrl`. Fulfil from a verified `completed` webhook, or from a `verify` call.
4. **Do not invent API fields.** If something is missing from the reference, ask the merchant or tell them to ask Payguru.
5. **Stop at the production gate** (phase 6). You can prepare everything, you cannot pass it.

## Phase 0: Scope

Ask the merchant only what you cannot read from the repository:

- Which methods: DCB S2S, DCB checkout (hosted page), OB, BT (wallet or not), refunds, subscriptions.
- Where orders live (table, service) and what "paid" means in their system.
- Their public webhook URL for the sandbox (a tunnel to a dev machine is fine).
- Whether they already have an onboarding with Payguru (see phase 6). It is not needed for the sandbox.

Write the scope down in a short `PAYGURU.md` in the repository. Update it as you go.

## Phase 1: Sandbox access

1. Create a sandbox merchant. Either the merchant opens the console and does it, or you call `POST https://sandbox.payguru.com/sandbox/api/merchants` with `{"webhookUrl": "...", "webhookFormat": "post"}`. The response holds `publicKey` and `privateKey`.
2. Write the keys to `.env` (`PAYGURU_BASE_URL`, `PAYGURU_PUBLIC_KEY`, `PAYGURU_PRIVATE_KEY`). The same private key signs and verifies webhooks. Do not print the private key in your output.
3. Sandbox merchants are deleted after 14 days unused. If calls start returning `401`, create a new one.

## Phase 2: Implement

Build, in this order. Keep it as a small client module the merchant can read in one sitting.

1. **Signing and sessions.** `startpaymentintent` and `startrefundintent` as in guide section 3. The signature is AES-256-CBC over `UUID=...&Timestamp=...&Language=en` with a key derived from the private key. Cover it with a test against a live sandbox call, a wrong implementation only shows up as `401`.
2. **Payment calls.** `onetime/start` (dcb, ob, bt), `onetime/checkout` if they use the hosted page, `onetime/verify`. Amounts are strings in minor units. Send `TPAY-Request-Id` (a new UUID per call, store it with the order) and `TPAY-Client-IP` on every start.
3. **Webhook endpoint.** Public HTTPS, reads the **raw body**, verifies `TPAY-Signature` (`{publicKey}:{hex HMAC-SHA256(rawBody, privateKey)}`) with a constant-time compare, answers 2xx within 10 seconds, does the work after answering if it is slow. Reject a bad signature with 401.
4. **Idempotent handling.** Key on `eventId`. Events repeat and arrive out of order: decide on `result.reason` and the state already stored, never move a paid order back to pending. Every state is sent (`pending`, `processing`, then the final one), so treat the early ones as information only.
5. **Result mapping.** Branch on `result.reason`, never on `description`. Use the table in guide section 6. `retryable: true` means retry later, `unavailable` and `error` never mean "not paid".
6. **Fallback.** A scheduled check that calls `verify` for orders that stay pending longer than expected, so a lost webhook does not strand an order.
7. **Refunds** if in scope: the refund session is the idempotency key, OB and BT refunds are requests that finish later by `onetime.refund`.
8. **Subscriptions** if in scope: states and `subscription.payment` / `subscription.status` as in the guide.

## Phase 3: Test cases

Write automated tests. Unit tests for signing and webhook verification (include a tampered body and a wrong key). Then scenario tests that run against the sandbox with the test data below. Each row is one test: start, wait for the webhook, assert the order state.

| Scenario | Input | Expected |
|---|---|---|
| DCB completed | msisdn `5550000001` | `completed`, order paid |
| DCB declined | `5550000002` | `declined`, order not paid, customer can retry |
| DCB expired | `5550000003` | `expired` |
| DCB cancelled | `5550000004` | `cancelled` |
| DCB pending | `5550000005` | stays `pending` until resolved in the console, then final |
| DCB start failures | `5550000006`, `07`, `08` | `declined`, `invalidrequest`, `unavailable` (`retryable: true`) |
| OB / BT declined | amount ends `01` | `declined` |
| OB / BT held | amount ends `02` | `processing`, then `completed` after release in the console |
| OB / BT cancelled | amount ends `03` | `cancelled` |
| OB / BT expired | amount ends `04` | `expired` |
| OB / BT partial | amount ends `05` | `partial`, order not marked fully paid |
| OB / BT completed | any other amount | `completed` |
| Duplicate webhook | send the same event twice | processed once |
| Bad signature | tamper with the body | rejected, 401 |
| Failing endpoint | return 500 once | retry arrives (after 30 s), no double processing |
| Lost webhook | do not answer at all | `verify` fallback resolves the order |
| Refund | full, partial, same session twice | one refund, never two |

Resolving pending items and releasing held payments is done by hand in the sandbox console, or on the sandbox payment pages. Tell the merchant when a test needs that step.

## Phase 4: Run in the sandbox

1. Start the merchant's app with the sandbox `.env` and expose the webhook URL.
2. Run the scenario tests. Check the **webhook log** in the console: every delivery, its HTTP status, and whether the signature matched.
3. Report as a table: scenario, expected, actual, pass or fail. Fix failures, do not delete the test. A flaky test is a bug in the merchant's handler (usually idempotency or ordering), find the cause.

## Phase 5: Review before go-live

Walk the go-live checklist in guide section 7 against the code and tick each item with evidence (file and line, or a test name). Anything you cannot show is not done. Also check:

- the private key is only read from the environment, nowhere in the repository or the logs;
- logs carry `TPAY-Request-Id`, `paymentId` and `eventId` and no full msisdn or IBAN;
- amounts never pass through floating point.

## Phase 6: Production gate

Stop here and tell the merchant, in these words or close to them:

> The integration is ready and tested in the sandbox. Production needs two things you do with Payguru, not with me: a completed onboarding and the production keys that Payguru issues after approval.

- **Onboarding.** The merchant starts it at `https://report.payguru.com/create-account`, or by contacting Payguru by email or phone (`https://www.payguru.com/tr/destek`). Payguru checks the company, agrees the methods and the OB / BT bank and institution codes, and takes the production webhook URL.
- **Production keys** are different from the sandbox keys and are delivered by Payguru to the merchant. Do not create, guess or request them. Never put them in the repository or in this chat.
- **Cut-over** is the merchant's step, after Payguru confirms: put the production base URL and keys into the production environment (a secret store, not a file in the repository), allow the Payguru webhook addresses if they filter by IP, run one small real payment per method and one refund, then watch the first days. Nothing else in the code changes.

Offer to prepare a short cut-over checklist for their ops team. Do not run anything against production yourself.

## Support

Every support request to Payguru needs the `TPAY-Request-Id` of the call, the `paymentId` or `subscriptionId`, and the time. Make the merchant's code log them.
