# API Reference

> Complete VINR API documentation with endpoints, parameters, and examples.

## Base URL

```
Production: https://api.vinr.com/v1
Sandbox:    https://sandbox.api.vinr.com/v1
```

## Authentication

All API requests require a Bearer token:

```
Authorization: Bearer sk_live_your_secret_key
```

## Core Resources

### Payments

| Method | Endpoint                | Description                   |
| ------ | ----------------------- | ----------------------------- |
| POST   | `/payments`             | Create a payment              |
| GET    | `/payments/:id`         | Retrieve a payment            |
| GET    | `/payments`             | List payments                 |
| POST   | `/payments/:id/capture` | Capture an authorized payment |
| POST   | `/payments/:id/cancel`  | Cancel a payment              |

### Refunds

| Method | Endpoint       | Description       |
| ------ | -------------- | ----------------- |
| POST   | `/refunds`     | Create a refund   |
| GET    | `/refunds/:id` | Retrieve a refund |
| GET    | `/refunds`     | List refunds      |

### Webhooks

| Method | Endpoint        | Description                 |
| ------ | --------------- | --------------------------- |
| POST   | `/webhooks`     | Register a webhook endpoint |
| GET    | `/webhooks`     | List webhook endpoints      |
| DELETE | `/webhooks/:id` | Remove a webhook endpoint   |

### Settlements

| Method | Endpoint                        | Description                       |
| ------ | ------------------------------- | --------------------------------- |
| GET    | `/settlements`                  | List settlements                  |
| GET    | `/settlements/:id`              | Retrieve settlement details       |
| GET    | `/settlements/:id/transactions` | List transactions in a settlement |

## Response Format

All responses follow a consistent structure:

```json
{
  "id": "pay_1234567890",
  "object": "payment",
  "status": "completed",
  "amount": 1000,
  "currency": "EUR",
  "created_at": "2026-04-15T10:30:00Z",
  "metadata": {}
}
```

## Payment Object

| Field         | Type                                                                               | Description                                            | Default     |
| ------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------- |
| `id`          | `string`                                                                           | Unique identifier prefixed with pay\_                  | `—`         |
| `object`      | `string`                                                                           | Always 'payment'                                       | `—`         |
| `status`      | `'pending' \| 'requires_authentication' \| 'completed' \| 'failed' \| 'cancelled'` | Current payment status                                 | `—`         |
| `amount`      | `number`                                                                           | Amount in minor units (e.g. 1000 = €10.00)             | `—`         |
| `currency`    | `string`                                                                           | ISO 4217 three-letter currency code                    | `—`         |
| `description` | `string`                                                                           | Merchant-provided description                          | `undefined` |
| `returnUrl`   | `string`                                                                           | URL to redirect customer after payment                 | `—`         |
| `checkoutUrl` | `string`                                                                           | URL to redirect customer for payment (hosted checkout) | `—`         |
| `created_at`  | `string`                                                                           | ISO 8601 timestamp of creation                         | `—`         |

## Create Payment Parameters

| Field            | Type      | Description                                      | Default          |
| ---------------- | --------- | ------------------------------------------------ | ---------------- |
| `amount`         | `number`  | Amount in minor units (required)                 | `—`              |
| `currency`       | `string`  | ISO 4217 currency code (required)                | `—`              |
| `description`    | `string`  | Payment description shown to customer            | `undefined`      |
| `returnUrl`      | `string`  | Redirect URL after payment completion (required) | `—`              |
| `idempotencyKey` | `string`  | Unique key to prevent duplicate payments         | `auto-generated` |
| `capture`        | `boolean` | Whether to capture immediately or authorize only | `true`           |

## Error Codes

| Code  | Meaning                              |
| ----- | ------------------------------------ |
| `400` | Bad Request — Invalid parameters     |
| `401` | Unauthorized — Invalid API key       |
| `403` | Forbidden — Insufficient permissions |
| `404` | Not Found — Resource doesn't exist   |
| `409` | Conflict — Idempotency conflict      |
| `429` | Rate Limited — Too many requests     |
| `500` | Server Error — Contact support       |

> Full OpenAPI specification will be available for download when the spec is finalized. Auto-generated reference pages will replace this overview.