Light APIv1.0.0

API / Reference / Card Transactions

Import card transactions

POST https://api.light.inc/v1/card-transactions/import

Imports a batch of up to 100 external card transactions. Each row is validated and created independently, so one bad row does not affect the others -- the response has one result per row, in the same order as the request. Larger batches are rejected as a whole. 'providerId' is the row's idempotency key: a row whose providerId was already imported comes back as SKIPPED_DUPLICATE with the existing transaction id. Always pass the issuer's own transaction id when you have one; when omitted, the key is derived from the row's card, amount, date and merchant, so re-sending the same rows is safe but two genuinely different transactions with identical content in one request are kept apart only by their order. 'amount' and 'currency' are what settled on the card's balance account and must be in that account's currency; for a purchase made in another currency, pass the purchase-side amount as 'originalAmount' and 'originalCurrency'. Rules, each failing only that row: both or neither; the same currency must carry the same amount; both amounts are positive magnitudes and 'direction' carries the sign. When omitted they default to the settled amount.

Authorization

Send one of these on every request. See Authentication for how to get credentials.

  • API key

    Basic authentication header of the form Basic <api_key>, where <api_key> is your api key.

  • Bearer token

Request body

application/json;charset=UTF-8

  • cardId string · uuid

  • providerId string

  • amount integer · int64

  • currency string

  • originalAmount integer · int64

  • originalCurrency string

  • direction string

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of DEBIT CREDIT

  • merchantName string

  • performedAt string · date-time

Response

  • outcome string

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of CREATED FAILED SKIPPED_DUPLICATE

  • cardTransactionId string · uuid

  • error string