> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsa.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingest Bank Accounts, Blockchain Wallets & Payment Accounts

> Step-by-step guide for ingesting bank accounts, blockchain wallets, and payment accounts into Corsa for compliance monitoring.

This guide walks you through ingesting financial accounts - **Bank Accounts**, **Blockchain Wallets**, and **Payment Accounts** - and associating them with clients in Corsa.

Full API endpoint details are available in the [API Reference](https://api.corsa.finance/api-spec.json) (requires API credentials).

<Note>Before ingesting accounts and wallets, make sure the related clients have already been ingested. See the [Ingesting Clients](/api/ingesting-clients) guide.</Note>

***

## Step 1: Create Bank Accounts

**Endpoint:** `POST /v1/bank-accounts`

Create a bank account record and optionally associate it with clients in a single request.

<CodeGroup>
  ```json REST API theme={null}
  POST /v1/bank-accounts?upsert=true
  Content-Type: application/json

  {
    "referenceId": "REF-BA-001",
    "accountNumber": "1234567890",
    "routingNumber": "021000021",
    "bankName": "Chase Bank",
    "accountHolderName": "John Doe",
    "accountType": "checking",
    "currency": "USD",
    "status": "ACTIVE",
    "balanceInCurrency": 15000.50,
    "countries": ["USA"],
    "associatedClients": [
      {
        "clientId": "client-uuid-123",
        "name": "Primary Account"
      }
    ]
  }
  ```

  ```typescript Javascript theme={null}
  const bankAccount = await corsa.bankAccounts.createBankAccount(
    {
      referenceId: "REF-BA-001",
      accountNumber: "1234567890",
      routingNumber: "021000021",
      bankName: "Chase Bank",
      accountHolderName: "John Doe",
      accountType: "checking",
      currency: "USD",
      status: "ACTIVE",
      balanceInCurrency: 15000.5,
      countries: ["USA"],
      associatedClients: [
        {
          clientId: "client-uuid-123",
          name: "Primary Account",
        },
      ],
    },
    true // upsert
  );
  ```

  ```python Python theme={null}
  from corsa_sdk.api.bank_accounts.create_bank_account import _get_kwargs
  from corsa_sdk.models.create_bank_account_dto import CreateBankAccountDto

  resp = http.request(**_get_kwargs(
      body=CreateBankAccountDto(
          reference_id="REF-BA-001",
          account_number="1234567890",
          routing_number="021000021",
          bank_name="Chase Bank",
          account_holder_name="John Doe",
          account_type="checking",
          currency="USD",
          status="ACTIVE",
          balance_in_currency=15000.50,
          countries=["USA"],
          associated_clients=[{"clientId": "client-uuid-123", "name": "Primary Account"}],
      ),
      upsert=True,
  ))
  bank_account = resp.json()
  ```
</CodeGroup>

### Key Fields

| Field               | Required | Description                                           |
| ------------------- | -------- | ----------------------------------------------------- |
| `accountNumber`     | Yes      | Unique national bank account number                   |
| `referenceId`       | No       | Your external reference ID (used for upsert matching) |
| `status`            | No       | `ACTIVE`, `INACTIVE`, or `CLOSED`                     |
| `currency`          | No       | ISO 4217 currency code (e.g., `USD`, `EUR`)           |
| `countries`         | No       | ISO 3166-1 alpha-3 country codes (max 20)             |
| `associatedClients` | No       | Clients to link at creation time (max 50)             |
| `riskHistory`       | No       | Historical risk assessments                           |
| `customFields`      | No       | Custom key-value data                                 |

The `upsert=true` query parameter will update an existing bank account if matched by `referenceId` or `accountNumber`.

***

## Step 2: Associate Bank Accounts with Clients

**Endpoint:** `POST /v1/bank-accounts/{bankAccountId}/clients`

If you didn't associate clients at creation time, or need to add more, use this endpoint.

<CodeGroup>
  ```json REST API theme={null}
  POST /v1/bank-accounts/bank-account-uuid/clients
  Content-Type: application/json

  {
    "clients": [
      {
        "clientId": "client-uuid-456",
        "name": "Joint Account Holder"
      }
    ]
  }
  ```

  ```typescript Javascript theme={null}
  const updated = await corsa.bankAccounts.associateBankAccountWithClients(
    "bank-account-uuid",
    {
      clients: [
        {
          clientId: "client-uuid-456",
          name: "Joint Account Holder",
        },
      ],
    }
  );
  ```

  ```python Python theme={null}
  from corsa_sdk.api.bank_accounts.associate_bank_account_with_clients import _get_kwargs
  from corsa_sdk.models.associate_bank_account_with_client_dto import AssociateBankAccountWithClientDto

  resp = http.request(**_get_kwargs(
      bank_account_id="bank-account-uuid",
      body=AssociateBankAccountWithClientDto(
          clients=[{"clientId": "client-uuid-456", "name": "Joint Account Holder"}],
      ),
  ))
  updated = resp.json()
  ```
</CodeGroup>

***

## Step 3: Create Blockchain Wallets

**Endpoint:** `POST /v1/blockchain-wallets`

Create a blockchain wallet record and optionally associate it with clients.

<CodeGroup>
  ```json REST API theme={null}
  POST /v1/blockchain-wallets?upsert=true
  Content-Type: application/json

  {
    "referenceId": "REF-WALLET-001",
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "chain": "ethereum",
    "screeningDate": "2024-01-15T10:30:00.000Z",
    "associatedClients": [
      {
        "clientId": "client-uuid-123",
        "name": "Primary Wallet"
      }
    ]
  }
  ```

  ```typescript Javascript theme={null}
  const wallet = await corsa.blockchainWallets.createBlockchainWallet(
    {
      referenceId: "REF-WALLET-001",
      address: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      chain: "ethereum",
      screeningDate: "2024-01-15T10:30:00.000Z",
      associatedClients: [
        {
          clientId: "client-uuid-123",
          name: "Primary Wallet",
        },
      ],
    },
    true // upsert
  );
  ```

  ```python Python theme={null}
  from corsa_sdk.api.blockchain_wallets.create_blockchain_wallet import _get_kwargs
  from corsa_sdk.models.create_blockchain_wallet_dto import CreateBlockchainWalletDto

  resp = http.request(**_get_kwargs(
      body=CreateBlockchainWalletDto(
          reference_id="REF-WALLET-001",
          address="0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
          chain="ethereum",
          screening_date="2024-01-15T10:30:00.000Z",
          associated_clients=[{"clientId": "client-uuid-123", "name": "Primary Wallet"}],
      ),
      upsert=True,
  ))
  wallet = resp.json()
  ```
</CodeGroup>

### Key Fields

| Field               | Required | Description                                                 |
| ------------------- | -------- | ----------------------------------------------------------- |
| `address`           | Yes      | Wallet address on the blockchain (26-100 chars)             |
| `referenceId`       | No       | Your external reference ID (used for upsert matching)       |
| `chain`             | No       | Blockchain network identifier (e.g., `ethereum`, `bitcoin`) |
| `screeningDate`     | No       | Date the wallet was last screened                           |
| `associatedClients` | No       | Clients to link at creation time (max 50)                   |
| `riskHistory`       | No       | Historical risk assessments                                 |
| `integrations`      | No       | Third-party integration data (e.g., Chainalysis)            |
| `customFields`      | No       | Custom key-value data                                       |

The `upsert=true` query parameter will update an existing wallet if matched by `referenceId` or `address`.

***

## Step 4: Associate Blockchain Wallets with Clients

**Endpoint:** `POST /v1/blockchain-wallets/{blockchainWalletId}/clients`

Add client associations to an existing blockchain wallet.

<CodeGroup>
  ```json REST API theme={null}
  POST /v1/blockchain-wallets/wallet-uuid/clients
  Content-Type: application/json

  {
    "associatedClients": [
      {
        "clientId": "client-uuid-789",
        "name": "Trading Wallet"
      }
    ]
  }
  ```

  ```typescript Javascript theme={null}
  const updated = await corsa.blockchainWallets.associateBlockchainWalletWithClients(
    "wallet-uuid",
    {
      associatedClients: [
        {
          clientId: "client-uuid-789",
          name: "Trading Wallet",
        },
      ],
    }
  );
  ```

  ```python Python theme={null}
  from corsa_sdk.api.blockchain_wallets.associate_blockchain_wallet_with_clients import _get_kwargs
  from corsa_sdk.models.associate_blockchain_wallet_with_client_dto import AssociateBlockchainWalletWithClientDto

  resp = http.request(**_get_kwargs(
      blockchain_wallet_id="wallet-uuid",
      body=AssociateBlockchainWalletWithClientDto(
          associated_clients=[{"clientId": "client-uuid-789", "name": "Trading Wallet"}],
      ),
  ))
  updated = resp.json()
  ```
</CodeGroup>

***

## Step 5: Create Payment Accounts

**Endpoint:** `POST /v1/payment-accounts`

Payment accounts represent alternative payment identifiers used in emerging market payment rails - such as PIX keys (Brazil), CLABE numbers (Mexico), mobile money accounts, or internal account identifiers. Create a payment account and optionally associate it with clients.

<CodeGroup>
  ```json REST API theme={null}
  POST /v1/payment-accounts?upsert=true
  Content-Type: application/json

  {
    "referenceId": "REF-PA-001",
    "identifier": "+55 11 91234-5678",
    "identifierType": "MOBILE_MONEY",
    "accountHolderName": "Maria Silva",
    "currency": "BRL",
    "countries": ["BRA"],
    "associatedClients": [
      {
        "clientId": "client-uuid-123",
        "name": "Primary Payment Account"
      }
    ]
  }
  ```

  ```typescript Javascript theme={null}
  const paymentAccount = await corsa.paymentAccounts.createPaymentAccount(
    {
      referenceId: "REF-PA-001",
      identifier: "+55 11 91234-5678",
      identifierType: "MOBILE_MONEY",
      accountHolderName: "Maria Silva",
      currency: "BRL",
      countries: ["BRA"],
      associatedClients: [
        {
          clientId: "client-uuid-123",
          name: "Primary Payment Account",
        },
      ],
    },
    true // upsert
  );
  ```

  ```python Python theme={null}
  from corsa_sdk.api.payment_accounts.create_payment_account import _get_kwargs
  from corsa_sdk.models.create_payment_account_dto import CreatePaymentAccountDto

  resp = http.request(**_get_kwargs(
      body=CreatePaymentAccountDto(
          reference_id="REF-PA-001",
          identifier="+55 11 91234-5678",
          identifier_type="MOBILE_MONEY",
          account_holder_name="Maria Silva",
          currency="BRL",
          countries=["BRA"],
          associated_clients=[{"clientId": "client-uuid-123", "name": "Primary Payment Account"}],
      ),
      upsert=True,
  ))
  payment_account = resp.json()
  ```
</CodeGroup>

### Key Fields

| Field               | Required | Description                                                                                 |
| ------------------- | -------- | ------------------------------------------------------------------------------------------- |
| `identifier`        | Yes      | Primary identifier for the payment account (e.g., PIX key, mobile number, CLABE)            |
| `referenceId`       | No       | Your external reference ID (used for upsert matching)                                       |
| `identifierType`    | No       | Type of identifier: `MOBILE_MONEY`, `PIX`, `CLABE`, `INTERNAL`, `CREDIT_CARD`, `DEBIT_CARD` |
| `routingCode`       | No       | Routing or network code for the payment method                                              |
| `currency`          | No       | ISO 4217 currency code (e.g., `BRL`, `MXN`, `USD`)                                          |
| `countries`         | No       | ISO 3166-1 alpha-3 country codes (max 20)                                                   |
| `associatedClients` | No       | Clients to link at creation time (max 50)                                                   |
| `riskHistory`       | No       | Historical risk assessments                                                                 |
| `customFields`      | No       | Custom key-value data                                                                       |

The `upsert=true` query parameter will update an existing payment account if matched by `referenceId` or `identifier`.

***

## Step 6: Associate Payment Accounts with Clients

**Endpoint:** `POST /v1/payment-accounts/{paymentAccountId}/clients`

Add client associations to an existing payment account.

<CodeGroup>
  ```json REST API theme={null}
  POST /v1/payment-accounts/payment-account-uuid/clients
  Content-Type: application/json

  {
    "clients": [
      {
        "clientId": "client-uuid-456",
        "name": "Secondary PIX Holder"
      }
    ]
  }
  ```

  ```typescript Javascript theme={null}
  const updated = await corsa.paymentAccounts.associatePaymentAccountWithClients(
    "payment-account-uuid",
    {
      clients: [
        {
          clientId: "client-uuid-456",
          name: "Secondary PIX Holder",
        },
      ],
    }
  );
  ```

  ```python Python theme={null}
  from corsa_sdk.api.payment_accounts.associate_payment_account_with_clients import _get_kwargs
  from corsa_sdk.models.associate_payment_account_with_client_dto import AssociatePaymentAccountWithClientDto

  resp = http.request(**_get_kwargs(
      payment_account_id="payment-account-uuid",
      body=AssociatePaymentAccountWithClientDto(
          clients=[{"clientId": "client-uuid-456", "name": "Secondary PIX Holder"}],
      ),
  ))
  updated = resp.json()
  ```
</CodeGroup>

***

## What's Next?

<CardGroup cols={2}>
  <Card title="Ingest Operations" icon="arrow-right-arrow-left" href="/api/ingesting-operations">
    Ingest deposits, withdrawals, trades, and transfers for your clients.
  </Card>

  <Card title="Ingest Sessions" icon="fingerprint" href="/api/ingesting-sessions">
    Track client sessions with device fingerprinting.
  </Card>
</CardGroup>