Перейти к содержимому

API

На странице

Создание

Создавайте вывод с баланса токена на кошелёк из белого списка, выбирайте сеть, подписывайте запрос и отслеживайте состояние.

POST/v1/withdrawals

API-ключ: Payout

Выплаты необратимы после отправки в сеть. Дважды проверьте destination_address и network перед подтверждением. Чарджбэка нет — неверный адрес = потерянные средства.

Тело запроса

Параметр Тип Обязателен Описание
amount string Да Сумма выплаты как decimal-строка (например, "100.00")
currency string Да Символ криптоактива. На вывод доступны только USDT и USDC — каждый в любой сети, где он выпущен (см. Поддерживаемые валюты)
network string Да Код сети блокчейна — TRC20, ERC20, BEP20, POLYGON, ARBITRUM, OPTIMISM, BASE, TON, AVAX, SOL, NEAR, SUI или PLASMA (см. Поддерживаемые валюты)
destination_address string Да Адрес кошелька получателя. Должен быть заранее добавлен в белый список выплат этого мерчанта
external_order_id string Да Ваш идентификатор выплаты (макс. 200 символов), уникальный в рамках мерчанта. Используется для идемпотентности: повторный вызов с тем же значением вернёт уже созданную выплату, а не отправит средства ещё раз

Пример запроса

{
  "amount": "100.00",
  "currency": "USDT",
  "network": "TRC20",
  "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
  "external_order_id": "payout-001"
}

Примеры кода

В каждой вкладке используется официальный SDK с Payout-ключом. Подпись, сериализацию, безопасные повторы и типизированные ошибки обрабатывает SDK.

import { Paymos, externalOrderId } from '@paymos/sdk';

const paymos = new Paymos({
  apiKey: process.env.PAYMOS_PAYOUT_KEY,
  apiSecret: process.env.PAYMOS_API_SECRET,
});
const withdrawal = await paymos.withdrawals.create({
  destinationAddress: 'TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9',
  network: 'TRC20',
  currency: 'USDT',
  amount: '50.00',
  externalOrderId: externalOrderId('payout'),
});

console.log(withdrawal.withdrawalId, withdrawal.status);
import os

from paymos import Paymos

paymos = Paymos(
    api_key=os.environ["PAYMOS_PAYOUT_KEY"],
    api_secret=os.environ["PAYMOS_API_SECRET"],
)
withdrawal = paymos.withdrawals.create(
    destination_address="TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
    network="TRC20",
    currency="USDT",
    amount="50.00",
    external_order_id="payout-001",
)

print(withdrawal["withdrawal_id"], withdrawal["status"])
<?php
use Paymos\Client;
use Paymos\ClientConfig;
use Paymos\IdempotencyKey;

$paymos = new Client(new ClientConfig(
    getenv('PAYMOS_PAYOUT_KEY'),
    getenv('PAYMOS_API_SECRET')
));
$withdrawal = $paymos->withdrawals()->create(array(
    'destination_address' => 'TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9',
    'network' => 'TRC20',
    'currency' => 'USDT',
    'amount' => '50.00',
    'external_order_id' => IdempotencyKey::externalOrderId('payout'),
));

echo $withdrawal['withdrawal_id'] . ' ' . $withdrawal['status'];
package main

import (
	"context"
	"fmt"
	"os"

	paymos "github.com/Paymos-labs/go-sdk/v2"
)

func main() {
	client, err := paymos.NewClient(os.Getenv("PAYMOS_PAYOUT_KEY"), os.Getenv("PAYMOS_API_SECRET"))
	if err != nil {
		panic(err)
	}
	withdrawal, err := client.Withdrawals.Create(context.Background(), paymos.CreateWithdrawalParams{
		DestinationAddress: "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
		Network:            "TRC20",
		Currency:           "USDT",
		Amount:             "50.00",
		ExternalOrderID:    "payout-001",
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(withdrawal.WithdrawalID, withdrawal.Status)
}
using Paymos;

using var paymos = new PaymosClient(
    Environment.GetEnvironmentVariable("PAYMOS_PAYOUT_KEY")!,
    Environment.GetEnvironmentVariable("PAYMOS_API_SECRET")!);

var withdrawal = await paymos.Withdrawals.CreateAsync(new CreateWithdrawalRequest(
    DestinationAddress: "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
    Network: "TRC20",
    Currency: "USDT",
    Amount: "50.00",
    ExternalOrderId: "payout-001"));

Console.WriteLine($"{withdrawal.WithdrawalId} {withdrawal.Status}");
import io.paymos.CreateWithdrawalRequest;
import io.paymos.PaymosClient;
import io.paymos.Withdrawal;

PaymosClient paymos = new PaymosClient(
    System.getenv("PAYMOS_PAYOUT_KEY"),
    System.getenv("PAYMOS_API_SECRET"));

Withdrawal withdrawal = paymos.withdrawals.create(new CreateWithdrawalRequest(
    "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
    "TRC20",
    "USDT",
    "50.00",
    "payout-001"));

System.out.println(withdrawal.withdrawalId() + " " + withdrawal.status());
require 'paymos'

paymos = Paymos::Client.new(
  api_key: ENV.fetch('PAYMOS_PAYOUT_KEY'),
  api_secret: ENV.fetch('PAYMOS_API_SECRET')
)
withdrawal = paymos.withdrawals.create(
  destination_address: 'TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9',
  network: 'TRC20',
  currency: 'USDT',
  amount: '50.00',
  external_order_id: 'payout-001'
)

puts "#{withdrawal.withdrawal_id} #{withdrawal.status}"
use paymos::{CreateWithdrawalRequest, PaymosClient};

let paymos = PaymosClient::new(
    std::env::var("PAYMOS_PAYOUT_KEY")?,
    std::env::var("PAYMOS_API_SECRET")?,
)?;
let withdrawal = paymos
    .withdrawals()
    .create(&CreateWithdrawalRequest {
        destination_address: "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9".to_owned(),
        network: "TRC20".to_owned(),
        currency: "USDT".to_owned(),
        amount: "50.00".to_owned(),
        external_order_id: "payout-001".to_owned(),
    })
    .await?;

println!("{} {}", withdrawal.withdrawal_id, withdrawal.status);

Ответ (201 Created / 200 при идемпотентном совпадении)

{
  "withdrawal_id": "wdr_2M8K6Q4P9X1Z7A3B",
  "external_order_id": "payout-001",
  "status": "created",
  "is_final": false,
  "is_test": true,
  "amount": "100.00",
  "currency": "USDT",
  "network": "TRC20",
  "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
  "created_at": 1739289600
}

Поля ответа

Поле Тип Описание
withdrawal_id string Идентификатор выплаты с префиксом (wdr_...)
external_order_id string Ваш собственный идентификатор выплаты, возвращённый из запроса на создание
status string Статус выплаты (snake_case — см. Статусы выплаты)
is_final boolean true когда выплата достигла терминального состояния (completed, failed, cancelled)
is_test boolean true для тестовых выводов
amount string Сумма выплаты
fee string? Фиксированная комиссия за вывод для этого токена, в том же активе, что и amount. Величину задаёт ваша политика выводов, от текущей цены газа она не зависит: это субсидированная часть сетевых расходов, комиссии Paymos в ней нет. Отсутствует, если комиссии нет
currency string Символ криптоактива
network string Код сети блокчейна
destination_address string Адрес получателя
tx_hash string? Хеш транзакции после завершения
explorer_url string? Прямая ссылка на транзакцию в блок-эксплорере сети (Tronscan / Etherscan / Tonviewer и т. п.). Заполняется только когда задан tx_hash и для сети настроен блок-эксплорер. Можно выводить как есть — это готовая кликабельная ссылка.
created_at integer Unix timestamp, секунды
completed_at integer? Время завершения
failed_at integer? Время ошибки
cancelled_at integer? Время отмены

Идемпотентность

Всегда отправляйте external_order_id при создании выплаты. Повторный вызов с тем же external_order_id возвращает уже созданную выплату — не вторую отправку. Статус ответа — 200 OK (без заголовка Location) при идемпотентном совпадении и 201 Created для новой выплаты.

Это ваша страховка от нестабильной сети, упавших воркеров и циклов повторов. Используйте тот же id для той же выплаты; новый id — для новой.

Ошибки

См. Коды ошибок — полный каталог. URI в поле type каждой ошибки ведёт сразу на нужную строку.