# Issuing Purchase

The Issuing Purchase resource represents a purchase transaction made with an issuing card.

Purchases are created when a cardholder makes a payment at a merchant using an issued card.

You can list, retrieve, and update purchases, as well as monitor purchase events through the log endpoints.

### The Issuing Purchase object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing purchase. |
| `productId` | STRING | Id of the IssuingProduct of the card used in the purchase. |
| `holderName` | STRING | Name of the cardholder. |
| `cardId` | STRING | Id of the IssuingCard used for the purchase. |
| `amount` | INTEGER | Purchase amount in cents in the issuer currency. |
| `tax` | INTEGER | Tax amount in cents charged on the purchase. |
| `issuerAmount` | INTEGER | Amount in cents in the issuer currency. |
| `issuerCurrencyCode` | STRING | ISO 4217 currency code of the issuer. Example: "BRL". |
| `issuerCurrencySymbol` | STRING | Currency symbol of the issuer. Example: "R$". |
| `merchantAmount` | INTEGER | Amount in cents in the merchant currency. |
| `merchantCurrencyCode` | STRING | ISO 4217 currency code of the merchant. Example: "USD". |
| `merchantCurrencySymbol` | STRING | Currency symbol of the merchant. Example: "$". |
| `merchantCategoryCode` | STRING | Merchant category code (MCC) for the purchase. |
| `merchantCategoryNumber` | STRING | MCC number of the merchant category. Example: "5814". |
| `merchantCategoryType` | STRING | Type of the merchant category. Example: "food". |
| `merchantCountryCode` | STRING | ISO 3166 country code of the merchant. Example: "BRA". |
| `acquirerId` | STRING | Id of the payment acquirer. |
| `merchantId` | STRING | Id of the merchant. |
| `merchantName` | STRING | Name of the merchant. |
| `merchantFee` | INTEGER | Merchant fee in cents. |
| `walletId` | STRING | Id of the digital wallet used if this was a token purchase. |
| `methodCode` | STRING | Payment method code. Options: "chip", "token", "server", "manual", "magstripe", "contactless". |
| `score` | FLOAT | Fraud risk score from 0 to 1. Higher values indicate higher risk. |
| `endToEndId` | STRING | End-to-end transaction identifier. |
| `tags` | LIST OF STRINGS | Tags associated with the purchase. |
| `zipCode` | STRING | ZIP code of the merchant location. |
| `issuingTransactionIds` | LIST OF STRINGS | Ids of the IssuingTransactions linked to this purchase. |
| `purpose` | STRING | Purchase purpose. Options: "purchase", "withdrawal", "verification", "purchaseRefund", "cashbackPurchase", "paymentTransaction". |
| `installmentCount` | INTEGER | Number of installments of the purchase. Example: 1. |
| `cardEnding` | STRING | Last 4 digits of the card number used. |
| `metadata` | OBJECT | Additional data related to the purchase, such as the authorizationId. |
| `description` | STRING | Purchase description provided by the merchant. |
| `confirmed` | STRING | Confirmation datetime. Null until the purchase is confirmed. |
| `status` | STRING | Current purchase status. Options: "approved", "canceled", "denied", "confirmed", "voided". |
| `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". |

### List Issuing Purchases

`GET /v2/issuing-purchase`

Get a list of issuing purchases 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 purchases by the specified status. |
| `cardIds` | OPTIONAL | Filter purchases by card ids. |
| `holderIds` | OPTIONAL | Filter purchases by holder ids. |
| `endToEndIds` | OPTIONAL | Filter purchases by their end-to-end transaction ids. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |

**Request**

```python
import starkinfra

purchases = starkinfra.issuingpurchase.query(
    limit=10,
    status="approved"
)

for purchase in purchases:
    print(purchase)
```

**Response**

```python
IssuingPurchase(
    id=5715709195239424,
    holder_name=Tony Stark,
    product_id=654321,
    card_id=7834882116598271,
    card_ending=1234,
    purpose=purchase,
    installment_count=1,
    amount=5000,
    tax=0,
    issuer_amount=5000,
    issuer_currency_code=BRL,
    issuer_currency_symbol=R$,
    merchant_amount=5000,
    merchant_currency_code=BRL,
    merchant_currency_symbol=R$,
    merchant_category_code=fastFoodRestaurants,
    merchant_category_number=5814,
    merchant_category_type=food,
    merchant_country_code=BRA,
    acquirer_id=5656565656565656,
    merchant_id=5656565656565656,
    merchant_name=Stark Store,
    merchant_fee=0,
    wallet_id=None,
    method_code=chip,
    score=0.9775689825217906,
    end_to_end_id=79fcf95d-1dfb-40db-9fa8-679e329c58f0,
    tags=[],
    issuing_transaction_ids=['5155165527080960'],
    status=approved,
    description=,
    metadata={},
    zip_code=01311-000,
    confirmed=2022-01-01 00:00:02,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get an Issuing Purchase

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

Get a single issuing purchase by its id.

**Parameters**

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

**Request**

```python
import starkinfra

purchase = starkinfra.issuingpurchase.get("5715709195239424")

print(purchase)
```

**Response**

```python
IssuingPurchase(
    id=5715709195239424,
    holder_name=Tony Stark,
    product_id=654321,
    card_id=7834882116598271,
    card_ending=1234,
    purpose=purchase,
    installment_count=1,
    amount=5000,
    tax=0,
    issuer_amount=5000,
    issuer_currency_code=BRL,
    issuer_currency_symbol=R$,
    merchant_amount=5000,
    merchant_currency_code=BRL,
    merchant_currency_symbol=R$,
    merchant_category_code=fastFoodRestaurants,
    merchant_category_number=5814,
    merchant_category_type=food,
    merchant_country_code=BRA,
    acquirer_id=5656565656565656,
    merchant_id=5656565656565656,
    merchant_name=Stark Store,
    merchant_fee=0,
    wallet_id=None,
    method_code=chip,
    score=0.9775689825217906,
    end_to_end_id=79fcf95d-1dfb-40db-9fa8-679e329c58f0,
    tags=[],
    issuing_transaction_ids=['5155165527080960'],
    status=approved,
    description=,
    metadata={},
    zip_code=01311-000,
    confirmed=2022-01-01 00:00:02,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Update an Issuing Purchase

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

Update the tags of an existing issuing purchase.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the issuing purchase entity. |
| `tags` | OPTIONAL | New array of strings to tag the purchase. |
| `description` | OPTIONAL | New description for the purchase. Max of 140 characters. |

**Request**

```python
import starkinfra

purchase = starkinfra.issuingpurchase.update(
    "5715709195239424",
    tags=["reconciled", "month: january"]
)

print(purchase)
```

**Response**

```python
IssuingPurchase(
    id=5715709195239424,
    holder_name=Tony Stark,
    product_id=654321,
    card_id=7834882116598271,
    card_ending=1234,
    purpose=purchase,
    installment_count=1,
    amount=5000,
    tax=0,
    issuer_amount=5000,
    issuer_currency_code=BRL,
    issuer_currency_symbol=R$,
    merchant_amount=5000,
    merchant_currency_code=BRL,
    merchant_currency_symbol=R$,
    merchant_category_code=fastFoodRestaurants,
    merchant_category_number=5814,
    merchant_category_type=food,
    merchant_country_code=BRA,
    acquirer_id=5656565656565656,
    merchant_id=5656565656565656,
    merchant_name=Stark Store,
    merchant_fee=0,
    wallet_id=None,
    method_code=chip,
    score=0.9775689825217906,
    end_to_end_id=79fcf95d-1dfb-40db-9fa8-679e329c58f0,
    tags=['reconciled', 'month: january'],
    issuing_transaction_ids=['5155165527080960'],
    status=approved,
    description=,
    metadata={},
    zip_code=01311-000,
    confirmed=2022-01-01 00:00:02,
    created=2022-01-01 00:00:00,
    updated=2022-06-01 00:00:00
)
```

### List Issuing Purchase Logs

`GET /v2/issuing-purchase/log`

Get a paged list of issuing purchase 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. |
| `purchaseIds` | OPTIONAL | Array of purchase ids to filter logs. |

**Request**

```python
import starkinfra

logs = starkinfra.issuingpurchase.log.query(
    limit=10,
    types=["approved"]
)

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

**Response**

```python
Log(
    id=6724771005489152,
    type=approved,
    purchase=IssuingPurchase(id=5715709195239424, amount=5000, status=approved),
    created=2022-01-01 00:00:00
)
```

### Get an Issuing Purchase Log

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

Get a single issuing purchase log by its id.

**Parameters**

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

**Request**

```python
import starkinfra

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

print(log)
```

**Response**

```python
Log(
    id=6724771005489152,
    type=approved,
    purchase=IssuingPurchase(id=5715709195239424, amount=5000, status=approved),
    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-purchase-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/issuing-purchase-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/issuing-purchase-php.md)
- [Java](https://docs.starkinfra.com/api/v2/issuing-purchase-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/issuing-purchase-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/issuing-purchase-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/issuing-purchase-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/issuing-purchase-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/issuing-purchase-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/issuing-purchase-curl.md)