### Authenticate with HTTP Basic Auth

Source: https://docs.esto.eu/?region=lv

Example of using curl to authenticate a POST request to the purchase endpoint.

```bash
curl -u your-shop-id:your-secret-key \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"amount": 91.89, "reference": "order-1234"}' \
  https://api.esto.lv/v2/purchase
```

--------------------------------

### Create Payment

Source: https://docs.esto.eu/?region=lv

Initiates a new payment transaction by providing the amount, reference, customer information, and callback URLs.

```APIDOC
## POST /payments

### Description
Initiates a new payment transaction.

### Request Body
- **amount** (number) - Required - The total amount of the transaction.
- **reference** (string) - Required - A unique reference for the transaction.
- **return_url** (string) - Required - URL to redirect the user after payment.
- **notification_url** (string) - Required - URL for server-to-server notifications.
- **cancel_url** (string) - Required - URL to redirect the user if payment is cancelled.
- **connection_mode** (string) - Required - The mode of the connection (e.g., "live").
- **schedule_type** (string) - Required - The type of schedule (e.g., "REGULAR").
- **items** (array) - Required - List of items being purchased.
- **customer** (object) - Required - Customer details including first_name, last_name, email, phone, address, city, and post_code.
- **cashier_id** (number) - Optional - ID of the cashier.
- **store_id** (number) - Required - ID of the store.

### Request Example
{
  "amount": 91.89,
  "reference": "fwejigjwe8g32g3jg",
  "return_url": "https://your-site.com/return",
  "notification_url": "https://your-site.com/notification",
  "cancel_url": "https://your-site.com/cancel",
  "connection_mode": "live",
  "schedule_type": "REGULAR",
  "items": [
    { "name": "Bitcoin 101", "unit_price": 30.3, "quantity": 3 },
    { "name": "The One Ring", "unit_price": 0.99, "quantity": 1 }
  ],
  "customer": {
    "first_name": "BoJack",
    "last_name": "Horseman",
    "email": "email@address.com",
    "phone": "567891234",
    "address": "Hollywoo Blvd. 42",
    "city": "Los Angeles",
    "post_code": "12345"
  },
  "cashier_id": 999,
  "store_id": 111
}
```

--------------------------------

### POST /purchase

Source: https://docs.esto.eu/?region=lv

Creates a new purchase in the ESTO system. Requires basic authentication using shop_id and secret key.

```APIDOC
## POST /purchase

### Description
Creates a new purchase transaction.

### Method
POST

### Endpoint
https://api.esto.lv/v2/purchase

### Authentication
Basic Auth (Username: shop_id, Password: merchant secret key)
```

--------------------------------

### POST /purchase

Source: https://docs.esto.eu/?region=lv

Creates a new purchase request for the merchant. This endpoint requires HTTP Basic authentication using the shop_id and secret key.

```APIDOC
## POST /purchase

### Description
Creates a new purchase transaction. ESTO handles identification, scoring, contract signing, and payment collection.

### Method
POST

### Endpoint
https://api.esto.lv/v2/purchase

### Request Body
- **amount** (number) - Required - The total amount of the purchase.
- **reference** (string) - Required - The merchant's unique order reference.

### Request Example
{
  "amount": 91.89,
  "reference": "order-1234"
}
```

--------------------------------

### MAC Signature Algorithm

Source: https://docs.esto.eu/?region=lv

The formula for calculating the MAC signature using SHA-512.

```text
MAC = UPPERCASE( SHA-512( trim(json_string) + secret_key ) )
```

--------------------------------

### Verify MAC Signature

Source: https://docs.esto.eu/?region=lv

Implementations for verifying the MAC signature to ensure response authenticity.

```php
function verifyMac(string $json, string $secretKey, string $mac): bool
{
    $computed = strtoupper(hash('sha512', trim($json) . $secretKey));

    return hash_equals($computed, $mac);
}
```

```javascript
const crypto = require('crypto');

function verifyMac(json, secretKey, mac) {
  const computed = crypto
    .createHash('sha512')
    .update(json.trim() + secretKey)
    .digest('hex')
    .toUpperCase();

  return computed === mac;
}
```

--------------------------------

### JSON Request Body Structure

Source: https://docs.esto.eu/?region=lv

The request body requires a JSON object containing transaction details, customer information, and store configuration.

```json
{ "amount": 91.89, "reference": "fwejigjwe8g32g3jg", "return_url": "https://your-site.com/return", "notification_url": "https://your-site.com/notification", "cancel_url": "https://your-site.com/cancel", "connection_mode": "live", "schedule_type": "REGULAR", "items": [ { "name": "Bitcoin 101", "unit_price": 30.3, "quantity": 3 }, { "name": "The One Ring", "unit_price": 0.99, "quantity": 1 } ], "customer": { "first_name": "BoJack", "last_name": "Horseman", "email": "email@address.com", "phone": "567891234", "address": "Hollywoo Blvd. 42", "city": "Los Angeles", "post_code": "12345" }, "cashier_id": 999, "store_id": 111}
```

--------------------------------

### API Response Structure

Source: https://docs.esto.eu/?region=lv

Details on the envelope format used for authenticated purchase endpoints.

```APIDOC
## API Response Structure

### Authenticated Purchase Envelope
- **errors** (array) - List of errors if applicable.
- **data** (string) - A JSON-encoded string containing the payload.
- **mac** (string) - UPPERCASE_SHA512_HEX signature.

### Notes
- Metadata and /calculate/* endpoints return plain JSON without the envelope.
```

--------------------------------

### Authentication

Source: https://docs.esto.eu/?region=lv

Authentication requirements for the ESTO API.

```APIDOC
## Authentication

### Method
Basic Authentication

### Credentials
- **Username**: Merchant `shop_id`
- **Password**: Merchant secret key

Credentials are issued in the Partner Portal under Developer Tools.
```

--------------------------------

### API Request Structure

Source: https://docs.esto.eu/?region=lv

Details on the base URL and request body format for the ESTO API.

```APIDOC
## API Request Structure

### Base URL
https://api.esto.lv/v2

### Request Format
- **Content-Type**: application/json
- **connection_mode**: Optional - Set to "test" for test purchases or "live" (or omit) for real purchases.
```

--------------------------------

### API Response Envelope Structure

Source: https://docs.esto.eu/?region=lv

The standard envelope format for authenticated purchase endpoints, where the data field is a JSON-encoded string.

```json
{ "errors": [], "data": "{...}", "mac": "UPPERCASE_SHA512_HEX" }
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.