Console Cards for Integrators and Vendors

Reach out to us to get access

Getting Started

Prerequisites

Grant dashboard access to [email protected] for Rain and Sumsub platforms with developer-level privileges. This access excludes sensitive user data but enables webhook configuration management and case-specific debugging capabilities.
Share Rain and Sumsub API key via email to [email protected]

Once done, please get in touch with the team to get the following details

For Integrators who wish to offer their cards to users, make sure you have the following

Tenant ID
API Key
Solver Configuration
Cards Delegation Address

Service Endpoints

PROD : https://api.console.fi

DEV : https://dev.console.fi

User Onboarding Flow

Logging in a user
Initiating their KYC
Checking KYC Status
Creating a card if KYC approved
Delegating user DeFi position

Onboarding New User

Logging In

Start by requesting an EIP712 signature from the user. Use that signature to call the login endpoint along with tenantId . This should provide you with an accessToken and refreshToken .

{
    EIP712Domain: [
        { name: "name", type: "string" },
        { name: "version", type: "string" },
      ],
      Login: [
        { name: "timestamp", type: "uint256" },
        { name: "tenantID", type: "string" },
      ],
    },
    primaryType: "Login",
    domain: {
      name: "BrahmaCards",
      version: "1",
    },
    message: {
      timestamp,
      tenantID,
    },
}

post

Authenticates a user using a cryptographic signature and returns JWT access and refresh tokens

Header parameters

X-Partner-IDstringRequired

Partner identifier

X-API-KeystringRequired

API Key for authentication

Body

Request payload for user authentication via signature verification

eoastringOptionalExample: 0x742d35Cc6d9c2A4C8E1D3f2b3b4A7C8E9F0A1B2C...

sigstringOptionalExample: 0x1234567890abcdef...

timestampintegerOptionalExample: 1672531200

versionstringOptionalExample: 1.0

Responses

200

Authentication successful with tokens

application/json

400

Invalid signature format or malformed request

application/json

401

Authentication failed - invalid signature or expired

application/json

500

Internal server error

application/json

post

/auth/sig/login

POST /v1/vendor/cards/auth/sig/login HTTP/1.1
Host: api.console.fi
X-Partner-ID: text
X-API-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 124

{
  "eoa": "0x742d35Cc6d9c2A4C8E1D3f2b3b4A7C8E9F0A1B2C...",
  "sig": "0x1234567890abcdef...",
  "timestamp": 1672531200,
  "version": "1.0"
}

{
  "data": {
    "accessToken": "text",
    "expiresIn": 1,
    "refreshToken": "text",
    "tokenType": "text"
  }
}

This API is called when accessToken expires. This can be called with expired accessToken and refreshToken to generate new keys without requesting user login signature again. If this doesnt work then both are expires and we need to go back to logging in user via fresh 712 signature

Refresh JWT tokens

post

Refreshes expired access tokens using a valid refresh token and returns new JWT tokens

Header parameters

X-Partner-IDstringRequired

Partner identifier

X-API-KeystringRequired

API Key for authentication

Body

accessTokenstringOptional

expiresInintegerOptional

refreshTokenstringOptional

tokenTypestringOptional

Responses

200

Tokens refreshed successfully

application/json

400

Invalid token format or malformed request

application/json

401

Invalid or expired refresh token

application/json

500

Internal server error

application/json

post

/auth/token/refresh

POST /v1/vendor/cards/auth/token/refresh HTTP/1.1
Host: api.console.fi
X-Partner-ID: text
X-API-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 77

{
  "accessToken": "text",
  "expiresIn": 1,
  "refreshToken": "text",
  "tokenType": "text"
}

{
  "data": {
    "accessToken": "text",
    "expiresIn": 1,
    "refreshToken": "text",
    "tokenType": "text"
  }
}

Please note that after login, every API call should contain Authorization Header withBearer <accessToken> as the value

Checking User Status

Once the JWT is generated, we can start by fetching the user's status. Calling this endpoint will provide us with user's kycStatus and rainStatus

Get user KYC status

get

Retrieves the Rain KYC status of the authenticated user

Authorizations

AuthorizationstringRequired

Bearer token for JWT authentication (format: "Bearer {token}")

Header parameters

X-Partner-IDstringRequired

Partner identifier

X-API-KeystringRequired

API Key for authentication

Responses

200

User KYC status

application/json

400

Invalid request

application/json

401

Unauthorized

application/json

500

Internal server error

application/json

get

/users/status

GET /v1/vendor/cards/users/status HTTP/1.1
Host: api.console.fi
Authorization: YOUR_API_KEY
X-Partner-ID: text
X-API-Key: text
Accept: */*

{
  "data": {
    "errorDetails": "",
    "kycStatus": "APPROVED",
    "rainStatus": "ACTIVE"
  }
}

Based on KYC status, we can decide wether to start KYC for user / let the user know they are pending approval / let them know they are rejected or they are approved and proceed with card creation

kycStatus

rainStatus

Action

not_requested

Start KYC Modal

requested

Start KYC Modal

rejected

Show Rejected screen

resubmit

Raise issue with Brahma team

onhold

Raise issue with Brahma team

pending

Show Pending Screen

review

Show Pending Screen

pending

Show Pending Screen

initiated

Show Pending Screen

approved

Proceed with card creation

Creating New User

If user's kycStatus is not_requested or requested then we should initiate their KYC.

We need to create a new sumsub access token for the user by passing ownerAddress as connected wallet EOA of the user. This should return token and userId

Create SumSub access token

post

Generates a SumSub access token for a given owner address

Header parameters

X-Partner-IDstringRequired

Partner identifier

X-API-KeystringRequired

API Key for authentication

Body

Request structure for generating SumSub KYC access token

ownerAddressstringOptionalExample: 0x742d35Cc6d9c2A4C8E1D3f2b3b4A7C8E9F0A1B2C...

Responses

200

Success response with access token

application/json

400

Invalid input

application/json

401

Unauthorized

application/json

500

Internal server error

application/json

post

/sumsub/token

POST /v1/vendor/cards/sumsub/token HTTP/1.1
Host: api.console.fi
X-Partner-ID: text
X-API-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 64

{
  "ownerAddress": "0x742d35Cc6d9c2A4C8E1D3f2b3b4A7C8E9F0A1B2C..."
}

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userId": "usr_12345abcdef"
  }
}

We use both token and userId to initialize SumsubWebSDK on frontend

REF: https://docs.sumsub.com/docs/get-started-with-web-sdk#set-up-frontend-integration

Once the user completes their KYC flow, fetching the KYC status again would show kycStatus as pending . If documents are submitted correctly, user's rainStatus should turn to approved in a few minutes, so user can be asked to check back again later.

Creating a Card for approved user

Once rainStatus shows as approved in KYC status endpoint, we can proceed with creating card.

Notice here while creating card, you need to provide chainId {ex 999 for hyperevm, 8541 for base..etc}

hookConfig and hookType are optional and can be left as {} and "" empty respectively

cardSolverConfig , solverType should be provided to you by brahma team

creditProviderAddress is user's wallet address also known as their EOA

Once executed, you should be able to receive their card details including last 4 digits, expiry and an id which is a unique identifier for their card.

Note: Sensitive card details including full 16 digit card number and CVV are only available in encrypted format via dedicated endpoint. For ease of integration, they will be available in brahma's swype SDK

Create a new card for user

post

Creates a card for a user and assigns a credit provider.

Authorizations

AuthorizationstringRequired

Bearer token for JWT authentication (format: "Bearer {token}")

Query parameters

card_typestringOptional

Optional card type

Header parameters

X-Partner-IDstringRequired

Partner identifier

X-API-KeystringRequired

API Key for authentication

Body

Request structure for creating a card with credit provider assignment

cardSolverConfigobjectOptional

chainIDintegerOptionalExample: 1

creditProviderAddressstringOptionalExample: 0x742d35Cc6d9c2A4C8E1D3f2b3b4A7C8E9F0A1B2C...

hookConfigobjectOptional

hookTypeall ofOptional

Optional hook configuration

Example: PRE_TRANSACTION

string · enumOptionalPossible values:

solverTypeall ofOptionalExample: EULER

string · enumOptionalPossible values:

Responses

200

Card successfully created

application/json

400

Invalid request or input

application/json

401

Unauthorized

application/json

500

Internal server error

application/json

post

/create

POST /v1/vendor/cards/create HTTP/1.1
Host: api.console.fi
Authorization: YOUR_API_KEY
X-Partner-ID: text
X-API-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 173

{
  "cardSolverConfig": {},
  "chainID": 1,
  "creditProviderAddress": "0x742d35Cc6d9c2A4C8E1D3f2b3b4A7C8E9F0A1B2C...",
  "hookConfig": {},
  "hookType": "PRE_TRANSACTION",
  "solverType": "EULER"
}

{
  "data": {
    "expirationMonth": "12",
    "expirationYear": "2027",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "last4": "1234",
    "limit": {
      "amount": 1,
      "frequency": "per24HourPeriod"
    },
    "status": "ACTIVE",
    "type": "VIRTUAL",
    "userId": "660f9500-f39c-52e5-b827-557766551111"
  }
}

Once a user has a card created, we can call the GET endpoint to fetch their card details. This can also be called when the user logs in to quickly identify if they are an existing card holder.

Note that this endpoint will rely on JWT token as well as Partner ID and API key to identify user and their card details if any

Get user's cards with configurations

get

Retrieves all cards owned by the authenticated user along with their solver and hook configurations

Authorizations

AuthorizationstringRequired

Bearer token for JWT authentication (format: "Bearer {token}")

Header parameters

X-Partner-IDstringRequired

Partner identifier

X-API-KeystringRequired

API Key for authentication

Responses

200

List of user cards with configurations

application/json

400

Invalid tenant context

application/json

401

User authentication required

application/json

404

No cards found

application/json

500

Internal server error

application/json

get

GET /v1/vendor/cards/ HTTP/1.1
Host: api.console.fi
Authorization: YOUR_API_KEY
X-Partner-ID: text
X-API-Key: text
Accept: */*

{
  "data": [
    {
      "cardID": "550e8400-e29b-41d4-a716-446655440000",
      "chainID": 1,
      "expirationMonth": "12",
      "expirationYear": "2027",
      "hookChainID": 1,
      "hookConfig": {},
      "hookType": "PRE_TRANSACTION",
      "last4": "1234",
      "solverConfig": {},
      "solverCreditProviderAddress": 6.632511494639532e+47,
      "solverType": "EULER",
      "status": "ACTIVE",
      "type": "VIRTUAL"
    }
  ]
}

Integrating Cards SDK for decrypting sensitive card info

Brahma Cards provides a react SDK which can be integrated into client frontend. This exposes methods like showCardDetails which will take care of decrypting sensitive card info and let you show the details to user in plaintext https://www.npmjs.com/package/@brahmafi/cards-sdk

Delegating User Assets to make them spendable

Now that user has a card, we can let user delegate their defi positions to the Cards Delegation Address provided by team.

The integrator frontend can check onchain balances / ask user how much tokens/assets they would like to delegate and let them sign transaction to delegate their assets

Delegation transactions can be as simple as ERC20 token approvals for tokens like aave's aTokens, 4626 vault tokens.

In case of more complex defi positions like lending and borrowing tokens, please contact team to get exact information on supported delegation transactions. Once delegated, user should be able to start spending from their card

Managing a user's card configuration

Console cards exposes endpoints which can be used to set card details like setting spend limits

Update card limits

patch

Updates spending limits for a specific card (e.g. daily, weekly, monthly).

Authorizations

AuthorizationstringRequired

Bearer token for JWT authentication (format: "Bearer {token}")

Header parameters

X-Partner-IDstringRequired

Partner identifier

X-API-KeystringRequired

API Key for authentication

Body

Request structure for updating card spending limits and frequency

cardIDstringOptionalExample: 550e8400-e29b-41d4-a716-446655440000

frequencyall ofOptionalExample: DAILY

string · enumOptionalPossible values:

limitintegerOptionalExample: 1000

Responses

200

Card limits updated successfully

400

Invalid input or invalid card operation

application/json

401

Unauthorized

application/json

500

Internal server error

application/json

patch

/limits

PATCH /v1/vendor/cards/limits HTTP/1.1
Host: api.console.fi
Authorization: YOUR_API_KEY
X-Partner-ID: text
X-API-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 82

{
  "cardID": "550e8400-e29b-41d4-a716-446655440000",
  "frequency": "DAILY",
  "limit": 1000
}

No content

Update card PIN

patch

Updates the PIN of a specific card. Requires a valid session ID header.

Authorizations

AuthorizationstringRequired

Bearer token for JWT authentication (format: "Bearer {token}")

Header parameters

sessionIDstringRequired

Session ID

X-Partner-IDstringRequired

Partner identifier

X-API-KeystringRequired

API Key for authentication

Body

Request structure for updating card PIN with encrypted data

cardIDstringOptionalExample: 550e8400-e29b-41d4-a716-446655440000

Responses

200

Card PIN updated successfully

400

Invalid input, missing sessionID, or invalid card operation

application/json

401

Unauthorized

application/json

500

Internal server error

application/json

patch

/pin

PATCH /v1/vendor/cards/pin HTTP/1.1
Host: api.console.fi
Authorization: YOUR_API_KEY
sessionID: text
X-Partner-ID: text
X-API-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 100

{
  "cardID": "550e8400-e29b-41d4-a716-446655440000",
  "pin": {
    "encryptedPin": {
      "data": "text",
      "iv": "text"
    }
  }
}

No content

Get card transactions

get

Retrieves paginated transactions for a specific card of the authenticated user

Authorizations

AuthorizationstringRequired

Bearer token for JWT authentication (format: "Bearer {token}")

Path parameters

cardIDstringRequired

Card ID

Query parameters

limitintegerOptional

Maximum number of transactions to return

cursorstringOptional

Cursor for pagination

Header parameters

X-Partner-IDstringRequired

Partner identifier

X-API-KeystringRequired

API Key for authentication

Responses

200

Paginated list of transactions

application/json

400

Invalid card ID or query parameters

application/json

401

Unauthorized

application/json

500

Internal server error

application/json

get

/transactions/{cardID}

GET /v1/vendor/cards/transactions/{cardID} HTTP/1.1
Host: api.console.fi
Authorization: YOUR_API_KEY
X-Partner-ID: text
X-API-Key: text
Accept: */*

{
  "data": {
    "pagination": {
      "has_next": true,
      "limit": 1,
      "next_cursor": "text"
    },
    "transactions": [
      {
        "amount": 1,
        "authorized_at": "text",
        "created_at": "text",
        "currency": "text",
        "declined_reason": "text",
        "flow": "debit",
        "id": "text",
        "local_amount": 1,
        "local_currency": "text",
        "merchant": {
          "category": "text",
          "city": "text",
          "country": "text",
          "icon": "text",
          "name": "text"
        },
        "posted_at": "text",
        "status": "requested",
        "type": "spend"
      }
    ]
  }
}

Generating delegation transaction for user to sign and submit

For specific types of solver such as aave, console-cards can build calldata for you. In example below, we are delegating 3 cents from user's spend position.

{
    "creditType": "hypurrFi-withdraw",
    "creditLimit": 3,
    "chainID": 999,
    "userParams": {
        "aTokenAddress": "0x1Ca7e21B2dAa5Ab2eB9de7cf8f34dCf9c8683007",
        "purchaseBaseTokenAddress": "0xb8ce59fc3717ada4c02eadf9682a9e934f625ebb"
    }
}

Get delegation transaction

post

Generates a delegation transaction for the authenticated user based on credit limit and type

Authorizations

AuthorizationstringRequired

Bearer token for JWT authentication (format: "Bearer {token}")

Header parameters

X-Partner-IDstringRequired

Partner identifier

X-API-KeystringRequired

API Key for authentication

Body

Request structure for generating delegation transaction data

chainIDintegerOptionalExample: 1

creditLimitintegerOptionalExample: 1000

creditTypeall ofOptionalExample: EULER

string · enumOptionalPossible values:

userParamsobjectOptional

Responses

200

Delegation transaction details

application/json

400

Invalid input

application/json

401

Unauthorized

application/json

500

Internal server error

application/json

post

/users/credit/delegate

POST /v1/vendor/cards/users/credit/delegate HTTP/1.1
Host: api.console.fi
Authorization: YOUR_API_KEY
X-Partner-ID: text
X-API-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 69

{
  "chainID": 1,
  "creditLimit": 1000,
  "creditType": "EULER",
  "userParams": {}
}

{
  "data": {
    "callData": "text",
    "chainID": 1,
    "from": "text",
    "operation": 1,
    "simulationSuccessful": true,
    "to": "text",
    "value": "text"
  }
}

Last updated 4 months ago

hashtagGetting Started

hashtagPrerequisites

hashtagService Endpoints

hashtagUser Onboarding Flow

hashtag

hashtagOnboarding New User

hashtagLogging In

hashtagLogin with cryptographic signature

hashtagRefresh JWT tokens

hashtagChecking User Status

hashtagGet user KYC status

hashtagCreating New User

hashtagCreate SumSub access token

hashtagCreating a Card for approved user

hashtagCreate a new card for user

hashtagGet user's cards with configurations

hashtagIntegrating Cards SDK for decrypting sensitive card info

hashtag

hashtagDelegating User Assets to make them spendable

hashtag

hashtagManaging a user's card configuration

hashtagUpdate card limits

hashtagUpdate card PIN

hashtagGet card transactions

hashtagGenerating delegation transaction for user to sign and submit

hashtagGet delegation transaction

Getting Started

Prerequisites

Service Endpoints

User Onboarding Flow

Onboarding New User

Logging In

Login with cryptographic signature

Refresh JWT tokens

Checking User Status

Get user KYC status

Creating New User

Create SumSub access token

Creating a Card for approved user

Create a new card for user

Get user's cards with configurations

Integrating Cards SDK for decrypting sensitive card info

Delegating User Assets to make them spendable

Managing a user's card configuration

Update card limits

Update card PIN

Get card transactions

Generating delegation transaction for user to sign and submit

Get delegation transaction