# 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

| Aspect                 | Tier 1                         | Tier 2 (Full Integration)                  |
| ---------------------- | ------------------------------ | ------------------------------------------ |
| Customer UI            | Partner's platform             | BRIJ Widget                                |
| KYC Handling           | Partner handles                | BRIJ handles initial KYC                   |
| Data Flow              | Customer redirected to partner | Partner receives data via API              |
| Order Creation         | Partner creates on redirect    | BRIJ calls partner's Create Order endpoint |
| Transaction Completion | On partner's platform          | Within BRIJ Widget                         |

### 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:

```mermaid
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 `SyncPaymentOptions` in [API Reference](/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](/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

| Endpoint     | Purpose                                           | Documentation                                                            |
| ------------ | ------------------------------------------------- | ------------------------------------------------------------------------ |
| Quote        | Returns live pricing for a transaction            | [Quote Request](/docs/webhooks-and-requests/quote-request)               |
| Create Order | Creates an order and returns deposit instructions | [Create Order Request](/docs/webhooks-and-requests/create-order-request) |
| Cancel Order | Cancels an existing order                         | [Cancel Order Request](/docs/webhooks-and-requests/cancel-order-request) |

### 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](/docs/webhooks-and-requests/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](/docs/webhooks-and-requests/data-shared-by-customer) for payload details.

Upon receiving this webhook:

1. Fetch customer data using `GetCustomerDataById` in [API Reference](/api-reference)
2. Fetch attestations using `GetAttestationRecord` in [API Reference](/api-reference)
3. Store the data for compliance and transaction processing

```mermaid
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:

| Endpoint          | Purpose                                    | Documentation                       |
| ----------------- | ------------------------------------------ | ----------------------------------- |
| Get Orders        | List orders with optional status filtering | [Get Orders](/api-reference)        |
| Get Order Details | Retrieve full details of a specific order  | [Get Order Details](/api-reference) |
| Update Order      | Progress orders through their lifecycle    | [Update Order](/api-reference)      |

### Order Lifecycle

Orders progress through the following statuses:

```mermaid
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 `UpdateOrder` in [API Reference](/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:

| Endpoint                | Purpose                                         | Documentation                             |
| ----------------------- | ----------------------------------------------- | ----------------------------------------- |
| Get Customer Data       | List all data shared by a customer              | [Get Customer Data](/api-reference)       |
| Get Customer Data by ID | Retrieve specific data record with full content | [Get Customer Data by ID](/api-reference) |
| Get Attestation Record  | Retrieve verification attestation details       | [Get Attestation Record](/api-reference)  |

### Available Data Types

Customers can share various types of data. See [Customer Data](/docs/reference/customer-data#data-types) 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](/docs/reference/customer-attestations#attestation-types) 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:

| Endpoint                    | Purpose                                | Documentation                                 |
| --------------------------- | -------------------------------------- | --------------------------------------------- |
| Add Customer Requirement    | Request additional data or attestation | [Add Customer Requirement](/api-reference)    |
| Remove Customer Requirement | Remove a previously added requirement  | [Remove Customer Requirement](/api-reference) |
| Add Customer Flag           | Flag a customer for internal tracking  | [Add Customer Flag](/api-reference)           |
| Remove Customer Flag        | Remove a customer flag                 | [Remove Customer Flag](/api-reference)        |

**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`

```mermaid
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