# Corporate Purchase

The Corporate Purchase resource displays the purchases made with the corporate cards issued in your Workspace.

You never create a purchase yourself. A purchase shows up when a cardholder pays at a merchant and the authorization request reaches us: we check it against the card and holder rules, answer the card network and register the resulting purchase here.

All amounts are integers in cents. When the purchase is made in another currency, the same money is recorded twice: merchantAmount (in merchantCurrencyCode) is what the merchant charged and issuerAmount (in issuerCurrencyCode) is what was debited from your corporate balance after conversion, with the IOF in tax.

You can list purchases, get a single purchase by its id, update its description and tags and follow its whole life cycle through the logs.

### The Corporate Purchase object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the corporate purchase. Example: "5353197895942144". |
| `amount` | INTEGER | Purchase amount in cents. Minimum = 0. Example: 12345 (R$123.45). |
| `attachments` | LIST OF OBJECTS | List of attachment objects linked to the purchase, each one with an id and a name. |
| `cardEnding` | STRING | Last 4 digits of the card number used in the purchase. Example: "1234". |
| `cardId` | STRING | Id of the corporate card used in the purchase. Example: "5671893688385536". |
| `centerId` | STRING | Id of the cost center the purchase was charged to. Empty string when the holder has no cost center. Example: "5656565656565656". |
| `centerName` | STRING | Name of the cost center the purchase was charged to. Returned only when you pass expand=centerName. Example: "Engineering". |
| `corporateTransactionIds` | LIST OF STRINGS | Ids of the corporate ledger transactions linked to this purchase. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `description` | STRING | Purchase description. Empty string until you set one. Example: "Team lunch". |
| `holderId` | STRING | Id of the cardholder. Example: "5917814565109760". |
| `holderName` | STRING | Name of the cardholder. Example: "Tony Stark". |
| `installmentCount` | INTEGER | Number of installments the purchase was split into. Example: 1. |
| `issuerAmount` | INTEGER | Amount in cents in the issuer currency, debited from your corporate balance. Example: 12345 (R$123.45). |
| `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. Example: 12345 (R$123.45). |
| `merchantCategoryCode` | STRING | Merchant category code (MCC) of the purchase. Example: "fastFoodRestaurants". |
| `merchantCategoryNumber` | STRING | Number of the merchant category code. Example: "5814". |
| `merchantCategoryType` | STRING | Type of the merchant category. Example: "food". |
| `merchantCountryCode` | STRING | ISO 3166 country code of the merchant. Example: "BRA". |
| `merchantCurrencyCode` | STRING | ISO 4217 currency code of the merchant. Example: "BRL". |
| `merchantCurrencySymbol` | STRING | Currency symbol of the merchant. Example: "R$". |
| `merchantDisplayName` | STRING | Merchant name ready to be displayed to your users. Falls back to the merchant category name followed by the merchant id when the merchant name is unknown. Example: "COMPANY 123". |
| `merchantDisplayUrl` | STRING | Public URL of the merchant icon (png image). Example: "https://sandbox.api.starkbank.com/v2/corporate-icon/type/food.png". |
| `merchantFee` | INTEGER | Fee charged by the merchant in cents to cover specific costs, such as ATM withdrawal logistics. Example: 200 (R$2.00). |
| `merchantName` | STRING | Merchant name as informed by the card network. Example: "COMPANY 123". |
| `methodCode` | STRING | Method used in the purchase. Options: "ocr", "chip", "token", "server", "manual", "unknown", "barcode", "magstripe", "contactless". |
| `status` | STRING | Current purchase status. Options: "approved", "canceled", "denied", "confirmed", "voided". |
| `tags` | LIST OF STRINGS | Tags associated with the purchase. Example: ["travel", "food"]. |
| `tax` | INTEGER | IOF amount in cents taxed on international purchases. Example: 638 (R$6.38). |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### List Corporate Purchases

`GET /v2/corporate-purchase`

Use this route to get a list of corporate purchases in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. Example: "2022-01-01". |
| `before` | OPTIONAL | Filter entities created before this date. Example: "2022-01-20". |
| `cardIds` | OPTIONAL | Filter purchases by the ids of the cards used. Max = 30 ids. |
| `centerIds` | OPTIONAL | Filter purchases by the ids of the cost centers they were charged to. Max = 30 ids. Not available in the SDKs. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `expand` | OPTIONAL | List of strings to add extra keys to the response JSON. Options: "centerName". Not available in the SDKs. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `holderIds` | OPTIONAL | Filter purchases by the ids of the cardholders. Max = 30 ids. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. Max = 100 ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. Default = 100. |
| `merchantCategoryTypes` | OPTIONAL | Filter purchases by the types of the merchant categories. Example: "food", "health", "transportation". |
| `status` | OPTIONAL | Filter purchases by the specified status. Options: "approved", "canceled", "denied", "confirmed", "voided". |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. Max = 30 tags. Not available in the SDKs. |

**Request**

```python
import starkbank

purchases = starkbank.corporatepurchase.query(
    after="2022-01-01",
    before="2022-01-20",
    limit=10
)

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

**Response**

```python
CorporatePurchase(
    amount=12345,
    card_ending=1234,
    card_id=5671893688385536,
    center_id=5656565656565656,
    corporate_transaction_ids=['5415434763141120'],
    created=2022-01-01 00:00:00,
    description=Team lunch,
    holder_id=5917814565109760,
    holder_name=Tony Stark,
    id=5353197895942144,
    issuer_amount=12345,
    issuer_currency_code=BRL,
    issuer_currency_symbol=R$,
    merchant_amount=12345,
    merchant_category_code=fastFoodRestaurants,
    merchant_category_type=food,
    merchant_country_code=BRA,
    merchant_currency_code=BRL,
    merchant_currency_symbol=R$,
    merchant_display_name=COMPANY 123,
    merchant_display_url=https://sandbox.api.starkbank.com/v2/corporate-icon/type/food.png,
    merchant_fee=0,
    merchant_name=COMPANY 123,
    method_code=chip,
    status=approved,
    tags=['travel', 'food'],
    tax=0,
    updated=2022-01-01 00:00:00
)
```

### Get a Corporate Purchase

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

Use this route to get a single corporate purchase by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the corporate purchase entity. Example: "5353197895942144". |
| `expand` | OPTIONAL | List of strings to add extra keys to the response JSON. Options: "centerName". Not available in the SDKs. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

purchase = starkbank.corporatepurchase.get("5353197895942144")

print(purchase)
```

**Response**

```python
CorporatePurchase(
    amount=12345,
    card_ending=1234,
    card_id=5671893688385536,
    center_id=5656565656565656,
    corporate_transaction_ids=['5415434763141120'],
    created=2022-01-01 00:00:00,
    description=Team lunch,
    holder_id=5917814565109760,
    holder_name=Tony Stark,
    id=5353197895942144,
    issuer_amount=12345,
    issuer_currency_code=BRL,
    issuer_currency_symbol=R$,
    merchant_amount=12345,
    merchant_category_code=fastFoodRestaurants,
    merchant_category_type=food,
    merchant_country_code=BRA,
    merchant_currency_code=BRL,
    merchant_currency_symbol=R$,
    merchant_display_name=COMPANY 123,
    merchant_display_url=https://sandbox.api.starkbank.com/v2/corporate-icon/type/food.png,
    merchant_fee=0,
    merchant_name=COMPANY 123,
    method_code=chip,
    status=approved,
    tags=['travel', 'food'],
    tax=0,
    updated=2022-01-01 00:00:00
)
```

### Update a Corporate Purchase

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

Use this route to update the description and the tags of a corporate purchase. A purchase is settled by the card network, so every other field is read-only.

**NOTE:**Each update creates an updated log, and the request body must contain at least one of description or tags.

This route is not yet mapped by our SDKs.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the corporate purchase entity. Example: "5353197895942144". |
| `description` | OPTIONAL | New description for the purchase. Max of 140 characters. Example: "Team lunch". |
| `tags` | OPTIONAL | New array of strings to tag the purchase. Max of 100 tags of up to 100 characters each. All tags will be converted to lowercase. |

**Request**

```python
import starkbank

purchase = starkbank.request.patch(
    path="/corporate-purchase/5353197895942144",
    body={
        "description": "Team lunch",
        "tags": ["travel", "food"]
    }
).json()

print(purchase)
```

**Response**

```python
{
    'message': 'Purchase successfully updated.',
    'purchase': {
        'amount': 12345,
        'attachments': [],
        'cardEnding': '1234',
        'cardId': '5671893688385536',
        'centerId': '5656565656565656',
        'corporateTransactionIds': ['5415434763141120'],
        'created': '2022-01-01T00:00:00.000000+00:00',
        'description': 'Team lunch',
        'holderId': '5917814565109760',
        'holderName': 'Tony Stark',
        'id': '5353197895942144',
        'installmentCount': 1,
        'issuerAmount': 12345,
        'issuerCurrencyCode': 'BRL',
        'issuerCurrencySymbol': 'R$',
        'merchantAmount': 12345,
        'merchantCategoryCode': 'fastFoodRestaurants',
        'merchantCategoryNumber': '5814',
        'merchantCategoryType': 'food',
        'merchantCountryCode': 'BRA',
        'merchantCurrencyCode': 'BRL',
        'merchantCurrencySymbol': 'R$',
        'merchantDisplayName': 'COMPANY 123',
        'merchantDisplayUrl': 'https://sandbox.api.starkbank.com/v2/corporate-icon/type/food.png',
        'merchantFee': 0,
        'merchantName': 'COMPANY 123',
        'methodCode': 'chip',
        'status': 'approved',
        'tags': ['travel', 'food'],
        'tax': 0,
        'updated': '2022-01-02T12:30:00.000000+00:00'
    }
}
```

### List Corporate Purchase Logs

`GET /v2/corporate-purchase/log`

Use this route to get a paged list of corporate purchase logs. A log tracks a change in the corporate purchase entity according to its life cycle.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. Example: "2022-01-01". |
| `before` | OPTIONAL | Filter entities created before this date. Example: "2022-01-20". |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. Default = 100. |
| `purchaseIds` | OPTIONAL | Array of corporate purchase ids that are linked to the logs you desire. Max = 30 ids. |
| `types` | OPTIONAL | Filters logs by log types. Options: "approved", "denied", "canceled", "confirmed", "reversed", "voided", "updated". |

**Request**

```python
import starkbank

logs = starkbank.corporatepurchase.log.query(
    purchase_ids=["5353197895942144"],
    limit=10
)

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

**Response**

```python
Log(
    corporate_transaction_id=5415434763141120,
    created=2022-01-01 00:00:00,
    description=Purchase approved: R$ 123,45.,
    errors=[],
    id=6531653149130752,
    purchase=CorporatePurchase(amount=12345, card_id=5671893688385536, holder_name=Tony Stark, ...),
    type=approved
)
```

### Get a Corporate Purchase Log

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

Use this route to get a single corporate purchase log by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the log entity. Example: "6531653149130752". |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

log = starkbank.corporatepurchase.log.get("6531653149130752")

print(log)
```

**Response**

```python
Log(
    corporate_transaction_id=5415434763141120,
    created=2022-01-01 00:00:00,
    description=Purchase approved: R$ 123,45.,
    errors=[],
    id=6531653149130752,
    purchase=CorporatePurchase(amount=12345, card_id=5671893688385536, holder_name=Tony Stark, ...),
    type=approved
)
```

## Available Languages

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

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