E-Pos ödemesini tamamen iptal veya iade et

{
  "status": true,
  "result": {
    "_id": "600000000000000000000002",
    "accountId": "600000000000000000000001",
    "reference": "600000000000000000000002",
    "status": "voided",
    "amountMinor": 10000,
    "amountEditable": true,
    "currency": "TRY",
    "pricingMode": "card",
    "saleRateMode": "family",
    "cardFamily": "paraf",
    "installmentOptions": [
      {
        "installment": 1,
        "saleRate": 0,
        "familySaleRates": []
      },
      {
        "installment": 3,
        "saleRate": 0,
        "familySaleRates": [
          {
            "family": "paraf",
            "saleRate": 0
          }
        ]
      }
    ],
    "expiresAt": "2026-10-25T09:30:00.000Z",
    "verification": "verified",
    "returnedMinor": 10000,
    "remainingMinor": 0,
    "activeReturnId": null,
    "returnOperations": [
      {
        "id": "600000000000000000000003",
        "amountMinor": 10000,
        "state": "verified",
        "kind": "void",
        "reason": null,
        "createdAt": "2026-10-25T09:00:00.000Z",
        "completedAt": "2026-10-25T09:00:00.000Z"
      }
    ],
    "reconciliation": {
      "checks": 0,
      "lastCheckedAt": null,
      "lastResult": null,
      "reason": null,
      "nextCheckAt": null
    },
    "startFailure": null,
    "url": "<yanıttan-alınan-ödeme-adresi>",
    "totalMinor": 10000,
    "saleCommissionMinor": 0,
    "purchaseCommissionMinor": 480,
    "netMinor": 9520,
    "installment": 3
  },
  "operation": {
    "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "type": "epos.return",
    "state": "succeeded",
    "reviewRequired": false,
    "retryable": false,
    "result": {
      "resultId": "600000000000000000000003",
      "paymentId": "600000000000000000000002"
    },
    "statusUrl": "/apps/operations/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-10-25T09:00:00.000Z",
    "updatedAt": "2026-10-25T09:00:00.000Z"
  }
}

{
  "status": false,
  "code": "BANKPOS_INVALID_REQUEST",
  "message": "İstek alanları geçersiz."
}

{
  "status": false,
  "code": "UNAUTHORIZED",
  "message": "API kimlik bilgileri doğrulanamadı."
}

{
  "status": false,
  "message": "Ürün, IP, modül izni veya kaynak kapsamı uygun değil."
}

{
  "status": false
}

{
  "status": false,
  "code": "OPERATION_IN_PROGRESS",
  "message": "İşlemi tekrar göndermeden durumunu kontrol edin.",
  "retryable": false,
  "reviewRequired": true,
  "operation": {
    "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "type": "epos.return",
    "state": "review_required",
    "reviewRequired": true,
    "retryable": false,
    "result": {
      "resultId": "600000000000000000000003",
      "paymentId": "600000000000000000000002"
    },
    "statusUrl": "/apps/operations/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-10-25T09:00:00.000Z",
    "updatedAt": "2026-10-25T09:00:00.000Z"
  }
}

{
  "status": false,
  "code": "BANKPOS_ACCOUNT_NOT_READY",
  "message": "İşlemin ön koşulları sağlanmadı."
}

{
  "status": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please try again later."
}

{
  "status": false,
  "code": "INTERNAL_ERROR",
  "message": "İşlem gerçekleştirilemedi."
}

{
  "status": false,
  "code": "UPSTREAM_RESULT_UNCERTAIN",
  "message": "İşlemi tekrar göndermeden durumunu kontrol edin.",
  "retryable": false,
  "reviewRequired": true,
  "operation": {
    "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "type": "epos.return",
    "state": "review_required",
    "reviewRequired": true,
    "retryable": false,
    "result": {
      "resultId": "600000000000000000000003",
      "paymentId": "600000000000000000000002"
    },
    "statusUrl": "/apps/operations/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-10-25T09:00:00.000Z",
    "updatedAt": "2026-10-25T09:00:00.000Z"
  }
}

{
  "status": false,
  "code": "OPERATION_RECORD_UNAVAILABLE",
  "message": "İşlemi tekrar göndermeden durumunu kontrol edin.",
  "retryable": false,
  "reviewRequired": true,
  "operation": {
    "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "type": "epos.return",
    "state": "review_required",
    "reviewRequired": true,
    "retryable": false,
    "result": {
      "resultId": "600000000000000000000003",
      "paymentId": "600000000000000000000002"
    },
    "statusUrl": "/apps/operations/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-10-25T09:00:00.000Z",
    "updatedAt": "2026-10-25T09:00:00.000Z"
  }
}

POST

https://api.muhasip.pro

apps

bankpos

payments

{paymentId}

returns

{
  "status": true,
  "result": {
    "_id": "600000000000000000000002",
    "accountId": "600000000000000000000001",
    "reference": "600000000000000000000002",
    "status": "voided",
    "amountMinor": 10000,
    "amountEditable": true,
    "currency": "TRY",
    "pricingMode": "card",
    "saleRateMode": "family",
    "cardFamily": "paraf",
    "installmentOptions": [
      {
        "installment": 1,
        "saleRate": 0,
        "familySaleRates": []
      },
      {
        "installment": 3,
        "saleRate": 0,
        "familySaleRates": [
          {
            "family": "paraf",
            "saleRate": 0
          }
        ]
      }
    ],
    "expiresAt": "2026-10-25T09:30:00.000Z",
    "verification": "verified",
    "returnedMinor": 10000,
    "remainingMinor": 0,
    "activeReturnId": null,
    "returnOperations": [
      {
        "id": "600000000000000000000003",
        "amountMinor": 10000,
        "state": "verified",
        "kind": "void",
        "reason": null,
        "createdAt": "2026-10-25T09:00:00.000Z",
        "completedAt": "2026-10-25T09:00:00.000Z"
      }
    ],
    "reconciliation": {
      "checks": 0,
      "lastCheckedAt": null,
      "lastResult": null,
      "reason": null,
      "nextCheckAt": null
    },
    "startFailure": null,
    "url": "<yanıttan-alınan-ödeme-adresi>",
    "totalMinor": 10000,
    "saleCommissionMinor": 0,
    "purchaseCommissionMinor": 480,
    "netMinor": 9520,
    "installment": 3
  },
  "operation": {
    "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "type": "epos.return",
    "state": "succeeded",
    "reviewRequired": false,
    "retryable": false,
    "result": {
      "resultId": "600000000000000000000003",
      "paymentId": "600000000000000000000002"
    },
    "statusUrl": "/apps/operations/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-10-25T09:00:00.000Z",
    "updatedAt": "2026-10-25T09:00:00.000Z"
  }
}

{
  "status": false,
  "code": "BANKPOS_INVALID_REQUEST",
  "message": "İstek alanları geçersiz."
}

{
  "status": false,
  "code": "UNAUTHORIZED",
  "message": "API kimlik bilgileri doğrulanamadı."
}

{
  "status": false,
  "message": "Ürün, IP, modül izni veya kaynak kapsamı uygun değil."
}

{
  "status": false
}

{
  "status": false,
  "code": "OPERATION_IN_PROGRESS",
  "message": "İşlemi tekrar göndermeden durumunu kontrol edin.",
  "retryable": false,
  "reviewRequired": true,
  "operation": {
    "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "type": "epos.return",
    "state": "review_required",
    "reviewRequired": true,
    "retryable": false,
    "result": {
      "resultId": "600000000000000000000003",
      "paymentId": "600000000000000000000002"
    },
    "statusUrl": "/apps/operations/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-10-25T09:00:00.000Z",
    "updatedAt": "2026-10-25T09:00:00.000Z"
  }
}

{
  "status": false,
  "code": "BANKPOS_ACCOUNT_NOT_READY",
  "message": "İşlemin ön koşulları sağlanmadı."
}

{
  "status": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please try again later."
}

{
  "status": false,
  "code": "INTERNAL_ERROR",
  "message": "İşlem gerçekleştirilemedi."
}

{
  "status": false,
  "code": "UPSTREAM_RESULT_UNCERTAIN",
  "message": "İşlemi tekrar göndermeden durumunu kontrol edin.",
  "retryable": false,
  "reviewRequired": true,
  "operation": {
    "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "type": "epos.return",
    "state": "review_required",
    "reviewRequired": true,
    "retryable": false,
    "result": {
      "resultId": "600000000000000000000003",
      "paymentId": "600000000000000000000002"
    },
    "statusUrl": "/apps/operations/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-10-25T09:00:00.000Z",
    "updatedAt": "2026-10-25T09:00:00.000Z"
  }
}

{
  "status": false,
  "code": "OPERATION_RECORD_UNAVAILABLE",
  "message": "İşlemi tekrar göndermeden durumunu kontrol edin.",
  "retryable": false,
  "reviewRequired": true,
  "operation": {
    "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "type": "epos.return",
    "state": "review_required",
    "reviewRequired": true,
    "retryable": false,
    "result": {
      "resultId": "600000000000000000000003",
      "paymentId": "600000000000000000000002"
    },
    "statusUrl": "/apps/operations/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-10-25T09:00:00.000Z",
    "updatedAt": "2026-10-25T09:00:00.000Z"
  }
}

Ne yapar?

Ödenmiş kaydın remainingMinor tutarının tamamını iptal/iade için gönderir. Kısmi tutar 422 BANKPOS_FULL_RETURN_REQUIRED üretir. Sağlayıcı sonucu voided veya refunded olarak doğrulanır; HTTP 200/operation.state=succeeded yalnız isteğin işlendiğini gösterir. Belirsiz sonuçta mevcut ödeme sorgulanır; yeni anahtarla tekrar mali işlem başlatılmaz. İptal/iade uygunluğu ve gün sonu koşulları sağlayıcıya bağlıdır.

Ön koşullar ve izin

Gereken izin: muhasip:epos:write. Açık izin her durumda zorunludur; genel erişim veya yönetici yetkisi bunun yerine geçmez. write tek başına read sağlamaz. Firma kimlik bilgilerinden belirlenir; ilişkili kayıtlar aynı firmaya ait olmalıdır. Firma paketi ücretli ve süresi aktif olmalıdır. Kimlik ve izinler · E-Pos entegrasyonu

İstek örnekleri

Örnekler temsilîdir. Kimlikleri, sürümleri ve işyeri bilgilerini kendi kayıtlarınızla değiştirin. Oranlar yüzde, amountMinor değerleri kuruştur. Gereken işlem anahtarını çağrıdan önce kalıcı saklayın; otomatik tekrar yapmayın. Gerçek işyeri anahtarını güvenli sunucu ortamından sağlayın. Node.js örneği Node.js 20 veya üzeri, PHP örneği cURL uzantısı gerektirir.

curl --request POST 'https://api.muhasip.pro/apps/bankpos/payments/600000000000000000000002/returns' \
  --user "$MUHASIP_API_USER_ID:$MUHASIP_API_SECRET" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $MUHASIP_IDEMPOTENCY_KEY" \
  --data-binary @- <<'JSON'
{
  "amountMinor": 10000
}
JSON

<?php
$apiUserId = getenv("MUHASIP_API_USER_ID");
$secret = getenv("MUHASIP_API_SECRET");
if (!$apiUserId || !$secret) {
    throw new RuntimeException("API kimlik bilgileri eksik.");
}
$headers = ["Accept: application/json"];
$key = getenv("MUHASIP_IDEMPOTENCY_KEY");
if (!$key) { throw new RuntimeException("İşlem anahtarı eksik."); }
$headers[] = "Idempotency-Key: " . $key;
$headers[] = "Content-Type: application/json";
$body = <<<'JSON'
{
  "amountMinor": 10000
}
JSON;
$curl = curl_init("https://api.muhasip.pro/apps/bankpos/payments/600000000000000000000002/returns");
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => $apiUserId . ":" . $secret,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_TIMEOUT => 100,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $body
]);
$response = curl_exec($curl);
$httpStatus = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ($response === false) {
    curl_close($curl);
    throw new RuntimeException("Sonuç belirsiz; yeniden göndermeden işlem ve ödeme durumunu okuyun.");
}
curl_close($curl);
$result = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
// Ödeme bağlantısını veya gizli alanları günlüklemeyin.
echo json_encode(["httpStatus" => $httpStatus, "status" => $result["status"] ?? null, "id" => $result["result"]["_id"] ?? null, "operationId" => $result["operation"]["operationId"] ?? null], JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);

async function main() {
  const apiUserId = process.env.MUHASIP_API_USER_ID
  const secret = process.env.MUHASIP_API_SECRET
  if (!apiUserId || !secret) throw new Error("API kimlik bilgileri eksik.")
  const headers = {
    Authorization: `Basic ${Buffer.from(`${apiUserId}:${secret}`, "utf8").toString("base64")}`,
    Accept: "application/json"
  }
  const key = process.env.MUHASIP_IDEMPOTENCY_KEY
  if (!key) throw new Error("İşlem anahtarı eksik.")
  headers["Idempotency-Key"] = key
  headers["Content-Type"] = "application/json"
  const body = {
    amountMinor: 10000
  }
  const response = await fetch("https://api.muhasip.pro/apps/bankpos/payments/600000000000000000000002/returns", {
    method: "POST",
    headers,
    redirect: "error",
    signal: AbortSignal.timeout(100000),
    body: JSON.stringify(body)
  })
  const result = await response.json()
  // Ödeme bağlantısını veya gizli alanları günlüklemeyin.
  console.log({
    httpStatus: response.status,
    status: result.status,
    id: result.result?._id,
    operationId: result.operation?.operationId
  })
}
main().catch(() => {
  console.error("Sonuç alınamadı; işlem/ödeme durumunu kontrol etmeden yeniden göndermeyin.")
  process.exitCode = 1
})

Cevabı değerlendirin

Aşağıdaki cevap temsilîdir; varsa url alanı örnekte yer tutucudur. Uygulamada dönen adresi doğrudan kullanın ve günlüklemeyin. operation.state=succeeded, ödeme veya iadenin mali olarak tamamlandığı anlamına gelmez. Ödeme kaydının status, verification ve iade geçmişini okuyun. Tamamlanmış tekrar cevabı ilk gövde yerine güvenli kimlikler döndürebilir.

{
  "status": true,
  "result": {
    "_id": "600000000000000000000002",
    "accountId": "600000000000000000000001",
    "reference": "600000000000000000000002",
    "status": "voided",
    "amountMinor": 10000,
    "amountEditable": true,
    "currency": "TRY",
    "pricingMode": "card",
    "saleRateMode": "family",
    "cardFamily": "paraf",
    "installmentOptions": [
      {
        "installment": 1,
        "saleRate": 0,
        "familySaleRates": []
      },
      {
        "installment": 3,
        "saleRate": 0,
        "familySaleRates": [
          {
            "family": "paraf",
            "saleRate": 0
          }
        ]
      }
    ],
    "expiresAt": "2026-10-25T09:30:00.000Z",
    "verification": "verified",
    "returnedMinor": 10000,
    "remainingMinor": 0,
    "activeReturnId": null,
    "returnOperations": [
      {
        "id": "600000000000000000000003",
        "amountMinor": 10000,
        "state": "verified",
        "kind": "void",
        "reason": null,
        "createdAt": "2026-10-25T09:00:00.000Z",
        "completedAt": "2026-10-25T09:00:00.000Z"
      }
    ],
    "reconciliation": {
      "checks": 0,
      "lastCheckedAt": null,
      "lastResult": null,
      "reason": null,
      "nextCheckAt": null
    },
    "startFailure": null,
    "url": "<yanıttan-alınan-ödeme-adresi>",
    "totalMinor": 10000,
    "saleCommissionMinor": 0,
    "purchaseCommissionMinor": 480,
    "netMinor": 9520,
    "installment": 3
  },
  "operation": {
    "operationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "type": "epos.return",
    "state": "succeeded",
    "reviewRequired": false,
    "retryable": false,
    "result": {
      "resultId": "600000000000000000000003",
      "paymentId": "600000000000000000000002"
    },
    "statusUrl": "/apps/operations/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-10-25T09:00:00.000Z",
    "updatedAt": "2026-10-25T09:00:00.000Z"
  }
}

Hata durumunda

HTTP / kod	Yapılacak işlem
`400 BANKPOS_INVALID_REQUEST`	İstek, kimlik, filtre veya oran biçimini düzeltin.
`401 UNAUTHORIZED`	API kimliği, erişim süresi ve firma durumunu kontrol edin.
`403 API_SCOPE_FORBIDDEN`	Açık E-Pos iznini, firma/IP ve paket koşullarını kontrol edin.
`429`	İstek sıklığını azaltın; mali çağrıyı körlemesine tekrarlamayın.
`500 INTERNAL_ERROR`	İstek tamamlanamadı; yazma sonucunu kayıttan kontrol edin.
`404 BANKPOS_PAYMENT_NOT_FOUND`	Aynı firmaya ait ödeme kimliğini kullanın; sorgu için başlatılmış deneme gerekir.
`409 BANKPOS_RETURN_NOT_READY`	Ödeme/iade durumunu ve devam eden talebi okuyun.
`409 BANKPOS_QUERY_IN_PROGRESS`	Mevcut işlem tamamlanmadan yeni mali işlem başlatmayın.
`422 BANKPOS_FULL_RETURN_REQUIRED`	Güncel remainingMinor tutarının tamamını gönderin.
`503 BANKPOS_BRIDGE_UNAVAILABLE`	Bağlantı şu anda kullanılamıyor; mali isteği otomatik tekrarlamayın.
`400 IDEMPOTENCY_KEY_REQUIRED`	Çağrıdan önce kalıcı işlem anahtarını hazırlayın.
`409 IDEMPOTENCY_PAYLOAD_CONFLICT`	Aynı anahtarı farklı istekle kullanmayın.
`409 OPERATION_IN_PROGRESS`	Mevcut işlem makbuzunu okuyun.
`409 OPERATION_TARGET_LOCKED`	Mevcut ödeme ve işlem makbuzunu kontrol edin.
`502 UPSTREAM_RESULT_UNCERTAIN`	Sonuç belirsiz; yeni anahtarla mali işlemi tekrar başlatmayın.
`503 OPERATION_RECORD_UNAVAILABLE`	Varsa operationId ve ödeme kimliğiyle sonucu araştırın.

Hata yönetimi · İşlem takibi

Sonraki adım

E-Pos entegrasyon akışını izleyin. Hesap değişikliğinde dönen revision değerini saklayın; ödemede bağlantı oluşturmayı, müşterinin 3D işlemini ve doğrulanmış mali sonucu ayrı değerlendirin.

Yetkilendirmeler

Authorization

string

header

gerekli

Kullanıcı adı apiUserId, parola secretKey. Aktif ve süresi geçmemiş API kullanıcısı ve uygun firma gerekir.

Başlıklar

Idempotency-Key

string

gerekli

İş niyetine ait kalıcı anahtar. Farklı işlerde yeniden kullanmayın. Aynı anahtar ve farklı içerik 409 döndürür.

Required string length: 1 - 128

Pattern: ^[!-~]+$

Yol Parametreleri

paymentId

string

gerekli

Aynı firmaya ait 24 haneli kayıt kimliği.

Pattern: ^[a-fA-F0-9]{24}$

Gövde

application/json

amountMinor

integer

gerekli

Güncel remainingMinor değerinin tamamına eşit olmalıdır; kısmi iade desteklenmez.

Gerekli aralık: 1 <= x <= 9007199254740991

Yanıt

İşlem cevabı; örnek temsilîdir.

Option 1
Option 2

status

enum<boolean>

gerekli

Mevcut seçenekler:

true

result

object

gerekli

Show child attributes

operation

object

gerekli

Show child attributes

Servis ve uygulamalar

Cari hesaplar

Kasa ve transferler

Alış-satış (e-belgesiz)

Ödemeler ve mahsuplaşma

Muhasebe seçenekleri

Fatura ve e-belge

Banka hesapları ve hareketleri

Banka otomasyonları

İş akışları ve alanlar

POS ve tahsilat

E-Pos

GİB e-Arşiv

Pazaryeri

Online işlemler

Proje ve görevler

Ajanda

Takvim

Mali işlem durumu

E-Pos ödemesini tamamen iptal veya iade et

Ne yapar?

Ön koşullar ve izin

İstek örnekleri

Cevabı değerlendirin

Hata durumunda

Sonraki adım

Yetkilendirmeler

Başlıklar

Yol Parametreleri

Gövde

Yanıt

​Ne yapar?

​Ön koşullar ve izin

​İstek örnekleri

​Cevabı değerlendirin

​Hata durumunda

​Sonraki adım

Yetkilendirmeler

Başlıklar

Yol Parametreleri

Gövde

Yanıt

Ne yapar?

Ön koşullar ve izin

İstek örnekleri

Cevabı değerlendirin

Hata durumunda

Sonraki adım