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. Amounts are in minor units (cents). '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. Each result echoes the row's index and providerId; a FAILED row carries the error as text and as a structured 'failure'.

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

  • transactions array of objectrequired

    Rows to import. Maximum 100 per request.

    • cardId string · uuid

      Light's id of the card. Give this or cardProviderId, not both.

    • cardProviderId string

      The card's own provider id, as given when the card was created. Give this or cardId, not both.

    • providerId string

      The issuer's own transaction id. Used as the idempotency key: a row whose providerId was already imported comes back as SKIPPED_DUPLICATE. When omitted, Light derives one from the card, amount, date and merchant.

    • amount integer · int64required

      Amount settled on the balance account, in minor units (e.g. cents). Positive; 'direction' carries the sign.

    • currency stringrequired

    • originalAmount integer · int64

      Purchase-side amount in minor units when the purchase was made in another currency.

    • 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

    • postingDate string · date

      Posting date of the ledger document when the transaction is auto-posted. Defaults to the day of 'performedAt'.

Response

  • index integer · int32

    Position of the row in the request.

  • outcome string

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

    One of CREATED FAILED SKIPPED_DUPLICATE

  • cardTransactionId string · uuid

  • providerId string

    The row's providerId: the one sent, or the one Light derived for a created or skipped row.

  • error string

  • failure object

    Failure context when vendor onboarding fails.

    • name string

      The error name

    • type string

      The error type

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

      One of BAD_REQUEST UNAUTHORIZED FORBIDDEN NOT_FOUND CONFLICT UNPROCESSABLE_CONTENT

    • errors array of object

      List of errors providing details about what went wrong

      • type string

        A string code identifying the error type

      • message string

        A human-readable message providing more details about the error

      • path array of string

        Optional path of the error when the error is for a specific field. Used mostly on BAD_REQUEST errors, that path will match the field name on the request object

      • context object

        Optional context providing additional information about the error. This can include any relevant data that might help in understanding or resolving the error