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.

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.

    • phoneNumber object

      Vendor phone number.

      • 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

    • 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

      Vendor phone number.

      • 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

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.

    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

      Vendor phone number.

      • 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

    • 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