Deliver IBAN - Integration Guide

This guide explains how to deliver an IBAN to your users via the KYC process. The process includes: KYC iframe integration, IBAN creation via the CREATE_IBAN operation, and status tracking via userData.

📊 View Flow Diagram

1. Get KYC Iframe URL

The KYC iframe allows the user to complete their identity verification process.

Endpoint : POST /v1.2/auth/iframe

Headers :

Body (JSON) :

Request Example :

POST /v1.2/auth/iframe
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "language": "en"
}

Response (200 OK) :

{
  "chatbotURL": "https://kyc.foo.domain/flow",
  "sessionId": "a1b2c3d4e5"
}
💾 To Store :

Iframe Integration

Build the complete redirect URL by combining the received data:

const redirectUrl = `${chatbotURL}?session=${sessionId}&returnUrl=${encodeURIComponent(appUrl)}`;

Where:

Implementation Example :

// 1. Get iframe URL
const iframeResponse = await fetch('/v1.2/auth/iframe', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ language: 'en' })
});

const { chatbotURL, sessionId } = await iframeResponse.json();

// 2. Build redirect URL
const appUrl = window.location.origin + '/kyc-callback';
const redirectUrl = `${chatbotURL}?session=${sessionId}&returnUrl=${encodeURIComponent(appUrl)}`;

// 3. Redirect user to KYC iframe
window.location.href = redirectUrl;

2. Create IBAN via CREATE_IBAN Operation

Once KYC is completed, you must create the IBAN via a Safe operation. This operation signs a message declaring ownership of the Safe address.

Endpoint : POST /v1.2/safes/operations

Headers :

Body (JSON) :

MONERIUM_CREATE_IBAN Operation :

Request Example :

POST /v1.2/safes/operations
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "safeAddress": "0xd676c6188195372EC269E9C2cAf815C56436A679",
  "operations": [
    {
      "type": "MONERIUM_CREATE_IBAN"
    }
  ]
}

Response (200 OK) :

{
  "credentialRequestOptions": {
    "challenge": "<base64url_encoded_userOpHash>",
    "rpId": "foo.domain",
    "userVerification": "required"
  }
}
⚠️ Important : After receiving credentialRequestOptions, you must:
  1. Use navigator.credentials.get() with these options to obtain a credential
  2. Send a PUT /v1.2/safes/operations request with the credential to finalize IBAN creation

Finalize Creation (PUT)

Endpoint : PUT /v1.2/safes/operations

Body (JSON) :

Request Example :

PUT /v1.2/safes/operations
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "credential": {
    "id": "AVZs0qRCBSmfThZWu37g...",
    "rawId": "AVZs0qRCBSmfThZWu37g...",
    "type": "public-key",
    "response": {
      "authenticatorData": "SZYN5YgOjGh0NBcPZHZgW4/krrmihjLHmVzzuoMdl2MFAAAAAQ...",
      "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoi...",
      "signature": "MEUCIQC..."
    }
  }
}

3. Track KYC Status and IBAN via userData

Once KYC is completed and the CREATE_IBAN operation is executed, you can track the KYC status and retrieve the IBAN via userData.

Get userData

Endpoint : GET /v1.2/ibexsafe/userdata/external/{externalUserId}

Headers :

Request Example :

GET /v1.2/ibexsafe/userdata/external/{externalUserId}
Authorization: Bearer <access_token>

Response (200 OK) :

{
  "id": "user123",
  "ky": "2",
  "signers": [
    {
      "id": "signer123",
      "safes": [
        {
          "address": "0xd676c6188195372EC269E9C2cAf815C56436A679",
          "threshold": 1,
          "iban": {
            "chainId": 100,
            "iban": "FR76 1234 5678 9012 3456 7890 123",
            "bic": "CREDFRPP",
            "status": "VERIFIED"
          }
        }
      ]
    }
  ]
}
💾 To Store :

KYC States

The ky field in userData indicates the KYC process status. Possible values are:

Value Code Description
"0" NO_KYC No KYC
"1" LVL1_IN_PROGRESS Process started but not completed
"2" LVL1_SUBMITTED Process completed, documents submitted
"3" LVL1_ADDITIONAL_INFO_REQUESTED Additional information requested
"4" LVL1_REJECTED Rejected
"5" LVL1_ACCEPTED Accepted
"55" TEMPORARY_BLOCKED Temporarily blocked

IBAN Statuses

The iban.status field indicates the IBAN status:

4. Real-Time Tracking via WebSocket

You can also receive real-time notifications about KYC and IBAN changes via WebSocket.

WebSocket Message - KYC Update :

{
  "type": "user.ky.updated",
  "data": {
    "safeAddress": "0xd676c6188195372EC269E9C2cAf815C56436A679",
    "previousKyc": "1",
    "newKyc": "2",
    "updatedAt": "2025-08-01T07:36:04.083Z"
  },
  "timestamp": "2025-08-01T07:36:04.083Z"
}

WebSocket Message - IBAN Update :

{
  "type": "user.iban.updated",
  "data": {
    "safeAddress": "0xd676c6188195372EC269E9C2cAf815C56436A679",
    "iban": "FR76 1234 5678 9012 3456 7890 123",
    "previousState": "PENDING",
    "newState": "VERIFIED",
    "updatedAt": "2025-08-01T07:36:04.083Z"
  },
  "timestamp": "2025-08-01T07:36:04.083Z"
}
💡 Note : For more details on WebSocket integration, see the IBEx Safe documentation.

Complete Flow Summary

  1. Get KYC iframe URL : POST /v1.2/auth/iframe
  2. Redirect user to iframe : Build URL with chatbotURL, sessionId, and returnUrl
  3. Wait for user return : User completes KYC in the iframe
  4. Create IBAN : POST /v1.2/safes/operations with MONERIUM_CREATE_IBAN operation
  5. Finalize creation : PUT /v1.2/safes/operations with WebAuthn credential
  6. Track status : GET /v1.2/ibexsafe/userdata/external/{externalUserId} to check ky and iban
  7. Retrieve IBAN : Once iban.status = "VERIFIED", the IBAN is available in iban.iban

Technical Deep Dive - For AI Integration

This section provides detailed technical information for AI systems integrating the IBEX IBAN delivery flow, including architecture patterns, data models, and implementation details.

KYC Iframe Integration - Technical Details

POST /v1.2/auth/iframe

Iframe Redirect Flow:

MONERIUM_CREATE_IBAN Operation - Technical Details

POST /v1.2/safes/operations

PUT /v1.2/safes/operations/{userOpHash}

IBAN Status Tracking - Technical Details

Database Schema:

Iban {
  safeAddress: String (PK, composite with blockchainId)
  blockchainId: Int (PK, composite with safeAddress)
  provider: IbanProvider (MONERIUM)
  status: String (PENDING, VERIFIED, etc.)
  createdAt: DateTime
  updatedAt: DateTime
  Safe: Safe (relation)
}

Status Updates:

UserData Retrieval:

KYC Status Values - Technical Details

The ky field in userData represents KYC verification status:

KYC Status Flow:

WebSocket Real-Time Updates

KYC Status Updates:

IBAN Status Updates:

Complete Flow - Technical Sequence

  1. Get KYC iframe : POST /v1.2/auth/iframe → returns chatbotURL, sessionId
  2. Redirect user : Client redirects to iframe URL with sessionId and returnUrl
  3. User completes KYC : External KYC service processes verification
  4. KYC status updated : Upstream service updates userData.ky (poll or WebSocket)
  5. Create IBAN operation : POST /v1.2/safes/operations with MONERIUM_CREATE_IBAN
  6. Sign operation : PUT /v1.2/safes/operations/{userOpHash} with WebAuthn credential
  7. Operation executed : Bundler submits signed message to blockchain
  8. Notification sent : IBEX API notifies upstream service of signed message
  9. IBAN created : Upstream service creates IBAN and updates userData
  10. IBAN status updated : POST /recovery/iban updates Iban.status to VERIFIED
  11. Retrieve IBAN : GET /v1.2/ibexsafe/userdata/external/{externalUserId} returns IBAN details

Key Implementation Files

Error Handling

← Back to Main Guide