Host-to-host

Host-to-host (H2H): ваша страница или приложение показывает плательщику, куда переводить, и плательщик не уходит от вас. Вы берёте на себя то, что делает страница оплаты: показ реквизитов, обратный отсчёт, исход.

1. Укажите метод и банк плательщика

Если вы знаете, как платит плательщик, укажите это в payment_method. Тогда реквизиты выдаются, и плательщика ни о чём не спрашивают:

#!/usr/bin/env bash
# Create a payment whose method and payer's bank you know: the account comes without the payment page.
set -euo pipefail
. "$(dirname "$0")/../signed-request.sh"

body=$(cat <<JSON
{
  "merchant_order_id": "${ORDER_ID:-order-$(mka_new_key)}",
  "amount": "${AMOUNT:-2500.00}",
  "currency": "LKR",
  "payment_method": {
    "type": "bank_transfer",
    "payer_institution": "${PAYER_BANK:-boc}"
  }
}
JSON
)
mka_request POST "/v1/payments" "$body" "$(mka_new_key)"

// Create a payment whose method and payer's bank you know: the account comes without the payment page.
import { newKey, print, request } from "../signed-request.mjs";

const answer = await request("POST", "/v1/payments", {
  body: {
    merchant_order_id: process.env.ORDER_ID ?? `order-${newKey()}`,
    amount: process.env.AMOUNT ?? "2500.00",
    currency: "LKR",
    payment_method: {
      type: "bank_transfer",
      payer_institution: process.env.PAYER_BANK ?? "boc",
    },
  },
  idempotencyKey: newKey(),
});
print(answer);

<?php
// Create a payment whose method and payer's bank you know: the account comes without the payment page.

declare(strict_types=1);

require __DIR__ . '/../signed_request.php';

mka_show(mka_request(
    'POST',
    '/v1/payments',
    [
        'merchant_order_id' => getenv('ORDER_ID') ?: 'order-' . mka_new_key(),
        'amount' => getenv('AMOUNT') ?: '2500.00',
        'currency' => 'LKR',
        'payment_method' => [
            'type' => 'bank_transfer',
            'payer_institution' => getenv('PAYER_BANK') ?: 'boc',
        ],
    ],
    mka_new_key(),
));

"""Create a payment whose method and payer's bank you know: the account comes without the payment page."""
import os

from signed_request import new_key, request, show

show(request(
    "POST",
    "/v1/payments",
    body={
        "merchant_order_id": os.environ.get("ORDER_ID") or f"order-{new_key()}",
        "amount": os.environ.get("AMOUNT", "2500.00"),
        "currency": "LKR",
        "payment_method": {
            "type": "bank_transfer",
            "payer_institution": os.environ.get("PAYER_BANK", "boc"),
        },
    },
    idempotency_key=new_key(),
))

//go:build ignore

// Create a payment whose method and payer's bank you know: the account comes without the payment page.
package main

import (
  "docs.processing.yolotech.cc/examples/signedrequest"
)

func main() {
  signedrequest.Show(signedrequest.Request("POST", "/v1/payments", map[string]any{
    "merchant_order_id": signedrequest.Env("ORDER_ID", "order-"+signedrequest.NewKey()),
    "amount":            signedrequest.Env("AMOUNT", "2500.00"),
    "currency":          "LKR",
    "payment_method": map[string]any{
      "type":              "bank_transfer",
      "payer_institution": signedrequest.Env("PAYER_BANK", "boc"),
    },
  }, signedrequest.NewKey()))
}

type — метод. Сейчас это bank_transfer, перевод на счёт. Методы — это данные: новые могут появиться без новой версии API.
payer_institution — необязательно, банк плательщика: boc (Bank of Ceylon), peoples (People’s Bank), combank (Commercial Bank of Ceylon), hnb (Hatton National Bank), ndb (NDB Bank), sampath (Sampath Bank) или other. Это предпочтение: реквизиты в этом банке выдаются, пока они есть, а затем — в любом другом; тогда перевод идёт между банками через CEFTS.

Метод или банк, которого нет в каталоге, — это 422 method_unavailable.

2. Покажите реквизиты

Читайте платёж, пока он не станет requires_action с customer_action.kind: bank_transfer — обычно через несколько секунд после создания, — и покажите ровно то, что в нём:

"customer_action": {
  "kind": "bank_transfer",
  "bank_transfer": {
    "bank_name": "Bank of Ceylon",
    "account_name": "K. A. Perera",
    "account_number": "0081234567"
  }
},
"expires_at": "2026-10-22T18:49:01Z"

#!/usr/bin/env bash
# Read a payment: the truth after a webhook, a timeout or a 503.
set -euo pipefail
. "$(dirname "$0")/../signed-request.sh"

payment_id=$(mka_required PAYMENT_ID)
mka_request GET "/v1/payments/$payment_id"

// Read a payment: the truth after a webhook, a timeout or a 503.
import { print, request, required } from "../signed-request.mjs";

const paymentId = required("PAYMENT_ID");
const answer = await request("GET", `/v1/payments/${paymentId}`);
print(answer);

<?php
// Read a payment: the truth after a webhook, a timeout or a 503.

declare(strict_types=1);

require __DIR__ . '/../signed_request.php';

$paymentId = mka_required('PAYMENT_ID');
mka_show(mka_request('GET', "/v1/payments/{$paymentId}"));

"""Read a payment: the truth after a webhook, a timeout or a 503."""
from signed_request import request, required, show

payment_id = required("PAYMENT_ID")
show(request("GET", f"/v1/payments/{payment_id}"))

//go:build ignore

// Read a payment: the truth after a webhook, a timeout or a 503.
package main

import (
  "docs.processing.yolotech.cc/examples/signedrequest"
)

func main() {
  paymentID := signedrequest.Required("PAYMENT_ID")
  signedrequest.Show(signedrequest.Request("GET", "/v1/payments/"+paymentID, nil, ""))
}

Показывайте точную сумму: перевод на другую сумму не сопоставится с платежом.
Показывайте payment_reference, если он есть; плательщик вписывает его в назначение перевода.
Ведите обратный отсчёт до expires_at. После него скройте реквизиты: такой перевод зачисляет только поддержка.
Не кешируйте реквизиты. Каждый GET возвращает их заново и перестаёт возвращать, как только ими больше нельзя пользоваться.

3. Следите за статусом

Статусы и вебхуки те же, что у любого платежа (жизненный цикл). При succeeded сообщите плательщику; при failed с expired предложите попробовать снова новым платежом.

Когда выбирает плательщик

Без payment_method проект, который разрешает плательщикам выбирать, отвечает requires_action с customer_action.kind: method_selection: доступные методы и банки и selection_expires_at. Выбор делается на checkout_url — отправьте плательщика туда. Если за 30 минут ничего не выбрано, платёж завершается failed с expired. Незнакомый вам kind — тоже отправьте плательщика на checkout_url.