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:

sequenceDiagram
    participant Customer
    participant BRIJ Widget
    participant BRIJ
    participant Partner
    Note over Customer, Partner: Initial Setup
    Partner ->> BRIJ: Sync Payment Options
    Partner ->> BRIJ: Set Requirement Policy
    Note over Customer, Partner: Customer Flow
    Customer ->> BRIJ Widget: Starts onboarding
    BRIJ Widget ->> BRIJ: Begin KYC
    Customer ->> BRIJ Widget: Completes initial KYC (BRIJ requirements)
    BRIJ -->> BRIJ Widget: KYC complete
    Customer ->> BRIJ Widget: Selects partner service
    BRIJ ->> Partner: Quote Request
    Partner -->> BRIJ: Quote response
    BRIJ -->> BRIJ Widget: Display quote
    Customer ->> BRIJ Widget: Completes partner's additional KYC
    BRIJ -->> BRIJ Widget: All requirements satisfied
    Customer ->> BRIJ Widget: Agrees to share data with partner
    BRIJ ->> Partner: Data Shared Webhook
    Partner ->> BRIJ: Fetch customer data/attestations
    Customer ->> BRIJ Widget: Initiates order
    BRIJ ->> Partner: Create Order Request
    Partner -->> BRIJ: Order created (AWAITING_FUNDS)
    BRIJ -->> BRIJ Widget: Display deposit instructions
    Note over Customer, Partner: Order Lifecycle
    alt Customer cancels
        Customer ->> BRIJ Widget: Cancel order
        BRIJ ->> Partner: Cancel Order Request
        Partner -->> BRIJ: Order canceled
    else Customer sends funds
        Customer ->> Partner: Sends funds
        Partner ->> BRIJ: Update Order (status changes)
    end

Part 1: Sync Your Payment Options to BRIJ¶

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

See Syncing Payment Options 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 Set Requirement Policy 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 Get Customer Data by ID
2. Fetch attestations using Get Attestation Record
3. Store the data for compliance and transaction processing

sequenceDiagram
    participant BRIJ
    participant Partner
    BRIJ ->> Partner: Data Shared Webhook
    Note right of Partner: Payload includes customerId,<br/>customerDataIds, attestationIds
    Partner ->> BRIJ: GetCustomerDataById (for each data ID)
    BRIJ -->> Partner: Customer data (name, ID document, etc.)
    Partner ->> BRIJ: GetAttestationRecord (for each attestation ID)
    BRIJ -->> Partner: Attestation details (verification status)
    Note right of Partner: Store data for compliance

Part 5: Manage Orders via Partner API¶

Use the Partner API to retrieve and manage orders:

Order Lifecycle¶

Orders progress through the following statuses:

stateDiagram-v2
    [*] --> AWAITING_FUNDS: Order created
    AWAITING_FUNDS --> FUNDS_RECEIVED: Customer sends funds
    FUNDS_RECEIVED --> PAYMENT_SUBMITTED: Partner initiates payout
    PAYMENT_SUBMITTED --> PAYMENT_PROCESSED: Payout complete
    AWAITING_FUNDS --> CANCELED: Customer cancels
    AWAITING_FUNDS --> ERROR: Error occurs
    FUNDS_RECEIVED --> REFUNDING: Refund initiated
    REFUNDING --> REFUNDED: Refund complete
    FUNDS_RECEIVED --> IN_REVIEW: Compliance review
    IN_REVIEW --> FUNDS_RECEIVED: Review passed
    IN_REVIEW --> ERROR: Review failed

Use the Update Order endpoint 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:

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

sequenceDiagram
    participant Customer
    participant BRIJ Widget
    participant BRIJ
    participant Partner
    Note over Customer, Partner: Order Creation
    Customer ->> BRIJ Widget: Initiates order
    BRIJ Widget ->> BRIJ: Create order request
    BRIJ ->> Partner: Create Order Request
    Partner -->> BRIJ: {externalOrderId, status: AWAITING_FUNDS, depositInstructions}
    BRIJ -->> BRIJ Widget: Display deposit instructions
    Note over Customer, Partner: Order Cancellation (optional)
    alt Customer cancels while AWAITING_FUNDS
        Customer ->> BRIJ Widget: Cancel order
        BRIJ ->> Partner: Cancel Order Request
        Partner -->> BRIJ: Order canceled
        BRIJ -->> BRIJ Widget: Show cancellation confirmation
    end

    Note over Customer, Partner: Order Fulfillment
    Customer ->> Partner: Sends funds (bank transfer/crypto)
    Partner ->> BRIJ: UpdateOrder (FUNDS_RECEIVED)
    BRIJ -->> BRIJ Widget: Update status
    Partner ->> Partner: Process payout
    Partner ->> BRIJ: UpdateOrder (PAYMENT_SUBMITTED)
    Partner ->> BRIJ: UpdateOrder (PAYMENT_PROCESSED)
    BRIJ -->> BRIJ Widget: Transaction complete
    BRIJ Widget -->> Customer: Success confirmation

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