İçeriğe atlayın

API

Bu sayfada

Oluştur

Token bakiyesinden beyaz listedeki bir cüzdana çekim oluşturun, ödeme çıkış ağını seçin, isteği imzalayın ve durumunu izleyin.

POST/v1/withdrawals

API anahtarı: Payout

İşlem imzalanıp zincire yayınlandıktan sonra çekimler geri alınamaz. Göndermeden önce destination_address ve network değerlerini doğrulayın — istek created durumuna düşer ve yalnızca yürütme başlayana kadar iptal edilebilir; bu, birkaç an sonra bile olabilir. Yayınlandıktan sonra geri dönüş yolu yoktur ve yanlış adres kayıp para demektir.

Çekim bir ödeme turunu beklemez: istek kabul edilir edilmez yürütme başlar. Transferin sonrasında ne kadar sürede ulaşacağı, çıkış ağının o anki hızına ve yoğunluğuna bağlıdır.

İstek gövdesi

Parametre Tip Zorunlu Açıklama
amount string Evet Ondalık dize olarak çekim tutarı (ör. "100.00")
currency string Evet Kripto varlık sembolü. Bakiyeniz olan her varlık çekilebilir; kullanılabilir ağlar varlığa göre değişir (bkz. Desteklenen Para Birimleri)
network string Evet Çıkış ağı kodu — TRC20, ERC20, BEP20, POLYGON, ARBITRUM, OPTIMISM, BASE, TON, AVAX, SOL veya PLASMA. Ödeme kabul eden on üç ağın on biri: NEAR ve SUI yalnızca tahsilat yapar, oradaki bir adres beyaz listeye eklenemez (bkz. Desteklenen Para Birimleri)
destination_address string Evet Hedef cüzdan adresi. Bu satıcının çekim beyaz listesinde zaten bulunmalıdır
external_order_id string Evet Ödeme çıkışı kimliğiniz (en fazla 200 karakter), satıcı başına benzersizdir. Idempotency için kullanılır — aynı değerle tekrar, yeniden göndermek yerine mevcut çekimi döndürür

Örnek istek

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

Kod örnekleri

Her sekme, Payout anahtarıyla resmî bir SDK kullanır. İmzalama, serileştirme, güvenli yeniden denemeler ve tiplenmiş hatalar SDK tarafından yürütülür.

API_KEY_ID="rk_live_xxxxxxxxxxxx"
API_SECRET="sk_live_xxxxxxxxxxxx"
BODY='{"destination_address":"TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9","network":"TRC20","currency":"USDT","amount":"50.00","external_order_id":"payout-123"}'

TS=$(date +%s)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | sed 's/^.* //')
SIGNATURE=$(printf '%s\n%s\n%s\n%s\n%s' "$TS" POST /v1/withdrawals '' "$BODY_HASH" \
  | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -sS https://api.paymos.io/v1/withdrawals \
  -H "Authorization: HMAC-SHA256 $API_KEY_ID:$SIGNATURE" \
  -H "X-Request-Timestamp: $TS" \
  -H "Content-Type: application/json" \
  -d "$BODY"
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);

Yanıt (201 Created / idempotent eşleşmede 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
}

Yanıt alanları

Alan Tip Açıklama
withdrawal_id string Önekli çekim kimliği (wdr_...)
external_order_id string Kendi ödeme çıkışı referansınız, oluşturma isteğinden aynen döner
status string Çekim durumu (snake_case — bkz. Çekim Durumları)
is_final boolean Çekim nihai duruma ulaştığında true (completed, failed, cancelled)
is_test boolean Sandbox çekimleri için true
amount string Çekim tutarı
fee string? Platform token kataloğundan çözülen, token başına sabit çekim ücreti; amount ile aynı varlıktadır. Canlı gas teklifi yerine token başına sabittir — o rotanın ağ maliyetinin altında kalır ve Paymos komisyonu içermez. Ücret yoksa atlanır
currency string Kripto varlık sembolü
network string Blockchain ağ kodu
destination_address string Hedef adres
tx_hash string? Ödeme çıkışını sonuçlandıran transferin zincir üstü hash'i. Yalnızca status completed olduğunda ayarlanır
explorer_url string? tx_hash için ağın blok gezginindeki doğrudan bağlantı (ör. Tronscan, Etherscan). Yalnızca tx_hash ayarlıysa ve ağın yapılandırılmış gezgini varsa ayarlanır. Olduğu gibi tıklanabilir bağlantı olarak gösterin
created_at integer Unix zaman damgası, saniye
completed_at integer? Unix zaman damgası, saniye. Ödeme çıkışı tamamlandığında ayarlanır
failed_at integer? Unix zaman damgası, saniye. Ödeme çıkışı başarısız olduğunda ayarlanır
cancelled_at integer? Unix zaman damgası, saniye. Çekim iptal edildiğinde ayarlanır

Idempotency

Çekimde her zaman external_order_id gönderin. Aynı external_order_id ile aynı çağrının tekrarı, mevcut çekimi döndürür — asla ikinci bir transfer olmaz. İdempotent eşleşmede yanıt durumu 200 OK (Location başlığı olmadan), yeni çekimde 201 Created olur.

Bu; kararsız ağlara, çöken işçilere ve yeniden deneme döngülerine karşı güvenlik ağınızdır. Aynı ödeme çıkışı için aynı kimliği kullanın; yeni bir çıkış için yeni kimlik seçin.

Hatalar

Tam katalog için bkz. Hata Kodları. Her hata yanıtındaki type URI'si ilgili satıra doğrudan bağlanır.