BRIJ Tier 2 Partner Integration Guide

Overview

This guide describes how to integrate with BRIJ as a Tier 2 Partner using the full integration mode. In this mode, BRIJ handles the complete customer experience through an embedded widget, including initial KYC verification. Partners receive verified customer data and attestations only after explicit user consent, and can perform additional KYC if needed.

Key Differences from Tier 1

Benefits of Full Integration

• Reduced friction: Customers complete transactions without leaving the BRIJ interface
• Verified data: Receive KYC-verified customer data and attestations
• Compliance: BRIJ handles initial identity verification
• Flexibility: Add custom KYC requirements based on your compliance needs
• Full control: Manage orders through the Partner API

Prerequisites

• API Key: BRIJ will provide you with an API key for authentication
• Base URLs: Provide BRIJ with your JSON API base URLs for:
  • Quote endpoint
  • Create Order endpoint
  • Cancel Order endpoint
• Webhook URL: Provide a URL to receive webhooks (e.g., Data Shared notifications)
• Supported configurations: Define your supported countries, currencies, payment methods, and limits

Integration Architecture

The following diagram illustrates the high-level architecture of a Tier 2 integration:

Part 1: Sync Your Payment Options to BRIJ

Register your supported configurations with BRIJ by calling the SyncPaymentOptions endpoint.

See SyncPaymentOptions in API Reference for complete details.

This defines:

• Supported countries
• Available payment methods
• Cryptocurrency and fiat currency pairs
• Transaction limits (min/max amounts)
• Networks you support

Part 2: Configure Requirement Policy

Define compliance rules that determine what attestations or data are required from customers based on their nationality or residency country. This policy is evaluated after the customer selects your service, and they must satisfy all requirements before they can share data and initiate an order.

See SetRequirementPolicy in API Reference for complete details.

Example use cases:

• Require enhanced KYC for customers from specific regions
• Block transactions from restricted jurisdictions

Part 3: Implement Your Partner API

BRIJ will call your API endpoints to get quotes, create orders, and handle cancellations. You must implement three JSON API endpoints:

Required Endpoints

Verifying Request Signatures

All requests from BRIJ include a signed JWT in the X-BRIJ-Signature header. You should verify this signature to ensure requests originate from BRIJ.

See Signature Verification for implementation details.

Part 4: Handle Webhooks

BRIJ sends webhooks to notify you of important events. The primary webhook for Tier 2 integration is:

Data Shared by Customer

Sent when a customer explicitly shares their data and attestations with your organization.

See Data Shared by Customer for payload details.

Upon receiving this webhook:

1. Fetch customer data using GetCustomerDataById in API Reference
2. Fetch attestations using GetAttestationRecord in API Reference
3. Store the data for compliance and transaction processing

Part 5: Manage Orders via Partner API

Use the Partner API to retrieve and manage orders:

Order Lifecycle

Orders progress through the following statuses:

Use UpdateOrder in API Reference to:

• Mark funds as received (FUNDS_RECEIVED)
• Record payment submission (PAYMENT_SUBMITTED)
• Confirm payment completion (PAYMENT_PROCESSED)
• Report errors with reason codes (ERROR)

Part 6: Access Customer Data and Attestations

Retrieve customer information that has been shared with your organization:

Available Data Types

Customers can share various types of data. See Customer Data for all supported types including:

• Personal information (name, date of birth, nationality)
• Contact details (email, phone)
• Identity documents (passport, driver’s license)
• Financial information (bank account, tax ID)
• Compliance data (source of funds, occupation)

Available Attestation Types

BRIJ provides verification attestations for customer data. See Customer Attestations for all supported types including:

• VALIDATED_EMAIL - Verified email address
• VALIDATED_PHONE - Verified phone number
• VALIDATED_ID_DOCUMENT - Verified identity document
• LIVENESS_CHECK - Liveness verification completed
• AML_CHECK - Anti-money laundering check completed

Part 7: Additional KYC (Optional)

If you need additional verification beyond what BRIJ provides, you can request more data or attestations from customers:

Note: Adding requirements will prompt the customer to provide additional information through the BRIJ Widget before they can proceed with transactions.

Integration Flow

1. Initial Setup

1. BRIJ provides you with an API key
2. You provide BRIJ with your API endpoint URLs and webhook URL
3. You call SyncPaymentOptions to register your capabilities
4. You call SetRequirementPolicy to configure your compliance rules

2. Runtime Flow - Customer Onboarding

1. Customer starts onboarding through the BRIJ Widget
2. Customer completes initial KYC (BRIJ requirements)
3. Customer selects your service from available options
4. BRIJ calls your /quote endpoint to get live pricing
5. Customer completes additional KYC based on your requirement policy
6. Customer explicitly agrees to share their data with your organization
7. BRIJ sends a Data Shared webhook to your endpoint
8. You fetch customer data and attestations via the Partner API

3. Runtime Flow - Order Processing

1. Customer initiates the order
2. BRIJ calls your /create-order endpoint
3. You return the order ID, status (AWAITING_FUNDS), and deposit instructions
4. BRIJ displays the deposit instructions to the customer
5. While in AWAITING_FUNDS status, customer can cancel the order
6. If customer cancels, BRIJ calls your /cancel-order endpoint

4. Runtime Flow - Order Lifecycle Management

1. Customer sends funds according to the deposit instructions
2. You receive funds from the customer
3. You call UpdateOrder to mark as FUNDS_RECEIVED
4. You initiate the payout (crypto transfer or fiat payment)
5. You call UpdateOrder to mark as PAYMENT_SUBMITTED
6. Payment completes
7. You call UpdateOrder to mark as PAYMENT_PROCESSED

Best Practices

1. Sync Frequency

• Sync payment options whenever your capabilities change
• Full replacement mode means you don’t need to track deltas

2. Quote Caching

• Return fresh quotes on each request
• Consider short-lived quote IDs (e.g., 5-10 minutes)
• Include expiration times in rawResponse

3. Error Handling

• Return appropriate HTTP status codes
• Include descriptive error messages for debugging
• Provide customer-facing messages in customerFacingReason
• Log all requests for troubleshooting

4. Performance

• Quote endpoint should respond within 2 seconds
• Create order endpoint should respond within 5 seconds

5. Security

• Use HTTPS for all endpoints
• Verify the X-BRIJ-Signature header on all incoming requests
• Validate all input parameters
• Use the X-Forwarded-For header for fraud detection
• Handle customer data according to applicable privacy regulations

6. Customer Data Handling

• Only store data necessary for compliance and transaction processing
• Implement appropriate data retention policies
• Honor data deletion requests
• Protect sensitive data with encryption at rest

7. Order Updates

• Update order status promptly as the transaction progresses
• Include transaction IDs when marking payments as submitted
• Provide clear reasons when reporting errors

Testing

Test Credentials

Contact BRIJ support for test API keys and sandbox endpoint URLs.

Demo Environment

• Base URL: https://api-demo.brij.fi
• Use demo API keys for testing
• Test the full flow including webhooks and order lifecycle

Checklist

Before going live, verify:

• Payment options synced successfully
• Quote endpoint returns accurate pricing
• Create order endpoint handles all scenarios
• Cancel order endpoint works correctly
• Webhooks are received and processed
• Customer data and attestations can be fetched
• Order status updates work through the full lifecycle
• Error handling returns appropriate responses
• Signature verification is implemented