Light APIv1.0.0

API / Reference / Cards

Create card

POST https://api.light.inc/v1/cards

Creates a new card. Use metadata type 'VENDOR' for vendor cards or 'EMPLOYEE' for employee cards.

Creation is synchronous with the card issuer: the response is the finished card, and a virtual card comes back ACTIVE and ready to use. A physical card is activated by POST /v1/cards/{cardId}/unfreeze once the cardholder has it. Preconditions, all 400: the balance account is active (CARD_BALANCE_ACCOUNT_NOT_ACTIVE), its entity is set up for cards (COMPANY_ENTITY_NOT_ACTIVE_ON_CARDS), and ownerId is an active user (CARD_CREATION_OWNER_NOT_RECOGNIZED). With metadata.type = VENDOR the vendor must exist and be linked to that entity (CARD_CREATION_VENDOR_NOT_RECOGNIZED); with EMPLOYEE nothing further is validated. Two limits with the same interval fail with CARD_CREATION_CONFLICTING_LIMITS. formFactor defaults to VIRTUAL.

Send an X-Idempotency-Key header: a retry with the same key returns the existing card, while a retry without one issues a second card. threeDs.password is generated by Light and always returned masked as ****. Not available in the sandbox.

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

Headers

  • X-Idempotency-Key string

Request body

application/json;charset=UTF-8

  • balanceAccountId string · uuid

    ID of the card balance account to associate with this card.

  • ownerId string · uuid

    ID of the user who will own/manage this card.

  • metadata object

    Card type metadata. Use type 'VENDOR' with vendorId for vendor cards, or type 'EMPLOYEE' with employeeId for employee cards.

    • type string

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

      One of VENDOR EMPLOYEE

  • description string

    Optional description or memo for this card.

  • authentication object

    3D Secure authentication details for the card. Required for Light-issued cards, ignored for external providers.

    • phoneNumber object

      • countryCode string

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

        One of UNDEFINED AC AD AE AF AG AI AL AM AN AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BU BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CP CR CS CU CV CW CX CY CZ DE DG DJ DK DM DO DZ EA EC EE EG EH ER ES ET EU EZ FI FJ FK FM FO FR FX GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU IC ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NT NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SF SG SH SI SJ SK SL SM SN SO SR SS ST SU SV SX SY SZ TA TC TD TF TG TH TJ TK TL TM TN TO TP TR TT TV TW TZ UA UG UK UM US UY UZ VA VC VE VG VI VN VU WF WS XI XU XK YE YT YU ZA ZM ZR ZW

      • localNumber string

        The number without the country code.

    • email string

      Email address for 3D Secure authentication.

  • limits array of object

    Optional spending limits for this card.

    • amount integer · int64

      Spending limit amount in minor units (e.g., cents).

    • currency string

    • interval string

      Interval for the spending limit (PER_TRANSACTION, WEEKLY, or MONTHLY).

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

      One of PER_TRANSACTION WEEKLY MONTHLY

  • formFactor string

    Card form factor. Defaults to VIRTUAL when omitted. PHYSICAL ships a plastic card and requires deliveryContact to be set. VIRTUAL must be sent with deliveryContact left null. Mismatches are rejected with PHYSICAL_CARD_DELIVERY_CONTACT_REQUIRED or VIRTUAL_CARD_DELIVERY_CONTACT_NOT_ALLOWED.

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

    One of PHYSICAL VIRTUAL

  • deliveryContact object

    Recipient and address used by the card issuer to ship the physical card. Only address and name are required.

    • address object

      Postal address the card is shipped to. Country must be an ISO 3166-1 alpha-2 code; stateOrProvince is required for US and CA destinations. An address the card issuer rejects comes back as CARD_PROVIDER_REJECTED_FIELD with path pointing at the offending field.

      • street string

        Street name (maps to Adyen address.line1).

      • houseNumberOrName string

        House number, building, apartment, or suite (maps to Adyen address.line2).

      • city string

        City.

      • postalCode string

        Postal or ZIP code in the delivery country's own format; separators such as spaces and dashes are optional. Max 10 characters, or 5 digits for US. The card issuer validates the format and rejects a code that doesn't match the destination country.

      • country string

        ISO 3166-1 alpha-2 country code (e.g. DK, US, GB).

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

        One of UNDEFINED AC AD AE AF AG AI AL AM AN AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BU BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CP CR CS CU CV CW CX CY CZ DE DG DJ DK DM DO DZ EA EC EE EG EH ER ES ET EU EZ FI FJ FK FM FO FR FX GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU IC ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NT NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SF SG SH SI SJ SK SL SM SN SO SR SS ST SU SV SX SY SZ TA TC TD TF TG TH TJ TK TL TM TN TO TP TR TT TV TW TZ UA UG UK UM US UY UZ VA VC VE VG VI VN VU WF WS XI XU XK YE YT YU ZA ZM ZR ZW

      • stateOrProvince string

        State, province, or region. Required when country is US or CA; requests without it are rejected with PHYSICAL_CARD_STATE_OR_PROVINCE_REQUIRED. Optional for other countries.

    • name object

      Name printed on the shipping label.

      • firstName string

        Recipient first name.

      • lastName string

        Recipient last name.

    • company string

      Company or department name on the shipping label.

    • email string

      Contact email for delivery notifications.

    • phoneNumber object

      • countryCode string

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

        One of UNDEFINED AC AD AE AF AG AI AL AM AN AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BU BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CP CR CS CU CV CW CX CY CZ DE DG DJ DK DM DO DZ EA EC EE EG EH ER ES ET EU EZ FI FJ FK FM FO FR FX GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU IC ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NT NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SF SG SH SI SJ SK SL SM SN SO SR SS ST SU SV SX SY SZ TA TC TD TF TG TH TJ TK TL TM TN TO TP TR TT TV TW TZ UA UG UK UM US UY UZ VA VC VE VG VI VN VU WF WS XI XU XK YE YT YU ZA ZM ZR ZW

      • localNumber string

        The number without the country code.

  • providerId string

    Issuer-supplied card ID, for external (non-Adyen) cards only. Prefer sending this when known, since it makes repeat imports idempotent. A synthetic ID is generated when omitted. Ignored for cards on an Adyen-backed balance account.

  • lastFour string

    Last four digits of the card number, for external (non-Adyen) cards only. Required when the balance account is external. Ignored for cards on an Adyen-backed balance account.

  • cardholderName string

    Name embossed on the card, for external (non-Adyen) cards only. Required when the balance account is external. Ignored for cards on an Adyen-backed balance account.

Response

  • id string · uuid

  • companyEntityId string · uuid

  • companyId string · uuid

  • ownerId string · uuid

  • cardBalanceAccountId string · uuid

  • form string

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

    One of PHYSICAL VIRTUAL

  • status string

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

    ACTIVE, FROZEN, CLOSED, or the transient UPDATE_IN_PROGRESS while a freeze or unfreeze is being applied at the issuer.

    One of ACTIVE FROZEN CLOSED UPDATE_IN_PROGRESS

  • metadata object

    • type string

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

      One of VENDOR EMPLOYEE

  • threeDs object

    • phoneNumber object

      May be null.

      • countryCode string

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

        One of UNDEFINED AC AD AE AF AG AI AL AM AN AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BU BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CP CR CS CU CV CW CX CY CZ DE DG DJ DK DM DO DZ EA EC EE EG EH ER ES ET EU EZ FI FJ FK FM FO FR FX GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU IC ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NT NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SF SG SH SI SJ SK SL SM SN SO SR SS ST SU SV SX SY SZ TA TC TD TF TG TH TJ TK TL TM TN TO TP TR TT TV TW TZ UA UG UK UM US UY UZ VA VC VE VG VI VN VU WF WS XI XU XK YE YT YU ZA ZM ZR ZW

      • localNumber string

        The number without the country code.

    • password string

    • email string

  • description string

  • bin string

  • lastFour string

  • cardholderName string

  • limits array of object

    • id string · uuid

    • companyId string · uuid

    • cardId string · uuid

    • amount integer · int64

    • currency string

    • interval string

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

      One of PER_TRANSACTION WEEKLY MONTHLY

    • createdAt string · date-time

    • updatedAt string · date-time

  • createdAt string · date-time

  • updatedAt string · date-time

  • type string

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

    One of VENDOR EMPLOYEE