API referansı

Temel URL

Canlı ortam

https://cryptomerchant.online/api/v1https://cryptomerchant.online/api/v1

Yerel geliştirme

http://localhost:3000/api/v1http://localhost:3000/api/v1

Bu API'nin makine tarafından okunabilir açıklaması /openapi.json adresindedir (OpenAPI 3.1). Postman'e veya bir istemci oluşturucuya aktarabilirsiniz.

Kimlik doğrulama

Gizli anahtarınızı her isteğin Authorization başlığında Bearer token olarak gönderin. Anahtarları portalda Geliştiriciler altında oluşturun.

Authorization: Bearer cm_live_…

• Anahtarlar ana ağda cm_live_, test ağında cm_test_ ile başlar.
• Anahtarın tamamı yalnızca bir kez, oluşturduğunuzda gösterilir. Yalnızca hash değerini saklarız, bu yüzden anahtarı güvenli bir yerde saklayın.
• Anahtarları yalnızca sunucunuzda kullanın. Asla bir web sayfasına, mobil uygulamaya veya herkese açık bir kod deposuna koymayın.
• Bir anahtar sızmış olabilirse portalda iptal edin ve yeni bir tane oluşturun.

Hatalar

Bir istek başarısız olduğunda yanıt, bir HTTP hata durumuna ve makine tarafından okunabilen bir code ile insan tarafından okunabilen bir message içeren bir JSON gövdesine sahip olur:

{
  "error": {
    "code": "amount_too_small",
    "message": "Amount must be at least 0.50 USD."
  }
}

HTTP durumu

400

İstek geçerli değil; örneğin eksik bir alan veya çok küçük bir tutar.

401

API anahtarı eksik, yanlış veya iptal edilmiş.

403

Hesabınız bunu yapamaz: henüz canlı değil veya askıya alınmış.

404

Nesne mevcut değil veya başka bir işletmeye ait.

409

Fatura mevcut durumunda bu işlemi yapamaz; örneğin zaten ödemesi olan bir faturayı iptal etmek.

500

Bizim tarafımızda bir sorun oluştu. Biraz sonra tekrar deneyin.

Görebileceğiniz kodlar

invalid_json

İstek gövdesi bir JSON nesnesi değil.

invalid_request

Bir alan eksik veya geçerli değil. Mesaj, alanın adını belirtir.

unauthorized

API anahtarı eksik, yanlış veya iptal edilmiş.

account_suspended

Bu işletme hesabı askıya alınmış.

merchant_not_live

Hesabınız henüz canlı değil. Önce portalda kurulumu tamamlayın.

invalid_amount

Tutar eksik, sayı değil veya sıfırdan büyük değil.

amount_too_small

Tutarın değeri 0,50 ABD dolarından az.

invalid_asset

Coin kimliği bilinen bir coine ait değil.

asset_not_accepted

Bu coini kabul etmiyorsunuz.

invalid_state

Fatura mevcut durumunda bu işlemi yapamaz.

not_found

Bu kimliğe sahip bir nesne yok.

server_error

Bizim tarafımızda bir sorun oluştu.

Fatura nesnesi

Faturalar API yanıtlarında ve webhook'larda bu yapıdadır. Tutarlar ondalık dize (string) olarak verilir, böylece hassasiyet kaybolmaz.

idstring

inv_ ile başlayan fatura kimliği.

objectstring

Her zaman invoice.

statusstring

Mevcut durum. Aşağıdaki durum listesine bakın.

amountstring

currency cinsinden istediğiniz fiyat.

currencystring

Fiyatın para birimi, örneğin USD.

amount_usdstring

ABD doları cinsinden fiyat.

descriptionstring | null

Müşteriye gösterilen açıklamanız.

order_idstring | null

Kendi sipariş referansınız.

customer_emailstring | null

Verdiyseniz müşterinin e-postası.

metadataobject

Faturayı oluştururken gönderdiğiniz nesne; değiştirilmeden döndürülür.

coinobject | null

Müşterinin seçtiği coin veya gerçekte ödediği coin; id, symbol ve network bilgileriyle. Bir coin seçilene kadar null.

requested_coinobject | null

Genellikle null. Müşteri başka bir coinle veya başka bir ağda ödediyse ve ödeme sayıldıysa, faturanın istediği coindir; coin ile aynı alanlara sahiptir. Bkz. yanlış coin veya yanlış ağ.

pay_addressstring | null

Bu faturanın yatırma adresi. Bir coin seçilene kadar null.

pay_amountstring | null

Seçilen coin cinsinden gönderilecek tam tutar.

network_fee_amountstring

pay_amount tutarının bir parçası: müşterinin fiyata ek olarak ödediği gas ücreti, coin cinsinden. Yoksa 0.

network_fee_usdstring

ABD doları cinsinden aynı gas ücreti.

rate_usdstring | null

Seçilen coinin bir biriminin ABD doları cinsinden sabitlenmiş fiyatı.

received_amountstring

Seçilen coin cinsinden şu ana kadar ulaşan tutar.

received_usdstring

Ulaşan tutarın ABD doları cinsinden değeri.

overpaid_amountstring

Seçilen coin cinsinden, faturanın istediğinden ne kadar fazla ödendiği.

refunded_amountstring

Bu ödemede iade bağlantılarıyla ne kadar iade ettiğiniz, ödenen coin cinsinden. Hiç yoksa 0.

checkout_urlstring

Fatura sayfası. Ödeme yapması için müşterinizi buraya gönderin.

redirect_urlstring | null

Müşterinin ödeme yaptıktan sonra gidebileceği yer.

expires_atISO 8601

Ödeme görülmezse faturanın süresinin dolacağı zaman.

paid_atISO 8601 | null

Faturanın ödendiği zaman veya null.

created_atISO 8601

Faturanın oluşturulduğu zaman.

{
  "id": "inv_…",
  "object": "invoice",
  "status": "open",
  "amount": "49.9",
  "currency": "USD",
  "amount_usd": "49.9",
  "description": "Annual plan",
  "order_id": "1042",
  "customer_email": "[email protected]",
  "metadata": { "plan": "annual" },
  "coin": null,
  "requested_coin": null,
  "pay_address": null,
  "pay_amount": null,
  "network_fee_amount": "0",
  "network_fee_usd": "0",
  "rate_usd": null,
  "received_amount": "0",
  "received_usd": "0",
  "overpaid_amount": "0",
  "refunded_amount": "0",
  "checkout_url": "https://cryptomerchant.online/pay/i/inv_…",
  "redirect_url": "https://yourstore.example/thanks",
  "expires_at": "2026-10-28T10:00:00.000Z",
  "paid_at": null,
  "created_at": "2026-10-28T09:30:00.000Z"
}

Fatura durumları

openAçık

Oluşturuldu. Müşteri henüz bir coin seçmedi.

awaiting_paymentÖdeme bekleniyor

Bir coin seçildi, yatırma adresi atandı ve kur sabitlendi.

confirmingOnaylanıyor

Zincir üstünde bir ödeme görüldü ve onay bekliyor.

underpaidEksik ödeme

Onaylanan ödemedeki eksik, toleransınızdan fazla. Müşteri kalanını ödeyebilir veya iade isteyebilir.

paidÖdendi

Ödendi ve onaylandı. Ücret düşüldükten sonraki tutar bakiyenizde. Kısmi bir iade bu durumu korur.

expiredSüresi doldu

Herhangi bir ödeme görülmeden süre doldu.

cancelledİptal edildi

Fatura, herhangi bir ödeme görülmeden önce iptal edildi.

refundedİade edildi

Eksik ödenen bir faturada müşteriye gönderdiği tutar iade edildi veya ödenmiş bir faturadan size kalanın tamamını iade ettiniz.

Fatura oluşturma

POST/invoices

Bir fatura oluşturur ve fatura nesnesini 201 durumuyla döndürür. Müşterinizi faturanın checkout_url adresine gönderin.

Gövde parametreleri

amountZorunlunumber | string

Sayı veya ondalık dize olarak fiyat. Değeri en az 0,50 ABD doları olmalıdır.

currencyİsteğe bağlıstring

Fiyatın para birimi, örneğin USD. Varsayılan değer USD.

descriptionİsteğe bağlıstring

Müşterinin ne için ödeme yaptığı, en fazla 300 karakter. Fatura sayfasında gösterilir.

order_idİsteğe bağlıstring

Faturayı bir siparişle eşleştirmek için kendi sipariş referansınız, en fazla 120 karakter.

customer_emailİsteğe bağlıstring

Müşterinin e-posta adresi. Ödemeler portalda müşteriye göre gruplanır.

customer_nameİsteğe bağlıstring

Müşterinin adı, en fazla 120 karakter.

redirect_urlİsteğe bağlıstring

Müşterinin ödeme yaptıktan sonra gidebileceği tam bir URL.

metadataİsteğe bağlıobject

En fazla 4 KB boyutunda herhangi bir JSON nesnesi. Faturada ve webhook'larda değiştirilmeden döndürülür.

coinİsteğe bağlıstring

Bir coini kimliğiyle önceden seçin, örneğin USDT.TRON. Kabul ettiğiniz coinlerden biri olmalıdır.

Önceden seçilmiş bir coin ile yatırma adresi hemen atanır ve kur hemen sabitlenir; böylece pay_address ve pay_amount doldurulur ve ödeme ayrıntılarını kendi arayüzünüzde gösterebilirsiniz.

curl https://cryptomerchant.online/api/v1/invoices \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.90",
    "currency": "USD",
    "order_id": "1042",
    "description": "Annual plan",
    "customer_email": "[email protected]",
    "redirect_url": "https://yourstore.example/thanks",
    "metadata": { "plan": "annual" }
  }'

const res = await fetch("https://cryptomerchant.online/api/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CM_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "49.90",
    currency: "USD",
    order_id: "1042",
    description: "Annual plan",
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const invoice = await res.json();
// Send the customer to invoice.checkout_url

Faturaları listeleme

GET/invoices

Faturalarınızı en yeniden başlayarak, her seferinde bir sayfa olacak şekilde döndürür.

Sorgu parametreleri

statusİsteğe bağlıstring

Yalnızca bu durumdaki faturalar, örneğin paid. Yukarıdaki durumlardan biri olmalıdır.

limitİsteğe bağlınumber

Döndürülecek fatura sayısı, 1 ile 100 arasında. Varsayılan değer 20.

starting_afterİsteğe bağlıstring

Bir fatura kimliği. Sonraki sayfa için bu faturadan sonra gelen faturaları döndürür.

Faturalar data içindedir. has_more değeri true olduğunda, starting_after değerini aldığınız son faturanın kimliğine ayarlayarak sonraki sayfayı isteyin.

curl "https://cryptomerchant.online/api/v1/invoices?status=paid&limit=20" \
  -H "Authorization: Bearer $CM_SECRET_KEY"

{
  "object": "list",
  "data": [
    { "id": "inv_…", "object": "invoice", "status": "paid", … }
  ],
  "has_more": true
}

Fatura getirme

GET/invoices/{id}

Kimliğine göre tek bir fatura döndürür.

curl https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Fatura iptal etme

POST/invoices/{id}/cancel

Bir faturayı iptal eder. Bu yalnızca fatura ödenmemişken ve fatura için herhangi bir ödeme görülmemişken çalışır.

curl -X POST https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID/cancel \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Bakiyeler

GET/balances

İşletmenizin her coinde tuttuğu miktarı, ABD doları cinsinden toplamı ve gas bakiyenizi döndürür.

data[].coin

Coin kimliği, örneğin USDT.TRON.

data[].symbol

Coin sembolü, örneğin USDT.

data[].network

Coinin bulunduğu ağ.

data[].amount

Tuttuğunuz coin miktarı, ondalık dize olarak.

data[].usd

Güncel fiyatla ABD doları cinsinden değeri.

total_usd

Tüm coinlerinizin ABD doları cinsinden değeri.

gas_balance_usd

Gas ücretlerini ödemek için kullanılan, ABD doları cinsinden gas bakiyeniz.

curl https://cryptomerchant.online/api/v1/balances \
  -H "Authorization: Bearer $CM_SECRET_KEY"

{
  "object": "balance",
  "data": [
    { "coin": "USDT.TRON", "symbol": "USDT", "network": "Tron", "amount": "…", "usd": "…" }
  ],
  "total_usd": "…",
  "gas_balance_usd": "…"
}

Kabul edilen coinler

GET/coins

Şu anda kabul ettiğiniz coinleri; her birinin id, symbol, name, network ve decimals bilgileriyle döndürür. Fatura oluştururken id değerini coin olarak kullanın. Örneğin:

curl https://cryptomerchant.online/api/v1/coins \
  -H "Authorization: Bearer $CM_SECRET_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "ETH.ETH",
      "symbol": "ETH",
      "name": "Ethereum",
      "network": "Ethereum",
      "decimals": 18
    },
    {
      "id": "USDT.ETH",
      "symbol": "USDT",
      "name": "Tether USD",
      "network": "Ethereum",
      "decimals": 6
    },
    {
      "id": "USDC.ETH",
      "symbol": "USDC",
      "name": "USD Coin",
      "network": "Ethereum",
      "decimals": 6
    }
  ]
}

Ödeme bağlantısı oluşturma

POST/payment-links

Bir ödeme bağlantısı oluşturur ve bağlantıyı id ve paylaşılabilir url değerleriyle birlikte 201 durumuyla döndürür.

Gövde parametreleri

titleZorunlustring

Müşterinin ödeme yaptığı şeyin adı, en fazla 120 karakter.

amountİsteğe bağlınumber | string

Sabit bir fiyat. Tutarı müşterinin girmesi için bu alanı göndermeyin.

currencyİsteğe bağlıstring

Fiyatın para birimi. Varsayılan değer USD.

descriptionİsteğe bağlıstring

Müşteriye gösterilen ek ayrıntı, en fazla 300 karakter.

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Consulting hour",
    "amount": "80",
    "currency": "USD"
  }'

{
  "id": "…",
  "object": "payment_link",
  "title": "Consulting hour",
  "description": null,
  "amount": "80",
  "currency": "USD",
  "active": true,
  "url": "https://cryptomerchant.online/pay/l/…",
  "created_at": "2026-10-28T09:30:00.000Z"
}

Ödeme bağlantılarını listeleme

GET/payment-links

En son 100 ödeme bağlantınızı, en yeniden başlayarak data içinde döndürür.

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Ödeme gönderimi nesnesi

Ödeme gönderimi webhook'ları (payout.sent ve payout.failed) bu nesneyi data içinde taşır. Gelir paylaşımından iş ortağı payının ödeme gönderimleri de aynı nesneyi kullanır ve partner_share değeri true olur.

idstring

Ödeme gönderimi kimliği.

objectstring

Her zaman payout.

coinstring

Coin kimliği, örneğin USDT.TRON.

amountstring

Gönderilen tutar, o coin cinsinden.

network_feestring

Gönderimin gas ücreti, o coin cinsinden.

to_addressstring

Gönderildiği cüzdan adresi.

statusstring

queued, running, done veya failed.

tx_hashstring | null

Gönderildikten sonra blokzincirdeki işlem kimliği.

autoboolean

Ödeme gönderimi bir kişi tarafından talep edilmeden otomatik olarak yapıldıysa true.

partner_shareboolean

Bu ödeme gönderimi, iş ortağının cüzdanına gönderilen bir gelir paylaşımı iş ortağı payıysa true.

created_atISO 8601

Ödeme gönderiminin oluşturulduğu zaman.

{
  "id": "…",
  "object": "payout",
  "coin": "USDT.TRON",
  "amount": "120",
  "network_fee": "…",
  "to_address": "T…",
  "status": "done",
  "tx_hash": "…",
  "auto": true,
  "partner_share": true,
  "created_at": "2026-10-28T09:30:00.000Z"
}