Принимайте оплату картами с помощью платёжных ссылок GetPay

01Как это работает

Платёжная ссылка — это размещённая у GetPay платёжная страница для одного заказа. Ваш сервер создаёт её с данными заказа, а всё остальное берёт на себя GetPay.

1. Ваш серверСоздаёт платёжную ссылку с товарами, суммой и номером вашего заказа. GetPay возвращает url.
2. Ваш сайтПеренаправляет покупателя на этот url.
3. ПокупательПроверяет заказ, вводит свои данные и оплачивает картой на защищённой странице банка. Если карта отклонена, можно повторить попытку по той же ссылке.
4. GetPayПроверяет результат в банке, отправляет покупателя на ваш success_url и присылает вебхук payment_link.completed на ваш сервер.
5. Ваш серверПодтверждает оплату и выполняет заказ.

sequenceDiagram
    participant S as Ваш сервер
    participant C as Покупатель
    participant G as GetPay
    participant B as Банк (vPOS)
    S->>G: POST /payment-links
    G-->>S: { id, url }
    S->>C: Редирект на url
    C->>G: Открывает страницу оплаты, нажимает «Оплатить»
    G->>B: Регистрация платежа
    C->>B: Ввод карты, 3-D Secure
    B->>G: Результат
    G->>C: Редирект на success_url
    G->>S: Вебхук payment_link.completed
    S->>G: GET /payment-links/{id} (подтверждение)
      

02Перед началом

Ваш домен и базовый URL

API работает на вашем собственном домене, а не на getpay.am. В личном кабинете GetPay откройте раздел Домен, укажите свой домен (например, shopx.am) и добавьте четыре показанные DNS-записи — все они указывают на IP-адрес GetPay:

Затем нажмите Проверить подключение. Когда все записи найдены, в кабинете появится базовый URL вашего API. Запросы на любой другой адрес, включая api.getpay.am, отклоняются с кодом 403.

API-ключи

Ключи находятся в личном кабинете GetPay в разделе Главная → API-ключи. Их два, по одному на каждую среду:

Передавайте ключ в заголовке Authorization каждого запроса:

Соглашения

• Суммы указываются в минимальных единицах. 150000 означает 1 500,00 AMD. Всегда передавайте целые числа.
• Валюта: валюты, включённые GetPay, — GET /meta/currencies (пока AMD). Для остальных возвращается CURRENCY_NOT_SUPPORTED.
• Запросы и ответы — в формате JSON. Передавайте Content-Type: application/json.
• Время указывается в UTC в формате ISO 8601, например 2026-09-30T10:15:00Z.
• Идентификаторы — это UUID. Сохраняйте id платёжной ссылки рядом со своим заказом.

03Создание платёжной ссылки

Вызывайте этот метод со своего сервера, когда покупатель готов платить. Передайте, что он покупает, кто он (если знаете) и куда направить его после оплаты.

Параметры

Передайте либо line_items, либо amount, но не оба сразу. Всё остальное необязательно.

Ответ

201 Created с платёжной ссылкой. Сохраните id вместе с заказом и направьте покупателя на url.

04Переход покупателя на платёжную страницу

Перенаправьте браузер покупателя на url из ответа. На странице показаны название вашей компании, товары и итоговая сумма; она запрашивает выбранные вами поля и предлагает оплату картой. Покупатель может переключаться между армянским, английским и русским языками.

Что происходит дальше

05Подтверждение оплаты

Используйте любой из способов или оба. Вебхуки надёжнее: они приходят, даже если покупатель закрыл браузер, не дойдя до вашей страницы успеха.

• Вебхук: обработайте payment_link.completed (см. Вебхуки).
• API: когда покупатель попадает на ваш success_url, запросите ссылку.

Выполняйте заказ, только если status равен complete, payment_status равен paid, а amount_total и currency совпадают с вашим заказом. Этот вызов также повторно проверяет в банке платёж, ожидающий подтверждения.

Статусы платёжной ссылки

Статусы платежа

Каждая попытка оплаты — это платёж. Он возвращается в поле payment ссылки и через API платежей.

06Вебхуки

Когда что-то происходит, GetPay отправляет HTTPS-запрос POST на ваш сервер, поэтому опрашивать API не нужно. Каждый запрос подписан секретом, который известен только вам и GetPay.

Настройка эндпоинта

• В личном кабинете откройте раздел Вебхуки, выберите Sandbox или Live и добавьте свой URL, например https://your-site.am/webhooks/getpay.
• Выберите все события или только нужные.
• Скопируйте секрет подписи (whsec_…) и сохраните его на сервере как GETPAY_WEBHOOK_SECRET. Он отличается от вашего API-ключа.
• Нажмите Отправить тест, чтобы проверить эндпоинт. В личном кабинете видна каждая доставка вместе с ответом вашего сервера.

Live-эндпоинты должны использовать https://. Sandbox-эндпоинты могут использовать http://. GetPay не может обратиться к localhost; чтобы получать события на своём компьютере во время разработки, используйте туннель, например ngrok http 8001, и зарегистрируйте выданный им публичный URL.

События

Формат запроса

data.object имеет точно такую же структуру, как ответ API для этого объекта.

Проверка подписи

Подпись — это HMAC-SHA256(secret, t + "." + raw_body) в hex. Вычисляйте её по исходному телу запроса (повторно закодированный JSON не совпадёт), сравнивайте за постоянное время и отклоняйте запросы старше 5 минут.

Ответ и повторные попытки

• Верните любой код 2xx в течение 10 секунд. Медленную работу (письма, обновление остатков, синхронизацию с ERP) выполняйте в фоновой задаче после ответа.
• В любом другом случае доставка повторяется через 1 минуту, 5 минут, 30 минут, 2 часа, 6 часов, 12 часов и 24 часа. После этого доставка помечается как неуспешная, и её можно отправить повторно из личного кабинета.
• Будьте готовы к дубликатам. Одно и то же событие может прийти несколько раз. Сохраняйте обработанные значения GetPay-Event-Id и пропускайте повторы.
• Не полагайтесь на порядок. События могут приходить не по порядку. Используйте статус внутри data.object или запрашивайте актуальное состояние через API.
• Перепроверьте, если сомневаетесь. Запросите событие через GET /events/{id} со своим секретным ключом.

07Тестирование в sandbox

С ключом sk_sandbox_… всё работает так же, как в live, но кнопка Оплатить открывает тестовую страницу GetPay вместо банка. Вы сами выбираете, чем закончится платёж. Вебхуки, редиректы, сообщения об отказе и возвраты ведут себя точно так же, как в режиме live. Банковские учётные данные не нужны.

Перед запуском проверьте: успешный платёж, отказ с последующей успешной повторной попыткой, покупателя, который закрывает браузер после оплаты (ваш вебхук всё равно должен выполнить заказ), и возврат.

08Возвраты и отмены

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

Каждый платёж сам сообщает, что с ним можно сделать прямо сейчас, поэтому вам не нужно отслеживать правила самостоятельно:

Отмена платежа

Отменяет весь платёж в банке. Используйте, когда заказ отменён вскоре после оплаты. По истечении 72 часов или после любого возврата запрос вернёт 409, и вместо отмены нужно будет сделать возврат. Затем отправляется вебхук payment.reversed.

Возврат платежа

Для частичного возврата на сумму до amount_refundable передайте {"amount": 500000}. Чтобы вернуть весь остаток, передайте пустое тело или {}. Частичных возвратов может быть несколько. После каждого отправляется вебхук payment.refunded.

Оба запроса возвращают обновлённый платёж. Идентификатор платежа находится в поле payment.id ссылки и в параметре payment_id, добавленном к вашему success URL.

09Квитанции

Каждый оплаченный платёж получает квитанцию, как в Stripe: короткий номер, который покупатель может назвать (например, 4821-0937), и страницу квитанции на стороне GetPay на вашем домене по адресу https://receipt.your-domain.am/…. На странице видны данные вашей компании, товары, использованная карта, возвраты и кнопка сохранения в PDF. Страница доступна на армянском, английском и русском.

Квитанция выпускается в момент оплаты, поэтому ссылка уже есть, когда покупатель возвращается на ваш сайт и когда приходят вебхуки. Ничего создавать или включать не нужно.

Где вы получаете ссылку на квитанцию

Объект квитанции

10Фискальные чеки (ЭККА)

Если ваш бизнес обязан выдавать кассовые чеки, GetPay может регистрировать каждый успешный платёж в Комитете госдоходов через электронную кассу PayX (Է-ՀԴՄ, ehdm.am). Нужен ваш собственный договор с PayX. Подключите выданный ими API-логин в личном кабинете в разделе Настройки → ЭККА.

Пока ЭККА включена, каждая платёжная ссылка должна указывать, что продаётся: код классификатора, название на армянском и единицу измерения. После успешной оплаты GetPay автоматически выдаёт фискальный чек, а после отмены или полного возврата — чек возврата.

Проверьте, включена ли ЭККА

enabled: true означает, что ваши платёжные ссылки должны содержать фискальные данные (или пропускать их). dep — налоговый отдел, выбранный в настройках ЭККА; он используется для товаров без dep.

Фискальные данные в платёжной ссылке

После оплаты

Чек регистрируется в фоне, обычно за несколько секунд. Страница квитанции покупателя (receipt_url) показывает его как кассовый чек — с фискальным номером, QR-кодом и ссылкой на PDF от PayX. Вы получаете его в трёх местах:

Статусы фискального чека

11Справочник API

Все эндпоинты используют ваш секретный ключ. Sandbox-ключ видит только данные sandbox, а live-ключ — только данные live.

Списки возвращаются в виде { "object": "list", "items": [...], "total", "limit", "offset" }.

12Ошибки

При ошибке возвращается JSON с HTTP-статусом, стабильным кодом message_code для проверки в вашем коде и понятным текстом message.

13Чек-лист запуска

• Ваш домен подключён в разделе Домен, и ваш сервер использует указанный там базовый URL API.
• Ваш аккаунт мерчанта прошёл онбординг и переведён в режим live в личном кабинете.
• Учётные данные вашего банка (Ameriabank vPOS) подключены и включены в разделе Платёжные шлюзы → Live.
• Ваш сервер берёт ключ sk_live_… из переменной окружения, а не из кода.
• Добавлен live-эндпоинт вебхуков с адресом https://, а его секрет whsec_… хранится на вашем сервере.
• Ваш обработчик вебхуков проверяет подписи, отклоняет старые метки времени и игнорирует повторяющиеся идентификаторы событий.
• Вы выполняете заказы только после подтверждения complete / paid и совпадения суммы и валюты.
• Ваша страница благодарности или письмо о заказе показывает покупателю receipt_url.
• Если вы используете ЭККА: PayX подключён и включён в разделе Настройки → ЭККА, а ваши ссылки передают line_items[].ehdm.
• Вы провели один небольшой реальный платёж и вернули его.