API. Mailchecker

В связи с невозможность проверки некоторых типов чека мы предлагаем использовать проверку чеков через отправку на Email.

Создания ящика для транзакции

POST /api/v1/signature/proofs

Headers

Name

Value

Content-Type

application/json

Signature

<signature>

Правило создания сигнатуры

Сигнатура создается путем получения SHA-1 от вашего API-secret и json-строки body

let raw_body = JSON.stringify(JSON.parse(body));
let api_secret = "<SECRET>";
let hash = CryptoJS.SHA1(api_secret + raw_body);
let signature = CryptoJS.enc.Hex.stringify(hash);

require 'json'
require 'digest'

raw_body = JSON.dump(JSON.parse(body))
api_secret = "<SECRET>"
signature = Digest::SHA1.hexdigest(api_secret + raw_body)

$raw_body = json_encode(json_decode($body, true), JSON_UNESCAPED_SLASHES);
$api_secret = "<SECRET>";
$signature = sha1($api_secret . $raw_body);

import json
import hashlib

raw_body = json.dumps(json.loads(body), separators=(',', ':'))
api_secret = "<SECRET>"
signature = hashlib.sha1((api_secret + raw_body).encode('utf-8')).hexdigest()

import (
	"crypto/sha1"
	"encoding/hex"
	"encoding/json"
	"fmt"
)

var rawBodyInterface interface{}
json.Unmarshal([]byte(body), &rawBodyInterface)
rawBodyBytes, _ := json.Marshal(rawBodyInterface)
raw_body := string(rawBodyBytes)

api_secret := "<SECRET>"
signature := hex.EncodeToString(sha1.Sum([]byte(api_secret + raw_body))[:])

Body

Name

Type

Description

client_id

string *

CLIENT_ID для авторизации запроса

requisite

string *

+79001234567

Номер реквизита

fiat_amount

number *

Ожидаемая сумма платежа

callback_url

string *

https://site.com/callback

Ссылка, куда пришлем колбэк после проверки письма

timestamp

number *

1741194476019

Дата, когда был выдан реквизит. UNIX формат.

metadata

json *

{
  uuid: "your-uuid",
  somethingElse: "..."
}

Должна содержать поле uuid, где будет указан номер вашей транзакции. Так же можно поместить любую другую информацию. Это поле прийдет в колбэке

bank_name

string

Сбербанк

Название банка получателя, если требуется проверка (только для СБП)

group_id

string

Если требуется предоставлять разграниченный доступ разным категориям саппорта, то можно передавать group_id. Только саппорты относящиеся к данной группе смогут увидеть эти транзакции.

Response

В ответ получите инструкции по отправке письма и сам почтовый ящик. Для Яндекс-банка мы проверяем чек через предоставление прямой ссылки согласно инструкции.

{
    "id": 32576,
    "created_at": "2025-07-03T12:13:27.468+03:00",
    "uuid": "<INTERNAL_UUID>",
    "email": "[email protected]",
    "requisite": "+79001234567",
    "fiat_amount": 500.0,
    "bank_code": "100000000111",
    "web_url": "https://mailbox-api.ttr.cx/emails/<INTERNAL_UUID>",
    "bank": {
        "name": "Сбербанк"
    },
    "callback_url": "https://webhook.site/e72cf3e2-0e73-493d-937f-5a563c0ce6d9",
    "state": "created",
    "final_fiat_amount": 0.0,
    "instructions": {
        "sovkom": {
            "instruction_url": "https://instructions.ttr.cx/instructions/<INTERNAL_UUID>/sovkom",
            "email": "[email protected]"
        },
        "otp": {
            "instruction_url": "https://instructions.ttr.cx/instructions/<INTERNAL_UUID>/otp",
            "email": "[email protected]"
        },
        "tinkoff": {
            "instruction_url": "https://instructions.ttr.cx/instructions/<INTERNAL_UUID>/tinkoff",
            "email": "[email protected]"
        },
        "raiffeisen": {
            "instruction_url": "https://instructions.ttr.cx/instructions/<INTERNAL_UUID>/raiffeisen",
            "email": "[email protected]"
        },
        "rus_standart": {
            "instruction_url": "https://instructions.ttr.cx/instructions/<INTERNAL_UUID>/rus_standart",
            "email": "[email protected]"
        },
        "psb": {
            "instruction_url": "https://instructions.ttr.cx/instructions/<INTERNAL_UUID>/psb",
            "email": "[email protected]"
        },
        "uralsib": {
            "instruction_url": "https://instructions.ttr.cx/instructions/<INTERNAL_UUID>/uralsib",
            "email": "[email protected]"
        },
        "yandex": {
            "instruction_url": "https://instructions.ttr.cx/instructions/<INTERNAL_UUID>/yandex"
        }
    },
    "metadata": {
        "uuid": "<YOUR_UUID>",
        "something_else": "lalala"
    },
    "proof_sources": []
}

Колбэки

В зависимости от того, были ли выполнены все условия при отправке письма или нет, мы присылаем 2 типа коллбэков.

Тип Incorrect

{
  "state": "incorrect",
  "verdict": [
    {
      "got": "[email protected]",
      "code": "INCORRECT_SENDER_EMAIL",
      "expected": [
        "[email protected]",
        "[email protected]",
        "[email protected]",
        "[email protected]",
        "[email protected]",
        "[email protected]",
        "[email protected]"
      ]
    }
  ],
  "metadata": { "uuid": "3779cb759b1c93c52af97d50ea095e6b" }
}

Возможные ошибки валидации при incorrect

Тип

Описание

INCORRECT_SENDER_EMAIL

Пользователь отправил письмо с личного почтового адреса. Решение: указать пользователю на его ошибку при отправке чека по инструкции

INCORRECT_SENDER_DOMAIN

INCORRECT_DOMAIN_RESOLVED

Подделка заголовков отправителя с целью имитировать отправку от лица банка

RECEIPT_WRONG_STATUS

Чек имеет незафиналенный статус

RECEIPT_WRONG_DATE

Дата перевода в чеке раньше, чем дата выдачи реквизита

RECEIPT_WRONG_REQUISITE

Перевод на неверный реквизит

RECEIPT_WRONG_BANK

Перевод на неверный банк

RECEIPT_WRONG_DOCUMENT_NUMBER

Чек с данным номером документа уже был учтен ранее

Тип Success

{
  "id": 32672,
  "uuid": "3e05e5bd-5544-4b27-970d-5e6f7a1a1a50",
  "group_id": null,
  "metadata": { "uuid": "3779cb759b1c93c52af97d50ea095e6b" },
  "fiat_amount": "9500.0",
  "final_fiat_amount": "9500.0",
  "state": "successed",
  "proof_sources": [
    {
      "attachment": {
        "id": 32421,
        "created_at": "2025-07-03T15:08:22.634+03:00",
        "filename": "proof.pdf",
        "size": "59 KB",
        "preview": "<ссылка на превью>",
        "url": "<ссылка на pdf-версию чека>"
      }
    }
  ]
}

Обратите внимание, что вы будете получать данный коллбэк всякий раз, когда пользователь пришлет верный чек по данной транзакции, который ранее не был нигде учтен. В ответе присутствует 2 поля: fiat_amount (текущая сумма успеха по чеку) и final_fiat_amount (общая сумма успеха по транзакции)

Поле

Описание

uuid

UUID в системе майлчекера

group_id

ID группы, если передано

metadata

переданная при создании запроса metadata

fiat_amount

текущая сумма успеха по чеку

final_fiat_amount

общая сумма успеха по транзакции

state

successed

proof_sources

Массив всех присланных писем

PreviousAPI. Получение исторических данных

Last updated 17 days ago