Hosted payment page

The quickest integration: create a payment and redirect the payer to its checkout_url. The page shows the amount and the account to transfer to, follows the payment as it goes, and sends the payer back to you when it ends. You build no payment UI.

#!/usr/bin/env bash
# Create a payment and send the payer to its checkout_url.
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",
  "return_url": "https://shop.example.lk/orders/return"
}
JSON
)
mka_request POST "/v1/payments" "$body" "$(mka_new_key)"

// Create a payment and send the payer to its checkout_url.
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",
    return_url: "https://shop.example.lk/orders/return",
  },
  idempotencyKey: newKey(),
});
print(answer);

<?php
// Create a payment and send the payer to its checkout_url.

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',
        'return_url' => 'https://shop.example.lk/orders/return',
    ],
    mka_new_key(),
));

"""Create a payment and send the payer to its checkout_url."""
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",
        "return_url": "https://shop.example.lk/orders/return",
    },
    idempotency_key=new_key(),
))

//go:build ignore

// Create a payment and send the payer to its checkout_url.
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",
    "return_url":        "https://shop.example.lk/orders/return",
  }, signedrequest.NewKey()))
}

What you send

Field
`merchant_order_id`	Your order number, 1–128 characters, unique in the project. Sending it again with the same body answers the same payment.
`amount`	A string with two decimals: `"2500.00"`.
`currency`	`LKR`.
`return_url`	Optional. `https://` only. Where the page’s button takes the payer once the payment ended.
`locale`	Optional: `en`, `si`, `ta` or `ru`. The page’s language when the payer chose none; then the browser’s, then English.

What the payer sees

The page opens while the payment is pending and shows the account as soon as it is given.
If your project lets payers choose their bank, they choose it first; the account follows within seconds.
The payer transfers the exact amount from their bank app. The page updates itself: no refresh needed.
On succeeded, failed or cancelled the page says so and offers the way back to return_url.

The link is the same in every answer for this payment, cannot be guessed, and opens while the payment runs and for 24 hours after it ended. It carries no key: send it to the payer as is — a redirect, a link in an e-mail, a QR code.

When the payer comes back

return_url is a convenience, not a proof. The payer may close the tab, or come back before the money arrived. Decide by the payment’s status — from its webhook or a GET:

#!/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, ""))
}