# Issuing Card

The Issuing Card resource represents a physical or virtual card issued to a holder.

Cards can be created as virtual (immediately available) or physical (requires embossing and shipping).

You can set rules on the card level to control spending limits, merchant restrictions, and other card behaviors.

### The Issuing Card object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing card. |
| `holderId` | STRING | Id of the IssuingHolder associated with this card. |
| `holderName` | STRING | Name of the holder printed on the card. |
| `holderTaxId` | STRING | Tax id of the IssuingHolder associated with this card. |
| `holderExternalId` | STRING | External id of the IssuingHolder associated with this card. |
| `displayName` | STRING | Name displayed on the card face. Example: "TONY STARK". |
| `rules` | LIST OF OBJECTS | List of spending rule objects applied to the card. |
| `productId` | STRING | Id of the IssuingProduct associated with this card. |
| `tags` | LIST OF STRINGS | Tags associated with the card. |
| `streetLine1` | STRING | Primary line of the billing address. |
| `streetLine2` | STRING | Secondary line of the billing address. |
| `district` | STRING | District of the billing address. |
| `city` | STRING | City of the billing address. |
| `stateCode` | STRING | State code of the billing address. Example: "SP". |
| `zipCode` | STRING | ZIP code of the billing address. Example: "01311-000". |
| `type` | STRING | Card type. Options: "virtual", "physical". |
| `status` | STRING | Current card status. Options: "pending", "active", "blocked", "canceled", "expired". |
| `number` | STRING | Card number (PAN). Masked unless "expand=number" is informed in the request. |
| `securityCode` | STRING | Card security code (CVV). Masked unless "expand=securityCode" is informed in the request. |
| `expiration` | STRING | Card expiration datetime, the last instant of the card's expiration month. Example: "2029-07-31T23:59:59.999999+00:00". Masked unless "expand=expiration" is informed in the request. Same concept as the "expiration" parameter of Create Issuing Cards, which is informed as "YYYY-MM", not as a datetime. |
| `isPinDefined` | BOOLEAN | Whether the card has a PIN defined. Returned only when "expand=isPinDefined" is informed in the request. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create Issuing Cards

`POST /v2/issuing-card`

Use this route to create up to 100 new issuing cards at a time.

The billing address parameters (streetLine1, streetLine2, district, city, stateCode and zipCode) default to the sub-issuer's registered address when omitted.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `holderName` | REQUIRED | Name of the card holder. Example: "Tony Stark". |
| `holderTaxId` | REQUIRED | Tax id (CPF/CNPJ) of the card holder. Example: "012.345.678-90". |
| `holderExternalId` | REQUIRED | Unique id of the card holder in your system. Example: "my-holder-id-1234". |
| `productId` | OPTIONAL | Id of the IssuingProduct to use for this card. If omitted, a product is chosen automatically for the sub-issuer. |
| `type` | OPTIONAL | Card type. Options: "virtual", "physical". Default: "virtual". |
| `displayName` | OPTIONAL | Name to be displayed on the card. Example: "TONY STARK". |
| `rules` | OPTIONAL | List of spending rule objects to apply to the card. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. |
| `expiration` | OPTIONAL | Card expiration month, as a string in the "YYYY-MM" format. Example: "2029-07". It must be between 12 and 120 months ahead of the current month (both limits included), counted in Brasília time (America/Sao_Paulo). The card expires at the last instant of the informed month, for both virtual and physical cards. If omitted or null, the current behavior is kept: virtual cards get a generated expiration and physical cards get theirs at embossing. Physical cards: if the informed expiration is later than the maximum expiration allowed by the embossing provider's certificate, it is reduced to the last month that fits in the certificate at embossing. Otherwise it is kept as informed. The applied value is returned with "expand=expiration". Invalid values are rejected with a 400 "invalidExpiration" error. Causes: a non-string value, a format other than "YYYY-MM" (e.g. "07/29", "2029/07"), a month outside 01-12, or a month outside the 12-120 month window. |
| `streetLine1` | OPTIONAL | Primary line of the billing address. |
| `streetLine2` | OPTIONAL | Secondary line of the billing address. |
| `district` | OPTIONAL | District of the billing address. |
| `city` | OPTIONAL | City of the billing address. |
| `stateCode` | OPTIONAL | State code of the billing address. Example: "SP". |
| `zipCode` | OPTIONAL | ZIP code of the billing address. Example: "01311-000". |
| `expand` | OPTIONAL | Fields to return expanded in the response. Options: "rules", "securityCode", "number", "expiration", "isPinDefined". |

**Request**

```python
import starkinfra

cards = starkinfra.issuingcard.create([
    starkinfra.IssuingCard(
        holder_name="Tony Stark",
        holder_tax_id="012.345.678-90",
        holder_external_id="my-holder-id-1234",
        product_id="654321",
        type="virtual",
        display_name="TONY STARK",
        tags=["department: tech", "team: backend"]
    )
])

for card in cards:
    print(card)
```

**Response**

```python
IssuingCard(
    id=5715709195239424,
    holder_id=5155165527080960,
    holder_name=Tony Stark,
    holder_tax_id=012.345.678-90,
    holder_external_id=my-holder-id-1234,
    display_name=TONY STARK,
    product_id=654321,
    type=virtual,
    status=active,
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=10 andar,
    district=Itaim Bibi,
    city=Sao Paulo,
    state_code=SP,
    zip_code=01311-000,
    tags=['department: tech', 'team: backend'],
    number=**** **** **** 1234,
    security_code=***,
    expiration=****-**-**T**:**:**.******+00:00,
    is_pin_defined=False,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### List Issuing Cards

`GET /v2/issuing-card`

Get a list of issuing cards in chunks of at most 100.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `status` | OPTIONAL | Filter cards by the specified status. Options: "pending", "active", "blocked", "canceled", "expired". |
| `types` | OPTIONAL | Filter cards by type. Options: "virtual", "physical". |
| `holderIds` | OPTIONAL | Filter cards by holder ids. |
| `endings` | OPTIONAL | List of strings to filter cards by their last 4 digits. Max 30. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `expand` | OPTIONAL | Fields to return expanded in the response. Options: "rules", "securityCode", "number", "expiration", "isPinDefined". |

**Request**

```python
import starkinfra

cards = starkinfra.issuingcard.query(
    limit=10,
    status="active"
)

for card in cards:
    print(card)
```

**Response**

```python
IssuingCard(
    id=5715709195239424,
    holder_id=5155165527080960,
    holder_name=Tony Stark,
    holder_tax_id=012.345.678-90,
    holder_external_id=my-holder-id-1234,
    display_name=TONY STARK,
    product_id=654321,
    type=virtual,
    status=active,
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=10 andar,
    district=Itaim Bibi,
    city=Sao Paulo,
    state_code=SP,
    zip_code=01311-000,
    tags=['department: tech', 'team: backend'],
    number=**** **** **** 1234,
    security_code=***,
    expiration=****-**-**T**:**:**.******+00:00,
    is_pin_defined=False,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get an Issuing Card

`GET /v2/issuing-card/:id`

Get a single issuing card by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the issuing card entity. |
| `expand` | OPTIONAL | Fields to return expanded in the response. Options: "rules", "securityCode", "number", "expiration", "isPinDefined". |

**Request**

```python
import starkinfra

card = starkinfra.issuingcard.get("5715709195239424")

print(card)
```

**Response**

```python
IssuingCard(
    id=5715709195239424,
    holder_id=5155165527080960,
    holder_name=Tony Stark,
    holder_tax_id=012.345.678-90,
    holder_external_id=my-holder-id-1234,
    display_name=TONY STARK,
    product_id=654321,
    type=virtual,
    status=active,
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=10 andar,
    district=Itaim Bibi,
    city=Sao Paulo,
    state_code=SP,
    zip_code=01311-000,
    tags=['department: tech', 'team: backend'],
    number=**** **** **** 1234,
    security_code=***,
    expiration=****-**-**T**:**:**.******+00:00,
    is_pin_defined=False,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Update an Issuing Card

`PATCH /v2/issuing-card/:id`

Update the properties of an existing issuing card.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the issuing card entity. |
| `status` | OPTIONAL | Status to update the card to. Options: "active", "blocked". |
| `rules` | OPTIONAL | New list of spending rule objects to apply to the card. |
| `tags` | OPTIONAL | New array of strings to tag the card. |
| `displayName` | OPTIONAL | New display name for the card. |
| `pin` | OPTIONAL | Card PIN. Numeric string of 4 to 6 digits. Write-only — it is never returned; inform "expand=isPinDefined" to check whether a PIN is set. A pending physical card must receive a pin when you activate it (set status to "active"). |

**Request**

```python
import starkinfra

card = starkinfra.issuingcard.update(
    "5715709195239424",
    status="blocked",
    pin="1234",
    tags=["blocked-reason: fraud"]
)

print(card)
```

**Response**

```python
IssuingCard(
    id=5715709195239424,
    holder_id=5155165527080960,
    holder_name=Tony Stark,
    holder_tax_id=012.345.678-90,
    holder_external_id=my-holder-id-1234,
    display_name=TONY STARK,
    product_id=654321,
    type=virtual,
    status=blocked,
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=10 andar,
    district=Itaim Bibi,
    city=Sao Paulo,
    state_code=SP,
    zip_code=01311-000,
    tags=['blocked-reason: fraud'],
    number=**** **** **** 1234,
    security_code=***,
    expiration=****-**-**T**:**:**.******+00:00,
    is_pin_defined=False,
    created=2022-01-01 00:00:00,
    updated=2022-06-01 00:00:00
)
```

### Cancel an Issuing Card

`DELETE /v2/issuing-card/:id`

Cancel an issuing card. This action is irreversible.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the issuing card entity to cancel. |

**Request**

```python
import starkinfra

card = starkinfra.issuingcard.cancel("5715709195239424")

print(card)
```

**Response**

```python
IssuingCard(
    id=5715709195239424,
    holder_id=5155165527080960,
    holder_name=Tony Stark,
    holder_tax_id=012.345.678-90,
    holder_external_id=my-holder-id-1234,
    display_name=TONY STARK,
    product_id=654321,
    type=virtual,
    status=canceled,
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=10 andar,
    district=Itaim Bibi,
    city=Sao Paulo,
    state_code=SP,
    zip_code=01311-000,
    tags=['department: tech', 'team: backend'],
    number=**** **** **** 1234,
    security_code=***,
    expiration=****-**-**T**:**:**.******+00:00,
    is_pin_defined=False,
    created=2022-01-01 00:00:00,
    updated=2022-06-01 00:00:00
)
```

### List Issuing Card Logs

`GET /v2/issuing-card/log`

Get a paged list of issuing card logs.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `types` | OPTIONAL | Filter logs by log types. |
| `cardIds` | OPTIONAL | Array of card ids to filter logs. |
| `ids` | OPTIONAL | List of strings to get specific log entities by ids. |

**Request**

```python
import starkinfra

logs = starkinfra.issuingcard.log.query(
    limit=10,
    types=["blocked"]
)

for log in logs:
    print(log)
```

**Response**

```python
Log(
    id=6724771005489152,
    type=blocked,
    card=IssuingCard(id=5715709195239424, status=blocked),
    created=2022-01-01 00:00:00
)
```

### Get an Issuing Card Log

`GET /v2/issuing-card/log/:id`

Get a single issuing card log by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the log entity. |

**Request**

```python
import starkinfra

log = starkinfra.issuingcard.log.get("6724771005489152")

print(log)
```

**Response**

```python
Log(
    id=6724771005489152,
    type=blocked,
    card=IssuingCard(id=5715709195239424, status=blocked),
    created=2022-01-01 00:00:00
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

- [Python](https://docs.starkinfra.com/api/v2/issuing-card-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/issuing-card-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/issuing-card-php.md)
- [Java](https://docs.starkinfra.com/api/v2/issuing-card-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/issuing-card-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/issuing-card-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/issuing-card-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/issuing-card-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/issuing-card-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/issuing-card-curl.md)