Virtual Cards (coming soon)

This page outlines the Card object that will be used to issue and manage virtual cards through Confido Legal.

The Card Object

type Card {
  id: string
  authorizationControls?: AuthorizationControls
  bankAccount: BankAccount
  billingAddress: Address
  bin: string
  cardholderName: CardholderName
  client?: Client
  createdOn: Date
  expMonth: string
  expYear: string
  lastFour: string
  matter?: Matter
  nickname?: string
  status: string
  vendor?: Vendor
}

AuthorizationControls

type AuthorizationControls {
  merchantAcceptorIds: AllowBlockList
  merchantCategoryCode: AllowBlockList
  merchantCountry: AllowBlockList
  usage: UsageControls
}

type AllowBlockList {
  allowed: [String]
  blocked: [String]
}

type UsageControls {
  category: 'single_use' | 'multi_use'
  multiUse?: MultiUseControls
  singleUse?: SingleUseControls
}

type MultiUseControls {
  spendingLimits: SpendingLimit[]
}

type SpendingLimit {
  interval: 'all_time' | 'per_transaction' | 'per_day' | 'per_week' | 'per_month'
  merchantCategoryCodes?: [String]
  settlementAmount: Int
}

type SingleUseControls {
  settlementAmount: SingleUseSettlementAmount
}

type SingleUseSettlementAmount {
  comparison: 'equals' | 'less_than_or_equals'
  value: Int
}

Creating a Card

The cardCreate mutation issues a new virtual card. Call it with the Firm API token.

mutation CardCreate($input: CardCreateInput!) {
  cardCreate(input: $input) {
    id
    bin
    cardholderName
    createdOn
    expMonth
    expYear
    lastFour
    nickname
    status
  }
}

Input

authorizationControls — restrictions on where and how the card can be used (nullable)
bankAccountId — the ID of the bank account the card is funded from
billingAddress — the billing address associated with the card, defaults to the firm address (nullable)
cardholderName — the name of the cardholder, defaults to the firm name (nullable)
clientId — the ID of the client to associate with the card (nullable)
matterId — the ID of the matter to associate with the card (nullable)
nickname — an optional nickname for the card (nullable)
vendorId — the ID of the vendor to associate with the card (nullable)

Update a Card

The cardUpdate mutation updates an existing virtual card. Call it with the Firm API token.

mutation CardUpdate($input: CardUpdateInput!) {
  cardUpdate(input: $input) {
    id
    bin
    cardholderName
    createdOn
    expMonth
    expYear
    lastFour
    nickname
    status
  }
}

Input

id — the ID of the card to update
authorizationControls — restrictions on where and how the card can be used (nullable)
billingAddress — the billing address associated with the card (nullable)
clientId — the ID of the client to associate with the card (nullable)
matterId — the ID of the matter to associate with the card (nullable)
nickname — an optional nickname for the card (nullable)
status — the status of the card (nullable)
vendorId — the ID of the vendor to associate with the card (nullable)

Viewing Card Details

Sensitive card details (PAN, CVV, and expiration) are never returned directly from the API. To view a card, mint a short-lived token from your server, then open Confido’s hosted card page or embed it in an iframe. Card data is rendered on Confido’s hosted page, so your servers stay out of PCI scope for card display.

High level flow

Mint a card view token from your server

Open the hosted card page or embed an iframe using the token

Mint a new token when the previous one expires

1. Create a token

Call cardDetailsTokenCreate with the Firm API token and the card ID:

mutation CardDetailsTokenCreate($input: CardDetailsTokenCreateInput!) {
  cardDetailsTokenCreate(input: $input) {
    token
    expiresAt
  }
}

Input

cardId — the ID of the card to view

Response

token — a short-lived token used to access the card details page
expiresAt — when the token expires (one hour after creation)

Keep the Firm API token on your server. Only the returned token should be sent to the browser.

2. View the card

Environment	Base URL
Sandbox	`https://pay.sandbox.confidolegal.com`
Production	`https://pay.confidolegal.com`

Hosted page Redirect the user (or open a new tab) to the card details page with the token as a query parameter:

https://pay.sandbox.confidolegal.com/card?token=TOKEN

iframe Embed the card details iframe in your application:

<iframe
  id="card-display"
  title="Virtual card"
  src="https://pay.sandbox.confidolegal.com/card/iframe?token=TOKEN"
  style="border: none; width: 100%; min-height: 320px;"
></iframe>

Register your application’s parent-page origin as a trusted domain when embedding the iframe. Required in sandbox and production.

Notes

Tokens expire after one hour. When a token expires, call cardDetailsTokenCreate again and update the page URL or iframe src.
Do not cache or log full card details. Treat the token as sensitive while it is valid.
Your application should never collect or store PAN or CVV from the displayed card.

Introduction

Firm Onboarding

Embedded Forms

Receive Money

Send Money (Disbursements)

Payment Methods

Cards

Payments Lifecycle

Hosted Fields

Statements

Webhooks

Sandbox

The Card Object

Creating a Card

Update a Card

Viewing Card Details

High level flow

1. Create a token

2. View the card

Notes

​The Card Object

​Creating a Card

​Update a Card

​Viewing Card Details

​High level flow

​1. Create a token

​2. View the card

​Notes

The Card Object

Creating a Card

Update a Card

Viewing Card Details

High level flow

1. Create a token

2. View the card

Notes