VerityPro API Documentation

Overview

VerityPro provides KYC identity verification, address verification, enhanced due diligence (EDD), and transaction monitoring (AML) as modular APIs and SDKs. Each product is independently activatable — your integration only calls the services your compliance programme requires.

KYC

Document capture + biometric liveness with PEP/sanctions screening.

Address Verification

Proof-of-address with geocoding and document matching.

Enhanced Due Diligence

Deep customer risk profiling triggered by TM or rule conditions.

Transaction Monitoring

Real-time AML scoring, velocity rules, and case management.

Base URL

https://api.skylinefare.com

Request format

All requests are JSON (Content-Type: application/json). Authentication uses two headers present on every call.

Authentication

VerityPro uses API key authentication. Every request must include both headers below. Retrieve your keys from the Integrations page in the VerityPro portal.

Parameter	Type	Required	Description
x-api-key	string	Required	Your integration API key. Treat this as a secret — never expose it in client-side code.
Integrationid	UUID	Required	Your integration UUID. Safe to embed in mobile SDKs (public identifier).

Key rotation

Rotate keys from the portal under Settings → Integration → Keys → Rotate. When the rotation runs immediately, the new key is displayed once — copy it into your secrets manager before you close the dialog. If your organisation requires approval for key rotation, the request is queued instead and the new key is not shown in that dialog; ask your approver how it will be delivered before you rotate.

Never put your API key in client code

The x-api-key header must only be sent from your server. Mobile and web SDK calls use a short-lived session token minted by your server.

Environments

Environment	Base URL	Notes
Production	https://api.skylinefare.com	Real verifications, billing applies
Sandbox	https://sandbox.api.skylinefare.com	No billing, test documents accepted

Pass sandbox: true in SDK options to target the sandbox automatically. Server-side calls set the base URL manually.

Create KYC Session

Before launching the SDK on the user's device, your server creates a KYC session. The response contains a sessionToken that you pass to the SDK. This keeps your API key server-side only.

POST/integration/api/integration/kyc/session

Parameter	Type	Required	Description
userId	string	Required	Your internal user identifier — returned unchanged in every webhook.
firstName	string	Required	User's legal first name.
lastName	string	Required	User's legal last name.
email	string	Optional	Used for communications and duplicate detection.
dateOfBirth	YYYY-MM-DD	Optional	Pre-fills the document verification step.
streetAddress	string	Optional	Pre-fills address verification if enabled.
country	ISO 3166-1 alpha-2	Required	User's country of residence.
requiredModules	string[]	Required	Modules to run: 'DOCUMENT', 'BIOMETRIC', 'ADDRESS'.
locale	string	Optional	SDK UI locale. Default: 'en-AU'.

Response

{ "sessionToken": "vt_sess_...", "sessionId": "sess_abc123", "expiresAt": "2024-01-15T11:30:00Z" }

Pass sessionToken to the SDK. Sessions expire in 60 minutes.

Hosted Web Page (v2)

The recommended integration for web. Your backend creates a KYC session and VerityPro returns a sessionUrl. Redirect your user to that URL — the hosted page runs the full verification flow with your branding applied — or embed it in an iframe and listen for the completion postMessage.

POST/kycintegration/kyc-verification/add-kyc-verification

Create the session server-side with your secret key — never in the browser. The response contains data.sessionUrl.

Redirect (full-page)

window.location.href = data.sessionUrl;

Iframe embed + postMessage

iOS SDK

Install via Swift Package Manager: https://github.com/VerityPro/verity-pro-ios

Requirements

iOS 17.0+ deployment target
Camera and FaceID usage descriptions in Info.plist
Session token minted by your server (see Create Session)

Info.plist entries required

<key>NSCameraUsageDescription</key> <string>Required for document capture and liveness check.</string> <key>NSFaceIDUsageDescription</key> <string>Used for biometric authentication.</string>

Result handling

The VerityResult returned in the completion block contains the outcome, completed steps, and any error details including whether the error is recoverable.

Android SDK

Add to your build.gradle or build.gradle.kts:

dependencies { implementation("com.veritypro:sdk:1.0.0") }

Manifest permissions

<uses-permission android:name="android.permission.CAMERA" />

Activity result launcher

Register the launcher in onCreate before the activity is started. Use VerityPro.extractResult(result) to get the typed result.

Flutter SDK

Dart plugin bridging to the native iOS/Android SDKs — same product coverage. Installed via git dependency (not published to pub.dev).

pubspec.yaml

dependencies: verity: git: url: https://github.com/TopRateTransfer-Pty-Ltd/verity_flutter_sdk.git ref: "fa28fbcf808c16a349d48fa96fb9f78da8c2ad29"

v2 — server-driven (recommended): pass serverSessionId from your backend and mode: VerityMode.serverDriven. The full Dart example is in the code panel.

v1 — legacy: use mode: VerityMode.biometric (or .address / .edd) with preCreatedSessionId.

Web SDK

Install: npm install @veritypro/web-sdk

Presentation modes

Mode	Description
modal	Overlay on top of your page
embed	Mounted into a container element you provide
hosted	Full-page redirect to VerityPro hosted URL

Use the embedToken from your server session call. Do not pass your API key to the web SDK.

KYC Webhooks

VerityPro delivers a webhook to your registered endpoint when a KYC session reaches a terminal state. Configure the URL in Settings → Integration → Webhooks.

Payload fields

Parameter	Type	Required	Description
event	string	Required	Event type, e.g. 'kyc.completed'
status	string	Required	Outcome: approved \| pendingManualReview \| rejected \| cancelled \| failed
userId	string	Required	Your userId passed at session creation
sessionId	string	Required	VerityPro session identifier
completedSteps	string[]	Optional	Modules completed: ['DOCUMENT', 'BIOMETRIC']
timestamp	ISO 8601	Required	UTC time of the event

Verify the X-VerityPro-Signature header on every webhook before processing. See Verify Signature for details.

Address SDK

Address verification is triggered through the same SDK as KYC — set mode: .address (iOS) or mode = VerityMode.ADDRESS.name (Android). No separate SDK install is needed.

SDK options for address verification

Parameter	Type	Required	Description
streetAddress	string	Required	User's street address to verify
city	string	Optional	City / suburb
stateOrProvince	string	Optional	State or province code
postalCode	string	Optional	Postcode / ZIP
country	string	Required	Country of the address (full name or ISO code)

Address Server API

You can also verify addresses directly from your server without launching the mobile SDK — useful for document-based proof-of-address flows.

POST/integration/api/integration/address/verify

Parameter	Type	Required	Description
userId	string	Required	Your internal user identifier
firstName	string	Required	User's first name
lastName	string	Required	User's last name
streetAddress	string	Required	Street address
city	string	Optional	City
state	string	Optional	State or province
postalCode	string	Optional	Postcode / ZIP
country	string	Required	Country (ISO 3166-1 alpha-2)
dateOfBirth	YYYY-MM-DD	Optional	Used for cross-verification

Trigger EDD

Enhanced Due Diligence (EDD) is triggered when your risk programme identifies a customer requiring deeper scrutiny — typically after a high-risk transaction flag or on a scheduled review cycle.

POST/integration/api/integration/edd

Parameter	Type	Required	Description
userId	string	Required	Your internal user identifier
triggerReason	enum	Required	HIGH_RISK_TRANSACTION \| PERIODIC_REVIEW \| MANUAL \| SANCTIONS_PROXIMITY \| PEP_IDENTIFIED
firstName	string	Required	User's first name
lastName	string	Required	User's last name
dateOfBirth	YYYY-MM-DD	Optional	Pre-fills EDD form
country	string	Required	Country (ISO 3166-1 alpha-2)

EDD can also be launched via the mobile SDK — pass mode: .edd and an authToken from your server session.

EDD Status

GET/integration/api/integration/edd/{eddId}/status

Response

{ "eddId": "edd_abc123", "status": "PENDING_REVIEW", "userId": "your-user-id", "openedAt": "2024-01-15T10:30:00Z", "reviewedAt": null, "outcome": null }

Poll this endpoint or subscribe to edd.status.changed webhooks. EDD reviews are completed by your compliance team in the VerityPro case management portal.

Process Transaction

Submit transactions to VerityPro's AML engine for real-time risk scoring. Each transaction is checked against velocity rules, sanctions screening, and ML-based anomaly detection. A risk decision is returned synchronously.

POST/integration/api/integration/transactions

Parameter	Type	Required	Description
vendorData	string	Required	Your internal user identifier
transactionType	enum	Required	TRANSFER \| DEPOSIT \| WITHDRAWAL \| PAYMENT \| EXCHANGE
amount	number	Required	Transaction amount (positive decimal)
currency	ISO 4217	Required	3-letter currency code, e.g. AUD, USD
sender.firstName	string	Required	Sender first name
sender.lastName	string	Required	Sender last name
sender.email	string	Optional	Sender email
sender.country	string	Required	Sender country (ISO 3166-1 alpha-2)
recipient.firstName	string	Required	Recipient first name
recipient.lastName	string	Required	Recipient last name
recipient.country	string	Required	Recipient country (ISO 3166-1 alpha-2)
paymentMethod	enum	Required	BANK_TRANSFER \| CARD \| CRYPTO \| CASH
transactionReference	string	Optional	Your reference number for reconciliation

Response

{ "decision": "PASS", "riskScore": 24, "riskLevel": "LOW", "transactionId": "txn_xyz789", "flags": [] }

Decision values: PASS | REVIEW | DECLINED. Treat REVIEW as a soft block — hold the transaction pending analyst review. DECLINED is a hard block.

Step-Up Biometric Authentication

Re-verify a returning user's identity using face liveness + face match against the template enrolled during KYC onboarding. Use this for risk-triggered moments — high-value transactions, new-device logins, suspicious activity — rather than full re-onboarding. The subject must have completed a liveness-verified KYC session with the BIOMETRIC module before step-up is available.

Authentication: x-api-key only (JWT is not accepted on step-up endpoints). The subjectId must exactly match the vendorData value used at KYC onboarding.

1 — Create a challenge

POST/kycintegration/api/v1/step-up/challenges

Parameter	Type	Required	Description
subjectId	string	Required	Must equal the vendorData used at KYC onboarding.
riskReason	string	Required	Why step-up was triggered, e.g. 'high_value_txn'.
channelOrigin	string	Optional	'mobile_ios' \| 'mobile_android' \| 'web'.

Returns challengeId (your primary reference, valid 300s, max 3 attempts) and a short-lived token to forward to the app as X-StepUp-Token. A 422 means the subject has no enrolled face — route to full KYC.

2 — Get AWS Rekognition credentials

POST/kycintegration/api/v1/step-up/challenges/{challengeId}/begin-liveness

Send x-api-key + X-StepUp-Token. Returns livenessSessionId, region, and short-lived AWS credentials — pass all of them to the AWS Amplify Face Liveness widget in your app. No VerityPro SDK screens are needed for step-up.

3 — Complete after AWS liveness

POST/kycintegration/api/v1/step-up/challenges/{challengeId}/complete

Parameter	Type	Required	Description
livenessSessionId	string	Required	The AWS Face Liveness session ID from step 2.
selfieImageB64	string	Required	Base64-encoded JPEG/PNG selfie captured by the AWS SDK.

Verdicts

verdict	Action
Passed	Identity confirmed — proceed with the action
ManualReview	Hold pending operator review; a webhook follows
Failed	Deny the action; retry available while attemptCount < 3
NoEnrolledTemplate	Subject has no enrolled face — route to full KYC

Webhook Event Types

VerityPro delivers events to your registered HTTPS endpoint. Configure the URL and secret in Settings → Integration → Webhooks.

Event	Trigger
kyc.completed	KYC session reached a terminal state
kyc.session.expired	KYC session timed out (60 min)
address.verified	Address verification completed
edd.status.changed	EDD case status changed
transaction.risk.flagged	Transaction flagged REVIEW by TM engine
transaction.blocked	Transaction blocked DECLINED by TM engine

Your endpoint must return HTTP 200 within 10 seconds. Failed deliveries are retried with exponential backoff for up to 24 hours.

Verify Webhook Signature

Every webhook request carries two headers: X-Veritypro-Signature, an HMAC-SHA512 signature, and X-Veritypro-Timestamp, the unix epoch seconds the payload was signed at. Always verify both before processing the payload.

The signature is computed as HMAC-SHA512(webhookSecret, "{timestamp}.{rawBody}") — the timestamp header value, a literal dot, then the raw request body bytes before JSON parsing. It is encoded as lowercase hex, 128 characters, with no prefix.

Sign the timestamped payload, not the body alone

The timestamp is part of the signed input. Computing the HMAC over the body by itself will never match. Reject any delivery whose timestamp is more than 5 minutes from your own clock in either direction — that bounds how long a captured request stays replayable, but it does not make deliveries unique, so still key your own processing on the event id.

Use raw body, not parsed JSON

JSON serialisation is not deterministic. Always compute the HMAC over the raw bytes received from the network, not over a re-serialised object.

Result Types

VerityOutcome

Value	Meaning
approved	All required modules passed. Customer is verified.
pendingManualReview	Requires analyst review — do not approve or reject automatically.
rejected	Verification failed. Check VerityErrorCode for reason.
cancelled	User exited the SDK before completing.
failed	Technical error. Check recoverable flag before re-launching.

VerityVerificationError

Parameter	Type	Required	Description
code	VerityErrorCode	Required	Named error code, e.g. DOCUMENT_EXPIRED
message	string	Required	Human-readable error description
recoverable	boolean	Required	True if re-launching the SDK may succeed
recommendedAction	string	Optional	UX copy to show the user

Error Codes

HTTP errors use standard status codes. The response body contains a typed error payload.

Status	Meaning
400	Bad Request — missing or invalid parameters
401	Unauthorized — API key missing or invalid
403	Forbidden — integration disabled or insufficient permissions
404	Not Found — session or resource does not exist
409	Conflict — duplicate request or resource already exists
422	Unprocessable — request is well-formed but semantically invalid
429	Rate Limited — slow down and retry after the Retry-After header
500	Internal Error — transient; safe to retry with backoff

Error response body

{ "error": "SESSION_NOT_FOUND", "message": "The session token is invalid or has expired.", "traceId": "req_abc123" }