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

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:



496
497
498
499
500
 
# File 'lib/lithic/resources/cards.rb', line 496

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.

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



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](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:



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



420
421
422
423
424
425
426
427
 
# File 'lib/lithic/resources/cards.rb', line 420

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](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:



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

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](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:



482
483
484
485
486
487
488
489
490
491
 
# File 'lib/lithic/resources/cards.rb', line 482

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