KYC Guide

Overview

Welcome to the detailed documentation for the Know Your Customer (KYC) process for our cryptocurrency platform. Before making any transactions, it is essential to complete the KYC verification process to comply with regulations and ensure the security of all users. This guide provides a comprehensive overview of workflows, account statuses, and the steps required to integrate and operate on our platform.

First, create an individual account using Create Blockwyre Account. For business account verification, please refer to the KYB Guide.

KYC Process Overview
Account Statuses
KYC Verification Statuses
KYC Process Flow
Platform Integration
Webhook Events
Document Requirements
Testing
Final Considerations

KYC Process Overview

The KYC process is a standard procedure to verify user identity and prevent fraudulent activities, including Anti-Money Laundering (AML). When integrating our platform, it is crucial to understand and follow this process to ensure regulatory compliance and transaction security.

Account Statuses

After KYC verification is complete, accounts transition through the following statuses:

pending: Initial state when an account is created. The account is waiting for KYC data submission.
active: The account has been verified and approved. Users can perform transactions.
paused: The account requires additional information or action from the user.
closed: The account has been closed due to rejection or other reasons.

Note: Account status is updated based on KYC verification results. See KYC Verification Statuses for the verification process states.

KYC Verification Statuses

During the KYC verification process, the verification goes through these statuses:

pending: Initial state when KYC data is submitted.
in_review: The KYC data is undergoing review by the provider.
approved: The KYC verification has been successful.
needs_update: Additional information is required from the user.
rejected: The KYC verification has been rejected due to risk or non-compliance reasons.

KYC Process Flow

The KYC process consists of several key steps that change the verification status based on progress and results.

4.1. Account Creation

Action: As a merchant, you use the account creation endpoint to register a new user.
Resulting State: The account is created with the initial state pending.

4.2. Submitting KYC Data

Action: The user's KYC data is sent to the provider for verification.
Resulting State: The verification changes to in_review while the review is underway.

4.3. Review and Approval

Action: The KYC provider reviews the provided information.
Resulting State:
- If verification is successful, the status changes to approved.
- The user can now perform transactions on the platform.

4.4. Request for Additional Information

If the provider requires additional information, the process is as follows:

Option 1: User Link

Action: A verification link is generated by the platform and returned in the response of the KYC submission endpoint (verificationUrl). You must provide this link to the end-user.
User: Accesses the link and provides the required information (facial recognition, identity documents, proof of address, etc.).
Resulting State: Once the information is submitted, the status goes back to in_review.

Option 2: Sending Documents to Support

Action: A list of necessary documents is provided.
User: Sends the documents to the support team via email.
Support: Manually provides the information to the provider.
Resulting State: The verification changes to in_review after receiving the documents.

4.5. KYC Process Result

Approval:
- Status: approved
- Action: The user can fully utilize the platform.
Rejection:
- Status: rejected
- Reasons: Fraud risk, AML, or other non-compliance issues.
- Action: The user must contact the support team for more information. No actions can be performed on the account until the status is resolved.

Platform Integration

To integrate our platform into your system, follow the detailed instructions below.

5.1. Endpoint for Submitting KYC Data

Individual Banking Verification:

Endpoint: POST /api/v2/kyc/banking-verification/individual

Authentication:

Bearer token (JWT) required
Permissions: KYC management permissions

Required Parameters:

accountId: Unique ID of the created account (UUID).
dateOfBirth: Date of birth of the user (ISO 8601 format: YYYY-MM-DD).
phone: Phone number of the user (E.164 format, including country code).
address: Address of the user.
documentId: Identification document for the user.

Each address object must contain:

address1: First line of the address (required, max 255 characters).
address2: Second line of the address (optional, max 255 characters).
city: City of the address (required, max 100 characters).
state: State of the address (required, max 100 characters).
postalCode: Postal code of the address (required, validated against country).
country: Country of the address (required, ISO 3166-1 alpha-2).

The documentId object must contain:

idNumber: Identification document number (required, 2-20 characters).
idDocumentType: Type of document (required, e.g., passport, national_id, driver_license).
idIssueDate: Issue date (optional, ISO 8601 format: YYYY-MM-DD).
idExpiryDate: Expiration date (optional, ISO 8601 format: YYYY-MM-DD).
idCountryOfIssue: Country of issuance (optional, ISO 3166-1 alpha-2).
nationality: Nationality of the user (optional, ISO 3166-1 alpha-2).

Successful Response:

{
  "accountId": "019f1234-5678-90ab-cdef-1234567890ab",
  "verificationUrl": "https://verification.blockwyre.com/v2/verification/..."
}

Note: The verificationUrl is provided for users to complete additional verification steps if required. All process events will be sent via webhooks.

5.2. Checking KYC Status

Endpoint: GET /api/v2/kyc/banking-verification/individual/{accountId}

Authentication:

Bearer token (JWT) required

Path Parameters:

accountId: Unique ID of the account (UUID).

Response:

{
  "accountId": "019f1234-5678-90ab-cdef-1234567890ab",
  "status": "in_review",
  "verificationUrl": "https://verification.blockwyre.com/v2/verification/...",
  "statusReason": "",
  "phone": "+12025551234",
  "dateOfBirth": "1990-01-15",
  "nationality": "US",
  "documentId": {
    "idNumber": "AB1234567",
    "idDocumentType": "passport",
    "idIssueDate": "2020-01-01",
    "idExpiryDate": "2030-01-01",
    "idCountryOfIssue": "US",
    "nationality": "US"
  },
  "address": {
    "address1": "123 Main St",
    "address2": "",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US"
  },
  "eventHistory": [
    {
      "status": "pending",
      "date": "2026-02-16T00:00:00Z"
    },
    {
      "status": "in_review",
      "date": "2026-02-16T01:00:00Z"
    }
  ],
  "createdAt": "2026-02-16T00:00:00Z",
  "updatedAt": "2026-02-16T12:00:00Z"
}

Actions based on Status:

pending: Waiting for KYC data submission.
in_review: No action required; the process is underway.
needs_update: Notify the user to provide additional information via the verification link.
approved: Allow the user to perform transactions.
rejected: Inform the user and provide contact details for support.

5.3. Request Verification Review

When a user's KYC status is needs_update and the user has provided the additional information, you can request a re-verification review from the provider.

Endpoint: POST /api/v2/kyc/banking-verification/individual/{accountId}/request-verification

Authentication:

Bearer token (JWT) required

Path Parameters:

accountId: Unique ID of the account (UUID).

Response:

{
  "accountId": "019f1234-5678-90ab-cdef-1234567890ab",
  "verificationUrl": "https://verification.blockwyre.com/v2/verification/..."
}

5.3.1 Submit External Verification

If the user's identity has already been verified by an external provider (e.g. Jumio, Onfido), you can submit the verification data directly without going through the default Veriff flow.

Endpoint: POST /api/v2/kyc/banking-verification/individual/{accountId}/submit-external-verification

Authentication:

Bearer token (JWT) required

Content Type: multipart/form-data

Path Parameters:

accountId: Unique ID of the account (UUID).

Required Parameters:

face: Selfie image file of the user.
documentFront: Front of the ID document file.
raw: Raw verification JSON from the external provider (must be valid JSON).
provider: Source provider name (e.g. jumio, onfido).

Optional Parameters:

documentBack: Back of the ID document file.

Prerequisites:

The banking verification data must be submitted first.
The account must not already be approved or in_review.

Status Change: The verification status changes directly to approved.

Response: Returns the banking verification status (same format as 5.2 Checking KYC Status response) with status approved.

Error Responses:

400 Bad Request: Invalid raw JSON
409 Conflict: Account already in approved or in_review status

5.4. Card Verification

For card-related KYC verification, the following endpoints are available:

Submit Card Verification

Endpoint: POST /api/v2/kyc/card-verification

Authentication:

Bearer token (JWT) required

Required Parameters:

accountId: Unique ID of the created account (UUID).
dateOfBirth: Date of birth of the user (ISO 8601 format: YYYY-MM-DD).
phone: Phone number of the user (E.164 format, including country code).
nationality: Nationality of the user (ISO 3166-1 alpha-2).
address: Address of the user (same format as banking verification).

Response:

{
  "accountId": "019f1234-5678-90ab-cdef-1234567890ab",
  "verificationLink": "https://verification.blockwyre.com/v2/verification/..."
}

Get Card Verification Status

Endpoint: GET /api/v2/kyc/card-verification/{accountId}

Authentication:

Bearer token (JWT) required

Path Parameters:

accountId: Unique ID of the account (UUID).

Response:

{
  "accountId": "019f1234-5678-90ab-cdef-1234567890ab",
  "status": "in_review",
  "statusReason": "",
  "email": "john@example.com",
  "firstName": "John",
  "lastName": "Wick",
  "dateOfBirth": "1990-01-15",
  "phone": "+12025551234",
  "nationality": "US",
  "address": {
    "address1": "123 Main St",
    "address2": "",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US"
  },
  "eventHistory": [],
  "createdAt": "2026-02-16T00:00:00Z",
  "updatedAt": "2026-02-16T12:00:00Z"
}

Request Card Verification from Approved Banking KYC

If a user already has an approved banking KYC, you can request a card verification based on that data.

Endpoint: POST /api/v2/kyc/card-verification/{accountId}/request-verification

Authentication:

Bearer token (JWT) required

Path Parameters:

accountId: Unique ID of the account (UUID).

Response: Returns the card verification status (same format as GET card verification status).

5.5. Communication with End Users

Maintaining clear communication with users is essential:

Status Notifications: Inform users when their verification status changes. You will receive webhook notifications for all status changes.
Clear Instructions: Provide detailed guides for submitting additional information if needed. Use the verificationUrl provided in the response.
Support: Provide support channels to resolve questions or issues.

Webhook Events

BlockWyre sends webhooks for all KYC process events. Configure webhook targets to receive real-time notifications.

KYC Events

The following webhook events are sent during the KYC process:

Event Type	Description
`kyc_status_updated`	KYC verification status has changed
`kyc_needs_update`	Additional information is required
`kyc_verification_submitted`	KYC verification has been submitted
`kyc_verification_signed`	User has signed terms and conditions
`kyc_document_upload_received`	Document upload event received from provider
`kyc_document_uploaded`	Documents have been uploaded successfully
`kyc_verification_completed`	KYC verification process is complete

Webhook Configuration

For complete webhook documentation including:

How to configure webhook targets
Signature verification
Payload structure and examples
Best practices and troubleshooting

Please see the Webhooks Guide.

Example Webhook Payload

{
  "webhookId": "019f1234-5678-90ab-cdef-1234567890ab",
  "type": "kyc_status_updated",
  "accountId": "019f9876-5432-10fe-dcba-0987654321fe",
  "timestamp": "2026-02-16T12:00:00Z",
  "details": {
    "kycId": "019faaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "accountId": "019f9876-5432-10fe-dcba-0987654321fe",
    "status": "approved",
    "previousStatus": "in_review",
    "kycType": "banking"
  },
  "systemNotes": "KYC status updated"
}

Document Requirements

Supported Document Types

The following document types are accepted for KYC verification:

passport: Passport
driver_license: Driver's license
national_id: National identity card
ssn: Social Security Number (US)
itin: Individual Taxpayer Identification Number (US)
ein: Employer Identification Number (US)
other: Other valid government-issued identification

Document Guidelines

Formats: Documents should be clear, legible images or PDFs
Size Limit: Maximum 10MB per request
Validity: All documents must be current and not expired
Country Codes: Use ISO 3166-1 alpha-2 format for country codes
Date Format: Use ISO 8601 format (YYYY-MM-DD) for all dates

Testing

Sandbox Environment

BlockWyre provides a sandbox environment for testing KYC flows without affecting production data.

Simulator UI: You can test the complete verification flow using the simulator interface at:

https://sandbox.blockwyre.com/v2/verification/simulator/{sessionId}

Test Scenarios: The simulator supports the following test outcomes:

approved: Verification approved
declined: Verification declined
resubmission_requested: Additional information required

Testing Best Practices

Use sandbox environment for all testing
Test all verification statuses and outcomes
Verify webhook delivery for each status change
Test error handling for rejected verifications
Validate verification link expiration handling

Final Considerations

Regulatory Compliance

Regulations: Ensure compliance with all local and international regulations related to KYC and AML.
Data Protection: All user data is encrypted and stored securely in compliance with data protection regulations.
Retention: Verification data is retained according to regulatory requirements.

Data Security

Encryption: All sensitive data is encrypted at rest and in transit.
Access Control: Access to KYC data is strictly controlled and logged.
Storage: Documents are stored in private, secure storage with appropriate access controls.

Updates and Changes

Provider Changes: Stay updated with potential changes in the verification process or additional requirements from the KYC provider.
API Updates: Monitor for API version updates and new features.
Webhook Events: New webhook events may be added as the platform evolves.

Support

If you need assistance or have questions about the KYC process:

Email: support@blockwyre.com

Support and Resources

If you need assistance or have any questions, our support team is here to help. You can contact our support team at support@blockwyre.com.

Stay Updated

Stay up-to-date with the latest news, updates, and features from BlockWyre by following us on social media:

Instagram: BlockWyre Instagram
Twitter: BlockWyre Twitter
Facebook: BlockWyre Facebook
LinkedIn: BlockWyre LinkedIn

We are excited to have you on board and look forward to seeing how you leverage BlockWyre's powerful tools to enhance your financial operations. Happy integrating!

Overview​

Table of Contents​

KYC Process Overview​

Account Statuses​

KYC Verification Statuses​

KYC Process Flow​

4.1. Account Creation​

4.2. Submitting KYC Data​

4.3. Review and Approval​

4.4. Request for Additional Information​

Option 1: User Link​

Option 2: Sending Documents to Support​

4.5. KYC Process Result​

Platform Integration​

5.1. Endpoint for Submitting KYC Data​

5.2. Checking KYC Status​

5.3. Request Verification Review​

5.3.1 Submit External Verification​

5.4. Card Verification​

Submit Card Verification​

Get Card Verification Status​

Request Card Verification from Approved Banking KYC​

5.5. Communication with End Users​

Webhook Events​

KYC Events​

Webhook Configuration​

Example Webhook Payload​

Document Requirements​

Supported Document Types​

Document Guidelines​

Testing​

Sandbox Environment​

Testing Best Practices​

Final Considerations​

Regulatory Compliance​

Data Security​

Updates and Changes​

Support​

Support and Resources​

Stay Updated​

Overview

Table of Contents

KYC Process Overview

Account Statuses

KYC Verification Statuses

KYC Process Flow

4.1. Account Creation

4.2. Submitting KYC Data

4.3. Review and Approval

4.4. Request for Additional Information

Option 1: User Link

Option 2: Sending Documents to Support

4.5. KYC Process Result

Platform Integration

5.1. Endpoint for Submitting KYC Data

5.2. Checking KYC Status

5.3. Request Verification Review

5.3.1 Submit External Verification

5.4. Card Verification

Submit Card Verification

Get Card Verification Status

Request Card Verification from Approved Banking KYC

5.5. Communication with End Users

Webhook Events

KYC Events

Webhook Configuration

Example Webhook Payload

Document Requirements

Supported Document Types

Document Guidelines

Testing

Sandbox Environment

Testing Best Practices

Final Considerations

Regulatory Compliance

Data Security

Updates and Changes

Support

Support and Resources

Stay Updated