İçeriğe atlayın
API
.md olarak aç
Bu sayfada

Listele

Fatura iadelerini imleçli sayfalama ile listeleyin; fatura kimliği, durum veya oluşturulma zaman aralığına göre filtreleyin.

GET/v1/refunds

API anahtarı: Payment

Kimliği doğrulanmış Payment anahtarının kapsamındaki projelere ait fatura iadelerini created_at DESC, ardından withdrawal_id DESC sıralamasıyla döndürür. POST /v1/withdrawals ile oluşturulan normal üye işyeri çekimleri bu listede yer almaz.

Sorgu parametreleri

Parametre Tür Varsayılan Açıklama
limit integer 20 1 ile 100 arasında sayfa boyutu
cursor string — Önceki yanıttan alınan opak next_cursor değeri
invoice_id string — Önekli fatura kimliğine (inv_...) göre filtrele
status string — Tam snake_case durumu (created, signed, pending_review, cancelling, completed, failed, cancelled). Birden fazla durumu eşleştirmek için parametreyi tekrarlayın
created_from RFC 3339 — Saat dilimi içeren dahil created_at alt sınırı (ör. 2026-08-23T00:00:00Z)
created_to RFC 3339 — Saat dilimi içeren hariç created_at üst sınırı. created_from değerinden sonra olmalıdır

Bilinmeyen sorgu parametreleri, yinelenen durumlar ve geçersiz zaman damgaları 400 ile reddedilir.

Kod örnekleri

Her sekme ilgili dilin resmi SDK'sını bir Payment anahtarı (pk_) ile kullanır.

API_KEY_ID="pk_live_xxxxxxxxxxxx"
API_SECRET="sk_live_xxxxxxxxxxxx"
QUERY="?invoice_id=inv_7K2M9P4Q8R1X5Z3A0bC2dE&limit=20"

TS=$(date +%s)
# No body: the hash slot is the EMPTY STRING, not sha256("").
SIGNATURE=$(printf '%s\n%s\n%s\n%s\n%s' "$TS" GET /v1/refunds "$QUERY" '' \
  | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -sS "https://api.paymos.io/v1/refunds$QUERY" \
  -H "Authorization: HMAC-SHA256 $API_KEY_ID:$SIGNATURE" \
  -H "X-Request-Timestamp: $TS"
import { Paymos } from '@paymos/sdk';

const paymos = new Paymos({
  apiKey: process.env.PAYMOS_API_KEY,
  apiSecret: process.env.PAYMOS_API_SECRET,
});

const page = await paymos.refunds.list({
  invoiceId: 'inv_7K2M9P4Q8R1X5Z3A0bC2dE',
  limit: 20,
});

for await (const refund of paymos.refunds.iterate({ status: ['completed'] }, 10)) {
  console.log(refund.withdrawalId);
}
import os

from paymos import Paymos

paymos = Paymos(
    api_key=os.environ["PAYMOS_API_KEY"],
    api_secret=os.environ["PAYMOS_API_SECRET"],
)

page = paymos.refunds.list(invoice_id="inv_7K2M9P4Q8R1X5Z3A0bC2dE", limit=20)

for refund in paymos.refunds.iterate(10, status=["completed"]):
    print(refund["withdrawal_id"])
<?php
use Paymos\Client;
use Paymos\ClientConfig;

$paymos = new Client(new ClientConfig(
    getenv('PAYMOS_API_KEY'),
    getenv('PAYMOS_API_SECRET')
));

$page = $paymos->refunds()->listPage(array(
    'invoice_id' => 'inv_7K2M9P4Q8R1X5Z3A0bC2dE',
    'limit' => 20,
));

foreach ($paymos->refunds()->iterate(array('status' => array('completed')), 10) as $refund) {
    echo $refund['withdrawal_id'] . PHP_EOL;
}
package main

import (
	"context"
	"fmt"
	"os"

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

func main() {
	client, err := paymos.NewClient(os.Getenv("PAYMOS_API_KEY"), os.Getenv("PAYMOS_API_SECRET"))
	if err != nil {
		panic(err)
	}

	page, err := client.Refunds.List(context.Background(), paymos.RefundListParams{
		InvoiceID: "inv_7K2M9P4Q8R1X5Z3A0bC2dE",
		Limit:     20,
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(len(page.Items), page.NextCursor)

	iter := paymos.NewRefundIterator(client.Refunds, paymos.RefundListParams{
		Status: []paymos.WithdrawalStatus{paymos.WithdrawalCompleted},
	}, 10)
	for {
		refund, ok, err := iter.Next(context.Background())
		if err != nil {
			panic(err)
		}
		if !ok {
			break
		}
		fmt.Println(refund.WithdrawalID)
	}
}
using Paymos;

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

var page = await paymos.Refunds.ListAsync(new RefundListOptions(
    InvoiceId: "inv_7K2M9P4Q8R1X5Z3A0bC2dE",
    Limit: 20));

await foreach (var refund in paymos.Refunds.IterateAsync(
    new RefundListOptions(Status: [WithdrawalStatus.Completed]), maxPages: 10))
{
    Console.WriteLine(refund.WithdrawalId);
}
import io.paymos.Page;
import io.paymos.PaymosClient;
import io.paymos.Refund;
import io.paymos.RefundListOptions;
import io.paymos.WithdrawalStatus;

import java.util.List;

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

Page<Refund> page = paymos.refunds.list(RefundListOptions.builder()
    .invoiceId("inv_7K2M9P4Q8R1X5Z3A0bC2dE")
    .limit(20)
    .build());

for (Refund refund : paymos.refunds.iterate(
        RefundListOptions.builder().status(List.of(WithdrawalStatus.COMPLETED)).build(), 10)) {
    System.out.println(refund.withdrawalId());
}
require 'paymos'

paymos = Paymos::Client.new(
  api_key: ENV.fetch('PAYMOS_API_KEY'),
  api_secret: ENV.fetch('PAYMOS_API_SECRET')
)

page = paymos.refunds.list(invoice_id: 'inv_7K2M9P4Q8R1X5Z3A0bC2dE', limit: 20)

paymos.refunds.each(max_pages: 10, status: ['completed']) do |refund|
  puts refund.withdrawal_id
end
use paymos::{PaymosClient, RefundListParams, WithdrawalStatus};

let paymos = PaymosClient::new(
    std::env::var("PAYMOS_API_KEY")?,
    std::env::var("PAYMOS_API_SECRET")?,
)?;

let page = paymos
    .refunds()
    .list(&RefundListParams {
        invoice_id: Some("inv_7K2M9P4Q8R1X5Z3A0bC2dE".to_owned()),
        limit: Some(20),
        ..Default::default()
    })
    .await?;
println!("{} items, next_cursor={:?}", page.items.len(), page.next_cursor);

let mut pager = paymos.refunds().pager(
    RefundListParams { status: Some(vec![WithdrawalStatus::Completed]), ..Default::default() },
    Some(10),
)?;
while let Some(refund) = pager.next().await? {
    println!("{}", refund.withdrawal_id);
}

Yanıt (200 OK)

{
  "items": [
    {
      "withdrawal_id": "wdr_6Qm2fK8xR4vN7cT1bY9dL5",
      "invoice_id": "inv_7K2M9P4Q8R1X5Z3A0bC2dE",
      "mode": "full",
      "external_order_id": "refund-1042-full",
      "status": "completed",
      "is_final": true,
      "is_test": false,
      "amount": "100.00",
      "fee": "1.00",
      "currency": "USDT",
      "network": "TRC20",
      "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
      "first_sender": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
      "tx_hash": "9f3b8c2a1d0e4f6789abc123def4567890abc123def4567890abc123def45678",
      "explorer_url": "https://tronscan.org/#/transaction/9f3b8c2a1d0e4f6789abc123def4567890abc123def4567890abc123def45678",
      "created_at": 1767225600,
      "completed_at": 1767225932,
      "type": "refund",
      "project_id": "prj_3F9xL2mN8pQ4rT6vW1yZ5b"
    }
  ],
  "next_cursor": null
}

items içindeki her öğe, İadeyi Getir ile aynı yapıda tam iade kaynağını taşır.

Sayfalama kuralları

  • next_cursor değeri null dönene kadar takip edin.
  • İmleç /v1/refunds uç noktasına ve tam filtre parametrelerine (invoice_id, status, created_from, created_to) bağlıdır. Sayfalar arasında filtreleri değiştirmeyin; limit değişebilir.
  • İmleçler oluşturulduktan 24 saat sonra sona erer.
  • Anahtarınızın proje kapsamı dışında kalan bir invoice_id göndermek 404 yerine boş liste döndürür.

Hatalar

Payout (rk_) anahtarı 403 payment_key_required ile reddedilir. Geçersiz filtre değerleri 400, süresi dolmuş veya uyuşmayan imleç ise 400 pagination_cursor_invalid döndürür. Bkz. Hata Kodları.