Card

Cards: virtual cards with limits, for agents that buy things.

card = noclick.Card.create("Office supplies", limit_usd=1500, interval="month",
                           merchants=["office_supplies"], agent=buyer, require_approval_above_usd=200)
details = card.purchase(124.50, "Staples", reason="Toner").wait()   # approved first when above $200
for charge in card.transactions(limit=20):
    print(charge.merchant, charge.amount_usd, charge.status)
card.freeze()

Cards are your company's commercial cards, for US businesses, in dollars. They spend your company's own card balance, held by Stripe Payments Company (Card.funding()), which you fund by bank transfer: what a card pays isn't charged to your NoClick account, which pays only $0.13 per card number issued. Cards need card issuing, which your company applies for once in the console (Card.program()); until it's active these calls raise noclick.NotAvailable. A card number is shown only on a page where the card issuer's own element displays it (reveal()): it never passes through NoClick, your code or a model.

class Card

Invite-only beta. A virtual card with a spending limit. Card.fromName("Office supplies", { createIfMissing: true, limitUsd: 1500 }) is lazy; await card.purchase(...) approves and pays one purchase, await card.reveal() shows its number to a person. A card is always your company's, for its business, including buying for one of your users: one issued for a user is only that user's agents' to pay with, never a card the user owns or funds. It may be held by one agent, which pays with it at checkouts in its browser.

Like every live object, it also has hydrate(), refresh() and raw.

Attributes

id	string
name	string
last4	string \| null
brand	string \| null	The card network, like `visa`.
expMonth	number \| null
expYear	number \| null
status	CardStatus	`active`, `frozen` or `closed`.
statusReason	"negative_balance" \| null	Why it's frozen when you didn't freeze it: `negative_balance` while your card balance is below zero (it pays again once funded). Null otherwise.
limitUsd	number \| null	The most it spends per `interval` (null: no limit).
interval	CardInterval \| null	What `limit_usd` covers: `transaction`, `day`, `month` or `all_time`.
spentUsd	number \| null	Spent in the current interval (this calendar month's spend for a per-transaction limit).
resetsAt	Date \| null	When `spentUsd` starts over (null for `all_time`).
merchants	string[] \| null	The merchant categories it may pay (null: any).
requireApprovalAboveUsd	number \| null	Charges above this wait for a person (null: never).
agentId	string \| null	The agent that pays with it (null if none).
singleUse	boolean	Whether every checkout gets a fresh number that takes one charge (`last4` is the latest one's).
userId	string \| null
createdAt	Date \| null

createstatic

static create(name: string, options: CardCreateOptions): Promise<Card>

Issue a virtual card called name (unique among its user's open cards; a duplicate throws Conflict with existingId).

Parameters

namestringrequired

options.limitUsdnumberrequired

The most it spends per interval.

options.intervalCardInterval

Default "month".

options.merchantsstring | string[]

Merchant categories it may pay ("office_supplies", "software", "travel", ... or a 4-digit code); any when omitted, never cash, money transfers, gambling or securities.

options.agentAgent | string

The agent that pays with it.

options.requireApprovalAboveUsdnumber

A purchase above this is approved by a person before anything is paid (purchase); a charge above it that nobody announced is declined, and the merchant's retry passes once they approve.

options.singleUseboolean

Every checkout (every purchase, every reveal()) gets a fresh number that takes one charge and then closes; together they spend within limitUsd per interval (UTC days and months).

options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

(defaults to the current user)

options.clientNoClick

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

Returns

The new card, active, with its last4 and expiry (a single-use card has none until its first checkout). Its number is only ever shown on reveal()'s page. Each number costs $0.13.

fromNamestatic

static fromName(
  name: string,
  options?: CardDefinition & { createIfMissing?: boolean },
): Card

A lazy reference to the open card called name for the current (or given) user. With createIfMissing your code is the definition: it's issued on first use, and an existing card whose limit, interval, merchants, approval threshold or agent differ is updated to match. A field left out is never changed; null clears agent or requireApprovalAboveUsd, as update does.

Parameters

namestringrequired

options.createIfMissingboolean

options.limitUsdnumber

The most it spends per interval.

options.intervalCardInterval

Default "month".

options.merchantsstring | string[]

Merchant categories it may pay ("office_supplies", "software", "travel", ... or a 4-digit code); any when omitted, never cash, money transfers, gambling or securities.

options.agentAgent | string | nullomit to leave it unchanged

options.requireApprovalAboveUsdnumber | nullomit to leave it unchanged

options.singleUseboolean

Every checkout (every purchase, every reveal()) gets a fresh number that takes one charge and then closes; together they spend within limitUsd per interval (UTC days and months).

options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

(defaults to the current user)

options.clientNoClick

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

Returns

A card that loads (or is issued, or brought in step with your definition) the first time it's used. Nothing is sent yet.

fromIdstatic

static fromId(cardId: string, options?: CallOptions): Card

A lazy reference to a card by id.

Parameters

cardIdstringrequired

options.clientNoClick

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

(defaults to the current user)

Returns

A card that loads the first time you read a field. Nothing is sent yet.

getstatic

static get(cardId: string, options?: CallOptions): Promise<Card>

Load a card by id now; an unknown id raises noclick.NotFound.

Parameters

cardIdstringrequired

options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

(defaults to the current user)

options.clientNoClick

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

Returns

The card, loaded, with this interval's spent_usd.

liststatic

static list(
  options?: ReadOptions & {
    status?: CardStatus;
    agent?: Agent | string;
    limit?: number;
  },
): Promise<Card[]>

The current user's cards (the account's own outside asUser, or those userFilter covers).

Parameters

options.statusCardStatus

options.agentAgent | string

options.limitnumber

Return at most this many.

options.userFilterUserFilter

Which users the read covers (user_id query), instead of acting as one (user).

options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

(defaults to the current user)

options.clientNoClick

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

Returns

Every matching card, newest first, fetched page by page. Closed cards are listed only with status="closed".

listPagestatic

static listPage(
  options?: ReadOptions & PageOptions & {
    status?: CardStatus;
    agent?: Agent | string;
  },
): Promise<Page<Card>>

One page of cards; pass nextCursor back as cursor.

Parameters

options.cursorstring | null

The next_cursor of the page before; omit it for the first page.

options.limitnumber

Return at most this many.

options.statusCardStatus

options.agentAgent | string

options.userFilterUserFilter

Which users the read covers (user_id query), instead of acting as one (user).

options.userUserOption

undefined = the ambient user (asUser), null = the account itself.

(defaults to the current user)

options.clientNoClick

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

Returns

A page whose data holds the cards and whose next_cursor is None on the last page.

fundingstatic

static funding(options?: { client?: NoClick }): Promise<CardFunding>

Your company's card balance, which every card (the account's and every user's) spends from, and the bank details that fund it.

Parameters

options.clientNoClick

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

Returns

The balance_usd, what pending charges hold (pending_usd), what cards can still spend (available_usd), and the bank_transfer details that fund it.

programstatic

static program(options?: { client?: NoClick }): Promise<CardProgram>

Where your company's card issuing stands. It's applied for once, in the console.

Parameters

options.clientNoClick

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

Returns

The program's status (not_started, pending_verification, active, rejected or restricted), what it still needs (requirements_due) and where to apply (onboarding_url).

merchantCategoriesstatic

static merchantCategories(
  options?: { client?: NoClick },
): Promise<CardMerchantCategory[]>

The names merchants takes, each with the merchant category codes it covers (a 4-digit code works too).

Parameters

options.clientNoClick

The client to send with; defaults to the module client built from NOCLICK_API_KEY.

Returns

Every category, like office_supplies, software and travel.

transactions

transactions(
  options?: { status?: CardTransactionStatus; limit?: number | null },
): Promise<CardTransaction[]>

Its charges and refunds, newest first, each with any dispute: the newest limit (20 by default; null for every one).

Parameters

options.statusCardTransactionStatus

options.limitnumber | null

Return at most this many.

(default 20)

Returns

The newest limit (20 by default; None for every one), each with its amount, merchant, status, for a decline why, and any dispute.

reveal

reveal(): Promise<CardDetails>

A page that shows the card's number to a person: the card issuer's own element displays it there, for 10 minutes, so the number never passes through NoClick or your code. On a single-use card it's a fresh number, which closes unused after an hour. Needs a key with the cards:reveal scope; every reveal is recorded with the key that made it.

Returns

The page's url, when it stops showing the number, the number's last4 and expiry, and the cardholder name and billing address a checkout asks for.

purchase

purchase(
  amountUsd: number,
  merchant: string,
  options?: { reason?: string },
): Promise<Operation<CardDetails>>

Approve one purchase before paying it: a number for exactly this purchase, which takes one charge of at most amountUsd (tax and shipping included) and then closes. At or under requireApprovalAboveUsd it's ready at once; above it the card's user (or your account's owner) is asked first. A card.purchase operation: wait() resolves to the CardDetails to pay with, and throws PolicyDenied (declined) or Expired (nobody answered in 30 minutes). Needs cards:reveal.

Parameters

amountUsdnumberrequired

merchantstringrequired

options.reasonstring

Returns

A card.purchase operation; wait() returns the CardDetails to pay with once approved, and raises noclick.PolicyDenied (declined) or noclick.Expired (nobody answered in 30 minutes).

dispute

dispute(
  transaction: CardTransaction | string,
  options: {
    reason: CardDisputeReason;
    explanation: string;
    amountUsd?: number;
    product?: "merchandise" | "service";
    duplicateOf?: CardTransaction | string;;
  },
): Promise<CardDispute>

Dispute a settled charge with the card network: fraudulent (nobody here made it), canceled, duplicate (name the charge it copies in duplicateOf), not_received, not_as_described (with product) or incorrect_amount (with the amountUsd in dispute). A wrong purchase your agent made is a merchant dispute, not fraud.

Parameters

transactionCardTransaction | stringrequired

options.reasonCardDisputeReasonrequired

options.explanationstringrequired

options.amountUsdnumber

options.product"merchandise" | "service"

options.duplicateOfCardTransaction | string

Returns

The dispute, submitted; card.dispute.updated events follow it to won or lost.

update

update(fields: CardUpdateOptions): Promise<this>

Change its limits, merchants, approval threshold, agent or name; null clears a field.

Parameters

fieldsCardUpdateOptionsrequired

Returns

This card, updated. A field you leave out is unchanged, and changes apply from the next charge.

freeze

freeze(): Promise<this>

Decline every charge until unfreeze(); the card keeps its number and limits.

Returns

This card, frozen.

unfreeze

unfreeze(): Promise<this>

Let a frozen card pay again. While your card balance is below zero every card stays frozen (statusReason negative_balance): this throws Conflict until it's funded.

Returns

This card, active.

close

close(): Promise<this>

Close the card for good: it declines every charge and its number is never reissued.

Returns

This card, closed.

CardTransaction invite-only beta

interface CardTransaction

One charge or refund on a card. A charge is approved (held until the merchant settles it), settled (settledAmountUsd), reversed, declined or pending_approval (held for a person); a refund is settled, its amountUsd below zero. A decline says why in declineReason (over_limit, over_budget (an app's card, past what's left of the app's budget), merchant_not_allowed, frozen, insufficient_funds, amount_mismatch, not_approved, approval_expired, awaiting_approval, card_closed, card_expired, invalid_cvc, invalid_expiry, 3ds_failed, issuer_declined).

Attributes

id	string \| null
cardId	string \| null
kind	"charge" \| "refund" \| null
amountUsd	number \| null
settledAmountUsd	number \| null
merchant	string \| null
merchantCategory	string \| null	The `Card.merchantCategories()` name its `merchantMcc` is in (null: none of them).
merchantMcc	string \| null
status	CardTransactionStatus \| null
declineReason	string \| null
approvalId	string \| null	The held charge's approval, an operation: `await Operation.fromId(approvalId).wait()` is `true` once approved.
purchaseId	string \| null	The `card.purchase` operation whose number paid it.
last4	string \| null	The number it was on.
dispute	CardDispute \| null
at	Date \| null
raw	JsonObject	The response JSON exactly as the API sent it.

CardDetails invite-only beta

class CardDetails

Invite-only beta. A card number to pay with, shown only at url: a page where the card issuer's own element displays the number, CVC and expiry to whoever opens it, until expiresAt. The number never passes through NoClick, your code or a model, so send url only to the person who pays. Printing or serializing it leaves url out.

Attributes

url	string
expiresAt	Date \| null
last4	string \| null
brand	string \| null
expMonth	number \| null
expYear	number \| null
singleUse	boolean	A number that takes one charge (every number of a single-use card, every purchase's).
amountUsd	number \| null	A purchase's exact amount: the most its one charge may be.
closesAt	Date \| null	When a single-use number nobody paid with closes.
cardholder	string \| null	The name and billing address a checkout asks for: your company's.
billingAddress	JsonObject \| null
raw	JsonObject	The response JSON exactly as the API sent it.

CardFunding invite-only beta

interface CardFunding

Your company's card balance, held by Stripe Payments Company: every card spends from it. It can drop below zero when a merchant takes a charge without asking; NoClick then freezes your cards until it's funded again.

Attributes

balanceUsd	number \| null
pendingUsd	number \| null	Held by charges that haven't settled.
availableUsd	number \| null	What cards can still spend: the balance less what's pending.
topUpUrl	string \| null	The console page with the bank details.
bankTransfer	CardBankTransfer \| null
frozenSince	Date \| null	Since when your cards have been frozen because the balance is below zero (null: they aren't).
raw	JsonObject	The response JSON exactly as the API sent it.

CardBankTransfer invite-only beta

interface CardBankTransfer

Where your company sends money to fund its card balance: a wire lands the same day, ACH within days.

Attributes

bankName	string \| null
routingNumber	string \| null
accountNumber	string \| null
networks	string[]	`ach` and `wire`.

CardDispute invite-only beta

interface CardDispute

A settled charge disputed with the card network: submitted, then won, lost or expired.

Attributes

id	string \| null
transactionId	string \| null
reason	CardDisputeReason \| null	`fraudulent`, `canceled`, `duplicate`, `not_received`, `not_as_described` or `incorrect_amount`.
status	"submitted" \| "won" \| "lost" \| "expired" \| null
amountUsd	number \| null
createdAt	Date \| null
raw	JsonObject	The response JSON exactly as the API sent it.

CardProgram invite-only beta

interface CardProgram

Card issuing for your company: not_started, then pending_verification while the card issuer verifies it (requirementsDue), active; or rejected, or restricted (it needs something again). Your company applies once, in the console at onboardingUrl: US businesses, in dollars.

Attributes

status	CardProgramStatus
requirementsDue	string[]
companyName	string \| null
country	string \| null
currency	string \| null
onboardingUrl	string \| null
raw	JsonObject	The response JSON exactly as the API sent it.

CardMerchantCategory invite-only beta

interface CardMerchantCategory

A name merchants takes, and the merchant category codes it covers.

Attributes

name	string
description	string \| null
mccs	string[]