Bank PSP Sandbox API — API.md

Base URL: https://banksandboxapi.shake-out.com/api

This sandbox simulates the provider/bank side only (no checkout UI). It accepts an opaque encrypted_card_payload, runs a deterministic scenario engine (approve/decline/3DS/timeout/error), enforces a strict transaction state machine, exposes mock 3DS challenge pages, and can dispatch signed webhooks.

Contract rule: Never return or log sensitive card data. The sandbox never stores decrypted PAN/CVV/expiry, and never persists the encrypted payload itself.

---

Contents

• Auth
• Idempotency
• Money & precision
• PCI and scope notes
• Errors format
• Transaction statuses
• State machine
• Scenarios
• Webhooks
• 3DS flow
• Endpoints
  • GET /health
  • POST /psp/payments/authorize
  • POST /psp/payments/capture
  • POST /psp/payments/refund
  • GET /psp/3ds/challenge/{transaction_id}
  • POST /psp/3ds/complete/{transaction_id}
  • GET /psp/transactions/{transaction_id}

---

Auth

Controlled by env: SANDBOX_AUTH_MODE

Mode: api_key

Send header:

• X-Api-Key: <your key>

Mode: none

No auth header required.

Unauthorized response:

{
    "error": "UNAUTHORIZED",
    "message": "API key missing or invalid",
    "details": {}
}

---

Idempotency

Supported on:

• POST /psp/payments/authorize

Header:

• Idempotency-Key: <string>

Behavior:

• If the same Idempotency-Key and merchant_order_id are sent again, the sandbox returns the original response (same transaction_id, status, etc.).
• If Idempotency-Key matches but merchant_order_id differs, treat it as a conflict and return 422.

Example conflict:

{
    "error": "IDEMPOTENCY_CONFLICT",
    "message": "Idempotency-Key was already used with a different merchant_order_id",
    "details": {
        "idempotency_key": "abc",
        "existing_merchant_order_id": "ORD-1",
        "incoming_merchant_order_id": "ORD-2"
    }
}

---

Money & precision

• amount is a decimal with up to 2 fractional digits.
• Clients should treat it as fixed-precision (avoid binary float rounding).

---

PCI and scope notes

• Never send raw PAN/CVV/expiry. Only send encrypted_card_payload.
• The sandbox never stores decrypted card data.
• The sandbox never stores the encrypted payload.
• Logging must redact sensitive keys/payloads.

Scope clarification

• Sandbox uses synthetic test data and a mock provider.
• Intended to be out of PCI DSS scope (no real PAN/CVV processing).

If you describe scope externally, be careful: the behavior is out-of-scope-like, but the real PCI scope depends on your full system boundary and assessor interpretation.

---

Errors format

All error responses must follow:

{
    "error": "ERROR_CODE",
    "message": "Human readable message",
    "details": {}
}

Common HTTP codes:

• 401 UNAUTHORIZED
• 404 NOT_FOUND
• 422 UNPROCESSABLE_ENTITY
• 500 INTERNAL_SERVER_ERROR
• 504 GATEWAY_TIMEOUT

---

Transaction statuses

• APPROVED
• DECLINED
• 3DS_REQUIRED
• CAPTURED
• REFUNDED

---

State machine

Valid transitions:

• APPROVED → CAPTURED
• CAPTURED → REFUNDED
• 3DS_REQUIRED → APPROVED
• 3DS_REQUIRED → DECLINED

Any invalid transition returns 422 UNPROCESSABLE_ENTITY.

Example:

{
    "error": "INVALID_STATE_TRANSITION",
    "message": "Cannot refund a payment that is not CAPTURED",
    "details": {
        "transaction_id": "tx_xxx",
        "current_status": "APPROVED",
        "required_status": "CAPTURED"
    }
}

---

Scenarios

Scenario engine is deterministic. You can force behavior via request field:

• scenario: approve | decline | 3ds | timeout | error

Notes:

• If scenario is omitted, sandbox may default to approve (recommended) or a configured default.
• timeout returns 504.
• error returns 500.
• 3ds returns 3DS_REQUIRED and provides acs_url.

---

Webhooks

If webhook_url is provided, the sandbox sends payment.updated when a transaction is created or updated (approve/decline/3DS required/capture/refund).

Delivery rules:

• Timeout: 3 seconds

• Retries: 2 (backoff 1s then 3s)

• Retries happen only on:

  • timeout
  • network error
  • non-2xx response

• No retries for any 2xx.

Signing

Controlled by env:

• WEBHOOK_SIGNING_MODE=hmac|stripe
• WEBHOOK_SECRET=...
• STRIPE_TOLERANCE_SECONDS=... (only in stripe mode)

HMAC mode

Headers:

• X-Signature-Timestamp: <unix>
• X-Signature: <hex(hmac_sha256("<ts>.<raw_body>", WEBHOOK_SECRET))>

Verification (PHP pseudo):

$timestamp = $_SERVER['HTTP_X_SIGNATURE_TIMESTAMP'];
$signature = $_SERVER['HTTP_X_SIGNATURE'];
$payload = $timestamp . '.' . $rawBody;
$expected = hash_hmac('sha256', $payload, $secret);
hash_equals($expected, $signature);

Stripe-style mode

Header:

• Stripe-Signature: t=<ts>,v1=<hex(hmac_sha256("<ts>.<raw_body>", WEBHOOK_SECRET))>

• Sandbox sends exactly one v1 signature.

Verification (PHP pseudo):

[$tPart, $v1Part] = explode(',', $_SERVER['HTTP_STRIPE_SIGNATURE']);
$timestamp = explode('=', $tPart)[1];
$signature = explode('=', $v1Part)[1];
$payload = $timestamp . '.' . $rawBody;
$expected = hash_hmac('sha256', $payload, $secret);
hash_equals($expected, $signature);

In WEBHOOK_SIGNING_MODE=stripe, reject if:

• abs(now - t) > STRIPE_TOLERANCE_SECONDS

Event: payment.updated

Payload:

{
    "event": "payment.updated",
    "data": {
        "transaction_id": "tx_xxx",
        "merchant_order_id": "ORD-12345",
        "status": "APPROVED|DECLINED|3DS_REQUIRED|CAPTURED|REFUNDED",
        "amount": 150.75,
        "currency": "EGP",
        "token": "tok_xxx_if_any",
        "provider_ref": "psp_xxx"
    }
}

---

3DS flow

1. Client calls POST /psp/payments/authorize with scenario=3ds
2. Sandbox returns status=3DS_REQUIRED and acs_url
3. Browser is redirected to acs_url (mock challenge UI)
4. Challenge submits result to POST /psp/3ds/complete/{transaction_id} with result=success|fail
5. Sandbox updates status to APPROVED or DECLINED and sends webhook payment.updated
6. If return_url was provided, the sandbox redirects the browser to:

return_url?transaction_id=...&status=...&token=... (token only if approved)

---

Endpoints

GET /health

Purpose: Service health check.

Request

• Path: GET /health
• Headers: none

Response 200

{
    "ok": true,
    "service": "bank-sandbox-api",
    "time": "2026-01-26T10:00:00Z"
}

---

POST /psp/payments/authorize

Purpose: Create a transaction and return APPROVED, DECLINED, or 3DS_REQUIRED (or simulated timeout / error).

Request

• Path: POST /psp/payments/authorize

• Headers:

  • Content-Type: application/json
  • Idempotency-Key: <string> (optional)
  • X-Api-Key: ... (required if SANDBOX_AUTH_MODE=api_key)

Body:

{
    "merchant_order_id": "ORD-12345",
    "amount": 150.75,
    "currency": "EGP",
    "encrypted_card_payload": "BASE64_OR_HEX_STRING",
    "scenario": "approve|decline|3ds|timeout|error",
    "webhook_url": "https://your-system.com/webhooks/payment",
    "return_url": "https://your-system.com/payments/return"
}

Validation

• merchant_order_id: required, string, max 100
• amount: required, numeric, > 0, max 2 decimals
• currency: required, 3-letter uppercase (e.g. EGP)
• encrypted_card_payload: required string, min length 20
• scenario: optional, one of approve|decline|3ds|timeout|error
• webhook_url: optional, valid URL
• return_url: optional, valid URL

Response 200 (APPROVED)

{
    "transaction_id": "tx_xxx",
    "merchant_order_id": "ORD-12345",
    "status": "APPROVED",
    "amount": 150.75,
    "currency": "EGP",
    "token": "tok_xxx",
    "provider_ref": "psp_xxx",
    "created_at": "2026-01-26T10:00:00Z"
}

Response 200 (DECLINED)

{
    "transaction_id": "tx_xxx",
    "merchant_order_id": "ORD-12345",
    "status": "DECLINED",
    "decline_code": "DO_NOT_HONOR",
    "decline_message": "Payment was declined",
    "amount": 150.75,
    "currency": "EGP",
    "created_at": "2026-01-26T10:00:00Z"
}

Response 200 (3DS_REQUIRED)

{
    "transaction_id": "tx_xxx",
    "merchant_order_id": "ORD-12345",
    "status": "3DS_REQUIRED",
    "acs_url": "https://banksandboxapi.shake-out.com/api/psp/3ds/challenge/tx_xxx",
    "amount": 150.75,
    "currency": "EGP",
    "created_at": "2026-01-26T10:00:00Z"
}

Response 504 (scenario=timeout)

{
    "error": "GATEWAY_TIMEOUT",
    "message": "Simulated timeout",
    "details": {
        "transaction_id": "tx_xxx_optional"
    }
}

Response 500 (scenario=error)

{
    "error": "PROVIDER_ERROR",
    "message": "Simulated provider error",
    "details": {
        "provider_error_code": "SIMULATED_500"
    }
}

Error codes

• 401 UNAUTHORIZED: API key missing/invalid
• 422 UNPROCESSABLE_ENTITY: validation failed or idempotency conflict
• 504 GATEWAY_TIMEOUT: scenario timeout
• 500 INTERNAL_SERVER_ERROR: scenario error

---

POST /psp/payments/capture

Purpose: Capture an approved payment.

Request

• Path: POST /psp/payments/capture

• Headers:

  • Content-Type: application/json
  • X-Api-Key: ... (required if SANDBOX_AUTH_MODE=api_key)

Body:

{
    "transaction_id": "tx_xxx"
}

Response 200

{
    "transaction_id": "tx_xxx",
    "merchant_order_id": "ORD-12345",
    "status": "CAPTURED",
    "amount": 150.75,
    "currency": "EGP",
    "token": "tok_xxx",
    "provider_ref": "psp_xxx",
    "created_at": "2026-01-26T10:00:00Z"
}

Errors

• 401 UNAUTHORIZED
• 404 NOT_FOUND: transaction not found
• 422 UNPROCESSABLE_ENTITY: allowed only when status is APPROVED

---

POST /psp/payments/refund

Purpose: Refund a captured payment.

Request

• Path: POST /psp/payments/refund

• Headers:

  • Content-Type: application/json
  • X-Api-Key: ... (required if SANDBOX_AUTH_MODE=api_key)

Body:

{
    "transaction_id": "tx_xxx"
}

Response 200

{
    "transaction_id": "tx_xxx",
    "merchant_order_id": "ORD-12345",
    "status": "REFUNDED",
    "amount": 150.75,
    "currency": "EGP",
    "token": "tok_xxx",
    "provider_ref": "psp_xxx",
    "created_at": "2026-01-26T10:00:00Z"
}

Errors

• 401 UNAUTHORIZED
• 404 NOT_FOUND: transaction not found
• 422 UNPROCESSABLE_ENTITY: allowed only when status is CAPTURED

---

GET /psp/3ds/challenge/{transaction_id}

Purpose: Display mock 3DS challenge page (HTML).

Request

• Path: GET /psp/3ds/challenge/{transaction_id}
• Headers: none

Response

• 200 text/html: page with Approve / Fail buttons

Errors

• 404 NOT_FOUND

---

POST /psp/3ds/complete/{transaction_id}

Purpose: Complete 3DS challenge and update transaction state.

Request

• Path: POST /psp/3ds/complete/{transaction_id}

• Headers:

  • Content-Type: application/json or application/x-www-form-urlencoded

Body (either):

• JSON: { "result": "success|fail" }
• Form: result=success|fail

Response 200 (JSON)

{
    "transaction_id": "tx_xxx",
    "status": "APPROVED|DECLINED",
    "token": "tok_xxx_if_any"
}

Redirect behavior (if return_url is set)

• Returns 302 redirect to return_url with query params:

  • transaction_id
  • status
  • token (only if approved)

CSRF

This endpoint is excluded from CSRF protection because it is called from the mock 3DS page.

Errors

• 404 NOT_FOUND
• 422 UNPROCESSABLE_ENTITY: invalid state or invalid result

---

GET /psp/transactions/{transaction_id}

Purpose: Debug endpoint to view safe transaction data.

Request

• Path: GET /psp/transactions/{transaction_id}

• Headers:

  • X-Api-Key: ... (required if SANDBOX_AUTH_MODE=api_key)

Response 200

{
    "transaction_id": "tx_xxx",
    "merchant_order_id": "ORD-12345",
    "amount": 150.75,
    "currency": "EGP",
    "status": "APPROVED",
    "scenario": "approve",
    "token": "tok_xxx",
    "provider_ref": "psp_xxx",
    "webhook_url": "https://your-system.com/webhooks/payment",
    "return_url": "https://your-system.com/payments/return",
    "created_at": "2026-01-26T10:00:00Z",
    "updated_at": "2026-01-26T10:00:00Z"
}

Errors

• 401 UNAUTHORIZED
• 404 NOT_FOUND

---

Change log (recommended)

• 2026-01-26: Initial public draft.