API Reference

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:

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

Payment Object

Prop	Type	Default
`id`	`string`	-
`object`	`string`	-
`status`	`'pending' \| 'requires_authentication' \| 'completed' \| 'failed' \| 'cancelled'`	-
`amount`	`number`	-
`currency`	`string`	-
`description`	`string`	`undefined`
`returnUrl`	`string`	-
`checkoutUrl`	`string`	-
`metadata`	`Record<string, string>`	`{}`
`created_at`	`string`	-

Create Payment Parameters

Prop	Type	Default
`amount`	`number`	-
`currency`	`string`	-
`description`	`string`	`undefined`
`returnUrl`	`string`	-
`metadata`	`Record<string, string>`	`{}`
`idempotencyKey`	`string`	`auto-generated`
`capture`	`boolean`	`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.

Съдържание