# Merchant Session

The Merchant Session resource can be created by a merchant and used by the card holder in order to collect their card data without having to handle it on the merchant's side.

The card data can be sent directly from a browser or app to Stark Bank's API using the Merchant Session Purchase route.

### The Merchant Session object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the merchant session. |
| `allowedFundingTypes` | LIST OF STRINGS | Funding types allowed for the purchase. Options: "credit", "debit". |
| `allowedInstallments` | LIST OF OBJECTS | Installment configurations allowed for the purchase. |
| `allowedIps` | LIST OF STRINGS | IP addresses allowed to create a purchase. |
| `challengeMode` | STRING | Holder verification (3DS) mode. Options: "enabled", "disabled". |
| `confirmationMode` | STRING | Purchase confirmation mode. Options: "automatic", "manual". |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `expiration` | INTEGER | Time in seconds until the session expires, from 60 to 86400. |
| `holderId` | STRING | Your identifier for the card holder. |
| `softDescriptor` | STRING | Text shown on the card holder's statement. |
| `status` | STRING | Current session status. Options: "created", "expired", "success", "voided". |
| `tags` | LIST OF STRINGS | Tags associated with the session. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `uuid` | STRING | Unique UUID for the session. |

### Create Merchant Sessions

`POST /v2/merchant-session`

This route allows the merchant to create a session that can be used by the card holder's application to create a new purchase.

The UUID parameter returned by the session should be used to create a Merchant Session Purchase.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `allowedFundingTypes` | REQUIRED | The types of funding that are allowed to be used for the purchase. Options are "credit" and "debit". |
| `allowedInstallments` | REQUIRED | List of installment options allowed for the purchase. Each option is an object with totalAmount, a non-negative integer that represents the total amount in cents to be received (E.g.: 100 (R$1.00)), and count, the number of installments. When an option has more than one installment, each installment must be at least 500 (R$5.00): totalAmount divided by count cannot be lower than 500. |
| `expiration` | REQUIRED | Time in seconds counted from the creation datetime until the session expires. Must be between 60 and 86400 (24 hours). After expiration, a purchase cannot be created using the session anymore. A purchase already created keeps its own deadline. E.g.: 3600 (1 hour). |
| `allowedIps` | OPTIONAL | Up to 100 IP addresses that are allowed to create a purchase using the session. A purchase created from any other IP is rejected with the ipNotAllowed error. If omitted, any IP can create the purchase. |
| `challengeMode` | OPTIONAL | Defines whether a holder verification (3DS) will be used to authorize the purchase. 3DS is a protocol designed to enhance security for e-commerce purchases: the card issuer authenticates the card holder during checkout and, when the authentication succeeds, the liability for fraud chargebacks shifts from you to the issuer. When enabled, the purchase is created with status "pending" and returns a token. Your front-end uses this token with the Stark 3DS SDK to authenticate the card holder, and your backend completes the purchase with POST /v2/merchant-purchase/:id/challenge. Options are "enabled" and "disabled". Default: "disabled" |
| `confirmationMode` | OPTIONAL | Defines how the purchases created with the session are confirmed. With "automatic", approved purchases are confirmed automatically. With "manual" (pre-authorization), the amount stays authorized on the card and the purchase remains approved until you confirm it with PATCH /v2/merchant-purchase/:id. Manual confirmation is only available for credit purchases, so it cannot be used when "debit" is in allowedFundingTypes, and it is not allowed for zero dollar purchases. Options are "automatic" and "manual". Default: "automatic" |
| `holderId` | OPTIONAL | Your identifier for the card holder, from 1 to 50 characters. It can be used to filter sessions and purchases. It will soon become required, so we recommend sending it already. |
| `softDescriptor` | OPTIONAL | Text shown on the card holder's statement, from 1 to 16 characters. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

**Request**

```python
import starkbank
from starkbank.merchantsession import AllowedInstallment

allowed_installments = [
    AllowedInstallment(total_amount=5000, count=1),
    AllowedInstallment(total_amount=5500, count=2)
]

merchant_session = starkbank.MerchantSession(
    allowed_funding_types=["debit", "credit"],
    allowed_installments=allowed_installments,
    expiration=3600,
    challenge_mode="disabled",
    tags=["session_123"]
)

print(starkbank.merchantsession.create(merchant_session))
```

**Response**

```python
MerchantSession(
    allowed_funding_types=['debit', 'credit'],
    allowed_installments=[
        AllowedInstallment(
            count=1,
            total_amount=5000
        ),
        AllowedInstallment(
            count=2,
            total_amount=5500
        )
    ],
    allowed_ips=[],
    challenge_mode=disabled,
    created=2025-02-20 19:34:45.818681,
    expiration=3600,
    id=4932221869752320,
    status=created,
    tags=['session_123'],
    updated=2025-02-20 19:34:45.827862,
    uuid=cc80706d85c5438b9fbe02085daf5315
)
```

### Create Merchant Session Purchase

`POST /v2/merchant-session/:uuid/purchase`

This route can be used to create a Merchant Purchase directly from the payer's client application.

The UUID of a Merchant Session that was previously created by the merchant is necessary to access this route.

This route is currently not available in the SDKs. Your front-end must call "POST /v2/merchant-session/:uuid/purchase" directly on the Stark Bank API.

If the session was created with challengeMode "enabled", the purchase is returned with status "pending" along with a token object. Your front-end uses token.accessToken with the Stark 3DS SDK to authenticate the card holder, and your backend completes the purchase with POST /v2/merchant-purchase/:id/challenge. A pending purchase that is not completed within one hour fails and must be created again.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `amount` | REQUIRED | A non-negative integer that represents the amount in cents to be received. E.g: 100 (R$1.00) |
| `cardExpiration` | REQUIRED | A string in the format YYYY-MM representing the expiration of the card to be used for the purchase. |
| `cardNumber` | REQUIRED | A string representing the number of the card to be used for the purchase. |
| `cardSecurityCode` | REQUIRED | A string representing the security code of the card to be used for the purchase. |
| `fundingType` | REQUIRED | The type of funding to be used for the purchase. Options are "credit" and "debit". |
| `holderName` | REQUIRED | The name of the card holder as it appears on the card. |
| `uuid` | REQUIRED | The UUID of the Merchant Session created by the merchant to process the purchase. |
| `holderEmail` | CONDITIONALLY REQUIRED | The email associated with the holder of the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise. |
| `holderPhone` | CONDITIONALLY REQUIRED | The phone number associated with the holder of the card used for the purchase, digits only and with the area code. Required if challengeMode is "enabled" and optional otherwise. |
| `billingCity` | OPTIONAL | The billing city associated with the card used for the purchase. Optional, but recommended when challengeMode is "enabled": the issuer uses it to assess the risk of the purchase. |
| `billingCountryCode` | OPTIONAL | The billing country code associated with the card used for the purchase. Optional, but recommended when challengeMode is "enabled": the issuer uses it to assess the risk of the purchase. |
| `billingStateCode` | OPTIONAL | The two-letter billing state code associated with the card used for the purchase. E.g.: "SP". Optional, but recommended when challengeMode is "enabled": the issuer uses it to assess the risk of the purchase. |
| `billingStreetLine1` | OPTIONAL | The billing street address associated with the card used for the purchase. Optional, but recommended when challengeMode is "enabled": the issuer uses it to assess the risk of the purchase. |
| `billingStreetLine2` | OPTIONAL | The billing street address complement associated with the card used for the purchase. Optional, but recommended when challengeMode is "enabled": the issuer uses it to assess the risk of the purchase. |
| `billingZipCode` | OPTIONAL | The billing zip code associated with the card used for the purchase. Optional, but recommended when challengeMode is "enabled": the issuer uses it to assess the risk of the purchase. |
| `installmentCount` | OPTIONAL | A positive integer that represents the number of purchase installments. Must match one of the session's allowedInstallments. Debit purchases always have 1 installment. Default: 1 |
| `metadata` | OPTIONAL | An object with data about the payer's device: userAgent, userIp, language, timezoneOffset, screenHeight and screenWidth. Optional, but recommended when challengeMode is "enabled": the issuer uses it to assess the risk of the purchase. |

### List Merchant Sessions

`GET /v2/merchant-session`

Get a list of merchant sessions 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. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `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. |
| `holderId` | OPTIONAL | Filter sessions by the holderId informed on creation. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter sessions by the specified status, such as: created, expired, success, voided. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

**Request**

```python
import starkbank

merchant_sessions = starkbank.merchantsession.query(after= "2025-01-01", before= "2025-03-01")

for merchant_session in merchant_sessions:
    print(merchant_session)
```

**Response**

```python
MerchantSession(
    allowed_funding_types=['credit', 'debit'],
    allowed_installments=[
        AllowedInstallment(
            count=1,
            total_amount=5000
        ),
        AllowedInstallment(
            count=2,
            total_amount=5500
        )
    ],
    allowed_ips=[],
    challenge_mode=enabled,
    created=2025-01-03 15:47:08.879093,
    expiration=3600,
    id=5739291523153920,
    status=success,
    tags=[],
    updated=2025-01-03 15:47:41.826546,
    uuid=281319fce4f149acb71044e2f305953d
)
```

### Get a Merchant Session

`GET /v2/merchant-session/:id`

Retrieve detailed information about a specific session by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | The unique identifier for the merchant session that needs to be retrieved. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

merchant_session = starkbank.merchantsession.get('5739291523153920')
print(merchant_session)
```

**Response**

```python
MerchantSession(
    allowed_funding_types=['credit', 'debit'],
    allowedInstallments=[
        AllowedInstallment(
            count=1,
            total_amount=5000
        ),
        AllowedInstallment(
            count=2,
            total_amount=5500
        )
    ],
    allowed_ips=[],
    challenge_mode=enabled,
    created=2025-01-03 15:47:08.879093,
    expiration=3600,
    id=5739291523153920,
    status=success,
    tags=[],
    updated=2025-01-03 15:47:41.826546,
    uuid=281319fce4f149acb71044e2f305953d
)
```

### List Merchant Session Logs

`GET /v2/merchant-session/log`

Get a paged list of merchant session logs.

A log tracks a change in the session entity according to its life cycle.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `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. |
| `sessionIds` | OPTIONAL | Filter the merchant session ids to only include its corresponding logs |
| `types` | OPTIONAL | Filters logs by log types. |

**Request**

```python
import starkbank

merchant_session_logs = starkbank.merchantsession.log.query(limit=1)
for log in merchant_session_logs:
    print(log)
```

**Response**

```python
Log(
    created=2025-02-21 22:30:11.107220,
    errors=[],
    id=6206771064471552,
    session=MerchantSession(
        allowed_funding_types=['debit', 'credit'],
        allowed_installments=[
            AllowedInstallment(
                count=1,
                total_amount=5000
            ),
            AllowedInstallment(
                count=2,
                total_amount=5500
            )
        ],
        allowed_ips=[],
        challenge_mode=enabled,
        created=2025-02-21 22:30:11.080441,
        expiration=3600,
        id=5080871157628928,
        status=created,
        tags=['stark', 'suit'],
        updated=2025-02-21 22:30:11.233107,
        uuid=ffc2e83962f14424833b96776dcaed83
    ),
    type=created
)
```

### Get a Merchant Session Log

`GET /v2/merchant-session/log/:id`

Get a single merchant session log by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | The unique identifier for the merchant session that needs to be retrieved. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

log = starkbank.merchantsession.log.get('5950134772826112')
print(log)
```

**Response**

```python
Log(
    created=2025-02-21 22:30:11.107220,
    errors=[],
    id=6206771064471552,
    session=MerchantSession(
        allowed_funding_types=['debit', 'credit'],
        allowed_installments=[
            AllowedInstallment(
                count=1,
                total_amount=5000
            ),
            AllowedInstallment(
                count=2,
                total_amount=5500
            )
        ],
        allowed_ips=[],
        challenge_mode=disabled,
        created=2025-02-21 22:30:11.080441,
        expiration=3600,
        id=5080871157628928,
        status=created,
        tags=['stark', 'suit'],
        updated=2025-02-21 22:30:11.233107,
        uuid=ffc2e83962f14424833b96776dcaed83
    ),
    type=created
)
```

## 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/merchant-session-python.md)
- [Node.js](https://docs.starkbank.com/api/v2/merchant-session-node.md)
- [PHP](https://docs.starkbank.com/api/v2/merchant-session-php.md)
- [Java](https://docs.starkbank.com/api/v2/merchant-session-java.md)
- [Ruby](https://docs.starkbank.com/api/v2/merchant-session-ruby.md)
- [Elixir](https://docs.starkbank.com/api/v2/merchant-session-elixir.md)
- [.NET](https://docs.starkbank.com/api/v2/merchant-session-dotnet.md)
- [Go](https://docs.starkbank.com/api/v2/merchant-session-go.md)
- [Clojure](https://docs.starkbank.com/api/v2/merchant-session-clojure.md)
- [cURL](https://docs.starkbank.com/api/v2/merchant-session-curl.md)