Ingest Bank Accounts, Blockchain Wallets & Payment Accounts

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 (requires API credentials).

Before ingesting accounts and wallets, make sure the related clients have already been ingested. See the Ingesting Clients guide.

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.

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"
    }
  ]
}

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
);

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()

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.

POST /v1/bank-accounts/bank-account-uuid/clients
Content-Type: application/json

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

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

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()

Step 3: Create Blockchain Wallets

Endpoint: POST /v1/blockchain-wallets Create a blockchain wallet record and optionally associate it with clients.

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"
    }
  ]
}

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
);

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()

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.

POST /v1/blockchain-wallets/wallet-uuid/clients
Content-Type: application/json

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

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

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()

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.

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"
    }
  ]
}

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
);

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()

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.

POST /v1/payment-accounts/payment-account-uuid/clients
Content-Type: application/json

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

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

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()

Data Ingestion

Ingest Bank Accounts, Blockchain Wallets & Payment Accounts

Step 1: Create Bank Accounts

Key Fields

Step 2: Associate Bank Accounts with Clients

Step 3: Create Blockchain Wallets

Key Fields

Step 4: Associate Blockchain Wallets with Clients

Step 5: Create Payment Accounts

Key Fields

Step 6: Associate Payment Accounts with Clients

What’s Next?

Ingest Operations

Ingest Sessions

​Step 1: Create Bank Accounts

​Key Fields

​Step 2: Associate Bank Accounts with Clients

​Step 3: Create Blockchain Wallets

​Key Fields

​Step 4: Associate Blockchain Wallets with Clients

​Step 5: Create Payment Accounts

​Key Fields

​Step 6: Associate Payment Accounts with Clients

​What’s Next?

Ingest Operations

Ingest Sessions

Step 1: Create Bank Accounts

Key Fields

Step 2: Associate Bank Accounts with Clients

Step 3: Create Blockchain Wallets

Key Fields

Step 4: Associate Blockchain Wallets with Clients

Step 5: Create Payment Accounts

Key Fields

Step 6: Associate Payment Accounts with Clients

What’s Next?