Выплаты игрокам

Выплата переводит деньги с баланса вашего проекта на банковский счёт игрока — это вывод средств в iGaming.

#!/usr/bin/env bash
# Pay a player's withdrawal out of the project's balance.
set -euo pipefail
. "$(dirname "$0")/../signed-request.sh"

body=$(cat <<JSON
{
  "merchant_payout_id": "${PAYOUT_REF:-withdrawal-$(mka_new_key)}",
  "amount": "${AMOUNT:-5000.00}",
  "currency": "LKR",
  "recipient": {
    "bank_name": "Commercial Bank of Ceylon",
    "account_holder": "S. Jayasuriya",
    "account_number": "8001234567"
  }
}
JSON
)
mka_request POST "/v1/payouts" "$body" "$(mka_new_key)"

// Pay a player's withdrawal out of the project's balance.
import { newKey, print, request } from "../signed-request.mjs";

const answer = await request("POST", "/v1/payouts", {
  body: {
    merchant_payout_id: process.env.PAYOUT_REF ?? `withdrawal-${newKey()}`,
    amount: process.env.AMOUNT ?? "5000.00",
    currency: "LKR",
    recipient: {
      bank_name: "Commercial Bank of Ceylon",
      account_holder: "S. Jayasuriya",
      account_number: "8001234567",
    },
  },
  idempotencyKey: newKey(),
});
print(answer);

<?php
// Pay a player's withdrawal out of the project's balance.

declare(strict_types=1);

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

mka_show(mka_request(
    'POST',
    '/v1/payouts',
    [
        'merchant_payout_id' => getenv('PAYOUT_REF') ?: 'withdrawal-' . mka_new_key(),
        'amount' => getenv('AMOUNT') ?: '5000.00',
        'currency' => 'LKR',
        'recipient' => [
            'bank_name' => 'Commercial Bank of Ceylon',
            'account_holder' => 'S. Jayasuriya',
            'account_number' => '8001234567',
        ],
    ],
    mka_new_key(),
));

"""Pay a player's withdrawal out of the project's balance."""
import os

from signed_request import new_key, request, show

show(request(
    "POST",
    "/v1/payouts",
    body={
        "merchant_payout_id": os.environ.get("PAYOUT_REF") or f"withdrawal-{new_key()}",
        "amount": os.environ.get("AMOUNT", "5000.00"),
        "currency": "LKR",
        "recipient": {
            "bank_name": "Commercial Bank of Ceylon",
            "account_holder": "S. Jayasuriya",
            "account_number": "8001234567",
        },
    },
    idempotency_key=new_key(),
))

//go:build ignore

// Pay a player's withdrawal out of the project's balance.
package main

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

func main() {
  signedrequest.Show(signedrequest.Request("POST", "/v1/payouts", map[string]any{
    "merchant_payout_id": signedrequest.Env("PAYOUT_REF", "withdrawal-"+signedrequest.NewKey()),
    "amount":             signedrequest.Env("AMOUNT", "5000.00"),
    "currency":           "LKR",
    "recipient": map[string]any{
      "bank_name":      "Commercial Bank of Ceylon",
      "account_holder": "S. Jayasuriya",
      "account_number": "8001234567",
    },
  }, signedrequest.NewKey()))
}

merchant_payout_id — id вашего вывода, 1–128 символов, уникальный в проекте. Это второй ключ идемпотентности: тот же id с тем же телом возвращает выплату, созданную первой.
amount — ровно столько, сколько получит игрок.
recipient — bank_name, account_holder, account_number (от 6 до 20 цифр). Хранится в зашифрованном виде, при чтении маскируется и никогда не попадает в вебхук.

Комиссия — сверху. Действует ставка вашего проекта для выплат на счёт: баланс сразу удерживает amount + fee, а комиссия списывается, только если выплата прошла. Сумма больше доступного баланса — это 422 insufficient_available_balance; нет опубликованной ставки — 422 payout_method_unavailable. В этих случаях ничего не удерживается.

На новую выплату ответ — 201. Повтор — тот же ключ или тот же merchant_payout_id под новым ключом, с тем же телом — даёт 200 с Idempotent-Replayed: true. Другое тело — 409 idempotency_conflict.

Статусы

Статус	Значение
`pending`	Удержана с баланса; ждёт агента. Ещё можно отменить.
`processing`	Агент взял выплату и отправляет её.
`succeeded`	Отправлена и подтверждена. Комиссия списана. Финальный.
`failed`	Никто не взял её за 24 часа (`not_taken`) или платформа отказала (`refused`). Сумма и комиссия возвращаются. Финальный.
`cancelled`	Вы отозвали её в статусе `pending`. Сумма и комиссия возвращаются. Финальный.

Каждая версия, включая создание, — это вебхук payout.status_changed; они доставляются по порядку. Быстро отправленная выплата может перейти из pending сразу в succeeded.

#!/usr/bin/env bash
# Read one payout.
set -euo pipefail
. "$(dirname "$0")/../signed-request.sh"

payout_id=$(mka_required PAYOUT_ID)
mka_request GET "/v1/payouts/$payout_id"

// Read one payout.
import { print, request, required } from "../signed-request.mjs";

const payoutId = required("PAYOUT_ID");
const answer = await request("GET", `/v1/payouts/${payoutId}`);
print(answer);

<?php
// Read one payout.

declare(strict_types=1);

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

$payoutId = mka_required('PAYOUT_ID');
mka_show(mka_request('GET', "/v1/payouts/{$payoutId}"));

"""Read one payout."""
from signed_request import request, required, show

payout_id = required("PAYOUT_ID")
show(request("GET", f"/v1/payouts/{payout_id}"))

//go:build ignore

// Read one payout.
package main

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

func main() {
  payoutID := signedrequest.Required("PAYOUT_ID")
  signedrequest.Show(signedrequest.Request("GET", "/v1/payouts/"+payoutID, nil, ""))
}

Отмена

Отменить можно только выплату в статусе pending; если агент её уже взял, ответ — 409 payout_not_cancellable.

#!/usr/bin/env bash
# Cancel a payout no Agent took yet; the amount and fee come back.
set -euo pipefail
. "$(dirname "$0")/../signed-request.sh"

payout_id=$(mka_required PAYOUT_ID)
mka_request POST "/v1/payouts/$payout_id/cancel" "" "$(mka_new_key)"

// Cancel a payout no Agent took yet; the amount and fee come back.
import { newKey, print, request, required } from "../signed-request.mjs";

const payoutId = required("PAYOUT_ID");
const answer = await request("POST", `/v1/payouts/${payoutId}/cancel`, {
  idempotencyKey: newKey(),
});
print(answer);

<?php
// Cancel a payout no Agent took yet; the amount and fee come back.

declare(strict_types=1);

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

$payoutId = mka_required('PAYOUT_ID');
mka_show(mka_request(
    'POST',
    "/v1/payouts/{$payoutId}/cancel",
    null,
    mka_new_key(),
));

"""Cancel a payout no Agent took yet; the amount and fee come back."""
from signed_request import new_key, request, required, show

payout_id = required("PAYOUT_ID")
show(request(
    "POST",
    f"/v1/payouts/{payout_id}/cancel",
    idempotency_key=new_key(),
))

//go:build ignore

// Cancel a payout no Agent took yet; the amount and fee come back.
package main

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

func main() {
  payoutID := signedrequest.Required("PAYOUT_ID")
  signedrequest.Show(signedrequest.Request("POST", "/v1/payouts/"+payoutID+"/cancel", nil, signedrequest.NewKey()))
}

Потеряли ответ?

После таймаута или 503 payout_unavailable повторите запрос с тем же Idempotency-Key или найдите выплату по своему id:

GET /v1/payouts?merchant_payout_id=withdrawal-5001

#!/usr/bin/env bash
# The project's payouts, newest first.
set -euo pipefail
. "$(dirname "$0")/../signed-request.sh"

mka_request GET "/v1/payouts?limit=10"

// The project's payouts, newest first.
import { print, request } from "../signed-request.mjs";

const answer = await request("GET", "/v1/payouts?limit=10");
print(answer);

<?php
// The project's payouts, newest first.

declare(strict_types=1);

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

mka_show(mka_request('GET', '/v1/payouts?limit=10'));

"""The project's payouts, newest first."""
from signed_request import request, show

show(request("GET", "/v1/payouts?limit=10"))

//go:build ignore

// The project's payouts, newest first.
package main

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

func main() {
  signedrequest.Show(signedrequest.Request("GET", "/v1/payouts?limit=10", nil, ""))
}

Список идёт от новых к старым: limit 1–100 (по умолчанию 50), starting_after с последним id предыдущей страницы, status для фильтра и has_more.