Class: Lithic::Resources::Cards

Inherits:
Object
  • Object
show all
Defined in:
lib/lithic/resources/cards.rb,
lib/lithic/resources/cards/balances.rb,
lib/lithic/resources/cards/financial_transactions.rb,
sig/lithic/resources/cards.rbs,
sig/lithic/resources/cards/balances.rbs,
sig/lithic/resources/cards/financial_transactions.rbs

Defined Under Namespace

Classes: Balances, FinancialTransactions

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Cards

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Cards.

Parameters:



521
522
523
524
525
 
# File 'lib/lithic/resources/cards.rb', line 521

def initialize(client:)
  @client = client
  @balances = Lithic::Resources::Cards::Balances.new(client: client)
  @financial_transactions = Lithic::Resources::Cards::FinancialTransactions.new(client: client)
end

Instance Attribute Details

#balances ⇒ Lithic::Resources::Cards::Balances (readonly)

Returns:



7
8
9
 
# File 'lib/lithic/resources/cards.rb', line 7

def balances
  @balances
end

#financial_transactions ⇒ Lithic::Resources::Cards::FinancialTransactions (readonly)

Returns:



10
11
12
 
# File 'lib/lithic/resources/cards.rb', line 10

def financial_transactions
  @financial_transactions
end

Instance Method Details

#convert_physical(card_token, shipping_address:, carrier: nil, product_id: nil, shipping_method: nil, request_options: {}) ⇒ Lithic::Models::Card

Some parameter documentations has been truncated, see Models::CardConvertPhysicalParams for more details.

Convert a virtual card into a physical card and manufacture it. Customer must supply relevant fields for physical card creation including product_id, carrier, shipping_method, and shipping_address. The card token will be unchanged. The card's type will be altered to PHYSICAL. The card will be set to state PENDING_FULFILLMENT and fulfilled at next fulfillment cycle. Virtual cards created on card programs which do not support physical cards cannot be converted. The card program cannot be changed as part of the conversion. Cards must be in an OPEN state to be converted. Only applies to cards of type VIRTUAL (or existing cards with deprecated types of DIGITAL_WALLET and UNLOCKED).

Parameters:

Returns:

See Also:



220
221
222
223
224
225
226
227
228
229
 
# File 'lib/lithic/resources/cards.rb', line 220

def convert_physical(card_token, params)
  parsed, options = Lithic::CardConvertPhysicalParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["v1/cards/%1$s/convert_physical", card_token],
    body: parsed,
    model: Lithic::Card,
    options: options
  )
end

#create(type:, account_token: nil, bulk_order_token: nil, card_program_token: nil, carrier: nil, digital_card_art_token: nil, exp_month: nil, exp_year: nil, memo: nil, pin: nil, product_id: nil, replacement_account_token: nil, replacement_comment: nil, replacement_for: nil, replacement_substatus: nil, shipping_address: nil, shipping_method: nil, spend_limit: nil, spend_limit_duration: nil, state: nil, idempotency_key: nil, request_options: {}) ⇒ Lithic::Models::Card

Some parameter documentations has been truncated, see Models::CardCreateParams for more details.

Create a new virtual or physical card. Parameters shipping_address and product_id only apply to physical cards.

Parameters:

  • type (Symbol, Lithic::Models::CardCreateParams::Type) —

    Body param: Card types:

  • account_token (String) —

    Body param: Globally unique identifier for the account that the card will be ass

  • bulk_order_token (String) —

    Body param: Globally unique identifier for an existing bulk order to associate t

  • card_program_token (String) —

    Body param: For card programs with more than one BIN range. This must be configu

  • carrier (Lithic::Models::Carrier) —

    Body param

  • digital_card_art_token (String) —

    Body param: Specifies the digital card art to be displayed in the user’s digital

  • exp_month (String) —

    Body param: Two digit (MM) expiry month. If neither exp_month nor exp_year i

  • exp_year (String) —

    Body param: Four digit (yyyy) expiry year. If neither exp_month nor exp_year

  • memo (String) —

    Body param: Friendly name to identify the card.

  • pin (String) —

    Body param: Encrypted PIN block (in base64). Applies to cards of type PHYSICAL

  • product_id (String) —

    Body param: Only applicable to cards of type PHYSICAL. This must be configured

  • replacement_account_token (String) —

    Body param: Restricted field limited to select use cases. Lithic will reach out

  • replacement_comment (String) —

    Body param: Additional context or information related to the card that this card

  • replacement_for (String) —

    Body param: Globally unique identifier for the card that this card will replace.

  • replacement_substatus (Symbol, Lithic::Models::CardCreateParams::ReplacementSubstatus) —

    Body param: Card state substatus values for the card that this card will replace

  • shipping_address (Lithic::Models::ShippingAddress) —

    Body param

  • shipping_method (Symbol, Lithic::Models::CardCreateParams::ShippingMethod) —

    Body param: Shipping method for the card. Only applies to cards of type PHYSICAL

  • spend_limit (Integer) —

    Body param: Amount (in cents) to limit approved authorizations (e.g. 100000 woul

  • spend_limit_duration (Symbol, Lithic::Models::SpendLimitDuration) —

    Body param: Spend limit duration values:

  • state (Symbol, Lithic::Models::CardCreateParams::State) —

    Body param: Card state values:

  • idempotency_key (String) —

    Header param: Idempotency key for the request

  • request_options (Lithic::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/lithic/resources/cards.rb', line 67

def create(params)
  parsed, options = Lithic::CardCreateParams.dump_request(params)
  header_params = {idempotency_key: "idempotency-key"}
  @client.request(
    method: :post,
    path: "v1/cards",
    headers: parsed.slice(*header_params.keys).transform_keys(header_params),
    body: parsed.except(*header_params.keys),
    model: Lithic::Card,
    options: options
  )
end

#embed(embed_request:, hmac:, request_options: {}) ⇒ String

Handling full card PANs and CVV codes requires that you comply with the Payment Card Industry Data Security Standards (PCI DSS). Some clients choose to reduce their compliance obligations by leveraging our embedded card UI solution documented below.

In this setup, PANs and CVV codes are presented to the end-user via a card UI that we provide, optionally styled in the customer's branding using a specified css stylesheet. A user's browser makes the request directly to api.lithic.com, so card PANs and CVVs never touch the API customer's servers while full card data is displayed to their end-users. The response contains an HTML document (see Embedded Card UI or Changelog for upcoming changes in January). This means that the url for the request can be inserted straight into the src attribute of an iframe.

<iframe
  id="card-iframe"
  src="https://sandbox.lithic.com/v1/embed/card?embed_request=eyJjc3MiO...;hmac=r8tx1..."
  allow="clipboard-write"
  class="content"
></iframe>

You should compute the request payload on the server side. You can render it (or the whole iframe) on the server or make an ajax call from your front end code, but do not ever embed your API key into front end code, as doing so introduces a serious security vulnerability.

Parameters:

  • embed_request (String) —

    A base64 encoded JSON string of an EmbedRequest to specify which card to load.

  • hmac (String) —

    SHA256 HMAC of the embed_request JSON string with base64 digest.

  • request_options (Lithic::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (String)

See Also:



270
271
272
273
274
275
276
277
278
279
280
281
 
# File 'lib/lithic/resources/cards.rb', line 270

def embed(params)
  parsed, options = Lithic::CardEmbedParams.dump_request(params)
  query = Lithic::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "v1/embed/card",
    query: query,
    headers: {"accept" => "text/html"},
    model: String,
    options: options
  )
end

#list(account_token: nil, begin_: nil, end_: nil, ending_before: nil, memo: nil, page_size: nil, starting_after: nil, state: nil, request_options: {}) ⇒ Lithic::Internal::CursorPage<Lithic::Models::NonPCICard>

Some parameter documentations has been truncated, see Models::CardListParams for more details.

List cards.

Parameters:

  • account_token (String) —

    Returns cards associated with the specified account.

  • begin_ (Time) —

    Date string in RFC 3339 format. Only entries created after the specified time wi

  • end_ (Time) —

    Date string in RFC 3339 format. Only entries created before the specified time w

  • ending_before (String) —

    A cursor representing an item's token before which a page of results should end.

  • memo (String) —

    Returns cards containing the specified partial or full memo text.

  • page_size (Integer) —

    Page size (for pagination).

  • starting_after (String) —

    A cursor representing an item's token after which a page of results should begin

  • state (Symbol, Lithic::Models::CardListParams::State) —

    Returns cards with the specified state.

  • request_options (Lithic::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/lithic/resources/cards.rb', line 176

def list(params = {})
  parsed, options = Lithic::CardListParams.dump_request(params)
  query = Lithic::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "v1/cards",
    query: query.transform_keys(begin_: "begin", end_: "end"),
    page: Lithic::Internal::CursorPage,
    model: Lithic::NonPCICard,
    options: options
  )
end

#provision(card_token, certificate: nil, client_device_id: nil, client_wallet_account_id: nil, digital_wallet: nil, nonce: nil, nonce_signature: nil, request_options: {}) ⇒ Lithic::Models::CardProvisionResponse

Some parameter documentations has been truncated, see Models::CardProvisionParams for more details.

Allow your cardholders to directly add payment cards to the device's digital wallet (e.g. Apple Pay) with one touch from your app.

This requires some additional setup and configuration. Please Contact Us or your Customer Success representative for more information.

Parameters:

  • card_token (String) —

    The unique token of the card to add to the device's digital wallet.

  • certificate (String) —

    Only applicable if digital_wallet is APPLE_PAY. Omit to receive only `activa

  • client_device_id (String) —

    Only applicable if digital_wallet is GOOGLE_PAY or SAMSUNG_PAY and the car

  • client_wallet_account_id (String) —

    Only applicable if digital_wallet is GOOGLE_PAY or SAMSUNG_PAY and the car

  • digital_wallet (Symbol, Lithic::Models::CardProvisionParams::DigitalWallet) —

    Name of digital wallet provider.

  • nonce (String) —

    Only applicable if digital_wallet is APPLE_PAY. Omit to receive only `activa

  • nonce_signature (String) —

    Only applicable if digital_wallet is APPLE_PAY. Omit to receive only `activa

  • request_options (Lithic::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



314
315
316
317
318
319
320
321
322
323
 
# File 'lib/lithic/resources/cards.rb', line 314

def provision(card_token, params = {})
  parsed, options = Lithic::CardProvisionParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["v1/cards/%1$s/provision", card_token],
    body: parsed,
    model: Lithic::Models::CardProvisionResponse,
    options: options
  )
end

#reissue(card_token, carrier: nil, product_id: nil, shipping_address: nil, shipping_method: nil, request_options: {}) ⇒ Lithic::Models::Card

Some parameter documentations has been truncated, see Models::CardReissueParams for more details.

Initiate print and shipment of a duplicate physical card (e.g. card is physically damaged). The PAN, expiry, and CVC2 will remain the same and the original card can continue to be used until the new card is activated. Only applies to cards of type PHYSICAL. A card can be reissued or renewed a total of 8 times.

Parameters:

Returns:

See Also:



351
352
353
354
355
356
357
358
359
360
 
# File 'lib/lithic/resources/cards.rb', line 351

def reissue(card_token, params = {})
  parsed, options = Lithic::CardReissueParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["v1/cards/%1$s/reissue", card_token],
    body: parsed,
    model: Lithic::Card,
    options: options
  )
end

#renew(card_token, shipping_address:, carrier: nil, exp_month: nil, exp_year: nil, product_id: nil, shipping_method: nil, request_options: {}) ⇒ Lithic::Models::Card

Some parameter documentations has been truncated, see Models::CardRenewParams for more details.

Applies to card types PHYSICAL and VIRTUAL. For PHYSICAL, creates a new card with the same card token and PAN, but updated expiry and CVC2 code. The original card will keep working for card-present transactions until the new card is activated. For card-not-present transactions, the original card details (expiry, CVC2) will also keep working until the new card is activated. A PHYSICAL card can be reissued or renewed a total of 8 times. For VIRTUAL, the card will retain the same card token and PAN and receive an updated expiry and CVC2 code. product_id, shipping_method, shipping_address, carrier are only relevant for renewing PHYSICAL cards.

Parameters:

  • card_token (String)
  • shipping_address (Lithic::Models::ShippingAddress) —

    The shipping address this card will be sent to.

  • carrier (Lithic::Models::Carrier) —

    If omitted, the previous carrier will be used.

  • exp_month (String) —

    Two digit (MM) expiry month. If neither exp_month nor exp_year is provided,

  • exp_year (String) —

    Four digit (yyyy) expiry year. If neither exp_month nor exp_year is provided

  • product_id (String) —

    Specifies the configuration (e.g. physical card art) that the card should be man

  • shipping_method (Symbol, Lithic::Models::CardRenewParams::ShippingMethod) —

    Shipping method for the card. Only applies to cards of type PHYSICAL.

  • request_options (Lithic::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



396
397
398
399
400
401
402
403
404
405
 
# File 'lib/lithic/resources/cards.rb', line 396

def renew(card_token, params)
  parsed, options = Lithic::CardRenewParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["v1/cards/%1$s/renew", card_token],
    body: parsed,
    model: Lithic::Card,
    options: options
  )
end

#retrieve(card_token, request_options: {}) ⇒ Lithic::Models::Card

Get card configuration such as spend limit and state.

Parameters:

Returns:

See Also:



90
91
92
93
94
95
96
97
 
# File 'lib/lithic/resources/cards.rb', line 90

def retrieve(card_token, params = {})
  @client.request(
    method: :get,
    path: ["v1/cards/%1$s", card_token],
    model: Lithic::Card,
    options: params[:request_options]
  )
end

#retrieve_signals(card_token, request_options: {}) ⇒ Lithic::Models::SignalsResponse

Returns behavioral feature state derived from a card's transaction history.

These signals expose the same data used by behavioral rule attributes (e.g. AMOUNT_Z_SCORE with scope: CARD, IS_NEW_COUNTRY with scope: CARD) and custom code TRANSACTION_HISTORY_SIGNALS features, allowing clients to inspect feature values before writing rules and debug rule behavior.

Parameters:

  • card_token (String) —

    The token of the card to fetch signals for.

  • request_options (Lithic::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



423
424
425
426
427
428
429
430
 
# File 'lib/lithic/resources/cards.rb', line 423

def retrieve_signals(card_token, params = {})
  @client.request(
    method: :get,
    path: ["v1/cards/%1$s/signals", card_token],
    model: Lithic::SignalsResponse,
    options: params[:request_options]
  )
end

#retrieve_spend_limits(card_token, request_options: {}) ⇒ Lithic::Models::CardSpendLimits

Get a Card's available spend limit, which is based on the spend limit configured on the Card and the amount already spent over the spend limit's duration. For example, if the Card has a monthly spend limit of $1000 configured, and has spent $600 in the last month, the available spend limit returned would be $400.

Parameters:

Returns:

See Also:



445
446
447
448
449
450
451
452
 
# File 'lib/lithic/resources/cards.rb', line 445

def retrieve_spend_limits(card_token, params = {})
  @client.request(
    method: :get,
    path: ["v1/cards/%1$s/spend_limits", card_token],
    model: Lithic::CardSpendLimits,
    options: params[:request_options]
  )
end

#search_by_pan(pan:, request_options: {}) ⇒ Lithic::Models::Card

Get card configuration such as spend limit and state. Customers must be PCI compliant to use this endpoint. Please contact support.lithic.com for questions. Note: this is a POST endpoint because it is more secure to send sensitive data in a request body than in a URL.

Parameters:

  • pan (String) —

    The PAN for the card being retrieved.

  • request_options (Lithic::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



469
470
471
472
473
474
475
476
477
478
 
# File 'lib/lithic/resources/cards.rb', line 469

def search_by_pan(params)
  parsed, options = Lithic::CardSearchByPanParams.dump_request(params)
  @client.request(
    method: :post,
    path: "v1/cards/search_by_pan",
    body: parsed,
    model: Lithic::Card,
    options: options
  )
end

#update(card_token, comment: nil, digital_card_art_token: nil, memo: nil, network_program_token: nil, pin: nil, pin_status: nil, spend_limit: nil, spend_limit_duration: nil, state: nil, substatus: nil, request_options: {}) ⇒ Lithic::Models::Card

Some parameter documentations has been truncated, see Models::CardUpdateParams for more details.

Update the specified properties of the card. Unsupplied properties will remain unchanged.

Note: setting a card to a CLOSED state is a final action that cannot be undone.

Parameters:

  • card_token (String)
  • comment (String) —

    Additional context or information related to the card.

  • digital_card_art_token (String) —

    Specifies the digital card art to be displayed in the user’s digital wallet afte

  • memo (String) —

    Friendly name to identify the card.

  • network_program_token (String) —

    Globally unique identifier for the card's network program. Currently applicable

  • pin (String) —

    Encrypted PIN block (in base64). Only applies to cards of type PHYSICAL and `V

  • pin_status (Symbol, Lithic::Models::CardUpdateParams::PinStatus) —

    Indicates if a card is blocked due a PIN status issue (e.g. excessive incorrect

  • spend_limit (Integer) —

    Amount (in cents) to limit approved authorizations (e.g. 100000 would be a $1,00

  • spend_limit_duration (Symbol, Lithic::Models::SpendLimitDuration) —

    Spend limit duration values:

  • state (Symbol, Lithic::Models::CardUpdateParams::State) —

    Card state values:

  • substatus (Symbol, Lithic::Models::CardUpdateParams::Substatus) —

    Card state substatus values:

  • request_options (Lithic::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



137
138
139
140
141
142
143
144
145
146
 
# File 'lib/lithic/resources/cards.rb', line 137

def update(card_token, params = {})
  parsed, options = Lithic::CardUpdateParams.dump_request(params)
  @client.request(
    method: :patch,
    path: ["v1/cards/%1$s", card_token],
    body: parsed,
    model: Lithic::Card,
    options: options
  )
end

#web_provision(card_token, client_device_id: nil, client_wallet_account_id: nil, digital_wallet: nil, server_session_id: nil, request_options: {}) ⇒ Lithic::Models::CardWebProvisionResponse::AppleWebPushProvisioningResponse, Lithic::Models::CardWebProvisionResponse::GoogleWebPushProvisioningResponse

Some parameter documentations has been truncated, see Models::CardWebProvisionParams for more details.

Allow your cardholders to directly add payment cards to the device's digital wallet from a browser on the web.

This requires some additional setup and configuration. Please Contact Us or your Customer Success representative for more information.

Parameters:

  • card_token (String) —

    The unique token of the card to add to the device's digital wallet.

  • client_device_id (String) —

    Only applicable if digital_wallet is GOOGLE_PAY. Google Pay Web Push Provision

  • client_wallet_account_id (String) —

    Only applicable if digital_wallet is GOOGLE_PAY. Google Pay Web Push Provision

  • digital_wallet (Symbol, Lithic::Models::CardWebProvisionParams::DigitalWallet) —

    Name of digital wallet provider.

  • server_session_id (String) —

    Only applicable if digital_wallet is GOOGLE_PAY. Google Pay Web Push Provision

  • request_options (Lithic::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



507
508
509
510
511
512
513
514
515
516
 
# File 'lib/lithic/resources/cards.rb', line 507

def web_provision(card_token, params = {})
  parsed, options = Lithic::CardWebProvisionParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["v1/cards/%1$s/web_provision", card_token],
    body: parsed,
    model: Lithic::Models::CardWebProvisionResponse,
    options: options
  )
end