GELİŞTİRİCİLER

Hesap İşlemleri API

Bakiyeyi okuyun, iade ve çekim talep edin, itirazları yanıtlayın ve webhook teslimatlarını yönetin. Her isteği Kimlik doğrulama bölümündeki gibi imzalayın.

Temel URLhttps://www.manuellsolutions.com/api/v3
API sürümü3.0.0

İşlemlere gidin

Ortam

SandboxCanlı

Gerçek para hareketi olmadan test edin.

Gerçek ödemeler. Canlı anahtar gerekir.

Bakiye

Kullanılabilir ve çekilebilir bakiyenizi okuyun.

Sandbox bakiyesi sanaldır. Sandbox ödemeleri valör beklemeden hemen available_amount alanına geçer; böylece çekimi hemen test edebilirsiniz.

Canlı bakiye gerçek tahsilatlardan oluşur. Ödeme valör tarihine kadar pending_settlement_amount alanında bekler, sonra available_amount alanına geçer.

GET/api/v3/balance

Bakiyeyi getir

Yanıt · 200

Bakiye özeti.

`Balance`

Alan	Tür	Zorunlu	Açıklama
`currency_code`	`string`	Zorunlu	Yapılandırılmış platform taban para birimi. `USDEURAEDTRY`
`available_amount`	`string`	Zorunlu	Ödeme bağlantısı, API ve mağaza cüzdanlarının toplam kullanılabilir bakiyesi. Sandbox anahtarı bunun yerine yalıtılmış sanal API cüzdanını okur.
`pending_settlement_amount`	`string`	Zorunlu	Tahsil edildi ancak henüz hesaba geçmedi (valör tarihi bekleniyor). Sandbox anahtarıyla her zaman 0.00'dır; çünkü sandbox ödemeleri valör tarihini beklemez.
`environment`	`string`	Zorunlu	Rakamların ait olduğu ortam (imzalayan anahtarın ortamı). `livesandbox`

Yanıt · Örnek

{
  "currency_code": "USD",
  "available_amount": "48200.00",
  "pending_settlement_amount": "250.00",
  "environment": "live"
}

Olası hatalar

9000026503

GET/api/v3/balance/withdrawable

Çekilebilir bakiyeyi getir

Yanıt · 200

Çekilebilir bakiye özeti.

`WithdrawableBalance`

Alan	Tür	Zorunlu	Açıklama
`currency_code`	`string`	Zorunlu	Yapılandırılmış platform taban para birimi. `USDEURAEDTRY`
`withdrawable_amount`	`string`	Zorunlu	Ödeme bağlantısı, API ve mağaza bakiyelerinin toplam kullanılabilir tutarı; POST /withdrawals yalnızca API cüzdanından düşebilir ve ek denetimler uygular. Sandbox anahtarı yalıtılmış sanal API cüzdanını okur.
`can_withdraw`	`boolean`	Zorunlu	Cüzdan bölümlerinden biri negatifse değer false olur.
`environment`	`string`	Zorunlu	Rakamların ait olduğu ortam (imzalayan anahtarın ortamı). `livesandbox`

Yanıt · Örnek

{
  "currency_code": "USD",
  "withdrawable_amount": "48200.00",
  "can_withdraw": true,
  "environment": "live"
}

Olası hatalar

9000026503

İadeler

İade ya da iptal talep edin ve takip edin.

Canlıda HTTP 202, talebin alındığı anlamına gelir; iade tamamlanmadı. Sonucu durum uçlarından izleyin: requested, sonra awaiting_provider_manual, sonra completed; ya da rejected / cancelled.

Sandbox'ta talep hemen sonuçlanır (varsayılan completed). Reddedilen iadeyi denemek için X-CAV-Sandbox-Scenario: rejected başlığını gönderin.

Canlı talepler incelenir. Dönen iade kaydını completed, rejected veya cancelled olana kadar izleyin. refund kesinleşmiş ödemeyi iade eder, void kesinleşmemiş tahsilatı iptal eder. payment.refunded yalnız tamamlanan refund için gönderilir; void sonucunu GET ile izleyin.

POST/api/v3/refundsIdempotency-Key gerekir

İade ya da iptal talep et

Parametreler

Alan	Tür	Zorunlu	Açıklama
`X-CAV-Sandbox-Scenario`	`string · header`	İsteğe bağlı	Yalnızca sandbox anahtarları. Simüle edilen sonucu seçer: `completed` (varsayılan) ya da `rejected` (sanal cüzdana etkisi yoktur). Bu başlığı gönderen bir canlı anahtar ya da tanımlı değerler dışında bir değer gönderen herhangi bir anahtar 422 `1000001` alır. Başlık imzalanan metnin parçası değildir; Idempotency-Key parmak izinin parçasıdır, bu yüzden bir anahtarı başka bir senaryoyla yeniden kullanmak 9000010 döndürür. Uygulanan senaryo, aynı adlı yanıt başlığında geri yansıtılır. `completedrejected`

İstek gövdesi

Alan	Tür	Zorunlu	Açıklama
`payment_code`	`string`	Zorunlu	İade/iptal edilecek, başarıyla ödenmiş ödemenin kodu. `maxLength 16`
`operation_type`	`string`	Zorunlu	`refund` kesinleşmiş bir ödemeyi iade eder; `void` henüz kesinleşmemiş bir kart tahsilatını iptal eder. İkisi de bir geri alma talebi açar (durum `requested`). Bir operatör talebi inceler; onaylandığında tutar bakiyenizde ayrılır ve sağlayıcı iade referansı kaydedilene kadar durum `awaiting_provider_manual` olur (`completed`); aksi halde talep `rejected` ya da `cancelled` ile sona erer (ayrılan tutar serbest kalır). Bu uç sağlayıcıyı çağırmaz. `refundvoid`
`reason`	`string`	Zorunlu	İade/iptalin neden talep edildiği. `minLength 3maxLength 500`

İstek gövdesi · Örnek

{
  "payment_code": "ab34cdef",
  "operation_type": "refund",
  "reason": "Customer cancelled the order."
}

Yanıt · 202

İade/iptal talebi alındı. İnceleme ve sağlayıcıya iletme işlemi elle yapılır. Sandbox anahtarıyla simüle edilmiş sonuç döner (environment sandbox); idempotent bir tekrar da 202 döndürür.

`Reversal`

Alan	Tür	Zorunlu	Açıklama
`id`	`string`	Zorunlu	İade/iptal talebi tanımlayıcısı (UUID).
`operation`	`string`	Zorunlu	İşlem türü. `refundvoid`
`status`	`string`	Zorunlu	İade/iptal yaşam döngüsü: `requested` (operatör bekleniyor) → `awaiting_provider_manual` (onaylandı; sağlayıcı iade referansı kaydedilene kadar tutar ayrılır) → `completed`, ya da `rejected` / `cancelled` (ayrılan tutar serbest kalır). `processing` ve `failed`, bugün ödeme geri almaları için kullanılmayan ayrılmış değerlerdir. Sandbox anahtarıyla durum hemen kesinleşir: `completed` (varsayılan) ya da `rejected`. `requestedprocessingcompletedrejectedfailedawaiting_provider_manualcancelled`
`amount`	`string`	Zorunlu	İade/iptal edilen ödemenin tamamının tutarı; ödemenin kendi para biriminde (ödeme ve `payment.refunded` webhook'uyla aynı tutar ve para birimi), 2 ondalık haneli ondalık dizge olarak verilir. Durum requested olsa da para hareket etmiş sayılmaz.
`currency`	`string`	Zorunlu	`amount` alanının para birimi: iade/iptal edilen ödemenin `currency_code` değeri.
`reason`	`string`	Zorunlu	Belirttiğiniz gerekçe.
`provider_reference`	`string \| null`	Zorunlu	Gerçek POS iadesi tamamlandığında doldurulan sağlayıcı iade referansı. Sandbox'ta simüle edilen iade/iptal tamamlandığında `SBX-` ile başlayan sentetik bir referans döner; bu bir sağlayıcı kaydı değildir.
`provider_refunded_at`	`string · date-time \| null`	Zorunlu	Sağlayıcı iadesinin kaydedildiği zaman (UTC). Elle tamamlanana kadar null.
`created_at`	`string · date-time`	Zorunlu	İstek zamanı (UTC).
`updated_at`	`string · date-time \| null`	Zorunlu	Son durum değişikliği (UTC).
`payment_code`	`string \| null`	Zorunlu	Bu iade/iptal talebinin ait olduğu ödemenin kodu (ödeme oluşturulurken dönen `code`).
`environment`	`string`	Zorunlu	İade/iptal talebinin ortamı (imzalayan anahtarın ortamı). `livesandbox`

Yanıt · Örnek

{
  "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
  "operation": "refund",
  "status": "requested",
  "amount": "250.00",
  "currency": "USD",
  "reason": "Customer cancelled the order.",
  "provider_reference": "string",
  "provider_refunded_at": "2026-09-26T09:00:00.000Z",
  "created_at": "2026-09-26T09:00:00.000Z",
  "updated_at": "2026-09-26T09:00:00.000Z",
  "payment_code": "ab34cdef",
  "environment": "live"
}

Olası hatalar

GET/api/v3/refunds

İadeleri listele

Parametreler

Alan	Tür	Zorunlu	Açıklama
`page`	`integer · query`	İsteğe bağlı	Sayfa numarası. `minimum 1`
`per_page`	`integer · query`	İsteğe bağlı	Sayfa başına öğe sayısı. `minimum 1maximum 100`
`status`	`string · query`	İsteğe bağlı	Duruma göre filtreler. `requestedprocessingawaiting_provider_manualcompletedrejectedfailedcancelled`
`operation_type`	`string · query`	İsteğe bağlı	İşlem türüne göre filtreler. `refundvoid`

Yanıt · 200

Sayfalanmış iadeler.

Alan	Tür	Açıklama
`data`	`Reversal[]`
`meta`	`PaginationMeta`

Yanıt · Örnek

{
  "data": [
    {
      "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
      "operation": "refund",
      "status": "requested",
      "amount": "250.00",
      "currency": "USD",
      "reason": "Customer cancelled the order.",
      "provider_reference": "string",
      "provider_refunded_at": "2026-09-26T09:00:00.000Z",
      "created_at": "2026-09-26T09:00:00.000Z",
      "updated_at": "2026-09-26T09:00:00.000Z",
      "payment_code": "ab34cdef",
      "environment": "live"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

Olası hatalar

GET/api/v3/refunds/{id}

İade durumunu getir

Parametreler

Alan	Tür	Zorunlu	Açıklama
`id`	`string · uuid · path`	Zorunlu	İade/iptal talebinin kimliği.

Yanıt · 200

İade/iptal talebi.

Nesne: Reversal (alanlar İade ya da iptal talep et altında listelenir).

Yanıt · Örnek

{
  "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
  "operation": "refund",
  "status": "requested",
  "amount": "250.00",
  "currency": "USD",
  "reason": "Customer cancelled the order.",
  "provider_reference": "string",
  "provider_refunded_at": "2026-09-26T09:00:00.000Z",
  "created_at": "2026-09-26T09:00:00.000Z",
  "updated_at": "2026-09-26T09:00:00.000Z",
  "payment_code": "ab34cdef",
  "environment": "live"
}

Olası hatalar

Bildirim

İade tamamlandığında ödemenin webhook adresine imzalı bir payment.refunded bildirimi gönderilir. Başlıklar, imza ve yeniden denemeler Webhook’lar bölümündeki gibidir. void bildirim göndermez.

POSTpayment.refunded

Mağaza adresine imzalı payment.refunded bildirimi

İstek gövdesi

Alan	Tür	Zorunlu	Açıklama
`event_id`	`string · uuid`	Zorunlu
`event_type`	`string`	Zorunlu	`payment.refunded`
`environment`	`string`	Zorunlu	`sandboxlive`
`occurred_at`	`string · date-time`	Zorunlu
`refund`	`object`	Zorunlu
`refund.public_id`	`string · uuid`	Zorunlu
`refund.status`	`string`	Zorunlu	`completed`
`refund.amount`	`string`	Zorunlu	Sabit ölçekli, 2 ondalık haneli ondalık dizge olarak pozitif tutar. "0.00" kabul edilmez.
`refund.currency_code`	`string`	Zorunlu	Fiat para birimi kodu; desteklenen dört para birimiyle sınırlıdır. `USDEURAEDTRY`
`refund.completed_at`	`string · date-time`	Zorunlu	`occurred_at` ile aynı an.
`payment`	`object`	Zorunlu
`payment.public_id`	`string · uuid`	Zorunlu
`payment.code`	`string`	Zorunlu	`minLength 1maxLength 16`
`payment.merchant_reference`	`string \| null`	Zorunlu	`maxLength 64`
`order`	`object`	Zorunlu
`order.public_id`	`string · uuid`	Zorunlu

İstek gövdesi · Örnek

{
  "event_id": "B5D4E456-EFC1-4EC2-A613-D64A16E45BD5",
  "event_type": "payment.refunded",
  "environment": "sandbox",
  "occurred_at": "2026-09-28T12:00:00.000Z",
  "refund": {
    "public_id": "A1B2C3D4-E5F6-4789-8ABC-DEF012345678",
    "status": "completed",
    "amount": "100.00",
    "currency_code": "USD",
    "completed_at": "2026-09-28T12:00:00.000Z"
  },
  "payment": {
    "public_id": "11111111-2222-4333-8444-555555555555",
    "code": "ab34cdef",
    "merchant_reference": "SIP-2026-0001"
  },
  "order": {
    "public_id": "66666666-7777-4888-8999-AAAAAAAAAAAA"
  }
}

Çekimler

USDT (TRC20) çekimi talep edin ve takip edin.

Canlıda HTTP 201, talebin kabul edildiği ve tutarın bloke edildiği anlamına gelir; USDT'nin gönderildiği anlamına gelmez. status ve tx_hash alanlarını kontrol edin ve adresi iki kez doğrulayın; zincir üzerindeki transfer geri alınamaz.

Sandbox çekimi sanal bakiyeden düşer ve zincire hiçbir şey göndermez. Alt sınır, günlük üst sınır ve kur dahil canlıyla aynı kurallara tabidir. Reddi denemek için X-CAV-Sandbox-Scenario: rejected başlığını gönderin. Sandbox hedef olarak TRON sıfır adresini kabul eder; canlı, yakma adreslerini 1000030 ile reddeder.

En düşük tutar ve günlük üst sınır hesap bazında Manuell tarafından belirlenir; alt sınırın altında API 9000019, üst sınırın üstünde 9000021 döndürür. Canlıda USDT'yi Manuell operatörü gönderir ve tx_hash değerini girer (sent); ya da gerekçeyle reddeder (rejected) ve tutar bakiyenize döner.

POST/api/v3/withdrawalsIdempotency-Key gerekir

USDT çekimi talep et

Parametreler

Alan	Tür	Zorunlu	Açıklama
`X-CAV-Sandbox-Scenario`	`string · header`	İsteğe bağlı	Yalnızca sandbox anahtarları. Simüle edilen sonucu seçer: `sent` (varsayılan) ya da `rejected` (sanal cüzdana etkisi yoktur). Bu başlığı gönderen bir canlı anahtar ya da tanımlı değerler dışında bir değer gönderen herhangi bir anahtar 422 `1000001` alır. Başlık imzalanan metnin parçası değildir; Idempotency-Key parmak izinin parçasıdır, bu yüzden bir anahtarı başka bir senaryoyla yeniden kullanmak 9000010 döndürür. Uygulanan senaryo, aynı adlı yanıt başlığında geri yansıtılır. `sentrejected`

İstek gövdesi

Alan	Tür	Zorunlu	Açıklama
`amount`	`string`	Zorunlu	API cüzdanından bloke edilecek tutar; yapılandırılmış platform taban para biriminde, 2 ondalık haneli ondalık dizge olarak verilir. En düşük tutar ve günlük üst sınır hesap bazında platform operatörü tarafından belirlenir: en düşük tutarın altındaki tutar 9000019, günlük üst sınırın üstündeki tutar 9000021 döndürür. Sınırlarınızı hesap yöneticinize sorun.
`address`	`string`	Zorunlu	USDT TRC20 çekimi için kontrol ettiğiniz kendi TRON adresiniz. Örnekteki değer yer tutucudur ve değiştirilmeden gönderilirse reddedilir. `maxLength 64`
`address_acknowledged`	`boolean`	Zorunlu	true olmalıdır — hedef adresin doğru olduğunu ve işlemin geri alınamaz olduğunu onaylarsınız.

İstek gövdesi · Örnek

{
  "amount": "250.00",
  "address": "REPLACE_WITH_YOUR_TRON_ADDRESS",
  "address_acknowledged": true
}

Yanıt · 201

Çekim talep edildi. Bakiye bloke edilir; zincir üstü gönderim elle yapılır. Sandbox anahtarıyla simüle edilmiş sonuç döner (environment sandbox); idempotent bir tekrar da 201 döndürür.

`Withdrawal`

Alan	Tür	Zorunlu	Açıklama
`id`	`string`	Zorunlu	Çekim talebi tanımlayıcısı (UUID).
`status`	`string`	Zorunlu	Çekim yaşam döngüsü durumu: `requested` → `sent` ya da `rejected`. Zincir üstü gönderimi platform operatörü elle yapar. Sandbox anahtarıyla durum hemen kesinleşir: `sent` (varsayılan) ya da `rejected`. `requestedsentrejected`
`amount`	`string`	Zorunlu	API cüzdanından talep edilen ve bloke edilen tutar; platform taban para biriminde, 2 ondalık haneli ondalık dizge olarak verilir; USDT tutarı değildir.
`currency`	`string`	Zorunlu	Tutarın ifade edildiği taban para birimi.
`asset`	`string`	Zorunlu	Çekim varlığı (USDT).
`network`	`string`	Zorunlu	Çekim ağı (TRC20).
`address`	`string`	Zorunlu	Belirttiğiniz hedef adres.
`usdt_amount`	`string`	Zorunlu	Talep kabul edildiğinde hesaplanan USDT tutarı; sabit ölçekli, 6 ondalık haneli ondalık dizge. Bu alan tek başına zincir üstü bir transferi doğrulamaz.
`tx_hash`	`string \| null`	Zorunlu	Gönderimden sonra doldurulan zincir üstü işlem özeti (hash). Sandbox'ta `sent` durumundaki bir çekim için 64 karakterlik sentetik bir hash döner; zincirde hiçbir transfer yapılmaz.
`rejection_reason`	`string \| null`	Zorunlu	Reddedilirse doldurulan gerekçe. Sandbox'ta reddedilen bir çekimde `Sandbox scenario: rejected` yer alır.
`requested_at`	`string · date-time`	Zorunlu	İstek zamanı (UTC).
`processed_at`	`string · date-time \| null`	Zorunlu	Gönderildiği ya da reddedildiği zaman (UTC).
`created_at`	`string · date-time`	Zorunlu	Kaydın oluşturulma zamanı (UTC).
`environment`	`string`	Zorunlu	Çekimin ortamı (imzalayan anahtarın ortamı). `livesandbox`

Yanıt · Örnek

{
  "id": "7F0C2A94-3B1E-4D58-9A6F-1C2D3E4F5A6B",
  "status": "requested",
  "amount": "250.00",
  "currency": "USD",
  "asset": "USDT",
  "network": "TRC20",
  "address": "REPLACE_WITH_YOUR_TRON_ADDRESS",
  "usdt_amount": "249.000000",
  "tx_hash": null,
  "rejection_reason": null,
  "requested_at": "2026-09-26T09:30:00.000Z",
  "processed_at": null,
  "created_at": "2026-09-26T09:30:00.000Z",
  "environment": "live"
}

Olası hatalar

GET/api/v3/withdrawals

Çekimleri listele

Parametreler

Alan	Tür	Zorunlu	Açıklama
`page`	`integer · query`	İsteğe bağlı	Sayfa numarası. `minimum 1`
`per_page`	`integer · query`	İsteğe bağlı	Sayfa başına öğe sayısı. `minimum 1maximum 100`
`status`	`string · query`	İsteğe bağlı	Duruma göre filtreler. `requestedsentrejected`

Yanıt · 200

Sayfalanmış çekimler.

Alan	Tür	Açıklama
`data`	`Withdrawal[]`
`meta`	`PaginationMeta`

Yanıt · Örnek

{
  "data": [
    {
      "id": "7F0C2A94-3B1E-4D58-9A6F-1C2D3E4F5A6B",
      "status": "requested",
      "amount": "250.00",
      "currency": "USD",
      "asset": "USDT",
      "network": "TRC20",
      "address": "REPLACE_WITH_YOUR_TRON_ADDRESS",
      "usdt_amount": "249.000000",
      "tx_hash": null,
      "rejection_reason": null,
      "requested_at": "2026-09-26T09:30:00.000Z",
      "processed_at": null,
      "created_at": "2026-09-26T09:30:00.000Z",
      "environment": "live"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

Olası hatalar

GET/api/v3/withdrawals/{id}

Çekim durumunu getir

Parametreler

Alan	Tür	Zorunlu	Açıklama
`id`	`string · uuid · path`	Zorunlu	Çekim kimliği.

Yanıt · 200

Çekim.

Nesne: Withdrawal (alanlar USDT çekimi talep et altında listelenir).

Yanıt · Örnek

{
  "id": "7F0C2A94-3B1E-4D58-9A6F-1C2D3E4F5A6B",
  "status": "requested",
  "amount": "250.00",
  "currency": "USD",
  "asset": "USDT",
  "network": "TRC20",
  "address": "REPLACE_WITH_YOUR_TRON_ADDRESS",
  "usdt_amount": "249.000000",
  "tx_hash": null,
  "rejection_reason": null,
  "requested_at": "2026-09-26T09:30:00.000Z",
  "processed_at": null,
  "created_at": "2026-09-26T09:30:00.000Z",
  "environment": "live"
}

Olası hatalar

İtirazlar

İtirazları listeleyin ve kanıtınızı gönderin.

İtirazlar kart kuruluşlarından geldiği için sandbox'ta test itirazını POST /api/v3/sandbox/disputes ile kendiniz oluşturursunuz. Bkz. Hesap işlemlerini test etme.

İtiraz, banka bildirdiğinde Manuell tarafından kaydedilir. İtiraz edilen tutar bakiyenizden düşer (bakiye eksiye inebilir ve can_withdraw false olur); kazanırsanız geri eklenir. Kanıtınızı evidence_due_at tarihinden önce gönderin; itiraz açıkken yeni bir Idempotency-Key önceki notunuzu değiştirir.

GET/api/v3/disputes

İtirazları listele

Parametreler

Alan	Tür	Zorunlu	Açıklama
`page`	`integer · query`	İsteğe bağlı	Sayfa numarası. `minimum 1`
`per_page`	`integer · query`	İsteğe bağlı	Sayfa başına öğe sayısı. `minimum 1maximum 100`
`status`	`string · query`	İsteğe bağlı	Duruma göre filtreler. `openunder_reviewwonlost`

Yanıt · 200

Sayfalanmış itirazlar.

Alan	Tür	Açıklama
`data`	`Dispute[]`
`meta`	`PaginationMeta`

`Dispute`

Alan	Tür	Zorunlu	Açıklama
`id`	`string`	Zorunlu	İtiraz tanımlayıcısı (UUID).
`service`	`string`	Zorunlu	Kendisine itiraz edilen ödemenin ait olduğu hizmet: bu API üzerinden oluşturulan ödeme için `api`, ödeme bağlantısı için `link`.
`amount`	`string`	Zorunlu	İtiraz edilen tutar (ondalık dizge).
`currency`	`string`	Zorunlu	İtirazın para birimi.
`status`	`string`	Zorunlu	İtiraz durumu. `openunder_reviewwonlost`
`reason`	`string`	Zorunlu	İtirazın neden kategorisi. `fraudunauthorizedproduct_not_deliveredduplicateamount_mismatchother`
`reason_note`	`string \| null`	Zorunlu	Bankanın gerekçe notu, olduğu gibi.
`occurred_on`	`string · date`	Zorunlu	İtirazın açıldığı tarih (YYYY-MM-DD).
`evidence_due_at`	`string · date-time \| null`	Zorunlu	Kanıt gönderme son tarihi (UTC). Sandbox itirazı, oluşturulduktan sonra 7 gün boyunca kanıt için açık kalır.
`evidence_submitted_at`	`string · date-time \| null`	Zorunlu	Platformun savunmayı bankaya ilettiği zaman.
`merchant_evidence_note`	`string \| null`	Zorunlu	Gönderdiğiniz not.
`merchant_evidence_submitted_at`	`string · date-time \| null`	Zorunlu	Notunuzu gönderdiğiniz zaman.
`resolved_at`	`string · date-time \| null`	Zorunlu	İtirazın sonuçlandığı zaman.
`created_at`	`string · date-time`	Zorunlu	Kaydın oluşturulma zamanı (UTC).
`payment_code`	`string \| null`	Zorunlu	İtirazın ait olduğu API ödemesinin kodu (ödeme oluşturulurken dönen `code`); itiraz bir API ödemesine bağlı değilse null.
`environment`	`string`	Zorunlu	İtirazın ortamı (imzalayan anahtarın ortamı). `livesandbox`

Yanıt · Örnek

{
  "data": [
    {
      "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
      "service": "api",
      "amount": "250.00",
      "currency": "USD",
      "status": "open",
      "reason": "fraud",
      "reason_note": "string",
      "occurred_on": "2026-09-26",
      "evidence_due_at": "2026-09-26T09:00:00.000Z",
      "evidence_submitted_at": "2026-09-26T09:00:00.000Z",
      "merchant_evidence_note": "string",
      "merchant_evidence_submitted_at": "2026-09-26T09:00:00.000Z",
      "resolved_at": "2026-09-26T09:00:00.000Z",
      "created_at": "2026-09-26T09:00:00.000Z",
      "payment_code": "ab34cdef",
      "environment": "live"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

Olası hatalar

GET/api/v3/disputes/{id}

İtirazı getir

Parametreler

Alan	Tür	Zorunlu	Açıklama
`id`	`string · uuid · path`	Zorunlu	İtiraz kimliği.

Yanıt · 200

İtiraz.

Nesne: Dispute (alanlar İtirazları listele altında listelenir).

Yanıt · Örnek

{
  "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
  "service": "api",
  "amount": "250.00",
  "currency": "USD",
  "status": "open",
  "reason": "fraud",
  "reason_note": "string",
  "occurred_on": "2026-09-26",
  "evidence_due_at": "2026-09-26T09:00:00.000Z",
  "evidence_submitted_at": "2026-09-26T09:00:00.000Z",
  "merchant_evidence_note": "string",
  "merchant_evidence_submitted_at": "2026-09-26T09:00:00.000Z",
  "resolved_at": "2026-09-26T09:00:00.000Z",
  "created_at": "2026-09-26T09:00:00.000Z",
  "payment_code": "ab34cdef",
  "environment": "live"
}

Olası hatalar

POST/api/v3/disputes/{id}/evidenceIdempotency-Key gerekir

İtiraz kanıtı gönder

Parametreler

Alan	Tür	Zorunlu	Açıklama
`id`	`string · uuid · path`	Zorunlu	İtiraz kimliği.

İstek gövdesi

Alan	Tür	Zorunlu	Açıklama
`note`	`string`	Zorunlu	İtiraz için kanıt metniniz. `minLength 3maxLength 4000`

İstek gövdesi · Örnek

{
  "note": "Order 4821 was delivered on 2026-09-25. Carrier reference ABC123."
}

Yanıt · 200

Kanıt kaydedildi; itirazın durumu değişmez. Aynı idempotent tekrar, özgün yanıt gövdesini döndürür.

Nesne: Dispute (alanlar İtirazları listele altında listelenir).

Yanıt · Örnek

{
  "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
  "service": "api",
  "amount": "250.00",
  "currency": "USD",
  "status": "open",
  "reason": "fraud",
  "reason_note": "string",
  "occurred_on": "2026-09-26",
  "evidence_due_at": "2026-09-26T09:00:00.000Z",
  "evidence_submitted_at": "2026-09-26T09:00:00.000Z",
  "merchant_evidence_note": "string",
  "merchant_evidence_submitted_at": "2026-09-26T09:00:00.000Z",
  "resolved_at": "2026-09-26T09:00:00.000Z",
  "created_at": "2026-09-26T09:00:00.000Z",
  "payment_code": "ab34cdef",
  "environment": "live"
}

Olası hatalar

Teslimatları yönetin

Webhook teslimatlarını inceleyin ve başarısızları yeniden gönderin.

Bildirimlerin gideceği adres ortam başına “API anahtarı ve entegrasyon” sayfasında belirlenir. Aşağıdaki uçlar teslimatları listeler ve başarısız olanları yeniden kuyruğa alır.

GET/api/v3/webhooks/deliveries

Webhook teslimatlarını listele

Parametreler

Alan	Tür	Zorunlu	Açıklama
`page`	`integer · query`	İsteğe bağlı	Sayfa numarası. `minimum 1`
`per_page`	`integer · query`	İsteğe bağlı	Sayfa başına öğe sayısı. `minimum 1maximum 100`
`status`	`string · query`	İsteğe bağlı	Duruma göre filtreler. `pendingdeliveredfailed`

Yanıt · 200

Sayfalanmış teslimatlar.

Alan	Tür	Açıklama
`data`	`WebhookDelivery[]`
`meta`	`PaginationMeta`

`WebhookDelivery`

Alan	Tür	Açıklama
`id`	`string`	Teslimat tanımlayıcısı (UUID).
`event`	`string`	Teslimatın olay türü: `payment.paid`, `payment.refunded` veya `payment.failed`. Başarısız deneme kesin sonuç değildir; ödeme created kalır ve daha sonra ödenebilir.
`status`	`string`	Teslimat durumu. `pendingdeliveredfailed`
`payment_code`	`string \| null`	İlgili ödeme kodu (varsa).
`attempt_count`	`integer`	Şimdiye kadarki teslimat denemesi sayısı.
`last_status_code`	`integer \| null`	Son denemenin HTTP durumu.
`last_error`	`string \| null`	Eski ham teslimat hatası; last_error_code ve last_error_message kullanın.
`last_error_code`	`string \| null`	Kararlı, makine tarafından okunabilir teslimat hata kodu. `invalid_webhook_targetwebhook_target_private_networkwebhook_environment_invalidwebhook_signing_unavailablewebhook_response_unsuccessfulwebhook_egress_proxy_unreachablewebhook_unreachablewebhook_delivery_failed`
`last_error_message`	`string \| null`	Accept-Language ile seçilen kısa, insanın okuyacağı teslimat hata iletisi.
`next_attempt_at`	`string · date-time \| null`	Bir sonraki yeniden denemenin planlandığı zaman (UTC).
`delivered_at`	`string · date-time \| null`	Teslim edildiği zaman (UTC).
`created_at`	`string · date-time`	Kaydın oluşturulma zamanı (UTC).

Yanıt · Örnek

{
  "data": [
    {
      "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
      "event": "payment.paid",
      "status": "pending",
      "payment_code": null,
      "attempt_count": 1,
      "last_status_code": null,
      "last_error": null,
      "last_error_code": null,
      "last_error_message": null,
      "next_attempt_at": null,
      "delivered_at": null,
      "created_at": "2026-09-26T09:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

Olası hatalar

1000001422

GET/api/v3/webhooks/deliveries/{id}

Webhook teslimatını getir

Parametreler

Alan	Tür	Zorunlu	Açıklama
`id`	`string · uuid · path`	Zorunlu	Teslimat kimliği.

Yanıt · 200

Teslimat; url ve payload dahil.

`WebhookDeliveryDetail`

Alan	Tür	Açıklama
`id`	`string`	Teslimat tanımlayıcısı (UUID).
`event`	`string`	Teslimatın olay türü: `payment.paid`, `payment.refunded` veya `payment.failed`. Başarısız deneme kesin sonuç değildir; ödeme created kalır ve daha sonra ödenebilir.
`status`	`string`	Teslimat durumu. `pendingdeliveredfailed`
`payment_code`	`string \| null`	İlgili ödeme kodu (varsa).
`attempt_count`	`integer`	Şimdiye kadarki teslimat denemesi sayısı.
`last_status_code`	`integer \| null`	Son denemenin HTTP durumu.
`last_error`	`string \| null`	Eski ham teslimat hatası; last_error_code ve last_error_message kullanın.
`last_error_code`	`string \| null`	Kararlı, makine tarafından okunabilir teslimat hata kodu. `invalid_webhook_targetwebhook_target_private_networkwebhook_environment_invalidwebhook_signing_unavailablewebhook_response_unsuccessfulwebhook_egress_proxy_unreachablewebhook_unreachablewebhook_delivery_failed`
`last_error_message`	`string \| null`	Accept-Language ile seçilen kısa, insanın okuyacağı teslimat hata iletisi.
`next_attempt_at`	`string · date-time \| null`	Bir sonraki yeniden denemenin planlandığı zaman (UTC).
`delivered_at`	`string · date-time \| null`	Teslim edildiği zaman (UTC).
`created_at`	`string · date-time`	Kaydın oluşturulma zamanı (UTC).
`url`	`string`	Bu teslimat için webhook adresiniz.
`payload`	`object \| null`	Gönderilen JSON gövdesi.

Yanıt · Örnek

{
  "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
  "event": "payment.paid",
  "status": "pending",
  "payment_code": null,
  "attempt_count": 1,
  "last_status_code": null,
  "last_error": null,
  "last_error_code": null,
  "last_error_message": null,
  "next_attempt_at": null,
  "delivered_at": null,
  "created_at": "2026-09-26T09:00:00.000Z",
  "url": "string",
  "payload": null
}

Olası hatalar

9000024404

POST/api/v3/webhooks/deliveries/{id}/retryIdempotency-Key gerekir

Başarısız teslimatı yeniden dene

Parametreler

Alan	Tür	Zorunlu	Açıklama
`id`	`string · uuid · path`	Zorunlu	Teslimat kimliği.

Yanıt · 200

Başarısız teslimat yeniden kuyruğa alındı. Aynı idempotent tekrar, yeni bir deneme yapmadan ilk kuyruğa alma yanıtını döndürür.

Nesne: WebhookDeliveryDetail (alanlar Webhook teslimatını getir altında listelenir).

Yanıt · Örnek

{
  "id": "9B2E6F3A-0C1D-4E5F-8A7B-000000000001",
  "event": "payment.paid",
  "status": "pending",
  "payment_code": null,
  "attempt_count": 1,
  "last_status_code": null,
  "last_error": null,
  "last_error_code": null,
  "last_error_message": null,
  "next_attempt_at": null,
  "delivered_at": null,
  "created_at": "2026-09-26T09:00:00.000Z",
  "url": "string",
  "payload": null
}

Olası hatalar

Teslimat hataları

last_error eski alandır; yeni entegrasyonlarda last_error_code kullanın.

Alan	Açıklama
`invalid_webhook_target`	Webhook hedefi geçersiz.
`webhook_target_private_network`	Webhook hedefi özel bir ağa çözümleniyor.
`webhook_environment_invalid`	Webhook ortamı geçersiz.
`webhook_signing_unavailable`	Webhook imzalanamadı.
`webhook_response_unsuccessful`	Hedef 2xx dışında yanıt verdi.
`webhook_egress_proxy_unreachable`	Teslimat çıkış vekiline ulaşılamadı.
`webhook_unreachable`	Webhook hedefine ulaşılamadı.
`webhook_delivery_failed`	Webhook teslimatı başarısız oldu.

Hizmet durumu ve bakım

Bazı hizmetler geçici olarak bakıma alınabilir. Yalnızca yeni işler etkilenir; bu bölüm nelerin durduğunu, nelerin çalışmaya devam ettiğini ve durumun nasıl sorgulanacağını anlatır.

GET/api/v3/service-statusHerkese açık

Hizmet durumunu getir

Yanıt · 200

Bakımdaki hizmetler (liste boş olabilir).

Alan	Tür	Zorunlu	Açıklama
`data`	`ServiceStatusItem[]`	Zorunlu	Şu anda bakımda olan hizmetler; boş liste hiçbirinin bakımda olmadığı anlamına gelir.

`ServiceStatusItem`

Alan	Tür	Zorunlu	Açıklama
`service`	`string`	Zorunlu	Hizmet kodu: `api_collection` (API üzerinden oluşturulan ödemeler ve ödeme sayfaları), `withdrawals` (çekim talepleri) ya da `link_collection`, `storefront`, `usdt_sales` ve `balance_load` (platformun diğer hizmetleri). `api_collectionlink_collectionwithdrawalsstorefrontusdt_salesbalance_load`
`until`	`string · date-time \| null`	Zorunlu	Tahmini dönüş zamanı (UTC, ISO-8601) ya da null. Yalnızca bir tahmindir: bakım kendiliğinden bitmez ve bu zaman geçtikten sonra alan null olur.
`note`	`string \| null`	Zorunlu	Platform operatöründen gelen kısa düz metin mesajı ya da null. `maxLength 240`

Yanıt · Örnek

{
  "data": [
    {
      "service": "api_collection",
      "until": "2026-10-01T12:00:00Z",
      "note": "Planned maintenance."
    }
  ]
}

Diğer yanıtlar

429İstek sınırı aşıldı.

Olası hatalar

1000005429

Sayfalama

Liste uçları page (varsayılan 1) ve per_page (varsayılan 20, en fazla 100) alır; data ve meta döndürür.

`PaginationMeta`

Alan	Tür	Zorunlu	Açıklama
`page`	`integer`	Zorunlu	Sayfa numarası (1'den başlar).
`per_page`	`integer`	Zorunlu	Sayfa başına öğe sayısı (1–100).
`total`	`integer`	Zorunlu	Eşleşen toplam kayıt sayısı.
`total_pages`	`integer`	Zorunlu	ceil(total / per_page).

Hesap işlemlerini test etme

Bakiye, iade, çekim ve itirazlar sandbox'ta canlıyla aynı uçlar, gövdeler ve hata kodlarıyla çalışır.

Sandbox ödemeleri valör beklemeden hemen available_amount alanına geçer.
İade ve çekim talepleri hemen sonuçlanır. Sonucu X-CAV-Sandbox-Scenario başlığı belirler.
İtirazlar bankadan geldiği için sandbox'ta POST /api/v3/sandbox/disputes ile oluşturursunuz.

İade, çekim ve itiraz testlerini “Sandbox işlemleri” sayfasından izleyin.

Sonucu seçme

İade ve çekim talepleri canlıyla aynı uçları ve gövdeleri kullanır. Sonucu seçmek için isteğe bağlı X-CAV-Sandbox-Scenario başlığını ekleyin. Başlık imzaya dahil değildir. Canlı anahtarla gönderilen başlık 422 (1000001) ile reddedilir; böylece bir test hiçbir zaman gerçek bir isteğe dönüşmez.

X-CAV-Sandbox-Scenario

X-CAV-Sandbox-Scenario: rejected

Uç nokta	Başlık değerleri	Varsayılan	Etki
`POST /api/v3/refunds`	`completed` `rejected`	`completed`	`completed` iadeyi sonuçlandırır ve sanal bakiyeden düşer; `rejected` reddi kaydeder, bakiyeyi değiştirmez.
`POST /api/v3/withdrawals`	`sent` `rejected`	`sent`	`sent` sanal bakiyeden düşer ve `tx_hash` alanını yer tutucu bir değerle doldurur; `rejected` tutarı serbest bırakır.
`POST /api/v3/sandbox/disputes`	`open` `won` `lost`	`open`	Başlıkla değil, istek gövdesinde verilir: `open`, `won` ya da `lost`.

Test itirazı

İtirazlar kart kuruluşlarından gelir; canlıda sizin tarafınızdan başlatılamaz. Bu, tek sandbox'a özel uçtur: ödenmiş bir sandbox ödemesi için test itirazı oluşturur ve canlıdaki Dispute nesnesini döndürür.

POST/api/v3/sandbox/disputesIdempotency-Key gerekir

Ödenmiş bir sandbox ödemesi için sandbox itirazı oluştur

İstek gövdesi

Alan	Tür	Zorunlu	Açıklama
`payment_code`	`string`	Zorunlu	Kendi sandbox anahtarınızla oluşturulmuş, ödenmiş bir ödemenin koduyla değiştirin. `maxLength 16`
`scenario`	`string`	İsteğe bağlı	Kaydedilecek sonuç: `open` (varsayılan) kanıt için açık kalır; `won` ve `lost` zaten sonuçlanmıştır. `openwonlost`
`reason`	`string`	Zorunlu	İtiraz neden kategorisi; `Dispute.reason` ile aynı değerler. `fraudunauthorizedproduct_not_deliveredduplicateamount_mismatchother`

İstek gövdesi · Örnek

{
  "payment_code": "ab34cdef",
  "scenario": "open",
  "reason": "fraud"
}

Yanıt · 201

İtiraz kaydedildi; idempotent bir tekrar aynı itirazı döndürür.

Nesne: Dispute (alanlar İtirazları listele altında listelenir).

Yanıt · Örnek

{
  "id": "B5D4E456-EFC1-4EC2-A613-D64A16E45BD5",
  "service": "api",
  "amount": "250.00",
  "currency": "USD",
  "status": "open",
  "reason": "fraud",
  "reason_note": null,
  "occurred_on": "2026-09-30",
  "evidence_due_at": "2026-10-07T09:00:00.000Z",
  "evidence_submitted_at": null,
  "merchant_evidence_note": null,
  "merchant_evidence_submitted_at": null,
  "resolved_at": null,
  "created_at": "2026-09-30T09:00:00.000Z",
  "payment_code": "ab34cdef",
  "environment": "sandbox"
}