查询收款人列表 Try it ↗

GET /api/payees

查询当前账户下的收款人列表。

所需权限： payees:read

请求头：

x-api-key: sk-xxxxxxxxxxxxxxxxxxxx

Query 参数：

参数	类型	必填	默认值	说明
offset	number	否	0	分页偏移量
limit	number	否	10	每页条数，最大 1000
types	string	否	—	逗号分隔，过滤类型，如 SWIFT,CHINA_MAINLAND_BANK
keyword	string	否	—	收款人名称关键词搜索

示例请求

GET /api/payees?limit=20&types=SWIFT,CHINA_MAINLAND_BANK&keyword=Example

响应正文 (Body)

{
  "success": true,
  "data": {
    "payees": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "type": "SWIFT",
        "display_name": "Example Corp",
        "owner_id": "f0e1d2c3-b4a5-6789-0fed-cba987654321",
        "recipient_id": "e7f8a9b0-c1d2-3456-ef01-234567890abc",
        "details": {
          "recipient": {
            "account_type": "COMPANY",
            "country_code": "CHN",
            "transfer_type": "WIRE",
            "bank_name": "China Construction Bank",
            "bank_swift_code": "PCBCCNBJ",
            "bank_address": "Beijing, China",
            "account_number": "6217001234567890",
            "beneficiary_name": "Example Corp Ltd"
          }
        },
        "created_at": "2024-01-01T00:00:00.000Z",
        "updated_at": "2024-01-01T00:00:00.000Z"
      }
    ],
    "medias": {
      "d4e5f6a7-b8c9-0123-def0-1234567890ab": {
        "file_id": "d4e5f6a7-b8c9-0123-def0-1234567890ab",
        "url": "https://cdn.example.com/files/d4e5f6a7.pdf"
      }
    },
    "total": 42
  }
}

错误响应

// 400
{ "success": false, "message": "请求内容不正确" }

// 401
{ "success": false, "message": "未授权" }

// 403
{ "success": false, "message": "权限不足" }

示例代码

curl

curl -X GET "https://YOUR_API_ENDPOINT/api/payees?limit=20&types=SWIFT,CHINA_MAINLAND_BANK&keyword=Example" \
  -H "x-api-key: YOUR_API_KEY"

Java

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

public class ListPayees {
    public static void main(String[] args) throws Exception {
        String apiEndpoint = "YOUR_API_ENDPOINT";
        String apiKey = "YOUR_API_KEY";

        String query = String.format("limit=%d&types=%s&keyword=%s",
            20,
            URLEncoder.encode("SWIFT,CHINA_MAINLAND_BANK", StandardCharsets.UTF_8),
            URLEncoder.encode("Example", StandardCharsets.UTF_8));

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://" + apiEndpoint + "/api/payees?" + query))
            .header("x-api-key", apiKey)
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println("Status: " + response.statusCode());
        System.out.println("Body: " + response.body());
    }
}

Python

from urllib.request import Request, urlopen
from urllib.parse import urlencode

api_endpoint = "YOUR_API_ENDPOINT"
api_key = "YOUR_API_KEY"

params = urlencode({
    "limit": 20,
    "types": "SWIFT,CHINA_MAINLAND_BANK",
    "keyword": "Example",
})

req = Request(
    f"https://{api_endpoint}/api/payees?{params}",
    headers={"x-api-key": api_key},
    method="GET",
)

with urlopen(req) as resp:
    print(f"Status: {resp.status}")
    print(f"Body: {resp.read().decode('utf-8')}")

PHP

<?php
$apiEndpoint = "YOUR_API_ENDPOINT";
$apiKey      = "YOUR_API_KEY";

$query = http_build_query([
    "limit"   => 20,
    "types"   => "SWIFT,CHINA_MAINLAND_BANK",
    "keyword" => "Example",
]);

$ch = curl_init("https://{$apiEndpoint}/api/payees?{$query}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "x-api-key: {$apiKey}",
    ],
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "Status: {$httpCode}\n";
echo "Body: {$response}\n";

Go

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
)

func main() {
	apiEndpoint := "YOUR_API_ENDPOINT"
	apiKey := "YOUR_API_KEY"

	params := url.Values{}
	params.Set("limit", "20")
	params.Set("types", "SWIFT,CHINA_MAINLAND_BANK")
	params.Set("keyword", "Example")

	req, err := http.NewRequest("GET", "https://"+apiEndpoint+"/api/payees?"+params.Encode(), nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("x-api-key", apiKey)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Printf("Status: %d\n", resp.StatusCode)
	fmt.Printf("Body: %s\n", body)
}

JavaScript

const apiEndpoint = "YOUR_API_ENDPOINT";
const apiKey = "YOUR_API_KEY";

const params = new URLSearchParams({
  limit: "20",
  types: "SWIFT,CHINA_MAINLAND_BANK",
  keyword: "Example",
});

const resp = await fetch(`https://${apiEndpoint}/api/payees?${params}`, {
  method: "GET",
  headers: {
    "x-api-key": apiKey,
  },
});

console.log("Status:", resp.status);
console.log("Body:", await resp.json());