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/aggregate_balances.rb,
lib/lithic/resources/cards/financial_transactions.rb

Defined Under Namespace

Classes: AggregateBalances, 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:



487
488
489
490
491
492
 
# File 'lib/lithic/resources/cards.rb', line 487

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

Instance Attribute Details

#aggregate_balances ⇒ Lithic::Resources::Cards::AggregateBalances (readonly)

Returns:



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

def aggregate_balances
  @aggregate_balances
end

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

Returns:



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

def balances
  @balances
end

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

Returns:



13
14
15
 
# File 'lib/lithic/resources/cards.rb', line 13

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:



212
213
214
215
216
217
218
219
220
221
 
# File 'lib/lithic/resources/cards.rb', line 212

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, 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) —

    Card types:

  • account_token (String) —

    Globally unique identifier for the account that the card will be associated with

  • bulk_order_token (String) —

    Globally unique identifier for an existing bulk order to associate this card wit

  • card_program_token (String) —

    For card programs with more than one BIN range. This must be configured with Lit

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

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

  • 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

  • memo (String) —

    Friendly name to identify the card.

  • pin (String) —

    Encrypted PIN block (in base64). Applies to cards of type ‘PHYSICAL` and `VIRTUA

  • product_id (String) —

    Only applicable to cards of type ‘PHYSICAL`. This must be configured with Lithic

  • replacement_account_token (String) —

    Restricted field limited to select use cases. Lithic will reach out directly if

  • replacement_comment (String) —

    Additional context or information related to the card that this card will replac

  • replacement_for (String) —

    Globally unique identifier for the card that this card will replace. If the card

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

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

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

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

  • 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::CardCreateParams::State) —

    Card state values:

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

Returns:

See Also:



68
69
70
71
 
# File 'lib/lithic/resources/cards.rb', line 68

def create(params)
  parsed, options = Lithic::CardCreateParams.dump_request(params)
  @client.request(method: :post, path: "v1/cards", body: parsed, 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.

“‘html <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:



262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/lithic/resources/cards.rb', line 262

def embed(params)
  parsed, options = Lithic::CardEmbedParams.dump_request(params)
  @client.request(
    method: :get,
    path: "v1/embed/card",
    query: parsed,
    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:



169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/lithic/resources/cards.rb', line 169

def list(params = {})
  parsed, options = Lithic::CardListParams.dump_request(params)
  @client.request(
    method: :get,
    path: "v1/cards",
    query: parsed.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](lithic.com/contact) 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:



305
306
307
308
309
310
311
312
313
314
 
# File 'lib/lithic/resources/cards.rb', line 305

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:



342
343
344
345
346
347
348
349
350
351
 
# File 'lib/lithic/resources/cards.rb', line 342

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:



387
388
389
390
391
392
393
394
395
396
 
# File 'lib/lithic/resources/cards.rb', line 387

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:



83
84
85
86
87
88
89
90
 
# File 'lib/lithic/resources/cards.rb', line 83

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_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:



411
412
413
414
415
416
417
418
 
# File 'lib/lithic/resources/cards.rb', line 411

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 [[email protected]]([email protected]) 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:



435
436
437
438
439
440
441
442
443
444
 
# File 'lib/lithic/resources/cards.rb', line 435

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:



130
131
132
133
134
135
136
137
138
139
 
# File 'lib/lithic/resources/cards.rb', line 130

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. Currently only suported for Apple Pay.

This requires some additional setup and configuration. Please [Contact Us](lithic.com/contact) 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:



473
474
475
476
477
478
479
480
481
482
 
# File 'lib/lithic/resources/cards.rb', line 473

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