Third-Party Integrations — Double PIN Technology

What Third-Party Integration Means

Third-party integration allows an external platform, such as a bank, fintech app, marketplace, e-wallet provider, document portal, enterprise admin system, or mobile application, to use Double PIN as a secure authorisation layer. The third-party system continues to run its own business logic, while Double PIN handles the second-stage PIN₂ authorisation process for sensitive actions.

How It Works Through APIs

The API model allows a third-party system to request, verify, and record PIN₂ authorisation without exposing its internal systems.

Integration Concept

Double PIN becomes an authorisation checkpoint

When a user tries to perform a sensitive action in a third-party system, that system calls the Double PIN API. Double PIN generates PIN₂, delivers it through the configured channel, and waits for the user to enter PIN₂. The third-party system then verifies the result before allowing the protected action to complete.

This means the third party does not need to redesign its entire application. It only needs to insert an API-based authorisation step at the point where extra security is required.

Third-Party App

Detects a sensitive action that requires PIN₂ approval.

Double PIN API

Creates the authorisation request and manages PIN₂ verification.

Action Approved

The third-party system completes the action only after successful authorisation.

Typical API Integration Flow

A clean request-response process protects the action while keeping the third-party system in control of its business logic.

User Starts a Sensitive Action

The user tries to complete a transfer, withdrawal, document unlock, admin change, purchase release, refund, or other protected operation.

Third Party Sends an Authorisation Request

The third-party backend sends a secure API request containing user reference, action type, transaction reference, expiry rules, callback URL, and metadata.

Double PIN Generates PIN₂

The API creates a time-limited authorisation challenge and delivers PIN₂ through the configured channel.

User Enters PIN₂ for Verification

The user enters PIN₂ in the third-party interface or a secure Double PIN verification screen, depending on the integration design.

API Response or Webhook Confirms the Result

Double PIN returns an approved, declined, expired, failed, or pending status. The third-party system then continues or blocks the action.

Example API Endpoints

These examples show the type of API structure third parties can use. Final endpoint names can be adjusted to match implementation standards.

Create Authorisation Request

Used when the third-party platform wants to start PIN₂ authorisation for a protected action.

POST /api/v1/authorisations
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "external_user_id": "USER-12345",
  "action_type": "wallet_transfer",
  "reference": "TXN-90001",
  "amount": 2500.00,
  "currency": "ZAR",
  "channel": "sms",
  "expires_in_seconds": 300,
  "callback_url": "https://partner.co.za/webhooks/double-pin",
  "metadata": {
    "device_id": "DEVICE-777",
    "ip_address": "196.0.0.1"
  }
}

Verify PIN₂

Used when the user enters PIN₂ and the third-party platform needs to confirm whether the action can proceed.

POST /api/v1/authorisations/{authorisation_id}/verify
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "pin2": "493821",
  "reference": "TXN-90001"
}

Check Authorisation Status

Used to check whether the PIN₂ challenge is pending, approved, failed, expired, or cancelled.

GET /api/v1/authorisations/{authorisation_id}
Authorization: Bearer {api_key}

Cancel Authorisation

Used when the third-party platform cancels the protected action before PIN₂ verification is completed.

POST /api/v1/authorisations/{authorisation_id}/cancel
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "reason": "User cancelled transfer"
}

Callbacks and Webhooks

Webhooks allow Double PIN to notify third-party systems when the authorisation status changes.

Webhook Event Example

When PIN₂ is approved, failed, expired, or cancelled, Double PIN can send a signed webhook event to the third-party callback URL. The third-party system verifies the webhook signature before trusting the update.

Approved events allow the third-party system to continue the action.
Failed or expired events allow the system to block or restart the action.
Signed events help prevent fake callback notifications.

POST https://partner.co.za/webhooks/double-pin
X-Double-Pin-Signature: sha256=...
Content-Type: application/json

{
  "event": "authorisation.approved",
  "authorisation_id": "AUTH-10001",
  "reference": "TXN-90001",
  "external_user_id": "USER-12345",
  "status": "approved",
  "approved_at": "2026-05-26T17:30:00Z",
  "metadata": {
    "action_type": "wallet_transfer"
  }
}

API Security Controls

Third-party API usage must be protected with strong security controls because it is handling sensitive authorisation decisions.

API Keys or OAuth

Each third-party system should authenticate API calls using approved credentials, scoped tokens, or OAuth-style access.

Signed Requests

Requests and webhooks can be signed so that both sides can verify message integrity and origin.

Replay Protection

Timestamps, nonces, and idempotency keys help prevent old requests from being reused maliciously.

Rate Limits

Rate limits help prevent brute-force attempts, API abuse, and excessive PIN₂ generation.

TLS Encryption

All API communication should happen over secure encrypted connections.

Audit Logs

Every request, verification attempt, status change, expiry, and callback can be logged for investigation and reporting.

Third-Party Integration Use Cases

Any platform with sensitive actions can use APIs to add Double PIN authorisation at the right checkpoint.

Wallet Transfers

A wallet app calls the API before releasing funds to another user or external account.

ATM Withdrawals

An ATM or banking system requests PIN₂ approval before dispensing cash.

Marketplace Handover

A marketplace verifies handover, receipt, or release actions before completing a protected transaction.

Document Access

A document platform calls the API before allowing file download, opening, or decryption.

Admin Overrides

An enterprise admin system requires PIN₂ before permission changes, refunds, exports, or manual overrides.

Payment Approval

A payment processor uses Double PIN to confirm that a user authorises a high-risk payment.

Third-party integration makes Double PIN usable across many platforms.

Through APIs, Double PIN can become a reusable authorisation layer for banks, fintech apps, marketplaces, enterprise systems, document platforms, and mobile applications that need stronger protection for sensitive actions.

API-Based Double PIN Integration