پرداخت به مشتری

فهرست پرداخت‌ها به مشتری و بازپرداخت‌ها

GET/api/pay/v1/payouts

از جدید به قدیم، با صفحه‌بندی مکان‌نما. به کلیدی از کلاس پرداخت به مشتری نیاز دارد.

Authorization

bearerKey

AuthorizationBearer <token>

Authorization: Bearer clpay_live_<64 hex> for the checkout routes, Authorization: Bearer clpay_payout_<64 hex> for the payout routes. The wrong class on a route is PAY_WRONG_KEY_KIND (403).

In: header

Query Parameters

limit?integer

تعداد رکورد در هر صفحه.

Range1 <= value <= 100

Default25

cursor?string

مقدار next_cursor از صفحه قبل.

kind?string

فقط پرداخت‌ها به مشتری، یا فقط بازپرداخت‌ها.

Value in

"payout"
"refund"

from?string

کران پایین created_at به قالب ISO 8601.

Formatdate-time

to?string

کران بالای created_at به قالب ISO 8601.

Formatdate-time

`application/json`

curl -X GET "https://example.com/api/pay/v1/payouts"

{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "reference_id": "string",      "kind": "payout",      "status": "completed",      "currency": "string",      "amount": "string",      "debited_amount": "string",      "fee_amount": "string",      "fee_percent": "string",      "usd_value": "string",      "payer_id": "7bded2ff-6743-4a0e-a147-77540fb16606",      "payment_id": "d43b87f9-9e28-4802-8eaa-6ee91a40ea71",      "comment": "string",      "created_at": "2019-08-24T14:15:22Z",      "settled_at": "2019-08-24T14:15:22Z"    }  ],  "next_cursor": "string"}

پرداخت به یک مشتری

POST/api/pay/v1/payouts

از کیف‌پول کسب‌وکارتان به یک مشتری کوین‌لند ارز بفرستید. به کلیدی از کلاس پرداخت به مشتری نیاز دارد.

این فراخوانی همزمان است. کد ۲۰۱ یعنی پول جابه‌جا شده است — کیف‌پول کسب‌وکار شما به اندازه debited_amount بدهکار و موجودی اسپات گیرنده دقیقاً به اندازه amount بستانکار می‌شود، در یک تراکنش و پیش از نوشته‌شدن پاسخ. هیچ وضعیت «در انتظار»ی برای استعلام وجود ندارد.

گیرنده را دقیقاً به یکی از دو روش مشخص کنید (فرستادن هر دو یا هیچ‌کدام، PAY_RECIPIENT_INVALID می‌گیرد):

payer_id — دستگیره مبهمی که روی هر پرداختِ آن مشتری به شما آمده است. این مسیر معمول است: دستگیره را از قبل دارید، چیزی لازم نیست جست‌وجو شود و هیچ ایمیلی روی سیم نمی‌رود.
recipient_token به‌همراه recipient_confirm — مسیر ایمیل، برای پرداخت به کسی که تا حالا به شما پرداختی نکرده. اول POST /payouts/recipients/lookup را صدا بزنید، masked_name بازگشتی را به یک انسان نشان دهید و همان رشته را عیناً به‌عنوان recipient_confirm برگردانید. فقط وقتی در دسترس است که کوین‌لند دامنه پرداخت شما را روی any تنظیم کرده باشد.

کارمزد با شماست: گیرنده دقیقاً amount را دریافت می‌کند و کیف‌پول شما به اندازه amount + fee_amount بدهکار می‌شود، با همان نرخ پلکانی‌ای که روی پرداخت‌هایتان اعمال می‌شود. ارسال دوباره با همان reference_id و همان محتوا، پرداختِ اصلی را با کد ۲۰۱ برمی‌گرداند و دو بار پول نمی‌فرستد.

Authorization

bearerKey

AuthorizationBearer <token>

Authorization: Bearer clpay_live_<64 hex> for the checkout routes, Authorization: Bearer clpay_payout_<64 hex> for the payout routes. The wrong class on a route is PAY_WRONG_KEY_KIND (403).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reference_id*string

Your id for this payout — the idempotency key.

Lengthlength <= 128

currency*string

Coin slug (e.g. usdt). Any enabled crypto your business wallet holds — it does NOT have to be in your accepted checkout set. Toman is refused: this rail is crypto only.

amount*string

What the RECIPIENT receives, as a positive decimal string. The fee is added on top of it, not taken out of it.

payer_id?string

The recipient's handle, from a payment's payer_id. Mutually exclusive with recipient_token.

Formatuuid

recipient_token?string

The token from POST /payouts/recipients/lookup. Valid 10 minutes and only for the merchant that minted it.

Lengthlength <= 2048

recipient_confirm?string

The masked_name from that same lookup, echoed back character for character. Required with recipient_token.

Lengthlength <= 128

comment?string

A note for your own records and the recipient's notification.

Lengthlength <= 512

Response Body

`application/json`

curl -X POST "https://example.com/api/pay/v1/payouts" \  -H "Content-Type: application/json" \  -d '{    "reference_id": "payout-2291",    "currency": "usdt",    "amount": "25.00",    "payer_id": "7c1e5b90-3f42-4a86-9d05-2b8e4c1f6a37",    "comment": "Cashback for order 10492"  }'

{  "id": "9e3c7a41-0b52-4f18-8d6a-3c7e1f9b40d5",  "reference_id": "payout-2291",  "kind": "payout",  "status": "completed",  "currency": "usdt",  "amount": "25.00",  "debited_amount": "25.125",  "fee_amount": "0.125",  "fee_percent": "0.5",  "usd_value": "25.00",  "payer_id": "7c1e5b90-3f42-4a86-9d05-2b8e4c1f6a37",  "payment_id": null,  "comment": "Cashback for order 10492",  "created_at": "2026-08-11T09:31:04.000Z",  "settled_at": "2026-08-11T09:31:04.000Z"}

یافتن گیرنده با نشانی ایمیل

POST/api/pay/v1/payouts/recipients/lookup

یک نشانی ایمیل را به توکن امضاشده و کوتاه‌عمر recipient_token تبدیل می‌کند تا در POST /payouts خرجش کنید. به کلیدی از کلاس پرداخت به مشتری نیاز دارد و فقط برای کسب‌وکارهایی باز است که کوین‌لند دامنه پرداختشان را روی any گذاشته باشد؛ در غیر این صورت MERCHANT_PAYOUTS_DISABLED (۴۰۳) می‌گیرد. نشانی غیرقابل‌پرداخت — ناشناخته، فاقد شرایط یا بدون احراز هویت کامل — پاسخ PAY_RECIPIENT_INVALID (۴۲۲) می‌گیرد؛ یک کد برای همه این حالت‌ها، تا این نقطه راهی برای کاوش دفترچه کاربران نباشد.

توکن ۱۰ دقیقه اعتبار دارد، به کسب‌وکاری که آن را ساخته گره خورده، و گیرنده حل‌شده را داخل امضای خودش حمل می‌کند — خودِ ایمیل هرگز روی درخواست پرداخت سوار نمی‌شود.

masked_name کمکی برای بازشناسی است، نه شناسایی: آن را به یک انسان نشان دهید، تأیید بگیرید که همان کسی است که در نظر داشته، و همان را به‌عنوان recipient_confirm برگردانید. پرداختی که تأییدش نخوانَد رد می‌شود.

این اندپوینت عامدانه یک پیشگوی «این ایمیل حساب دارد یا نه» نیست. نشانی ناشناس، حساب غیرفعال، و حسابی که احراز هویت کاملش را تمام نکرده، هر سه همان PAY_RECIPIENT_INVALID را می‌گیرند، و جست‌وجوها برای هر کسب‌وکار سهمیه‌بندی شده است.

Authorization

bearerKey

AuthorizationBearer <token>

Authorization: Bearer clpay_live_<64 hex> for the checkout routes, Authorization: Bearer clpay_payout_<64 hex> for the payout routes. The wrong class on a route is PAY_WRONG_KEY_KIND (403).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

email*string

Formatemail

Lengthlength <= 320

Response Body

`application/json`

curl -X POST "https://example.com/api/pay/v1/payouts/recipients/lookup" \  -H "Content-Type: application/json" \  -d '{    "email": "customer@example.com"  }'

{  "recipient_token": "v1.eyJtZXJjaGFudElkIjo0Miwi….9f3c1d60ab72",  "masked_name": "A**** B****",  "expires_at": "2026-08-11T09:41:22.000Z"}

خواندن یک پرداخت به مشتری

GET/api/pay/v1/payouts/{id}

رکورد معتبر — همان چیزی که رویداد payout.completed به شما می‌گوید بیایید و بخوانید. به کلیدی از کلاس پرداخت به مشتری نیاز دارد.

Authorization

bearerKey

AuthorizationBearer <token>

Authorization: Bearer clpay_live_<64 hex> for the checkout routes, Authorization: Bearer clpay_payout_<64 hex> for the payout routes. The wrong class on a route is PAY_WRONG_KEY_KIND (403).

In: header

Path Parameters

id*string

شناسه پرداخت به مشتری (UUID) یا reference_id خودتان.

Response Body

`application/json`

curl -X GET "https://example.com/api/pay/v1/payouts/string"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "reference_id": "string",  "kind": "payout",  "status": "completed",  "currency": "string",  "amount": "string",  "debited_amount": "string",  "fee_amount": "string",  "fee_percent": "string",  "usd_value": "string",  "payer_id": "7bded2ff-6743-4a0e-a147-77540fb16606",  "payment_id": "d43b87f9-9e28-4802-8eaa-6ee91a40ea71",  "comment": "string",  "created_at": "2019-08-24T14:15:22Z",  "settled_at": "2019-08-24T14:15:22Z"}

بازپرداخت یک پرداخت

POST/api/pay/v1/payments/{id}/refund

ارز را به مشتری‌ای که به شما پرداخت کرده برگردانید. به کلیدی از کلاس پرداخت به مشتری نیاز دارد. مثل پرداخت به مشتری همزمان تسویه می‌شود و همان شیء را برمی‌گرداند، با kind برابر refund.

شما فقط مبلغ را تعیین می‌کنید. گیرنده و ارز از رکورد همان پرداخت خوانده می‌شوند، نه از درخواست — بازپرداخت از همان راهی برمی‌گردد که پول آمده بود، و اصلاً فیلدی وجود ندارد که با آن جای دیگری بفرستیدش.

بازپرداخت جزئی مجاز است و می‌تواند تکرار شود؛ آنچه سقف دارد جمع تجمعی است، برابر charged_amount همان پرداخت. عبور از آن PAY_REFUND_EXCEEDS_PAYMENT (۴۲۲) می‌گیرد.

بازپرداخت از کارمزد معاف است — fee_amount برابر "0" و debited_amount == amount. کوین‌لند کارمزدی را که روی پرداخت اصلی گرفته نگه می‌دارد و چیز تازه‌ای نمی‌گیرد، پس بازپرداخت فقط خودِ ارز را برای شما هزینه دارد. کارمزد اصلی برگردانده نمی‌شود.

Authorization

bearerKey

AuthorizationBearer <token>

Authorization: Bearer clpay_live_<64 hex> for the checkout routes, Authorization: Bearer clpay_payout_<64 hex> for the payout routes. The wrong class on a route is PAY_WRONG_KEY_KIND (403).

In: header

Path Parameters

id*string

شناسه پرداخت (UUID) یا شماره رسید (CLP-…).

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reference_id*string

Your id for this refund — the idempotency key.

Lengthlength <= 128

amount*string

How much to return, as a positive decimal string. May be less than the payment; cumulative refunds may not exceed its charged_amount.

comment?string

Lengthlength <= 512

Response Body

`application/json`

curl -X POST "https://example.com/api/pay/v1/payments/string/refund" \  -H "Content-Type: application/json" \  -d '{    "reference_id": "refund-10492-1",    "amount": "10.00",    "comment": "One item returned"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "reference_id": "string",  "kind": "payout",  "status": "completed",  "currency": "string",  "amount": "string",  "debited_amount": "string",  "fee_amount": "string",  "fee_percent": "string",  "usd_value": "string",  "payer_id": "7bded2ff-6743-4a0e-a147-77540fb16606",  "payment_id": "d43b87f9-9e28-4802-8eaa-6ee91a40ea71",  "comment": "string",  "created_at": "2019-08-24T14:15:22Z",  "settled_at": "2019-08-24T14:15:22Z"}

پرداخت به مشتری

200application/json

201application/json

403application/json

409application/json

422application/json

503application/json

200application/json

403application/json

422application/json

429application/json

200application/json

404application/json

201application/json

403application/json

404application/json

409application/json

422application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`