# Phase 11 Integration Guide

## VTpass

Verified current official behavior:
- Sandbox base: `https://sandbox.vtpass.com`
- Live base: `https://vtpass.com`
- POST authentication: `api-key` + `secret-key`
- GET authentication: `api-key` + `public-key`
- Purchase: `POST /api/pay`
- Requery: `POST /api/requery`
- Request ID begins with 12 numeric characters using Africa/Lagos/GMT+1 date/time.

Admin credentials:
- `api_key`
- `public_key`
- `secret_key`

Keep VTpass disabled until sandbox credentials are entered.

Every product should preserve the exact official `serviceID` and variation code from
VTpass. Do not infer service IDs from network names in production.

## Paystack

Verified current official behavior:
- Base: `https://api.paystack.co`
- Test/live mode is determined by the secret key.
- Initialize payment: `POST /transaction/initialize`
- Verify payment: `GET /transaction/verify/{reference}`
- Webhook signature: HMAC-SHA512 of raw payload with Paystack secret key in
  `x-paystack-signature`.
- Dedicated Virtual Account assignment: `POST /dedicated_account/assign`
- DVA fetch: `GET /dedicated_account/{id}`

Security behavior implemented:
- wallet is never credited from callback alone
- webhook signature is checked
- transaction is verified server-to-server
- verified amount must equal pending wallet-funding amount
- funding credit uses idempotency
- duplicate webhook deliveries are acknowledged safely

### Paystack DVA compliance
Paystack documents additional identity validation requirements for some Nigerian
business categories. The UI/API therefore requires explicit user consent and accepts
identity fields when needed. Do not collect or send BVN/account information unless
your Paystack account/business category actually requires it and you have an appropriate
privacy/compliance process.

## OPay

Adapter slot exists but remains disabled because this package does not guess merchant
endpoints or signature formats. Add only verified official merchant documentation.

## Smart SMS Solutions

Adapter slot exists but remains disabled until current official endpoint, auth, sender
and delivery-status documentation are verified.

## Production rule

Never place live credentials in code. Enter them through encrypted Provider Settings.