# FINTECHINI Merchant API

> Accept and send payments through FINTECHINI. This page is the full reference: everything below is generated from the code that serves the requests.

Base URL: `https://api-merchant.fintechini.io`. All endpoints are under `/v2`. Requests and responses are JSON.

**Authentication.**

Every request carries three headers:

| Header | Value |
|---|---|
| `x-api-key` | your `merchant_id` |
| `x-timestamp` | current Unix time, in **seconds** |
| `x-signature` | HMAC-SHA256, lower-case hex, see below |

The signed string is always the same shape:

```
{unix_timestamp}.{path}.{body}
```

* `path` is the request path with no host and no query string,
  for example `/v2/payments/incoming`. Sign it **percent-decoded**, the
  way our server sees it: an `order_id` of `shop:1` is signed as
  `/v2/payments/status/shop:1`, even if your HTTP client sends
  `shop%3A1` on the wire. Signing the encoded form gets
  `INVALID_SIGNATURE`.
* `body` is the **raw request body, byte for byte**. Do not
  re-serialize it before signing: field order and whitespace change
  the result.
* Requests without a body sign an empty `body`, so the string ends
  with a dot.

`x-timestamp` must be within five minutes of our clock. That window is
what stops a captured signature from working forever.

Full description with code examples: https://api-docs.fintechini.io/en/#description/authentication

## Specification

- [OpenAPI (English)](https://api-docs.fintechini.io/openapi.json): the complete machine-readable contract, OpenAPI 3.0.4
- [OpenAPI (Russian)](https://api-docs.fintechini.io/ru/openapi.json): the same contract with Russian descriptions
- [Postman collection (English)](https://api-docs.fintechini.io/en/postman.json): all requests, signed by the collection's pre-request script with apiSecret from the environment
- [Postman collection (Russian)](https://api-docs.fintechini.io/ru/postman.json): the same collection with Russian descriptions
- [Postman sandbox environment](https://api-docs.fintechini.io/en/postman-environment.json): sandbox address and empty apiKey and apiSecret to fill in
- [API reference (English)](https://api-docs.fintechini.io/en/): human-readable documentation
- [API reference (Russian)](https://api-docs.fintechini.io/ru/): the same documentation in Russian

## Guides

- [Quick start](https://api-docs.fintechini.io/en/#description/quick-start)
- [Authentication](https://api-docs.fintechini.io/en/#description/authentication)
- [Payment lifecycle](https://api-docs.fintechini.io/en/#description/payment-lifecycle)
- [Order identifiers](https://api-docs.fintechini.io/en/#description/order-identifiers)
- [When a request will not parse](https://api-docs.fintechini.io/en/#description/when-a-request-will-not-parse)
- [Amounts](https://api-docs.fintechini.io/en/#description/amounts)
- [Letting the payer choose](https://api-docs.fintechini.io/en/#description/letting-the-payer-choose)
- [Reconciliation](https://api-docs.fintechini.io/en/#description/reconciliation)
- [Disputes](https://api-docs.fintechini.io/en/#description/disputes)
- [Withdrawing your funds](https://api-docs.fintechini.io/en/#description/withdrawing-your-funds)
- [Idempotency and retries](https://api-docs.fintechini.io/en/#description/idempotency-and-retries)
- [Errors](https://api-docs.fintechini.io/en/#description/errors)
- [Rate limits](https://api-docs.fintechini.io/en/#description/rate-limits)
- [Callbacks](https://api-docs.fintechini.io/en/#description/callbacks)
- [Rotating your secret key](https://api-docs.fintechini.io/en/#description/rotating-your-secret-key)
- [Sandbox](https://api-docs.fintechini.io/en/#description/sandbox)
- [Changelog](https://api-docs.fintechini.io/en/#description/changelog)

## Disputes

- [POST /v2/disputes](https://api-docs.fintechini.io/en/#tag/disputes/POST/v2/disputes): Open a dispute
- [POST /v2/disputes/list](https://api-docs.fintechini.io/en/#tag/disputes/POST/v2/disputes/list): List disputes
- [GET /v2/disputes/{disputeId}](https://api-docs.fintechini.io/en/#tag/disputes/GET/v2/disputes/{disputeId}): Get the dispute state

## Merchant

- [GET /v2/merchant](https://api-docs.fintechini.io/en/#tag/merchant/GET/v2/merchant): Merchant profile
- [GET /v2/merchant/balances](https://api-docs.fintechini.io/en/#tag/merchant/GET/v2/merchant/balances): Balances
- [GET /v2/merchant/methods](https://api-docs.fintechini.io/en/#tag/merchant/GET/v2/merchant/methods): Available pay-in and payout methods

## Payment

- [POST /v2/payments/incoming](https://api-docs.fintechini.io/en/#tag/payment/POST/v2/payments/incoming): Create an incoming payment
- [POST /v2/payments/outgoing](https://api-docs.fintechini.io/en/#tag/payment/POST/v2/payments/outgoing): Create an outgoing payment
- [GET /v2/payments/status/{orderId}](https://api-docs.fintechini.io/en/#tag/payment/GET/v2/payments/status/{orderId}): Get the order state
- [POST /v2/payments/incoming/list](https://api-docs.fintechini.io/en/#tag/payment/POST/v2/payments/incoming/list): List incoming payments
- [POST /v2/payments/outgoing/list](https://api-docs.fintechini.io/en/#tag/payment/POST/v2/payments/outgoing/list): List outgoing payments
- [POST /v2/payments/{orderId}/cancel](https://api-docs.fintechini.io/en/#tag/payment/POST/v2/payments/{orderId}/cancel): Cancel an order
- [GET /v2/payments/{orderId}/receipts](https://api-docs.fintechini.io/en/#tag/payment/GET/v2/payments/{orderId}/receipts): Payout receipts

## Withdrawals

- [POST /v2/merchant/withdrawals](https://api-docs.fintechini.io/en/#tag/withdrawals/POST/v2/merchant/withdrawals): Withdraw funds
- [POST /v2/merchant/withdrawals/list](https://api-docs.fintechini.io/en/#tag/withdrawals/POST/v2/merchant/withdrawals/list): List withdrawals
- [GET /v2/merchant/withdrawals/{orderId}](https://api-docs.fintechini.io/en/#tag/withdrawals/GET/v2/merchant/withdrawals/{orderId}): Get the withdrawal state