ডেভেলপার ডকুমেন্টেশন

API ডকুমেন্টেশন

ইনভয়েস, চেকআউট আর পেমেন্ট নোটিফিকেশন যুক্ত করো।

দ্রুত শুরু

তোমার প্রথম ইনভয়েস তৈরি করো।

  1. একটি স্টোর প্রস্তুত করো

    পেমেন্ট পদ্ধতি চালু করো, provider কনফিগার করো আর প্রকল্পের ওয়ালেট ব্যাকআপ করো।

  2. একটি API ক্রেডেনশিয়াল তৈরি করো

    কনসোলের সেটিংস → API access-এ read/write বেছে নিয়ে প্রকল্প যুক্ত করো।

  3. অনুরোধ পাঠাও

    তোমার API host ব্যবহার করো আর project আর store ID কপি করো। দশমিক পরিমাণ string হিসেবে পাঠাও।

  4. চেকআউট খোলো

    Redirect করো এখানে links.checkout যা response-এ আছে। অর্ডার পূরণ করার আগে সেটেলমেন্ট যাচাই করো।

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new invoice.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: order-1042-attempt-1' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "amount": "49.90",
  "currency": "USD",
  "order_id": "order-1042",
  "exchange_rate_spread_percent": "0.5"
}'

উদাহরণে placeholder আছে; এই পৃষ্ঠা থেকে অনুরোধ পাঠায় না। ইনভয়েসের সব field আর response format দেখো →

Project ও store ID

YOUR_PROJECT_ID আর YOUR_STORE_ID কোথায় পাবে।

কনসোল থেকে পাওয়া UUID ব্যবহার করো, project/store-এর নাম বা পড়তে সুবিধাজনক identifier নয়।

Placeholderকোথায় পাবেকী কাজে লাগে
YOUR_PROJECT_IDপ্রকল্প → সেটিংস → API IDs → Project API ID → কপি। স্টোরের Basic tab-এও দেখা যায়।প্রকল্প আর স্টোরভিত্তিক অনুরোধ।
YOUR_STORE_IDপ্রকল্প → স্টোর → স্টোর বেছে নাও → Basic → API IDs → Store API ID → কপি।ইনভয়েস তৈরি আর স্টোরের payment-method অনুরোধ।
  • ডিফল্ট স্টোরের জন্যও ইনভয়েস তৈরিতে দুটো ID লাগে। স্টোরটি সেই প্রকল্পের হতে হবে এবং API ক্রেডেনশিয়ালের প্রকল্পে প্রবেশাধিকার থাকতে হবে।
  • ইনভয়েস তৈরি, তালিকা, বিস্তারিত আর চেকআউটে invoice_id ফেরত আসে: IPN/webhook-এ পাঠানো একই UUID। ইনভয়েসের path-এ এটি ব্যবহার করো, internal id বা order_id নয়। Merchant 4.0.0 থেকে পুরোনো public_id response field সরানো হয়েছে; আপগ্রেডের আগে integration বদলে নাও।
  • REST API-তে project/store তালিকার route নেই। কনসোল থেকে ID কপি করো, অথবা merchant 5.0.0+-এর সীমিত scope-এর list_projects আর list_stores MCP tool ব্যবহার করো।
  • Store → Basic → Store domains-এ সক্রিয় merchant, pay আর API hostname বেছে নেওয়া হয়। ফেরত আসা checkout link আর নতুন callback link আগে সেই স্টোর, তারপর default store, তারপর system default অনুসরণ করে। বন্ধ বা সক্রিয় না হওয়া নাম কখনো বেছে নেওয়া হয় না। পছন্দের API hostname দিয়ে SDK কনফিগার করো; পছন্দ বদলালে অন্য সক্রিয় alias redirect হয় না।

Authentication ও scope

ক্রেডেনশিয়াল সার্ভারে রাখো এবং শুধু প্রয়োজনীয় অনুমতি দাও।

ডিফল্ট hostকাজ
merchant.example.comমার্চেন্ট কনসোল আর সেটিংস
pay.example.comগ্রাহকের চেকআউট
api.example.comমার্চেন্ট API অনুরোধ

বদলে দাও example.com তোমার domain দিয়ে। আগের ইনস্টলেশনের কনফিগার করা নাম থাকে; Settings → System-এ alias পরিচালনা করো।

Authorization: Bearer YOUR_MERCHANT_API_TOKEN
সেটিংযেভাবে কাজ করে
প্রবেশাধিকারের স্তরRead-only ক্রেডেনশিয়াল তালিকা আর তথ্য পড়তে পারে। Read/write ক্রেডেনশিয়াল ইনভয়েস তৈরি আর ডকুমেন্ট করা অ্যাসেট নীতিও বদলাতে পারে।
প্রকল্পক্রেডেনশিয়াল কোন প্রকল্পে ঢুকতে পারবে সেট করো। store আর invoice ID নির্ধারিত প্রকল্পের হতে হবে।
IP সীমাবদ্ধতাচাইলে Settings → API access-এ নির্দিষ্ট public IPv4 বা IPv6 outgoing address অনুমোদন করো।
ক্রেডেনশিয়াল সংরক্ষণtoken backend configuration-এ রাখো। browser বা checkout link-এ bearer credential কখনো রেখো না।

পাবলিক checkout route ইনভয়েসের public ID ব্যবহার করে এবং চেকআউটে দেখানোর নিরাপদ ডেটাই প্রকাশ করে। console session আর প্রশাসনিক নিয়ন্ত্রণ merchant API ক্রেডেনশিয়াল থেকে আলাদা।

অ্যাসেট ও ওয়ালেট

প্রতিটি স্টোরের পেমেন্ট পদ্ধতি আলাদাভাবে বেছে নাও।

  1. পড়ো প্রকল্পের পেমেন্ট অ্যাসেট আর তাদের প্রস্তুতির অবস্থা।
  2. নেটিভ চেইন চালু করে তার ওয়ালেট আর provider কনফিগার করো।
  3. দেখো সম্ভাব্য টোকেন এবং contract বা mint যাচাই করো টোকেন চালু করার আগে।
  4. স্টোরের ক্রম অনুযায়ী বেছে নাও পেমেন্ট পদ্ধতি। নতুন ইনভয়েসে প্রস্তুত পদ্ধতিগুলো ব্যবহার হয়।

টোকেনগুলো তাদের নেটিভ চেইনের ওয়ালেটই ব্যবহার করে। ওয়ালেট ব্যালান্স সঠিক atomic amount আর ধারণামূলক fiat value ফেরত দেয়। কোন পদ্ধতি পেমেন্ট নিতে পারে তা জানতে ফেরত আসা readiness field ব্যবহার করো।

যাচাই করা ERC-20 টোকেন সমর্থিত EVM নেটওয়ার্ক ব্যবহার করে; যাচাই করা SPL টোকেন Solana ব্যবহার করে। ৩০টি যুক্ত নেটওয়ার্কে native payment method আছে। Monero প্রকল্পে যুক্ত বাহ্যিক view-only wallet connection ব্যবহার করে।

অর্থ গ্রহণের API আর native/token coverage
পেমেন্ট পথসমর্থনপ্রমাণপ্রয়োজনীয়তা
নেটিভ পেমেন্ট পথসমর্থিতলেনদেন স্ক্যান করে যাচাইBTC, SOL, ETH (Ethereum/Base/Arbitrum/OP), BNB, HYPE, AVAX আর POL; Bitcoin output, canonical EVM transaction/receipt আর বিশ্লেষিত Solana transfer ইনভয়েসের প্রমাণ দেয়।
ERC-20 টোকেন পেমেন্ট পথসমর্থিতলেনদেন স্ক্যান করে যাচাইEthereum, Base, BNB Chain, HyperEVM, Avalanche, Polygon, Arbitrum আর Optimism-এ on-chain verification লাগে; indexed Transfer log দিয়ে পেমেন্টের পরিচয় নির্ধারণ হয়।
SPL টোকেন পেমেন্ট পথসমর্থিতলেনদেন স্ক্যান করে যাচাইSolana-র সম্ভাব্য টোকেনে mainnet আর mint verification লাগে; বিশ্লেষিত লেনদেনে টোকেন ব্যালান্সের সঠিক পরিবর্তন দিয়ে পেমেন্টের পরিচয় নির্ধারণ হয়।
অতিরিক্ত UTXO নেটিভ পেমেন্ট পথসমর্থিতলেনদেন স্ক্যান করে যাচাইBCH/LTC/DOGE Esplora ব্যবহার করে; BCH/DOGE Bitcore-ও নেয়, LTC/DOGE/DASH BlockCypher নেয়, Dash Insight নেয় এবং transparent ZEC zcash-explorer নেয়। সবগুলো সংরক্ষিত সম্পূর্ণ Core-compatible node-rpc block-ও গ্রহণ করে। Raw mode-এ 1–48 confirmation লাগে, mempool detection নয়। Shielded Zcash সমর্থিত নয়।
Indexed account নেটিভ পেমেন্ট পথসমর্থিতলেনদেন স্ক্যান করে যাচাইTRON tron-indexer বা solidified node-rpc ব্যবহার করে; XRP xrpl-jsonrpc; Stellar stellar-horizon বা সংরক্ষিত Stellar node-rpc ledger; Cosmos Hub cometbft-jsonrpc; Algorand algorand-indexer বা algod node-rpc ব্যবহার করে; Hedera-তে hedera-mirror লাগে, EVM relay নয়।
নেটিভ ledger পেমেন্ট পথসমর্থিতলেনদেন স্ক্যান করে যাচাইAptos aptos-rest, Sui sui-graphql, NEAR near-jsonrpc আর Kaspa kaspa-rest ব্যবহার করে। Polkadot Asset Hub substrate-rest বা metadata-aware finalized node-rpc নেয়; Tezos tezos-tzkt বা পূর্ণ Octez node-rpc operation নেয়। শুধু native receipt; পুরোনো ইনভয়েসের জন্য archive সংরক্ষণ দরকার।
Cardano আর TON-এর নেটিভ পেমেন্ট পথসমর্থিতলেনদেন স্ক্যান করে যাচাইCardano-তে cardano-koios আর TON-এ toncenter-v3 লাগে। XRP tag, Stellar memo ID আর TON invoice comment destination_tag হিসেবে ফেরত আসে এবং হুবহু পাঠাতে হবে।
সেটেলমেন্টের অখণ্ডতাসমর্থিতস্বাধীন যাচাইডিফল্টে চূড়ান্ত সেটেলমেন্টের জন্য দুটি স্বাধীন provider-কে সঠিক transaction/event, amount, canonical block বা slot আর finality-তে একমত হতে হয়। Raw আর shared EVM window-তে সম্পূর্ণ coverage-ও যাচাই হয়। administrator চাইলে স্পষ্টভাবে একটি চেইনে একটি বিশ্বস্ত provider বেছে নিতে পারে; এতে স্বাধীন cross-check সরে, identity, completeness বা finality check নয়।
Monero নেটিভ পেমেন্ট পথসমর্থিতপ্রকল্পে যুক্ত view-only wallet RPCHTTPS method-allowlisting gateway-এর পেছনে আলাদা বাহ্যিক watch-only wallet-RPC account-0 subaddress তৈরি করে। কনফিগার করা mainnet daemon threshold (ডিফল্ট ২টি স্বাধীন উৎস, চাইলে ১টি) সেটেলমেন্টের প্রমাণ দেয়। Native --restricted-rpc create_address-এর সঙ্গে সামঞ্জস্যপূর্ণ নয়; wallet backup আর spend key না থাকার বিষয় operator স্পষ্টভাবে নিশ্চিত করে, আর কোনো key material Wholly Crypto-তে পাঠানো হয় না।

এক্সচেঞ্জের ব্যালান্স আর প্রতি অ্যাসেটে ওয়ালেট বা এক্সচেঞ্জে sweep-এর পছন্দ কনসোলে আছে, public v1 API-তে নয়। এক্সচেঞ্জ সেটআপ দেখো.

ইনভয়েসের জীবনচক্র

পেমেন্টের প্রমাণ, সেটেলমেন্ট আর অর্ডার পূরণ।

অবস্থাঅর্থ
newপেমেন্টের অপেক্ষায়
processingপেমেন্ট দেখা গেছে; গ্রহণযোগ্য পরিমাণ বা finality বাকি
settledইনভয়েসের settlement policy অনুযায়ী, বা ম্যানুয়ালি গ্রহণ করা হয়েছে
expiredসময়সীমা পেরিয়েছে; দেরির পেমেন্ট পর্যবেক্ষণ চলতে পারে
invalidপেমেন্ট স্বয়ংক্রিয়ভাবে গ্রহণ করা যাচ্ছে না
cancelledবাতিল; শুধু নির্দিষ্ট reconciliation action দিয়ে আবার খোলা যায়

amount_status রেকর্ড করে none, partial, paid অথবা overpaid. timing_status সময়মতো আর দেরির পেমেন্ট আলাদা করে। স্টোরের নিয়মে প্রয়োজনীয় confirmation আর underpayment tolerance নির্ধারিত হয়।

ইনভয়েসের এটি ব্যবহার করো invoice_id এর সঙ্গে ইনভয়েসের বিস্তারিত route। শুধু checkout redirect সেটেলমেন্টের প্রমাণ নয়। ব্যতিক্রমগুলো দেখো এর মাধ্যমে হিসাব মেলানো.

নিরাপদে আবার চেষ্টা

ইনভয়েস তৈরিতে লাগে Idempotency-Key। timeout হলে একই ক্রেডেনশিয়াল, key আর হুবহু request body দিয়ে আবার চেষ্টা করো। শুধু নতুন ইনভয়েসের জন্য নতুন key ব্যবহার করো।

EVM পেমেন্ট স্ক্যানিং

Shared native-block আর ERC-20 discovery সাম্প্রতিক ইনভয়েসকে পুরোনো catch-up কাজ থেকে আলাদা করে। প্রতিটি ইনভয়েসের স্থায়ী history cursor থাকে। Token query প্রতি অনুরোধে সর্বোচ্চ ১০০টি block ব্যবহার করে এবং provider-এর কঠোর সীমায় ছোট হয়। ডিফল্টে দুটি স্বাধীন provider প্রতিটি window যাচাই করে। Settings → Chain connections → Details-এ স্বাধীন cross-check ছাড়া একটি বিশ্বস্ত উৎস বেছে নেওয়া যায়; canonical transaction, amount আর confirmation check থাকে। Connection details-এ scanner delay, history restriction আর quota cooldown-কে সাধারণ node health থেকে আলাদা দেখায়। Public RPC capacity নিশ্চিত নয়।

IPN ও ওয়েবহুক

পেমেন্ট event গ্রহণ ও যাচাই করো।

IPN ইনভয়েসের কার্যকর ipn_url-এ তৈরি হওয়া প্রতিটি invoice event পায়। Webhook শুধু প্রতিটি চালু store endpoint-এর বাছাই করা event পায়। দুটোই একই JSON snapshot POST করে; তারা স্বাধীন, তাই দুটো চালু করলে তোমার application দুবার notification পেতে পারে।

সেট করো ipn_url ইনভয়েস তৈরির সময়, অথবা স্টোরের default নাও। IPN ব্যবহার করে স্টোর → IPN secret; প্রতিটি স্টোর → ওয়েবহুক endpoint-এর নিজের secret থাকে। কোনোটিই তোমার API key নয়।

কখন অর্ডার পূরণ করব?

Event-ভিত্তিক কাজের জন্য event_type = invoice.settled আর status = settled একসঙ্গে দেখে order check শুরু করো। বর্তমান ইনভয়েস যাচাই করো এবং প্রতিটি অর্ডার একবারই পূরণ করো।

status হলো event তৈরির সময়ের ইনভয়েসের অবস্থা। event_type জানায় কী ঘটেছে। payment.received-এ processing বা settled থাকতে পারে; এর মানে দ্বিতীয় পেমেন্ট নয় এবং এটি আলাদা order fulfilment signal নয়।

কোন event আর status পাঠানো হয়?

সেটিংস/ইতিহাসে eventBody-র statusঅর্থ
invoice.creatednewইনভয়েস তৈরি হয়েছে এবং পেমেন্টের অপেক্ষায়। নিয়ন্ত্রিত reopen-এ ইনভয়েস আবার new হলে এটিও ব্যবহার হয়।
payment.receivedResulting invoice statusপেমেন্ট রেকর্ড হয়েছে বা পাওয়া পরিমাণ বেড়েছে। সাধারণত processing বা settled; শুধু এই event সেটেলমেন্টের প্রমাণ নয়।
invoice.processingprocessingপেমেন্ট শনাক্ত হয়েছে, কিন্তু গ্রহণযোগ্য পরিমাণ বা প্রয়োজনীয় finality এখনো হয়নি। আংশিক পেমেন্টও এর মধ্যে আছে।
invoice.settledsettledSettlement policy পূরণ হয়েছে, অথবা ম্যানুয়ালি গ্রহণ করা হয়েছে। অর্ডার পূরণের আগে resolution আর অর্ডার দেখো।
invoice.expiredexpiredপেমেন্টের সময়সীমা পেরিয়েছে। পর্যবেক্ষণ চলার সময় দেরির পেমেন্টে status বদলাতে পারে।
invoice.invalidinvalidস্বয়ংক্রিয়ভাবে গ্রহণ করা যাচ্ছে না, পেমেন্টের প্রমাণ হারিয়েছে, বা মার্চেন্ট প্রত্যাখ্যান করেছে। ইনভয়েস পর্যালোচনা করো।
invoice.cancelledcancelledইনভয়েস বাতিল হয়েছে। অর্ডার পূরণ কোরো না; বাতিল করলে on-chain পেমেন্ট refund হয় না।
Ethereum আর Solana কেন আলাদা event flow পাঠাতে পারে

Confirmation পরে আসে (Ethereum উদাহরণ)

ক্রমevent_typestatus
1invoice.creatednew
2payment.receivedprocessing
2invoice.processingprocessing
3invoice.settledsettled

শনাক্ত হওয়ার সময়ই final (Solana উদাহরণ)

ক্রমevent_typestatus
1invoice.creatednew
2payment.receivedsettled
2invoice.settledsettled

এগুলো event তৈরির ক্রম দেখায়, delivery-এর নিশ্চিত ক্রম নয়। শনাক্ত হওয়ার সময় আর settlement policy অনুযায়ী অন্য চেইনেও যেকোনো flow হতে পারে। settled-এর আগে processing event আসতেই হবে এমন শর্ত রেখো না।

একবারই অর্ডার পূরণ: receiver উদাহরণ আর ডুপ্লিকেট প্রতিরোধ
পদ্ধতিকীভাবে সামলাবে
Event-ভিত্তিক receiverস্বাক্ষরিত event_id দিয়ে আলাদা event রাখো, তারপর status = settled-সহ invoice.settled বেছে নাও। একই sequence-এর payment.received আগে এসেছে বলে এই event বাদ দিয়ো না।
SDK-এর order-state inboxদেওয়া PHP, Python আর Node receiver উদাহরণ project + invoice_id + sequence একত্র করে। event_type যাই হোক সেভ করা state প্রক্রিয়া করো, বর্তমান ইনভয়েস পড়ো এবং settled হলে একবারই অর্ডার পূরণ করো। এই একত্র করার পরে শুধু invoice.settled-এর filter যোগ কোরো না।

Retry-তে event_id আর মূল body একই থাকে। ভিন্ন event-এর sequence এক হতে পারে, কিন্তু event_id আলাদা হয়। Event-ভিত্তিক কাজে স্বাক্ষরিত event_id দিয়ে duplicate delivery বাদ দাও; আলাদাভাবে configured installation/project + invoice_id আর তোমার order দিয়ে একবারই fulfilment নিশ্চিত করো। পরে আবার settlement হলে order-এ দুবার credit দিয়ো না।

HTTP receiver:
  Verify raw-body signature, timestamp and configured project/store scope.
  Save to a durable inbox; deduplicate the signed event_id.
  Return HTTP 2xx only after persistence succeeds.

Event-based background worker:
  Other events go to status/reconciliation handling, not fulfilment.
  Continue here only for event_type = invoice.settled and status = settled.
  Fetch the current invoice from your configured API origin.
  Check settled status, project/store, order, amount, currency and review policy.
  In one database transaction:
    Lock the order and check the scoped invoice has not been fulfilled.
    Credit/complete once and save the fulfilment record.
    Queue any external fulfilment with the same business idempotency key.

SDK order-state worker:
  Use the same current-invoice checks and fulfil-once transaction.
  Do not filter event_type after collapsing events by invoice revision.

এটি pseudocode, সরাসরি ব্যবহারযোগ্য receiver নয়।

ইনভয়েসের সব state আর পেমেন্টের ব্যতিক্রম
Fieldমানঅর্থ
statusnew, processing, settled, expired, invalid, cancelledEvent তৈরির সময়ের ইনভয়েস state; delivery-এর সময়কার বর্তমান state নাও হতে পারে।
amount_statusnone, partial, paid, overpaidগ্রহণযোগ্য tolerance-সহ পাওয়া পরিমাণ। paid মানে confirmation finality নয়।
timing_statuson_time, lateপেমেন্ট ইনভয়েসের সময়সীমার মধ্যে এসেছে কি না।
resolutionautomatic, manually_settled, manually_invalidatedসাধারণ নিয়ম, নাকি ম্যানুয়াল গ্রহণ/প্রত্যাখ্যান ফল নির্ধারণ করেছে।
requires_reviewfalse, trueব্যতিক্রমের ইঙ্গিত; আরেকটি invoice status বা স্বয়ংক্রিয় fulfil/refund-এর অনুমতি নয়।
পরিস্থিতিকরণীয়
কম পেমেন্ট / toleranceস্বয়ংক্রিয় নিয়মে partial সেটেল হয় না। paid-এ গ্রহণযোগ্য কম পরিমাণ থাকতে পারে, কিন্তু finality তবুও লাগে। শুধু পরিমাণ তুলনা নয়, invoice status ব্যবহার করো।
বেশি পেমেন্টoverpaid-এর সঙ্গে settled আর requires_review = true থাকতে পারে। অতিরিক্ত পেমেন্টের নীতি প্রয়োগ করো; order-এ দুবার credit বা যাচাই না করা ঠিকানায় স্বয়ংক্রিয় refund কখনো কোরো না।
দেরির পেমেন্টপর্যবেক্ষণ চললে expired পরে বদলাতে পারে। timing_status = late পর্যালোচনার সংকেত; বাতিল order নিজে থেকে আবার খুলো না বা পাঠিয়ো না।
ম্যানুয়াল গ্রহণউপযুক্ত on-chain অর্থ ছাড়াও invoice.settled-এ resolution = manually_settled থাকতে পারে। তোমার integration এই override নেবে কি না ঠিক করো; payment summary field null হতে পারে।
Reorg / অবৈধ হওয়ানতুন revision আগের পেমেন্ট প্রমাণকে অবৈধ করতে পারে। বর্তমান state আবার পড়ে reconciliation দিয়ে reversal সামলাও। অর্ডার একবার settled ছিল বলে এটি উপেক্ষা কোরো না।
শূন্য confirmation / শূন্য পরিমাণZero-confirmation settlement শনাক্ত হওয়ার সময়ই হতে পারে এবং reorg-এর ঝুঁকি থাকে। স্পষ্টভাবে অনুমোদিত zero-amount invoice পেমেন্ট ছাড়াই সেটেল হয়। কোনোটির আগে payment.received event থাকা বাধ্যতামূলক নয়।

অর্ডার পূরণে status = settled ব্যবহার করো, amount_status = paid বা checkout redirect নয়। প্রয়োজনীয় confirmation শূন্য হলে শনাক্ত হওয়াতেই settlement হতে পারে; এতে reorg-এর ঝুঁকি থাকে।

কম পেমেন্ট হলো amount_status = partial; বেশি পেমেন্ট হলো overpaid। paid মানে invoice-এর underpayment tolerance-সহ গ্রহণযোগ্য ন্যূনতম পরিমাণ এসেছে। এগুলো পরিমাণের state, invoice status নয়। late একটি timing_status, আলাদা event নয়।

সাধারণ flow হলো new → processing → settled, কিন্তু মাঝের state বাদ যেতে পারে। স্পষ্টভাবে অনুমোদিত zero-amount invoice পেমেন্ট ছাড়াই সেটেল হয় এবং amount_status = none থাকে। ম্যানুয়াল গ্রহণ manually_settled দিয়ে চিহ্নিত হয়।

Callback অপরিবর্তনীয় snapshot, live status response নয়। এগুলো দেরিতে, ক্রমের বাইরে বা একাধিকবার আসতে পারে। Payment আর status event-এর invoice sequence আর invoice-state field এক হতে পারে, কিন্তু স্বাক্ষরিত event_id আর event_type আলাদা। Confirmation count-এর জন্য প্রতি block-এ callback নিশ্চিত নয়।

যা পাবে

{
  "invoice_id": "11111111-2222-4333-8444-555555555555",
  "status": "settled",
  "amount_status": "paid",
  "timing_status": "on_time",
  "resolution": "automatic",
  "sequence": 3,
  "amount": "49.9",
  "currency": "EUR",
  "order_id": "order-1042",
  "payload_version": 2,
  "event_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "event_type": "invoice.settled",
  "occurred_at": "2026-09-14T12:05:00Z",
  "project_id": "11111111-1111-4111-8111-111111111111",
  "store_id": "22222222-2222-4222-8222-222222222222",
  "description": "Annual plan",
  "email": "ada@example.test",
  "customer": {
    "firstname": "Ada",
    "lastname": "Lovelace",
    "countryiso2": "GB"
  },
  "metadata": {
    "firstname": "Ada",
    "lastname": "Lovelace",
    "countryiso2": "GB",
    "cart_id": "cart-681"
  },
  "created_at": "2026-09-14T12:00:00Z",
  "updated_at": "2026-09-14T12:05:00Z",
  "expires_at": "2026-09-14T12:15:00Z",
  "monitoring_expires_at": "2026-09-21T12:15:00Z",
  "settled_at": "2026-09-14T12:05:00Z",
  "paid_chain": "ethereum",
  "paid_asset": "USDC",
  "paid_asset_amount": "58.17342",
  "paid_asset_amount_received": "58.17342",
  "paid_payment_method_id": "33333333-3333-4333-8333-333333333333",
  "settlement_exchange_rate": {
    "rate": "1.17",
    "units": "asset_per_invoice_currency",
    "currency": "EUR",
    "symbol": "USDC",
    "observed_at": "2026-09-14T12:05:00Z",
    "as_of": "2026-09-14T12:04:30Z",
    "pricing_provider": "kraken",
    "asset_provider": "kraken",
    "pricing_fetched_at": "2026-09-14T12:04:30Z",
    "asset_fetched_at": "2026-09-14T12:04:30Z",
    "stale": false,
    "is_fixed": false,
    "reference_currency": "USD",
    "uses_reference_proxy": false
  },
  "cancelled_at": null,
  "exchange_rate_spread_percent": "0.5",
  "underpayment_tolerance_percent": "1",
  "reason_code": "payment_confirmed",
  "requires_review": false,
  "links": {
    "checkout": "https://pay.example.com/invoice/11111111-2222-4333-8444-555555555555",
    "invoice": "https://api.example.com/v1/projects/11111111-1111-4111-8111-111111111111/invoices/11111111-2222-4333-8444-555555555555",
    "payments": "https://api.example.com/v1/projects/11111111-1111-4111-8111-111111111111/invoices/11111111-2222-4333-8444-555555555555/payments"
  },
  "payment_info": {
    "active_payment_method_id": "33333333-3333-4333-8333-333333333333",
    "method_count": 1,
    "methods_truncated": false,
    "methods": [
      {
        "payment_method_id": "33333333-3333-4333-8333-333333333333",
        "payment_rail": "onchain",
        "chain_slug": "ethereum",
        "network": "mainnet",
        "caip_network_id": "eip155:1",
        "asset_id": "44444444-4444-4444-8444-444444444444",
        "asset_key": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "caip_asset_id": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "asset_name": "USD Coin",
        "symbol": "USDC",
        "asset_kind": "token",
        "asset_decimals": 6,
        "contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "token_standard": "erc20",
        "destination_address": "0x1111111111111111111111111111111111111111",
        "destination_tag": null,
        "status": "paid",
        "amounts": {
          "expected_amount": "58.17342",
          "expected_amount_atomic": "58173420",
          "received_amount": "58.17342",
          "received_amount_atomic": "58173420",
          "confirmed_amount": "58.17342",
          "confirmed_amount_atomic": "58173420",
          "unconfirmed_amount": "0",
          "unconfirmed_amount_atomic": "0",
          "minimum_payment_amount": "57.591686",
          "minimum_payment_amount_atomic": "57591686",
          "remaining_amount": "0",
          "remaining_amount_atomic": "0",
          "remaining_to_full_amount": "0",
          "remaining_to_full_amount_atomic": "0",
          "overpaid_amount": "0",
          "overpaid_amount_atomic": "0"
        },
        "acceptance": {
          "finality_mode": "confirmations",
          "required_confirmations": 2,
          "observed_confirmations": 2,
          "underpayment_tolerance_percent": "1"
        },
        "quote": {
          "effective_rate": "1.1658",
          "reference_rate": "1.16",
          "units": "asset_per_invoice_currency",
          "currency": "EUR",
          "symbol": "USDC",
          "exchange_rate_spread_percent": "0.5",
          "quote_expires_at": "2026-09-14T12:15:00Z",
          "provenance_available": true,
          "rounding": "up",
          "unrounded_payment_amount": "58.17342",
          "rounding_adjustment": "0",
          "pricing_provider": "kraken",
          "asset_provider": "kraken",
          "pricing_fetched_at": "2026-09-14T11:59:30Z",
          "asset_fetched_at": "2026-09-14T11:59:30Z"
        },
        "market_rate_at_event": {
          "rate": "1.17",
          "units": "asset_per_invoice_currency",
          "currency": "EUR",
          "symbol": "USDC",
          "observed_at": "2026-09-14T12:05:00Z",
          "pricing_provider": "kraken",
          "asset_provider": "kraken",
          "pricing_fetched_at": "2026-09-14T12:04:30Z",
          "asset_fetched_at": "2026-09-14T12:04:30Z",
          "as_of": "2026-09-14T12:04:30Z",
          "stale": false,
          "is_fixed": false,
          "reference_currency": "USD",
          "uses_reference_proxy": false
        },
        "payment_count": 1,
        "payments_truncated": false,
        "payments": [
          {
            "payment_id": "55555555-5555-4555-8555-555555555555",
            "payment_method_id": "33333333-3333-4333-8333-333333333333",
            "transaction_id": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
            "payment_hash": null,
            "event_index": 0,
            "payment_rail": "onchain",
            "chain_slug": "ethereum",
            "network": "mainnet",
            "asset_id": "44444444-4444-4444-8444-444444444444",
            "asset_key": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "caip_asset_id": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "symbol": "USDC",
            "asset_decimals": 6,
            "amount": "58.17342",
            "amount_atomic": "58173420",
            "status": "final",
            "counts_towards_received": true,
            "confirmations": 2,
            "block_height": 26000000,
            "observed_at": "2026-09-14T12:04:30Z",
            "chain_time": "2026-09-14T12:04:20Z",
            "finalized_at": "2026-09-14T12:05:00Z",
            "explorer_name": "Etherscan",
            "explorer_url": "https://etherscan.io/tx/0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
          }
        ],
        "links": {
          "payments": "https://api.example.com/v1/projects/11111111-1111-4111-8111-111111111111/invoices/11111111-2222-4333-8444-555555555555/payments?payment_method_id=33333333-3333-4333-8333-333333333333"
        }
      }
    ]
  }
}

amount হলো মূল ইনভয়েসের মোট পরিমাণ। payment_info দেখা crypto transfer, বাকি পরিমাণ আর locked rate জানায়। Version 2-এ event name, event ID আর project/store scope-ও স্বাক্ষরিত।

Callback-এর সব field আর অতিরিক্ত ইনভয়েস ডেটা
Fieldধরনঅর্থ
invoice_idUUIDPublic invoice UUID, authenticated invoice detail route-এ ব্যবহৃত
statusstringSnapshot invoice state: new, processing, settled, expired, invalid, cancelled
amount_statusstringnone, partial, paid বা overpaid; paid-এ গ্রহণযোগ্য underpayment tolerance আছে, confirmation finality নয়
timing_statusstringon_time বা late
resolutionstringautomatic, manually_settled বা manually_invalidated
sequenceintegerবাড়তে থাকা invoice revision; একাধিক event-এর revision এক হতে পারে। integer precision না হারিয়ে তুলনা করো
amountdecimal stringমূল ইনভয়েসের মোট পরিমাণ, প্রাপ্ত crypto amount নয়; decimal precision বজায় রাখো
currencystringamount-এর মুদ্রা, যেমন USDC দিয়ে দেওয়া EUR ইনভয়েসে EUR
order_idstring | nullমার্চেন্টের order reference
payload_versionintegerনতুন 4.1.0+ event-এ 2; সংরক্ষিত পুরোনো event-এ অনুপস্থিত
event_idUUIDস্বাক্ষরিত event identity, retry আর manual redelivery-তে অপরিবর্তিত
event_typestringসাতটি subscription event-এর একটি
occurred_attimestampএই অপরিবর্তনীয় event কখন তৈরি হয়েছে, delivery-এর সময় নয়
project_idUUIDমার্চেন্ট project scope; কনফিগার করা receiver-এর সঙ্গে মিলাও
store_idUUIDমার্চেন্ট store scope; কনফিগার করা receiver-এর সঙ্গে মিলাও
descriptionstring | nullমূল ইনভয়েসের বর্ণনা
emailstring | nullEvent তৈরির সময়ের ঐচ্ছিক customer email
customerobjectচেনা ঐচ্ছিক customer metadata field; অনুমান বা বাড়তি সংগৃহীত ব্যক্তিগত ডেটা নয়
metadataobjectEvent তৈরির সময় যেমন ছিল সেই মূল merchant metadata
created_attimestampইনভয়েস তৈরির সময়
updated_attimestampইনভয়েস state আপডেটের সময়
expires_attimestampইনভয়েস পেমেন্টের সময়সীমা
monitoring_expires_attimestampদেরির পেমেন্ট পর্যবেক্ষণের সময়সীমা
settled_attimestamp | nullসেটেলমেন্টের সময়
paid_chainstring | null4.1.2+: প্রমাণিত settling method-এর chain slug, যেমন ethereum; উপযুক্ত settlement সেভ না থাকলে null
paid_assetstring | null4.1.2+: native coin বা token ticker, যেমন BTC, ETH বা USDC; দেখানোর label, অনন্য asset identity নয়
paid_asset_amountdecimal string | null5.0.1+: tolerance বাদ দেওয়ার আগের paid_asset এককে চাওয়া পুরো locked amount; settlement-এ সেভ হয়
paid_asset_amount_receiveddecimal string | null5.0.1+: settlement-এর সময় winning method-এ পাওয়া মোট বৈধ পরিমাণ, গ্রহণযোগ্য কম/বেশিসহ; স্থির, live balance নয়
paid_payment_method_idUUID | null4.1.2+: settling intent ID; payment_info.methods[].payment_method_id আর তার সঠিক network/contract-এর সঙ্গে মেলে
settlement_exchange_rateobject | null4.1.2+: settlement-এ সেভ করা spread-এর আগের market snapshot, স্পষ্ট unit, currency, source timestamp আর quality flag-সহ; delivery-তে নতুন দাম বসে না
cancelled_attimestamp | nullবাতিলের সময়
exchange_rate_spread_percentdecimal stringলক করা spread, বর্তমান store default নয়
underpayment_tolerance_percentdecimal stringলক করা invoice tolerance; প্রতিটি method-এ তার কার্যকর tolerance-ও থাকে
reason_codestring | nullMachine-readable state-transition reason
requires_reviewbooleanপেমেন্ট ব্যতিক্রমের ইঙ্গিত; স্বয়ংক্রিয় fulfil বা refund-এর অনুমতি নয়
linksobjectEvent তৈরির সময়ের checkout, authenticated invoice আর payments URL। আগে Store → Basic-এর domain preference, তারপর default store, তারপর global primary; শুধু সক্রিয় role-মেলা domain ব্যবহার হয়। Retry-তে মূল স্বাক্ষরিত link থাকে; active host record না থাকলে null।
payment_infoobjectবাস্তবে দেখা method, সঠিক পরিমাণ, locked quote, ধারণামূলক market snapshot আর সীমিত payment observation; নিচের field group দেখো

সেটেলমেন্ট সারাংশ: settlement_exchange_rate

Fieldধরনঅর্থ
rate / units / currency / symbolstringsSpread-এর আগে প্রতি এক invoice currency unit-এ asset unit। Decimal string, payment amount বা সম্পন্ন trade নয়।
observed_at / as_oftimestampsSettlement capture-এর সময় / পুরোনো source timestamp। cached data-কে live tick ভেবো না।
pricing_provider / asset_provider / pricing_fetched_at / asset_fetched_atstrings / timestampsFiat আর asset price-এর উৎস ও fetch time, settlement-এ সেভ করা।
stale / is_fixed / uses_reference_proxy / reference_currencybooleans / stringmarket_rate_at_event-এর মতো quality flag। Fixed project price চিহ্নিত থাকে; reference currency USD।
Missing snapshot or pricenullপুরোনো rate অনুমান করা হয় না। Settlement-এর আগে সব summary field null; শুধু দাম না থাকলেও প্রমাণিত paid_* identifier থাকে।

পেমেন্ট পদ্ধতি: payment_info

Fieldধরনঅর্থ
active_payment_method_idUUID | nullWinning বা বাছাই করা observed method। Detection-এর আগে বা invalidation-এর পরে null; default method অনুমান করা হয় না।
method_count / methods_truncatedinteger / booleanমোট observed method আর embedded method list অসম্পূর্ণ কি না।
methods[]object[]সর্বোচ্চ আটটি observed method, active method আগে। ভিন্ন asset-এর মোট যোগ করা হয় না।
payment_method_id / payment_railUUID / stringInvoice intent identity আর onchain বা lightning transport।
chain_slug / network / caip_network_idstringNetwork identity। Token identity-এর সঙ্গে সব সময় তার network রাখো।
asset_id / asset_key / caip_asset_idUUID / string / nullable stringযাচাই করা registry identity; শুধু symbol অনন্য নয়।
asset_name / symbol / asset_kindstringদেখানোর asset name, ticker আর native বা token ধরন।
contract_address / token_standardstring | nullToken contract বা mint আর standard; native asset-এর জন্য null।
asset_decimalsintegerAtomic precision; Lightning BTC-তে 11।
destination_address / destination_tagstring | nullPublic receiving address আর প্রয়োজনীয় memo/tag। Lightning-এ address null; কখনো private key নয়।
statusstringMethod state: pending, partial, paid, overpaid, expired বা invalid। শুধু paid হওয়া invoice settlement নয়।
payment_count / payments_truncated / payments[]integer / boolean / object[]মোট observation আর সর্বশেষ পাঁচটি বা কম। নিচে প্রতিটির বর্ণনা আছে।
links.paymentsHTTPS URL | nullকনফিগার করা API origin-এ এই method-এর authenticated paginated history।

সঠিক পরিমাণ: methods[].amounts

Fieldধরনঅর্থ
expected_amountdecimal stringSpread আর ওপরের দিকে rounding-এর পরে পুরো locked quote।
received_amount / confirmed_amountdecimal stringsশনাক্ত বৈধ অর্থ / এই method-এর confirmation বা finality policy পূরণ করা অর্থ।
unconfirmed_amountdecimal stringmax(received - confirmed, 0)। অতিরিক্ত পাঠানোর পরিমাণ নয়।
minimum_payment_amountdecimal stringTolerance-এর পরে গ্রহণযোগ্য সীমা। পুরো quote-এর চেয়ে কম হতে পারে।
remaining_amountdecimal stringmax(minimum accepted - received, 0)। গ্রহণযোগ্য সীমায় পৌঁছাতে আরও যে অর্থ লাগে, confirmation-এর অগ্রগতি নয়।
remaining_to_full_amountdecimal stringmax(full quote - received, 0), tolerance বাদ দিয়ে।
overpaid_amountdecimal stringmax(received - full quote, 0)। স্বয়ংক্রিয় refund-এর অনুমতি দেয় না।
Every amount's *_atomic companioninteger stringসবচেয়ে ছোট এককে সঠিক প্রকাশ। decimal বা integer library ব্যবহার করো; অর্থের জন্য float বা JavaScript Number নয়।

Confirmation policy: methods[].acceptance

Fieldধরনঅর্থ
finality_mode / required_confirmationsstring / integerলক করা confirmation বা finalized policy। Zero confirmation মার্চেন্টের নীতিতে স্পষ্টভাবে অনুমোদিত, সর্বজনীন network finality নয়।
observed_confirmationsinteger | nullবৈধ observation-এর মধ্যে সর্বনিম্ন, শুধু নতুন transfer নয়। Lightning বা বৈধ observation না থাকলে null।
underpayment_tolerance_percentdecimal stringMethod-এর কার্যকর tolerance। Invoice-এ on-chain tolerance শূন্যের বেশি হলেও Lightning-এ শূন্য।

Rate: methods[].quote আর market_rate_at_event

Fieldধরনঅর্থ
quote.effective_rate / units / currency / symbolstringsSpread-সহ locked asset_per_invoice_currency rate; currency আর symbol দিয়ে দিক স্পষ্ট করা থাকে।
quote.exchange_rate_spread_percent / quote_expires_atdecimal string / timestampলক করা spread আর quote deadline। বর্তমান store settings দিয়ে কখনো বদলানো হয় না।
quote.reference_rate / unrounded_payment_amount / rounding_adjustmentdecimal string | nullSpread-এর আগের reference, rounding-এর আগের payment amount আর asset unit-এ ওপরের দিকে adjustment।
quote.pricing_provider / asset_provider / pricing_fetched_at / asset_fetched_atstring or timestamp | nullমূল currency আর asset price-এর উৎস/সময়। API key বা provider credential নয়।
quote.provenance_available / roundingboolean / stringসেভ করা source snapshot ছাড়া পুরোনো ইনভয়েসে false; rounding ওপরের দিকে।
market_rate_at_eventobject | nullEvent তৈরির সময়ের ধারণামূলক cached market snapshot। ডেটা না থাকলে null থাকে; এটি invoice amount বদলায় না বা network fetch-এর জন্য দেরি করে না।
market_rate_at_event.rate / units / currency / symbolstringsSpread-এর আগের market rate, quote-এর মতো একই স্পষ্ট দিকসহ।
market_rate_at_event.observed_at / as_of / pricing_fetched_at / asset_fetched_attimestampsEvent snapshot-এর সময় / দুই source time-এর মধ্যে পুরোনোটি / প্রতিটি source-এর সময়।
market_rate_at_event.pricing_provider / asset_providerstringsCached currency আর asset source, কনফিগার করা custom-token price-সহ।
market_rate_at_event.stale / is_fixed / uses_reference_proxy / reference_currencybooleans / stringCache পুরোনো কি না, token price fixed কি না বা USD reference stablecoin proxy ব্যবহার করে কি না। Reference currency USD। Stale ধারণামূলক তথ্য, কখনো নতুন quote নয়।

Transfer record: methods[].payments[] আর GET …/payments

Fieldধরনঅর্থ
payment_id / payment_method_idUUIDObservation identity / parent intent identity। History-র duplicate বাদ দিতে payment_id ব্যবহার করো।
transaction_id / payment_hash / event_indexstring | null / integerOn-chain hash আর transfer/log/output index, অথবা Lightning hash। Lightning-এ transaction বা explorer link নেই।
payment_rail / chain_slug / network / asset_id / asset_key / caip_asset_id / symbol / asset_decimalsstrings / UUID / integerধারণকারী method-এর মতোই asset আর network identifier।
amount / amount_atomicdecimal / integer stringsএই transfer-এর সঠিক মূল্য, কখনো fiat conversion নয়।
status / counts_towards_receivedstring / booleandetected, confirming আর final গণনায় ধরা হয়; reorged, replaced আর invalid নয়। হিসাব মেলানোর জন্য invalidated history রাখো।
confirmations / block_heightinteger | nullObservation-এর block data; Lightning-এ confirmation null।
observed_at / chain_time / finalized_attimestamp | nullপ্রথম local detection-এর সময়, পাওয়া গেলে বিশ্বস্ত chain time এবং policy-final হলে সেই সময়।
explorer_name / explorer_urlstring | nullসমর্থিত হলে যাচাই করা public block-explorer reference।

Merchant 5.13.3 গ্রাহকের মোট পেমেন্ট, payment_info, invoice payments API, refund limit আর payment.received event থেকে যাচাই করা internal gas-funding transfer বাদ দেয়। Wallet accounting-এর জন্য chain/treasury record থাকে। সাধারণ transfer আর প্রকৃত overpayment ধরা হয়। আগের স্বাক্ষরিত callback body কখনো নতুন করে লেখা হয় না। পুরোনো settlement গ্রাহকের অর্থের বদলে internal funding-এর ওপর নির্ভর করলে reconciliation reason_code internal_gas_funding_excluded-সহ invoice.invalid তৈরি করে; আবার অর্ডার পূরণ না করে পর্যালোচনা করো।

Merchant 4.1.0 মূল নয়টি field সরানো বা বদলানো ছাড়াই payload_version 2 যোগ করে। আগে কিউতে থাকা event-এর মূল body থাকে এবং payload_version নাও থাকতে পারে। event_id, event_type আর project/store ID এখন স্বাক্ষরিত body-র মধ্যে; transport event/delivery header এখনো স্বাক্ষরিত নয়।

payment_info দেখা পেমেন্টের বর্ণনা দেয়, চেকআউটে দেওয়া সব বিকল্পের নয়। Detection-এর আগে active_payment_method_id null আর methods খালি থাকে। Active method null হওয়ার পরও reorged/invalid observation methods-এ থাকতে পারে। ভিন্ন asset বা network-এর পরিমাণ কখনো যোগ কোরো না।

সব amount, atomic integer, rate আর percentage string। received_amount-এ confirmation-এর অপেক্ষায় থাকা বৈধ অর্থ থাকে; confirmed_amount সেই method-এর finality policy পূরণ করে। remaining_amount হলো max(minimum_payment_amount minus received_amount, 0); remaining_to_full_amount হলো max(expected_amount minus received_amount, 0)। উদাহরণ: চাওয়া 100 USDC, পাওয়া 99, tolerance 1% হলে remaining_amount 0 আর remaining_to_full_amount 1। Finality তবুও দরকার।

quote হলো locked invoice calculation: প্রতি এক invoice currency unit-এ asset unit। ওপরের দিকে rounding-এর আগে spread লাগে। সঠিক পেমেন্ট তুলনায় expected_amount_atomic ব্যবহার করো; শুধু দেখানো rate দিয়ে upward rounding পুনরায় নাও পাওয়া যেতে পারে। Source provenance সেভ না থাকা পুরোনো ইনভয়েসে source/reference/rounding field null আর provenance_available false থাকে; আজকের ডেটাকে পুরোনো quote বলে দেখায় না।

market_rate_at_event spread-এর আগের ধারণামূলক cached data, event তৈরির সময় স্থির করা। এতে source time, stale আর reference-proxy flag থাকে; ব্যবহারযোগ্য cached pair না থাকলে null। Live rate request নোটিফিকেশন আটকায় না, এবং এই market observation পাওনা বদলায় না। Fixed custom token-এ is_fixed label থাকে; DEX token একই symbol-এর অন্য token নয়, তার প্রকল্পের নির্দিষ্ট source ব্যবহার করে।

Top-level paid_chain, paid_asset, paid_payment_method_id আর settlement_exchange_rate (4.1.2+) settlement-এর পরে প্রমাণিত winning method চিহ্নিত করে, বাছাই করা checkout option বা ভিন্ন method-এর যোগফল নয়। Settlement-এর আগে, invalidation-এর পরে, পুরোনো snapshot-বিহীন settlement-এ বা উপযুক্ত policy-final অর্থ ছাড়া manual acceptance-এ summary field null। Symbol দেখানোর label: সঠিক network/asset/contract identity-এর জন্য method ID অনুসরণ করো।

Merchant 5.0.1 paid_asset এককে সঠিক decimal string হিসেবে paid_asset_amount আর paid_asset_amount_received যোগ করে; payload_version 2 থাকে। paid_asset_amount হলো পুরো locked quote, spread আর upward rounding-সহ, tolerance threshold বা বাকি balance নয়। paid_asset_amount_received হলো settlement-এর সময় winning method-এর মোট বৈধ প্রাপ্তি, confirmation-এর অপেক্ষায় থাকা অর্থ আর গ্রহণযোগ্য কম/বেশিসহ। উদাহরণ: 100 USDC quote, 99 পাওয়া এবং tolerance-এ গ্রহণ করা হলে মান 100 আর 99, 99 আর 99 নয়। দুটোই settlement snapshot-এ স্থির; প্রতিটি event-এর প্রাপ্তির জন্য payment_info.methods[].amounts বা বর্তমান record-এর জন্য payments API ব্যবহার করো। উপযুক্ত snapshot ছাড়া এবং 5.0.1-এর আগের snapshot-এ এগুলো null; পুরোনো queued event body অপরিবর্তিত। Accounting-এর জন্য সঠিক decimal string কখনো floating point-এ বদলিও না।

settlement_exchange_rate settlement-এর সঙ্গে নেওয়া spread-এর আগের cached market observation, locked invoice quote বা সম্পন্ন exchange trade নয়। এর গঠন market_rate_at_event-এর মতো; EUR/USDC-তে 1.17 asset_per_invoice_currency মানে 1 EUR = 1.17 USDC। Source timestamp আর stale/fixed/proxy flag মানের অবস্থা জানায়। Pair না থাকলে rate null, কিন্তু প্রমাণিত method-এর paid_* field থাকে। এটি পাওনা বদলায় না বা live provider call-এর অপেক্ষা করে না। একই method-এ পরের payment, retry আর redelivery সেভ করা snapshot বদলাতে পারে না, সেভ করা null rate-ও নয়। প্রকৃত re-settlement বা settling method বদলালে নতুন snapshot হয়; observed_at সেই capture চিহ্নিত করে, settled_at প্রথম settlement-এর সময় রেখেও দিতে পারে। পুরোনো event body অপরিবর্তিত থাকে।

সর্বোচ্চ আটটি observed method আর প্রতিটি method-এর সর্বশেষ পাঁচটি payment observation থাকে, count আর truncation flag-সহ। Payload budget-এ array আরও ছোট হতে পারে। একটি payment observation একটি transfer/log/UTXO output, সব সময় অনন্য transaction hash নয়। সম্পূর্ণ বর্তমান history পেতে payment_method_id, limit আর offset-সহ GET /v1/projects/YOUR_PROJECT_ID/invoices/{invoice_id}/payments ব্যবহার করো। Invoice detail-এ সব quoted method আর quote_details থাকে। API link-এ তোমার configured host আর credential লাগে; callback-এর দেওয়া যেকোনো URL-এ bearer token ফরোয়ার্ড কোরো না।

Lightning transaction_id-এর বদলে payment_hash ব্যবহার করে; receiving address, explorer আর observed confirmation null। সঠিক BTC amount-এ ১১ decimal (millisatoshi) থাকে, আর কার্যকর tolerance শূন্য। BOLT11 payment preimage, wallet key, signing secret বা provider credential থাকে না। Customer/metadata field শুধু merchant response আর signed callback-এর জন্য, public checkout নয়; metadata-তে credential রেখো না।

পৃষ্ঠাভাগ করা payment history →

নিরাপদে গ্রহণ করো

  1. Parse করার আগে সঠিক secret দিয়ে হুবহু raw body যাচাই করো। Store → IPN-এ IPN secret থাকে, custom ipn_url delivery-র জন্যও। Store → Webhooks-এর প্রতিটি endpoint-এর নিজের secret আছে। কোনোটিই API token নয়; একটি বদলালে অন্যগুলো বদলায় না।
  2. স্বাক্ষরিত timestamp পরীক্ষা করো (SDK default: দুই দিকেই পাঁচ মিনিট) এবং signed project/store ID থাকলে receiver configuration-এর সঙ্গে মিলাও। HTTP 2xx দেওয়ার আগে স্থায়ী কিউতে রাখো। প্রতি-event processing-এ v2 event_id স্বাক্ষরিত; শুধু header ID replay protection নয়, কারণ header স্বাক্ষরিত নয়। Order-state inbox-এ invoice_id আর sequence দিয়ে duplicate বাদ দাও এবং মূল invoice state field তুলনা করো, পুরো v2 body নয়: ভিন্ন event type/ID একই revision ভাগ করতে পারে।
  3. Worker-এ configured API origin থেকে বর্তমান invoice পড়ো, যেকোনো callback link থেকে নয়। সেভ করা order, project/store, amount আর currency মিলাও, বর্তমান status settled চাই এবং manual-acceptance ও exception policy প্রয়োগ করো। Order lock করে database transaction-এ একবারই পূরণ করো, event deduplication থেকে স্বাধীনভাবে।
  4. নতুন sequence-এর ওপর পুরোনো sequence কখনো প্রয়োগ কোরো না। ভিন্ন event-এর revision এক হতে পারে; revision-level deduplication-এর সঙ্গে শুধু invoice.settled filter মিশিয়ো না। Reopen/reconciliation-এ status বদলাতে পারে; update-এর ক্রম sequence ঠিক করে, নির্দিষ্ট status ranking নয়। আবার পূরণ না করে reversal পর্যালোচনার জন্য রেকর্ড করো।

Receiver উদাহরণ: PHP · Python · Node.js / TypeScript.

Signature verification ও delivery-এর নিয়ম
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWhollySignature(rawBody, header, signingSecret, toleranceSeconds = 300) {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || "");
  if (!match) return false;

  const timestamp = Number(match[1]);
  if (!Number.isSafeInteger(timestamp)) return false;
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > toleranceSeconds) return false;

  // rawBody must be the exact request Buffer, before JSON parsing.
  const expected = createHmac("sha256", signingSecret)
    .update(String(timestamp))
    .update(".")
    .update(rawBody)
    .digest();
  const presented = Buffer.from(match[2], "hex");
  return timingSafeEqual(expected, presented);
}
Delivery-এর নিয়মবিস্তারিত
HeaderWholly-Signature, Wholly-Event-Id আর Wholly-Delivery-Id; Content-Type হলো application/json।
স্বাক্ষর<unix timestamp>.<exact raw body>-এর ওপর HMAC-SHA256; header format t=<timestamp>,v1=<64 lowercase hex>।
সফলযেকোনো HTTP 2xx response। Redirect অনুসরণ করা হয় না; non-2xx response ব্যর্থ।
Timeoutসংযোগের timeout ৫ সেকেন্ড, পুরো অনুরোধের timeout ১০ সেকেন্ড।
আবার চেষ্টার সময়সূচিআবার চেষ্টা করা যায় এমন ব্যর্থতায় সর্বোচ্চ ৮ বার: সঙ্গে সঙ্গে, তারপর আগের চেষ্টা শেষের 10s, 1m, 5m, 15m, 1h, 6h আর 24h পরে। IPN নিজে থেকে retry করে; webhook-এর automatic retry প্রতি endpoint-এ বন্ধ করা যায়।
গন্তব্যের নিরাপত্তাশুধু public HTTPS। Delivery-র জন্য DNS আবার যাচাই করে pin করা হয়; local/private/reserved গন্তব্য প্রত্যাখ্যাত হয়।
Event সংরক্ষণNotification event payload আর delivery ৯০ দিন রাখার সময়সূচি আছে; সংরক্ষিত বিস্তারিত সীমিত batch-এ মুছে ফেলা হয়।
ডুপ্লিকেট প্রতিরোধConfigured project-এর scope-এ স্বাক্ষরিত invoice_id আর sequence স্থায়ীভাবে রাখো। Wholly-Event-Id event চিহ্নিত করে; Wholly-Delivery-Id delivery record চিহ্নিত করে (retry একইটি ব্যবহার করে; manual redelivery নতুনটি বানায়)। কোনো ID header-ই স্বাক্ষরিত নয়।
Event-এর নামVersion 2 body-তে event_id আর event_type স্বাক্ষর করে। পুরোনো queued event-এ কোনোটিই নেই। ভিন্ন event type একই invoice sequence ভাগ করতে পারে; revision দিয়ে invoice state মিলাও, অথবা স্বাক্ষরিত event_id দিয়ে পৃথক event-এর duplicate বাদ দাও।
Secret পরিবর্তনপরিবর্তনে overlap বা version header নেই এবং queued, retried আর manual delivery-র signature সঙ্গে সঙ্গে বদলায়।
স্থগিত deliveryপ্রসেসিং ক্রেডিট কম থাকলে retry-সহ IPN/webhook থামে। পেমেন্ট আসতে থাকে; credit যোগ হলে payload-retention সময়ের মধ্যে queued notification আবার চলে।

AI সহকারী · MCP

মার্চেন্ট ইনস্টলেশনে assistant সংযুক্ত করো।

Merchant 5.0.0-এ configured API domain-এ চাইলে চালু করার MCP server আছে। এটি তোমার ইনস্টলেশনের ভেতর চলে, shared Wholly Crypto relay দিয়ে নয়।

  1. Settings → API access খোলো। আলাদা ক্রেডেনশিয়াল বানাও, assistant-এর দরকারি প্রকল্পই দাও এবং read-only দিয়ে শুরু করো। Operator-hosted account-এ operator আগে installation-এর MCP service চালু করে; তুমি শুধু নিজের credential আর grant পরিচালনা করো।
  2. AI connections · MCP-তে MCP চালু করো, credential বেছে নিয়ে তার MCP access সেভ করো। স্পষ্টভাবে চালু করার আগে পুরোনো credential-এর MCP access থাকে না।
  3. MCP server URL client-এর remote HTTP server settings-এ কপি করো। OAuth হলে merchant console-এ sign in করো, client name আর return address দেখে credential বেছে অনুমোদন করো। আগের Basic Auth আর TOTP সুরক্ষা প্রযোজ্য থাকে।
  4. ইনভয়েস তৈরিতে আরও লাগে read/write credential, MCP policy-তে Read + create invoices, mcp:invoice:create OAuth scope এবং স্পষ্ট অনুমোদন। অনুমোদনের পরে credential-এ যোগ করা project কোনো OAuth connection নিজে থেকে পায় না।
{
  "mcpServers": {
    "whollycrypto": {
      "url": "https://api.example.com/mcp"
    }
  }
}

MCP সেটআপ গাইড →

Toolপ্রবেশাধিকারকাজ
list_projectsপড়োসংযোগে দেওয়া সক্রিয় প্রকল্প; limit/offset pagination।
list_storesপড়োproject_id-এর মধ্যে store, ID আর enabled status; limit/offset pagination।
list_payment_methodsপড়োproject_id + store_id-এর কনফিগার করা chain, token আর Lightning method।
get_wallet_balancesপড়োReceiving address আর cached balance, কতটা নতুন/উপলভ্য তা বোঝানোর field-সহ; কখনো wallet secret নয়।
list_invoicesপড়োStore, status বা search দিয়ে ফিল্টার করা project invoice; limit/offset pagination।
get_invoiceপড়োproject_id + invoice_id দিয়ে পুরো invoice detail আর checkout link।
get_delivery_historyপড়োStore IPN/webhook-এর status, attempt আর HTTP result। ঐচ্ছিক invoice_id/kind filter; secret বা callback body নেই।
convert_amountপড়োfrom, to আর decimal-string amount দিয়ে cached reference conversion; invoice quote নয়।
create_invoiceস্পষ্ট write অনুমতিproject_id, store_id, idempotency_key আর invoice (আগের invoice creation body)। invoice.payment_methods চালু store method ফিল্টার করে; 5.4.0+ inactive/unaccepted পছন্দ উপেক্ষা করে এবং কিছু না মিললে store default নেয়। শুধু chain দিলে সব সক্রিয় গ্রহণযোগ্য asset আসে। Chain-scoped asset_tickers 5.3.0 থেকে সমর্থিত। সাধারণ invoice response ফেরত দেয়।
Protocol, OAuth ও নিরাপত্তা

HTTPS-এর ওপর Streamable HTTP ব্যবহার করো। প্রকাশিত protocol version ঠিক করে পরের POST-এ MCP-Protocol-Version দাও। Content-Type: application/json আর Accept: application/json, text/event-stream পাঠাও। Response সীমিত JSON; reconnect-এ MCP session ID লাগে না।

OAuth অল্পমেয়াদি access token (১৫ মিনিট), একবার ব্যবহারযোগ্য S256 PKCE code (৫ মিনিট) আর rotating refresh token (সংযোগের মেয়াদ ৩০ দিন) ব্যবহার করে। ব্যবহৃত refresh token আবার দিলে সংযোগ বাতিল হয়। মেয়াদ শেষ, credential rotation, policy change বা মূল API domain বদলালে আবার সংযুক্ত করো।

MCP চালু থাকলেই OAuth discovery public হয়। resource parameter discovery থেকে ফেরত আসা canonical URL-এর সমান হতে হবে, /mcp-সহ। Dynamic registration সমর্থিত; remote client-ID metadata document আর client secret নয়।

Custom Authorization header সমর্থন করা client-এ MCP-enabled merchant API token Bearer হিসেবে ব্যবহার করা যায়। এর আলাদা REST permission থাকে; শুধু MCP-সীমিত সংযোগে OAuth ভালো। chat, URL, tool argument বা source control-এ credential পেস্ট কোরো না।

MCP ক্রেডেনশিয়ালের প্রতি-মিনিট REST quota আর নির্দিষ্ট source-IP restriction ভাগ করে, সঙ্গে API-host IP restriction। OAuth whitelist এড়ায় না। Remote AI client-এর প্রকাশিত outgoing IP অনুমোদন করো অথবা সচেতনভাবে restriction বন্ধ রাখো। MCP/OAuth route-এ web security challenge বা caching রেখো না।

HTTP error: 401-এ authentication লাগে, 403 origin/IP/permission আটকায়, 404 মানে MCP বন্ধ বা ভুল host, 405 মানে POST ব্যবহার করো, 413 মানে 32 KiB body limit, 429-এ Retry-After থাকে। JSON-RPC error error.code ব্যবহার করে; tool-level ব্যর্থতায় HTTP 200 হলেও result.isError=true থাকে। সফল ফলাফলে content আর structuredContent থাকে।

তালিকায় ডিফল্ট ২৫ row, সর্বোচ্চ ১০০; offset-এর সীমা 1000000। Tool reply সর্বোচ্চ 2 MiB। মেয়াদোত্তীর্ণ grant, authorization request আর rate bucket নিজে থেকে পরিষ্কার হয়; settings-এ সর্বোচ্চ ১০০ সক্রিয় OAuth connection দেখায়।

বন্ধ project/store MCP দিয়ে পরিচালনা করা যায় না। সংযোগ store-এর enabled state দেখাতে পারে, কিন্তু payment method, delivery history পড়া বা invoice তৈরিতে store চালু থাকতে হবে। সাধারণ console project user MCP administer করতে পারে না।

নতুন invoice-এ নতুন idempotency_key ব্যবহার করো; timeout হলে একই credential, key আর হুবহু invoice object দিয়ে retry করো। Decimal amount, spread, tolerance, confirmation আর checkout appearance REST invoice contract মেনে চলে। MCP merchant payment বা credit policy এড়ায় না।

প্রাথমিক tool-গুলো private key/recovery phrase দেখাতে, অর্থ send/sweep করতে, refund দিতে, callback আবার পাঠাতে, payment method বদলাতে, account/domain edit করতে বা billing চালাতে পারে না। Invoice description, customer field আর metadata-কে অবিশ্বস্ত ডেটা হিসেবে ধরো, agent instruction নয়। সংযুক্ত AI provider অনুমোদিত পড়ার ডেটা পায়।

MethodPathContract
POST/mcpAuthenticated JSON-RPC: initialize, ping, tools/list, tools/call। Notification request-এ 202 ফেরত আসে; batch প্রত্যাখ্যাত হয়।
GET / DELETE/mcpAuthenticated 405: সীমিত JSON response, আলাদা SSE stream বা server-side MCP session নেই।
GET/.well-known/oauth-protected-resource/mcpCanonical resource URL আর authorization-server discovery; /.well-known/oauth-protected-resource-এও আছে।
GET/.well-known/oauth-authorization-serverOAuth endpoint, authorization_code/refresh_token, S256 PKCE আর সমর্থিত scope।
POST/mcp/oauth/registerPublic-client registration: client_name আর হুবহু redirect_uris। শুধু HTTPS বা loopback HTTP। Client secret বা remote metadata fetching নেই।
GET/mcp/oauth/authorizeclient_id, redirect_uri, response_type=code, resource, code_challenge, code_challenge_method=S256, ঐচ্ছিক scope/state; console approval-এ redirect করে।
POST/mcp/oauth/tokenForm-encoded authorization_code + code + code_verifier + redirect_uri, অথবা refresh_token + refresh_token। সব সময় client_id আর resource দাও।
POST/mcp/oauth/revokeForm-encoded client_id আর token। মেলা access/refresh-token connection বাতিল করে।
সরাসরি tool request-এর উদাহরণ

আগে MCP client দিয়ে initialize করে protocol ঠিক করো। এটি তার পরের request দেখায়।

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/mcp" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'MCP-Protocol-Version: 2025-11-25' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_invoices",
    "arguments": {
      "project_id": "YOUR_PROJECT_ID",
      "limit": 10
    }
  }
}'

অপারেটর API

আলাদা, সীমিত server-side key দিয়ে hosted merchant তৈরি করো।

একাধিক ব্যবসা host করে api.example.com/v1/operator দিয়ে setup automate করো। 7.4.0 থেকে শুধু Operator mode-এ আছে। সাধারণ Merchant API অপরিবর্তিত।

  1. Operator → Settings → Operator API খুলে চালু করো (ডিফল্টে বন্ধ)। শুধু প্রয়োজনীয় permission আর hosted merchant-সহ আলাদা credential তৈরি করো।
  2. wc_operator_ key সার্ভারে রাখো। API hostname ব্যবহার করো, Operator panel hostname বা merchant key নয়।
  3. প্রতিটি Operator POST-এর আগে Idempotency-Key আর হুবহু request body স্থায়ীভাবে রাখো। ফল অনিশ্চিত হলে account পড়ে দেখো; শুধু retry করতে key বদলিও না।
  4. onboarding: direct আর password দিয়ে, অথবা onboarding: invitation আর password ছাড়া merchant তৈরি করো। তারপর project/store বানিয়ে checkout integration-এর জন্য project-scoped merchant key দাও।
Scopeপ্রবেশাধিকার
merchants.read / merchants.writeHosted merchant তালিকা/পড়া আর তৈরি/আপডেট।
users.read / users.write / users.securityUser পড়া/তৈরি/আপডেট; password বদলানো বা session বাতিল আলাদা। কখনো operator administrator তৈরি করে না।
invitations.read / invitations.writeএকবার ব্যবহারযোগ্য invitation/reset link তালিকা/পড়া, তৈরি, প্রতিস্থাপন আর বাতিল। নতুন user-এর জন্য users.write-ও লাগে; reset-এ users.security-ও লাগে।
credits.read / credits.write / fees.writeBalance/ledger পড়া; local credit দেওয়া বা সংশোধন; ভবিষ্যৎ fee সেট করা। শূন্যের বেশি starting credit-এ credits.write লাগে।
topups.read / topups.writeHosted-merchant credit checkout request পড়া বা তৈরি। কোনো API action এটিকে paid করতে পারে না।
projects.read / projects.write / reports.readMerchant project, store, appearance আর payment settings তৈরি; invoice, wallet balance আর financial report পড়া।
merchant_credentials.read / merchant_credentials.writeসাধারণ scoped merchant key পরিচালনা। শক্তিশালী অনুমতি: ইস্যু হওয়ার পর key-গুলো স্বাধীনভাবে কাজ করে।
events.read / webhooks.write / audit.read / health.readLifecycle history পড়া; signed lifecycle callback কনফিগার; audit/capability/node health পড়া।
শুরু করা, credit, permission আর নিরাপদ retry
বিষয়নিয়ম
ক্রেডেনশিয়ালঐচ্ছিক expiry আর নির্দিষ্ট IPv4/IPv6 allowlist; ডিফল্ট ৬০ request/minute, 1–600 করা যায়। প্রতিটি request-এ issuing administrator আর current scope যাচাই হয়। HTTP 429-এ Retry-After থাকে।
আলাদা রাখাKey শুধু নির্ধারিত hosted merchant-এ ঢোকে। Merchant তৈরি আর পুরো installation-এর report দেখতে all-merchants access লাগে। Operator-এর নিজের ব্যবসা বাদ থাকে।
প্রথম sign-inDirect account স্বীকার করে যে host তাদের wallet key পড়তে পারে। require_password_change প্রথম login-এ password বদলাতে বলে। Invitation গ্রহণে custody acknowledgement স্পষ্টভাবে দিতে হয়, তারপর স্বাভাবিক sign-in। Basic Auth আর আগের TOTP প্রযোজ্য থাকে।
আমন্ত্রণনতুন user-এর link ৪৮ ঘণ্টা; password-reset link এক ঘণ্টা থাকে। Token একবার ব্যবহারযোগ্য। নতুন করে ইস্যু করলে পুরোনো link বাতিল হয়। SMTP গ্রহণ মানেই inbox-এ পৌঁছানো নিশ্চিত নয়; email_delivery দেখো।
নিরাপদে আবার চেষ্টাপ্রতিটি Operator POST-এ 16–128 অক্ষরের key লাগে (letter, digit, -, _ বা .)। একই key আর হুবহু URL/body-তে সেভ করা ফল ফেরত আসে। Byte আলাদা হলে 409। Replay-তে secret/link বাদ থাকে; দরকার হলে নতুন স্পষ্ট operation দিয়ে rotate বা reissue করো।
অনিশ্চিত ফলoperator_request_in_progress মানে operation চলছে বা receipt লেখার আগে বাধা পেয়েছে। Resource আর audit দেখো; না দেখে নতুন key দিও না। সম্পন্ন receipt ৩০ দিন পরে সংক্ষিপ্ত হয়; পুরোনো key তবুও আবার চলতে পারে না।
ক্রেডিট আর ফিDecimal string, সর্বোচ্চ ছয় decimal। starting_credit একবারের local grant। Adjustment-এ signed amount, note আর request_id লাগে, সঙ্গে HTTP retry key। fee_bps=100 মানে 1%; পরিবর্তন ভবিষ্যৎ invoice-এ লাগে। Grant installation-এর নিজের prepaid balance top up করে না।
বিরতিenabled=false hosted account বন্ধ করে এবং console session বাতিল করে। payments_paused=true নতুন invoice থামায়। আগের payment monitoring চলে। Project/store creation আর automation installation-এর credit policy মেনে চলে।
যা প্রকাশিত নয়Wallet secret, signing, sending, refund, permanent deletion, TOTP reset, domain change বা server-level configuration নেই। সাধারণ invoice request-এ এখনো merchant key আর Merchant API লাগে।

Operator lifecycle webhook

Eventডেটা
merchant.created / merchant.updatedmerchant_id, enabled, payments_paused, fee_bps।
user.created / user.updatedmerchant_id, user_id, enabled। Updated event-এ email, enabled status আর admin role change থাকে।
invitation.accepted / password_reset.completedmerchant_id, user_id, invitation_id।
topup.settled / credit.balance_changedmerchant_id, ledger_id, kind, amount আর balance। হিসাব মেলাতে merchant credit currency বা ledger detail পড়ো।

Operator lifecycle event invoice IPN/store webhook থেকে আলাদা। Subscription তার সৃষ্টিকারী Operator credential-এর অধীনে, প্রতি key-তে সর্বোচ্চ ১০ endpoint। শুধু ভবিষ্যতের মেলা event queue হয়; সংরক্ষিত history-র জন্য GET /events ব্যবহার করো।

Body-তে event_id, event_type, merchant_id, occurred_at আর data থাকে। Endpoint-এর একবার দেখানো signing_secret দিয়ে হুবহু raw body-র Wholly-Signature যাচাই করো: HMAC-SHA256(secret, timestamp + '.' + raw_body), header t=...,v1=....। অল্প timestamp tolerance প্রয়োগ করো।

SDK-এর generic signature verifier ব্যবহার করো, invoice-notification parser নয়। তারপর merchant_id আর event_type যাচাই করে transaction-এ event_id সংরক্ষণ/duplicate বাদ দাও এবং স্থায়ীভাবে গ্রহণের পরই 2xx ফেরত দাও। Wholly-Event-Id স্বাক্ষরিত body-র সঙ্গে মিলতে হবে। unsigned header-কে business data ধরো না।

Delivery অন্তত একবার হয়, ক্রমের বাইরে আসতে পারে এবং সর্বোচ্চ ৮ বার চেষ্টা হয়। মিলাতে current resource পড়ো; occurred_at ক্রমশ বাড়তে থাকা sequence নয়। Delivery-র আগে scope আর enabled/expiry settings আবার পরীক্ষা হয়। Disabled subscription আগে queued কাজ থামায়, কিন্তু বন্ধ থাকা অবস্থায় নতুন event queue করে না।

Event আর delivery history ৩০ দিন রাখা হয়। Installation automation policy delivery থামাতে পারে। GET /webhooks/{id}/deliveries ফল আর অপরিবর্তনীয় payload দেখায়; public API মেয়াদোত্তীর্ণ record জোর করে পাঠায় না।

{
  "event_id": "55555555-5555-4555-8555-555555555555",
  "event_type": "merchant.created",
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "occurred_at": "2026-10-01T12:00:00Z",
  "data": {
    "merchant_id": "11111111-1111-4111-8111-111111111111",
    "enabled": true,
    "payments_paused": false,
    "fee_bps": 300
  }
}

মার্চেন্ট তৈরি করো → · আমন্ত্রণ গ্রহণ করো →

Marketplace API

সুরক্ষিত বিক্রেতার অংশ আর নিয়ন্ত্রিত payout-সহ একটি চেকআউট।

একটি customer invoice, সঠিক vendor share আর নিয়ন্ত্রিত same-asset payout। প্রতি project-এ চালু করো। Version 8.0.0 Bitcoin mainnet আর configured supported EVM native coin / standard ERC-20 token সমর্থন করে, সব receiving network নয়।

  1. প্রকল্পে Marketplace চালু করো, অংশ নেওয়া store বেছে নাও আর কনফিগার করার সময় payout বন্ধ রাখো।
  2. Vendor নিবন্ধন করে তাদের payout address স্বাধীনভাবে যাচাই করো। নতুন destination pending থাকে; অনুমোদনে destinations.approve লাগে।
  3. Settings → API access-এ আলাদা Marketplace credential তৈরি করো। সাধারণ Merchant, Operator আর MCP credential Marketplace-এর অর্থ খরচ করতে পারে না।
  4. 1–100টি positive decimal-string allocation দিয়ে invoice বানাও, যাদের যোগফল invoice amount-এর ঠিক সমান। প্রতিটি vendor-এর একই সমর্থিত store network-এ approved destination লাগবে।
  5. যাচাই করা allocation available হওয়ার অপেক্ষা করো। Payout প্রস্তুত করো, অপরিবর্তনীয় recipient আর cost limit পড়ো, তারপর revision আর হুবহু plan_hash অনুমোদন করো। Payout poll করো বা signed event যাচাই করো।
বিষয়নিয়ম
কাস্টডিCustomer-এর অর্থ আগে project-controlled wallet-এ আসে। Vendor-কে দেওয়া পর্যন্ত marketplace/server owner সেই key নিয়ন্ত্রণ করে। এটি সরাসরি customer-to-vendor payment, escrow বা vendor login system নয়।
তিন বিক্রেতা300 USD ইনভয়েসে তিনটি 100 USD share আর 4% commission থাকলে প্রতিটি vendor quoted crypto-র 96 USD-সমমূল্য পায়, আর 12 USD-সমমূল্য gross commission থাকে। Plan crypto atomic unit নিশ্চিত করে, ভবিষ্যতের fiat value নয়।
ফিআগের processing charge মূল settled invoice amount/currency-তে একবার লাগে। 1% সেট থাকলে 3 USD prepaid credit খরচ হয়, chain fee-এর আগে 9 USD-সমমূল্য commission থাকে। Vendor payout নতুন customer-sale fee তৈরি করে না।
বণ্টনLargest-remainder allocation প্রতিটি atomic unit রাখে। Commission নিচের দিকে round হয়; বাকি vendor net। Allocation override, invoice override, vendor override আর store/project default snapshot হয়। Payout-এর সময় নতুন exchange rate লাগে না।
সুরক্ষিত অর্থসাধারণ send, sweep, exchange deposit আর credit auto-top-up Marketplace receiving address বাদ দেয়। Network fee আর token gas-এর জন্য আলাদা free native coin লাগে। Cached wallet value ধারণামূলক; signing-এর আগে স্বাধীন live backing পরীক্ষা হয়।
FinalityCheckout zero confirmation বা এক scanner নিলেও Marketplace payout proof-এর জন্য positive chain floor আর দুটি স্বাধীন compatible provider লাগে। Provider cooldown payment verification/payout পিছিয়ে দেয়, অন্যভাবে বৈধ invoice creation নয়।
ব্যতিক্রমসাধারণ checkout tolerance-এ নেওয়া underpayment hold থাকে, অতিরিক্ত allocation হয় না। বিশেষ অনুমতির release সঠিক ছোট, পুরো backed split অনুমোদন করতে পারে। শুধু overpayment BTC বা সমর্থিত EVM native/ERC-20 method-এ quoted vendor split আটকায় না। অতিরিক্ত অংশ আলাদা hold থাকে। Bitcoin protected change invoice address-এ ফেরত দেয়; আলাদা project fund fee আর দরকারি dust-floor top-up দেয়। Mixed method, late/ambiguous/reorged payment আর backing না থাকলে review লাগে।
রিফান্ডএকটি দ্ব্যর্থহীন confirmed received method-এর পূর্ণ same-asset refund প্রস্তুত করে আলাদাভাবে payout হিসেবে অনুমোদন করো। Unpaid allocation আর commission reverse হয়। সব vendor-কে দেওয়া হয়ে গেলে primary wallet address আলাদাভাবে fund করো; clawback নেই। Partial vendor batch আর mixed-asset refund-এর আগে reconciliation লাগে। Partial-amount refund আর commission withdrawal 8.0.0-এ প্রকাশিত নয়।
পুনরায় চেষ্টাপ্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
Revisionবদলানো যায় এমন record-এ বর্তমান revision লাগে। Approve/resume-এ expected_plan_hash আর confirm:true-ও লাগে। Preparation ১৫ মিনিট অর্থ reserve করে; approval এক ঘণ্টা দেয়। Expired unsigned কাজ নিরাপদে ছাড়া হয়। Signed/uncertain transfer identity আর reservation ধরে রাখে।
স্বয়ংক্রিয় payoutডিফল্টে বন্ধ। প্রতি-asset policy approved destination, positive minimum, প্রতি-payout/rolling-24-hour principal আর native-fee/gas limit, interval আর confirmation অনুমোদন করে। Authority বদলানো/বাতিল করা unsent কাজ থামায়; observation চলে। Limit-এ reserved আর uncertain plan-ও থাকে। Billing-paused policy ন্যায্যভাবে reschedule হয়। Invalid invoice অন্য eligible invoice group না আটকে review-তে hold থাকে।
বিরতি ও পুনরুদ্ধারকম credit আর transfer safety gate অর্থ খরচ থামায়। Monitoring আর ledger reconciliation চলে। Resume একই সেভ করা plan পর্যালোচনা করে। দুই স্বাধীন provider-এ প্রমাণিত canonical EVM revert স্পষ্ট অনুমোদনের পরে অবশিষ্ট fee budget-এর মধ্যে replace করা যায়; মূল hash আর fee রেকর্ড থাকে। Unknown outcome বা token delivery mismatch hold থাকে। পুরো database আর key ব্যাকআপ করো; restore-এর পরে payout চালুর আগে submitted hash মিলাও।
Identifier আর paginationProject Settings থেকে project UUID আর Stores → Basic → API IDs থেকে store UUID নাও। Vendor/payout/asset ID এই API ফেরত দেয়। invoice_id হলো public invoice UUID। পৃষ্ঠাভাগ করা resource data আর pagination {page,per_page,total,pages} ফেরত দেয়; ডিফল্ট 1/25, সর্বোচ্চ ১০০ row। অর্থের সঠিক মান string।
ক্রেডেনশিয়ালের scopeKey-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

Marketplace-এর অনুমতি

marketplace.read · vendors.write · destinations.write · destinations.approve · invoices.write · policies.write · commissions.override · payouts.write · payouts.approve · webhooks.write · reconciliation.write

Allocation-এর state

pending · held · available · reserved · paid · refunding · refunded · shortfall

Payout-এর state

awaiting_approval · queued · funding_gas · sending · confirming · partially_paid · paid · needs_attention · cancelled · expired

মার্কেটপ্লেসের event

আলাদা Marketplace signing secret, invoice callback-এর মতো একই Wholly signature header আর raw-body HMAC verification algorithm ব্যবহার করে। Timestamp/signature যাচাই করো, event_id দিয়ে duplicate বাদ দাও আর দ্রুত 2xx দাও। Delivery অন্তত একবার, সর্বোচ্চ আটটি attempt; history থেকে একই event আবার পাঠানো যায়। Endpoint edit করলে পুরোনো unsent delivery বাতিল হয়, customer data নতুন ঠিকানায় ঘুরিয়ে দেয় না। Invoice settlement মানে vendor payout শেষ নয়। বাইরের callback বলেছে বলেই অর্থ পাঠিয়ো না।

  • marketplace.invoice.created
  • marketplace.allocations.available
  • marketplace.allocations.held
  • marketplace.payout.approved
  • marketplace.payout.broadcast
  • marketplace.payout.confirmed
  • marketplace.payout.partial
  • marketplace.payout.failed
  • marketplace.payout.cancelled
  • marketplace.refund.prepared
  • marketplace.refund.confirmed
{
  "event_id": "11111111-1111-4111-8111-111111111111",
  "event_type": "marketplace.payout.confirmed",
  "payload_version": 1,
  "project_id": "YOUR_PROJECT_ID",
  "occurred_at": "2026-10-06T12:00:00Z",
  "data": {
    "payout_id": "YOUR_PAYOUT_ID",
    "asset_id": "YOUR_ASSET_ID",
    "amount_atomic": "28800000",
    "transactions": [
      {
        "transaction_id": "EXAMPLE_TRANSACTION_ID",
        "explorer_url": "https://mempool.space/tx/EXAMPLE_TRANSACTION_ID"
      }
    ]
  }
}

একাধিক বিক্রেতার পেমেন্ট সেট করো · Marketplace invoice তৈরি করো

Error ও সীমা

Validation, quota আর retry পূর্বানুমেয়ভাবে সামলাও।

HTTP status আর Content-Type পরীক্ষা করে response parse করো। যদি পাও 429, অন্তত এই Retry-After সময় অপেক্ষা করে retry করো।

সীমাবিস্তারিত
অনুরোধের হারপ্রতি-ক্রেডেনশিয়াল quota: ডিফল্ট প্রতি UTC মিনিটে ১২০ request, Settings → API-তে 1–6000 করা যায়। সব authenticated v1 read/write, idempotent retry আর authentication-এর পরের authorization/validation failure-সহ, domain, project আর process জুড়ে একই সীমা ভাগ করে। Invalid credential, console route আর public checkout এটি খরচ করে না।
Rate-limit headerAuthenticated v1 response-এ X-RateLimit-Limit, X-RateLimit-Remaining আর X-RateLimit-Reset থাকে (পরের UTC-minute boundary-র Unix second)। বাড়তি request-এ JSON 429 rate_limit_exceeded আর পূর্ণ second-এর Retry-After ফেরত আসে। অন্তত ততক্ষণ অপেক্ষা করে retry jitter যোগ করো। Fixed window মিনিটের সীমানায় burst হতে দেয়; এটি প্রতি-second request-এর নিশ্চয়তা নয়।
মার্চেন্ট bodyApplication router-এ সর্বোচ্চ 32 KiB। JSON error envelope তৈরির আগেই edge বড় request প্রত্যাখ্যান করতে পারে।
ইনভয়েসের তালিকাlimit ডিফল্ট ৫০, 1–100 গ্রহণ করে; offset 0–1,000,000 গ্রহণ করে। Search সর্বোচ্চ ১০০ অক্ষর। নতুন ফল আগে আসে, total/has_more metadata-সহ।
স্টোরের পদ্ধতিপ্রতি store-এ সর্বোচ্চ ৬৪ asset selection, ৩০টি native chain আর সীমিত verified-token catalog-এর জন্য যথেষ্ট। Project policy, scanner capability আর প্রস্তুত backed-up chain wallet এখনো invoice creation-এর শর্ত।
টোকেন খোঁজাCandidate limit ডিফল্ট ৫০, 1–100 গ্রহণ করে। On-chain verification সফল না হওয়া পর্যন্ত discovery result payment asset নয়।
প্রকল্পের নিবন্ধিত টোকেনপ্রতি project-এ সর্বোচ্চ ২০ স্থায়ী token asset। আগে নিবন্ধিত asset আর slot খরচ না করে আবার ব্যবহার করা যায়।
IdempotencyInvoice তৈরিতে বাধ্যতামূলক। ফাঁক ছাড়া 1–128 দৃশ্যমান ASCII অক্ষর; key প্রতি store-এ অনন্য, replay-তে মূল credential আর হুবহু raw body লাগবে।
Metadataশুধু JSON object, সর্বোচ্চ 4,096 encoded byte আর পাঁচ স্তরের nesting।
Callbackসর্বোচ্চ 2,048 byte-এর public HTTPS URL। Notification request body সর্বোচ্চ 256 KiB; সংরক্ষিত invoice event payload সীমিত payment history-সহ সর্বোচ্চ 64 KiB।
চেকআউট অ্যাসেটQR SVG response private আর no-store, কারণ underpayment-এ সঠিক বাকি পরিমাণ বদলায়। Revisioned PNG logo এক বছর public cache হয় আর অপরিবর্তনীয়।
API edgeManaged API upstream request-এর read timeout ৩০ সেকেন্ড। Caller-এর স্পষ্ট timeout তার job budget-এর চেয়ে কম রাখো।
Non-JSON ব্যর্থতাভুল UUID/query extraction, ভুল method আর 32 KiB length guard framework text/খালি response ফেরত দিতে পারে। অজানা /v1 path এখন 404 console HTML ফেরত দেয়; parse-এর আগে status আর Content-Type যাচাই করো।

Error রেফারেন্স

HTTPError codeঅর্থ
400invalid_reconciliation_actionException status, reason, search বা history-page filter বৈধ নয়।
500reconciliation_unavailableException queue বা evidence লোড হয়নি। Backoff দিয়ে read retry করো।
402billing_requiredপ্রতিটি নতুন invoice-এর জন্য যাচাই করা paired credit account আর live authorization লাগে। Prepaid credit কম হলে creation বা incoming payment আটকায় না: বরং IPN, webhook আর Sweep থামে, fee জমতে থাকে। Suspended account, expired/invalid billing verification, credit service-এ পৌঁছাতে না পারা বা unauthorized invoice fiat basis-এ creation বন্ধ থাকে। Fee মূল invoice fiat amount-এ হয়, crypto received, spread, overpayment বা network fee-তে নয়। Checkout তৈরির আগে সেই amount আর independent conversion নিবন্ধিত হয়। বিভ্রাটে আগের monitoring আর invoice retrieval চলে। Fund করার পরে queued notification স্বাভাবিক payload-retention সময়ে আর enabled sweep rule আবার চলে। Settings → Fees দেখো এবং failed creation একই Idempotency-Key দিয়ে retry করো।
400invalid_jsonভুল JSON, অজানা field বা documented request-এর সঙ্গে না মেলা body।
400idempotency_key_requiredCreate invoice-এ Idempotency-Key নেই।
400invalid_idempotency_keyKey খালি, ১২৮ byte-এর বেশি, non-ASCII, whitespace বা control byte আছে।
400invalid_payment_requestযাচাই করা field বা বাছাই করা active method ব্যর্থ হয়েছে। সঠিক বাধা জানতে error.message আর error.details.payment_methods (PaymentMethodIssue[]) পড়ো। SDK 2.4.0+ নিরাপদ করণীয় exception summary আর issue helper যোগ করে; পুরোনো PHP SDK-তে getApiMessage() আছে।
400invalid_invoice_statusList status ডকুমেন্ট করা ছয় invoice state-এর বাইরে।
400invalid_callback_urlকার্যকর IPN target HTTPS, public-address, DNS বা SSRF validation-এ ব্যর্থ।
400invalid_wallet_requestWallet/address preparation-এর input বৈধ নয়।
400invalid_token_assetToken chain, candidate query, CoinGecko identity, catalog metadata বা contract/mint input বৈধ নয়।
401authentication_requiredBearer token অনুপস্থিত, ভুল গঠনের, বন্ধ, বদলানো বা অজানা।
403source_ip_deniedCredential IP restriction-এ request-এর সঠিক public source address নেই।
403source_ip_not_allowedHostname-এর source IP restriction এই client বাদ দেয়। Administrator Settings → System-এ live-host allowlist পরিচালনা করতে পারে; credential IP restriction-এর পাশাপাশি এগুলোও লাগে।
503source_access_unavailableHostname access verification সাময়িকভাবে পাওয়া যাচ্ছে না। পরে চেষ্টা করো; যাচাই না হলে প্রবেশ বন্ধ থাকে।
403 / 409 / 500merchant_api_access_deniedAuthorization ব্যর্থ: permission/project scope-এ 403, disabled project/store-এ 409 আর authorization backend failure-এ 500 হতে পারে। Operator receiving wallet শুধু Operator panel-এর জন্য, পুরোনো explicit project grant থাকলেও merchant API credential বা MCP-এর জন্য নয়।
403project_access_deniedTransactional create-time recheck-এ দেখা গেছে credential-এর আর project-এ access নেই।
404invoice_not_foundঅনুমোদিত project-এ সেই public ID-এর invoice নেই, বা checkout তা প্রকাশ করতে পারছে না।
404payment_resource_not_foundInvoice তৈরিতে দরকারি project, store, asset বা wallet আর নেই।
404token_candidate_not_foundProject পাওয়া যাচ্ছে না বা token বর্তমান matched discovery catalog-এ আর নেই।
409idempotency_conflictStore-scoped key আগে থেকেই আছে এবং credential বা হুবহু raw request byte আলাদা।
409store_unavailableProject/store বন্ধ বা পাওয়া যাচ্ছে না।
409no_ready_payment_methodsকোনো store method প্রস্তুত নয়। chain_slug, asset_ticker আর reason_code-এর জন্য error.message আর error.details.payment_methods পড়ো। Wallet backup/activation, installed adapter আর pricing বৈধ হতে হবে। 6.0.6 থেকে scanner cooldown, failed বা stale health check আর provider quorum না থাকা creation আটকায় না।
409payment_method_unavailableAtomic create-time recheck-এর সময় বাছাই করা method অনুপলব্ধ হয়েছে।
409store_payment_method_not_selectedস্টোরে বর্তমানে বাছাই করা নেই এমন asset-এর জন্য store confirmation override চাওয়া হয়েছে।
409wallet_unavailableAtomic create-time recheck-এর সময় payment wallet অনুপলব্ধ হয়েছে।
409ipn_secret_requiredকার্যকর IPN URL আছে, কিন্তু store-এ IPN signing secret নেই।
409payment_resource_not_readyপ্রয়োজনীয় payment asset বা wallet বন্ধ, ব্যাকআপ হয়নি, shared-account activation proof-এর অপেক্ষায়, নিঃশেষিত বা অন্যভাবে প্রস্তুত নয়।
409account_activation_unverifiedকনফিগার করা healthy mainnet endpoint-এর সংখ্যা অনুযায়ী XRP Ledger বা Stellar account activation প্রমাণিত হয়নি (ডিফল্ট ২, চাইলে ১); সঠিক account-এ fund করে verification আবার করো।
400invalid_monero_wallet_rpcHTTPS endpoint, সঠিক mainnet primary address, label বা পূর্ণ Digest/Basic/header authentication input বৈধ নয়।
404monero_wallet_rpc_not_foundProject-scoped Monero wallet-RPC binding নেই।
409monero_wallet_rpc_not_readyMonero asset, two-daemon quorum, immutable binding বা explicit backup/view-only attestation প্রস্তুত নয়।
409monero_wallet_rpc_unavailableInvoice তৈরিতে active, verified, attested project Monero wallet-RPC binding আর বৈধ server-side credential লাগে।
503lightning_unavailableস্টোরের একমাত্র ready method Lightning এবং তার wallet বা quote যাচাই করা যায়নি। একই idempotency key দিয়ে retry করো। অন্য ready on-chain method থাকলে unavailable Lightning method বাদ দেওয়া হয়।
422monero_wallet_rpc_verification_failedসঠিক wallet, HTTPS pinning, synchronization, mainnet daemon quorum বা gateway method-denial proof ব্যর্থ।
503monero_wallet_rpc_failedবাহ্যিক watch-only wallet-RPC নিরাপদে invoice subaddress তৈরি করে আবার পড়তে পারেনি; বানানো fallback address দেওয়া হয় না।
409token_chain_not_readyNative chain asset বন্ধ, verification-এর সময় discovery mapping বদলেছে, অথবা project-এ ইতিমধ্যে বর্তমান সর্বোচ্চ ২০ registered token asset আছে।
503dex_price_unavailableDEX provider অনুপলব্ধ, ব্যস্ত, rate-limited, response পুরোনো বা data ভুল গঠনের। এক মিনিট পরে retry করো; fixed pricing ব্যবহার করা যায়।
422invalid_dex_pricePrice-mode combination বৈধ নয় বা বাছাই করা pool সঠিক contract-এর উপযুক্ত price দিতে পারে না। অন্য pool বা fixed USD pricing বেছে নাও।
422token_verification_failedসব eligible node chain identity, contract code, decimal, balance-query বা mint verification-এ ব্যর্থ।
422invalid_store_confirmation_policyএই finality mode-এ store override নেই, ফেরত আসা chain-aware সীমার বাইরে বা unsupported zero-confirmation acceptance চাওয়া হয়েছে।
409invoice_not_payableCheckout invoice চূড়ান্ত অবস্থায় বা payment deadline পেরিয়ে গেছে।
409invoice_payment_method_lockedবৈধ পেমেন্ট ইতিমধ্যে অন্য asset বেছে নিয়েছে; active_payment_method_id দিয়ে চালিয়ে যাও।
409payment_method_not_payableবাছাই করা method সম্পূর্ণ বা আর পেমেন্ট নেয় না।
422payment_qr_unavailableCheckout payment request SVG QR image-এ ধরার জন্য অতিরিক্ত বড়।
503payment_rates_unavailableকোনো ready payment method-এর নতুন বিশ্বস্ত quote পাওয়া যাচ্ছে না।
500authentication_unavailableBearer authentication নিরাপদে সংরক্ষিত credential পড়তে বা যাচাই করতে পারেনি।
429rate_limit_exceededএই credential-এর বর্তমান UTC-minute quota শেষ। অন্তত Retry-After second অপেক্ষা করো; একই idempotency key দিয়ে invoice creation retry করো।
500database_error / internal_errorসাময়িক server-side ব্যর্থতা; একই idempotency key দিয়ে নিরাপদে retry করো।

API-এর সংক্ষিপ্ত পরিচয়

Field, উদাহরণ আর response দেখতে endpoint বেছে নাও।

ইনভয়েস

POSTইনভয়েস তৈরি করো/v1/projects/{project_id}/stores/{store_id}/invoicesGETইনভয়েসের তালিকা/v1/projects/{project_id}/invoicesGETইনভয়েস পড়ো/v1/projects/{project_id}/invoices/{invoice_id}GETইনভয়েসের পেমেন্ট তালিকা/v1/projects/{project_id}/invoices/{invoice_id}/payments

পেমেন্ট পদ্ধতি

GETপ্রকল্পের পেমেন্ট অ্যাসেটের তালিকা/v1/projects/{project_id}/payment-assetsPUTপ্রকল্পের অ্যাসেট নীতি বদলাও/v1/projects/{project_id}/payment-assets/{asset_id}GETসম্ভাব্য পেমেন্ট টোকেন দেখো/v1/projects/{project_id}/payment-token-candidatesPOSTটোকেন যাচাই ও নিবন্ধন করো/v1/projects/{project_id}/payment-token-assetsGETকাস্টম টোকেনের DEX pool খোঁজো/v1/projects/{project_id}/payment-token-dex-poolsPOSTকাস্টম টোকেন যোগ করো বা দাম বদলাও/v1/projects/{project_id}/payment-token-assets/customGETস্টোরের পেমেন্ট পদ্ধতির তালিকা/v1/projects/{project_id}/stores/{store_id}/payment-assetsPUTস্টোরের পেমেন্ট পদ্ধতি প্রতিস্থাপন করো/v1/projects/{project_id}/stores/{store_id}/payment-assetsPUTস্টোরের confirmation policy সেট করো/v1/projects/{project_id}/stores/{store_id}/payment-assets/{asset_id}/confirmation-policy

ওয়ালেট

GETপ্রকল্পের ওয়ালেট আর ব্যালান্সের তালিকা/v1/projects/{project_id}/wallets

হিসাব মেলানো

GETপেমেন্টের ব্যতিক্রমের তালিকা/v1/projects/{project_id}/reconciliationGETহিসাব মেলানোর প্রমাণ পড়ো/v1/projects/{project_id}/reconciliation/{invoice_id}

Marketplace API

GETসক্ষমতা/v1/marketplace/capabilitiesGETমার্কেটপ্লেস রিপোর্ট/v1/marketplace/overviewGETপ্রকল্পের সেটিংস/v1/marketplace/settingsPOSTপ্রকল্পের সেটিংস সেভ করো/v1/marketplace/settingsGETবিক্রেতার তালিকা/v1/marketplace/vendorsPOSTবিক্রেতা তৈরি করো/v1/marketplace/vendorsGETবিক্রেতার তথ্য নাও/v1/marketplace/vendors/{vendor_id}POSTবিক্রেতা আপডেট করো/v1/marketplace/vendors/{vendor_id}/updatePOSTবিক্রেতা আর্কাইভ করো/v1/marketplace/vendors/{vendor_id}/archiveGETবিক্রেতার গন্তব্য/v1/marketplace/vendors/{vendor_id}/destinationsPOSTপেআউটের গন্তব্য যোগ করো/v1/marketplace/vendors/{vendor_id}/destinationsPOSTগন্তব্য অনুমোদন করো/v1/marketplace/vendors/{vendor_id}/destinations/{destination_id}/approvePOSTগন্তব্য বন্ধ করো/v1/marketplace/vendors/{vendor_id}/destinations/{destination_id}/disableGETবিক্রেতার ব্যালান্স/v1/marketplace/vendors/{vendor_id}/balancesGETমার্কেটপ্লেসের ইনভয়েস/v1/marketplace/invoicesPOSTএকাধিক বিক্রেতার ইনভয়েস তৈরি করো/v1/marketplace/invoicesGETইনভয়েস আর বণ্টন/v1/marketplace/invoices/{invoice_id}GETইনভয়েস পেমেন্টের প্রমাণ/v1/marketplace/invoices/{invoice_id}/paymentsGETইনভয়েসের বণ্টন/v1/marketplace/invoices/{invoice_id}/allocationsPOSTঅপরিশোধিত ইনভয়েস বাতিল করো/v1/marketplace/invoices/{invoice_id}/cancelPOSTবণ্টন আটকে রাখো/v1/marketplace/invoices/{invoice_id}/allocations/holdPOSTবণ্টন পর্যালোচনা করে ছাড়ো/v1/marketplace/invoices/{invoice_id}/allocations/releasePOSTঅপরিশোধিত অংশের গন্তব্য আবার যুক্ত করো/v1/marketplace/invoices/{invoice_id}/allocations/{allocation_id}/destinationPOSTপূর্ণ রিফান্ড প্রস্তুত করো/v1/marketplace/invoices/{invoice_id}/refundGETপেআউটের বণ্টন খোঁজো/v1/marketplace/allocationsGETপ্রকল্পের ledger balance/v1/marketplace/balancesGETঅপরিবর্তনীয় journal/v1/marketplace/ledgerGETপেআউটের ইতিহাস/v1/marketplace/payoutsPOSTবণ্টন পরিকল্পনার preview/v1/marketplace/payouts/previewPOSTপেআউট প্রস্তুত করো/v1/marketplace/payoutsGETপেআউটের বিস্তারিত/v1/marketplace/payouts/{payout_id}POSTঅনুমোদন করে পাঠাও/v1/marketplace/payouts/{payout_id}/approvePOSTপেআউট পর্যালোচনা করে আবার চালাও/v1/marketplace/payouts/{payout_id}/resumePOSTস্বাক্ষর না করা কাজ বাতিল করো/v1/marketplace/payouts/{payout_id}/cancelGETস্বয়ংক্রিয় পেআউট নীতি/v1/marketplace/policiesPOSTপেআউট নীতির অনুমতি দাও/v1/marketplace/policiesGETমার্কেটপ্লেসের webhook/v1/marketplace/webhooksPOSTমার্কেটপ্লেস webhook তৈরি করো/v1/marketplace/webhooksPOSTমার্কেটপ্লেস webhook আপডেট করো/v1/marketplace/webhooks/{webhook_id}/updatePOSTমার্কেটপ্লেস webhook বন্ধ করো/v1/marketplace/webhooks/{webhook_id}/disableGETমার্কেটপ্লেসের event/v1/marketplace/eventsGETসংরক্ষিত event পড়ো/v1/marketplace/events/{event_id}GETমার্কেটপ্লেসের delivery history/v1/marketplace/webhook-deliveriesGETDelivery-এর বিস্তারিত/v1/marketplace/webhook-deliveries/{delivery_id}POSTএকই event আবার পাঠাও/v1/marketplace/webhook-deliveries/{delivery_id}/resend

অপারেটর API

GETসক্ষমতা/v1/operator/capabilitiesGETসিস্টেমের অবস্থা/v1/operator/healthGETমার্চেন্টের তালিকা/v1/operator/merchantsPOSTমার্চেন্ট তৈরি করো/v1/operator/merchantsGETমার্চেন্টের তথ্য নাও/v1/operator/merchants/{merchant_id}POSTমার্চেন্ট আপডেট করো/v1/operator/merchants/{merchant_id}GETব্যবহারকারীর তালিকা/v1/operator/merchants/{merchant_id}/usersPOSTব্যবহারকারী তৈরি করো/v1/operator/merchants/{merchant_id}/usersGETব্যবহারকারীর তথ্য নাও/v1/operator/merchants/{merchant_id}/users/{user_id}POSTব্যবহারকারী আপডেট করো/v1/operator/merchants/{merchant_id}/users/{user_id}POSTব্যবহারকারীর পাসওয়ার্ড সেট করো/v1/operator/merchants/{merchant_id}/users/{user_id}/passwordPOSTব্যবহারকারীর session বাতিল করো/v1/operator/merchants/{merchant_id}/users/{user_id}/revoke-sessionsGETআমন্ত্রণের তালিকা/v1/operator/merchants/{merchant_id}/invitationsPOSTআমন্ত্রণ তৈরি করো/v1/operator/merchants/{merchant_id}/invitationsGETআমন্ত্রণের তথ্য নাও/v1/operator/invitations/{invitation_id}POSTআমন্ত্রণ আবার পাঠাও/v1/operator/invitations/{invitation_id}/resendPOSTআমন্ত্রণ বাতিল করো/v1/operator/invitations/{invitation_id}/revokeGETক্রেডিটের তথ্য নাও/v1/operator/merchants/{merchant_id}/creditsGETক্রেডিট ledger-এর তালিকা/v1/operator/merchants/{merchant_id}/credits/ledgerPOSTক্রেডিট সমন্বয় করো/v1/operator/merchants/{merchant_id}/credits/adjustmentsGETটপ-আপের তালিকা/v1/operator/merchants/{merchant_id}/topupsPOSTটপ-আপ তৈরি করো/v1/operator/merchants/{merchant_id}/topupsGETটপ-আপের তথ্য নাও/v1/operator/merchants/{merchant_id}/topups/{topup_id}GETরিপোর্ট/v1/operator/reportsGETঅডিট তালিকা/v1/operator/auditGETEvent তালিকা/v1/operator/eventsGETWebhook তালিকা/v1/operator/webhooksPOSTWebhook তৈরি করো/v1/operator/webhooksPOSTWebhook আপডেট করো/v1/operator/webhooks/{webhook_id}POSTWebhook secret বদলাও/v1/operator/webhooks/{webhook_id}/rotateGETWebhook delivery-এর তালিকা/v1/operator/webhooks/{webhook_id}/deliveriesGETপ্রকল্পের তালিকা/v1/operator/merchants/{merchant_id}/projectsPOSTপ্রকল্প তৈরি করো/v1/operator/merchants/{merchant_id}/projectsGETপ্রকল্পের তথ্য নাও/v1/operator/merchants/{merchant_id}/projects/{project_id}POSTপ্রকল্প আপডেট করো/v1/operator/merchants/{merchant_id}/projects/{project_id}GETস্টোরের তালিকা/v1/operator/merchants/{merchant_id}/projects/{project_id}/storesPOSTস্টোর তৈরি করো/v1/operator/merchants/{merchant_id}/projects/{project_id}/storesGETস্টোরের তথ্য নাও/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}POSTস্টোর আপডেট করো/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}GETস্টোরের ডিজাইন পড়ো/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/checkout-appearancePOSTস্টোরের ডিজাইন বদলাও/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/checkout-appearanceGETস্টোরের পেমেন্ট অ্যাসেটের তালিকা/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/payment-assetsPOSTস্টোরের পেমেন্ট অ্যাসেট বদলাও/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/payment-assetsGETস্টোরের webhook তালিকা/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/webhooksPOSTস্টোরের webhook তৈরি করো/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/webhooksPOSTস্টোরের webhook আপডেট করো/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/webhooks/{webhook_id}GETইনভয়েস তালিকা/v1/operator/merchants/{merchant_id}/projects/{project_id}/invoicesGETইনভয়েসের তথ্য নাও/v1/operator/merchants/{merchant_id}/projects/{project_id}/invoices/{invoice_id}GETওয়ালেট তালিকা/v1/operator/merchants/{merchant_id}/projects/{project_id}/walletsGETওয়ালেটের ঠিকানার তালিকা/v1/operator/merchants/{merchant_id}/projects/{project_id}/wallets/{wallet_id}/addressesGETমার্চেন্ট ক্রেডেনশিয়ালের তালিকা/v1/operator/merchants/{merchant_id}/api-credentialsPOSTমার্চেন্ট ক্রেডেনশিয়াল তৈরি করো/v1/operator/merchants/{merchant_id}/api-credentialsPOSTমার্চেন্ট ক্রেডেনশিয়াল আপডেট করো/v1/operator/merchants/{merchant_id}/api-credentials/{credential_id}POSTমার্চেন্ট ক্রেডেনশিয়াল ঘোরাও/v1/operator/merchants/{merchant_id}/api-credentials/{credential_id}/rotatePOSTমার্চেন্ট ক্রেডেনশিয়াল বাতিল করো/v1/operator/merchants/{merchant_id}/api-credentials/{credential_id}/revokePOSTআমন্ত্রণের token পরীক্ষা করো/v1/onboarding/invitations/checkPOSTআমন্ত্রণ বা পাসওয়ার্ড reset গ্রহণ করো/v1/onboarding/invitations/accept

চেকআউট

GETচেকআউটের কাঠামো/GETহোস্টেড চেকআউট পৃষ্ঠা/invoice/{invoice_id}GETচেকআউটে দেখানোর নিরাপদ ইনভয়েস/checkout-api/invoices/{invoice_id}GETস্টোর চেকআউটের preview/invoice/preview/{project_id}GETচেকআউট preview-এর ডেটা/checkout-api/previews/{project_id}GETস্টোর চেকআউটের ছবি/checkout-api/invoices/{invoice_id}/appearance-images/{kind}/{revision}/image.pngGETস্টোর preview-এর ছবি/checkout-api/previews/{project_id}/stores/{store_id}/appearance-images/{kind}/{revision}/image.pngGETসংস্করণযুক্ত preview লোগো/checkout-api/previews/{project_id}/logo/{revision}/image.pngGETপেমেন্ট QR ছবি/checkout-api/invoices/{invoice_id}/payment-methods/{intent_id}/qr.svgGETসংস্করণযুক্ত চেকআউট লোগো/checkout-api/invoices/{invoice_id}/logo/{revision}/image.png

পরিষেবা

GETAPI পরিষেবা আবিষ্কার/GETপরিষেবার অবস্থা/healthz
GETসক্ষমতা/v1/operator/capabilitiesশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/capabilities" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "api_version": "v1",
  "operator_version": "7.4.0",
  "scopes": [
    "health.read"
  ],
  "all_merchants": false,
  "merchant_ids": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "onboarding": [
    "direct",
    "invitation"
  ],
  "write_methods": [
    "POST"
  ],
  "idempotency_required": true
}

Response field

api_versionstring
operator_versionstring
scopes[]array
all_merchantsboolean
merchant_ids[]array
onboarding[]array
write_methods[]array
idempotency_requiredboolean
ব্যবহারের নোট
  • health.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETসিস্টেমের অবস্থা/v1/operator/healthশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/health" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "version": "7.4.0",
  "nodes": []
}

Response field

versionstring
nodes[]array
ব্যবহারের নোট
  • health.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETমার্চেন্টের তালিকা/v1/operator/merchantsশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Query parameter

pageঐচ্ছিক
পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।বিস্তারিত

পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Response field

data[]array
pageinteger
page_sizeinteger
totalinteger
ব্যবহারের নোট
  • merchants.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTমার্চেন্ট তৈরি করো/v1/operator/merchantsপড়া + লেখা

সরাসরি password দিয়ে বা invitation-এ একসঙ্গে hosted merchant আর প্রথম administrator তৈরি করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Example shop",
  "email": "admin@example.test",
  "onboarding": "direct",
  "password": "REPLACE_WITH_A_UNIQUE_TEMPORARY_PASSWORD",
  "require_password_change": true,
  "currency": "EUR",
  "starting_credit": "0",
  "external_id": "customer-1042"
}'

Request body

namestringবাধ্যতামূলক

Merchant name আর সর্বত্র অনন্য প্রথম-admin email।

emailstringবাধ্যতামূলক

Merchant name আর সর্বত্র অনন্য প্রথম-admin email।

onboardingdirect | invitationবাধ্যতামূলক

direct-এ password লাগে, invitation email পাঠায় না। invitation-এ password বাদ দাও।

passwordstring · direct only

12–128 অক্ষর (সর্বোচ্চ 512 UTF-8 byte); কখনো ফেরত দেওয়া বা email করা হয় না। Temporary password-এ require_password_change ব্যবহার করো।

require_password_changebooleanঐচ্ছিক

প্রথম login-এ নতুন password লাগে। সরাসরি তৈরি প্রতিটি account-কে hosted wallet custody স্বীকার করতে হয়।

currencyfiat codeঐচ্ছিক

Prepaid account currency; ডিফল্ট regional currency এবং পরে বদলানো যায় না।

fee_bpsintegerঐচ্ছিক

0–10000; 100 মানে 1%। না দিলে operator default। fees.write লাগে।

starting_creditdecimal stringঐচ্ছিক

সঠিক একবারের local grant। শূন্যের বেশি হলে credits.write লাগে। Operator-এর installation balance ভরে না।

external_idstringঐচ্ছিক

অনন্য integration reference, 1–120 অক্ষর।

default_timezoneIANA timezoneঐচ্ছিক

ডিফল্ট installation-এর regional timezone।

send_invitation_emailbooleanঐচ্ছিক

শুধু invitation। Configured SMTP লাগে; response relay acceptance আর account creation আলাদা করে।

উত্তর 201 or 200 application/json

উদাহরণ response
{
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "user_id": "22222222-2222-4222-8222-222222222222",
  "merchant": {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "Example shop",
    "currency": "EUR",
    "balance": "0"
  },
  "onboarding": "direct",
  "access_link": null,
  "email_delivery": {
    "status": "not_requested"
  },
  "custody_acceptance_required": true
}

Response field

merchant_idstring
user_idstring
merchantobject
idstring
namestring
currencystring
balancestring
onboardingstring
email_deliveryobject
statusstring
custody_acceptance_requiredboolean
ব্যবহারের নোট
  • merchants.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Global merchant access লাগে। Explicit fee override-এ fees.write-ও লাগে; শূন্যের বেশি starting_credit-এ credits.write লাগে। Invitation onboarding-এ invitations.write-ও লাগে। Automatic login, Basic Auth bypass বা retry-তে পেছনের credit যোগ হয় না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETমার্চেন্টের তথ্য নাও/v1/operator/merchants/{merchant_id}শুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Example shop",
  "currency": "EUR",
  "balance": "10",
  "fee_bps": 300,
  "enabled": true,
  "payments_paused": false,
  "external_id": "customer-1042"
}

Response field

idstring
namestring
currencystring
balancestring
fee_bpsinteger
enabledboolean
payments_pausedboolean
external_idstring
ব্যবহারের নোট
  • merchants.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTমার্চেন্ট আপডেট করো/v1/operator/merchants/{merchant_id}পড়া + লেখা

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "payments_paused": true
}'

Request body

namefieldsঐচ্ছিক
বন্ধ করলে session বাতিল হয়। payments_paused নতুন invoice আটকায়, আগের payment scanning নয়। Fee edit-এ fees.write লাগে এবং ভবিষ্যৎ invoice-এ লাগে; account currency বদলায় না।বিস্তারিত

বন্ধ করলে session বাতিল হয়। payments_paused নতুন invoice আটকায়, আগের payment scanning নয়। Fee edit-এ fees.write লাগে এবং ভবিষ্যৎ invoice-এ লাগে; account currency বদলায় না।

enabledfieldsঐচ্ছিক
বন্ধ করলে session বাতিল হয়। payments_paused নতুন invoice আটকায়, আগের payment scanning নয়। Fee edit-এ fees.write লাগে এবং ভবিষ্যৎ invoice-এ লাগে; account currency বদলায় না।বিস্তারিত

বন্ধ করলে session বাতিল হয়। payments_paused নতুন invoice আটকায়, আগের payment scanning নয়। Fee edit-এ fees.write লাগে এবং ভবিষ্যৎ invoice-এ লাগে; account currency বদলায় না।

payments_pausedfieldsঐচ্ছিক
বন্ধ করলে session বাতিল হয়। payments_paused নতুন invoice আটকায়, আগের payment scanning নয়। Fee edit-এ fees.write লাগে এবং ভবিষ্যৎ invoice-এ লাগে; account currency বদলায় না।বিস্তারিত

বন্ধ করলে session বাতিল হয়। payments_paused নতুন invoice আটকায়, আগের payment scanning নয়। Fee edit-এ fees.write লাগে এবং ভবিষ্যৎ invoice-এ লাগে; account currency বদলায় না।

fee_bpsfieldsঐচ্ছিক
বন্ধ করলে session বাতিল হয়। payments_paused নতুন invoice আটকায়, আগের payment scanning নয়। Fee edit-এ fees.write লাগে এবং ভবিষ্যৎ invoice-এ লাগে; account currency বদলায় না।বিস্তারিত

বন্ধ করলে session বাতিল হয়। payments_paused নতুন invoice আটকায়, আগের payment scanning নয়। Fee edit-এ fees.write লাগে এবং ভবিষ্যৎ invoice-এ লাগে; account currency বদলায় না।

external_idfieldsঐচ্ছিক
বন্ধ করলে session বাতিল হয়। payments_paused নতুন invoice আটকায়, আগের payment scanning নয়। Fee edit-এ fees.write লাগে এবং ভবিষ্যৎ invoice-এ লাগে; account currency বদলায় না।বিস্তারিত

বন্ধ করলে session বাতিল হয়। payments_paused নতুন invoice আটকায়, আগের payment scanning নয়। Fee edit-এ fees.write লাগে এবং ভবিষ্যৎ invoice-এ লাগে; account currency বদলায় না।

উত্তর 200 application/json

উদাহরণ response
{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Example shop",
  "currency": "EUR",
  "balance": "10",
  "fee_bps": 300,
  "enabled": true,
  "payments_paused": false
}

Response field

idstring
namestring
currencystring
balancestring
fee_bpsinteger
enabledboolean
payments_pausedboolean
ব্যবহারের নোট
  • merchants.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETব্যবহারকারীর তালিকা/v1/operator/merchants/{merchant_id}/usersশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

Query parameter

pageঐচ্ছিক
পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।বিস্তারিত

পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Response field

data[]array
pageinteger
page_sizeinteger
totalinteger
ব্যবহারের নোট
  • users.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTব্যবহারকারী তৈরি করো/v1/operator/merchants/{merchant_id}/usersপড়া + লেখা

Merchant administrator বা বাছাই করা project-এ সীমিত user যোগ করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "email": "staff@example.test",
  "display_name": "Store team",
  "onboarding": "invitation",
  "access_level": "projects",
  "project_ids": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "send_invitation_email": false
}'

Request body

emailstringsবাধ্যতামূলক

Email পুরো installation-এ অনন্য।

display_namestringsবাধ্যতামূলক

Email পুরো installation-এ অনন্য।

onboardingsame as merchant creation

Invitation তৈরিতে invitations.write-ও লাগে।

passwordsame as merchant creation

Invitation তৈরিতে invitations.write-ও লাগে।

require_password_changesame as merchant creation

Invitation তৈরিতে invitations.write-ও লাগে।

send_invitation_emailsame as merchant creation

Invitation তৈরিতে invitations.write-ও লাগে।

access_leveladmin | projectsঐচ্ছিক

admin শুধু এই merchant-এর administrator, কখনো installation/operator administrator নয়।

project_ids[]UUID[]

শুধু merchant-এর project। Project-restricted access-এ selection লাগবে; কখনো অন্য tenant নয়।

default_timezoneIANA timezoneঐচ্ছিক

না দিলে regional default।

উত্তর 201 or 200 application/json

উদাহরণ response
{
  "user": {
    "id": "22222222-2222-4222-8222-222222222222",
    "merchant_id": "11111111-1111-4111-8111-111111111111",
    "email": "admin@example.test",
    "display_name": "Shop administrator",
    "access_level": "admin",
    "project_ids": [],
    "enabled": true,
    "password_setup_required": false,
    "custody_acceptance_required": true,
    "password_change_required": true
  },
  "user_id": "22222222-2222-4222-8222-222222222222",
  "access_link": null,
  "email_delivery": {
    "status": "not_requested"
  },
  "merchant_id": "11111111-1111-4111-8111-111111111111"
}

Response field

userobject
idstring
merchant_idstring
emailstring
display_namestring
access_levelstring
project_ids[]array
enabledboolean
password_setup_requiredboolean
custody_acceptance_requiredboolean
password_change_requiredboolean
user_idstring
email_deliveryobject
statusstring
merchant_idstring
ব্যবহারের নোট
  • users.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETব্যবহারকারীর তথ্য নাও/v1/operator/merchants/{merchant_id}/users/{user_id}শুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

user_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "id": "22222222-2222-4222-8222-222222222222",
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "email": "admin@example.test",
  "display_name": "Shop administrator",
  "access_level": "admin",
  "project_ids": [],
  "enabled": true,
  "password_setup_required": false,
  "custody_acceptance_required": true,
  "password_change_required": true
}

Response field

idstring
merchant_idstring
emailstring
display_namestring
access_levelstring
project_ids[]array
enabledboolean
password_setup_requiredboolean
custody_acceptance_requiredboolean
password_change_requiredboolean
ব্যবহারের নোট
  • users.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTব্যবহারকারী আপডেট করো/v1/operator/merchants/{merchant_id}/users/{user_id}পড়া + লেখা

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

user_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "display_name": "Store manager"
}'

Request body

emailfieldsঐচ্ছিক

দেওয়া field আপডেট করে; last-admin protection থাকে। Password-এর আলাদা users.security operation আছে।

display_namefieldsঐচ্ছিক

দেওয়া field আপডেট করে; last-admin protection থাকে। Password-এর আলাদা users.security operation আছে।

enabledfieldsঐচ্ছিক

দেওয়া field আপডেট করে; last-admin protection থাকে। Password-এর আলাদা users.security operation আছে।

access_levelfieldsঐচ্ছিক

দেওয়া field আপডেট করে; last-admin protection থাকে। Password-এর আলাদা users.security operation আছে।

project_idsfieldsঐচ্ছিক

দেওয়া field আপডেট করে; last-admin protection থাকে। Password-এর আলাদা users.security operation আছে।

default_timezonefieldsঐচ্ছিক

দেওয়া field আপডেট করে; last-admin protection থাকে। Password-এর আলাদা users.security operation আছে।

উত্তর 200 application/json

উদাহরণ response
{
  "id": "22222222-2222-4222-8222-222222222222",
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "email": "admin@example.test",
  "display_name": "Shop administrator",
  "access_level": "admin",
  "project_ids": [],
  "enabled": true,
  "password_setup_required": false,
  "custody_acceptance_required": true,
  "password_change_required": true
}

Response field

idstring
merchant_idstring
emailstring
display_namestring
access_levelstring
project_ids[]array
enabledboolean
password_setup_requiredboolean
custody_acceptance_requiredboolean
password_change_requiredboolean
ব্যবহারের নোট
  • users.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTব্যবহারকারীর পাসওয়ার্ড সেট করো/v1/operator/merchants/{merchant_id}/users/{user_id}/passwordপড়া + লেখা

Hosted account-এর password সেট করে session বাতিল করো। আগের TOTP থাকে।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

user_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID/password" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "password": "REPLACE_WITH_A_NEW_UNIQUE_PASSWORD",
  "require_password_change": true
}'

Request body

passwordstringবাধ্যতামূলক

TOTP রেখে password বদলায় আর session বাতিল করে। users.security লাগে।

require_password_changebooleanঐচ্ছিক

পরের সফল login-এ user-কে নিজের password সেট করতে হবে।

উত্তর 200 application/json

উদাহরণ response
{
  "user_id": "11111111-1111-4111-8111-111111111111",
  "sessions_revoked": true,
  "totp_preserved": true
}

Response field

user_idstring
sessions_revokedboolean
totp_preservedboolean
ব্যবহারের নোট
  • users.security লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTব্যবহারকারীর session বাতিল করো/v1/operator/merchants/{merchant_id}/users/{user_id}/revoke-sessionsপড়া + লেখা

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

user_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID/revoke-sessions" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{}'

উত্তর 200 application/json

উদাহরণ response
{
  "user_id": "11111111-1111-4111-8111-111111111111",
  "sessions_revoked": true,
  "totp_preserved": true
}

Response field

user_idstring
sessions_revokedboolean
totp_preservedboolean
ব্যবহারের নোট
  • users.security লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETআমন্ত্রণের তালিকা/v1/operator/merchants/{merchant_id}/invitationsশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

Query parameter

pageঐচ্ছিক
পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।বিস্তারিত

পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/invitations" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Response field

data[]array
pageinteger
page_sizeinteger
totalinteger
ব্যবহারের নোট
  • invitations.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTআমন্ত্রণ তৈরি করো/v1/operator/merchants/{merchant_id}/invitationsপড়া + লেখা

একবার ব্যবহারযোগ্য invitation বা password-reset link তৈরি বা প্রতিস্থাপন করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/invitations" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "user_id": "11111111-1111-4111-8111-111111111111",
  "send_email": false
}'

Request body

user_idUUID, boolean

আগের account-এর জন্য একবার ব্যবহারযোগ্য link ইস্যু/প্রতিস্থাপন করো। সক্রিয় user এক ঘণ্টার reset link পায় এবং users.security লাগে।

send_emailUUID, boolean

আগের account-এর জন্য একবার ব্যবহারযোগ্য link ইস্যু/প্রতিস্থাপন করো। সক্রিয় user এক ঘণ্টার reset link পায় এবং users.security লাগে।

new user fieldsalternative to user_id

আমন্ত্রিত user তৈরিতে email, display_name, access_level আর project_ids ব্যবহার করো; users.write লাগে।

উত্তর 201 or 200 application/json

উদাহরণ response
{
  "user_id": "22222222-2222-4222-8222-222222222222",
  "email": "admin@example.test",
  "kind": "invitation",
  "expires_at": "2026-10-03T12:00:00Z",
  "url": "https://merchant.example.com/account-access.html#token=YOUR_PRIVATE_INVITATION_TOKEN"
}

Response field

user_idstring
emailstring
kindstring
expires_atstring
urlstring
ব্যবহারের নোট
  • invitations.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETআমন্ত্রণের তথ্য নাও/v1/operator/invitations/{invitation_id}শুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

invitation_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "id": "44444444-4444-4444-8444-444444444444",
  "user_id": "22222222-2222-4222-8222-222222222222",
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "kind": "invitation",
  "status": "pending",
  "created_at": "2026-10-01T12:00:00Z",
  "expires_at": "2026-10-03T12:00:00Z"
}

Response field

idstring
user_idstring
merchant_idstring
kindstring
statusstring
created_atstring
expires_atstring
ব্যবহারের নোট
  • invitations.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTআমন্ত্রণ আবার পাঠাও/v1/operator/invitations/{invitation_id}/resendপড়া + লেখা

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

invitation_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID/resend" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "send_email": false
}'

Request body

send_emailbooleanঐচ্ছিক

আগের token প্রতিস্থাপন করে, credit যোগ করে না। নতুন link একবার ফেরত দেয়। আগে সক্রিয় account-এ users.security লাগে।

উত্তর 200 application/json

উদাহরণ response
{
  "user_id": "22222222-2222-4222-8222-222222222222",
  "email": "admin@example.test",
  "kind": "invitation",
  "expires_at": "2026-10-03T12:00:00Z",
  "url": "https://merchant.example.com/account-access.html#token=YOUR_PRIVATE_INVITATION_TOKEN"
}

Response field

user_idstring
emailstring
kindstring
expires_atstring
urlstring
ব্যবহারের নোট
  • invitations.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTআমন্ত্রণ বাতিল করো/v1/operator/invitations/{invitation_id}/revokeপড়া + লেখা

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

invitation_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID/revoke" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{}'

উত্তর 200 application/json

উদাহরণ response
{
  "revoked": true,
  "invitation_id": "44444444-4444-4444-8444-444444444444"
}

Response field

revokedboolean
invitation_idstring
ব্যবহারের নোট
  • invitations.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETক্রেডিটের তথ্য নাও/v1/operator/merchants/{merchant_id}/creditsশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Example shop",
  "currency": "EUR",
  "balance": "10",
  "fee_bps": 300,
  "enabled": true,
  "payments_paused": false,
  "external_id": "customer-1042"
}

Response field

idstring
namestring
currencystring
balancestring
fee_bpsinteger
enabledboolean
payments_pausedboolean
external_idstring
ব্যবহারের নোট
  • credits.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETক্রেডিট ledger-এর তালিকা/v1/operator/merchants/{merchant_id}/credits/ledgerশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

Query parameter

pageঐচ্ছিক
পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।বিস্তারিত

পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।

qঐচ্ছিক
পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।বিস্তারিত

পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits/ledger" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Response field

data[]array
pageinteger
page_sizeinteger
totalinteger
ব্যবহারের নোট
  • credits.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTক্রেডিট সমন্বয় করো/v1/operator/merchants/{merchant_id}/credits/adjustmentsপড়া + লেখা

এই merchant-এর prepaid ledger-এ কারণসহ grant বা correction যোগ করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits/adjustments" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "amount": "10.00",
  "note": "Promotional credit",
  "request_id": "11111111-1111-4111-8111-111111111111"
}'

Request body

amountsigned decimal stringবাধ্যতামূলক

Merchant credit currency-তে positive grant বা negative correction, সর্বোচ্চ ছয় decimal। On-chain transfer নয়।

notestringবাধ্যতামূলক

শুধু যোগ করা যায় এমন ledger-এ কারণ থাকে।

request_idUUIDবাধ্যতামূলক

HTTP Idempotency-Key-এর পাশাপাশি amount আর reason-সহ স্থায়ীভাবে রাখো।

উত্তর 200 application/json

উদাহরণ response
{
  "balance": "25"
}

Response field

balancestring
ব্যবহারের নোট
  • credits.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETটপ-আপের তালিকা/v1/operator/merchants/{merchant_id}/topupsশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

Query parameter

pageঐচ্ছিক
পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।বিস্তারিত

পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Response field

data[]array
pageinteger
page_sizeinteger
totalinteger
ব্যবহারের নোট
  • topups.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTটপ-আপ তৈরি করো/v1/operator/merchants/{merchant_id}/topupsপড়া + লেখা

Prepaid credit-এর checkout তৈরি করো; কখনো ম্যানুয়ালি paid চিহ্নিত কোরো না।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "amount": "25.00",
  "request_id": "11111111-1111-4111-8111-111111111111"
}'

Request body

amountdecimal stringবাধ্যতামূলক

Merchant credit currency-র অন্তত এক unit। Ready Operator receiving store লাগে।

request_idUUIDবাধ্যতামূলক

Retry জুড়ে একইটি রাখো। আগে তৈরি হলে সেই invoice ফেরত দেয়। Settlement দেখা গেলেই credit যোগ হয়।

উত্তর 201 or 200 application/json

উদাহরণ response
{
  "id": "44444444-4444-4444-8444-444444444444",
  "invoice_id": "33333333-3333-4333-8333-333333333333",
  "checkout_url": "https://pay.example.com/invoice/33333333-3333-4333-8333-333333333333"
}

Response field

idstring
invoice_idstring
checkout_urlstring
ব্যবহারের নোট
  • topups.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETটপ-আপের তথ্য নাও/v1/operator/merchants/{merchant_id}/topups/{topup_id}শুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

topup_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups/YOUR_TOPUP_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "id": "44444444-4444-4444-8444-444444444444",
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "invoice_id": "33333333-3333-4333-8333-333333333333",
  "amount": "25",
  "currency": "EUR",
  "status": "pending",
  "invoice_status": "new",
  "checkout_url": "https://pay.example.com/invoice/33333333-3333-4333-8333-333333333333"
}

Response field

idstring
merchant_idstring
invoice_idstring
amountstring
currencystring
statusstring
invoice_statusstring
checkout_urlstring
ব্যবহারের নোট
  • topups.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETরিপোর্ট/v1/operator/reportsশুধু পড়া

Operator-এর আর্থিক সংক্ষিপ্তসার পড়ো। সব hosted merchant-এ access লাগে।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Query parameter

periodঐচ্ছিক

Finance filter। period ডিফল্ট last30; YYYY-MM-DD start/end-সহ custom ব্যবহার করো। শুধু all-merchant credential।

startঐচ্ছিক

Finance filter। period ডিফল্ট last30; YYYY-MM-DD start/end-সহ custom ব্যবহার করো। শুধু all-merchant credential।

endঐচ্ছিক

Finance filter। period ডিফল্ট last30; YYYY-MM-DD start/end-সহ custom ব্যবহার করো। শুধু all-merchant credential।

currencyঐচ্ছিক

Finance filter। period ডিফল্ট last30; YYYY-MM-DD start/end-সহ custom ব্যবহার করো। শুধু all-merchant credential।

merchant_idঐচ্ছিক

Finance filter। period ডিফল্ট last30; YYYY-MM-DD start/end-সহ custom ব্যবহার করো। শুধু all-merchant credential।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/reports" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "summary": {
    "fees": "10",
    "costs": "3",
    "margin": "7",
    "credits": "25",
    "pending": 0,
    "missing_rates": 0
  },
  "merchants": [],
  "filters": {
    "period": "last30",
    "currency": "EUR",
    "timezone": "UTC"
  },
  "basis": "first_settlement_latest_net_fees"
}

Response field

summaryobject
feesstring
costsstring
marginstring
creditsstring
pendinginteger
missing_ratesinteger
merchants[]array
filtersobject
periodstring
currencystring
timezonestring
basisstring
ব্যবহারের নোট
  • reports.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Total হিসাবের আগে নিজের ব্যবসার row, cost আর count বাদ যায়। Own-business merchant_id filter-এ 404। Reporting installation timezone ব্যবহার করে।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETঅডিট তালিকা/v1/operator/auditশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Query parameter

merchant_idঐচ্ছিক

অনুমোদিত merchant, সঠিক event type (events) বা action text (audit) দিয়ে filter। Event থাকে ৩০ দিন।

pageঐচ্ছিক
পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।বিস্তারিত

পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/audit" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Response field

data[]array
pageinteger
page_sizeinteger
totalinteger
ব্যবহারের নোট
  • audit.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETEvent তালিকা/v1/operator/eventsশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Query parameter

merchant_idঐচ্ছিক

অনুমোদিত merchant, সঠিক event type (events) বা action text (audit) দিয়ে filter। Event থাকে ৩০ দিন।

event_typeঐচ্ছিক

অনুমোদিত merchant, সঠিক event type (events) বা action text (audit) দিয়ে filter। Event থাকে ৩০ দিন।

pageঐচ্ছিক
পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।বিস্তারিত

পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/events" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Response field

data[]array
pageinteger
page_sizeinteger
totalinteger
ব্যবহারের নোট
  • events.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETWebhook তালিকা/v1/operator/webhooksশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Query parameter

pageঐচ্ছিক
পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।বিস্তারিত

পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/webhooks" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Response field

data[]array
pageinteger
page_sizeinteger
totalinteger
ব্যবহারের নোট
  • events.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTWebhook তৈরি করো/v1/operator/webhooksপড়া + লেখা

ভবিষ্যতের Operator lifecycle event subscribe করো। Store payment webhook নয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/webhooks" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "url": "https://shop.example.test/operator-events",
  "events": [
    "merchant.created",
    "topup.settled"
  ],
  "merchant_ids": [],
  "enabled": true
}'

Request body

urlpublic HTTPS URLবাধ্যতামূলক

Credential, private IP বা redirect নয়। Delivery-র সময় DNS/IP আবার পরীক্ষা হয়।

events[]string[]বাধ্যতামূলক

Operator guide-এর lifecycle event বেছে নাও, invoice callback নয়।

merchant_ids[]UUID[]ঐচ্ছিক

খালি মানে এই credential-এ অনুমোদিত সব merchant। Live scope restriction আবার পরীক্ষা হয়।

enabledbooleanঐচ্ছিক

Paused endpoint queued delivery রাখে; আবার চালু করলে বৈধ সংরক্ষিত কাজ চলে।

উত্তর 201 or 200 application/json

উদাহরণ response
{
  "id": "11111111-1111-4111-8111-111111111111",
  "signing_secret": "wco_whsec_EXAMPLE_ONLY_SAVE_ONCE"
}

Response field

idstring
signing_secretstring
ব্যবহারের নোট
  • webhooks.write + events.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTWebhook আপডেট করো/v1/operator/webhooks/{webhook_id}পড়া + লেখা

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

webhook_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "url": "https://shop.example.test/operator-events",
  "events": [
    "topup.settled"
  ],
  "merchant_ids": [],
  "enabled": false
}'

Request body

urlpublic HTTPS URLবাধ্যতামূলক

Credential, private IP বা redirect নয়। Delivery-র সময় DNS/IP আবার পরীক্ষা হয়।

events[]string[]বাধ্যতামূলক

Operator guide-এর lifecycle event বেছে নাও, invoice callback নয়।

merchant_ids[]UUID[]ঐচ্ছিক

খালি মানে এই credential-এ অনুমোদিত সব merchant। Live scope restriction আবার পরীক্ষা হয়।

enabledbooleanঐচ্ছিক

Paused endpoint queued delivery রাখে; আবার চালু করলে বৈধ সংরক্ষিত কাজ চলে।

উত্তর 200 application/json

উদাহরণ response
{
  "id": "44444444-4444-4444-8444-444444444444",
  "signing_secret": null
}

Response field

idstring
signing_secretJSON | null
ব্যবহারের নোট
  • webhooks.write + events.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTWebhook secret বদলাও/v1/operator/webhooks/{webhook_id}/rotateপড়া + লেখা

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

webhook_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID/rotate" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{}'

উত্তর 200 application/json

উদাহরণ response
{
  "id": "11111111-1111-4111-8111-111111111111",
  "signing_secret": "wco_whsec_EXAMPLE_ONLY_SAVE_ONCE"
}

Response field

idstring
signing_secretstring
ব্যবহারের নোট
  • webhooks.write + events.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETWebhook delivery-এর তালিকা/v1/operator/webhooks/{webhook_id}/deliveriesশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

webhook_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

Query parameter

pageঐচ্ছিক
পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।বিস্তারিত

পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID/deliveries" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Response field

data[]array
pageinteger
page_sizeinteger
totalinteger
ব্যবহারের নোট
  • events.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETপ্রকল্পের তালিকা/v1/operator/merchants/{merchant_id}/projectsশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

Query parameter

pageঐচ্ছিক
পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।বিস্তারিত

পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Response field

data[]array
pageinteger
page_sizeinteger
totalinteger
ব্যবহারের নোট
  • projects.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTপ্রকল্প তৈরি করো/v1/operator/merchants/{merchant_id}/projectsপড়া + লেখা

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Online shop",
  "slug": "online-shop",
  "enabled": false
}'

Request body

namestringsবাধ্যতামূলক

নাম আর অনন্য স্থায়ী project identifier। আগের project bootstrap দিয়ে local wallet তৈরি করে, অর্থ পাঠায় না।

slugstringsবাধ্যতামূলক

নাম আর অনন্য স্থায়ী project identifier। আগের project bootstrap দিয়ে local wallet তৈরি করে, অর্থ পাঠায় না।

enabledঐচ্ছিক

enabled ডিফল্ট true; আগে paused অবস্থায় তৈরি করে store কনফিগার করা ভালো।

reporting_timezoneঐচ্ছিক

enabled ডিফল্ট true; আগে paused অবস্থায় তৈরি করে store কনফিগার করা ভালো।

checkout_titleঐচ্ছিক

enabled ডিফল্ট true; আগে paused অবস্থায় তৈরি করে store কনফিগার করা ভালো।

checkout_descriptionঐচ্ছিক

enabled ডিফল্ট true; আগে paused অবস্থায় তৈরি করে store কনফিগার করা ভালো।

checkout_themeঐচ্ছিক

enabled ডিফল্ট true; আগে paused অবস্থায় তৈরি করে store কনফিগার করা ভালো।

checkout_accent_colorঐচ্ছিক

enabled ডিফল্ট true; আগে paused অবস্থায় তৈরি করে store কনফিগার করা ভালো।

উত্তর 201 or 200 application/json

উদাহরণ response
{
  "id": "33333333-3333-4333-8333-333333333333",
  "slug": "example-shop",
  "name": "Example shop",
  "enabled": false,
  "reporting_currency": "EUR",
  "reporting_timezone": "Europe/Berlin",
  "stores": []
}

Response field

idstring
slugstring
namestring
enabledboolean
reporting_currencystring
reporting_timezonestring
stores[]array
ব্যবহারের নোট
  • projects.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETপ্রকল্পের তথ্য নাও/v1/operator/merchants/{merchant_id}/projects/{project_id}শুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

project_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "id": "33333333-3333-4333-8333-333333333333",
  "slug": "example-shop",
  "name": "Example shop",
  "enabled": false,
  "reporting_currency": "EUR",
  "reporting_timezone": "Europe/Berlin",
  "stores": []
}

Response field

idstring
slugstring
namestring
enabledboolean
reporting_currencystring
reporting_timezonestring
stores[]array
ব্যবহারের নোট
  • projects.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTপ্রকল্প আপডেট করো/v1/operator/merchants/{merchant_id}/projects/{project_id}পড়া + লেখা

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

project_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "enabled": true
}'

Request body

nameঐচ্ছিক

আংশিক update। Identifier আর merchant ownership বদলানো যায় না।

enabledঐচ্ছিক

আংশিক update। Identifier আর merchant ownership বদলানো যায় না।

reporting_currencyঐচ্ছিক

আংশিক update। Identifier আর merchant ownership বদলানো যায় না।

reporting_timezoneঐচ্ছিক

আংশিক update। Identifier আর merchant ownership বদলানো যায় না।

checkout_titleঐচ্ছিক

আংশিক update। Identifier আর merchant ownership বদলানো যায় না।

checkout_descriptionঐচ্ছিক

আংশিক update। Identifier আর merchant ownership বদলানো যায় না।

checkout_themeঐচ্ছিক

আংশিক update। Identifier আর merchant ownership বদলানো যায় না।

checkout_accent_colorঐচ্ছিক

আংশিক update। Identifier আর merchant ownership বদলানো যায় না।

উত্তর 200 application/json

উদাহরণ response
{
  "id": "33333333-3333-4333-8333-333333333333",
  "slug": "example-shop",
  "name": "Example shop",
  "enabled": false,
  "reporting_currency": "EUR",
  "reporting_timezone": "Europe/Berlin",
  "stores": []
}

Response field

idstring
slugstring
namestring
enabledboolean
reporting_currencystring
reporting_timezonestring
stores[]array
ব্যবহারের নোট
  • projects.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETস্টোরের তালিকা/v1/operator/merchants/{merchant_id}/projects/{project_id}/storesশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

project_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

Query parameter

pageঐচ্ছিক
পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।বিস্তারিত

পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Response field

data[]array
pageinteger
page_sizeinteger
totalinteger
ব্যবহারের নোট
  • projects.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTস্টোর তৈরি করো/v1/operator/merchants/{merchant_id}/projects/{project_id}/storesপড়া + লেখা

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

project_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Web checkout",
  "slug": "web-checkout",
  "default_currency": "EUR",
  "enabled": false
}'

Request body

namestringsবাধ্যতামূলক

Store name আর স্থায়ী identifier।

slugstringsবাধ্যতামূলক

Store name আর স্থায়ী identifier।

default_currencyঐচ্ছিক

Percentage-এ decimal string ব্যবহার করো। নতুন store প্রকল্পের default-store appearance নেয়।

invoice_expiry_minutesঐচ্ছিক

Percentage-এ decimal string ব্যবহার করো। নতুন store প্রকল্পের default-store appearance নেয়।

exchange_rate_spread_percentঐচ্ছিক

Percentage-এ decimal string ব্যবহার করো। নতুন store প্রকল্পের default-store appearance নেয়।

underpayment_tolerance_percentঐচ্ছিক

Percentage-এ decimal string ব্যবহার করো। নতুন store প্রকল্পের default-store appearance নেয়।

enabledঐচ্ছিক

payment-assets দিয়ে accepted asset কনফিগার করো; zero-amount invoice ডিফল্টে বন্ধ।

is_defaultঐচ্ছিক

payment-assets দিয়ে accepted asset কনফিগার করো; zero-amount invoice ডিফল্টে বন্ধ।

allow_zero_amount_invoicesঐচ্ছিক

payment-assets দিয়ে accepted asset কনফিগার করো; zero-amount invoice ডিফল্টে বন্ধ।

allow_underpaymentsঐচ্ছিক

payment-assets দিয়ে accepted asset কনফিগার করো; zero-amount invoice ডিফল্টে বন্ধ।

allow_overpaymentsঐচ্ছিক

payment-assets দিয়ে accepted asset কনফিগার করো; zero-amount invoice ডিফল্টে বন্ধ।

allowed_chain_slugsঐচ্ছিক

payment-assets দিয়ে accepted asset কনফিগার করো; zero-amount invoice ডিফল্টে বন্ধ।

ipn_enabledঐচ্ছিক

IPN আর return URL আগের URL validation মেনে চলে। ইচ্ছামতো HTML/JavaScript নয়।

default_ipn_urlঐচ্ছিক

IPN আর return URL আগের URL validation মেনে চলে। ইচ্ছামতো HTML/JavaScript নয়।

default_redirect_urlঐচ্ছিক

IPN আর return URL আগের URL validation মেনে চলে। ইচ্ছামতো HTML/JavaScript নয়।

default_cancel_urlঐচ্ছিক

IPN আর return URL আগের URL validation মেনে চলে। ইচ্ছামতো HTML/JavaScript নয়।

redirect_automaticallyঐচ্ছিক

IPN আর return URL আগের URL validation মেনে চলে। ইচ্ছামতো HTML/JavaScript নয়।

checkout_languageঐচ্ছিক

সমর্থিত language আর active role domain ব্যবহার করো; embedding origin স্পষ্টভাবে কনফিগার করো।

embed_enabledঐচ্ছিক

সমর্থিত language আর active role domain ব্যবহার করো; embedding origin স্পষ্টভাবে কনফিগার করো।

allowed_embed_originsঐচ্ছিক

সমর্থিত language আর active role domain ব্যবহার করো; embedding origin স্পষ্টভাবে কনফিগার করো।

domainsঐচ্ছিক

সমর্থিত language আর active role domain ব্যবহার করো; embedding origin স্পষ্টভাবে কনফিগার করো।

উত্তর 201 or 200 application/json

উদাহরণ response
{
  "id": "44444444-4444-4444-8444-444444444444",
  "project_id": "33333333-3333-4333-8333-333333333333",
  "slug": "online",
  "name": "Online shop",
  "enabled": false,
  "default_currency": "EUR",
  "invoice_expiry_minutes": 60
}

Response field

idstring
project_idstring
slugstring
namestring
enabledboolean
default_currencystring
invoice_expiry_minutesinteger
ব্যবহারের নোট
  • projects.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETস্টোরের তথ্য নাও/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}শুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

project_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

store_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "id": "44444444-4444-4444-8444-444444444444",
  "project_id": "33333333-3333-4333-8333-333333333333",
  "slug": "online",
  "name": "Online shop",
  "enabled": false,
  "default_currency": "EUR",
  "invoice_expiry_minutes": 60
}

Response field

idstring
project_idstring
slugstring
namestring
enabledboolean
default_currencystring
invoice_expiry_minutesinteger
ব্যবহারের নোট
  • projects.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTস্টোর আপডেট করো/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}পড়া + লেখা

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

project_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

store_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "enabled": true
}'

Request body

store fieldsঐচ্ছিক

Store creation-এর মতোই mutable settings, শুধু slug ছাড়া। শুধু দেওয়া field বদলায়।

enabledboolean

উত্তর 200 application/json

উদাহরণ response
{
  "id": "44444444-4444-4444-8444-444444444444",
  "project_id": "33333333-3333-4333-8333-333333333333",
  "slug": "online",
  "name": "Online shop",
  "enabled": false,
  "default_currency": "EUR",
  "invoice_expiry_minutes": 60
}

Response field

idstring
project_idstring
slugstring
namestring
enabledboolean
default_currencystring
invoice_expiry_minutesinteger
ব্যবহারের নোট
  • projects.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETস্টোরের ডিজাইন পড়ো/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/checkout-appearanceশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

project_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

store_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/checkout-appearance" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "revision": 1,
  "settings": {
    "inherit_default_store": true
  },
  "effective": {
    "title": "Pay securely"
  }
}

Response field

revisioninteger
settingsobject
inherit_default_storeboolean
effectiveobject
titlestring
ব্যবহারের নোট
  • projects.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTস্টোরের ডিজাইন বদলাও/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/checkout-appearanceপড়া + লেখা

যাচাই করা, revision-সুরক্ষিত store design সেভ করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

project_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

store_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/checkout-appearance" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "revision": 1,
  "settings": {
    "inherit_default_store": false,
    "title": "Pay securely",
    "theme": "light"
  }
}'

Request body

revisionintegerবাধ্যতামূলক

আগে GET দিয়ে current revision পড়ো। Stale revision অন্য editor-এর কাজ না মুছে ব্যর্থ হয়।

settingsobjectবাধ্যতামূলক
যাচাই করা checkout appearance, inherit_default_store, branding, intro/outro, font size আর visibility-সহ। ইচ্ছামতো HTML/JavaScript নয়। Image byte upload শুধু console-এ।বিস্তারিত

যাচাই করা checkout appearance, inherit_default_store, branding, intro/outro, font size আর visibility-সহ। ইচ্ছামতো HTML/JavaScript নয়। Image byte upload শুধু console-এ।

inherit_default_storeboolean
titlestring
themestring

উত্তর 200 application/json

উদাহরণ response
{
  "settings": {
    "inherit_default_store": false,
    "title": "Pay securely",
    "theme": "light"
  },
  "revision": 2
}

Response field

settingsobject
inherit_default_storeboolean
titlestring
themestring
revisioninteger
ব্যবহারের নোট
  • projects.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETস্টোরের পেমেন্ট অ্যাসেটের তালিকা/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/payment-assetsশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

project_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

store_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": []
}

Response field

data[]array
ব্যবহারের নোট
  • projects.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTস্টোরের পেমেন্ট অ্যাসেট বদলাও/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/payment-assetsপড়া + লেখা

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

project_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

store_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "assets": [
    {
      "asset_id": "11111111-1111-4111-8111-111111111111",
      "display_order": 0
    }
  ]
}'

Request body

assets[]object[]বাধ্যতামূলক
On-chain method পুরো প্রতিস্থাপন: asset_id UUID আর display_order। [] দিলে accepted on-chain asset খালি হয়। শুধু verified project asset; Lightning কনফিগার করে না।বিস্তারিত

On-chain method পুরো প্রতিস্থাপন: asset_id UUID আর display_order। [] দিলে accepted on-chain asset খালি হয়। শুধু verified project asset; Lightning কনফিগার করে না।

asset_idstring
display_orderinteger

উত্তর 200 application/json

উদাহরণ response
{
  "data": []
}

Response field

data[]array
ব্যবহারের নোট
  • projects.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETস্টোরের webhook তালিকা/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/webhooksশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

project_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

store_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

Query parameter

pageঐচ্ছিক
পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।বিস্তারিত

পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Response field

data[]array
pageinteger
page_sizeinteger
totalinteger
ব্যবহারের নোট
  • projects.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTস্টোরের webhook তৈরি করো/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/webhooksপড়া + লেখা

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

project_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

store_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Orders",
  "url": "https://shop.example.test/payments",
  "event_types": [
    "invoice.settled"
  ],
  "enabled": true,
  "automatic_redelivery": true
}'

Request body

namestrings / arrayবাধ্যতামূলক

Public HTTPS receiver আর IPN/webhook documentation-এর invoice event name।

urlstrings / arrayবাধ্যতামূলক

Public HTTPS receiver আর IPN/webhook documentation-এর invoice event name।

event_types[]strings / arrayবাধ্যতামূলক

Public HTTPS receiver আর IPN/webhook documentation-এর invoice event name।

enabledbooleansঐচ্ছিক

তৈরির সময় signing secret একবার আসে। এগুলো store payment callback, Operator lifecycle event নয়।

automatic_redeliverybooleansঐচ্ছিক

তৈরির সময় signing secret একবার আসে। এগুলো store payment callback, Operator lifecycle event নয়।

উত্তর 201 or 200 application/json

উদাহরণ response
{
  "signing_secret": "EXAMPLE_ONLY_SAVE_ONCE",
  "endpoint": {
    "id": "44444444-4444-4444-8444-444444444444",
    "name": "Orders",
    "enabled": true
  },
  "secret_visible_once": true
}

Response field

signing_secretstring
endpointobject
idstring
namestring
enabledboolean
secret_visible_onceboolean
ব্যবহারের নোট
  • projects.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTস্টোরের webhook আপডেট করো/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/webhooks/{webhook_id}পড়া + লেখা

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

project_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

store_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

webhook_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks/YOUR_WEBHOOK_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Orders",
  "url": "https://shop.example.test/payments",
  "event_types": [
    "invoice.settled"
  ],
  "enabled": false,
  "automatic_redelivery": true
}'

Request body

namestrings / arrayবাধ্যতামূলক

Public HTTPS receiver আর IPN/webhook documentation-এর invoice event name।

urlstrings / arrayবাধ্যতামূলক

Public HTTPS receiver আর IPN/webhook documentation-এর invoice event name।

event_types[]strings / arrayবাধ্যতামূলক

Public HTTPS receiver আর IPN/webhook documentation-এর invoice event name।

enabledbooleansঐচ্ছিক

তৈরির সময় signing secret একবার আসে। এগুলো store payment callback, Operator lifecycle event নয়।

automatic_redeliverybooleansঐচ্ছিক

তৈরির সময় signing secret একবার আসে। এগুলো store payment callback, Operator lifecycle event নয়।

উত্তর 200 application/json

উদাহরণ response
{
  "id": "44444444-4444-4444-8444-444444444444",
  "name": "Orders",
  "enabled": true
}

Response field

idstring
namestring
enabledboolean
ব্যবহারের নোট
  • projects.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETইনভয়েস তালিকা/v1/operator/merchants/{merchant_id}/projects/{project_id}/invoicesশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

project_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

Query parameter

limitঐচ্ছিক

Project invoice list-এর মতোই invoice pagination আর filter।

offsetঐচ্ছিক

Project invoice list-এর মতোই invoice pagination আর filter।

statusঐচ্ছিক

Project invoice list-এর মতোই invoice pagination আর filter।

store_idঐচ্ছিক

Project invoice list-এর মতোই invoice pagination আর filter।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 0,
    "has_more": false
  }
}

Response field

data[]array
paginationobject
limitinteger
offsetinteger
totalinteger
has_moreboolean
ব্যবহারের নোট
  • reports.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETইনভয়েসের তথ্য নাও/v1/operator/merchants/{merchant_id}/projects/{project_id}/invoices/{invoice_id}শুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

project_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

invoice_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices/YOUR_INVOICE_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "invoice_id": "44444444-4444-4444-8444-444444444444",
  "project_id": "33333333-3333-4333-8333-333333333333",
  "amount": "25",
  "currency": "EUR",
  "status": "new",
  "metadata": {},
  "payment_intents": []
}

Response field

invoice_idstring
project_idstring
amountstring
currencystring
statusstring
metadataobject
payment_intents[]array
ব্যবহারের নোট
  • reports.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।
  • invoice_id হলো creation আর callback-এ ফেরত আসা public invoice ID, internal id নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETওয়ালেট তালিকা/v1/operator/merchants/{merchant_id}/projects/{project_id}/walletsশুধু পড়া

Cached public wallet balance পড়ো, private key বা recovery phrase নয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

project_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

Query parameter

pageঐচ্ছিক
পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।বিস্তারিত

পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/wallets" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Response field

data[]array
pageinteger
page_sizeinteger
totalinteger
ব্যবহারের নোট
  • reports.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Balance হলো freshness field-সহ cached observation, খরচযোগ্য balance-এর নিশ্চয়তা নয়। এই API দিয়ে sending বা key export হয় না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETওয়ালেটের ঠিকানার তালিকা/v1/operator/merchants/{merchant_id}/projects/{project_id}/wallets/{wallet_id}/addressesশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

project_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

wallet_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

Query parameter

limitঐচ্ছিক
Limit 1–50, ডিফল্ট 25। পরের পৃষ্ঠায় next_cursor-কে before হিসেবে দাও। প্রথম পৃষ্ঠায় before বাদ দাও। has_balance=false আর hide_small_balances=false দিলে খালি/ছোট balance-ও আসে।বিস্তারিত

Limit 1–50, ডিফল্ট 25। পরের পৃষ্ঠায় next_cursor-কে before হিসেবে দাও। প্রথম পৃষ্ঠায় before বাদ দাও। has_balance=false আর hide_small_balances=false দিলে খালি/ছোট balance-ও আসে।

beforeঐচ্ছিক
Limit 1–50, ডিফল্ট 25। পরের পৃষ্ঠায় next_cursor-কে before হিসেবে দাও। প্রথম পৃষ্ঠায় before বাদ দাও। has_balance=false আর hide_small_balances=false দিলে খালি/ছোট balance-ও আসে।বিস্তারিত

Limit 1–50, ডিফল্ট 25। পরের পৃষ্ঠায় next_cursor-কে before হিসেবে দাও। প্রথম পৃষ্ঠায় before বাদ দাও। has_balance=false আর hide_small_balances=false দিলে খালি/ছোট balance-ও আসে।

has_balanceঐচ্ছিক
Limit 1–50, ডিফল্ট 25। পরের পৃষ্ঠায় next_cursor-কে before হিসেবে দাও। প্রথম পৃষ্ঠায় before বাদ দাও। has_balance=false আর hide_small_balances=false দিলে খালি/ছোট balance-ও আসে।বিস্তারিত

Limit 1–50, ডিফল্ট 25। পরের পৃষ্ঠায় next_cursor-কে before হিসেবে দাও। প্রথম পৃষ্ঠায় before বাদ দাও। has_balance=false আর hide_small_balances=false দিলে খালি/ছোট balance-ও আসে।

hide_small_balancesঐচ্ছিক
Limit 1–50, ডিফল্ট 25। পরের পৃষ্ঠায় next_cursor-কে before হিসেবে দাও। প্রথম পৃষ্ঠায় before বাদ দাও। has_balance=false আর hide_small_balances=false দিলে খালি/ছোট balance-ও আসে।বিস্তারিত

Limit 1–50, ডিফল্ট 25। পরের পৃষ্ঠায় next_cursor-কে before হিসেবে দাও। প্রথম পৃষ্ঠায় before বাদ দাও। has_balance=false আর hide_small_balances=false দিলে খালি/ছোট balance-ও আসে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/wallets/YOUR_WALLET_ID/addresses" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "wallet": {
    "id": "22222222-2222-4222-8222-222222222222",
    "chain_slug": "ethereum"
  },
  "items": [],
  "total": 0,
  "total_pages": 1,
  "next_cursor": null,
  "reporting_currency": "EUR",
  "has_balance": true,
  "hide_small_balances": true,
  "small_balance_threshold": {
    "amount": "0.20",
    "currency": "EUR"
  }
}

Response field

walletobject
idstring
chain_slugstring
items[]array
totalinteger
total_pagesinteger
next_cursorJSON | null
reporting_currencystring
has_balanceboolean
hide_small_balancesboolean
small_balance_thresholdobject
amountstring
currencystring
ব্যবহারের নোট
  • reports.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETমার্চেন্ট ক্রেডেনশিয়ালের তালিকা/v1/operator/merchants/{merchant_id}/api-credentialsশুধু পড়া

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

Query parameter

pageঐচ্ছিক
পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।বিস্তারিত

পৃষ্ঠা ১ থেকে শুরু, প্রতি পৃষ্ঠায় ২৫ item। Merchant, user, project, store, wallet, credential আর webhook-এ search আছে; native event list-এর নিজস্ব filter আছে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

Response field

data[]array
pageinteger
page_sizeinteger
totalinteger
ব্যবহারের নোট
  • merchant_credentials.read লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTমার্চেন্ট ক্রেডেনশিয়াল তৈরি করো/v1/operator/merchants/{merchant_id}/api-credentialsপড়া + লেখা

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Store integration",
  "access_level": "read_only",
  "enabled": true,
  "ip_restriction_enabled": false,
  "allowed_ips": [],
  "project_ids": [
    "11111111-1111-4111-8111-111111111111"
  ]
}'

Request body

namestringবাধ্যতামূলক

নতুন সাধারণ merchant key-এর label, Operator key নয়।

access_levelread_only | read_writeঐচ্ছিক

Read/write আগের merchant API contract চালু করে।

project_ids[]UUID[]

শুধু বাছাই করা merchant-এর project; খালি list আগের all-merchant-projects policy মেনে চলে।

enabledঐচ্ছিক

আগের merchant key control। Secret একবার ফেরত আসে; merchant_credentials.write লাগে।

ip_restriction_enabledঐচ্ছিক

আগের merchant key control। Secret একবার ফেরত আসে; merchant_credentials.write লাগে।

allowed_ips[]ঐচ্ছিক

আগের merchant key control। Secret একবার ফেরত আসে; merchant_credentials.write লাগে।

requests_per_minuteঐচ্ছিক

আগের merchant key control। Secret একবার ফেরত আসে; merchant_credentials.write লাগে।

উত্তর 201 or 200 application/json

উদাহরণ response
{
  "credential": {
    "id": "22222222-2222-4222-8222-222222222222",
    "name": "Checkout",
    "access_level": "read_only",
    "project_ids": [
      "33333333-3333-4333-8333-333333333333"
    ],
    "enabled": true
  },
  "token": "wc_live_EXAMPLE_ONLY_SAVE_ONCE"
}

Response field

credentialobject
idstring
namestring
access_levelstring
project_ids[]array
enabledboolean
tokenstring
ব্যবহারের নোট
  • merchant_credentials.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTমার্চেন্ট ক্রেডেনশিয়াল আপডেট করো/v1/operator/merchants/{merchant_id}/api-credentials/{credential_id}পড়া + লেখা

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

credential_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Checkout",
  "access_level": "read_only",
  "enabled": true,
  "ip_restriction_enabled": false,
  "allowed_ips": [],
  "project_ids": [
    "33333333-3333-4333-8333-333333333333"
  ]
}'

Request body

namefieldsবাধ্যতামূলক

পরিবর্তনসহ পুরো current credential configuration পাঠাও। project_ids ডিফল্ট []; requests_per_minute ডিফল্ট merchant API quota।

access_levelfieldsবাধ্যতামূলক

পরিবর্তনসহ পুরো current credential configuration পাঠাও। project_ids ডিফল্ট []; requests_per_minute ডিফল্ট merchant API quota।

enabledfieldsবাধ্যতামূলক

পরিবর্তনসহ পুরো current credential configuration পাঠাও। project_ids ডিফল্ট []; requests_per_minute ডিফল্ট merchant API quota।

ip_restriction_enabledfieldsবাধ্যতামূলক

পরিবর্তনসহ পুরো current credential configuration পাঠাও। project_ids ডিফল্ট []; requests_per_minute ডিফল্ট merchant API quota।

allowed_ips[]fieldsবাধ্যতামূলক

পরিবর্তনসহ পুরো current credential configuration পাঠাও। project_ids ডিফল্ট []; requests_per_minute ডিফল্ট merchant API quota।

project_ids[]array

উত্তর 200 application/json

উদাহরণ response
{
  "id": "22222222-2222-4222-8222-222222222222",
  "name": "Checkout",
  "access_level": "read_only",
  "project_ids": [
    "33333333-3333-4333-8333-333333333333"
  ],
  "enabled": true
}

Response field

idstring
namestring
access_levelstring
project_ids[]array
enabledboolean
ব্যবহারের নোট
  • merchant_credentials.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTমার্চেন্ট ক্রেডেনশিয়াল ঘোরাও/v1/operator/merchants/{merchant_id}/api-credentials/{credential_id}/rotateপড়া + লেখা

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

credential_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID/rotate" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{}'

উত্তর 200 application/json

উদাহরণ response
{
  "credential": {
    "id": "22222222-2222-4222-8222-222222222222",
    "name": "Checkout",
    "access_level": "read_only",
    "project_ids": [
      "33333333-3333-4333-8333-333333333333"
    ],
    "enabled": true
  },
  "token": "wc_live_EXAMPLE_ONLY_SAVE_ONCE"
}

Response field

credentialobject
idstring
namestring
access_levelstring
project_ids[]array
enabledboolean
tokenstring
ব্যবহারের নোট
  • merchant_credentials.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTমার্চেন্ট ক্রেডেনশিয়াল বাতিল করো/v1/operator/merchants/{merchant_id}/api-credentials/{credential_id}/revokeপড়া + লেখা

আলাদা Operator credential দিয়ে নির্দিষ্ট hosted merchant resource পরিচালনা বা পরীক্ষা করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই operation-এর জন্য স্থায়ীভাবে রাখা

Path parameter

merchant_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

credential_idUUIDবাধ্যতামূলক

Canonical lowercase resource UUID; credential-এর merchant scope-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID/revoke" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{}'

উত্তর 200 application/json

উদাহরণ response
{
  "revoked": true
}

Response field

revokedboolean
ব্যবহারের নোট
  • merchant_credentials.write লাগে; শুধু অনুমোদিত hosted merchant। Operator key মালিকের নিজের ব্যবসার workspace-এ ঢোকে না।
  • পাঠানোর আগে unique Idempotency-Key আর হুবহু body স্থায়ীভাবে রাখো। Retry committed action পুনরায় চালায় না। Replay-তে secret field বাদ থাকে; secret response হারালে তৈরি resource দেখে স্পষ্টভাবে rotate/reissue করো। 409 operator_request_in_progress মানে ফল অজানা বাধাপ্রাপ্ত request-ও হতে পারে: resource/audit দেখো; না দেখে নতুন key দিয়ে retry কোরো না।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTআমন্ত্রণের token পরীক্ষা করো/v1/onboarding/invitations/checkপাবলিক

শুধু token দিয়ে onboarding। Operator key নেয় না বা নিজে থেকে sign in করায় না। Console login-এ এখনো site-এর Basic Auth আর আগের TOTP লাগে।

Authentication ও header

পাবলিক

অনুরোধ

curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/onboarding/invitations/check" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "token": "YOUR_PRIVATE_INVITATION_TOKEN"
}'

Request body

tokenstringবাধ্যতামূলক

Invitation URL fragment-এর secret। কখনো log কোরো না।

উত্তর 200 application/json

উদাহরণ response
{
  "kind": "invitation",
  "email": "admin@example.test",
  "merchant_name": "Example shop"
}

Response field

kindstring
emailstring
merchant_namestring
ব্যবহারের নোট
  • ৪৮ ঘণ্টার invitation; এক ঘণ্টার password-reset link। একবারের hashed token। Reissue আগের link বাতিল করে। Acceptance-এ TOTP থাকে আর old session বাতিল হয়।
  • Automatic retry নেই। Acceptance timeout হলে link status দেখে sign in করার চেষ্টা করো; ব্যর্থ ধরে নিয়ো না। দেখা source IP অনুযায়ী rate limit। প্রাপককে নিজে custody acknowledgement দিতে হবে।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTআমন্ত্রণ বা পাসওয়ার্ড reset গ্রহণ করো/v1/onboarding/invitations/acceptপাবলিক

শুধু token দিয়ে onboarding। Operator key নেয় না বা নিজে থেকে sign in করায় না। Console login-এ এখনো site-এর Basic Auth আর আগের TOTP লাগে।

Authentication ও header

পাবলিক

অনুরোধ

curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/onboarding/invitations/accept" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "token": "YOUR_PRIVATE_INVITATION_TOKEN",
  "password": "REPLACE_WITH_YOUR_OWN_UNIQUE_PASSWORD",
  "custody_acknowledged": true
}'

Request body

tokenstringবাধ্যতামূলক

Invitation URL fragment-এর secret। কখনো log কোরো না।

passwordstringবাধ্যতামূলক

নতুন password, 12–128 অক্ষর (সর্বোচ্চ 512 UTF-8 byte)।

custody_acknowledgedboolean

নতুন hosted-wallet invitation গ্রহণে true হতে হবে।

উত্তর 200 application/json

উদাহরণ response
{
  "password_set": true
}

Response field

password_setboolean
ব্যবহারের নোট
  • ৪৮ ঘণ্টার invitation; এক ঘণ্টার password-reset link। একবারের hashed token। Reissue আগের link বাতিল করে। Acceptance-এ TOTP থাকে আর old session বাতিল হয়।
  • Automatic retry নেই। Acceptance timeout হলে link status দেখে sign in করার চেষ্টা করো; ব্যর্থ ধরে নিয়ো না। দেখা source IP অনুযায়ী rate limit। প্রাপককে নিজে custody acknowledgement দিতে হবে।
  • Response উদাহরণে বাছাই করা field দেখানো। অতিরিক্ত response field-কে সংযোজন হিসেবে ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETসক্ষমতা/v1/marketplace/capabilitiesশুধু পড়া

অংশ নেওয়া store, configured asset, supported payout rail, native fee asset আর readiness reason। সাময়িক scanner availability allowed asset set বাড়ায় না।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/capabilities?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETমার্কেটপ্লেস রিপোর্ট/v1/marketplace/overviewশুধু পড়া

store_id, asset_id, from আর to filter (দুই প্রান্তসহ YYYY-MM-DD, UTC; ডিফল্ট শেষ ৩০ দিন; সর্বোচ্চ দশ বছর)। শেষ তারিখের সঠিক account balance আর সময়ের পরিবর্তন। অনুমানভিত্তিক fiat earnings নয়। Store filter invoice ছাড়া project-wide fee বাদ দেয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/overview?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETপ্রকল্পের সেটিংস/v1/marketplace/settingsশুধু পড়া

enabled, payouts_paused, commission_percent, revision আর participating store ফেরত দেয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/settings?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTপ্রকল্পের সেটিংস সেভ করো/v1/marketplace/settingsপড়া + লেখা

Participating-store selection প্রতিস্থাপন করো। revision 0 settings শুরু করে; পরের edit-এ ফেরত পাওয়া revision লাগে। Commission decimal percentage, 0–100, সর্বোচ্চ দুই decimal।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopepolicies.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/settings" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 0,
  "enabled": true,
  "payouts_paused": true,
  "commission_percent": "4",
  "stores": [
    {
      "store_id": "YOUR_STORE_ID",
      "enabled": true,
      "commission_percent": null
    }
  ]
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

revision

0

enabled

true

payouts_paused

true

commission_percent

"4"

stores[]object[]

[{"store_id":"YOUR_STORE_ID","enabled":true,"commission_percent":null}]

store_idstring
enabledboolean
commission_percentJSON | null

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • policies.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETবিক্রেতার তালিকা/v1/marketplace/vendorsশুধু পড়া

পৃষ্ঠাভাগ করা vendor। q দিয়ে name, external ID বা email খোঁজো; status active, suspended বা archived।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/vendors?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

Response field

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTবিক্রেতা তৈরি করো/v1/marketplace/vendorsপড়া + লেখা

Name লাগে (১৬০ অক্ষর); external_id ঐচ্ছিক আর project-unique (১২৮); email ঐচ্ছিক (২৫৪); description সর্বোচ্চ ২০০০। commission_percent null হলে store থেকে নেয়। Non-null override-এ commissions.override-ও লাগে। Vendor hosted merchant account নয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopevendors.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/vendors" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "name": "Example vendor",
  "external_id": "vendor-1042",
  "email": "vendor@example.com",
  "description": "",
  "status": "active",
  "commission_percent": null
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

name

"উদাহরণ বিক্রেতা"

external_id

"vendor-1042"

email

"vendor@example.com"

description

""

status

"active"

commission_percent

null

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • vendors.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETবিক্রেতার তথ্য নাও/v1/marketplace/vendors/{vendor_id}শুধু পড়া

এক vendor, revision আর commission override ফেরত দেয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTবিক্রেতা আপডেট করো/v1/marketplace/vendors/{vendor_id}/updateপড়া + লেখা

Vendor detail আপডেট করো; status active বা suspended। commission_percent বদলাতে বা সরাতে commissions.override-ও লাগে; অপরিবর্তিত মানে শুধু vendors.write। Archived vendor ফেরাতে reconciliation.write-ও লাগে। Console financial edit-এ account reauthentication লাগে। আগের allocation মূল commission আর destination ধরে রাখে।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopevendors.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/update" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "name": "Example vendor",
  "external_id": "vendor-1042",
  "email": "vendor@example.com",
  "description": "",
  "status": "active",
  "commission_percent": null,
  "revision": 1
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

name

"উদাহরণ বিক্রেতা"

external_id

"vendor-1042"

email

"vendor@example.com"

description

""

status

"active"

commission_percent

null

revision

1

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • vendors.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTবিক্রেতা আর্কাইভ করো/v1/marketplace/vendors/{vendor_id}/archiveপড়া + লেখা

Unpaid আর open invoice obligation মেটার পরই archive; নইলে 409 vendor_has_obligations। History থাকে। সাময়িকভাবে suspended status নাও, অথবা update route আর reconciliation.write দিয়ে পুরোনো archived vendor ফেরাও।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopevendors.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/archive" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

revision

1

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • vendors.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETবিক্রেতার গন্তব্য/v1/marketplace/vendors/{vendor_id}/destinationsশুধু পড়া

Versioned destination আর pending/approved/disabled state। Approval ownership প্রমাণ করে না।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

Response field

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTপেআউটের গন্তব্য যোগ করো/v1/marketplace/vendors/{vendor_id}/destinationsপড়া + লেখা

অনুমোদনের অপেক্ষায় বৈধ mainnet BTC বা supported EVM address নিবন্ধন করো। Project-owned address, wrong network আর zero EVM address প্রত্যাখ্যাত।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopedestinations.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "chain_slug": "bitcoin",
  "network": "mainnet",
  "address": "VERIFIED_VENDOR_BTC_ADDRESS",
  "label": "Vendor BTC"
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

chain_slug

"bitcoin"

network

"mainnet"

address

"VERIFIED_VENDOR_BTC_ADDRESS"

label

"বিক্রেতার BTC"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • destinations.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTগন্তব্য অনুমোদন করো/v1/marketplace/vendors/{vendor_id}/destinations/{destination_id}/approveপড়া + লেখা

আগে স্বাধীনভাবে ownership যাচাই করো। এই vendor/network-এর আগের approved destination আগে বন্ধ করো; old snapshot নতুনদিকে যায় না।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopedestinations.approve

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations/YOUR_DESTINATION_ID/approve" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

revision

1

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • destinations.approve লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTগন্তব্য বন্ধ করো/v1/marketplace/vendors/{vendor_id}/destinations/{destination_id}/disableপড়া + লেখা

এই version-এর নতুন/unsent কাজ বন্ধ করো। Signed transaction বাতিল করা যায় না।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopedestinations.approve

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations/YOUR_DESTINATION_ID/disable" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

revision

1

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • destinations.approve লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETবিক্রেতার ব্যালান্স/v1/marketplace/vendors/{vendor_id}/balancesশুধু পড়া

অপরিবর্তনীয় asset identity আর account type অনুযায়ী সঠিক retained ledger amount; live spendable wallet balance নয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/balances?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETমার্কেটপ্লেসের ইনভয়েস/v1/marketplace/invoicesশুধু পড়া

পৃষ্ঠাভাগ করা invoice; q order, email, description, metadata আর invoice UUID খোঁজে। store_id, vendor_id আর Marketplace status filter করো। সাধারণ invoice বাদ থাকে।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/invoices?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

Response field

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTএকাধিক বিক্রেতার ইনভয়েস তৈরি করো/v1/marketplace/invoicesপড়া + লেখা

সাধারণ InvoiceCreateInput field আবার ব্যবহার করো, সঙ্গে store_id আর allocations। প্রতিটি vendor একবার, 1–100 positive share, যোগফল amount-এর ঠিক সমান। ঐচ্ছিক invoice/per-allocation commission_percent-এ commissions.override আর session request-এ console reauthentication লাগে। data.invoice_id আর links.checkout ফেরত দেয়। Compatible common method না থাকলে বিস্তারিত error; incompatible asset-এ fallback নয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopeinvoices.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/invoices" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "store_id": "YOUR_STORE_ID",
  "amount": "300.00",
  "currency": "USD",
  "order_id": "cart-1042",
  "allocations": [
    {
      "vendor_id": "VENDOR_A_UUID",
      "gross_amount": "100.00"
    },
    {
      "vendor_id": "VENDOR_B_UUID",
      "gross_amount": "100.00"
    },
    {
      "vendor_id": "VENDOR_C_UUID",
      "gross_amount": "100.00"
    }
  ]
}'

Request body

amountstringবাধ্যতামূলক
Sign বা exponent ছাড়া plain unsigned decimal string, সর্বোচ্চ ৪৮ integer digit আর ৩০ decimal place। ডিফল্টে positive হতে হবে। Store চাইলে Stores → Invoice-এ zero-amount invoice নিতে পারে; zero total অর্থ গ্রহণ, address allocation বা processing fee ছাড়াই settled হয়।বিস্তারিত

Sign বা exponent ছাড়া plain unsigned decimal string, সর্বোচ্চ ৪৮ integer digit আর ৩০ decimal place। ডিফল্টে positive হতে হবে। Store চাইলে Stores → Invoice-এ zero-amount invoice নিতে পারে; zero total অর্থ গ্রহণ, address allocation বা processing fee ছাড়াই settled হয়।

currencystring | nullঐচ্ছিক
সমর্থিত তিন অক্ষরের fiat currency, uppercase করা হয়। না দিলে বা null হলে store invoice currency। Creation-এ স্বাধীনভাবে পাওয়া billing conversion rate-ও লাগে।বিস্তারিত

সমর্থিত তিন অক্ষরের fiat currency, uppercase করা হয়। না দিলে বা null হলে store invoice currency। Creation-এ স্বাধীনভাবে পাওয়া billing conversion rate-ও লাগে।

payment_methods[]object[] | nullঐচ্ছিক
এই invoice-এর জন্য store-enabled method বেছে নাও। Merchant 5.4.0+: unknown/inactive/unaccepted পছন্দ উপেক্ষা; কিছু না মিললে store default। Omitted/null-ও store default; [] অবৈধ। Method চালু করে না বা store setting বদলায় না। নিচের selection schema দেখো।বিস্তারিত

এই invoice-এর জন্য store-enabled method বেছে নাও। Merchant 5.4.0+: unknown/inactive/unaccepted পছন্দ উপেক্ষা; কিছু না মিললে store default। Omitted/null-ও store default; [] অবৈধ। Method চালু করে না বা store setting বদলায় না। নিচের selection schema দেখো।

chain_slugstringবাধ্যতামূলক
Project → Stores → Payment methods থেকে chain_slug কপি করো, বা GET /v1/projects/{project_id}/stores/{store_id}/payment-assets থেকে পড়ো, যেমন ethereum, base বা bitcoin। একই chain/rail pair একবারই হতে পারে।বিস্তারিত

Project → Stores → Payment methods থেকে chain_slug কপি করো, বা GET /v1/projects/{project_id}/stores/{store_id}/payment-assets থেকে পড়ো, যেমন ethereum, base বা bitcoin। একই chain/rail pair একবারই হতে পারে।

asset_ids[]UUID[] | nullঐচ্ছিক
On-chain asset.id UUID, contract address বা invoice payment-method ID নয়। এটি অথবা asset_tickers ব্যবহার করো। এই chain-এর সব active accepted asset-এর জন্য দুই selector-ই বাদ দাও। [] আর duplicate/nil ID অবৈধ। 5.4.0+-এ এই store/chain-এ active/accepted নয় এমন ID উপেক্ষা; পুরো selection না মিললে store default।বিস্তারিত

On-chain asset.id UUID, contract address বা invoice payment-method ID নয়। এটি অথবা asset_tickers ব্যবহার করো। এই chain-এর সব active accepted asset-এর জন্য দুই selector-ই বাদ দাও। [] আর duplicate/nil ID অবৈধ। 5.4.0+-এ এই store/chain-এ active/accepted নয় এমন ID উপেক্ষা; পুরো selection না মিললে store default।

asset_tickers[]string[] | nullঐচ্ছিক
Merchant 5.3.0+। BTC, USDC বা PEPE-এর মতো symbol, chain_slug আর এই store-এর scope-এ। 1–64 unique ticker; trim/case-insensitive, 1–40 ASCII letter/digit/dot/underscore/hyphen। এটি অথবা asset_ids ব্যবহার করো। 5.4.0+-এ unknown/inactive/unaccepted ticker উপেক্ষা। Ambiguous accepted symbol এখনো ব্যর্থ: asset_ids ব্যবহার করো। Active selected method-এ valid wallet আর pricing লাগে; 6.0.6 থেকে temporary on-chain scanner outage creation আটকায় না। Lightning চাইলে শুধু BTC নেয়।বিস্তারিত

Merchant 5.3.0+। BTC, USDC বা PEPE-এর মতো symbol, chain_slug আর এই store-এর scope-এ। 1–64 unique ticker; trim/case-insensitive, 1–40 ASCII letter/digit/dot/underscore/hyphen। এটি অথবা asset_ids ব্যবহার করো। 5.4.0+-এ unknown/inactive/unaccepted ticker উপেক্ষা। Ambiguous accepted symbol এখনো ব্যর্থ: asset_ids ব্যবহার করো। Active selected method-এ valid wallet আর pricing লাগে; 6.0.6 থেকে temporary on-chain scanner outage creation আটকায় না। Lightning চাইলে শুধু BTC নেয়।

payment_railonchain | lightningঐচ্ছিক
ডিফল্ট onchain। Bitcoin Lightning বাছতে asset_ids ছাড়া {chain_slug: bitcoin, payment_rail: lightning} ব্যবহার করো; asset_tickers চাইলে [BTC] হতে পারে। Bitcoin on-chain-এ Lightning আসে না। Store-এর Lightning connection আগে enabled আর ready হতে হবে।বিস্তারিত

ডিফল্ট onchain। Bitcoin Lightning বাছতে asset_ids ছাড়া {chain_slug: bitcoin, payment_rail: lightning} ব্যবহার করো; asset_tickers চাইলে [BTC] হতে পারে। Bitcoin on-chain-এ Lightning আসে না। Store-এর Lightning connection আগে enabled আর ready হতে হবে।

order_idstring | nullঐচ্ছিক

Merchant order reference, trim-এর পরে 1–128 অক্ষর; control character প্রত্যাখ্যাত।

emailstring | nullঐচ্ছিক

শুধু merchant-এর customer email, ব্যবহারযোগ্য ASCII address-এ normalize করা, সর্বোচ্চ ২৫৪ অক্ষর। না দিলে বা null হলে email থাকে না।

descriptionstring | nullঐচ্ছিক

Customer-facing description, 1–500 অক্ষর; line break আর tab চলে।

expires_in_secondsinteger | nullঐচ্ছিক

Invoice quote-এর মেয়াদ 300 থেকে 86,400 second; না দিলে বা null হলে store policy।

exchange_rate_spread_percentdecimal string | nullঐচ্ছিক
Quote markup 0 থেকে 100, সর্বোচ্চ দুই decimal। না দিলে বা null হলে store default; "0" এই invoice-এ বন্ধ করে। Upward rounding-এর আগে প্রয়োগ করে lock হয়। Invoice fiat amount বা processing-fee basis বদলায় না।বিস্তারিত

Quote markup 0 থেকে 100, সর্বোচ্চ দুই decimal। না দিলে বা null হলে store default; "0" এই invoice-এ বন্ধ করে। Upward rounding-এর আগে প্রয়োগ করে lock হয়। Invoice fiat amount বা processing-fee basis বদলায় না।

underpayment_tolerance_percentdecimal string | nullঐচ্ছিক

গ্রহণযোগ্য shortfall 0 থেকে 99.99, সর্বোচ্চ দুই decimal। না দিলে বা null হলে store default।

ipn_urlstring | nullঐচ্ছিক

Public HTTPS callback, সর্বোচ্চ 2,048 byte, credential বা fragment ছাড়া। Store default override করে; null/omitted হলে সেখান থেকে নেয়।

redirect_urlstring | nullঐচ্ছিক

Settlement-এর পরে HTTPS success URL, সর্বোচ্চ 2,048 byte, embedded credential ছাড়া। না দিলে বা null হলে store default, তা মুছতে পারে না।

cancel_urlstring | nullঐচ্ছিক

সফল payment ছাড়া checkout শেষ হলে HTTPS return URL। না দিলে বা null হলে store default, তা মুছতে পারে না।

redirect_automaticallyboolean | nullঐচ্ছিক

না দিলে বা null হলে store policy। true-তে কার্যকর redirect_url লাগে।

languagestring | nullঐচ্ছিক
Customer language: en, de, es, pt-BR, it, ru, zh-CN, fr, ko বা ja। pt মানে Brazilian Portuguese আর zh মানে Simplified Chinese। de-DE-এর মতো supported regional tag তালিকার ভাষায় normalize হয়। না দিলে বা null হলে store language। Console language আলাদা।বিস্তারিত

Customer language: en, de, es, pt-BR, it, ru, zh-CN, fr, ko বা ja। pt মানে Brazilian Portuguese আর zh মানে Simplified Chinese। de-DE-এর মতো supported regional tag তালিকার ভাষায় normalize হয়। না দিলে বা null হলে store language। Console language আলাদা।

checkout_appearanceobject | nullঐচ্ছিক
এই invoice-এর আংশিক presentation settings। Omitted/null বর্তমান store design অনুসরণ করে। {}-সহ কোনো object creation-এর সময় resolved design আর image স্থির করে। নিচের override schema দেখো; financial setting, HTML, CSS, JavaScript বা remote image URL নয়।বিস্তারিত

এই invoice-এর আংশিক presentation settings। Omitted/null বর্তমান store design অনুসরণ করে। {}-সহ কোনো object creation-এর সময় resolved design আর image স্থির করে। নিচের override schema দেখো; financial setting, HTML, CSS, JavaScript বা remote image URL নয়।

inherit_default_storebooleanঐচ্ছিক
true হলে project-এর default-store design মূল হিসেবে নেয়; নইলে target store-এর effective design। তারপর override প্রয়োগ করে আলাদাভাবে সেভ হয়; resolved invoice flag false।বিস্তারিত

true হলে project-এর default-store design মূল হিসেবে নেয়; নইলে target store-এর effective design। তারপর override প্রয়োগ করে আলাদাভাবে সেভ হয়; resolved invoice flag false।

titlestringঐচ্ছিক

Checkout heading, সর্বোচ্চ ১২০ অক্ষর। খালি হলে standard heading।

introstringঐচ্ছিক
প্রতিটি সর্বোচ্চ ২,০০০ অক্ষরের plain text। Intro ওপরে, Outro নিচে সব state-এ থাকে। Newline রাখা হয়; নিরাপদ text URL link হয়। Empty string মুছে দেয়। পুরোনো customer_message intro-এর alias হিসেবে চলে; দুটো একসঙ্গে পাঠিয়ো না।বিস্তারিত

প্রতিটি সর্বোচ্চ ২,০০০ অক্ষরের plain text। Intro ওপরে, Outro নিচে সব state-এ থাকে। Newline রাখা হয়; নিরাপদ text URL link হয়। Empty string মুছে দেয়। পুরোনো customer_message intro-এর alias হিসেবে চলে; দুটো একসঙ্গে পাঠিয়ো না।

outrostringঐচ্ছিক
প্রতিটি সর্বোচ্চ ২,০০০ অক্ষরের plain text। Intro ওপরে, Outro নিচে সব state-এ থাকে। Newline রাখা হয়; নিরাপদ text URL link হয়। Empty string মুছে দেয়। পুরোনো customer_message intro-এর alias হিসেবে চলে; দুটো একসঙ্গে পাঠিয়ো না।বিস্তারিত

প্রতিটি সর্বোচ্চ ২,০০০ অক্ষরের plain text। Intro ওপরে, Outro নিচে সব state-এ থাকে। Newline রাখা হয়; নিরাপদ text URL link হয়। Empty string মুছে দেয়। পুরোনো customer_message intro-এর alias হিসেবে চলে; দুটো একসঙ্গে পাঠিয়ো না।

intro_font_sizeintegerঐচ্ছিক

Pixel: 12, 14, 16, 18, 20 বা 24। আলাদাভাবে inherit না করলে default 16।

outro_font_sizeintegerঐচ্ছিক

Pixel: 12, 14, 16, 18, 20 বা 24। আলাদাভাবে inherit না করলে default 16।

themesystem | light | dim | darkঐচ্ছিক

Customer device অনুসরণ করো অথবা fixed theme নাও।

accent_colorstringঐচ্ছিক

#RRGGBB। Automatic color-এর জন্য background, card আর button খালি থাকতে পারে। Text contrast স্বয়ংক্রিয়।

background_colorstringঐচ্ছিক

#RRGGBB। Automatic color-এর জন্য background, card আর button খালি থাকতে পারে। Text contrast স্বয়ংক্রিয়।

card_colorstringঐচ্ছিক

#RRGGBB। Automatic color-এর জন্য background, card আর button খালি থাকতে পারে। Text contrast স্বয়ংক্রিয়।

button_colorstringঐচ্ছিক

#RRGGBB। Automatic color-এর জন্য background, card আর button খালি থাকতে পারে। Text contrast স্বয়ংক্রিয়।

logo_sizestringঐচ্ছিক

small, medium বা large; left বা center।

logo_alignmentstringঐচ্ছিক

small, medium বা large; left বা center।

imagesobjectঐচ্ছিক
Key logo_light, logo_dark, favicon। Key বাদ দিলে base image থাকে; null সরায়। {store_id: UUID, kind?: logo_light|logo_dark|favicon} object একই project-এর সেই store-এর effective uploaded image ব্যবহার করে। kind ডিফল্ট target key। আগে Store → Checkout-এ upload করো; Basic → API IDs থেকে Store API ID কপি করো। Image না থাকলে বা অন্য project-এর ID হলে 400। External URL বা image data নেওয়া হয় না।বিস্তারিত

Key logo_light, logo_dark, favicon। Key বাদ দিলে base image থাকে; null সরায়। {store_id: UUID, kind?: logo_light|logo_dark|favicon} object একই project-এর সেই store-এর effective uploaded image ব্যবহার করে। kind ডিফল্ট target key। আগে Store → Checkout-এ upload করো; Basic → API IDs থেকে Store API ID কপি করো। Image না থাকলে বা অন্য project-এর ID হলে 400। External URL বা image data নেওয়া হয় না।

logo_lightobject | nullঐচ্ছিক
store_idUUIDবাধ্যতামূলক
kindlogo_light | logo_dark | faviconঐচ্ছিক
logo_darkobject | nullঐচ্ছিক
store_idUUIDবাধ্যতামূলক
kindlogo_light | logo_dark | faviconঐচ্ছিক
faviconobject | nullঐচ্ছিক
store_idUUIDবাধ্যতামূলক
kindlogo_light | logo_dark | faviconঐচ্ছিক
show_order_idbooleanঐচ্ছিক

Order ID detail আর title-এর নিচে plain-text description দেখাও। details_expanded শুরুতেই order ID detail খোলে। শুধু display, data redaction নয়।

show_descriptionbooleanঐচ্ছিক

Order ID detail আর title-এর নিচে plain-text description দেখাও। details_expanded শুরুতেই order ID detail খোলে। শুধু display, data redaction নয়।

details_expandedbooleanঐচ্ছিক

Order ID detail আর title-এর নিচে plain-text description দেখাও। details_expanded শুরুতেই order ID detail খোলে। শুধু display, data redaction নয়।

show_project_namebooleanঐচ্ছিক
Merchant 5.6.0+: customer checkout header-এ প্রতিটি নাম দেখাও বা লুকাও। দুটোই default true। Store → Checkout-এও আছে; অন্য appearance setting-এর মতো inherit আর invoice snapshot হয়। শুধু display, data redaction নয়।বিস্তারিত

Merchant 5.6.0+: customer checkout header-এ প্রতিটি নাম দেখাও বা লুকাও। দুটোই default true। Store → Checkout-এও আছে; অন্য appearance setting-এর মতো inherit আর invoice snapshot হয়। শুধু display, data redaction নয়।

show_store_namebooleanঐচ্ছিক
Merchant 5.6.0+: customer checkout header-এ প্রতিটি নাম দেখাও বা লুকাও। দুটোই default true। Store → Checkout-এও আছে; অন্য appearance setting-এর মতো inherit আর invoice snapshot হয়। শুধু display, data redaction নয়।বিস্তারিত

Merchant 5.6.0+: customer checkout header-এ প্রতিটি নাম দেখাও বা লুকাও। দুটোই default true। Store → Checkout-এও আছে; অন্য appearance setting-এর মতো inherit আর invoice snapshot হয়। শুধু display, data redaction নয়।

featured_chains[]string[]ঐচ্ছিক
ক্রমে রাখা chain slug, সর্বোচ্চ ৬০ unique value (lowercase letter, digit, hyphen; সর্বোচ্চ ৬৪ অক্ষর)। [] খালি করে। শুধু available invoice method-এর ক্রম বদলায়।বিস্তারিত

ক্রমে রাখা chain slug, সর্বোচ্চ ৬০ unique value (lowercase letter, digit, hyphen; সর্বোচ্চ ৬৪ অক্ষর)। [] খালি করে। শুধু available invoice method-এর ক্রম বদলায়।

featured_asset_ids[]UUID[]ঐচ্ছিক
সর্বোচ্চ ১০০ unique ordered asset ID; [] খালি করে। Default asset null হতে পারে। ID আসে payment-assets থেকে, payment-intent ID নয়। Method চালু করে না; received payment আর বৈধ customer preference আগে গুরুত্ব পায়।বিস্তারিত

সর্বোচ্চ ১০০ unique ordered asset ID; [] খালি করে। Default asset null হতে পারে। ID আসে payment-assets থেকে, payment-intent ID নয়। Method চালু করে না; received payment আর বৈধ customer preference আগে গুরুত্ব পায়।

default_asset_idUUID|nullঐচ্ছিক
সর্বোচ্চ ১০০ unique ordered asset ID; [] খালি করে। Default asset null হতে পারে। ID আসে payment-assets থেকে, payment-intent ID নয়। Method চালু করে না; received payment আর বৈধ customer preference আগে গুরুত্ব পায়।বিস্তারিত

সর্বোচ্চ ১০০ unique ordered asset ID; [] খালি করে। Default asset null হতে পারে। ID আসে payment-assets থেকে, payment-intent ID নয়। Method চালু করে না; received payment আর বৈধ customer preference আগে গুরুত্ব পায়।

messagesobjectঐচ্ছিক
en, de, es, pt-BR, it, ru, zh-CN, fr, ko বা ja key-এর language object, waiting, confirming, paid, underpaid, expired plain string-সহ (প্রতিটি ৫০০ অক্ষর)। শুধু দেওয়া language/state বদলায়; {} সব message মুছে, {en:{}} English মুছে, আর empty state string সেই state মুছে। English fallback। প্রকৃত status বদলায় না।বিস্তারিত

en, de, es, pt-BR, it, ru, zh-CN, fr, ko বা ja key-এর language object, waiting, confirming, paid, underpaid, expired plain string-সহ (প্রতিটি ৫০০ অক্ষর)। শুধু দেওয়া language/state বদলায়; {} সব message মুছে, {en:{}} English মুছে, আর empty state string সেই state মুছে। English fallback। প্রকৃত status বদলায় না।

enobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
deobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
esobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
pt-BRobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
itobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
ruobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
zh-CNobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
frobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
koobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
jaobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
support_emailstringঐচ্ছিক

ASCII email, সর্বোচ্চ ২৫৪ অক্ষর। খালি হলে মুছে।

support_urlstringঐচ্ছিক

Credential ছাড়া HTTPS URL, সর্বোচ্চ 2,048 অক্ষর। খালি হলে মুছে। Link নতুন window-তে খোলে।

terms_urlstringঐচ্ছিক

Credential ছাড়া HTTPS URL, সর্বোচ্চ 2,048 অক্ষর। খালি হলে মুছে। Link নতুন window-তে খোলে।

privacy_urlstringঐচ্ছিক

Credential ছাড়া HTTPS URL, সর্বোচ্চ 2,048 অক্ষর। খালি হলে মুছে। Link নতুন window-তে খোলে।

return_button_textstringঐচ্ছিক

Label সর্বোচ্চ ৬০ অক্ষর। Invoice behavior-এর জন্য top-level redirect_url/cancel_url/redirect_automatically/language ব্যবহার করো।

show_return_buttonbooleanঐচ্ছিক
Terminal state-সহ checkout-এ manual Return to merchant/cancel button দেখাও। বাদ দিলে store appearance নেয় (default true); false লুকায়। Invoice বাতিল করে না, JSON-এর URL লুকায় না বা automatic success redirect বন্ধ করে না। দরকার হলে top-level redirect_automatically আলাদাভাবে false করো। Merchant 8.1.4 বা নতুন লাগে।বিস্তারিত

Terminal state-সহ checkout-এ manual Return to merchant/cancel button দেখাও। বাদ দিলে store appearance নেয় (default true); false লুকায়। Invoice বাতিল করে না, JSON-এর URL লুকায় না বা automatic success redirect বন্ধ করে না। দরকার হলে top-level redirect_automatically আলাদাভাবে false করো। Merchant 8.1.4 বা নতুন লাগে।

metadataobject | nullঐচ্ছিক
Merchant-only JSON object; omitted বা null হলে {}, সর্বোচ্চ 4,096 encoded byte আর পাঁচ nested level। firstname, lastname, street, street2, zip, city, country, countryiso2, company আর vatid যাচাই, normalize করে customer summary field-এ দেওয়া হয়।বিস্তারিত

Merchant-only JSON object; omitted বা null হলে {}, সর্বোচ্চ 4,096 encoded byte আর পাঁচ nested level। firstname, lastname, street, street2, zip, city, country, countryiso2, company আর vatid যাচাই, normalize করে customer summary field-এ দেওয়া হয়।

firstnamestringঐচ্ছিক
lastnamestringঐচ্ছিক
streetstringঐচ্ছিক
street2stringঐচ্ছিক
zipstringঐচ্ছিক
citystringঐচ্ছিক
countrystringঐচ্ছিক
countryiso2stringঐচ্ছিক
companystringঐচ্ছিক
vatidstringঐচ্ছিক
project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

store_id

"YOUR_STORE_ID"

allocations[]object[]
[{"vendor_id":"VENDOR_A_UUID","gross_amount":"100.00"},{"vendor_id":"VENDOR_B_UUID","gross_amount":"100.00"},{"vendor_id":"VENDOR_C_UUID","gross_amount":"100.00"}]বিস্তারিত

[{"vendor_id":"VENDOR_A_UUID","gross_amount":"100.00"},{"vendor_id":"VENDOR_B_UUID","gross_amount":"100.00"},{"vendor_id":"VENDOR_C_UUID","gross_amount":"100.00"}]

vendor_idstring
gross_amountstring

উত্তর 200 application/json

উদাহরণ response
{
  "data": {
    "invoice_id": "YOUR_INVOICE_ID",
    "status": "new",
    "marketplace": {
      "state": "pending",
      "allocations": []
    }
  },
  "links": {
    "checkout": "https://pay.example.com/invoice/YOUR_INVOICE_ID"
  }
}

Response field

dataobject
invoice_idstring
statusstring
marketplaceobject
statestring
allocations[]array
ব্যবহারের নোট
  • invoices.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETইনভয়েস আর বণ্টন/v1/marketplace/invoices/{invoice_id}শুধু পড়া

সাধারণ invoice detail-এর সঙ্গে marketplace state, revision, hold_reason, frozen allocation, policy snapshot, সর্বশেষ ২০০ payment আর ১০০ related payout, truncation flag-সহ। Public checkout vendor data প্রকাশ করে না।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETইনভয়েস পেমেন্টের প্রমাণ/v1/marketplace/invoices/{invoice_id}/paymentsশুধু পড়া

page/per_page-সহ সাধারণ payment evidence। Observation vendor payout নয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/payments?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETইনভয়েসের বণ্টন/v1/marketplace/invoices/{invoice_id}/allocationsশুধু পড়া

উপযুক্ত settlement-এর পরে অপরিবর্তনীয় share/commission/destination snapshot আর সঠিক gross, commission, net atomic value।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTঅপরিশোধিত ইনভয়েস বাতিল করো/v1/marketplace/invoices/{invoice_id}/cancelপড়া + লেখা

শুধু অপরিশোধিত new বা expired invoice। Late receipt review-তে hold থাকে। Revision হলো Marketplace invoice revision।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopeinvoices.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/cancel" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

revision

1

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • invoices.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTবণ্টন আটকে রাখো/v1/marketplace/invoices/{invoice_id}/allocations/holdপড়া + লেখা

Obligation না মুছে unsigned allocation hold করো। Signed বা uncertain payout track হতে থাকে।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopereconciliation.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/hold" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1,
  "reason": "Verify customer request"
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

revision

1

reason

"গ্রাহকের অনুরোধ যাচাই করো"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • reconciliation.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTবণ্টন পর্যালোচনা করে ছাড়ো/v1/marketplace/invoices/{invoice_id}/allocations/releaseপড়া + লেখা

Backing/finality আবার পরীক্ষা করো। ঐচ্ছিক approved_amount_atomic allocation freeze-এর আগে ছোট fully backed split স্পষ্টভাবে গ্রহণ করে; প্রাপ্ত অর্থ বানিয়ে দেখায় না।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopereconciliation.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/release" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1,
  "reason": "Verified payment evidence"
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

revision

1

reason

"যাচাই করা পেমেন্ট প্রমাণ"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • reconciliation.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTঅপরিশোধিত অংশের গন্তব্য আবার যুক্ত করো/v1/marketplace/invoices/{invoice_id}/allocations/{allocation_id}/destinationপড়া + লেখা

Allocation revision লাগে। শুধু unreserved/unsigned কাজ আর মূল network-এ একই vendor-এর আলাদাভাবে approved version। Audited; signed কাজ বদলানো যায় না।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopereconciliation.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/YOUR_ALLOCATION_ID/destination" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1,
  "destination_id": "YOUR_DESTINATION_ID",
  "reason": "Vendor verified replacement address"
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

revision

1

destination_id

"YOUR_DESTINATION_ID"

reason

"বিক্রেতার যাচাই করা বিকল্প ঠিকানা"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • reconciliation.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTপূর্ণ রিফান্ড প্রস্তুত করো/v1/marketplace/invoices/{invoice_id}/refundপড়া + লেখা

আলাদাভাবে অনুমোদনের জন্য same-asset full received-amount refund প্রস্তুত করো। Vendor payout-এর আগে unpaid fund reserve করো আর confirmation-এ commission reverse করো। সব vendor payout-এর পরে আলাদা free primary-address fund ব্যবহার করো। Sender দেখে customer refund address অনুমান কোরো না।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopereconciliation.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/refund" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1,
  "payment_method_id": "YOUR_PAYMENT_METHOD_ID",
  "destination_address": "VERIFIED_CUSTOMER_REFUND_ADDRESS",
  "reason": "Customer cancellation",
  "maximum_network_fee_atomic": "10000",
  "maximum_gas_funding_atomic": "0",
  "fee_tier": "medium"
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

revision

1

payment_method_id

"YOUR_PAYMENT_METHOD_ID"

destination_address

"VERIFIED_CUSTOMER_REFUND_ADDRESS"

reason

"গ্রাহকের বাতিল অনুরোধ"

maximum_network_fee_atomic

"10000"

maximum_gas_funding_atomic

"0"

fee_tier

"medium"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • reconciliation.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETপেআউটের বণ্টন খোঁজো/v1/marketplace/allocationsশুধু পড়া

পৃষ্ঠাভাগ করা candidate; status (available ইত্যাদি), asset_id, vendor_id, store_id আর q (vendor/order/invoice) filter।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/allocations?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

Response field

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETপ্রকল্পের ledger balance/v1/marketplace/balancesশুধু পড়া

Held, available, reserved, paid, commission, refund আর network fee-সহ সঠিক grouped asset/account total। External balancing account বাদ।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/balances?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETঅপরিবর্তনীয় journal/v1/marketplace/ledgerশুধু পড়া

পৃষ্ঠাভাগ করা append-only movement; q reference/account, asset_id আর vendor_id filter। Amount atomic string; entry edit বা ম্যানুয়ালি paid করা যায় না।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/ledger?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

Response field

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETপেআউটের ইতিহাস/v1/marketplace/payoutsশুধু পড়া

পৃষ্ঠাভাগ করা parent; state, asset_id, vendor_id বা q ID/symbol filter। Paid মানে independent confirmation, শুধু broadcast নয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/payouts?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

Response field

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTবণ্টন পরিকল্পনার preview/v1/marketplace/payouts/previewপড়া + লেখা

Read-only accounting plan, reservation বা spend authority নয়। Maximum fee user cap, অনুমান করা actual fee নয়। পরে preparation-এ live check হয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopepayouts.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/payouts/preview" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "allocation_ids": [
    "YOUR_ALLOCATION_ID"
  ],
  "maximum_network_fee_atomic": "10000",
  "maximum_gas_funding_atomic": "0",
  "fee_tier": "medium"
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

allocation_ids[]

["YOUR_ALLOCATION_ID"]

maximum_network_fee_atomic

"10000"

maximum_gas_funding_atomic

"0"

fee_tier

"medium"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • payouts.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTপেআউট প্রস্তুত করো/v1/marketplace/payoutsপড়া + লেখা

এক asset/wallet-এ 1–100 available allocation ID reserve করো। BTC-তে প্রতিটি বাছাই করা invoice-এর সব unpaid share একই multi-output batch-এ লাগে। Budget native fee asset-এর atomic string। awaiting_approval plan তৈরি করে, broadcast নয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopepayouts.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/payouts" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "allocation_ids": [
    "YOUR_ALLOCATION_ID"
  ],
  "maximum_network_fee_atomic": "10000",
  "maximum_gas_funding_atomic": "0",
  "fee_tier": "medium"
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

allocation_ids[]

["YOUR_ALLOCATION_ID"]

maximum_network_fee_atomic

"10000"

maximum_gas_funding_atomic

"0"

fee_tier

"medium"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {
    "id": "YOUR_PAYOUT_ID",
    "state": "awaiting_approval",
    "revision": 1,
    "plan_hash": "RETAINED_PLAN_HASH",
    "plan": {
      "amount_atomic": "28800000",
      "maximum_network_fee_atomic": "10000",
      "maximum_gas_funding_atomic": "0",
      "items": []
    },
    "transactions": []
  }
}

Response field

dataobject
idstring
statestring
revisioninteger
plan_hashstring
planobject
amount_atomicstring
maximum_network_fee_atomicstring
maximum_gas_funding_atomicstring
items[]array
transactions[]array
ব্যবহারের নোট
  • payouts.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETপেআউটের বিস্তারিত/v1/marketplace/payouts/{payout_id}শুধু পড়া

অপরিবর্তনীয় plan/hash, revision, expiry, recipient item, সংরক্ষিত child attempt, progress, exact fee আর explorer link। Private key বা signed byte নয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {
    "id": "YOUR_PAYOUT_ID",
    "state": "awaiting_approval",
    "revision": 1,
    "plan_hash": "RETAINED_PLAN_HASH",
    "plan": {
      "amount_atomic": "28800000",
      "maximum_network_fee_atomic": "10000",
      "maximum_gas_funding_atomic": "0",
      "items": []
    },
    "transactions": []
  }
}

Response field

dataobject
idstring
statestring
revisioninteger
plan_hashstring
planobject
amount_atomicstring
maximum_network_fee_atomicstring
maximum_gas_funding_atomicstring
items[]array
transactions[]array
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTঅনুমোদন করে পাঠাও/v1/marketplace/payouts/{payout_id}/approveপড়া + লেখা

মেয়াদের মধ্যে সঠিক retained plan স্পষ্টভাবে অনুমোদন করো। সীমিত gas funding আর vendor transaction background-এ queue করো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopepayouts.approve

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/approve" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1,
  "expected_plan_hash": "COPY_EXACT_PLAN_HASH_FROM_PREPARE",
  "confirm": true
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

revision

1

expected_plan_hash

"COPY_EXACT_PLAN_HASH_FROM_PREPARE"

confirm

true

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • payouts.approve লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTপেআউট পর্যালোচনা করে আবার চালাও/v1/marketplace/payouts/{payout_id}/resumeপড়া + লেখা

শুধু needs_attention। Retained plan/hash আবার নাও; confirmed recipient-কে আবার পাঠায় না। Failed child replace করার আগে দুই independent provider-এ canonical sufficiently confirmed EVM revert প্রমাণিত হতে হবে। আগের fee approved budget-এ গোনা হয় এবং সব hash history-তে থাকে। Unknown/partial token delivery-তে payout_recovery_unverified; reservation hold থাকে।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopepayouts.approve

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/resume" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1,
  "expected_plan_hash": "COPY_EXACT_PLAN_HASH_FROM_PREPARE",
  "confirm": true
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

revision

1

expected_plan_hash

"COPY_EXACT_PLAN_HASH_FROM_PREPARE"

confirm

true

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • payouts.approve লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTস্বাক্ষর না করা কাজ বাতিল করো/v1/marketplace/payouts/{payout_id}/cancelপড়া + লেখা

শুধু নিরাপদ unsigned/unsubmitted reservation ছাড়ো। Confirmed recipient আর audit থাকে। Signed/uncertain কাজ বাতিল হয় না। স্পষ্টভাবে recovered, proven revert অবশিষ্ট unsigned কাজ বাতিলে আর বাধা দেয় না।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopepayouts.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/cancel" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

revision

1

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • payouts.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETস্বয়ংক্রিয় পেআউট নীতি/v1/marketplace/policiesশুধু পড়া

Per-asset policy, revision, next_attempt_at, last_checked_at আর preparation/authorization-এ সমস্যা হলে নিরাপদ last_error পড়ো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/policies?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": []
}

Response field

data[]array
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTপেআউট নীতির অনুমতি দাও/v1/marketplace/policiesপড়া + লেখা

সঠিক atomic string; minimum <= transfer <= daily principal, fee/gas cap <= তাদের daily budget। interval_seconds 60–604800; minimum_confirmations 1–100000, chain floor অনুযায়ী। Revision 0 তৈরি করে। Enabled policy আর click ছাড়াই পাঠাতে পারে; review-এর আগে false রাখো।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopepolicies.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/policies" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "asset_id": "YOUR_ASSET_ID",
  "revision": 0,
  "enabled": false,
  "minimum_atomic": "100000",
  "transfer_limit_atomic": "10000000",
  "daily_limit_atomic": "30000000",
  "fee_limit_atomic": "10000",
  "daily_fee_limit_atomic": "30000",
  "gas_limit_atomic": "0",
  "daily_gas_limit_atomic": "0",
  "interval_seconds": 3600,
  "minimum_confirmations": 2
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

asset_id

"YOUR_ASSET_ID"

revision

0

enabled

false

minimum_atomic

"100000"

transfer_limit_atomic

"10000000"

daily_limit_atomic

"30000000"

fee_limit_atomic

"10000"

daily_fee_limit_atomic

"30000"

gas_limit_atomic

"0"

daily_gas_limit_atomic

"0"

interval_seconds

3600

minimum_confirmations

2

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • policies.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETমার্কেটপ্লেসের webhook/v1/marketplace/webhooksশুধু পড়া

সর্বোচ্চ ২০ endpoint আর supported event_types। Encrypted বা plaintext signing secret ফেরত দেয় না।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/webhooks?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {
    "endpoints": [],
    "event_types": [
      "marketplace.invoice.created",
      "marketplace.allocations.available",
      "marketplace.allocations.held",
      "marketplace.payout.approved",
      "marketplace.payout.broadcast",
      "marketplace.payout.confirmed",
      "marketplace.payout.partial",
      "marketplace.payout.failed",
      "marketplace.payout.cancelled",
      "marketplace.refund.prepared",
      "marketplace.refund.confirmed"
    ]
  }
}

Response field

dataobject
endpoints[]array
event_types[]array
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTমার্কেটপ্লেস webhook তৈরি করো/v1/marketplace/webhooksপড়া + লেখা

শুধু public HTTPS, credential, private destination বা redirect নয়। Retained idempotent create response-এ signing_secret একবার ফেরত দেয়; নিরাপদে রাখো। Store IPN secret থেকে আলাদা।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopewebhooks.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/webhooks" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "url": "https://shop.example.com/marketplace-events",
  "enabled": true,
  "events": [
    "marketplace.payout.confirmed",
    "marketplace.payout.failed"
  ]
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

url

"https://shop.example.com/marketplace-events"

enabled

true

events[]

["marketplace.payout.confirmed","marketplace.payout.failed"]

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • webhooks.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTমার্কেটপ্লেস webhook আপডেট করো/v1/marketplace/webhooks/{webhook_id}/updateপড়া + লেখা

পরিবর্তনে পুরোনো unsent delivery বাতিল হয়। Secret বদলায় না; পুরোনো immutable payload নতুন URL-এ পাঠানো হয় না।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopewebhooks.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/webhooks/YOUR_WEBHOOK_ID/update" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1,
  "url": "https://shop.example.com/marketplace-events",
  "enabled": true,
  "events": [
    "marketplace.payout.confirmed"
  ]
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

revision

1

url

"https://shop.example.com/marketplace-events"

enabled

true

events[]

["marketplace.payout.confirmed"]

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • webhooks.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTমার্কেটপ্লেস webhook বন্ধ করো/v1/marketplace/webhooks/{webhook_id}/disableপড়া + লেখা

নতুন delivery বন্ধ করো; retained event history থাকে।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopewebhooks.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/webhooks/YOUR_WEBHOOK_ID/disable" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

revision

1

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • webhooks.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETমার্কেটপ্লেসের event/v1/marketplace/eventsশুধু পড়া

পৃষ্ঠাভাগ করা immutable event reference। q type/reference খোঁজে; status event_type filter করে।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/events?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

Response field

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETসংরক্ষিত event পড়ো/v1/marketplace/events/{event_id}শুধু পড়া

বর্তমান balance থেকে নতুন করে বানানো নয়, অপরিবর্তনীয় মূল event payload ফেরত দেয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/events/YOUR_EVENT_ID?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {
    "event_id": "11111111-1111-4111-8111-111111111111",
    "event_type": "marketplace.payout.confirmed",
    "payload_version": 1,
    "project_id": "YOUR_PROJECT_ID",
    "occurred_at": "2026-10-06T12:00:00Z",
    "data": {
      "payout_id": "YOUR_PAYOUT_ID",
      "asset_id": "YOUR_ASSET_ID",
      "amount_atomic": "28800000",
      "transactions": [
        {
          "transaction_id": "EXAMPLE_TRANSACTION_ID",
          "explorer_url": "https://mempool.space/tx/EXAMPLE_TRANSACTION_ID"
        }
      ]
    }
  }
}

Response field

dataobject
event_idstring
event_typestring
payload_versioninteger
project_idstring
occurred_atstring
dataobject
payout_idstring
asset_idstring
amount_atomicstring
transactions[]object[]
transaction_idstring
explorer_urlstring
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETমার্কেটপ্লেসের delivery history/v1/marketplace/webhook-deliveriesশুধু পড়া

পৃষ্ঠাভাগ করা delivery, event type, attempt আর last result। status pending/sending/succeeded/failed/cancelled filter; q event type।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/webhook-deliveries?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

Response field

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETDelivery-এর বিস্তারিত/v1/marketplace/webhook-deliveries/{delivery_id}শুধু পড়া

মূল URL, retained payload, HTTP result আর safe error; signing secret নয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopemarketplace.read

Query parameter

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

per_pageঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

qঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

statusঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

store_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

vendor_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

asset_idঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

fromঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

toঐচ্ছিক

শুধু এই resource-এর documented filter ব্যবহার করো। Paged list ডিফল্ট ২৫, সর্বোচ্চ ১০০ row।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/webhook-deliveries/YOUR_DELIVERY_ID?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • marketplace.read লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTএকই event আবার পাঠাও/v1/marketplace/webhook-deliveries/{delivery_id}/resendপড়া + লেখা

শুধু finished delivery আর অপরিবর্তিত active endpoint; সর্বোচ্চ ২০ manual retry। event_id একই থাকে। Failed notification কখনো দ্বিতীয় payment-এর অনুমতি দেয় না।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyবাধ্যতামূলক16–128 letter, digit, -, _ বা .; এই হুবহু request-এর সঙ্গে স্থায়ীভাবে রাখো
Parameterধরন / অবস্থাননিয়ম
permissioncredential scopewebhooks.write

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/webhook-deliveries/YOUR_DELIVERY_ID/resend" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "confirm": true
}'

Request body

project_idUUIDবাধ্যতামূলক

অনুমোদিত project। Item URL-সহ প্রতিটি request-এ দরকার।

confirm

true

উত্তর 200 application/json

উদাহরণ response
{
  "data": {}
}

Response field

dataobject
ব্যবহারের নোট
  • webhooks.write লাগে। Response উদাহরণে বাছাই করা field; পুরো retained evidence-এর জন্য resource GET করো।
  • প্রতিটি POST-এ স্থায়ীভাবে রাখা 16–128 অক্ষরের Idempotency-Key লাগে (letter, digit, -, _ বা .)। Timeout হলে একই key আর JSON instruction ব্যবহার করো। ভিন্ন instruction-এ 409। Completed response ৩০ দিন থাকে; পুরোনো key পুনরায় ব্যবহার অযোগ্য tombstone হয়। অনিশ্চিত ফল এড়াতে শুধু key বদলিও না।
  • Key-তে project list, ঐচ্ছিক invoice-store restriction, expiry, IP allowlist আর 1–600/minute quota থাকে (ডিফল্ট ৬০)। HTTP 429-এ Retry-After থাকে। Store-limited key vendor, project balance, ledger, payout বা settings দেখতে পারে না। অর্থ খরচের credential শুধু বিশ্বস্ত server-এ রাখো, browser বা বিতরণ করা mobile app-এ নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETপেমেন্টের ব্যতিক্রমের তালিকা/v1/projects/{project_id}/reconciliationশুধু পড়া

Underpaid, overpaid, late, reorged বা ambiguous payment, failed delivery আর disabled/expired method-এর জন্য একটি paginated review queue। Operator acknowledged case নতুন evidence এলে আবার খোলে।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MERCHANT_API_TOKEN

Path parameter

project_idUUIDবাধ্যতামূলক

এই credential-এ দেওয়া project।

Query parameter

statusstring

open (ডিফল্ট), resolved বা all।

reasonstring

underpaid, overpaid, late, reorged, ambiguous, delivery_failed, disabled_method বা expired_method।

store_idUUID

ঐচ্ছিক store filter।

pageinteger

1–40001। প্রতি পৃষ্ঠায় নির্দিষ্ট ২৫ case।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/reconciliation?status=open&page=1" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{"data":[],"pagination":{"page":1,"per_page":25,"total":0,"has_more":false},"counts":{"open":0,"resolved":0}}

Response field

data[]object[]সব সময়

সবচেয়ে নতুন আপডেটের case আগে। Merchant detail URL-এ invoice_id নাও, internal id নয়।

idUUIDসব সময়

Internal record ID / customer-facing invoice UUID। invoice_id callback payload-এর সঙ্গে মেলে।

invoice_idUUIDসব সময়

Internal record ID / customer-facing invoice UUID। invoice_id callback payload-এর সঙ্গে মেলে।

store_idUUIDসব সময়

মালিকানাধীন store।

store_namestringসব সময়

মালিকানাধীন store।

order_idstring | nullসব সময়

ব্যক্তিগত merchant order reference আর customer email।

emailstring | nullসব সময়

ব্যক্তিগত merchant order reference আর customer email।

amountdecimal stringসব সময়

মূল fiat invoice amount আর currency।

currencystringসব সময়

মূল fiat invoice amount আর currency।

invoice_statusinvoice statusসব সময়

বর্তমান payment lifecycle status।

statusopen|resolvedসব সময়

Case state আর reason filter-এর exception type।

reasons[]string[]সব সময়

Case state আর reason filter-এর exception type।

revisionintegerসব সময়

বর্তমান review revision আর update time।

updated_attimestampসব সময়

বর্তমান review revision আর update time।

paginationobjectসব সময়

page (1–40001), per_page (25), মোট মেলা row, has_more।

pageinteger
per_pageinteger
totalinteger
has_moreboolean
countsobjectসব সময়

বর্তমান filter থেকে স্বাধীন পুরো project-এর open আর resolved total।

openinteger
resolvedinteger
ব্যবহারের নোট
  • Read-only, project-scoped আর credential quota-র অধীনে। আর্থিক সিদ্ধান্ত আর refund শুধু console-এ।
  • Row-তে id (internal UUID), invoice_id (public UUID, callback-এর মতো), store info, মূল fiat amount/currency, invoice_status, case status, reason, revision আর updated_at থাকে। Merchant detail endpoint-এ invoice_id নাও।
  • Automatic detection মূল invoice monitoring window মেনে চলে; Rescan checkout চালু না করে observation এক ঘণ্টা বাড়ায়। Post-settlement/cancelled method সেই window-তে পর্যবেক্ষিত থাকে।

ত্রুটি

Error code ও retry-এর নিয়ম

GETহিসাব মেলানোর প্রমাণ পড়ো/v1/projects/{project_id}/reconciliation/{invoice_id}শুধু পড়া

Invoice, case, exact method total আর available refund amount, observed transaction, delivery history, merchant decision আর linked refund transfer ফেরত দেয়। Signing key বা callback secret প্রকাশ করে না।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MERCHANT_API_TOKEN

Path parameter

project_idUUIDবাধ্যতামূলক

নির্ধারিত project।

invoice_idUUIDবাধ্যতামূলক

Public invoice UUID, internal id নয়।

Query parameter

pageinteger

Decision-history page, ১ থেকে শুরু; প্রতি পৃষ্ঠায় ২৫ decision।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/reconciliation/YOUR_PUBLIC_INVOICE_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{"invoice":{"invoice_id":"YOUR_PUBLIC_INVOICE_ID","status":"processing"},"case":{"status":"open","reasons":["underpaid"],"revision":1},"methods":[],"history":[],"history_pagination":{"page":1,"per_page":25,"total":0},"refunds":[],"observations":[],"deliveries":[]}

Response field

invoiceobjectসব সময়

পূর্ণ merchant invoice: summary field, private metadata আর payment_intents। data-তে মোড়ানো নয়।

idUUIDসব সময়

Internal invoice UUID। Merchant detail বা checkout path-এ ব্যবহার কোরো না।

invoice_idUUIDসব সময়

Merchant detail আর checkout path-এ ব্যবহৃত public invoice UUID।

project_idUUIDসব সময়

মালিকানাধীন project।

store_idUUIDসব সময়

মালিকানাধীন store।

sourcemanual | apiসব সময়

ইনভয়েস কীভাবে তৈরি হয়েছিল।

order_idstring | nullসব সময়

Merchant order reference।

emailstring | nullসব সময়

শুধু merchant-এর customer email। Public checkout-এ ফেরত আসে না।

customer_namestring | nullসব সময়

Private firstname, lastname আর company metadata থেকে তৈরি display name।

customer_addressstring | nullসব সময়

Private company, street, street2, zip, city, country, countryiso2 আর vatid metadata থেকে তৈরি এক লাইনের merchant address।

descriptionstring | nullসব সময়

Customer-facing description।

amountdecimal stringসব সময়

Canonical invoice amount।

currencystringসব সময়

Normalized invoice currency/asset code।

exchange_rate_spread_percentdecimal stringসব সময়

Locked quote spread: creation override, না দিলে store default। Upward rounding-এর আগে লাগে; এই invoice-এ আর বদলায় না।

underpayment_tolerance_percentdecimal stringসব সময়

Invoice তৈরির সময় snapshot হওয়া অপরিবর্তনীয় accepted shortfall percentage।

statusinvoice statusসব সময়

new, processing, settled, expired, invalid বা cancelled।

amount_statusamount statusসব সময়

none, partial, paid বা overpaid। স্পষ্টভাবে অনুমোদিত zero-amount invoice none আর payment method ছাড়াই settled হয়।

timing_statustiming statusসব সময়

on_time বা late।

resolutionresolutionসব সময়

automatic, manually_settled বা manually_invalidated।

sequenceintegerসব সময়

ক্রমশ বাড়তে থাকা invoice state sequence, ১ থেকে শুরু।

winning_payment_intent_idUUID | nullসব সময়

বাছাই হলে যে payment method invoice resolve করেছে।

expires_atRFC 3339 timestampসব সময়

Quote/payment deadline।

monitoring_expires_atRFC 3339 timestampসব সময়

সব method-এর মধ্যে সর্বশেষ configured late-monitoring cutoff।

settled_attimestamp | nullসব সময়

Settled হলে settlement time।

cancelled_attimestamp | nullসব সময়

Cancelled হলে cancellation time।

archived_attimestamp | nullসব সময়

Archived হলে archival time।

created_atRFC 3339 timestampসব সময়

তৈরির সময়।

updated_atRFC 3339 timestampসব সময়

শেষ state update-এর সময়।

ipn_urlstring | nullসব সময়

কার্যকর per-invoice IPN target। শুধু merchant response; public checkout-এ নেই।

redirect_urlstring | nullসব সময়

Settlement-এর পরে ব্যবহৃত কার্যকর success URL।

cancel_urlstring | nullসব সময়

সফল payment ছাড়া checkout শেষ হলে কার্যকর return URL।

redirect_automaticallybooleanসব সময়

সফলতার পরে checkout নিজে থেকে redirect করবে কি না।

checkout_languagestringসব সময়

কার্যকর checkout language tag।

metadataobjectসব সময়
Merchant metadata। Public checkout-এ ফেরত আসে না। Console payment tool payment_tool provenance যোগ করে (id, kind, title, pricing, requested_amount, request_id); পেমেন্টের প্রমাণ নয়। Callback authenticate করে প্রতি invoice_id-তে invoice.settled একবারই fulfil করো।বিস্তারিত

Merchant metadata। Public checkout-এ ফেরত আসে না। Console payment tool payment_tool provenance যোগ করে (id, kind, title, pricing, requested_amount, request_id); পেমেন্টের প্রমাণ নয়। Callback authenticate করে প্রতি invoice_id-তে invoice.settled একবারই fulfil করো।

payment_intents[]object[]সব সময়

Quoted payment method আর monitoring state।

idUUIDসব সময়

Payment intent identifier; checkout QR intent_id হিসেবেও ব্যবহৃত।

payment_railonchain | lightningসব সময়
Invoice transport। Bitcoin on-chain আর Lightning একই asset_id ভাগ করতে পারে; শুধু symbol নয়, intent id আর এই field ব্যবহার করো। Asset catalog-এর scanner payment_rail থেকে এটি আলাদা।বিস্তারিত

Invoice transport। Bitcoin on-chain আর Lightning একই asset_id ভাগ করতে পারে; শুধু symbol নয়, intent id আর এই field ব্যবহার করো। Asset catalog-এর scanner payment_rail থেকে এটি আলাদা।

bolt11string | nullসব সময়

Lightning payment request, নইলে null। Lightning wallet দিয়ে request-এ pay করো, payment hash-এ on-chain fund পাঠিয়ো না।

asset_idUUIDসব সময়

Configured payment asset identifier।

asset_keystringসব সময়

Canonical CAIP-style asset key।

chain_slugstringসব সময়

Wholly Crypto chain identifier।

networkstringসব সময়

Configured network, supported payment asset-এর জন্য বর্তমানে mainnet।

caip_network_idstringসব সময়

Canonical CAIP-2 network identifier।

caip_asset_idstring | nullসব সময়

নিবন্ধিত হলে canonical CAIP-19 identifier।

symbolstringসব সময়

Asset symbol।

asset_decimalsintegerসব সময়

Atomic-unit precision। Lightning BTC-তে 11 (millisatoshi), on-chain Bitcoin-এর 8 নয়। Quote পূর্ণ satoshi; receipt-এ millisatoshi precision থাকে।

statusintent statusসব সময়

pending, partial, paid, overpaid, expired বা invalid।

finality_modeconfirmations | finalizedসব সময়

Finality policy।

required_confirmationsintegerসব সময়

প্রযোজ্য হলে প্রয়োজনীয় confirmation।

quote_ratedecimal stringসব সময়

Locked spread-সহ প্রতি এক invoice currency unit-এ asset unit। যেমন প্রতি USD-এ 1.02 USDC। উল্টো rate নয়।

quote_detailsobject | nullসব সময়
Locked quote provenance: spread-এর আগে reference_rate, unrounded_payment_amount, rounding_adjustment, pricing_provider, asset_provider, pricing_fetched_at আর asset_fetched_at। পুরোনো invoice-এ null; পুরোনো মান বানানো হয় না।বিস্তারিত

Locked quote provenance: spread-এর আগে reference_rate, unrounded_payment_amount, rounding_adjustment, pricing_provider, asset_provider, pricing_fetched_at আর asset_fetched_at। পুরোনো invoice-এ null; পুরোনো মান বানানো হয় না।

expected_amountdecimal stringসব সময়
Spread আর upward rounding-এর পরে পরিশোধের সঠিক locked asset amount। 4.1.1 থেকে চেনা verified fiat stablecoin (যেমন USDC, USDT, DAI, USDS, EURC) সর্বোচ্চ দুই decimal-এ ওপরের দিকে round হয়; 1.321 হয় 1.33, কখনো 1.32 নয়। Zero tolerance-এও এটাই expected amount। অন্য asset adaptive precision রাখে। আগের invoice-এর দাম বদলায় না।বিস্তারিত

Spread আর upward rounding-এর পরে পরিশোধের সঠিক locked asset amount। 4.1.1 থেকে চেনা verified fiat stablecoin (যেমন USDC, USDT, DAI, USDS, EURC) সর্বোচ্চ দুই decimal-এ ওপরের দিকে round হয়; 1.321 হয় 1.33, কখনো 1.32 নয়। Zero tolerance-এও এটাই expected amount। অন্য asset adaptive precision রাখে। আগের invoice-এর দাম বদলায় না।

expected_amount_atomicinteger stringসব সময়

Asset-এর সবচেয়ে ছোট এককে সঠিক amount।

minimum_payment_amountdecimal stringসব সময়

Invoice tolerance প্রয়োগের পরে paid হিসেবে গৃহীত সবচেয়ে ছোট amount।

minimum_payment_amount_atomicinteger stringসব সময়

Asset-এর সবচেয়ে ছোট এককে সঠিক accepted threshold।

received_amountdecimal stringসব সময়

দেখা amount।

received_amount_atomicinteger stringসব সময়

দেখা atomic amount।

confirmed_amountdecimal stringসব সময়

Confirmed/final amount।

confirmed_amount_atomicinteger stringসব সময়

Confirmed/final atomic amount।

destination_addressstringসব সময়

On-chain receiving address, অথবা Lightning-এর ৬৪ অক্ষরের payment hash। Lightning-এ pay করতে bolt11 নাও; hash Bitcoin address নয়।

destination_tagstring | nullসব সময়

প্রযোজ্য পথে দরকারি public payment reference: XRP destination tag, Stellar memo ID বা TON invoice comment। Unique-address পথে null।

derivation_indexintegerসব সময়

Reserved wallet child index; শুধু merchant detail।

quote_expires_atRFC 3339 timestampসব সময়

Quote expiry।

monitoring_expires_atRFC 3339 timestampসব সময়

এই method-এর late-monitoring cutoff।

next_check_attimestamp | nullসব সময়

পরের নির্ধারিত chain check।

last_checked_attimestamp | nullসব সময়

শেষ chain check।

last_chain_heightinteger | nullসব সময়

Monitor-এর দেখা সর্বশেষ বিশ্বস্ত height।

last_anchor_hashstring | nullসব সময়

শেষ monitor anchor/block hash।

last_monitor_errorstring | nullসব সময়

Operator-এর জন্য নিরাপদ monitoring diagnostic।

first_payment_attimestamp | nullসব সময়

প্রথম পেমেন্ট দেখার সময়।

fully_paid_attimestamp | nullসব সময়

গ্রহণযোগ্য minimum amount প্রথম পৌঁছানোর সময়।

finalized_attimestamp | nullসব সময়

পেমেন্ট finality policy পূরণের সময়।

caseobject | nullসব সময়

Status, reason, revision আর timestamp-সহ current case; exception না থাকলে null। Internal evidence বাদ।

statusstring
reasons[]array
revisioninteger
methods[]object[]সব সময়
id, wallet_id, asset_id, symbol, chain, decimals, expected_atomic, received_atomic, confirmed_atomic, refundable_atomic, address, tag, monitor_error, last_checked_at, monitoring_expires_at আর spending_supported। Atomic amount string।বিস্তারিত

id, wallet_id, asset_id, symbol, chain, decimals, expected_atomic, received_atomic, confirmed_atomic, refundable_atomic, address, tag, monitor_error, last_checked_at, monitoring_expires_at আর spending_supported। Atomic amount string।

history[]object[]সব সময়

এই পৃষ্ঠার সর্বশেষ ২৫ decision: id, action, note, actor, result, created_at।

history_paginationobjectসব সময়

page, per_page (25), total। শুধু decision history page দিয়ে ভাগ করা।

pageinteger
per_pageinteger
totalinteger
refunds[]object[]সব সময়
সর্বশেষ ১০০ refund: id, payment_intent_id, amount_atomic, destination, status, request, treasury_intent_id, transfer_status, created_at আর transactions (id/status)। Refund submit শুধু console-এ।বিস্তারিত

সর্বশেষ ১০০ refund: id, payment_intent_id, amount_atomic, destination, status, request, treasury_intent_id, transfer_status, created_at আর transactions (id/status)। Refund submit শুধু console-এ।

observations[]object[]সব সময়
সর্বশেষ ১০০: payment_intent_id, transaction_id, event_index, amount, status, confirmations, observed_at, symbol, chain আর disabled_at_detection। সমর্থিত হলে explorer_name/explorer_url থাকে।বিস্তারিত

সর্বশেষ ১০০: payment_intent_id, transaction_id, event_index, amount, status, confirmations, observed_at, symbol, chain আর disabled_at_detection। সমর্থিত হলে explorer_name/explorer_url থাকে।

deliveries[]object[]সব সময়

সর্বশেষ ৫০: id, kind, status, attempts, response_status, error, next_attempt_at, event_type আর created_at। Callback secret নয়।

ব্যবহারের নোট
  • Invoice-এ exception না হলে case null। সর্বশেষ ১০০ observation আর ৫০ delivery আসে; decision history paginated।
  • refundable_atomic-এ অন্তত এক network confirmation লাগে, আগের refund reservation বাদ থাকে, আর spendable wallet fund-এর প্রতিশ্রুতি নয়। Live quote-এ wallet readiness, source balance আর fee-ও যাচাই হয়।
  • Broadcast refund মানে chain endpoint-এ submit, customer-এর confirmed receipt স্বাধীনভাবে প্রমাণিত নয়। Fee আলাদা; refund দিলেই fiat processing fee নিজে থেকে credit হয় না।
  • Console project menu → Needs attention-এ cancel, accept, reject, reopen, review, note, Rescan, delivery retry আর supported-chain refund আছে। Decision-এ CSRF-protected session, unique request_id, current case revision, বাধ্যতামূলক note আর explicit confirmation লাগে; bearer token এই পরিবর্তন চালাতে পারে না।

ত্রুটি

Error code ও retry-এর নিয়ম

GETAPI পরিষেবা আবিষ্কার/পাবলিক

Managed API-host edge response v1 public API role নিশ্চিত করে। এই response managed proxy দেয়, merchant Axum router নয়।

Authentication ও header

পাবলিক

অনুরোধ

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/"

উত্তর 200 application/json

উদাহরণ response
{
  "service": "Wholly Crypto API",
  "status": "ready",
  "version": "v1"
}

Response field

servicestring
statusstring
versionstring
ব্যবহারের নোট
  • Bearer token লাগে না।
  • শুধু managed API hostname এই সঠিক root response নিশ্চিত করে।

ত্রুটি

Error code ও retry-এর নিয়ম

GETপরিষেবার অবস্থা/healthzপাবলিক

Application reachability আর দুই সেকেন্ডের database ping পরীক্ষা করে। Monitoring-এর জন্য, invoice status-এর বিকল্প নয়।

Authentication ও header

পাবলিক

অনুরোধ

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/healthz"

উত্তর 200 healthy; 503 database unavailable

উদাহরণ response
{
  "status": "ok",
  "database": "ok",
  "version": "0.1.0"
}

Response field

statusstring
databasestring
versionstring
ব্যবহারের নোট
  • Bearer token লাগে না।
  • Version হলো চলা package version, API path version নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETপ্রকল্পের পেমেন্ট অ্যাসেটের তালিকা/v1/projects/{project_id}/payment-assetsশুধু পড়া

Project policy, chain-wallet readiness আর installed scanner/balance capability-সহ native asset আর verified token তালিকা দেয়। scanner_ready adapter-build gate, live endpoint quorum result নয়। 6.0.6 থেকে scanner downtime-এ configured method creation-এ থাকে। Receiving verification-এ configured healthy exact-role provider threshold লাগে (ডিফল্ট ২, চাইলে ১)।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MERCHANT_API_TOKEN
Acceptপ্রস্তাবিতapplication/json

Path parameter

project_idUUIDবাধ্যতামূলক

Credential-এ দেওয়া enabled project।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-assets" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Accept: application/json'

উত্তর 200 application/json

উদাহরণ response
{
  "data": [
    {
      "asset": {
        "id": "10000000-0000-4000-8000-000000000003",
        "asset_key": "eip155:1/slip44:60",
        "chain_slug": "ethereum",
        "network": "mainnet",
        "caip_network_id": "eip155:1",
        "caip_asset_id": "eip155:1/slip44:60",
        "asset_kind": "native",
        "payment_rail": "evm-native",
        "symbol": "ETH",
        "name": "Ethereum",
        "decimals": 18,
        "contract_address": null,
        "coingecko_id": "ethereum",
        "icon_path": "/assets/coingecko/ethereum.png",
        "token_standard": null,
        "metadata_verified_at": null,
        "payment_supported": true,
        "scanner_ready": true,
        "balance_ready": true,
        "default_finality_mode": "confirmations",
        "default_required_confirmations": 12,
        "default_monitoring_minutes": 60
      },
      "policy": {
        "enabled": true,
        "finality_mode": "confirmations",
        "required_confirmations": 12,
        "monitoring_minutes": 60,
        "late_monitoring_days": 30
      },
      "wallet": null,
      "wallet_readiness": "wallet_missing",
      "receive_readiness": { "ready": false, "invoice_creatable": false, "checked_at": "2026-09-16T09:00:00Z", "issues": [{ "chain_slug": "ethereum", "asset_id": "10000000-0000-4000-8000-000000000003", "asset_ticker": "ETH", "reason_code": "wallet_missing", "message": "ethereum / ETH: Create a project wallet for this chain.", "action": "wallets" }] }
    }
  ]
}

Response field

data[]object[]
assetobjectসব সময়

স্থায়ী native বা verified token asset।

idUUIDসব সময়

Project আর store policy route-এ ব্যবহৃত স্থায়ী payment-asset identifier।

asset_keystringসব সময়

Canonical CAIP-style native বা contract asset identity।

chain_slugstringসব সময়

Wholly Crypto chain identifier আর configured network।

networkstringসব সময়

Wholly Crypto chain identifier আর configured network।

caip_network_idstringসব সময়

Canonical network আর asset identity।

caip_asset_idstring|nullসব সময়

Canonical network আর asset identity।

asset_kindnative | tokenসব সময়

Settlement chain currency নাকি verified contract/mint ব্যবহার করে।

payment_railstringসব সময়

Runtime rail: utxo, evm-native, solana-native, account-native, privacy-native বা token-transfer।

symbolstringসব সময়

দেখানোর identity আর সঠিক atomic-unit precision।

namestringসব সময়

দেখানোর identity আর সঠিক atomic-unit precision।

decimalsintegerসব সময়

দেখানোর identity আর সঠিক atomic-unit precision।

contract_addressstring | nullসব সময়

Token-এর canonical ERC-20 contract বা SPL mint; native asset-এ null।

coingecko_idstring | nullসব সময়

Discovery/pricing identity। Custom contract-এ null; ticker দেখে market price অনুমান কোরো না। শুধু CoinGecko metadata টোকেনকে selectable করে না।

custom_tokenbooleanসব সময়

Project-scoped fixed USD বা selected DEX pool pricing-সহ custom on-chain-verified contract।

icon_pathpath | nullসব সময়

পাওয়া গেলে locally cached token icon।

token_standarderc20 | spl-token | nullসব সময়

Verified runtime token standard; native asset-এ null।

metadata_verified_attimestamp | nullসব সময়

Promoted token-এর on-chain metadata verification time।

payment_supportedbooleanসব সময়
Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।বিস্তারিত

Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।

scanner_readybooleanসব সময়
Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।বিস্তারিত

Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।

balance_readybooleanসব সময়
Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।বিস্তারিত

Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।

default_finality_modeconfirmations | finalizedসব সময়

নতুন project policy-তে inherited default finality model।

default_required_confirmationsintegerসব সময়

Default confirmation আর monitoring policy।

default_monitoring_minutesintegerসব সময়

Default confirmation আর monitoring policy।

policyobject | nullসব সময়
Project activation/finality policy, কনফিগার না হলে null। এতে custom_price_mode (fixed/dex), custom_price_usd (fixed decimal string বা null), custom_dex_pair (selected pool বা null), আর custom_dex (dex_id, quote_symbol, বর্তমান price_usd বা null, liquidity_usd, fetched_at, last_error) থাকে। এই project-এর store-গুলো custom pricing ভাগ করে।বিস্তারিত

Project activation/finality policy, কনফিগার না হলে null। এতে custom_price_mode (fixed/dex), custom_price_usd (fixed decimal string বা null), custom_dex_pair (selected pool বা null), আর custom_dex (dex_id, quote_symbol, বর্তমান price_usd বা null, liquidity_usd, fetched_at, last_error) থাকে। এই project-এর store-গুলো custom pricing ভাগ করে।

enabledbooleanবাধ্যতামূলক

Project-এর জন্য asset চালু বা বন্ধ করে। Token-এর আগে native chain চালু থাকতে হবে।

finality_modeconfirmations | finalizedবাধ্যতামূলক

Asset rail-এর সমর্থিত finality policy। finalized-এ required_confirmations=1 লাগে।

required_confirmationsintegerবাধ্যতামূলক
Bitcoin আর EVM rail zero নেয়; অন্য confirmation rail-এ অন্তত এক, finalized-only rail-এ ঠিক এক, আর EVM rail 0–48-এ সীমিত যাতে প্রতিটি transfer transaction replay window-তে থাকে।বিস্তারিত

Bitcoin আর EVM rail zero নেয়; অন্য confirmation rail-এ অন্তত এক, finalized-only rail-এ ঠিক এক, আর EVM rail 0–48-এ সীমিত যাতে প্রতিটি transfer transaction replay window-তে থাকে।

monitoring_minutesintegerবাধ্যতামূলক

Invoice active থাকা সময় 1–10,080 মিনিটের polling window।

late_monitoring_daysintegerবাধ্যতামূলক

Invoice expiry-এর পরে 0–3,650 দিনের monitoring।

walletobject | nullসব সময়

Chain-এর non-custodial project wallet। Token একই chain-native wallet ব্যবহার করে।

idUUIDসব সময়

Wallet, owner project আর chain-native asset identifier।

project_idUUIDসব সময়

Wallet, owner project আর chain-native asset identifier।

native_asset_idUUIDসব সময়

Wallet, owner project আর chain-native asset identifier।

chain_slugstringসব সময়

Wallet chain আর network।

networkstringসব সময়

Wallet chain আর network।

asset_symbolstringসব সময়

Chain-native display identity।

asset_namestringসব সময়

Chain-native display identity।

statuspending | active | disabled | errorসব সময়

Wallet-এর পরিচালনাগত state।

labelstringসব সময়

Operator label।

public_keystring | nullসব সময়

Public wallet identity; seed phrase বা private key প্রকাশিত নয়।

primary_addressstring | nullসব সময়

Public wallet identity; seed phrase বা private key প্রকাশিত নয়।

derivation_schemestring | nullসব সময়

Address policy আর format।

address_formatstring | nullসব সময়

Address policy আর format।

backup_confirmed_attimestamp | nullসব সময়

Operator recovery backup নিশ্চিত করলে non-null।

activation_requiredbooleanসব সময়
Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।বিস্তারিত

Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।

activation_verified_attimestamp|nullসব সময়
Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।বিস্তারিত

Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।

receive_readinessobject | null5.5.0+
Wallet list-এ থাকে: project receiving setup আর chain scanner prerequisite। Balance, token gas আর send readiness থেকে আলাদা। অন্য wallet response-এ null থাকতে পারে।বিস্তারিত

Wallet list-এ থাকে: project receiving setup আর chain scanner prerequisite। Balance, token gas আর send readiness থেকে আলাদা। অন্য wallet response-এ null থাকতে পারে।

readybooleanসব সময়

Receive setup check পাস। Spending readiness, gas, balance refresh বা ভবিষ্যৎ quote-এর নিশ্চয়তা বোঝায় না।

invoice_creatableboolean6.0.6+
সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।বিস্তারিত

সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।

checked_attimestampসব সময়

Assessment time। List করতে network request বা address allocation হয় না।

issues[]object[]সব সময়
Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।বিস্তারিত

Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।

chain_slugstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_idUUIDজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_tickerstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

reason_codestringসব সময়
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।বিস্তারিত

scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।

messagestringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

actionstringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

required_endpoint_rolestring | nullঅন-চেইন
Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।বিস্তারিত

Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।

accepted_endpoint_roles[]string[] | nullঅন-চেইন
Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।বিস্তারিত

Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।

healthy_endpointsintegerঅন-চেইন

Healthy matching endpoint, independent-provider count নয়।

usable_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

required_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

last_checked_attimestamp | nullঅন-চেইন

শেষ matching endpoint health check, assessment time থেকে আলাদা।

monero_wallet_rpcMoneroWalletRpcBinding | nullসব সময়
Monero-র sanitized external view-only wallet-RPC binding state। Endpoint, authentication mode, account-0 primary address, technical proof flag/height আর operator attestation timestamp থাকে; credential, wallet key আর wallet file serialize হয় না।বিস্তারিত

Monero-র sanitized external view-only wallet-RPC binding state। Endpoint, authentication mode, account-0 primary address, technical proof flag/height আর operator attestation timestamp থাকে; credential, wallet key আর wallet file serialize হয় না।

last_secret_revealed_attimestamp|nullসব সময়

Console-side secret disclosure audit metadata।

secret_reveal_countintegerসব সময়

Console-side secret disclosure audit metadata।

next_receive_indexintegerসব সময়

পরের reserved child-address index।

last_scanned_heightinteger|nullসব সময়

Wallet scanner state।

last_scanned_attimestamp|nullসব সময়

Wallet scanner state।

last_errorstring|nullসব সময়

Wallet scanner state।

balances[]object[]সব সময়
৩০টি native chain rail আর verified ERC-20 ও SPL asset-এর cached balance। Monero-তে configured external view-only wallet-RPC লাগে।বিস্তারিত

৩০টি native chain rail আর verified ERC-20 ও SPL asset-এর cached balance। Monero-তে configured external view-only wallet-RPC লাগে।

wallet_idUUIDসব সময়

Wallet আর স্থায়ী asset identity।

asset_idUUIDসব সময়

Wallet আর স্থায়ী asset identity।

project_enabledbooleanসব সময়

Project asset policy-তে এই asset এখন enabled কি না।

active_store_countintegerসব সময়

বর্তমানে এই asset বেছে নেওয়া enabled store-এর সংখ্যা। এটি acceptance projection; read-only balance tracking স্বাধীন।

active_store_ids[]UUID[]সব সময়

এই project-এর যেসব enabled store এখন asset নেয়। আর API request ছাড়াই সঠিক local store filtering করা যায়।

tracking_activebooleanসব সময়
এই read-capable wallet আর registered same-chain asset background balance refresh-এর যোগ্য কি না। Project আর payment-method acceptance switch read-only tracking থামায় না।বিস্তারিত

এই read-capable wallet আর registered same-chain asset background balance refresh-এর যোগ্য কি না। Project আর payment-method acceptance switch read-only tracking থামায় না।

asset_kindnative | tokenসব সময়

Native currency বা verified contract/mint asset।

contract_addressstring | nullসব সময়

Token contract বা mint; native currency-তে null।

symbolstringসব সময়

Display identity আর atomic precision।

namestringসব সময়

Display identity আর atomic precision।

decimalsintegerসব সময়

Display identity আর atomic precision।

coingecko_idstring | nullসব সময়

Mapped হলে pricing identity।

balancedecimal string|nullসব সময়

Wallet primary address আর issued invoice address জুড়ে সঠিক display আর atomic balance। পূর্ণ মান না পাওয়া পর্যন্ত null।

balance_atomicinteger string|nullসব সময়

Wallet primary address আর issued invoice address জুড়ে সঠিক display আর atomic balance। পূর্ণ মান না পাওয়া পর্যন্ত null।

price_usddecimal string | nullসব সময়

Valuation-এ ব্যবহৃত ধারণামূলক cached USD unit price।

value_usddecimal string | nullসব সময়

Current rate থাকলে ধারণামূলক fiat valuation।

statuspending | refreshing | fresh | stale | errorসব সময়
Cached scan state। refreshing-এ completed balance থাকতে পারে: বয়স জানতে checked_at নাও। Pending মানে completed snapshot নেই। কোনোটিই transfer pending বা invoice settled প্রমাণ করে না।বিস্তারিত

Cached scan state। refreshing-এ completed balance থাকতে পারে: বয়স জানতে checked_at নাও। Pending মানে completed snapshot নেই। কোনোটিই transfer pending বা invoice settled প্রমাণ করে না।

checked_attimestamp | nullসব সময়

Completed balance scan যে সময়ের মান দেখায়।

last_errorstring | nullসব সময়

নিরাপদ operator diagnostic।

total_value_usddecimal string | nullসব সময়

Current USD price থাকা balance-এর ধারণামূলক যোগফল।

balance_statuspending | refreshing | fresh | stale | error | unknownসব সময়

সমষ্টিগত cache freshness; unknown সতর্ক fallback, আর কোনো state-ই invoice settlement প্রমাণ করে না।

balance_checked_attimestamp | nullসব সময়

Aggregate-এ থাকা প্রাসঙ্গিক successful balance check-এর মধ্যে সবচেয়ে পুরোনো।

recent_payments[]object[]সব সময়

ঠিক এই wallet-এর সর্বশেষ সর্বোচ্চ তিনটি valid detected, confirming বা final observation।

invoice_public_idUUIDসব সময়

Observation-এর সঙ্গে যুক্ত customer-facing invoice identity।

chain_slugstringসব সময়

Chain আর native বা verified token-এর display symbol।

symbolstringসব সময়

Chain আর native বা verified token-এর display symbol।

transaction_idstringসব সময়

Canonical transaction আর transfer-event identity।

event_indexintegerসব সময়

Canonical transaction আর transfer-event identity।

amountdecimal stringসব সময়

Floating-point conversion ছাড়া সঠিক observed asset amount।

statusdetected | confirming | finalসব সময়

বর্তমান valid observation state। Reorged, replaced আর invalid observation বাদ।

confirmationsintegerসব সময়

সর্বশেষ observed confirmation count।

observed_atRFC 3339 timestampসব সময়

Wholly Crypto প্রথম পেমেন্ট দেখার সময়।

created_atRFC 3339 timestampসব সময়

Wallet creation আর last update time।

updated_atRFC 3339 timestampসব সময়

Wallet creation আর last update time।

wallet_readinessreadiness enumসব সময়
unsupported, project_disabled, project_asset_disabled, store_disabled, store_asset_disabled, wallet_missing, wallet_pending, wallet_disabled, wallet_error, backup_required, account_activation_required, external_wallet_rpc_required বা ready।বিস্তারিত

unsupported, project_disabled, project_asset_disabled, store_disabled, store_asset_disabled, wallet_missing, wallet_pending, wallet_disabled, wallet_error, backup_required, account_activation_required, external_wallet_rpc_required বা ready।

receive_readinessobject | null5.5.0+
Shared project receive-setup assessment। Wallet আর independent scanner-provider check থাকে, balance freshness আর sending gas থেকে আলাদা। Project policy না থাকলে null। Invoice currency/rate creation-এর সময় পরীক্ষা হয়।বিস্তারিত

Shared project receive-setup assessment। Wallet আর independent scanner-provider check থাকে, balance freshness আর sending gas থেকে আলাদা। Project policy না থাকলে null। Invoice currency/rate creation-এর সময় পরীক্ষা হয়।

readybooleanসব সময়

Receive setup check পাস। Spending readiness, gas, balance refresh বা ভবিষ্যৎ quote-এর নিশ্চয়তা বোঝায় না।

invoice_creatableboolean6.0.6+
সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।বিস্তারিত

সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।

checked_attimestampসব সময়

Assessment time। List করতে network request বা address allocation হয় না।

issues[]object[]সব সময়
Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।বিস্তারিত

Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।

chain_slugstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_idUUIDজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_tickerstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

reason_codestringসব সময়
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।বিস্তারিত

scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।

messagestringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

actionstringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

required_endpoint_rolestring | nullঅন-চেইন
Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।বিস্তারিত

Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।

accepted_endpoint_roles[]string[] | nullঅন-চেইন
Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।বিস্তারিত

Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।

healthy_endpointsintegerঅন-চেইন

Healthy matching endpoint, independent-provider count নয়।

usable_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

required_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

last_checked_attimestamp | nullঅন-চেইন

শেষ matching endpoint health check, assessment time থেকে আলাদা।

ব্যবহারের নোট
  • Token global list-এ থাকলেও scanner_ready বা payment_supported false হলে বাছাই করা যায় না।
  • Operator capability matrix-এ scanner-এর সঠিক endpoint role-ও লাগে; incompatible API-র healthy endpoint গণনায় আসে না।
  • Token native chain-এর project wallet ভাগ করে; আরেক seed phrase তৈরি হয় না।
  • Embedded wallet summary শুধু readiness-এর জন্য, balance খালি রাখে; বিস্তারিত balance-এর জন্য GET /v1/projects/{project_id}/wallets নাও।

ত্রুটি

Error code ও retry-এর নিয়ম

PUTপ্রকল্পের অ্যাসেট নীতি বদলাও/v1/projects/{project_id}/payment-assets/{asset_id}পড়া + লেখা

একটি স্থায়ী asset-এর project policy তৈরি বা প্রতিস্থাপন করে updated project asset list ফেরত দেয়। Native chain বন্ধ করলে তার native asset আর token নতুন invoice-এ বন্ধ হয়, কিন্তু token policy, wallet আর store selection থাকে যাতে পরে চালানো যায়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MERCHANT_API_TOKEN
Content-Typeবাধ্যতামূলকapplication/json
Acceptপ্রস্তাবিতapplication/json

Path parameter

project_idUUIDবাধ্যতামূলক

Credential-এ দেওয়া enabled project।

asset_idUUIDবাধ্যতামূলক

Project asset list বা token registration-এর ফেরত দেওয়া asset id।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request PUT \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-assets/YOUR_ASSET_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "enabled": true,
  "finality_mode": "confirmations",
  "required_confirmations": 2,
  "monitoring_minutes": 60,
  "late_monitoring_days": 30
}'

Request body

enabledbooleanবাধ্যতামূলক

Project-এর জন্য asset চালু বা বন্ধ করে। Token-এর আগে native chain চালু থাকতে হবে।

finality_modeconfirmations | finalizedবাধ্যতামূলক

Asset rail-এর সমর্থিত finality policy। finalized-এ required_confirmations=1 লাগে।

required_confirmationsintegerবাধ্যতামূলক
Bitcoin আর EVM rail zero নেয়; অন্য confirmation rail-এ অন্তত এক, finalized-only rail-এ ঠিক এক, আর EVM rail 0–48-এ সীমিত যাতে প্রতিটি transfer transaction replay window-তে থাকে।বিস্তারিত

Bitcoin আর EVM rail zero নেয়; অন্য confirmation rail-এ অন্তত এক, finalized-only rail-এ ঠিক এক, আর EVM rail 0–48-এ সীমিত যাতে প্রতিটি transfer transaction replay window-তে থাকে।

monitoring_minutesintegerবাধ্যতামূলক

Invoice active থাকা সময় 1–10,080 মিনিটের polling window।

late_monitoring_daysintegerবাধ্যতামূলক

Invoice expiry-এর পরে 0–3,650 দিনের monitoring।

উত্তর 200 application/json

উদাহরণ response
{
  "data": [
    { "asset": { "id": "ASSET_UUID", "symbol": "USDC", "asset_kind": "token", "scanner_ready": true }, "policy": { "enabled": true, "finality_mode": "confirmations", "required_confirmations": 2, "monitoring_minutes": 60, "late_monitoring_days": 30 }, "wallet_readiness": "ready" }
  ]
}

Response field

data[]object[]
assetobjectসব সময়

স্থায়ী native বা verified token asset।

idUUIDসব সময়

Project আর store policy route-এ ব্যবহৃত স্থায়ী payment-asset identifier।

asset_keystringসব সময়

Canonical CAIP-style native বা contract asset identity।

chain_slugstringসব সময়

Wholly Crypto chain identifier আর configured network।

networkstringসব সময়

Wholly Crypto chain identifier আর configured network।

caip_network_idstringসব সময়

Canonical network আর asset identity।

caip_asset_idstring|nullসব সময়

Canonical network আর asset identity।

asset_kindnative | tokenসব সময়

Settlement chain currency নাকি verified contract/mint ব্যবহার করে।

payment_railstringসব সময়

Runtime rail: utxo, evm-native, solana-native, account-native, privacy-native বা token-transfer।

symbolstringসব সময়

দেখানোর identity আর সঠিক atomic-unit precision।

namestringসব সময়

দেখানোর identity আর সঠিক atomic-unit precision।

decimalsintegerসব সময়

দেখানোর identity আর সঠিক atomic-unit precision।

contract_addressstring | nullসব সময়

Token-এর canonical ERC-20 contract বা SPL mint; native asset-এ null।

coingecko_idstring | nullসব সময়

Discovery/pricing identity। Custom contract-এ null; ticker দেখে market price অনুমান কোরো না। শুধু CoinGecko metadata টোকেনকে selectable করে না।

custom_tokenbooleanসব সময়

Project-scoped fixed USD বা selected DEX pool pricing-সহ custom on-chain-verified contract।

icon_pathpath | nullসব সময়

পাওয়া গেলে locally cached token icon।

token_standarderc20 | spl-token | nullসব সময়

Verified runtime token standard; native asset-এ null।

metadata_verified_attimestamp | nullসব সময়

Promoted token-এর on-chain metadata verification time।

payment_supportedbooleanসব সময়
Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।বিস্তারিত

Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।

scanner_readybooleanসব সময়
Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।বিস্তারিত

Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।

balance_readybooleanসব সময়
Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।বিস্তারিত

Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।

default_finality_modeconfirmations | finalizedসব সময়

নতুন project policy-তে inherited default finality model।

default_required_confirmationsintegerসব সময়

Default confirmation আর monitoring policy।

default_monitoring_minutesintegerসব সময়

Default confirmation আর monitoring policy।

policyobject | nullসব সময়
Project activation/finality policy, কনফিগার না হলে null। এতে custom_price_mode (fixed/dex), custom_price_usd (fixed decimal string বা null), custom_dex_pair (selected pool বা null), আর custom_dex (dex_id, quote_symbol, বর্তমান price_usd বা null, liquidity_usd, fetched_at, last_error) থাকে। এই project-এর store-গুলো custom pricing ভাগ করে।বিস্তারিত

Project activation/finality policy, কনফিগার না হলে null। এতে custom_price_mode (fixed/dex), custom_price_usd (fixed decimal string বা null), custom_dex_pair (selected pool বা null), আর custom_dex (dex_id, quote_symbol, বর্তমান price_usd বা null, liquidity_usd, fetched_at, last_error) থাকে। এই project-এর store-গুলো custom pricing ভাগ করে।

enabledbooleanবাধ্যতামূলক

Project-এর জন্য asset চালু বা বন্ধ করে। Token-এর আগে native chain চালু থাকতে হবে।

finality_modeconfirmations | finalizedবাধ্যতামূলক

Asset rail-এর সমর্থিত finality policy। finalized-এ required_confirmations=1 লাগে।

required_confirmationsintegerবাধ্যতামূলক
Bitcoin আর EVM rail zero নেয়; অন্য confirmation rail-এ অন্তত এক, finalized-only rail-এ ঠিক এক, আর EVM rail 0–48-এ সীমিত যাতে প্রতিটি transfer transaction replay window-তে থাকে।বিস্তারিত

Bitcoin আর EVM rail zero নেয়; অন্য confirmation rail-এ অন্তত এক, finalized-only rail-এ ঠিক এক, আর EVM rail 0–48-এ সীমিত যাতে প্রতিটি transfer transaction replay window-তে থাকে।

monitoring_minutesintegerবাধ্যতামূলক

Invoice active থাকা সময় 1–10,080 মিনিটের polling window।

late_monitoring_daysintegerবাধ্যতামূলক

Invoice expiry-এর পরে 0–3,650 দিনের monitoring।

walletobject | nullসব সময়

Chain-এর non-custodial project wallet। Token একই chain-native wallet ব্যবহার করে।

idUUIDসব সময়

Wallet, owner project আর chain-native asset identifier।

project_idUUIDসব সময়

Wallet, owner project আর chain-native asset identifier।

native_asset_idUUIDসব সময়

Wallet, owner project আর chain-native asset identifier।

chain_slugstringসব সময়

Wallet chain আর network।

networkstringসব সময়

Wallet chain আর network।

asset_symbolstringসব সময়

Chain-native display identity।

asset_namestringসব সময়

Chain-native display identity।

statuspending | active | disabled | errorসব সময়

Wallet-এর পরিচালনাগত state।

labelstringসব সময়

Operator label।

public_keystring | nullসব সময়

Public wallet identity; seed phrase বা private key প্রকাশিত নয়।

primary_addressstring | nullসব সময়

Public wallet identity; seed phrase বা private key প্রকাশিত নয়।

derivation_schemestring | nullসব সময়

Address policy আর format।

address_formatstring | nullসব সময়

Address policy আর format।

backup_confirmed_attimestamp | nullসব সময়

Operator recovery backup নিশ্চিত করলে non-null।

activation_requiredbooleanসব সময়
Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।বিস্তারিত

Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।

activation_verified_attimestamp|nullসব সময়
Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।বিস্তারিত

Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।

receive_readinessobject | null5.5.0+
Wallet list-এ থাকে: project receiving setup আর chain scanner prerequisite। Balance, token gas আর send readiness থেকে আলাদা। অন্য wallet response-এ null থাকতে পারে।বিস্তারিত

Wallet list-এ থাকে: project receiving setup আর chain scanner prerequisite। Balance, token gas আর send readiness থেকে আলাদা। অন্য wallet response-এ null থাকতে পারে।

readybooleanসব সময়

Receive setup check পাস। Spending readiness, gas, balance refresh বা ভবিষ্যৎ quote-এর নিশ্চয়তা বোঝায় না।

invoice_creatableboolean6.0.6+
সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।বিস্তারিত

সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।

checked_attimestampসব সময়

Assessment time। List করতে network request বা address allocation হয় না।

issues[]object[]সব সময়
Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।বিস্তারিত

Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।

chain_slugstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_idUUIDজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_tickerstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

reason_codestringসব সময়
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।বিস্তারিত

scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।

messagestringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

actionstringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

required_endpoint_rolestring | nullঅন-চেইন
Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।বিস্তারিত

Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।

accepted_endpoint_roles[]string[] | nullঅন-চেইন
Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।বিস্তারিত

Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।

healthy_endpointsintegerঅন-চেইন

Healthy matching endpoint, independent-provider count নয়।

usable_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

required_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

last_checked_attimestamp | nullঅন-চেইন

শেষ matching endpoint health check, assessment time থেকে আলাদা।

monero_wallet_rpcMoneroWalletRpcBinding | nullসব সময়
Monero-র sanitized external view-only wallet-RPC binding state। Endpoint, authentication mode, account-0 primary address, technical proof flag/height আর operator attestation timestamp থাকে; credential, wallet key আর wallet file serialize হয় না।বিস্তারিত

Monero-র sanitized external view-only wallet-RPC binding state। Endpoint, authentication mode, account-0 primary address, technical proof flag/height আর operator attestation timestamp থাকে; credential, wallet key আর wallet file serialize হয় না।

last_secret_revealed_attimestamp|nullসব সময়

Console-side secret disclosure audit metadata।

secret_reveal_countintegerসব সময়

Console-side secret disclosure audit metadata।

next_receive_indexintegerসব সময়

পরের reserved child-address index।

last_scanned_heightinteger|nullসব সময়

Wallet scanner state।

last_scanned_attimestamp|nullসব সময়

Wallet scanner state।

last_errorstring|nullসব সময়

Wallet scanner state।

balances[]object[]সব সময়
৩০টি native chain rail আর verified ERC-20 ও SPL asset-এর cached balance। Monero-তে configured external view-only wallet-RPC লাগে।বিস্তারিত

৩০টি native chain rail আর verified ERC-20 ও SPL asset-এর cached balance। Monero-তে configured external view-only wallet-RPC লাগে।

wallet_idUUIDসব সময়

Wallet আর স্থায়ী asset identity।

asset_idUUIDসব সময়

Wallet আর স্থায়ী asset identity।

project_enabledbooleanসব সময়

Project asset policy-তে এই asset এখন enabled কি না।

active_store_countintegerসব সময়

বর্তমানে এই asset বেছে নেওয়া enabled store-এর সংখ্যা। এটি acceptance projection; read-only balance tracking স্বাধীন।

active_store_ids[]UUID[]সব সময়

এই project-এর যেসব enabled store এখন asset নেয়। আর API request ছাড়াই সঠিক local store filtering করা যায়।

tracking_activebooleanসব সময়
এই read-capable wallet আর registered same-chain asset background balance refresh-এর যোগ্য কি না। Project আর payment-method acceptance switch read-only tracking থামায় না।বিস্তারিত

এই read-capable wallet আর registered same-chain asset background balance refresh-এর যোগ্য কি না। Project আর payment-method acceptance switch read-only tracking থামায় না।

asset_kindnative | tokenসব সময়

Native currency বা verified contract/mint asset।

contract_addressstring | nullসব সময়

Token contract বা mint; native currency-তে null।

symbolstringসব সময়

Display identity আর atomic precision।

namestringসব সময়

Display identity আর atomic precision।

decimalsintegerসব সময়

Display identity আর atomic precision।

coingecko_idstring | nullসব সময়

Mapped হলে pricing identity।

balancedecimal string|nullসব সময়

Wallet primary address আর issued invoice address জুড়ে সঠিক display আর atomic balance। পূর্ণ মান না পাওয়া পর্যন্ত null।

balance_atomicinteger string|nullসব সময়

Wallet primary address আর issued invoice address জুড়ে সঠিক display আর atomic balance। পূর্ণ মান না পাওয়া পর্যন্ত null।

price_usddecimal string | nullসব সময়

Valuation-এ ব্যবহৃত ধারণামূলক cached USD unit price।

value_usddecimal string | nullসব সময়

Current rate থাকলে ধারণামূলক fiat valuation।

statuspending | refreshing | fresh | stale | errorসব সময়
Cached scan state। refreshing-এ completed balance থাকতে পারে: বয়স জানতে checked_at নাও। Pending মানে completed snapshot নেই। কোনোটিই transfer pending বা invoice settled প্রমাণ করে না।বিস্তারিত

Cached scan state। refreshing-এ completed balance থাকতে পারে: বয়স জানতে checked_at নাও। Pending মানে completed snapshot নেই। কোনোটিই transfer pending বা invoice settled প্রমাণ করে না।

checked_attimestamp | nullসব সময়

Completed balance scan যে সময়ের মান দেখায়।

last_errorstring | nullসব সময়

নিরাপদ operator diagnostic।

total_value_usddecimal string | nullসব সময়

Current USD price থাকা balance-এর ধারণামূলক যোগফল।

balance_statuspending | refreshing | fresh | stale | error | unknownসব সময়

সমষ্টিগত cache freshness; unknown সতর্ক fallback, আর কোনো state-ই invoice settlement প্রমাণ করে না।

balance_checked_attimestamp | nullসব সময়

Aggregate-এ থাকা প্রাসঙ্গিক successful balance check-এর মধ্যে সবচেয়ে পুরোনো।

recent_payments[]object[]সব সময়

ঠিক এই wallet-এর সর্বশেষ সর্বোচ্চ তিনটি valid detected, confirming বা final observation।

invoice_public_idUUIDসব সময়

Observation-এর সঙ্গে যুক্ত customer-facing invoice identity।

chain_slugstringসব সময়

Chain আর native বা verified token-এর display symbol।

symbolstringসব সময়

Chain আর native বা verified token-এর display symbol।

transaction_idstringসব সময়

Canonical transaction আর transfer-event identity।

event_indexintegerসব সময়

Canonical transaction আর transfer-event identity।

amountdecimal stringসব সময়

Floating-point conversion ছাড়া সঠিক observed asset amount।

statusdetected | confirming | finalসব সময়

বর্তমান valid observation state। Reorged, replaced আর invalid observation বাদ।

confirmationsintegerসব সময়

সর্বশেষ observed confirmation count।

observed_atRFC 3339 timestampসব সময়

Wholly Crypto প্রথম পেমেন্ট দেখার সময়।

created_atRFC 3339 timestampসব সময়

Wallet creation আর last update time।

updated_atRFC 3339 timestampসব সময়

Wallet creation আর last update time।

wallet_readinessreadiness enumসব সময়
unsupported, project_disabled, project_asset_disabled, store_disabled, store_asset_disabled, wallet_missing, wallet_pending, wallet_disabled, wallet_error, backup_required, account_activation_required, external_wallet_rpc_required বা ready।বিস্তারিত

unsupported, project_disabled, project_asset_disabled, store_disabled, store_asset_disabled, wallet_missing, wallet_pending, wallet_disabled, wallet_error, backup_required, account_activation_required, external_wallet_rpc_required বা ready।

receive_readinessobject | null5.5.0+
Shared project receive-setup assessment। Wallet আর independent scanner-provider check থাকে, balance freshness আর sending gas থেকে আলাদা। Project policy না থাকলে null। Invoice currency/rate creation-এর সময় পরীক্ষা হয়।বিস্তারিত

Shared project receive-setup assessment। Wallet আর independent scanner-provider check থাকে, balance freshness আর sending gas থেকে আলাদা। Project policy না থাকলে null। Invoice currency/rate creation-এর সময় পরীক্ষা হয়।

readybooleanসব সময়

Receive setup check পাস। Spending readiness, gas, balance refresh বা ভবিষ্যৎ quote-এর নিশ্চয়তা বোঝায় না।

invoice_creatableboolean6.0.6+
সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।বিস্তারিত

সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।

checked_attimestampসব সময়

Assessment time। List করতে network request বা address allocation হয় না।

issues[]object[]সব সময়
Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।বিস্তারিত

Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।

chain_slugstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_idUUIDজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_tickerstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

reason_codestringসব সময়
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।বিস্তারিত

scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।

messagestringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

actionstringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

required_endpoint_rolestring | nullঅন-চেইন
Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।বিস্তারিত

Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।

accepted_endpoint_roles[]string[] | nullঅন-চেইন
Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।বিস্তারিত

Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।

healthy_endpointsintegerঅন-চেইন

Healthy matching endpoint, independent-provider count নয়।

usable_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

required_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

last_checked_attimestamp | nullঅন-চেইন

শেষ matching endpoint health check, assessment time থেকে আলাদা।

ব্যবহারের নোট
  • Body পুরো policy প্রতিস্থাপন করে এবং unknown field প্রত্যাখ্যান করে।
  • Project enablement নিজে কোনো store-এর জন্য asset বেছে নেয় না।

ত্রুটি

Error code ও retry-এর নিয়ম

GETসম্ভাব্য পেমেন্ট টোকেন দেখো/v1/projects/{project_id}/payment-token-candidatesশুধু পড়া

যেসব chain-এ token invoice scanner আর balance adapter implemented, শুধু সেগুলোর locally cached CoinGecko contract mapping খোঁজে। Result discovery candidate, trusted payment asset নয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MERCHANT_API_TOKEN
Acceptপ্রস্তাবিতapplication/json

Path parameter

project_idUUIDবাধ্যতামূলক

Credential-এ দেওয়া enabled project।

Query parameter

chain_slugstring

Supported EVM chain slug অথবা solana বাধ্যতামূলক।

qstring

ঐচ্ছিক name, symbol, CoinGecko id, contract বা mint-এর substring; সর্বোচ্চ ৮০ অক্ষর।

limitinteger

ঐচ্ছিক 1–100; ডিফল্ট ৫০।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-candidates?chain_slug=ethereum&q=USDC&limit=50" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [
    {
      "coingecko_id": "usd-coin",
      "chain_slug": "ethereum",
      "symbol": "USDC",
      "name": "USDC",
      "contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "market_cap_rank": 7,
      "icon_path": "/assets/coingecko/usd-coin.png",
      "current_price_usd": "1.0001",
      "token_standard": "erc20",
      "scanner_ready": true,
      "registered_asset_id": null,
      "project_enabled": false
    }
  ]
}

Response field

data[]object[]
coingecko_idstringসব সময়

Registration request-এ ব্যবহৃত CoinGecko discovery identity।

chain_slugstringসব সময়

মেলা Wholly Crypto chain।

symbolstringসব সময়

Catalog display identity।

namestringসব সময়

Catalog display identity।

contract_addressstringসব সময়

মেলা contract বা mint; registration-এর আগে on-chain verify হয়।

market_cap_rankinteger | nullসব সময়

Discovery rank, trust বা payment-readiness signal নয়।

icon_pathpathসব সময়

Locally cached CoinGecko icon path।

current_price_usddecimal string | nullসব সময়

ধারণামূলক cached USD price।

token_standarderc20 | spl-tokenসব সময়

বাছাই করা chain adapter-এর supported token standard।

scanner_readybooleanসব সময়

এই build-এ implemented token rail-এর candidate হলেই true।

registered_asset_idUUID | nullসব সময়

আগে promoted হলে existing durable asset।

project_enabledbooleanসব সময়

Registered asset এই project-এ enabled কি না।

ব্যবহারের নোট
  • Supported token adapter: Ethereum, Base, BNB Chain, HyperEVM, Avalanche, Polygon, Arbitrum আর Optimism-এ ERC-20; Solana-তে SPL।
  • Unsupported catalog chain বাছাইযোগ্য না দেখিয়ে প্রত্যাখ্যান করা হয়।
  • CoinGecko rank, icon আর price ধারণামূলক discovery data।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTটোকেন যাচাই ও নিবন্ধন করো/v1/projects/{project_id}/payment-token-assetsপড়া + লেখা

Configured node দিয়ে chain identity, contract/mint identity, decimal আর ব্যবহারযোগ্য balance query verify করার পরই current candidate স্থায়ী payment registry-তে যায়। Registration শুধু CoinGecko metadata বিশ্বাস করে না; প্রতি project-এ সর্বোচ্চ ২০ registered token asset।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MERCHANT_API_TOKEN
Content-Typeবাধ্যতামূলকapplication/json
Acceptপ্রস্তাবিতapplication/json

Path parameter

project_idUUIDবাধ্যতামূলক

Credential-এ দেওয়া enabled project।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-assets" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "chain_slug": "ethereum",
  "coingecko_id": "usd-coin",
  "enabled": true
}'

Request body

chain_slugstringবাধ্যতামূলক

ethereum, base, bnb-chain, hyperliquid, avalanche, polygon, arbitrum, optimism বা solana।

coingecko_idstringবাধ্যতামূলক
Token search-এর ফেরত দেওয়া সঠিক candidate identity। শুরুর underscore বা hyphen রাখো, যেমন _ বা -6। Token name বা ticker থেকে ID বানিয়ো না।বিস্তারিত

Token search-এর ফেরত দেওয়া সঠিক candidate identity। শুরুর underscore বা hyphen রাখো, যেমন _ বা -6। Token name বা ticker থেকে ID বানিয়ো না।

enabledbooleanঐচ্ছিক

Verification-এর পরে project policy state; ডিফল্ট true।

উত্তর 201 application/json

উদাহরণ response
{
  "data": {
    "asset_id": "44444444-4444-4444-8444-444444444444",
    "chain_slug": "ethereum",
    "coingecko_id": "usd-coin",
    "contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "token_standard": "erc20",
    "symbol": "USDC",
    "name": "USDC",
    "decimals": 6,
    "enabled": true,
    "metadata_verified_at": "2026-08-31T18:00:00Z"
  }
}

Response field

dataobject
asset_idUUIDসব সময়

স্থায়ী payment asset identifier।

chain_slugstringসব সময়

যাচাই করা chain আর সেভ রাখা discovery/pricing identity।

coingecko_idstringসব সময়

যাচাই করা chain আর সেভ রাখা discovery/pricing identity।

contract_addressstringসব সময়

Canonical verified contract বা mint।

token_standarderc20 | spl-tokenসব সময়

Verified runtime token standard।

symbolstringসব সময়

Promoted display identity আর exact precision।

namestringসব সময়

Promoted display identity আর exact precision।

decimalsintegerসব সময়

Promoted display identity আর exact precision।

enabledbooleanসব সময়

প্রাথমিক project policy state।

metadata_verified_atRFC 3339 timestampসব সময়

On-chain verification time।

ব্যবহারের নোট
  • Token নিবন্ধনের আগে chain-এর native project asset চালু করো।
  • Project সর্বোচ্চ ২০ token asset নিবন্ধন করতে পারে; সীমার বেশি নতুন candidate-এ token_chain_not_ready (409)। আগে registered asset আবার নিলে নতুন slot লাগে না।
  • Catalog read-এর চেয়ে node verification বেশি সময় নিতে পারে; explicit client timeout নাও।
  • Registration-এর পরে যে store-এ দিতে চাও সেখানে asset বেছে নাও।

ত্রুটি

Error code ও retry-এর নিয়ম

GETকাস্টম টোকেনের DEX pool খোঁজো/v1/projects/{project_id}/payment-token-dex-poolsশুধু পড়া

DEX Screener দিয়ে exact chain আর base-token contract অনুযায়ী liquidity-র ক্রমে সর্বোচ্চ ১২ eligible pool খোঁজে। Token register বা enable করে না।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MERCHANT_API_TOKEN

Path parameter

project_idUUIDবাধ্যতামূলক

নির্ধারিত project।

Query parameter

chain_slugstring

Supported EVM token chain অথবা solana।

contract_addressstring

সঠিক ERC-20 contract বা classic SPL mint।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-dex-pools?chain_slug=ethereum&contract_address=YOUR_TOKEN_CONTRACT" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{"data":[{"pair_address":"0x2222222222222222222222222222222222222222","dex_id":"uniswap","quote_symbol":"WETH","price_usd":"0.25","liquidity_usd":"250000.00","fetched_at":"2026-09-09T12:00:00Z","url":"https://dexscreener.com/ethereum/0x2222222222222222222222222222222222222222"}]}

Response field

data[]object[]
pair_addressstringসব সময়

সঠিক pool identifier, exchange ID (যেমন uniswap/pancakeswap) আর শুধু দেখানোর paired ticker।

dex_idstringসব সময়

সঠিক pool identifier, exchange ID (যেমন uniswap/pancakeswap) আর শুধু দেখানোর paired ticker।

quote_symbolstringসব সময়

সঠিক pool identifier, exchange ID (যেমন uniswap/pancakeswap) আর শুধু দেখানোর paired ticker।

price_usddecimal stringসব সময়

Requested base token-এর USD price আর total pool liquidity। অন্তত $10,000 liquidity আর গত এক ঘণ্টায় trade লাগে।

liquidity_usddecimal stringসব সময়

Requested base token-এর USD price আর total pool liquidity। অন্তত $10,000 liquidity আর গত এক ঘণ্টায় trade লাগে।

fetched_atRFC 3339 timestampসব সময়

Server কখন provider observation এনেছে, on-chain trade-এর timestamp নয়।

urlHTTPS URLসব সময়

এই pool-এর verified DEX Screener link।

ব্যবহারের নোট
  • খালি data array মানে উপযুক্ত pool পাওয়া যায়নি। শুধু requested contract base token এমন pool আসে; quote-side USD price অনুমান করা হয় না।
  • DEX listing security audit নয়। Minimum liquidity আর recent activity অচল quote কমায়, market manipulation আটকায় না।
  • আগের chain scanner যেখানে token সমর্থন করে সেখানে Uniswap, PancakeSwap আর অন্য indexed DEX সমর্থিত। API access project-scoped আর rate-limited থাকে। Provider call-ও ক্রমানুসারে আর throttle করে হয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTকাস্টম টোকেন যোগ করো বা দাম বদলাও/v1/projects/{project_id}/payment-token-assets/customপড়া + লেখা

Configured chain node দিয়ে custom contract verify করে CoinGecko listing ছাড়াই register করে। Fixed USD price বা selected automatic DEX pool এই project-এর, ticker বা অন্য project-এর নয়। একই identity আবার দিলে existing enabled/disabled policy না বদলে project price আপডেট হয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MERCHANT_API_TOKEN
Content-Typeবাধ্যতামূলকapplication/json

Path parameter

project_idUUIDবাধ্যতামূলক

এই write-capable credential-এ দেওয়া project।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-assets/custom" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "chain_slug": "ethereum",
  "contract_address": "YOUR_VERIFIED_TOKEN_CONTRACT",
  "name": "Example token",
  "symbol": "EXAMPLE",
  "price_usd": "0.25"
}'

Request body

chain_slugstringবাধ্যতামূলক

ethereum, base, bnb-chain, hyperliquid, avalanche, polygon, arbitrum, optimism বা solana। এই contract-এর জন্য স্থির।

contract_addressstringবাধ্যতামূলক
ERC-20 contract (0x আর ৪০ hexadecimal অক্ষর), অথবা classic SPL mint। Node network identity আর exact decimal verify করে; caller-এর decimal আর RPC URL প্রত্যাখ্যাত।বিস্তারিত

ERC-20 contract (0x আর ৪০ hexadecimal অক্ষর), অথবা classic SPL mint। Node network identity আর exact decimal verify করে; caller-এর decimal আর RPC URL প্রত্যাখ্যাত।

namestringবাধ্যতামূলক
Display name (1–80 অক্ষর) আর ticker (1–16 letter/digit/dot/underscore/hyphen, প্রথম অক্ষর alphanumeric)। Existing identity-এর নাম এই endpoint বদলায় না।বিস্তারিত

Display name (1–80 অক্ষর) আর ticker (1–16 letter/digit/dot/underscore/hyphen, প্রথম অক্ষর alphanumeric)। Existing identity-এর নাম এই endpoint বদলায় না।

symbolstringবাধ্যতামূলক
Display name (1–80 অক্ষর) আর ticker (1–16 letter/digit/dot/underscore/hyphen, প্রথম অক্ষর alphanumeric)। Existing identity-এর নাম এই endpoint বদলায় না।বিস্তারিত

Display name (1–80 অক্ষর) আর ticker (1–16 letter/digit/dot/underscore/hyphen, প্রথম অক্ষর alphanumeric)। Existing identity-এর নাম এই endpoint বদলায় না।

price_modefixed | dexঐচ্ছিক

পুরোনো সামঞ্জস্যের জন্য default fixed। DEX exact chain আর contract-এর জন্য খুঁজে পাওয়া নির্দিষ্ট pool ব্যবহার করে।

price_usddecimal stringfixed mode

এক token-এর fixed USD value, positive, সর্বোচ্চ ৩০ decimal, maximum 1000000000000000000000000। Exponent বা float নয়। dex mode-এ বাদ দাও।

dex_pair_addressstringdex mode
payment-token-dex-pools থেকে pool address। dex mode-এ বাধ্যতামূলক; fixed mode-এ বাদ। প্রতিবার save-এ server pool identity, price, liquidity আর activity আবার দেখে।বিস্তারিত

payment-token-dex-pools থেকে pool address। dex mode-এ বাধ্যতামূলক; fixed mode-এ বাদ। প্রতিবার save-এ server pool identity, price, liquidity আর activity আবার দেখে।

উত্তর 200 application/json

উদাহরণ response
{"data":{"asset_id":"44444444-4444-4444-8444-444444444444"}}

Response field

dataobject
asset_idstring
ব্যবহারের নোট
  • Registration-এর পরে store-এর payment-assets endpoint-এ asset_id বেছে নাও; শুধু registration store method চালু করে না।
  • Custom আর catalog token একই ২০-token project limit ভাগ করে। ভিন্ন chain-এ একই contract ভিন্ন payment asset।
  • Existing catalog contract-এ 409: automatic market rate রাখতে catalog registration নাও। Custom ticker একই নামের token-এর price ধার নেয় না।
  • Fixed price operator-এর অনুমান। Automatic DEX price DEX Screener দিয়ে selected pool-এর spot observation, manipulation-resistant oracle নয়। Fresh fiat rate-সহ store spread আর upward rounding লাগে। আগে দেওয়া quote অপরিবর্তিত।
  • DEX mode-এ আগে pool খোঁজো, তারপর price_usd বাদ দিয়ে price_mode: dex আর dex_pair_address পাঠাও। Shared background task প্রতি মিনিটে selected pool refresh করে। Check ব্যর্থ বা price পাঁচ মিনিটের বেশি পুরোনো হলে নতুন quote থেকে token বাদ; চুপিসারে fixed-price বা ticker fallback হয় না।
  • শুধু standard ERC-20 আর classic SPL token নেয়। Token-2022/extension আর native-only chain প্রত্যাখ্যাত। Technical verification issuer/contract security audit নয়; fee-on-transfer, rebasing বা blacklisting token অসামঞ্জস্যপূর্ণ আচরণ করতে পারে।
  • অন্তত ৬০ সেকেন্ড client timeout নাও। Verification সীমিত এবং node fallback চেষ্টা করতে পারে। Invalid input-এ 400; failed chain/contract check-এ 422; identity conflict বা limit-এ 409।

ত্রুটি

Error code ও retry-এর নিয়ম

GETস্টোরের পেমেন্ট পদ্ধতির তালিকা/v1/projects/{project_id}/stores/{store_id}/payment-assetsশুধু পড়া

data-তে on-chain asset আর lightning-এ আলাদা Lightning readiness দেয়। On-chain method-এ ready chain wallet লাগে। Lightning store-এ বাছাই করা verified external receiving connection ব্যবহার করে, on-chain Bitcoin wallet থেকে স্বাধীন।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MERCHANT_API_TOKEN
Acceptপ্রস্তাবিতapplication/json

Path parameter

project_idUUIDবাধ্যতামূলক

Credential-এ দেওয়া project; paused হতে পারে।

store_idUUIDবাধ্যতামূলক

project_id-এর store; paused হতে পারে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [
    { "asset": { "id": "ASSET_UUID", "chain_slug": "ethereum", "symbol": "USDC", "asset_kind": "token", "token_standard": "erc20", "scanner_ready": true }, "project_policy": { "enabled": true, "required_confirmations": 12 }, "selected": true, "display_order": 0, "confirmation_policy": { "finality_mode": "confirmations", "project_required_confirmations": 12, "override_required_confirmations": 3, "effective_required_confirmations": 3, "editable": true, "minimum_required_confirmations": 0, "maximum_required_confirmations": 48 }, "wallet": { "id": "WALLET_UUID", "status": "active" }, "wallet_readiness": "ready" }
  ],
  "lightning": { "payment_rail": "lightning", "symbol": "BTC", "asset_decimals": 11, "enabled": true, "ready": true }
}

Response field

data[]object[]
assetobjectসব সময়

Project-visible native বা verified token asset।

idUUIDসব সময়

Project আর store policy route-এ ব্যবহৃত স্থায়ী payment-asset identifier।

asset_keystringসব সময়

Canonical CAIP-style native বা contract asset identity।

chain_slugstringসব সময়

Wholly Crypto chain identifier আর configured network।

networkstringসব সময়

Wholly Crypto chain identifier আর configured network।

caip_network_idstringসব সময়

Canonical network আর asset identity।

caip_asset_idstring|nullসব সময়

Canonical network আর asset identity।

asset_kindnative | tokenসব সময়

Settlement chain currency নাকি verified contract/mint ব্যবহার করে।

payment_railstringসব সময়

Runtime rail: utxo, evm-native, solana-native, account-native, privacy-native বা token-transfer।

symbolstringসব সময়

দেখানোর identity আর সঠিক atomic-unit precision।

namestringসব সময়

দেখানোর identity আর সঠিক atomic-unit precision।

decimalsintegerসব সময়

দেখানোর identity আর সঠিক atomic-unit precision।

contract_addressstring | nullসব সময়

Token-এর canonical ERC-20 contract বা SPL mint; native asset-এ null।

coingecko_idstring | nullসব সময়

Discovery/pricing identity। Custom contract-এ null; ticker দেখে market price অনুমান কোরো না। শুধু CoinGecko metadata টোকেনকে selectable করে না।

custom_tokenbooleanসব সময়

Project-scoped fixed USD বা selected DEX pool pricing-সহ custom on-chain-verified contract।

icon_pathpath | nullসব সময়

পাওয়া গেলে locally cached token icon।

token_standarderc20 | spl-token | nullসব সময়

Verified runtime token standard; native asset-এ null।

metadata_verified_attimestamp | nullসব সময়

Promoted token-এর on-chain metadata verification time।

payment_supportedbooleanসব সময়
Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।বিস্তারিত

Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।

scanner_readybooleanসব সময়
Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।বিস্তারিত

Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।

balance_readybooleanসব সময়
Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।বিস্তারিত

Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।

default_finality_modeconfirmations | finalizedসব সময়

নতুন project policy-তে inherited default finality model।

default_required_confirmationsintegerসব সময়

Default confirmation আর monitoring policy।

default_monitoring_minutesintegerসব সময়

Default confirmation আর monitoring policy।

project_policyobject | nullসব সময়

Parent project policy।

enabledbooleanবাধ্যতামূলক

Project-এর জন্য asset চালু বা বন্ধ করে। Token-এর আগে native chain চালু থাকতে হবে।

finality_modeconfirmations | finalizedবাধ্যতামূলক

Asset rail-এর সমর্থিত finality policy। finalized-এ required_confirmations=1 লাগে।

required_confirmationsintegerবাধ্যতামূলক
Bitcoin আর EVM rail zero নেয়; অন্য confirmation rail-এ অন্তত এক, finalized-only rail-এ ঠিক এক, আর EVM rail 0–48-এ সীমিত যাতে প্রতিটি transfer transaction replay window-তে থাকে।বিস্তারিত

Bitcoin আর EVM rail zero নেয়; অন্য confirmation rail-এ অন্তত এক, finalized-only rail-এ ঠিক এক, আর EVM rail 0–48-এ সীমিত যাতে প্রতিটি transfer transaction replay window-তে থাকে।

monitoring_minutesintegerবাধ্যতামূলক

Invoice active থাকা সময় 1–10,080 মিনিটের polling window।

late_monitoring_daysintegerবাধ্যতামূলক

Invoice expiry-এর পরে 0–3,650 দিনের monitoring।

selectedbooleanসব সময়
Method store-এর saved desired configuration-এর অংশ কি না। Project policy, wallet, installed adapter আর pricing বৈধ হলে দেওয়া হয়। Temporary scanner outage নতুন invoice থেকে সরায় না।বিস্তারিত

Method store-এর saved desired configuration-এর অংশ কি না। Project policy, wallet, installed adapter আর pricing বৈধ হলে দেওয়া হয়। Temporary scanner outage নতুন invoice থেকে সরায় না।

display_orderinteger | nullসব সময়

বাছাই হলে store checkout order।

confirmation_policyobject | nullসব সময়

Project-configured asset-এর effective store policy। Project policy না থাকলে null।

finality_modeconfirmations | finalizedসব সময়

Settlement configurable block count নাকি network finality ব্যবহার করে।

project_required_confirmationsintegerসব সময়

Store override না থাকলে future invoice-এর current project default।

override_required_confirmationsinteger | nullসব সময়

Store-specific count, বা project default নিতে null।

effective_required_confirmationsintegerসব সময়

এই store আর asset-এর নতুন invoice যে count snapshot করবে।

editablebooleanসব সময়

Finality policy override করা যায় না এমন finalized network-এ false।

minimum_required_confirmationsintegerসব সময়

দুই প্রান্তসহ chain-aware lower bound; detection-time acceptance সমর্থিত rail-এই 0 দেখায়।

maximum_required_confirmationsintegerসব সময়

দুই প্রান্তসহ chain-aware upper bound।

walletobject | nullসব সময়

Native আর token asset-এর shared chain wallet।

idUUIDসব সময়

Wallet, owner project আর chain-native asset identifier।

project_idUUIDসব সময়

Wallet, owner project আর chain-native asset identifier।

native_asset_idUUIDসব সময়

Wallet, owner project আর chain-native asset identifier।

chain_slugstringসব সময়

Wallet chain আর network।

networkstringসব সময়

Wallet chain আর network।

asset_symbolstringসব সময়

Chain-native display identity।

asset_namestringসব সময়

Chain-native display identity।

statuspending | active | disabled | errorসব সময়

Wallet-এর পরিচালনাগত state।

labelstringসব সময়

Operator label।

public_keystring | nullসব সময়

Public wallet identity; seed phrase বা private key প্রকাশিত নয়।

primary_addressstring | nullসব সময়

Public wallet identity; seed phrase বা private key প্রকাশিত নয়।

derivation_schemestring | nullসব সময়

Address policy আর format।

address_formatstring | nullসব সময়

Address policy আর format।

backup_confirmed_attimestamp | nullসব সময়

Operator recovery backup নিশ্চিত করলে non-null।

activation_requiredbooleanসব সময়
Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।বিস্তারিত

Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।

activation_verified_attimestamp|nullসব সময়
Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।বিস্তারিত

Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।

receive_readinessobject | null5.5.0+
Wallet list-এ থাকে: project receiving setup আর chain scanner prerequisite। Balance, token gas আর send readiness থেকে আলাদা। অন্য wallet response-এ null থাকতে পারে।বিস্তারিত

Wallet list-এ থাকে: project receiving setup আর chain scanner prerequisite। Balance, token gas আর send readiness থেকে আলাদা। অন্য wallet response-এ null থাকতে পারে।

readybooleanসব সময়

Receive setup check পাস। Spending readiness, gas, balance refresh বা ভবিষ্যৎ quote-এর নিশ্চয়তা বোঝায় না।

invoice_creatableboolean6.0.6+
সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।বিস্তারিত

সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।

checked_attimestampসব সময়

Assessment time। List করতে network request বা address allocation হয় না।

issues[]object[]সব সময়
Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।বিস্তারিত

Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।

chain_slugstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_idUUIDজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_tickerstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

reason_codestringসব সময়
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।বিস্তারিত

scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।

messagestringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

actionstringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

required_endpoint_rolestring | nullঅন-চেইন
Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।বিস্তারিত

Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।

accepted_endpoint_roles[]string[] | nullঅন-চেইন
Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।বিস্তারিত

Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।

healthy_endpointsintegerঅন-চেইন

Healthy matching endpoint, independent-provider count নয়।

usable_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

required_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

last_checked_attimestamp | nullঅন-চেইন

শেষ matching endpoint health check, assessment time থেকে আলাদা।

monero_wallet_rpcMoneroWalletRpcBinding | nullসব সময়
Monero-র sanitized external view-only wallet-RPC binding state। Endpoint, authentication mode, account-0 primary address, technical proof flag/height আর operator attestation timestamp থাকে; credential, wallet key আর wallet file serialize হয় না।বিস্তারিত

Monero-র sanitized external view-only wallet-RPC binding state। Endpoint, authentication mode, account-0 primary address, technical proof flag/height আর operator attestation timestamp থাকে; credential, wallet key আর wallet file serialize হয় না।

last_secret_revealed_attimestamp|nullসব সময়

Console-side secret disclosure audit metadata।

secret_reveal_countintegerসব সময়

Console-side secret disclosure audit metadata।

next_receive_indexintegerসব সময়

পরের reserved child-address index।

last_scanned_heightinteger|nullসব সময়

Wallet scanner state।

last_scanned_attimestamp|nullসব সময়

Wallet scanner state।

last_errorstring|nullসব সময়

Wallet scanner state।

balances[]object[]সব সময়
৩০টি native chain rail আর verified ERC-20 ও SPL asset-এর cached balance। Monero-তে configured external view-only wallet-RPC লাগে।বিস্তারিত

৩০টি native chain rail আর verified ERC-20 ও SPL asset-এর cached balance। Monero-তে configured external view-only wallet-RPC লাগে।

wallet_idUUIDসব সময়

Wallet আর স্থায়ী asset identity।

asset_idUUIDসব সময়

Wallet আর স্থায়ী asset identity।

project_enabledbooleanসব সময়

Project asset policy-তে এই asset এখন enabled কি না।

active_store_countintegerসব সময়

বর্তমানে এই asset বেছে নেওয়া enabled store-এর সংখ্যা। এটি acceptance projection; read-only balance tracking স্বাধীন।

active_store_ids[]UUID[]সব সময়

এই project-এর যেসব enabled store এখন asset নেয়। আর API request ছাড়াই সঠিক local store filtering করা যায়।

tracking_activebooleanসব সময়
এই read-capable wallet আর registered same-chain asset background balance refresh-এর যোগ্য কি না। Project আর payment-method acceptance switch read-only tracking থামায় না।বিস্তারিত

এই read-capable wallet আর registered same-chain asset background balance refresh-এর যোগ্য কি না। Project আর payment-method acceptance switch read-only tracking থামায় না।

asset_kindnative | tokenসব সময়

Native currency বা verified contract/mint asset।

contract_addressstring | nullসব সময়

Token contract বা mint; native currency-তে null।

symbolstringসব সময়

Display identity আর atomic precision।

namestringসব সময়

Display identity আর atomic precision।

decimalsintegerসব সময়

Display identity আর atomic precision।

coingecko_idstring | nullসব সময়

Mapped হলে pricing identity।

balancedecimal string|nullসব সময়

Wallet primary address আর issued invoice address জুড়ে সঠিক display আর atomic balance। পূর্ণ মান না পাওয়া পর্যন্ত null।

balance_atomicinteger string|nullসব সময়

Wallet primary address আর issued invoice address জুড়ে সঠিক display আর atomic balance। পূর্ণ মান না পাওয়া পর্যন্ত null।

price_usddecimal string | nullসব সময়

Valuation-এ ব্যবহৃত ধারণামূলক cached USD unit price।

value_usddecimal string | nullসব সময়

Current rate থাকলে ধারণামূলক fiat valuation।

statuspending | refreshing | fresh | stale | errorসব সময়
Cached scan state। refreshing-এ completed balance থাকতে পারে: বয়স জানতে checked_at নাও। Pending মানে completed snapshot নেই। কোনোটিই transfer pending বা invoice settled প্রমাণ করে না।বিস্তারিত

Cached scan state। refreshing-এ completed balance থাকতে পারে: বয়স জানতে checked_at নাও। Pending মানে completed snapshot নেই। কোনোটিই transfer pending বা invoice settled প্রমাণ করে না।

checked_attimestamp | nullসব সময়

Completed balance scan যে সময়ের মান দেখায়।

last_errorstring | nullসব সময়

নিরাপদ operator diagnostic।

total_value_usddecimal string | nullসব সময়

Current USD price থাকা balance-এর ধারণামূলক যোগফল।

balance_statuspending | refreshing | fresh | stale | error | unknownসব সময়

সমষ্টিগত cache freshness; unknown সতর্ক fallback, আর কোনো state-ই invoice settlement প্রমাণ করে না।

balance_checked_attimestamp | nullসব সময়

Aggregate-এ থাকা প্রাসঙ্গিক successful balance check-এর মধ্যে সবচেয়ে পুরোনো।

recent_payments[]object[]সব সময়

ঠিক এই wallet-এর সর্বশেষ সর্বোচ্চ তিনটি valid detected, confirming বা final observation।

invoice_public_idUUIDসব সময়

Observation-এর সঙ্গে যুক্ত customer-facing invoice identity।

chain_slugstringসব সময়

Chain আর native বা verified token-এর display symbol।

symbolstringসব সময়

Chain আর native বা verified token-এর display symbol।

transaction_idstringসব সময়

Canonical transaction আর transfer-event identity।

event_indexintegerসব সময়

Canonical transaction আর transfer-event identity।

amountdecimal stringসব সময়

Floating-point conversion ছাড়া সঠিক observed asset amount।

statusdetected | confirming | finalসব সময়

বর্তমান valid observation state। Reorged, replaced আর invalid observation বাদ।

confirmationsintegerসব সময়

সর্বশেষ observed confirmation count।

observed_atRFC 3339 timestampসব সময়

Wholly Crypto প্রথম পেমেন্ট দেখার সময়।

created_atRFC 3339 timestampসব সময়

Wallet creation আর last update time।

updated_atRFC 3339 timestampসব সময়

Wallet creation আর last update time।

wallet_readinessreadiness enumসব সময়

শুধু wallet/policy status; scanner prerequisite-এর জন্য receive_readiness নাও।

receive_readinessobject | null5.5.0+
Shared receive setup আর store acceptance। Cached observation ব্যবহার করে; reservation বা guarantee নয়। Creation-এ requirement আর actual invoice exchange rate আবার পরীক্ষা হয়।বিস্তারিত

Shared receive setup আর store acceptance। Cached observation ব্যবহার করে; reservation বা guarantee নয়। Creation-এ requirement আর actual invoice exchange rate আবার পরীক্ষা হয়।

readybooleanসব সময়

Receive setup check পাস। Spending readiness, gas, balance refresh বা ভবিষ্যৎ quote-এর নিশ্চয়তা বোঝায় না।

invoice_creatableboolean6.0.6+
সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।বিস্তারিত

সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।

checked_attimestampসব সময়

Assessment time। List করতে network request বা address allocation হয় না।

issues[]object[]সব সময়
Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।বিস্তারিত

Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।

chain_slugstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_idUUIDজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_tickerstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

reason_codestringসব সময়
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।বিস্তারিত

scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।

messagestringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

actionstringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

required_endpoint_rolestring | nullঅন-চেইন
Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।বিস্তারিত

Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।

accepted_endpoint_roles[]string[] | nullঅন-চেইন
Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।বিস্তারিত

Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।

healthy_endpointsintegerঅন-চেইন

Healthy matching endpoint, independent-provider count নয়।

usable_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

required_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

last_checked_attimestamp | nullঅন-চেইন

শেষ matching endpoint health check, assessment time থেকে আলাদা।

lightningobject
payment_railstring
symbolstring
asset_decimalsinteger
enabledboolean
readyboolean
ব্যবহারের নোট
  • selected হলো on-chain configuration; wallet_readiness তার live eligibility gate।
  • lightning response member-এ payment_rail: lightning, symbol: BTC, asset_decimals: 11, enabled আর ready থাকে। Node credential থাকে না। Store console-এ method কনফিগার করো; assets array বদলালে Lightning বদলায় না।
  • confirmation_policy শুধু on-chain method-এ লাগে। Lightning block confirmation ছাড়া settle হয় এবং partial-payment tolerance ছাড়া পুরো BOLT11 amount লাগে।
  • এক chain-এর native আর token method সেই chain wallet-এর একই invoice destination ব্যবহার করে।
  • Embedded wallet summary readiness-only, balance খালি; current value-এর জন্য dedicated project wallets route নাও।

ত্রুটি

Error code ও retry-এর নিয়ম

PUTস্টোরের পেমেন্ট পদ্ধতি প্রতিস্থাপন করো/v1/projects/{project_id}/stores/{store_id}/payment-assetsপড়া + লেখা

Store-এর পুরো ordered asset subset এক transaction-এ প্রতিস্থাপন করে refreshed list দেয়। বাদ দেওয়া asset deselect হয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MERCHANT_API_TOKEN
Content-Typeবাধ্যতামূলকapplication/json
Acceptপ্রস্তাবিতapplication/json

Path parameter

project_idUUIDবাধ্যতামূলক

Credential-এ দেওয়া project; paused হতে পারে।

store_idUUIDবাধ্যতামূলক

project_id-এর store; paused হতে পারে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request PUT \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "assets": [
    {
      "asset_id": "YOUR_ASSET_ID",
      "display_order": 0
    }
  ]
}'

Request body

assets[]object[]বাধ্যতামূলক

পূর্ণ replacement list, সর্বোচ্চ ৬৪ entry। প্রতিটিতে unique asset_id আর 0–10,000-এর unique display_order।

asset_idUUIDবাধ্যতামূলক
display_orderintegerঐচ্ছিক

উত্তর 200 application/json

উদাহরণ response
{
  "data": [
    { "asset": { "id": "44444444-4444-4444-8444-444444444444", "symbol": "USDC" }, "selected": true, "display_order": 0, "confirmation_policy": { "finality_mode": "confirmations", "project_required_confirmations": 12, "override_required_confirmations": null, "effective_required_confirmations": 12, "editable": true, "minimum_required_confirmations": 0, "maximum_required_confirmations": 48 }, "wallet_readiness": "ready" }
  ]
}

Response field

data[]object[]
assetobjectসব সময়

Project-visible native বা verified token asset।

idUUIDসব সময়

Project আর store policy route-এ ব্যবহৃত স্থায়ী payment-asset identifier।

asset_keystringসব সময়

Canonical CAIP-style native বা contract asset identity।

chain_slugstringসব সময়

Wholly Crypto chain identifier আর configured network।

networkstringসব সময়

Wholly Crypto chain identifier আর configured network।

caip_network_idstringসব সময়

Canonical network আর asset identity।

caip_asset_idstring|nullসব সময়

Canonical network আর asset identity।

asset_kindnative | tokenসব সময়

Settlement chain currency নাকি verified contract/mint ব্যবহার করে।

payment_railstringসব সময়

Runtime rail: utxo, evm-native, solana-native, account-native, privacy-native বা token-transfer।

symbolstringসব সময়

দেখানোর identity আর সঠিক atomic-unit precision।

namestringসব সময়

দেখানোর identity আর সঠিক atomic-unit precision।

decimalsintegerসব সময়

দেখানোর identity আর সঠিক atomic-unit precision।

contract_addressstring | nullসব সময়

Token-এর canonical ERC-20 contract বা SPL mint; native asset-এ null।

coingecko_idstring | nullসব সময়

Discovery/pricing identity। Custom contract-এ null; ticker দেখে market price অনুমান কোরো না। শুধু CoinGecko metadata টোকেনকে selectable করে না।

custom_tokenbooleanসব সময়

Project-scoped fixed USD বা selected DEX pool pricing-সহ custom on-chain-verified contract।

icon_pathpath | nullসব সময়

পাওয়া গেলে locally cached token icon।

token_standarderc20 | spl-token | nullসব সময়

Verified runtime token standard; native asset-এ null।

metadata_verified_attimestamp | nullসব সময়

Promoted token-এর on-chain metadata verification time।

payment_supportedbooleanসব সময়
Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।বিস্তারিত

Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।

scanner_readybooleanসব সময়
Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।বিস্তারিত

Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।

balance_readybooleanসব সময়
Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।বিস্তারিত

Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।

default_finality_modeconfirmations | finalizedসব সময়

নতুন project policy-তে inherited default finality model।

default_required_confirmationsintegerসব সময়

Default confirmation আর monitoring policy।

default_monitoring_minutesintegerসব সময়

Default confirmation আর monitoring policy।

project_policyobject | nullসব সময়

Parent project policy।

enabledbooleanবাধ্যতামূলক

Project-এর জন্য asset চালু বা বন্ধ করে। Token-এর আগে native chain চালু থাকতে হবে।

finality_modeconfirmations | finalizedবাধ্যতামূলক

Asset rail-এর সমর্থিত finality policy। finalized-এ required_confirmations=1 লাগে।

required_confirmationsintegerবাধ্যতামূলক
Bitcoin আর EVM rail zero নেয়; অন্য confirmation rail-এ অন্তত এক, finalized-only rail-এ ঠিক এক, আর EVM rail 0–48-এ সীমিত যাতে প্রতিটি transfer transaction replay window-তে থাকে।বিস্তারিত

Bitcoin আর EVM rail zero নেয়; অন্য confirmation rail-এ অন্তত এক, finalized-only rail-এ ঠিক এক, আর EVM rail 0–48-এ সীমিত যাতে প্রতিটি transfer transaction replay window-তে থাকে।

monitoring_minutesintegerবাধ্যতামূলক

Invoice active থাকা সময় 1–10,080 মিনিটের polling window।

late_monitoring_daysintegerবাধ্যতামূলক

Invoice expiry-এর পরে 0–3,650 দিনের monitoring।

selectedbooleanসব সময়
Method store-এর saved desired configuration-এর অংশ কি না। Project policy, wallet, installed adapter আর pricing বৈধ হলে দেওয়া হয়। Temporary scanner outage নতুন invoice থেকে সরায় না।বিস্তারিত

Method store-এর saved desired configuration-এর অংশ কি না। Project policy, wallet, installed adapter আর pricing বৈধ হলে দেওয়া হয়। Temporary scanner outage নতুন invoice থেকে সরায় না।

display_orderinteger | nullসব সময়

বাছাই হলে store checkout order।

confirmation_policyobject | nullসব সময়

Project-configured asset-এর effective store policy। Project policy না থাকলে null।

finality_modeconfirmations | finalizedসব সময়

Settlement configurable block count নাকি network finality ব্যবহার করে।

project_required_confirmationsintegerসব সময়

Store override না থাকলে future invoice-এর current project default।

override_required_confirmationsinteger | nullসব সময়

Store-specific count, বা project default নিতে null।

effective_required_confirmationsintegerসব সময়

এই store আর asset-এর নতুন invoice যে count snapshot করবে।

editablebooleanসব সময়

Finality policy override করা যায় না এমন finalized network-এ false।

minimum_required_confirmationsintegerসব সময়

দুই প্রান্তসহ chain-aware lower bound; detection-time acceptance সমর্থিত rail-এই 0 দেখায়।

maximum_required_confirmationsintegerসব সময়

দুই প্রান্তসহ chain-aware upper bound।

walletobject | nullসব সময়

Native আর token asset-এর shared chain wallet।

idUUIDসব সময়

Wallet, owner project আর chain-native asset identifier।

project_idUUIDসব সময়

Wallet, owner project আর chain-native asset identifier।

native_asset_idUUIDসব সময়

Wallet, owner project আর chain-native asset identifier।

chain_slugstringসব সময়

Wallet chain আর network।

networkstringসব সময়

Wallet chain আর network।

asset_symbolstringসব সময়

Chain-native display identity।

asset_namestringসব সময়

Chain-native display identity।

statuspending | active | disabled | errorসব সময়

Wallet-এর পরিচালনাগত state।

labelstringসব সময়

Operator label।

public_keystring | nullসব সময়

Public wallet identity; seed phrase বা private key প্রকাশিত নয়।

primary_addressstring | nullসব সময়

Public wallet identity; seed phrase বা private key প্রকাশিত নয়।

derivation_schemestring | nullসব সময়

Address policy আর format।

address_formatstring | nullসব সময়

Address policy আর format।

backup_confirmed_attimestamp | nullসব সময়

Operator recovery backup নিশ্চিত করলে non-null।

activation_requiredbooleanসব সময়
Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।বিস্তারিত

Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।

activation_verified_attimestamp|nullসব সময়
Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।বিস্তারিত

Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।

receive_readinessobject | null5.5.0+
Wallet list-এ থাকে: project receiving setup আর chain scanner prerequisite। Balance, token gas আর send readiness থেকে আলাদা। অন্য wallet response-এ null থাকতে পারে।বিস্তারিত

Wallet list-এ থাকে: project receiving setup আর chain scanner prerequisite। Balance, token gas আর send readiness থেকে আলাদা। অন্য wallet response-এ null থাকতে পারে।

readybooleanসব সময়

Receive setup check পাস। Spending readiness, gas, balance refresh বা ভবিষ্যৎ quote-এর নিশ্চয়তা বোঝায় না।

invoice_creatableboolean6.0.6+
সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।বিস্তারিত

সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।

checked_attimestampসব সময়

Assessment time। List করতে network request বা address allocation হয় না।

issues[]object[]সব সময়
Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।বিস্তারিত

Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।

chain_slugstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_idUUIDজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_tickerstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

reason_codestringসব সময়
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।বিস্তারিত

scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।

messagestringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

actionstringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

required_endpoint_rolestring | nullঅন-চেইন
Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।বিস্তারিত

Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।

accepted_endpoint_roles[]string[] | nullঅন-চেইন
Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।বিস্তারিত

Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।

healthy_endpointsintegerঅন-চেইন

Healthy matching endpoint, independent-provider count নয়।

usable_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

required_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

last_checked_attimestamp | nullঅন-চেইন

শেষ matching endpoint health check, assessment time থেকে আলাদা।

monero_wallet_rpcMoneroWalletRpcBinding | nullসব সময়
Monero-র sanitized external view-only wallet-RPC binding state। Endpoint, authentication mode, account-0 primary address, technical proof flag/height আর operator attestation timestamp থাকে; credential, wallet key আর wallet file serialize হয় না।বিস্তারিত

Monero-র sanitized external view-only wallet-RPC binding state। Endpoint, authentication mode, account-0 primary address, technical proof flag/height আর operator attestation timestamp থাকে; credential, wallet key আর wallet file serialize হয় না।

last_secret_revealed_attimestamp|nullসব সময়

Console-side secret disclosure audit metadata।

secret_reveal_countintegerসব সময়

Console-side secret disclosure audit metadata।

next_receive_indexintegerসব সময়

পরের reserved child-address index।

last_scanned_heightinteger|nullসব সময়

Wallet scanner state।

last_scanned_attimestamp|nullসব সময়

Wallet scanner state।

last_errorstring|nullসব সময়

Wallet scanner state।

balances[]object[]সব সময়
৩০টি native chain rail আর verified ERC-20 ও SPL asset-এর cached balance। Monero-তে configured external view-only wallet-RPC লাগে।বিস্তারিত

৩০টি native chain rail আর verified ERC-20 ও SPL asset-এর cached balance। Monero-তে configured external view-only wallet-RPC লাগে।

wallet_idUUIDসব সময়

Wallet আর স্থায়ী asset identity।

asset_idUUIDসব সময়

Wallet আর স্থায়ী asset identity।

project_enabledbooleanসব সময়

Project asset policy-তে এই asset এখন enabled কি না।

active_store_countintegerসব সময়

বর্তমানে এই asset বেছে নেওয়া enabled store-এর সংখ্যা। এটি acceptance projection; read-only balance tracking স্বাধীন।

active_store_ids[]UUID[]সব সময়

এই project-এর যেসব enabled store এখন asset নেয়। আর API request ছাড়াই সঠিক local store filtering করা যায়।

tracking_activebooleanসব সময়
এই read-capable wallet আর registered same-chain asset background balance refresh-এর যোগ্য কি না। Project আর payment-method acceptance switch read-only tracking থামায় না।বিস্তারিত

এই read-capable wallet আর registered same-chain asset background balance refresh-এর যোগ্য কি না। Project আর payment-method acceptance switch read-only tracking থামায় না।

asset_kindnative | tokenসব সময়

Native currency বা verified contract/mint asset।

contract_addressstring | nullসব সময়

Token contract বা mint; native currency-তে null।

symbolstringসব সময়

Display identity আর atomic precision।

namestringসব সময়

Display identity আর atomic precision।

decimalsintegerসব সময়

Display identity আর atomic precision।

coingecko_idstring | nullসব সময়

Mapped হলে pricing identity।

balancedecimal string|nullসব সময়

Wallet primary address আর issued invoice address জুড়ে সঠিক display আর atomic balance। পূর্ণ মান না পাওয়া পর্যন্ত null।

balance_atomicinteger string|nullসব সময়

Wallet primary address আর issued invoice address জুড়ে সঠিক display আর atomic balance। পূর্ণ মান না পাওয়া পর্যন্ত null।

price_usddecimal string | nullসব সময়

Valuation-এ ব্যবহৃত ধারণামূলক cached USD unit price।

value_usddecimal string | nullসব সময়

Current rate থাকলে ধারণামূলক fiat valuation।

statuspending | refreshing | fresh | stale | errorসব সময়
Cached scan state। refreshing-এ completed balance থাকতে পারে: বয়স জানতে checked_at নাও। Pending মানে completed snapshot নেই। কোনোটিই transfer pending বা invoice settled প্রমাণ করে না।বিস্তারিত

Cached scan state। refreshing-এ completed balance থাকতে পারে: বয়স জানতে checked_at নাও। Pending মানে completed snapshot নেই। কোনোটিই transfer pending বা invoice settled প্রমাণ করে না।

checked_attimestamp | nullসব সময়

Completed balance scan যে সময়ের মান দেখায়।

last_errorstring | nullসব সময়

নিরাপদ operator diagnostic।

total_value_usddecimal string | nullসব সময়

Current USD price থাকা balance-এর ধারণামূলক যোগফল।

balance_statuspending | refreshing | fresh | stale | error | unknownসব সময়

সমষ্টিগত cache freshness; unknown সতর্ক fallback, আর কোনো state-ই invoice settlement প্রমাণ করে না।

balance_checked_attimestamp | nullসব সময়

Aggregate-এ থাকা প্রাসঙ্গিক successful balance check-এর মধ্যে সবচেয়ে পুরোনো।

recent_payments[]object[]সব সময়

ঠিক এই wallet-এর সর্বশেষ সর্বোচ্চ তিনটি valid detected, confirming বা final observation।

invoice_public_idUUIDসব সময়

Observation-এর সঙ্গে যুক্ত customer-facing invoice identity।

chain_slugstringসব সময়

Chain আর native বা verified token-এর display symbol।

symbolstringসব সময়

Chain আর native বা verified token-এর display symbol।

transaction_idstringসব সময়

Canonical transaction আর transfer-event identity।

event_indexintegerসব সময়

Canonical transaction আর transfer-event identity।

amountdecimal stringসব সময়

Floating-point conversion ছাড়া সঠিক observed asset amount।

statusdetected | confirming | finalসব সময়

বর্তমান valid observation state। Reorged, replaced আর invalid observation বাদ।

confirmationsintegerসব সময়

সর্বশেষ observed confirmation count।

observed_atRFC 3339 timestampসব সময়

Wholly Crypto প্রথম পেমেন্ট দেখার সময়।

created_atRFC 3339 timestampসব সময়

Wallet creation আর last update time।

updated_atRFC 3339 timestampসব সময়

Wallet creation আর last update time।

wallet_readinessreadiness enumসব সময়

শুধু wallet/policy status; scanner prerequisite-এর জন্য receive_readiness নাও।

receive_readinessobject | null5.5.0+
Shared receive setup আর store acceptance। Cached observation ব্যবহার করে; reservation বা guarantee নয়। Creation-এ requirement আর actual invoice exchange rate আবার পরীক্ষা হয়।বিস্তারিত

Shared receive setup আর store acceptance। Cached observation ব্যবহার করে; reservation বা guarantee নয়। Creation-এ requirement আর actual invoice exchange rate আবার পরীক্ষা হয়।

readybooleanসব সময়

Receive setup check পাস। Spending readiness, gas, balance refresh বা ভবিষ্যৎ quote-এর নিশ্চয়তা বোঝায় না।

invoice_creatableboolean6.0.6+
সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।বিস্তারিত

সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।

checked_attimestampসব সময়

Assessment time। List করতে network request বা address allocation হয় না।

issues[]object[]সব সময়
Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।বিস্তারিত

Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।

chain_slugstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_idUUIDজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_tickerstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

reason_codestringসব সময়
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।বিস্তারিত

scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।

messagestringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

actionstringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

required_endpoint_rolestring | nullঅন-চেইন
Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।বিস্তারিত

Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।

accepted_endpoint_roles[]string[] | nullঅন-চেইন
Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।বিস্তারিত

Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।

healthy_endpointsintegerঅন-চেইন

Healthy matching endpoint, independent-provider count নয়।

usable_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

required_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

last_checked_attimestamp | nullঅন-চেইন

শেষ matching endpoint health check, assessment time থেকে আলাদা।

ব্যবহারের নোট
  • Array সর্বোচ্চ ৬৪ unique asset আর display order নেয়।
  • Selection saved desired configuration; wallet backup-এর আগে বা chain paused থাকলেও রাখা যায়। Invoice creation শুধু ready project policy, native parent policy, wallet আর runtime check-এর method দেয়।
  • কোনো payment method না রাখতে empty assets array পাঠাও।

ত্রুটি

Error code ও retry-এর নিয়ম

PUTস্টোরের confirmation policy সেট করো/v1/projects/{project_id}/stores/{store_id}/payment-assets/{asset_id}/confirmation-policyপড়া + লেখা

এক store-specific confirmation override সেট বা clear করে refreshed store payment-method list দেয়। Asset আগে store-এ selected হতে হবে। Project, store, chain বা wallet paused থাকলেও configuration করা যায়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MERCHANT_API_TOKEN
Content-Typeবাধ্যতামূলকapplication/json
Acceptপ্রস্তাবিতapplication/json

Path parameter

project_idUUIDবাধ্যতামূলক

Credential-এ দেওয়া project; paused হতে পারে।

store_idUUIDবাধ্যতামূলক

project_id-এর store; paused হতে পারে।

asset_idUUIDবাধ্যতামূলক

আপডেট করার বর্তমানে selected store payment asset।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request PUT \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets/YOUR_ASSET_ID/confirmation-policy" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "strategy": "custom",
  "required_confirmations": 0
}'

Request body

strategyinherit | customবাধ্যতামূলক

Tagged strategy। inherit store override সরায়; custom-এ required_confirmations লাগে।

required_confirmationsintegerশুধু custom

এই asset-এর ফেরত দেওয়া minimum/maximum-এর মধ্যে পূর্ণসংখ্যা। Unknown বা extra field প্রত্যাখ্যাত।

উত্তর 200 application/json

উদাহরণ response
{
  "data": [
    {
      "asset": { "id": "YOUR_ASSET_ID", "chain_slug": "bitcoin", "symbol": "BTC" },
      "selected": true,
      "display_order": 0,
      "confirmation_policy": {
        "finality_mode": "confirmations",
        "project_required_confirmations": 2,
        "override_required_confirmations": 0,
        "effective_required_confirmations": 0,
        "editable": true,
        "minimum_required_confirmations": 0,
        "maximum_required_confirmations": 10000
      },
      "wallet_readiness": "ready"
    }
  ]
}

Response field

data[]object[]
assetobjectসব সময়

Project-visible native বা verified token asset।

idUUIDসব সময়

Project আর store policy route-এ ব্যবহৃত স্থায়ী payment-asset identifier।

asset_keystringসব সময়

Canonical CAIP-style native বা contract asset identity।

chain_slugstringসব সময়

Wholly Crypto chain identifier আর configured network।

networkstringসব সময়

Wholly Crypto chain identifier আর configured network।

caip_network_idstringসব সময়

Canonical network আর asset identity।

caip_asset_idstring|nullসব সময়

Canonical network আর asset identity।

asset_kindnative | tokenসব সময়

Settlement chain currency নাকি verified contract/mint ব্যবহার করে।

payment_railstringসব সময়

Runtime rail: utxo, evm-native, solana-native, account-native, privacy-native বা token-transfer।

symbolstringসব সময়

দেখানোর identity আর সঠিক atomic-unit precision।

namestringসব সময়

দেখানোর identity আর সঠিক atomic-unit precision।

decimalsintegerসব সময়

দেখানোর identity আর সঠিক atomic-unit precision।

contract_addressstring | nullসব সময়

Token-এর canonical ERC-20 contract বা SPL mint; native asset-এ null।

coingecko_idstring | nullসব সময়

Discovery/pricing identity। Custom contract-এ null; ticker দেখে market price অনুমান কোরো না। শুধু CoinGecko metadata টোকেনকে selectable করে না।

custom_tokenbooleanসব সময়

Project-scoped fixed USD বা selected DEX pool pricing-সহ custom on-chain-verified contract।

icon_pathpath | nullসব সময়

পাওয়া গেলে locally cached token icon।

token_standarderc20 | spl-token | nullসব সময়

Verified runtime token standard; native asset-এ null।

metadata_verified_attimestamp | nullসব সময়

Promoted token-এর on-chain metadata verification time।

payment_supportedbooleanসব সময়
Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।বিস্তারিত

Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।

scanner_readybooleanসব সময়
Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।বিস্তারিত

Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।

balance_readybooleanসব সময়
Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।বিস্তারিত

Build-time registry gate। scanner_ready মানে payment scanner runtime installed; payment confirmation-এ configured সংখ্যক healthy exact-role provider লাগে (ডিফল্ট ২, চাইলে ১); 6.0.6 থেকে সাময়িক scanner availability invoice creation আটকায় না। Implemented balance adapter-এই balance_ready true।

default_finality_modeconfirmations | finalizedসব সময়

নতুন project policy-তে inherited default finality model।

default_required_confirmationsintegerসব সময়

Default confirmation আর monitoring policy।

default_monitoring_minutesintegerসব সময়

Default confirmation আর monitoring policy।

project_policyobject | nullসব সময়

Parent project policy।

enabledbooleanবাধ্যতামূলক

Project-এর জন্য asset চালু বা বন্ধ করে। Token-এর আগে native chain চালু থাকতে হবে।

finality_modeconfirmations | finalizedবাধ্যতামূলক

Asset rail-এর সমর্থিত finality policy। finalized-এ required_confirmations=1 লাগে।

required_confirmationsintegerবাধ্যতামূলক
Bitcoin আর EVM rail zero নেয়; অন্য confirmation rail-এ অন্তত এক, finalized-only rail-এ ঠিক এক, আর EVM rail 0–48-এ সীমিত যাতে প্রতিটি transfer transaction replay window-তে থাকে।বিস্তারিত

Bitcoin আর EVM rail zero নেয়; অন্য confirmation rail-এ অন্তত এক, finalized-only rail-এ ঠিক এক, আর EVM rail 0–48-এ সীমিত যাতে প্রতিটি transfer transaction replay window-তে থাকে।

monitoring_minutesintegerবাধ্যতামূলক

Invoice active থাকা সময় 1–10,080 মিনিটের polling window।

late_monitoring_daysintegerবাধ্যতামূলক

Invoice expiry-এর পরে 0–3,650 দিনের monitoring।

selectedbooleanসব সময়
Method store-এর saved desired configuration-এর অংশ কি না। Project policy, wallet, installed adapter আর pricing বৈধ হলে দেওয়া হয়। Temporary scanner outage নতুন invoice থেকে সরায় না।বিস্তারিত

Method store-এর saved desired configuration-এর অংশ কি না। Project policy, wallet, installed adapter আর pricing বৈধ হলে দেওয়া হয়। Temporary scanner outage নতুন invoice থেকে সরায় না।

display_orderinteger | nullসব সময়

বাছাই হলে store checkout order।

confirmation_policyobject | nullসব সময়

Project-configured asset-এর effective store policy। Project policy না থাকলে null।

finality_modeconfirmations | finalizedসব সময়

Settlement configurable block count নাকি network finality ব্যবহার করে।

project_required_confirmationsintegerসব সময়

Store override না থাকলে future invoice-এর current project default।

override_required_confirmationsinteger | nullসব সময়

Store-specific count, বা project default নিতে null।

effective_required_confirmationsintegerসব সময়

এই store আর asset-এর নতুন invoice যে count snapshot করবে।

editablebooleanসব সময়

Finality policy override করা যায় না এমন finalized network-এ false।

minimum_required_confirmationsintegerসব সময়

দুই প্রান্তসহ chain-aware lower bound; detection-time acceptance সমর্থিত rail-এই 0 দেখায়।

maximum_required_confirmationsintegerসব সময়

দুই প্রান্তসহ chain-aware upper bound।

walletobject | nullসব সময়

Native আর token asset-এর shared chain wallet।

idUUIDসব সময়

Wallet, owner project আর chain-native asset identifier।

project_idUUIDসব সময়

Wallet, owner project আর chain-native asset identifier।

native_asset_idUUIDসব সময়

Wallet, owner project আর chain-native asset identifier।

chain_slugstringসব সময়

Wallet chain আর network।

networkstringসব সময়

Wallet chain আর network।

asset_symbolstringসব সময়

Chain-native display identity।

asset_namestringসব সময়

Chain-native display identity।

statuspending | active | disabled | errorসব সময়

Wallet-এর পরিচালনাগত state।

labelstringসব সময়

Operator label।

public_keystring | nullসব সময়

Public wallet identity; seed phrase বা private key প্রকাশিত নয়।

primary_addressstring | nullসব সময়

Public wallet identity; seed phrase বা private key প্রকাশিত নয়।

derivation_schemestring | nullসব সময়

Address policy আর format।

address_formatstring | nullসব সময়

Address policy আর format।

backup_confirmed_attimestamp | nullসব সময়

Operator recovery backup নিশ্চিত করলে non-null।

activation_requiredbooleanসব সময়
Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।বিস্তারিত

Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।

activation_verified_attimestamp|nullসব সময়
Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।বিস্তারিত

Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।

receive_readinessobject | null5.5.0+
Wallet list-এ থাকে: project receiving setup আর chain scanner prerequisite। Balance, token gas আর send readiness থেকে আলাদা। অন্য wallet response-এ null থাকতে পারে।বিস্তারিত

Wallet list-এ থাকে: project receiving setup আর chain scanner prerequisite। Balance, token gas আর send readiness থেকে আলাদা। অন্য wallet response-এ null থাকতে পারে।

readybooleanসব সময়

Receive setup check পাস। Spending readiness, gas, balance refresh বা ভবিষ্যৎ quote-এর নিশ্চয়তা বোঝায় না।

invoice_creatableboolean6.0.6+
সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।বিস্তারিত

সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।

checked_attimestampসব সময়

Assessment time। List করতে network request বা address allocation হয় না।

issues[]object[]সব সময়
Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।বিস্তারিত

Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।

chain_slugstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_idUUIDজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_tickerstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

reason_codestringসব সময়
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।বিস্তারিত

scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।

messagestringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

actionstringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

required_endpoint_rolestring | nullঅন-চেইন
Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।বিস্তারিত

Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।

accepted_endpoint_roles[]string[] | nullঅন-চেইন
Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।বিস্তারিত

Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।

healthy_endpointsintegerঅন-চেইন

Healthy matching endpoint, independent-provider count নয়।

usable_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

required_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

last_checked_attimestamp | nullঅন-চেইন

শেষ matching endpoint health check, assessment time থেকে আলাদা।

monero_wallet_rpcMoneroWalletRpcBinding | nullসব সময়
Monero-র sanitized external view-only wallet-RPC binding state। Endpoint, authentication mode, account-0 primary address, technical proof flag/height আর operator attestation timestamp থাকে; credential, wallet key আর wallet file serialize হয় না।বিস্তারিত

Monero-র sanitized external view-only wallet-RPC binding state। Endpoint, authentication mode, account-0 primary address, technical proof flag/height আর operator attestation timestamp থাকে; credential, wallet key আর wallet file serialize হয় না।

last_secret_revealed_attimestamp|nullসব সময়

Console-side secret disclosure audit metadata।

secret_reveal_countintegerসব সময়

Console-side secret disclosure audit metadata।

next_receive_indexintegerসব সময়

পরের reserved child-address index।

last_scanned_heightinteger|nullসব সময়

Wallet scanner state।

last_scanned_attimestamp|nullসব সময়

Wallet scanner state।

last_errorstring|nullসব সময়

Wallet scanner state।

balances[]object[]সব সময়
৩০টি native chain rail আর verified ERC-20 ও SPL asset-এর cached balance। Monero-তে configured external view-only wallet-RPC লাগে।বিস্তারিত

৩০টি native chain rail আর verified ERC-20 ও SPL asset-এর cached balance। Monero-তে configured external view-only wallet-RPC লাগে।

wallet_idUUIDসব সময়

Wallet আর স্থায়ী asset identity।

asset_idUUIDসব সময়

Wallet আর স্থায়ী asset identity।

project_enabledbooleanসব সময়

Project asset policy-তে এই asset এখন enabled কি না।

active_store_countintegerসব সময়

বর্তমানে এই asset বেছে নেওয়া enabled store-এর সংখ্যা। এটি acceptance projection; read-only balance tracking স্বাধীন।

active_store_ids[]UUID[]সব সময়

এই project-এর যেসব enabled store এখন asset নেয়। আর API request ছাড়াই সঠিক local store filtering করা যায়।

tracking_activebooleanসব সময়
এই read-capable wallet আর registered same-chain asset background balance refresh-এর যোগ্য কি না। Project আর payment-method acceptance switch read-only tracking থামায় না।বিস্তারিত

এই read-capable wallet আর registered same-chain asset background balance refresh-এর যোগ্য কি না। Project আর payment-method acceptance switch read-only tracking থামায় না।

asset_kindnative | tokenসব সময়

Native currency বা verified contract/mint asset।

contract_addressstring | nullসব সময়

Token contract বা mint; native currency-তে null।

symbolstringসব সময়

Display identity আর atomic precision।

namestringসব সময়

Display identity আর atomic precision।

decimalsintegerসব সময়

Display identity আর atomic precision।

coingecko_idstring | nullসব সময়

Mapped হলে pricing identity।

balancedecimal string|nullসব সময়

Wallet primary address আর issued invoice address জুড়ে সঠিক display আর atomic balance। পূর্ণ মান না পাওয়া পর্যন্ত null।

balance_atomicinteger string|nullসব সময়

Wallet primary address আর issued invoice address জুড়ে সঠিক display আর atomic balance। পূর্ণ মান না পাওয়া পর্যন্ত null।

price_usddecimal string | nullসব সময়

Valuation-এ ব্যবহৃত ধারণামূলক cached USD unit price।

value_usddecimal string | nullসব সময়

Current rate থাকলে ধারণামূলক fiat valuation।

statuspending | refreshing | fresh | stale | errorসব সময়
Cached scan state। refreshing-এ completed balance থাকতে পারে: বয়স জানতে checked_at নাও। Pending মানে completed snapshot নেই। কোনোটিই transfer pending বা invoice settled প্রমাণ করে না।বিস্তারিত

Cached scan state। refreshing-এ completed balance থাকতে পারে: বয়স জানতে checked_at নাও। Pending মানে completed snapshot নেই। কোনোটিই transfer pending বা invoice settled প্রমাণ করে না।

checked_attimestamp | nullসব সময়

Completed balance scan যে সময়ের মান দেখায়।

last_errorstring | nullসব সময়

নিরাপদ operator diagnostic।

total_value_usddecimal string | nullসব সময়

Current USD price থাকা balance-এর ধারণামূলক যোগফল।

balance_statuspending | refreshing | fresh | stale | error | unknownসব সময়

সমষ্টিগত cache freshness; unknown সতর্ক fallback, আর কোনো state-ই invoice settlement প্রমাণ করে না।

balance_checked_attimestamp | nullসব সময়

Aggregate-এ থাকা প্রাসঙ্গিক successful balance check-এর মধ্যে সবচেয়ে পুরোনো।

recent_payments[]object[]সব সময়

ঠিক এই wallet-এর সর্বশেষ সর্বোচ্চ তিনটি valid detected, confirming বা final observation।

invoice_public_idUUIDসব সময়

Observation-এর সঙ্গে যুক্ত customer-facing invoice identity।

chain_slugstringসব সময়

Chain আর native বা verified token-এর display symbol।

symbolstringসব সময়

Chain আর native বা verified token-এর display symbol।

transaction_idstringসব সময়

Canonical transaction আর transfer-event identity।

event_indexintegerসব সময়

Canonical transaction আর transfer-event identity।

amountdecimal stringসব সময়

Floating-point conversion ছাড়া সঠিক observed asset amount।

statusdetected | confirming | finalসব সময়

বর্তমান valid observation state। Reorged, replaced আর invalid observation বাদ।

confirmationsintegerসব সময়

সর্বশেষ observed confirmation count।

observed_atRFC 3339 timestampসব সময়

Wholly Crypto প্রথম পেমেন্ট দেখার সময়।

created_atRFC 3339 timestampসব সময়

Wallet creation আর last update time।

updated_atRFC 3339 timestampসব সময়

Wallet creation আর last update time।

wallet_readinessreadiness enumসব সময়

শুধু wallet/policy status; scanner prerequisite-এর জন্য receive_readiness নাও।

receive_readinessobject | null5.5.0+
Shared receive setup আর store acceptance। Cached observation ব্যবহার করে; reservation বা guarantee নয়। Creation-এ requirement আর actual invoice exchange rate আবার পরীক্ষা হয়।বিস্তারিত

Shared receive setup আর store acceptance। Cached observation ব্যবহার করে; reservation বা guarantee নয়। Creation-এ requirement আর actual invoice exchange rate আবার পরীক্ষা হয়।

readybooleanসব সময়

Receive setup check পাস। Spending readiness, gas, balance refresh বা ভবিষ্যৎ quote-এর নিশ্চয়তা বোঝায় না।

invoice_creatableboolean6.0.6+
সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।বিস্তারিত

সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।

checked_attimestampসব সময়

Assessment time। List করতে network request বা address allocation হয় না।

issues[]object[]সব সময়
Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।বিস্তারিত

Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।

chain_slugstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_idUUIDজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_tickerstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

reason_codestringসব সময়
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।বিস্তারিত

scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।

messagestringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

actionstringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

required_endpoint_rolestring | nullঅন-চেইন
Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।বিস্তারিত

Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।

accepted_endpoint_roles[]string[] | nullঅন-চেইন
Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।বিস্তারিত

Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।

healthy_endpointsintegerঅন-চেইন

Healthy matching endpoint, independent-provider count নয়।

usable_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

required_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

last_checked_attimestamp | nullঅন-চেইন

শেষ matching endpoint health check, assessment time থেকে আলাদা।

ব্যবহারের নোট
  • Store override সরিয়ে future invoice-এ current project default নিতে {"strategy":"inherit"} নাও।
  • Finalized network editable false ফেরত দেয় আর Network finality ব্যবহার করে; custom block-count override নেয় না।
  • 0 মানে শনাক্ত হওয়াতেই গ্রহণ, network confirmation আর reorg protection ছাড়া। শুধু minimum_required_confirmations 0 হলে নেওয়া হয়।
  • Policy change শুধু নতুন invoice-এ লাগে। Existing invoice creation-এর project/store confirmation policy snapshot রাখে।
  • একবারে এক asset update; একই store asset-এর concurrent edit ক্রমানুসারে করো এবং refreshed response-কে current state ধরো।

ত্রুটি

Error code ও retry-এর নিয়ম

GETপ্রকল্পের ওয়ালেট আর ব্যালান্সের তালিকা/v1/projects/{project_id}/walletsশুধু পড়া

Public wallet metadata আর wallet-এর সঠিক chain/network-এর সব registered balance-capable asset ফেরত দেয়। ৩০টি native chain rail covered; verified ERC-20 আর SPL asset-ও tracked। প্রথম scan-এর আগেও বা payment-এ accepted না হলেও asset সঙ্গে সঙ্গে দেখায়। project_enabled payment acceptance জানায়; tracking_active স্বাধীনভাবে read-only refresh eligibility জানায়। Monero-তে project-bound external view-only wallet-RPC লাগে। Console Scan balances প্রতি-asset progress/error-সহ সীমিত read-কে অগ্রাধিকার দেয়; সম্পূর্ণ cycle-ই fresh total আপডেট করে। Invoice settlement transaction-level monitoring আর confirmation policy-তে হয়, cached balance-এ নয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MERCHANT_API_TOKEN
Acceptপ্রস্তাবিতapplication/json

Path parameter

project_idUUIDবাধ্যতামূলক

Credential-এ দেওয়া enabled project।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/wallets" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

উত্তর 200 application/json

উদাহরণ response
{
  "data": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "project_id": "11111111-1111-4111-8111-111111111111",
      "native_asset_id": "10000000-0000-4000-8000-000000000003",
      "chain_slug": "ethereum",
      "network": "mainnet",
      "asset_symbol": "ETH",
      "asset_name": "Ethereum",
      "status": "active",
      "label": "Primary Ethereum wallet",
      "public_key": "0x…",
      "primary_address": "0x…",
      "derivation_scheme": "bip44",
      "address_format": "eip55",
      "backup_confirmed_at": "2026-08-31T17:00:00Z",
      "last_secret_revealed_at": null,
      "secret_reveal_count": 0,
      "next_receive_index": 43,
      "last_scanned_height": 23123456,
      "last_scanned_at": "2026-08-31T18:05:00Z",
      "last_error": null,
      "balances": [
        { "wallet_id": "55555555-5555-4555-8555-555555555555", "asset_id": "10000000-0000-4000-8000-000000000003", "project_enabled": true, "tracking_active": true, "asset_kind": "native", "contract_address": null, "symbol": "ETH", "name": "Ethereum", "decimals": 18, "coingecko_id": "ethereum", "balance": "0.125", "balance_atomic": "125000000000000000", "price_usd": "4500", "value_usd": "562.50", "status": "fresh", "checked_at": "2026-08-31T18:05:00Z", "last_error": null },
        { "wallet_id": "55555555-5555-4555-8555-555555555555", "asset_id": "10000000-0000-4000-8000-000000000099", "project_enabled": false, "tracking_active": true, "asset_kind": "token", "contract_address": "0xA0b86991c6218b36c1d19d4a2e9eb0cE3606eB48", "symbol": "USDC", "name": "USDC", "decimals": 6, "coingecko_id": "usd-coin", "balance": null, "balance_atomic": null, "price_usd": "1", "value_usd": null, "status": "pending", "checked_at": null, "last_error": null }
      ],
      "total_value_usd": "562.50",
      "balance_status": "fresh",
      "balance_checked_at": "2026-08-31T18:05:00Z",
      "recent_payments": [
        { "invoice_public_id": "0a6a98db-d93d-48ee-8c3c-fd45f90c4a50", "chain_slug": "ethereum", "symbol": "USDC", "transaction_id": "0x…", "event_index": 0, "amount": "25", "status": "final", "confirmations": 12, "observed_at": "2026-08-31T18:04:00Z" }
      ],
      "created_at": "2026-08-31T16:00:00Z",
      "updated_at": "2026-08-31T18:05:00Z"
    }
  ]
}

Response field

data[]object[]
idUUIDসব সময়

Wallet, owner project আর chain-native asset identifier।

project_idUUIDসব সময়

Wallet, owner project আর chain-native asset identifier।

native_asset_idUUIDসব সময়

Wallet, owner project আর chain-native asset identifier।

chain_slugstringসব সময়

Wallet chain আর network।

networkstringসব সময়

Wallet chain আর network।

asset_symbolstringসব সময়

Chain-native display identity।

asset_namestringসব সময়

Chain-native display identity।

statuspending | active | disabled | errorসব সময়

Wallet-এর পরিচালনাগত state।

labelstringসব সময়

Operator label।

public_keystring | nullসব সময়

Public wallet identity; seed phrase বা private key প্রকাশিত নয়।

primary_addressstring | nullসব সময়

Public wallet identity; seed phrase বা private key প্রকাশিত নয়।

derivation_schemestring | nullসব সময়

Address policy আর format।

address_formatstring | nullসব সময়

Address policy আর format।

backup_confirmed_attimestamp | nullসব সময়

Operator recovery backup নিশ্চিত করলে non-null।

activation_requiredbooleanসব সময়
Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।বিস্তারিত

Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।

activation_verified_attimestamp|nullসব সময়
Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।বিস্তারিত

Operator দেখানো address fund করা এবং configured scanner provider ঠিক সেই account verify না করা পর্যন্ত XRP আর Stellar shared account unavailable। স্থায়ী proof-এর মেয়াদ শেষ হয় না; live scanner health payment verification-এর জন্য আলাদা পরীক্ষা হয়, invoice creation-এর জন্য নয়।

receive_readinessobject | null5.5.0+
Wallet list-এ থাকে: project receiving setup আর chain scanner prerequisite। Balance, token gas আর send readiness থেকে আলাদা। অন্য wallet response-এ null থাকতে পারে।বিস্তারিত

Wallet list-এ থাকে: project receiving setup আর chain scanner prerequisite। Balance, token gas আর send readiness থেকে আলাদা। অন্য wallet response-এ null থাকতে পারে।

readybooleanসব সময়

Receive setup check পাস। Spending readiness, gas, balance refresh বা ভবিষ্যৎ quote-এর নিশ্চয়তা বোঝায় না।

invoice_creatableboolean6.0.6+
সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।বিস্তারিত

সাময়িক scanner warning সত্ত্বেও configuration invoice method তৈরি করতে দেয়। Currency pricing creation-এ পরীক্ষা হয়। এটি payment verification নয়: invoice_creatable true হলেও ready false হতে পারে। Wallet না থাকা, disabled policy আর unsupported adapter নিরাপদে ব্যর্থ হয়।

checked_attimestampসব সময়

Assessment time। List করতে network request বা address allocation হয় না।

issues[]object[]সব সময়
Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।বিস্তারিত

Ready হলে খালি; নইলে receive warning বা configuration blocker। Temporary scanner warning আর invoice setup failure আলাদা করতে invoice_creatable দেখো।

chain_slugstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_idUUIDজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

asset_tickerstringজানা থাকলে

প্রভাবিত chain আর asset চিহ্নিত করে। Lightning-এ asset_id বাদ থাকতে পারে।

reason_codestringসব সময়
scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।বিস্তারিত

scanner_provider_quorum, scanner_not_checked, scanner_unavailable, wallet_missing, wallet_disabled, wallet_backup_required, wallet_key_unavailable, wallet_activation_required, monero_binding_unavailable, rate_unavailable, custom_rate_unavailable, lightning_unavailable, project_disabled, store_disabled, chain_disabled, asset_disabled বা asset_not_accepted।

messagestringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

actionstringপাওয়া গেলে
মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।বিস্তারিত

মার্চেন্টের জন্য ব্যাখ্যা আর action identifier: chain_connections, wallets, rates, payment_methods, project_settings বা store_settings। Credential বা private provider URL নয়।

required_endpoint_rolestring | nullঅন-চেইন
Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।বিস্তারিত

Preferred scanner API role (পুরোনো field)। পুরো compatibility list-এর জন্য accepted_endpoint_roles নাও। Basic node health payment-history support প্রমাণ করে না।

accepted_endpoint_roles[]string[] | nullঅন-চেইন
Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।বিস্তারিত

Compatible API dialect, endpoint history বা capacity-এর প্রমাণ নয়। Raw node-rpc BTC/BCH/LTC/DOGE/DASH আর transparent ZEC (পূর্ণ decoded block, 1–48 confirmation), solidified native TRX, algod-এ native ALGO, Octez-এ XTZ, SCALE metadata-তে finalized Asset Hub DOT আর invoice memo ID-সহ Stellar RPC-তে native XLM সমর্থন করে। Pruned বা অসম্পূর্ণ history যোগ্য নয়। Raw adapter token rail যোগ করে না। Indexed API বিকল্প থাকে; নিচের rail table দেখো। Mixed raw/indexed source সীমিত window স্বাধীনভাবে verify করে; ডিফল্ট দুই independent provider, একই operator-এর alias নয়। Basic node height, ORDnet chain info আর non-EVM rail-এর EVM relay receive proof নয়। Monero-তে এখনো project-bound view-only wallet-RPC লাগে।

healthy_endpointsintegerঅন-চেইন

Healthy matching endpoint, independent-provider count নয়।

usable_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

required_independent_providersintegerঅন-চেইন
ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।বিস্তারিত

ব্যবহারযোগ্য verification slot, সর্বোচ্চ দুই। required_independent_providers chain setting: ডিফল্ট ২, বা explicit administrator opt-in-এর পরে ১। Two-provider mode-এ provider key এবং host দুটোই আলাদা চাই। Disabled, stale (দশ মিনিটের বেশি) বা cooling-down source slot পূরণ করে না। Lightning-এর নিজস্ব connection rule।

last_checked_attimestamp | nullঅন-চেইন

শেষ matching endpoint health check, assessment time থেকে আলাদা।

monero_wallet_rpcMoneroWalletRpcBinding | nullসব সময়
Monero-র sanitized external view-only wallet-RPC binding state। Endpoint, authentication mode, account-0 primary address, technical proof flag/height আর operator attestation timestamp থাকে; credential, wallet key আর wallet file serialize হয় না।বিস্তারিত

Monero-র sanitized external view-only wallet-RPC binding state। Endpoint, authentication mode, account-0 primary address, technical proof flag/height আর operator attestation timestamp থাকে; credential, wallet key আর wallet file serialize হয় না।

last_secret_revealed_attimestamp|nullসব সময়

Console-side secret disclosure audit metadata।

secret_reveal_countintegerসব সময়

Console-side secret disclosure audit metadata।

next_receive_indexintegerসব সময়

পরের reserved child-address index।

last_scanned_heightinteger|nullসব সময়

Wallet scanner state।

last_scanned_attimestamp|nullসব সময়

Wallet scanner state।

last_errorstring|nullসব সময়

Wallet scanner state।

balances[]object[]সব সময়
৩০টি native chain rail আর verified ERC-20 ও SPL asset-এর cached balance। Monero-তে configured external view-only wallet-RPC লাগে।বিস্তারিত

৩০টি native chain rail আর verified ERC-20 ও SPL asset-এর cached balance। Monero-তে configured external view-only wallet-RPC লাগে।

wallet_idUUIDসব সময়

Wallet আর স্থায়ী asset identity।

asset_idUUIDসব সময়

Wallet আর স্থায়ী asset identity।

project_enabledbooleanসব সময়

Project asset policy-তে এই asset এখন enabled কি না।

active_store_countintegerসব সময়

বর্তমানে এই asset বেছে নেওয়া enabled store-এর সংখ্যা। এটি acceptance projection; read-only balance tracking স্বাধীন।

active_store_ids[]UUID[]সব সময়

এই project-এর যেসব enabled store এখন asset নেয়। আর API request ছাড়াই সঠিক local store filtering করা যায়।

tracking_activebooleanসব সময়
এই read-capable wallet আর registered same-chain asset background balance refresh-এর যোগ্য কি না। Project আর payment-method acceptance switch read-only tracking থামায় না।বিস্তারিত

এই read-capable wallet আর registered same-chain asset background balance refresh-এর যোগ্য কি না। Project আর payment-method acceptance switch read-only tracking থামায় না।

asset_kindnative | tokenসব সময়

Native currency বা verified contract/mint asset।

contract_addressstring | nullসব সময়

Token contract বা mint; native currency-তে null।

symbolstringসব সময়

Display identity আর atomic precision।

namestringসব সময়

Display identity আর atomic precision।

decimalsintegerসব সময়

Display identity আর atomic precision।

coingecko_idstring | nullসব সময়

Mapped হলে pricing identity।

balancedecimal string|nullসব সময়

Wallet primary address আর issued invoice address জুড়ে সঠিক display আর atomic balance। পূর্ণ মান না পাওয়া পর্যন্ত null।

balance_atomicinteger string|nullসব সময়

Wallet primary address আর issued invoice address জুড়ে সঠিক display আর atomic balance। পূর্ণ মান না পাওয়া পর্যন্ত null।

price_usddecimal string | nullসব সময়

Valuation-এ ব্যবহৃত ধারণামূলক cached USD unit price।

value_usddecimal string | nullসব সময়

Current rate থাকলে ধারণামূলক fiat valuation।

statuspending | refreshing | fresh | stale | errorসব সময়
Cached scan state। refreshing-এ completed balance থাকতে পারে: বয়স জানতে checked_at নাও। Pending মানে completed snapshot নেই। কোনোটিই transfer pending বা invoice settled প্রমাণ করে না।বিস্তারিত

Cached scan state। refreshing-এ completed balance থাকতে পারে: বয়স জানতে checked_at নাও। Pending মানে completed snapshot নেই। কোনোটিই transfer pending বা invoice settled প্রমাণ করে না।

checked_attimestamp | nullসব সময়

Completed balance scan যে সময়ের মান দেখায়।

last_errorstring | nullসব সময়

নিরাপদ operator diagnostic।

total_value_usddecimal string | nullসব সময়

Current USD price থাকা balance-এর ধারণামূলক যোগফল।

balance_statuspending | refreshing | fresh | stale | error | unknownসব সময়

সমষ্টিগত cache freshness; unknown সতর্ক fallback, আর কোনো state-ই invoice settlement প্রমাণ করে না।

balance_checked_attimestamp | nullসব সময়

Aggregate-এ থাকা প্রাসঙ্গিক successful balance check-এর মধ্যে সবচেয়ে পুরোনো।

recent_payments[]object[]সব সময়

ঠিক এই wallet-এর সর্বশেষ সর্বোচ্চ তিনটি valid detected, confirming বা final observation।

invoice_public_idUUIDসব সময়

Observation-এর সঙ্গে যুক্ত customer-facing invoice identity।

chain_slugstringসব সময়

Chain আর native বা verified token-এর display symbol।

symbolstringসব সময়

Chain আর native বা verified token-এর display symbol।

transaction_idstringসব সময়

Canonical transaction আর transfer-event identity।

event_indexintegerসব সময়

Canonical transaction আর transfer-event identity।

amountdecimal stringসব সময়

Floating-point conversion ছাড়া সঠিক observed asset amount।

statusdetected | confirming | finalসব সময়

বর্তমান valid observation state। Reorged, replaced আর invalid observation বাদ।

confirmationsintegerসব সময়

সর্বশেষ observed confirmation count।

observed_atRFC 3339 timestampসব সময়

Wholly Crypto প্রথম পেমেন্ট দেখার সময়।

created_atRFC 3339 timestampসব সময়

Wallet creation আর last update time।

updated_atRFC 3339 timestampসব সময়

Wallet creation আর last update time।

ব্যবহারের নোট
  • এই bearer route recovery phrase, private key, encrypted secret বা spending method ফেরত দেয় না।
  • নতুন registered same-chain asset প্রথম completed scan-এর আগে null balance আর pending status-এ আসে; বানানো zero দেখানো হয় না।
  • Project, payment acceptance-এর wallet, native rail বা individual asset বন্ধ করলেও read-only balance tracking থামে না: primary address থাকা active আর disabled wallet সব registered supported same-chain asset refresh করে। Pending আর error wallet scan হয় না।
  • project_enabled শুধু project-এর asset acceptance policy জানায়; tracking_active true থাকলেও false হতে পারে।
  • balance আর balance_atomic exact string; price_usd, value_usd আর total_value_usd ধারণামূলক, null হতে পারে। Fresh balance status fresh market price নিশ্চিত করে না।
  • Valuation সর্বোচ্চ দুই ঘণ্টা পুরোনো CoinGecko price আগে নেয়। Native coin আর verified canonical USDC/USDT সর্বোচ্চ পাঁচ মিনিট পুরোনো enabled Kraken/Binance USD quote fallback নিতে পারে, primary provider আগে। Dollar peg অনুমান বা শুধু ticker-ভিত্তিক custom-token pricing নয়; project fixed/DEX price আলাদা। Invoice quote অপরিবর্তিত।
  • Pending-এ complete snapshot নেই। Refreshing last completed amount আর checked_at রাখে; blockchain transfer pending মানে নয়। Stale/error amount-এও পুরোনো value থাকতে পারে। Unavailable cache-কে zero বা missing payment ধরো না। নিয়মিত EVM/Solana refresh audit-এর মাঝে সম্প্রতি পরীক্ষা করা empty address সর্বোচ্চ ৩০ মিনিট reuse করে, funded/new/changed address আবার দেখে। Console-এর explicit Scan balances full scan চায়।
  • recent_payments প্রতি wallet-এ তিন observation-এ সীমিত এবং invalidated history বাদ দেয়।

ত্রুটি

Error code ও retry-এর নিয়ম

POSTইনভয়েস তৈরি করো/v1/projects/{project_id}/stores/{store_id}/invoicesপড়া + লেখা

Wallet destination, fresh exact quote, audit history আর notification outbox entry-সহ এক transaction-এ invoice তৈরি করে। একই credential আর Idempotency-Key-তে হুবহু raw body byte replay করলে original invoice ফেরত আসে।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MERCHANT_API_TOKEN
Idempotency-Keyবাধ্যতামূলকWhitespace ছাড়া unique 1–128 visible ASCII অক্ষর।
Content-Typeপ্রস্তাবিতapplication/json। বর্তমান raw-body handler media type বাধ্য না করেই JSON parse করে।
Acceptপ্রস্তাবিতapplication/json

Path parameter

project_idUUIDবাধ্যতামূলক

Project → Settings → API IDs থেকে Project API ID কপি করো। Credential-এ assigned হতে হবে; readable project identifier গ্রহণ হয় না।

store_idUUIDবাধ্যতামূলক

Project → Stores → store বেছে নাও → Basic → API IDs থেকে Store API ID কপি করো। Default store-এও লাগে; enabled আর project_id-এর হতে হবে।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new invoice.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: order-1042-attempt-1' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "amount": "49.90",
  "currency": "USD"
}'

Request body

amountstringবাধ্যতামূলক
Sign বা exponent ছাড়া plain unsigned decimal string, সর্বোচ্চ ৪৮ integer digit আর ৩০ decimal place। ডিফল্টে positive হতে হবে। Store চাইলে Stores → Invoice-এ zero-amount invoice নিতে পারে; zero total অর্থ গ্রহণ, address allocation বা processing fee ছাড়াই settled হয়।বিস্তারিত

Sign বা exponent ছাড়া plain unsigned decimal string, সর্বোচ্চ ৪৮ integer digit আর ৩০ decimal place। ডিফল্টে positive হতে হবে। Store চাইলে Stores → Invoice-এ zero-amount invoice নিতে পারে; zero total অর্থ গ্রহণ, address allocation বা processing fee ছাড়াই settled হয়।

currencystring | nullঐচ্ছিক
সমর্থিত তিন অক্ষরের fiat currency, uppercase করা হয়। না দিলে বা null হলে store invoice currency। Creation-এ স্বাধীনভাবে পাওয়া billing conversion rate-ও লাগে।বিস্তারিত

সমর্থিত তিন অক্ষরের fiat currency, uppercase করা হয়। না দিলে বা null হলে store invoice currency। Creation-এ স্বাধীনভাবে পাওয়া billing conversion rate-ও লাগে।

payment_methods[]object[] | nullঐচ্ছিক
এই invoice-এর জন্য store-enabled method বেছে নাও। Merchant 5.4.0+: unknown/inactive/unaccepted পছন্দ উপেক্ষা; কিছু না মিললে store default। Omitted/null-ও store default; [] অবৈধ। Method চালু করে না বা store setting বদলায় না। নিচের selection schema দেখো।বিস্তারিত

এই invoice-এর জন্য store-enabled method বেছে নাও। Merchant 5.4.0+: unknown/inactive/unaccepted পছন্দ উপেক্ষা; কিছু না মিললে store default। Omitted/null-ও store default; [] অবৈধ। Method চালু করে না বা store setting বদলায় না। নিচের selection schema দেখো।

chain_slugstringবাধ্যতামূলক
Project → Stores → Payment methods থেকে chain_slug কপি করো, বা GET /v1/projects/{project_id}/stores/{store_id}/payment-assets থেকে পড়ো, যেমন ethereum, base বা bitcoin। একই chain/rail pair একবারই হতে পারে।বিস্তারিত

Project → Stores → Payment methods থেকে chain_slug কপি করো, বা GET /v1/projects/{project_id}/stores/{store_id}/payment-assets থেকে পড়ো, যেমন ethereum, base বা bitcoin। একই chain/rail pair একবারই হতে পারে।

asset_ids[]UUID[] | nullঐচ্ছিক
On-chain asset.id UUID, contract address বা invoice payment-method ID নয়। এটি অথবা asset_tickers ব্যবহার করো। এই chain-এর সব active accepted asset-এর জন্য দুই selector-ই বাদ দাও। [] আর duplicate/nil ID অবৈধ। 5.4.0+-এ এই store/chain-এ active/accepted নয় এমন ID উপেক্ষা; পুরো selection না মিললে store default।বিস্তারিত

On-chain asset.id UUID, contract address বা invoice payment-method ID নয়। এটি অথবা asset_tickers ব্যবহার করো। এই chain-এর সব active accepted asset-এর জন্য দুই selector-ই বাদ দাও। [] আর duplicate/nil ID অবৈধ। 5.4.0+-এ এই store/chain-এ active/accepted নয় এমন ID উপেক্ষা; পুরো selection না মিললে store default।

asset_tickers[]string[] | nullঐচ্ছিক
Merchant 5.3.0+। BTC, USDC বা PEPE-এর মতো symbol, chain_slug আর এই store-এর scope-এ। 1–64 unique ticker; trim/case-insensitive, 1–40 ASCII letter/digit/dot/underscore/hyphen। এটি অথবা asset_ids ব্যবহার করো। 5.4.0+-এ unknown/inactive/unaccepted ticker উপেক্ষা। Ambiguous accepted symbol এখনো ব্যর্থ: asset_ids ব্যবহার করো। Active selected method-এ valid wallet আর pricing লাগে; 6.0.6 থেকে temporary on-chain scanner outage creation আটকায় না। Lightning চাইলে শুধু BTC নেয়।বিস্তারিত

Merchant 5.3.0+। BTC, USDC বা PEPE-এর মতো symbol, chain_slug আর এই store-এর scope-এ। 1–64 unique ticker; trim/case-insensitive, 1–40 ASCII letter/digit/dot/underscore/hyphen। এটি অথবা asset_ids ব্যবহার করো। 5.4.0+-এ unknown/inactive/unaccepted ticker উপেক্ষা। Ambiguous accepted symbol এখনো ব্যর্থ: asset_ids ব্যবহার করো। Active selected method-এ valid wallet আর pricing লাগে; 6.0.6 থেকে temporary on-chain scanner outage creation আটকায় না। Lightning চাইলে শুধু BTC নেয়।

payment_railonchain | lightningঐচ্ছিক
ডিফল্ট onchain। Bitcoin Lightning বাছতে asset_ids ছাড়া {chain_slug: bitcoin, payment_rail: lightning} ব্যবহার করো; asset_tickers চাইলে [BTC] হতে পারে। Bitcoin on-chain-এ Lightning আসে না। Store-এর Lightning connection আগে enabled আর ready হতে হবে।বিস্তারিত

ডিফল্ট onchain। Bitcoin Lightning বাছতে asset_ids ছাড়া {chain_slug: bitcoin, payment_rail: lightning} ব্যবহার করো; asset_tickers চাইলে [BTC] হতে পারে। Bitcoin on-chain-এ Lightning আসে না। Store-এর Lightning connection আগে enabled আর ready হতে হবে।

order_idstring | nullঐচ্ছিক

Merchant order reference, trim-এর পরে 1–128 অক্ষর; control character প্রত্যাখ্যাত।

emailstring | nullঐচ্ছিক

শুধু merchant-এর customer email, ব্যবহারযোগ্য ASCII address-এ normalize করা, সর্বোচ্চ ২৫৪ অক্ষর। না দিলে বা null হলে email থাকে না।

descriptionstring | nullঐচ্ছিক

Customer-facing description, 1–500 অক্ষর; line break আর tab চলে।

expires_in_secondsinteger | nullঐচ্ছিক

Invoice quote-এর মেয়াদ 300 থেকে 86,400 second; না দিলে বা null হলে store policy।

exchange_rate_spread_percentdecimal string | nullঐচ্ছিক
Quote markup 0 থেকে 100, সর্বোচ্চ দুই decimal। না দিলে বা null হলে store default; "0" এই invoice-এ বন্ধ করে। Upward rounding-এর আগে প্রয়োগ করে lock হয়। Invoice fiat amount বা processing-fee basis বদলায় না।বিস্তারিত

Quote markup 0 থেকে 100, সর্বোচ্চ দুই decimal। না দিলে বা null হলে store default; "0" এই invoice-এ বন্ধ করে। Upward rounding-এর আগে প্রয়োগ করে lock হয়। Invoice fiat amount বা processing-fee basis বদলায় না।

underpayment_tolerance_percentdecimal string | nullঐচ্ছিক

গ্রহণযোগ্য shortfall 0 থেকে 99.99, সর্বোচ্চ দুই decimal। না দিলে বা null হলে store default।

ipn_urlstring | nullঐচ্ছিক

Public HTTPS callback, সর্বোচ্চ 2,048 byte, credential বা fragment ছাড়া। Store default override করে; null/omitted হলে সেখান থেকে নেয়।

redirect_urlstring | nullঐচ্ছিক

Settlement-এর পরে HTTPS success URL, সর্বোচ্চ 2,048 byte, embedded credential ছাড়া। না দিলে বা null হলে store default, তা মুছতে পারে না।

cancel_urlstring | nullঐচ্ছিক

সফল payment ছাড়া checkout শেষ হলে HTTPS return URL। না দিলে বা null হলে store default, তা মুছতে পারে না।

redirect_automaticallyboolean | nullঐচ্ছিক

না দিলে বা null হলে store policy। true-তে কার্যকর redirect_url লাগে।

languagestring | nullঐচ্ছিক
Customer language: en, de, es, pt-BR, it, ru, zh-CN, fr, ko বা ja। pt মানে Brazilian Portuguese আর zh মানে Simplified Chinese। de-DE-এর মতো supported regional tag তালিকার ভাষায় normalize হয়। না দিলে বা null হলে store language। Console language আলাদা।বিস্তারিত

Customer language: en, de, es, pt-BR, it, ru, zh-CN, fr, ko বা ja। pt মানে Brazilian Portuguese আর zh মানে Simplified Chinese। de-DE-এর মতো supported regional tag তালিকার ভাষায় normalize হয়। না দিলে বা null হলে store language। Console language আলাদা।

checkout_appearanceobject | nullঐচ্ছিক
এই invoice-এর আংশিক presentation settings। Omitted/null বর্তমান store design অনুসরণ করে। {}-সহ কোনো object creation-এর সময় resolved design আর image স্থির করে। নিচের override schema দেখো; financial setting, HTML, CSS, JavaScript বা remote image URL নয়।বিস্তারিত

এই invoice-এর আংশিক presentation settings। Omitted/null বর্তমান store design অনুসরণ করে। {}-সহ কোনো object creation-এর সময় resolved design আর image স্থির করে। নিচের override schema দেখো; financial setting, HTML, CSS, JavaScript বা remote image URL নয়।

inherit_default_storebooleanঐচ্ছিক
true হলে project-এর default-store design মূল হিসেবে নেয়; নইলে target store-এর effective design। তারপর override প্রয়োগ করে আলাদাভাবে সেভ হয়; resolved invoice flag false।বিস্তারিত

true হলে project-এর default-store design মূল হিসেবে নেয়; নইলে target store-এর effective design। তারপর override প্রয়োগ করে আলাদাভাবে সেভ হয়; resolved invoice flag false।

titlestringঐচ্ছিক

Checkout heading, সর্বোচ্চ ১২০ অক্ষর। খালি হলে standard heading।

introstringঐচ্ছিক
প্রতিটি সর্বোচ্চ ২,০০০ অক্ষরের plain text। Intro ওপরে, Outro নিচে সব state-এ থাকে। Newline রাখা হয়; নিরাপদ text URL link হয়। Empty string মুছে দেয়। পুরোনো customer_message intro-এর alias হিসেবে চলে; দুটো একসঙ্গে পাঠিয়ো না।বিস্তারিত

প্রতিটি সর্বোচ্চ ২,০০০ অক্ষরের plain text। Intro ওপরে, Outro নিচে সব state-এ থাকে। Newline রাখা হয়; নিরাপদ text URL link হয়। Empty string মুছে দেয়। পুরোনো customer_message intro-এর alias হিসেবে চলে; দুটো একসঙ্গে পাঠিয়ো না।

outrostringঐচ্ছিক
প্রতিটি সর্বোচ্চ ২,০০০ অক্ষরের plain text। Intro ওপরে, Outro নিচে সব state-এ থাকে। Newline রাখা হয়; নিরাপদ text URL link হয়। Empty string মুছে দেয়। পুরোনো customer_message intro-এর alias হিসেবে চলে; দুটো একসঙ্গে পাঠিয়ো না।বিস্তারিত

প্রতিটি সর্বোচ্চ ২,০০০ অক্ষরের plain text। Intro ওপরে, Outro নিচে সব state-এ থাকে। Newline রাখা হয়; নিরাপদ text URL link হয়। Empty string মুছে দেয়। পুরোনো customer_message intro-এর alias হিসেবে চলে; দুটো একসঙ্গে পাঠিয়ো না।

intro_font_sizeintegerঐচ্ছিক

Pixel: 12, 14, 16, 18, 20 বা 24। আলাদাভাবে inherit না করলে default 16।

outro_font_sizeintegerঐচ্ছিক

Pixel: 12, 14, 16, 18, 20 বা 24। আলাদাভাবে inherit না করলে default 16।

themesystem | light | dim | darkঐচ্ছিক

Customer device অনুসরণ করো অথবা fixed theme নাও।

accent_colorstringঐচ্ছিক

#RRGGBB। Automatic color-এর জন্য background, card আর button খালি থাকতে পারে। Text contrast স্বয়ংক্রিয়।

background_colorstringঐচ্ছিক

#RRGGBB। Automatic color-এর জন্য background, card আর button খালি থাকতে পারে। Text contrast স্বয়ংক্রিয়।

card_colorstringঐচ্ছিক

#RRGGBB। Automatic color-এর জন্য background, card আর button খালি থাকতে পারে। Text contrast স্বয়ংক্রিয়।

button_colorstringঐচ্ছিক

#RRGGBB। Automatic color-এর জন্য background, card আর button খালি থাকতে পারে। Text contrast স্বয়ংক্রিয়।

logo_sizestringঐচ্ছিক

small, medium বা large; left বা center।

logo_alignmentstringঐচ্ছিক

small, medium বা large; left বা center।

imagesobjectঐচ্ছিক
Key logo_light, logo_dark, favicon। Key বাদ দিলে base image থাকে; null সরায়। {store_id: UUID, kind?: logo_light|logo_dark|favicon} object একই project-এর সেই store-এর effective uploaded image ব্যবহার করে। kind ডিফল্ট target key। আগে Store → Checkout-এ upload করো; Basic → API IDs থেকে Store API ID কপি করো। Image না থাকলে বা অন্য project-এর ID হলে 400। External URL বা image data নেওয়া হয় না।বিস্তারিত

Key logo_light, logo_dark, favicon। Key বাদ দিলে base image থাকে; null সরায়। {store_id: UUID, kind?: logo_light|logo_dark|favicon} object একই project-এর সেই store-এর effective uploaded image ব্যবহার করে। kind ডিফল্ট target key। আগে Store → Checkout-এ upload করো; Basic → API IDs থেকে Store API ID কপি করো। Image না থাকলে বা অন্য project-এর ID হলে 400। External URL বা image data নেওয়া হয় না।

logo_lightobject | nullঐচ্ছিক
store_idUUIDবাধ্যতামূলক
kindlogo_light | logo_dark | faviconঐচ্ছিক
logo_darkobject | nullঐচ্ছিক
store_idUUIDবাধ্যতামূলক
kindlogo_light | logo_dark | faviconঐচ্ছিক
faviconobject | nullঐচ্ছিক
store_idUUIDবাধ্যতামূলক
kindlogo_light | logo_dark | faviconঐচ্ছিক
show_order_idbooleanঐচ্ছিক

Order ID detail আর title-এর নিচে plain-text description দেখাও। details_expanded শুরুতেই order ID detail খোলে। শুধু display, data redaction নয়।

show_descriptionbooleanঐচ্ছিক

Order ID detail আর title-এর নিচে plain-text description দেখাও। details_expanded শুরুতেই order ID detail খোলে। শুধু display, data redaction নয়।

details_expandedbooleanঐচ্ছিক

Order ID detail আর title-এর নিচে plain-text description দেখাও। details_expanded শুরুতেই order ID detail খোলে। শুধু display, data redaction নয়।

show_project_namebooleanঐচ্ছিক
Merchant 5.6.0+: customer checkout header-এ প্রতিটি নাম দেখাও বা লুকাও। দুটোই default true। Store → Checkout-এও আছে; অন্য appearance setting-এর মতো inherit আর invoice snapshot হয়। শুধু display, data redaction নয়।বিস্তারিত

Merchant 5.6.0+: customer checkout header-এ প্রতিটি নাম দেখাও বা লুকাও। দুটোই default true। Store → Checkout-এও আছে; অন্য appearance setting-এর মতো inherit আর invoice snapshot হয়। শুধু display, data redaction নয়।

show_store_namebooleanঐচ্ছিক
Merchant 5.6.0+: customer checkout header-এ প্রতিটি নাম দেখাও বা লুকাও। দুটোই default true। Store → Checkout-এও আছে; অন্য appearance setting-এর মতো inherit আর invoice snapshot হয়। শুধু display, data redaction নয়।বিস্তারিত

Merchant 5.6.0+: customer checkout header-এ প্রতিটি নাম দেখাও বা লুকাও। দুটোই default true। Store → Checkout-এও আছে; অন্য appearance setting-এর মতো inherit আর invoice snapshot হয়। শুধু display, data redaction নয়।

featured_chains[]string[]ঐচ্ছিক
ক্রমে রাখা chain slug, সর্বোচ্চ ৬০ unique value (lowercase letter, digit, hyphen; সর্বোচ্চ ৬৪ অক্ষর)। [] খালি করে। শুধু available invoice method-এর ক্রম বদলায়।বিস্তারিত

ক্রমে রাখা chain slug, সর্বোচ্চ ৬০ unique value (lowercase letter, digit, hyphen; সর্বোচ্চ ৬৪ অক্ষর)। [] খালি করে। শুধু available invoice method-এর ক্রম বদলায়।

featured_asset_ids[]UUID[]ঐচ্ছিক
সর্বোচ্চ ১০০ unique ordered asset ID; [] খালি করে। Default asset null হতে পারে। ID আসে payment-assets থেকে, payment-intent ID নয়। Method চালু করে না; received payment আর বৈধ customer preference আগে গুরুত্ব পায়।বিস্তারিত

সর্বোচ্চ ১০০ unique ordered asset ID; [] খালি করে। Default asset null হতে পারে। ID আসে payment-assets থেকে, payment-intent ID নয়। Method চালু করে না; received payment আর বৈধ customer preference আগে গুরুত্ব পায়।

default_asset_idUUID|nullঐচ্ছিক
সর্বোচ্চ ১০০ unique ordered asset ID; [] খালি করে। Default asset null হতে পারে। ID আসে payment-assets থেকে, payment-intent ID নয়। Method চালু করে না; received payment আর বৈধ customer preference আগে গুরুত্ব পায়।বিস্তারিত

সর্বোচ্চ ১০০ unique ordered asset ID; [] খালি করে। Default asset null হতে পারে। ID আসে payment-assets থেকে, payment-intent ID নয়। Method চালু করে না; received payment আর বৈধ customer preference আগে গুরুত্ব পায়।

messagesobjectঐচ্ছিক
en, de, es, pt-BR, it, ru, zh-CN, fr, ko বা ja key-এর language object, waiting, confirming, paid, underpaid, expired plain string-সহ (প্রতিটি ৫০০ অক্ষর)। শুধু দেওয়া language/state বদলায়; {} সব message মুছে, {en:{}} English মুছে, আর empty state string সেই state মুছে। English fallback। প্রকৃত status বদলায় না।বিস্তারিত

en, de, es, pt-BR, it, ru, zh-CN, fr, ko বা ja key-এর language object, waiting, confirming, paid, underpaid, expired plain string-সহ (প্রতিটি ৫০০ অক্ষর)। শুধু দেওয়া language/state বদলায়; {} সব message মুছে, {en:{}} English মুছে, আর empty state string সেই state মুছে। English fallback। প্রকৃত status বদলায় না।

enobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
deobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
esobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
pt-BRobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
itobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
ruobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
zh-CNobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
frobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
koobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
jaobjectঐচ্ছিক
waitingstringঐচ্ছিক
confirmingstringঐচ্ছিক
paidstringঐচ্ছিক
underpaidstringঐচ্ছিক
expiredstringঐচ্ছিক
support_emailstringঐচ্ছিক

ASCII email, সর্বোচ্চ ২৫৪ অক্ষর। খালি হলে মুছে।

support_urlstringঐচ্ছিক

Credential ছাড়া HTTPS URL, সর্বোচ্চ 2,048 অক্ষর। খালি হলে মুছে। Link নতুন window-তে খোলে।

terms_urlstringঐচ্ছিক

Credential ছাড়া HTTPS URL, সর্বোচ্চ 2,048 অক্ষর। খালি হলে মুছে। Link নতুন window-তে খোলে।

privacy_urlstringঐচ্ছিক

Credential ছাড়া HTTPS URL, সর্বোচ্চ 2,048 অক্ষর। খালি হলে মুছে। Link নতুন window-তে খোলে।

return_button_textstringঐচ্ছিক

Label সর্বোচ্চ ৬০ অক্ষর। Invoice behavior-এর জন্য top-level redirect_url/cancel_url/redirect_automatically/language ব্যবহার করো।

show_return_buttonbooleanঐচ্ছিক
Terminal state-সহ checkout-এ manual Return to merchant/cancel button দেখাও। বাদ দিলে store appearance নেয় (default true); false লুকায়। Invoice বাতিল করে না, JSON-এর URL লুকায় না বা automatic success redirect বন্ধ করে না। দরকার হলে top-level redirect_automatically আলাদাভাবে false করো। Merchant 8.1.4 বা নতুন লাগে।বিস্তারিত

Terminal state-সহ checkout-এ manual Return to merchant/cancel button দেখাও। বাদ দিলে store appearance নেয় (default true); false লুকায়। Invoice বাতিল করে না, JSON-এর URL লুকায় না বা automatic success redirect বন্ধ করে না। দরকার হলে top-level redirect_automatically আলাদাভাবে false করো। Merchant 8.1.4 বা নতুন লাগে।

metadataobject | nullঐচ্ছিক
Merchant-only JSON object; omitted বা null হলে {}, সর্বোচ্চ 4,096 encoded byte আর পাঁচ nested level। firstname, lastname, street, street2, zip, city, country, countryiso2, company আর vatid যাচাই, normalize করে customer summary field-এ দেওয়া হয়।বিস্তারিত

Merchant-only JSON object; omitted বা null হলে {}, সর্বোচ্চ 4,096 encoded byte আর পাঁচ nested level। firstname, lastname, street, street2, zip, city, country, countryiso2, company আর vatid যাচাই, normalize করে customer summary field-এ দেওয়া হয়।

firstnamestringঐচ্ছিক
lastnamestringঐচ্ছিক
streetstringঐচ্ছিক
street2stringঐচ্ছিক
zipstringঐচ্ছিক
citystringঐচ্ছিক
countrystringঐচ্ছিক
countryiso2stringঐচ্ছিক
companystringঐচ্ছিক
vatidstringঐচ্ছিক
cart_idstring

উত্তর 201 new invoice; 200 exact idempotent replay

উদাহরণ response
{
  "data": {
    "id": "2f798f9f-01f2-42f0-9d10-5581d6116b4c",
    "invoice_id": "0a6a98db-d93d-48ee-8c3c-fd45f90c4a50",
    "project_id": "11111111-1111-4111-8111-111111111111",
    "store_id": "22222222-2222-4222-8222-222222222222",
    "source": "api",
    "order_id": "order-1042",
    "email": "ada@example.com",
    "customer_name": "Ada Lovelace · Example GmbH",
    "customer_address": "Example GmbH · 12 Example Street · Suite 2 · 10115 Berlin · Germany (DE) · VAT DE123456789",
    "description": "Annual plan",
    "amount": "49.9",
    "currency": "USD",
    "exchange_rate_spread_percent": "0.5",
    "underpayment_tolerance_percent": "1",
    "status": "new",
    "amount_status": "none",
    "timing_status": "on_time",
    "resolution": "automatic",
    "sequence": 1,
    "winning_payment_intent_id": null,
    "expires_at": "2026-08-31T18:15:00Z",
    "monitoring_expires_at": "2026-09-07T18:15:00Z",
    "settled_at": null,
    "cancelled_at": null,
    "archived_at": null,
    "created_at": "2026-08-31T18:00:00Z",
    "updated_at": "2026-08-31T18:00:00Z",
    "ipn_url": "https://merchant.example/wholly/ipn",
    "redirect_url": "https://merchant.example/orders/1042",
    "cancel_url": "https://merchant.example/cart",
    "redirect_automatically": true,
    "checkout_language": "en",
    "metadata": { "cart_id": "cart-681", "firstname": "Ada", "lastname": "Lovelace", "street": "12 Example Street", "street2": "Suite 2", "zip": "10115", "city": "Berlin", "country": "Germany", "countryiso2": "DE", "company": "Example GmbH", "vatid": "DE123456789" },
    "payment_intents": [
      {
        "id": "33333333-3333-4333-8333-333333333333",
        "asset_id": "10000000-0000-4000-8000-000000000001",
        "asset_key": "bip122:000000000019d6689c085ae165831e93/slip44:0",
        "chain_slug": "bitcoin",
        "network": "mainnet",
        "caip_network_id": "bip122:000000000019d6689c085ae165831e93",
        "caip_asset_id": "bip122:000000000019d6689c085ae165831e93/slip44:0",
        "symbol": "BTC",
        "asset_decimals": 8,
        "status": "pending",
        "finality_mode": "confirmations",
        "required_confirmations": 1,
        "quote_rate": "0.000009218",
        "quote_details": null,
        "expected_amount": "0.00046",
        "expected_amount_atomic": "46000",
        "minimum_payment_amount": "0.0004554",
        "minimum_payment_amount_atomic": "45540",
        "received_amount": "0",
        "received_amount_atomic": "0",
        "confirmed_amount": "0",
        "confirmed_amount_atomic": "0",
        "destination_address": "bc1q…example",
        "destination_tag": null,
        "derivation_index": 42,
        "quote_expires_at": "2026-08-31T18:15:00Z",
        "monitoring_expires_at": "2026-09-07T18:15:00Z",
        "next_check_at": "2026-08-31T18:00:00Z",
        "last_checked_at": null,
        "last_chain_height": null,
        "last_anchor_hash": null,
        "last_monitor_error": null,
        "first_payment_at": null,
        "fully_paid_at": null,
        "finalized_at": null
      }
    ]
  },
  "links": {
    "checkout": "https://pay.example.com/invoice/0a6a98db-d93d-48ee-8c3c-fd45f90c4a50"
  }
}

Response field

dataobject
idUUIDসব সময়

Internal invoice UUID। Merchant detail বা checkout path-এ ব্যবহার কোরো না।

invoice_idUUIDসব সময়

Merchant detail আর checkout path-এ ব্যবহৃত public invoice UUID।

project_idUUIDসব সময়

মালিকানাধীন project।

store_idUUIDসব সময়

মালিকানাধীন store।

sourcemanual | apiসব সময়

ইনভয়েস কীভাবে তৈরি হয়েছিল।

order_idstring | nullসব সময়

Merchant order reference।

emailstring | nullসব সময়

শুধু merchant-এর customer email। Public checkout-এ ফেরত আসে না।

customer_namestring | nullসব সময়

Private firstname, lastname আর company metadata থেকে তৈরি display name।

customer_addressstring | nullসব সময়

Private company, street, street2, zip, city, country, countryiso2 আর vatid metadata থেকে তৈরি এক লাইনের merchant address।

descriptionstring | nullসব সময়

Customer-facing description।

amountdecimal stringসব সময়

Canonical invoice amount।

currencystringসব সময়

Normalized invoice currency/asset code।

exchange_rate_spread_percentdecimal stringসব সময়

Locked quote spread: creation override, না দিলে store default। Upward rounding-এর আগে লাগে; এই invoice-এ আর বদলায় না।

underpayment_tolerance_percentdecimal stringসব সময়

Invoice তৈরির সময় snapshot হওয়া অপরিবর্তনীয় accepted shortfall percentage।

statusinvoice statusসব সময়

new, processing, settled, expired, invalid বা cancelled।

amount_statusamount statusসব সময়

none, partial, paid বা overpaid। স্পষ্টভাবে অনুমোদিত zero-amount invoice none আর payment method ছাড়াই settled হয়।

timing_statustiming statusসব সময়

on_time বা late।

resolutionresolutionসব সময়

automatic, manually_settled বা manually_invalidated।

sequenceintegerসব সময়

ক্রমশ বাড়তে থাকা invoice state sequence, ১ থেকে শুরু।

winning_payment_intent_idUUID | nullসব সময়

বাছাই হলে যে payment method invoice resolve করেছে।

expires_atRFC 3339 timestampসব সময়

Quote/payment deadline।

monitoring_expires_atRFC 3339 timestampসব সময়

সব method-এর মধ্যে সর্বশেষ configured late-monitoring cutoff।

settled_attimestamp | nullসব সময়

Settled হলে settlement time।

cancelled_attimestamp | nullসব সময়

Cancelled হলে cancellation time।

archived_attimestamp | nullসব সময়

Archived হলে archival time।

created_atRFC 3339 timestampসব সময়

তৈরির সময়।

updated_atRFC 3339 timestampসব সময়

শেষ state update-এর সময়।

ipn_urlstring | nullসব সময়

কার্যকর per-invoice IPN target। শুধু merchant response; public checkout-এ নেই।

redirect_urlstring | nullসব সময়

Settlement-এর পরে ব্যবহৃত কার্যকর success URL।

cancel_urlstring | nullসব সময়

সফল payment ছাড়া checkout শেষ হলে কার্যকর return URL।

redirect_automaticallybooleanসব সময়

সফলতার পরে checkout নিজে থেকে redirect করবে কি না।

checkout_languagestringসব সময়

কার্যকর checkout language tag।

metadataobjectসব সময়
Merchant metadata। Public checkout-এ ফেরত আসে না। Console payment tool payment_tool provenance যোগ করে (id, kind, title, pricing, requested_amount, request_id); পেমেন্টের প্রমাণ নয়। Callback authenticate করে প্রতি invoice_id-তে invoice.settled একবারই fulfil করো।বিস্তারিত

Merchant metadata। Public checkout-এ ফেরত আসে না। Console payment tool payment_tool provenance যোগ করে (id, kind, title, pricing, requested_amount, request_id); পেমেন্টের প্রমাণ নয়। Callback authenticate করে প্রতি invoice_id-তে invoice.settled একবারই fulfil করো।

cart_idstring
firstnamestring
lastnamestring
streetstring
street2string
zipstring
citystring
countrystring
countryiso2string
companystring
vatidstring
payment_intents[]object[]সব সময়

Quoted payment method আর monitoring state।

idUUIDসব সময়

Payment intent identifier; checkout QR intent_id হিসেবেও ব্যবহৃত।

payment_railonchain | lightningসব সময়
Invoice transport। Bitcoin on-chain আর Lightning একই asset_id ভাগ করতে পারে; শুধু symbol নয়, intent id আর এই field ব্যবহার করো। Asset catalog-এর scanner payment_rail থেকে এটি আলাদা।বিস্তারিত

Invoice transport। Bitcoin on-chain আর Lightning একই asset_id ভাগ করতে পারে; শুধু symbol নয়, intent id আর এই field ব্যবহার করো। Asset catalog-এর scanner payment_rail থেকে এটি আলাদা।

bolt11string | nullসব সময়

Lightning payment request, নইলে null। Lightning wallet দিয়ে request-এ pay করো, payment hash-এ on-chain fund পাঠিয়ো না।

asset_idUUIDসব সময়

Configured payment asset identifier।

asset_keystringসব সময়

Canonical CAIP-style asset key।

chain_slugstringসব সময়

Wholly Crypto chain identifier।

networkstringসব সময়

Configured network, supported payment asset-এর জন্য বর্তমানে mainnet।

caip_network_idstringসব সময়

Canonical CAIP-2 network identifier।

caip_asset_idstring | nullসব সময়

নিবন্ধিত হলে canonical CAIP-19 identifier।

symbolstringসব সময়

Asset symbol।

asset_decimalsintegerসব সময়

Atomic-unit precision। Lightning BTC-তে 11 (millisatoshi), on-chain Bitcoin-এর 8 নয়। Quote পূর্ণ satoshi; receipt-এ millisatoshi precision থাকে।

statusintent statusসব সময়

pending, partial, paid, overpaid, expired বা invalid।

finality_modeconfirmations | finalizedসব সময়

Finality policy।

required_confirmationsintegerসব সময়

প্রযোজ্য হলে প্রয়োজনীয় confirmation।

quote_ratedecimal stringসব সময়

Locked spread-সহ প্রতি এক invoice currency unit-এ asset unit। যেমন প্রতি USD-এ 1.02 USDC। উল্টো rate নয়।

quote_detailsobject | nullসব সময়
Locked quote provenance: spread-এর আগে reference_rate, unrounded_payment_amount, rounding_adjustment, pricing_provider, asset_provider, pricing_fetched_at আর asset_fetched_at। পুরোনো invoice-এ null; পুরোনো মান বানানো হয় না।বিস্তারিত

Locked quote provenance: spread-এর আগে reference_rate, unrounded_payment_amount, rounding_adjustment, pricing_provider, asset_provider, pricing_fetched_at আর asset_fetched_at। পুরোনো invoice-এ null; পুরোনো মান বানানো হয় না।

expected_amountdecimal stringসব সময়
Spread আর upward rounding-এর পরে পরিশোধের সঠিক locked asset amount। 4.1.1 থেকে চেনা verified fiat stablecoin (যেমন USDC, USDT, DAI, USDS, EURC) সর্বোচ্চ দুই decimal-এ ওপরের দিকে round হয়; 1.321 হয় 1.33, কখনো 1.32 নয়। Zero tolerance-এও এটাই expected amount। অন্য asset adaptive precision রাখে। আগের invoice-এর দাম বদলায় না।বিস্তারিত

Spread আর upward rounding-এর পরে পরিশোধের সঠিক locked asset amount। 4.1.1 থেকে চেনা verified fiat stablecoin (যেমন USDC, USDT, DAI, USDS, EURC) সর্বোচ্চ দুই decimal-এ ওপরের দিকে round হয়; 1.321 হয় 1.33, কখনো 1.32 নয়। Zero tolerance-এও এটাই expected amount। অন্য asset adaptive precision রাখে। আগের invoice-এর দাম বদলায় না।

expected_amount_atomicinteger stringসব সময়

Asset-এর সবচেয়ে ছোট এককে সঠিক amount।

minimum_payment_amountdecimal stringসব সময়

Invoice tolerance প্রয়োগের পরে paid হিসেবে গৃহীত সবচেয়ে ছোট amount।

minimum_payment_amount_atomicinteger stringসব সময়

Asset-এর সবচেয়ে ছোট এককে সঠিক accepted threshold।

received_amountdecimal stringসব সময়

দেখা amount।

received_amount_atomicinteger stringসব সময়

দেখা atomic amount।

confirmed_amountdecimal stringসব সময়

Confirmed/final amount।

confirmed_amount_atomicinteger stringসব সময়

Confirmed/final atomic amount।

destination_addressstringসব সময়

On-chain receiving address, অথবা Lightning-এর ৬৪ অক্ষরের payment hash। Lightning-এ pay করতে bolt11 নাও; hash Bitcoin address নয়।

destination_tagstring | nullসব সময়

প্রযোজ্য পথে দরকারি public payment reference: XRP destination tag, Stellar memo ID বা TON invoice comment। Unique-address পথে null।

derivation_indexintegerসব সময়

Reserved wallet child index; শুধু merchant detail।

quote_expires_atRFC 3339 timestampসব সময়

Quote expiry।

monitoring_expires_atRFC 3339 timestampসব সময়

এই method-এর late-monitoring cutoff।

next_check_attimestamp | nullসব সময়

পরের নির্ধারিত chain check।

last_checked_attimestamp | nullসব সময়

শেষ chain check।

last_chain_heightinteger | nullসব সময়

Monitor-এর দেখা সর্বশেষ বিশ্বস্ত height।

last_anchor_hashstring | nullসব সময়

শেষ monitor anchor/block hash।

last_monitor_errorstring | nullসব সময়

Operator-এর জন্য নিরাপদ monitoring diagnostic।

first_payment_attimestamp | nullসব সময়

প্রথম পেমেন্ট দেখার সময়।

fully_paid_attimestamp | nullসব সময়

গ্রহণযোগ্য minimum amount প্রথম পৌঁছানোর সময়।

finalized_attimestamp | nullসব সময়

পেমেন্ট finality policy পূরণের সময়।

ব্যবহারের নোট
  • payment_methods শুধু এই invoice-এর store-enabled method filter করে। Omitted/null সব store method রাখে; [] অবৈধ। Project → Stores → Payment methods-এ ছোট chain_slug hint আর দেখানো asset ticker পাবে। API payment-assets list chain_slug, asset.symbol আর asset.id দেয়। Accepted Ethereum token-এর জন্য {chain_slug: ethereum, asset_tickers: [USDC, USDT]} নাও; BTC আর PEPE-ও তাদের chain-এ একইভাবে চলে। Ticker case-insensitive, chain-scoped এবং শুধু store-এর মধ্যে resolve হয়। একই ticker-এর দুই accepted contract থাকলে একটি not ready হলেও বেছে না নিয়ে 400 দেয়; তখন asset_ids নাও। Native asset, catalog আর custom token একই নিয়ম মেনে চলে। প্রতিটি chain/rail একবার; সর্বোচ্চ ৬৪ final method। Merchant 5.4.0+: unknown, disabled, wrong-chain বা unaccepted পছন্দ উপেক্ষা। পুরো selection-এ active accepted match না থাকলে store default; নইলে শুধু matching choice। Chain-only entry সব active accepted on-chain asset নেয়। Active selected method-এ valid wallet, installed scanner adapter আর trustworthy rate লাগে। 6.0.6 থেকে unavailable scanner, cooldown আর pending/stale health check invoice creation আটকায় না বা configured on-chain method সরায় না। Detection নিজে থেকে retry করে; settlement-এ provider quorum আর confirmation লাগে। receive_readiness দেখো এবং provider সচল রাখো: scanner ফিরতে না পারা পর্যন্ত invoice unverified থাকতে পারে। Monero subaddress allocation আর Lightning BOLT11 generation-এ এখনো external wallet/node service লাগে। Failure-এ error.message আর error.details.payment_methods-এ chain_slug, asset_ticker, reason_code এবং scanner diagnostic-এর জন্য required_endpoint_role, healthy_endpoints, required_independent_providers থাকে। TRON indexed history বা supported raw solidified native-block API নেয়; basic health scanner compatibility প্রমাণ করে না। Pricing failure asset/currency চিহ্নিত করে। কিছুই unaccepted asset চালু বা store policy বদলায় না। 5.4.0-এর আগে unknown/inactive explicit choice ব্যর্থ হয়। Store setting বদলালে existing invoice method বাড়ে না। Lightning আলাদা বাছতে হবে। Replay original method রাখে; একই Idempotency-Key-তে selection বদলালে 409।
  • checkout_appearance ওপরে থাকা সব presentation setting সমর্থন করে। Omitted field inherit হয়, array replace করে, nested message field merge হয়; empty message object সেই scope clear করে। Store edit ছাড়া resolved design আর image এই invoice-এর জন্য সেভ হয়। ফল দেখতে public checkout JSON-এর appearance পড়ো। পুরো request 32 KiB আর resolved settings 20 KiB-এ সীমিত।
  • একই Idempotency-Key-তে checkout_appearance বদলালে 409; identical raw byte দিয়ে retry করো। Appearance amount, rate, accepted asset, confirmation requirement, real status বা embedding permission বদলায় না। HTML, CSS, script বা remote image fetching নেই।
  • exchange_rate_spread_percent এই invoice-এ store default override করে: inherit করতে বাদ বা null, বন্ধ করতে "0" পাঠাও। Existing invoice quote কখনো বদলায় না।
  • Upward rounding-এর আগে spread লাগে। Fee মূল invoice fiat amount-এই হয়, spread বাদ দিয়ে।
  • সব সময় ফেরত দেওয়া expected_amount বা expected_amount_atomic পাঠাও। Rounding ওপরের দিকে, asset precision, amount-এর 0.1% আর এক fiat minor unit-এ সীমিত।
  • Retry-তে একই credential, Idempotency-Key আর হুবহু body byte রাখো। একই key-তে spread বদলালে 409 idempotency_conflict।
  • নতুন quote, callback DNS বা address preparation-এর আগে exact replay পরীক্ষা হয়। প্রতি request-এ credential scope আর project/store authorization তবুও পরীক্ষা হয়।
  • কার্যকর ipn_url-এ store IPN signing secret লাগে। Unknown body field প্রত্যাখ্যাত।

ত্রুটি

Error code ও retry-এর নিয়ম

GETইনভয়েসের তালিকা/v1/projects/{project_id}/invoicesশুধু পড়া

Merchant-only email আর চেনা metadata থেকে customer field-সহ scoped invoice summary-এর ছোট newest-first page দেয়। Search, status আর store filter server-side; নির্ভরযোগ্য paging-এর জন্য response-এ total আর has_more।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MERCHANT_API_TOKEN
Acceptপ্রস্তাবিতapplication/json

Path parameter

project_idUUIDবাধ্যতামূলক

Credential-এ দেওয়া enabled project।

Query parameter

store_idUUID

ঐচ্ছিক exact store filter।

statusenum

ঐচ্ছিক new, processing, settled, expired, invalid বা cancelled।

limitinteger

ঐচ্ছিক 1–100; ডিফল্ট ৫০।

offsetinteger

ঐচ্ছিক 0–1,000,000; ডিফল্ট ০।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices?search=order-1042&status=processing&limit=50&offset=0" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Accept: application/json'

উত্তর 200 application/json

উদাহরণ response
{
  "data": [
    {
      "id": "2f798f9f-01f2-42f0-9d10-5581d6116b4c",
      "invoice_id": "0a6a98db-d93d-48ee-8c3c-fd45f90c4a50",
      "project_id": "11111111-1111-4111-8111-111111111111",
      "store_id": "22222222-2222-4222-8222-222222222222",
      "source": "api",
      "order_id": "order-1042",
      "email": "ada@example.com",
      "customer_name": "Ada Lovelace · Example GmbH",
      "customer_address": "Example GmbH · 12 Example Street · Suite 2 · 10115 Berlin · Germany (DE) · VAT DE123456789",
      "description": "Annual plan",
      "amount": "49.9",
      "currency": "USD",
      "exchange_rate_spread_percent": "0.5",
      "underpayment_tolerance_percent": "1",
      "status": "processing",
      "amount_status": "paid",
      "timing_status": "on_time",
      "resolution": "automatic",
      "sequence": 3,
      "winning_payment_intent_id": "33333333-3333-4333-8333-333333333333",
      "expires_at": "2026-08-31T18:15:00Z",
      "monitoring_expires_at": "2026-09-07T18:15:00Z",
      "settled_at": null,
      "cancelled_at": null,
      "archived_at": null,
      "created_at": "2026-08-31T18:00:00Z",
      "updated_at": "2026-08-31T18:04:10Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 143,
    "has_more": true
  }
}

Response field

data[]object[]
idUUIDসব সময়

Internal invoice UUID। Merchant detail বা checkout path-এ ব্যবহার কোরো না।

invoice_idUUIDসব সময়

Merchant detail আর checkout path-এ ব্যবহৃত public invoice UUID।

project_idUUIDসব সময়

মালিকানাধীন project।

store_idUUIDসব সময়

মালিকানাধীন store।

sourcemanual | apiসব সময়

ইনভয়েস কীভাবে তৈরি হয়েছিল।

order_idstring | nullসব সময়

Merchant order reference।

emailstring | nullসব সময়

শুধু merchant-এর customer email। Public checkout-এ ফেরত আসে না।

customer_namestring | nullসব সময়

Private firstname, lastname আর company metadata থেকে তৈরি display name।

customer_addressstring | nullসব সময়

Private company, street, street2, zip, city, country, countryiso2 আর vatid metadata থেকে তৈরি এক লাইনের merchant address।

descriptionstring | nullসব সময়

Customer-facing description।

amountdecimal stringসব সময়

Canonical invoice amount।

currencystringসব সময়

Normalized invoice currency/asset code।

exchange_rate_spread_percentdecimal stringসব সময়

Locked quote spread: creation override, না দিলে store default। Upward rounding-এর আগে লাগে; এই invoice-এ আর বদলায় না।

underpayment_tolerance_percentdecimal stringসব সময়

Invoice তৈরির সময় snapshot হওয়া অপরিবর্তনীয় accepted shortfall percentage।

statusinvoice statusসব সময়

new, processing, settled, expired, invalid বা cancelled।

amount_statusamount statusসব সময়

none, partial, paid বা overpaid। স্পষ্টভাবে অনুমোদিত zero-amount invoice none আর payment method ছাড়াই settled হয়।

timing_statustiming statusসব সময়

on_time বা late।

resolutionresolutionসব সময়

automatic, manually_settled বা manually_invalidated।

sequenceintegerসব সময়

ক্রমশ বাড়তে থাকা invoice state sequence, ১ থেকে শুরু।

winning_payment_intent_idUUID | nullসব সময়

বাছাই হলে যে payment method invoice resolve করেছে।

expires_atRFC 3339 timestampসব সময়

Quote/payment deadline।

monitoring_expires_atRFC 3339 timestampসব সময়

সব method-এর মধ্যে সর্বশেষ configured late-monitoring cutoff।

settled_attimestamp | nullসব সময়

Settled হলে settlement time।

cancelled_attimestamp | nullসব সময়

Cancelled হলে cancellation time।

archived_attimestamp | nullসব সময়

Archived হলে archival time।

created_atRFC 3339 timestampসব সময়

তৈরির সময়।

updated_atRFC 3339 timestampসব সময়

শেষ state update-এর সময়।

paginationobject
limitintegerসব সময়

কার্যকর page size, 1–100।

offsetintegerসব সময়

কার্যকর zero-based row offset, 0–1,000,000।

totalintegerসব সময়

Page snapshot-এ project, store, status আর search filter-এর মেলা মোট row।

has_morebooleanসব সময়

Offset আর returned row count-এর যোগফল total-এর কম হলে true।

ব্যবহারের নোট
  • created_at descending, তারপর internal id descending ক্রম।
  • List item InvoiceSummary object; email, customer_name আর customer_address merchant-only। Raw metadata আর payment intent-এর জন্য detail নাও।
  • শুধু has_more true হলে next page-এ offset = pagination.offset + pagination.limit করো।
  • Count আর page একই repeatable-read database snapshot থেকে আসে; concurrent write পরের request-এ দেখা যায়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETইনভয়েস পড়ো/v1/projects/{project_id}/invoices/{invoice_id}শুধু পড়া

পূর্ণ merchant invoice detail আর current active checkout URL দেয়। Polling আর reconciliation-এ এই route নাও।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MERCHANT_API_TOKEN
Acceptপ্রস্তাবিতapplication/json

Path parameter

project_idUUIDবাধ্যতামূলক

Credential-এ দেওয়া enabled project।

invoice_idUUIDবাধ্যতামূলক

Creation/listing-এর invoice_id, internal id নয়।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices/YOUR_PUBLIC_INVOICE_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Accept: application/json'

উত্তর 200 application/json

উদাহরণ response
{
  "data": {
    "id": "2f798f9f-01f2-42f0-9d10-5581d6116b4c",
    "invoice_id": "0a6a98db-d93d-48ee-8c3c-fd45f90c4a50",
    "project_id": "11111111-1111-4111-8111-111111111111",
    "store_id": "22222222-2222-4222-8222-222222222222",
    "source": "api",
    "order_id": "order-1042",
    "email": "ada@example.com",
    "customer_name": "Ada Lovelace · Example GmbH",
    "customer_address": "Example GmbH · 12 Example Street · Suite 2 · 10115 Berlin · Germany (DE) · VAT DE123456789",
    "description": "Annual plan",
    "amount": "49.9",
    "currency": "USD",
    "exchange_rate_spread_percent": "0.5",
    "underpayment_tolerance_percent": "1",
    "status": "settled",
    "amount_status": "paid",
    "timing_status": "on_time",
    "resolution": "automatic",
    "sequence": 4,
    "winning_payment_intent_id": "33333333-3333-4333-8333-333333333333",
    "expires_at": "2026-08-31T18:15:00Z",
    "monitoring_expires_at": "2026-09-07T18:15:00Z",
    "settled_at": "2026-08-31T18:05:00Z",
    "cancelled_at": null,
    "archived_at": null,
    "created_at": "2026-08-31T18:00:00Z",
    "updated_at": "2026-08-31T18:05:00Z",
    "ipn_url": "https://merchant.example/wholly/ipn",
    "redirect_url": "https://merchant.example/orders/1042",
    "cancel_url": "https://merchant.example/cart",
    "redirect_automatically": true,
    "checkout_language": "en",
    "metadata": { "cart_id": "cart-681", "firstname": "Ada", "lastname": "Lovelace", "street": "12 Example Street", "street2": "Suite 2", "zip": "10115", "city": "Berlin", "country": "Germany", "countryiso2": "DE", "company": "Example GmbH", "vatid": "DE123456789" },
    "payment_intents": [
      {
        "id": "33333333-3333-4333-8333-333333333333",
        "asset_id": "10000000-0000-4000-8000-000000000001",
        "asset_key": "bip122:000000000019d6689c085ae165831e93/slip44:0",
        "chain_slug": "bitcoin",
        "network": "mainnet",
        "caip_network_id": "bip122:000000000019d6689c085ae165831e93",
        "caip_asset_id": "bip122:000000000019d6689c085ae165831e93/slip44:0",
        "symbol": "BTC",
        "asset_decimals": 8,
        "status": "paid",
        "finality_mode": "confirmations",
        "required_confirmations": 1,
        "quote_rate": "0.000009218",
        "quote_details": null,
        "expected_amount": "0.00046",
        "expected_amount_atomic": "46000",
        "minimum_payment_amount": "0.0004554",
        "minimum_payment_amount_atomic": "45540",
        "received_amount": "0.0004554",
        "received_amount_atomic": "45540",
        "confirmed_amount": "0.0004554",
        "confirmed_amount_atomic": "45540",
        "destination_address": "bc1q…example",
        "destination_tag": null,
        "derivation_index": 42,
        "quote_expires_at": "2026-08-31T18:15:00Z",
        "monitoring_expires_at": "2026-09-07T18:15:00Z",
        "next_check_at": null,
        "last_checked_at": "2026-08-31T18:05:00Z",
        "last_chain_height": 912345,
        "last_anchor_hash": "000000000000000000example",
        "last_monitor_error": null,
        "first_payment_at": "2026-08-31T18:03:00Z",
        "fully_paid_at": "2026-08-31T18:03:00Z",
        "finalized_at": "2026-08-31T18:05:00Z"
      }
    ]
  },
  "links": {
    "checkout": "https://pay.example.com/invoice/0a6a98db-d93d-48ee-8c3c-fd45f90c4a50"
  }
}

Response field

dataobject
idUUIDসব সময়

Internal invoice UUID। Merchant detail বা checkout path-এ ব্যবহার কোরো না।

invoice_idUUIDসব সময়

Merchant detail আর checkout path-এ ব্যবহৃত public invoice UUID।

project_idUUIDসব সময়

মালিকানাধীন project।

store_idUUIDসব সময়

মালিকানাধীন store।

sourcemanual | apiসব সময়

ইনভয়েস কীভাবে তৈরি হয়েছিল।

order_idstring | nullসব সময়

Merchant order reference।

emailstring | nullসব সময়

শুধু merchant-এর customer email। Public checkout-এ ফেরত আসে না।

customer_namestring | nullসব সময়

Private firstname, lastname আর company metadata থেকে তৈরি display name।

customer_addressstring | nullসব সময়

Private company, street, street2, zip, city, country, countryiso2 আর vatid metadata থেকে তৈরি এক লাইনের merchant address।

descriptionstring | nullসব সময়

Customer-facing description।

amountdecimal stringসব সময়

Canonical invoice amount।

currencystringসব সময়

Normalized invoice currency/asset code।

exchange_rate_spread_percentdecimal stringসব সময়

Locked quote spread: creation override, না দিলে store default। Upward rounding-এর আগে লাগে; এই invoice-এ আর বদলায় না।

underpayment_tolerance_percentdecimal stringসব সময়

Invoice তৈরির সময় snapshot হওয়া অপরিবর্তনীয় accepted shortfall percentage।

statusinvoice statusসব সময়

new, processing, settled, expired, invalid বা cancelled।

amount_statusamount statusসব সময়

none, partial, paid বা overpaid। স্পষ্টভাবে অনুমোদিত zero-amount invoice none আর payment method ছাড়াই settled হয়।

timing_statustiming statusসব সময়

on_time বা late।

resolutionresolutionসব সময়

automatic, manually_settled বা manually_invalidated।

sequenceintegerসব সময়

ক্রমশ বাড়তে থাকা invoice state sequence, ১ থেকে শুরু।

winning_payment_intent_idUUID | nullসব সময়

বাছাই হলে যে payment method invoice resolve করেছে।

expires_atRFC 3339 timestampসব সময়

Quote/payment deadline।

monitoring_expires_atRFC 3339 timestampসব সময়

সব method-এর মধ্যে সর্বশেষ configured late-monitoring cutoff।

settled_attimestamp | nullসব সময়

Settled হলে settlement time।

cancelled_attimestamp | nullসব সময়

Cancelled হলে cancellation time।

archived_attimestamp | nullসব সময়

Archived হলে archival time।

created_atRFC 3339 timestampসব সময়

তৈরির সময়।

updated_atRFC 3339 timestampসব সময়

শেষ state update-এর সময়।

ipn_urlstring | nullসব সময়

কার্যকর per-invoice IPN target। শুধু merchant response; public checkout-এ নেই।

redirect_urlstring | nullসব সময়

Settlement-এর পরে ব্যবহৃত কার্যকর success URL।

cancel_urlstring | nullসব সময়

সফল payment ছাড়া checkout শেষ হলে কার্যকর return URL।

redirect_automaticallybooleanসব সময়

সফলতার পরে checkout নিজে থেকে redirect করবে কি না।

checkout_languagestringসব সময়

কার্যকর checkout language tag।

metadataobjectসব সময়
Merchant metadata। Public checkout-এ ফেরত আসে না। Console payment tool payment_tool provenance যোগ করে (id, kind, title, pricing, requested_amount, request_id); পেমেন্টের প্রমাণ নয়। Callback authenticate করে প্রতি invoice_id-তে invoice.settled একবারই fulfil করো।বিস্তারিত

Merchant metadata। Public checkout-এ ফেরত আসে না। Console payment tool payment_tool provenance যোগ করে (id, kind, title, pricing, requested_amount, request_id); পেমেন্টের প্রমাণ নয়। Callback authenticate করে প্রতি invoice_id-তে invoice.settled একবারই fulfil করো।

cart_idstring
firstnamestring
lastnamestring
streetstring
street2string
zipstring
citystring
countrystring
countryiso2string
companystring
vatidstring
payment_intents[]object[]সব সময়

Quoted payment method আর monitoring state।

idUUIDসব সময়

Payment intent identifier; checkout QR intent_id হিসেবেও ব্যবহৃত।

payment_railonchain | lightningসব সময়
Invoice transport। Bitcoin on-chain আর Lightning একই asset_id ভাগ করতে পারে; শুধু symbol নয়, intent id আর এই field ব্যবহার করো। Asset catalog-এর scanner payment_rail থেকে এটি আলাদা।বিস্তারিত

Invoice transport। Bitcoin on-chain আর Lightning একই asset_id ভাগ করতে পারে; শুধু symbol নয়, intent id আর এই field ব্যবহার করো। Asset catalog-এর scanner payment_rail থেকে এটি আলাদা।

bolt11string | nullসব সময়

Lightning payment request, নইলে null। Lightning wallet দিয়ে request-এ pay করো, payment hash-এ on-chain fund পাঠিয়ো না।

asset_idUUIDসব সময়

Configured payment asset identifier।

asset_keystringসব সময়

Canonical CAIP-style asset key।

chain_slugstringসব সময়

Wholly Crypto chain identifier।

networkstringসব সময়

Configured network, supported payment asset-এর জন্য বর্তমানে mainnet।

caip_network_idstringসব সময়

Canonical CAIP-2 network identifier।

caip_asset_idstring | nullসব সময়

নিবন্ধিত হলে canonical CAIP-19 identifier।

symbolstringসব সময়

Asset symbol।

asset_decimalsintegerসব সময়

Atomic-unit precision। Lightning BTC-তে 11 (millisatoshi), on-chain Bitcoin-এর 8 নয়। Quote পূর্ণ satoshi; receipt-এ millisatoshi precision থাকে।

statusintent statusসব সময়

pending, partial, paid, overpaid, expired বা invalid।

finality_modeconfirmations | finalizedসব সময়

Finality policy।

required_confirmationsintegerসব সময়

প্রযোজ্য হলে প্রয়োজনীয় confirmation।

quote_ratedecimal stringসব সময়

Locked spread-সহ প্রতি এক invoice currency unit-এ asset unit। যেমন প্রতি USD-এ 1.02 USDC। উল্টো rate নয়।

quote_detailsobject | nullসব সময়
Locked quote provenance: spread-এর আগে reference_rate, unrounded_payment_amount, rounding_adjustment, pricing_provider, asset_provider, pricing_fetched_at আর asset_fetched_at। পুরোনো invoice-এ null; পুরোনো মান বানানো হয় না।বিস্তারিত

Locked quote provenance: spread-এর আগে reference_rate, unrounded_payment_amount, rounding_adjustment, pricing_provider, asset_provider, pricing_fetched_at আর asset_fetched_at। পুরোনো invoice-এ null; পুরোনো মান বানানো হয় না।

expected_amountdecimal stringসব সময়
Spread আর upward rounding-এর পরে পরিশোধের সঠিক locked asset amount। 4.1.1 থেকে চেনা verified fiat stablecoin (যেমন USDC, USDT, DAI, USDS, EURC) সর্বোচ্চ দুই decimal-এ ওপরের দিকে round হয়; 1.321 হয় 1.33, কখনো 1.32 নয়। Zero tolerance-এও এটাই expected amount। অন্য asset adaptive precision রাখে। আগের invoice-এর দাম বদলায় না।বিস্তারিত

Spread আর upward rounding-এর পরে পরিশোধের সঠিক locked asset amount। 4.1.1 থেকে চেনা verified fiat stablecoin (যেমন USDC, USDT, DAI, USDS, EURC) সর্বোচ্চ দুই decimal-এ ওপরের দিকে round হয়; 1.321 হয় 1.33, কখনো 1.32 নয়। Zero tolerance-এও এটাই expected amount। অন্য asset adaptive precision রাখে। আগের invoice-এর দাম বদলায় না।

expected_amount_atomicinteger stringসব সময়

Asset-এর সবচেয়ে ছোট এককে সঠিক amount।

minimum_payment_amountdecimal stringসব সময়

Invoice tolerance প্রয়োগের পরে paid হিসেবে গৃহীত সবচেয়ে ছোট amount।

minimum_payment_amount_atomicinteger stringসব সময়

Asset-এর সবচেয়ে ছোট এককে সঠিক accepted threshold।

received_amountdecimal stringসব সময়

দেখা amount।

received_amount_atomicinteger stringসব সময়

দেখা atomic amount।

confirmed_amountdecimal stringসব সময়

Confirmed/final amount।

confirmed_amount_atomicinteger stringসব সময়

Confirmed/final atomic amount।

destination_addressstringসব সময়

On-chain receiving address, অথবা Lightning-এর ৬৪ অক্ষরের payment hash। Lightning-এ pay করতে bolt11 নাও; hash Bitcoin address নয়।

destination_tagstring | nullসব সময়

প্রযোজ্য পথে দরকারি public payment reference: XRP destination tag, Stellar memo ID বা TON invoice comment। Unique-address পথে null।

derivation_indexintegerসব সময়

Reserved wallet child index; শুধু merchant detail।

quote_expires_atRFC 3339 timestampসব সময়

Quote expiry।

monitoring_expires_atRFC 3339 timestampসব সময়

এই method-এর late-monitoring cutoff।

next_check_attimestamp | nullসব সময়

পরের নির্ধারিত chain check।

last_checked_attimestamp | nullসব সময়

শেষ chain check।

last_chain_heightinteger | nullসব সময়

Monitor-এর দেখা সর্বশেষ বিশ্বস্ত height।

last_anchor_hashstring | nullসব সময়

শেষ monitor anchor/block hash।

last_monitor_errorstring | nullসব সময়

Operator-এর জন্য নিরাপদ monitoring diagnostic।

first_payment_attimestamp | nullসব সময়

প্রথম পেমেন্ট দেখার সময়।

fully_paid_attimestamp | nullসব সময়

গ্রহণযোগ্য minimum amount প্রথম পৌঁছানোর সময়।

finalized_attimestamp | nullসব সময়

পেমেন্ট finality policy পূরণের সময়।

ব্যবহারের নোট
  • Public ID অনুমোদিত project-এ না থাকলে scoped lookup ইচ্ছাকৃতভাবে invoice_not_found দেয়।
  • links.checkout Store → Basic → Store domains অনুসরণ করে: এই store-এর active pay hostname, তারপর default store-এর choice, তারপর system primary। Retired/draft বা wrong-service host উপেক্ষা। Creation আর MCP response-এও লাগে; idempotent replay-সহ response-এর সময় link resolve হয়। Signed callback link event creation-এ স্থির, retry-তে নতুন করে লেখা নয়। Preference শুধু link তৈরি করে; traffic redirect বা IP restriction বদলায় না।

ত্রুটি

Error code ও retry-এর নিয়ম

GETইনভয়েসের পেমেন্ট তালিকা/v1/projects/{project_id}/invoices/{invoice_id}/paymentsশুধু পড়া

Invalidated observation-সহ পূর্ণ current transfer history। Callback payments_truncated জানালে এটি নাও। এটি current state, পুরোনো event পুনর্গঠন নয়।

Authentication ও header
Headerপ্রয়োজনীয়তানিয়ম
Authorizationবাধ্যতামূলকBearer YOUR_MERCHANT_API_TOKEN
Acceptপ্রস্তাবিতapplication/json

Path parameter

project_idUUIDবাধ্যতামূলক

এই credential-এ দেওয়া project।

invoice_idUUIDবাধ্যতামূলক

Creation-এ ফেরত আসা public invoice_id।

Query parameter

payment_method_idUUIDঐচ্ছিক

এক invoice payment method-এ সীমিত করো।

limitinteger

1–100; ডিফল্ট ২৫।

offsetinteger

0–1,000,000; ডিফল্ট ০।

অনুরোধ

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices/YOUR_PUBLIC_INVOICE_ID/payments?limit=25&offset=0" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Accept: application/json'

উত্তর 200 application/json

উদাহরণ response
{
  "invoice_id": "11111111-2222-4333-8444-555555555555",
  "data": [{
    "payment_id": "44444444-4444-4444-8444-444444444444",
    "payment_method_id": "33333333-3333-4333-8333-333333333333",
    "transaction_id": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "payment_hash": null,
    "event_index": 12,
    "payment_rail": "onchain",
    "chain_slug": "ethereum",
    "network": "mainnet",
    "asset_id": "55555555-5555-4555-8555-555555555555",
    "asset_key": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "caip_asset_id": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "symbol": "USDC",
    "asset_decimals": 6,
    "amount": "58.17342",
    "amount_atomic": "58173420",
    "status": "final",
    "counts_towards_received": true,
    "confirmations": 2,
    "block_height": 25975377,
    "observed_at": "2026-09-14T12:03:00Z",
    "chain_time": "2026-09-14T12:02:48Z",
    "finalized_at": "2026-09-14T12:04:00Z",
    "explorer_name": "Etherscan",
    "explorer_url": "https://etherscan.io/tx/0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }],
  "pagination": {"limit": 25, "offset": 0, "total": 1, "has_more": false}
}

Response field

invoice_idstring
data[]object[]
payment_idstring
payment_method_idstring
transaction_idstring
payment_hashJSON | null
event_indexinteger
payment_railstring
chain_slugstring
networkstring
asset_idstring
asset_keystring
caip_asset_idstring
symbolstring
asset_decimalsinteger
amountstring
amount_atomicstring
statusstring
counts_towards_receivedboolean
confirmationsinteger
block_heightinteger
observed_atstring
chain_timestring
finalized_atstring
explorer_namestring
explorer_urlstring
paginationobject
limitinteger
offsetinteger
totalinteger
has_moreboolean
ব্যবহারের নোট
  • Observation token log, UTXO output বা অন্য rail transfer, সব সময় unique transaction hash নয়। payment_id দিয়ে duplicate বাদ দাও; transaction_id আর event_index মিলে chain transfer চিহ্নিত করে।
  • status হলো detected, confirming, final, reorged, replaced বা invalid। শুধু counts_towards_received observation received amount-এ যোগ হয়। ভিন্ন asset-এর পরিমাণ যোগ কোরো না।
  • Lightning record payment_hash ব্যবহার করে, transaction_id, confirmation আর explorer link null; BTC precision 11 (millisatoshi)। Preimage, BOLT11 বা wallet secret প্রকাশিত নয়।
  • observed_at descending, তারপর payment_id descending ক্রম। Count আর page একই repeatable-read snapshot ব্যবহার করে; payment এলে পরের page বদলাতে পারে। Live invoice paginate করলে payment_id দিয়ে duplicate বাদ দাও।
  • আগের read-only project scope, IP restriction আর per-credential rate limit প্রযোজ্য। Callback-provided link-এর origin configured API host-এর সঙ্গে না মিললে token দিয়ে অনুসরণ কোরো না।

ত্রুটি

Error code ও retry-এর নিয়ম

GETচেকআউটের কাঠামো/পাবলিক

Managed checkout-host root invoice না বেছে checkout application দেয়। Customer integration-এ সাধারণত links.checkout ব্যবহার করা উচিত।

Authentication ও header

পাবলিক

অনুরোধ

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://pay.example.com/" \
  --output 'checkout.html'

উত্তর 200 text/html

উদাহরণ response
<!doctype html>
<!-- Hosted Wholly Crypto checkout shell -->
ব্যবহারের নোট
  • Bearer token লাগে না।
  • Managed checkout edge GET/HEAD নেয় এবং অন্য method আটকায়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETহোস্টেড চেকআউট পৃষ্ঠা/invoice/{invoice_id}পাবলিক

Customer-facing HTML checkout। পৃষ্ঠা একই checkout host থেকে checkout-safe JSON আনে। Store চালু করে parent HTTPS origin স্পষ্টভাবে অনুমোদন না দিলে embedding বন্ধ।

Authentication ও header

পাবলিক

Path parameter

invoice_idUUIDবাধ্যতামূলক

Merchant API-এর ফেরত দেওয়া public invoice UUID।

অনুরোধ

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://pay.example.com/invoice/YOUR_PUBLIC_INVOICE_ID" \
  --output 'checkout.html'

উত্তর 200 text/html

উদাহরণ response
<!doctype html>
<!-- Hosted Wholly Crypto checkout application -->
ব্যবহারের নোট
  • Bearer token নেওয়া হয় না, দরকারও নেই।
  • Invoice না থাকলেও HTML shell নিজে 200 দেয়; তারপর checkout JSON request invoice_not_found পায়।
  • Response no-store, noindex এবং invoice-specific frame-ancestors CSP-সহ।
  • Disabled project/store বা unknown invoice checkout data প্রকাশ করে না।

ত্রুটি

Error code ও retry-এর নিয়ম

GETচেকআউটে দেখানোর নিরাপদ ইনভয়েস/checkout-api/invoices/{invoice_id}পাবলিক

শুধু checkout দেখানোর দরকারি field ফেরত দেয়। ইচ্ছাকৃতভাবে internal ID, customer email আর derived address field, IPN URL, merchant metadata, wallet ID, derivation path আর monitor diagnostic বাদ দেয়।

Authentication ও header

পাবলিক

Path parameter

invoice_idUUIDবাধ্যতামূলক

Public invoice UUID।

অনুরোধ

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID" \
  --header 'Accept: application/json'

উত্তর 200 application/json

উদাহরণ response
{
  "data": {
    "invoice_id": "0a6a98db-d93d-48ee-8c3c-fd45f90c4a50",
    "order_id": "order-1042",
    "description": "Annual plan",
    "amount": "49.9",
    "currency": "USD",
    "exchange_rate_spread_percent": "0.5",
    "underpayment_tolerance_percent": "1",
    "status": "processing",
    "amount_status": "partial",
    "timing_status": "on_time",
    "sequence": 3,
    "active_payment_method_id": "33333333-3333-4333-8333-333333333333",
    "payment_method_locked": true,
    "server_time": "2026-08-31T18:10:00Z",
    "expires_at": "2026-08-31T18:15:00Z",
    "expires_in_seconds": 300,
    "payment_open": true,
    "redirect_url": "https://merchant.example/orders/1042",
    "cancel_url": "https://merchant.example/cart",
    "redirect_automatically": true,
    "checkout_language": "en",
    "project": {
      "name": "Example project",
      "checkout_title": "Complete your payment",
      "checkout_description": "Send the exact amount shown.",
      "theme": "system",
      "accent_color": "#42e39b",
      "logo_url": "/checkout-api/invoices/…/logo/…/image.png"
    },
    "store": { "name": "Online shop" },
    "payment_methods": [
      {
        "id": "33333333-3333-4333-8333-333333333333",
        "asset_key": "bip122:000000000019d6689c085ae165831e93/slip44:0",
        "chain_slug": "bitcoin",
        "chain_name": "Bitcoin",
        "network": "mainnet",
        "caip_network_id": "bip122:000000000019d6689c085ae165831e93",
        "caip_asset_id": "bip122:000000000019d6689c085ae165831e93/slip44:0",
        "asset_name": "Bitcoin",
        "symbol": "BTC",
        "asset_icon_url": "/assets/coingecko/bitcoin.png",
        "asset_kind": "native",
        "contract_address": null,
        "token_standard": null,
        "asset_decimals": 8,
        "status": "partial",
        "payable": true,
        "finality_mode": "confirmations",
        "required_confirmations": 1,
        "expected_amount": "0.00046",
        "expected_amount_atomic": "46000",
        "minimum_payment_amount": "0.0004554",
        "minimum_payment_amount_atomic": "45540",
        "received_amount": "0.0002",
        "received_amount_atomic": "20000",
        "remaining_amount": "0.0002554",
        "remaining_amount_atomic": "25540",
        "confirmed_amount": "0",
        "confirmed_amount_atomic": "0",
        "destination_address": "bc1q…example",
        "destination_tag": null,
        "quote_expires_at": "2026-08-31T18:15:00Z",
        "payment_uri": "bitcoin:bc1q…example?amount=0.00026",
        "qr_url": "/checkout-api/invoices/…/payment-methods/…/qr.svg?sequence=3&amount_atomic=26000",
        "address_explorer_name": "mempool.space",
        "address_explorer_url": "https://mempool.space/address/…",
        "transaction_count": 0,
        "transactions_truncated": false,
        "transactions": []
      }
    ]
  }
}

Response field

dataobject
invoice_idUUIDসব সময়

Public invoice UUID।

order_idstring | nullসব সময়

Merchant order reference।

descriptionstring | nullসব সময়

Customer-facing description।

amountdecimal stringসব সময়

Invoice amount।

currencystringসব সময়

Invoice currency।

exchange_rate_spread_percentdecimal stringসব সময়

Per-invoice override-সহ creation-এ locked effective quote spread।

underpayment_tolerance_percentdecimal stringসব সময়

এই invoice-এর accepted shortfall percentage।

statusinvoice statusসব সময়

বর্তমান invoice status।

amount_statusamount statusসব সময়

none, partial, paid বা overpaid। স্পষ্টভাবে অনুমোদিত zero-amount invoice none আর payment method ছাড়াই settled হয়।

timing_statustiming statusসব সময়

on_time বা late।

sequenceintegerসব সময়

বর্তমান state sequence।

active_payment_method_idUUID | nullসব সময়

অর্থ পাওয়া তালিকাভুক্ত payment method। Checkout এই method-এই থাকে যাতে underpayment incompatible asset দিয়ে চালানো না হয়।

payment_method_lockedbooleanসব সময়

Valid payment active_payment_method_id বেছে নিলে true।

server_timeRFC 3339 timestampসব সময়

এই response-এর server clock; customer-device clock-এর ভুল এড়াতে expires_at-এর সঙ্গে নাও।

expires_atRFC 3339 timestampসব সময়

Invoice deadline।

expires_in_secondsintegerসব সময়

server_time-এ বাকি পূর্ণ second, ওপরের দিকে round আর শূন্যের নিচে নয়।

payment_openbooleanসব সময়

শুধু deadline-এর আগে new বা processing invoice-এ অন্তত এক payable method-এর বাকি amount থাকলে true।

redirect_urlstring | nullসব সময়

সফল settlement-এর পরে customer return target।

cancel_urlstring | nullসব সময়

সফল settlement ছাড়া বের হলে customer return target।

redirect_automaticallybooleanসব সময়

Automatic redirect policy।

checkout_languagestringসব সময়

Checkout language।

projectobjectসব সময়

name, checkout_title, checkout_description, theme, accent_color আর logo_url।

namestring
checkout_titlestring
checkout_descriptionstring
themestring
accent_colorstring
logo_urlstring
storeobjectসব সময়

Public store name।

namestring
appearanceobjectসব সময়

Effective presentation: দেওয়া থাকলে frozen per-invoice override, নইলে store-এর current design। Financial field বা safety warning বদলায় না।

inherit_default_storebooleanসব সময়

Project-এর default store এই appearance দিলে true। Independent store আর frozen invoice override-এ false।

invoice_overridebooleanসব সময়

Invoice creation-এ checkout_appearance দেওয়া হলে true। Omitted/null হলে false থাকে।

titlestringসব সময়

Plain merchant heading, top message আর bottom message। intro customer_message-এর বদলে আসে; পুরোনো stored copy থাকে। Markup হিসেবে evaluate কোরো না।

introstringসব সময়

Plain merchant heading, top message আর bottom message। intro customer_message-এর বদলে আসে; পুরোনো stored copy থাকে। Markup হিসেবে evaluate কোরো না।

outrostringসব সময়

Plain merchant heading, top message আর bottom message। intro customer_message-এর বদলে আসে; পুরোনো stored copy থাকে। Markup হিসেবে evaluate কোরো না।

intro_font_sizeintegerসব সময়

Pixel-এ font size: 12, 14, 16, 18, 20 বা 24।

outro_font_sizeintegerসব সময়

Pixel-এ font size: 12, 14, 16, 18, 20 বা 24।

customer_messagestringসব সময়

intro-এর পুরোনো compatibility alias। নতুন integration-এ intro নাও।

themesystem | light | dim | darkসব সময়

Customer-device preference বা fixed theme।

accent_colorstringসব সময়

শুধু #RRGGBB color। Automatic value-এর জন্য optional color খালি; foreground contrast হিসাব করা হয়।

background_colorstringসব সময়

শুধু #RRGGBB color। Automatic value-এর জন্য optional color খালি; foreground contrast হিসাব করা হয়।

card_colorstringসব সময়

শুধু #RRGGBB color। Automatic value-এর জন্য optional color খালি; foreground contrast হিসাব করা হয়।

button_colorstringসব সময়

শুধু #RRGGBB color। Automatic value-এর জন্য optional color খালি; foreground contrast হিসাব করা হয়।

logo_sizestringসব সময়

small, medium বা large; left বা center। Image পুরোটা ধরে দেখায়, crop নয়।

logo_alignmentstringসব সময়

small, medium বা large; left বা center। Image পুরোটা ধরে দেখায়, crop নয়।

imagesobjectসব সময়

ঐচ্ছিক logo_light, logo_dark আর favicon URL: scoped, same-origin normalized PNG image।

show_order_idbooleanসব সময়

Order ID visibility, title-এর নিচে description আর শুরুতে order ID expansion। Amount দেখা যায়; display control, data redaction নয়।

show_descriptionbooleanসব সময়

Order ID visibility, title-এর নিচে description আর শুরুতে order ID expansion। Amount দেখা যায়; display control, data redaction নয়।

details_expandedbooleanসব সময়

Order ID visibility, title-এর নিচে description আর শুরুতে order ID expansion। Amount দেখা যায়; display control, data redaction নয়।

show_project_namebooleanসব সময়

Merchant 5.6.0+: header name visibility। দুটো default true। Project/store identity JSON-এ থাকে।

show_store_namebooleanসব সময়

Merchant 5.6.0+: header name visibility। দুটো default true। Project/store identity JSON-এ থাকে।

featured_chains[]arrayসব সময়

ক্রমে রাখা preference, শুধু invoice-এ আগে থাকা method-এ লাগে। Missing বা disabled method উপেক্ষা।

featured_asset_ids[]arrayসব সময়

ক্রমে রাখা preference, শুধু invoice-এ আগে থাকা method-এ লাগে। Missing বা disabled method উপেক্ষা।

default_asset_idUUID | nullসব সময়

প্রস্তাবিত initial method। Valid remembered customer preference বা ইতিমধ্যে অর্থ পাওয়া method আগে।

messagesobjectসব সময়
en, de, es, pt-BR, it, ru, zh-CN, fr, ko আর ja-এর plain text, waiting, confirming, paid, underpaid আর expired key-এ। Merchant message না থাকলে English fallback। সহায়ক; actual status বদলায় না। Merchant-এর লেখা নিজে থেকে translate হয় না।বিস্তারিত

en, de, es, pt-BR, it, ru, zh-CN, fr, ko আর ja-এর plain text, waiting, confirming, paid, underpaid আর expired key-এ। Merchant message না থাকলে English fallback। সহায়ক; actual status বদলায় না। Merchant-এর লেখা নিজে থেকে translate হয় না।

enobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
deobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
esobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
pt-BRobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
itobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
ruobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
zh-CNobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
frobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
koobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
jaobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
support_emailstringসব সময়

ঐচ্ছিক contact আর HTTPS link, URL credential ছাড়া। External link নতুন window-তে খোলে।

support_urlstringসব সময়

ঐচ্ছিক contact আর HTTPS link, URL credential ছাড়া। External link নতুন window-তে খোলে।

terms_urlstringসব সময়

ঐচ্ছিক contact আর HTTPS link, URL credential ছাড়া। External link নতুন window-তে খোলে।

privacy_urlstringসব সময়

ঐচ্ছিক contact আর HTTPS link, URL credential ছাড়া। External link নতুন window-তে খোলে।

return_button_textstringসব সময়

শুধু ঐচ্ছিক label। Success/cancel target আর redirect policy invoice-এরই।

show_return_buttonbooleanসব সময়

Manual return/cancel button visibility; default true। Active আর terminal state-এ লাগে, automatic success redirect-এ নয়। Merchant 8.1.4 থেকে।

payment_methods[]object[]সব সময়

Checkout-safe payment method।

payment_railonchain | lightningসব সময়

Lightning Bitcoin method-ই থাকে, on-chain BTC থেকে আলাদা। শুধু asset_id নয়, intent id আর rail দিয়ে চিহ্নিত করো।

bolt11string | nullসব সময়

Signed Lightning request; on-chain method-এ null। payable false হলে আর pay কোরো না।

payment_hashstring | nullসব সময়

Reconciliation-এর Lightning payment hash, receiving address নয়। On-chain method-এ null।

idUUIDসব সময়

Payment intent identifier।

asset_idUUIDসব সময়

Appearance preference-এ asset UUID; এই invoice-এর payment intent id থেকে আলাদা।

asset_keystringসব সময়

Canonical asset key।

chain_slugstringসব সময়

Machine আর display chain name।

chain_namestringসব সময়

Machine আর display chain name।

networkstringসব সময়

Payment network।

caip_network_idstringসব সময়

বাছাই করা chain আলাদা করতে canonical network identity।

caip_asset_idstring | nullসব সময়

Canonical exact asset identity, প্রযোজ্য হলে verified token contract বা mint-সহ।

asset_namestringসব সময়

Payment asset display value।

symbolstringসব সময়

Payment asset display value।

asset_icon_urlstring | nullসব সময়

Same-origin locally cached asset icon, verified CoinGecko mapping না থাকলে null।

asset_kindnative | tokenসব সময়

Native currency আর contract/mint payment আলাদা করে।

contract_addressstring | nullসব সময়

Token-এর canonical ERC-20 contract বা SPL mint; native currency-তে null।

token_standarderc20 | spl-token | nullসব সময়

Verified token runtime, native currency-তে null।

asset_decimalsintegerসব সময়

Atomic-unit precision: Lightning BTC millisatoshi-তে 11, on-chain BTC satoshi-তে 8।

statusintent statusসব সময়

বর্তমান payment-method status।

payablebooleanসব সময়

শুধু এই exact method এখন payment নিতে পারলে true; অন্য asset-এ অর্থ আসার পর inactive method-এ false।

finality_modestringসব সময়

Finality policy।

required_confirmationsintegerসব সময়

Finality policy।

expected_amountdecimalসব সময়
Display আর actual on-chain unit-এ পুরো locked quote। চেনা fiat stablecoin সর্বোচ্চ দুই quote decimal নেয়, spread-এর পরে সব সময় ওপরের দিকে round; অন্য asset adaptive precision নেয়। Actual token decimal, received fund আর partial-payment remainder exact থাকে। Returned amount অপরিবর্তিত নাও।বিস্তারিত

Display আর actual on-chain unit-এ পুরো locked quote। চেনা fiat stablecoin সর্বোচ্চ দুই quote decimal নেয়, spread-এর পরে সব সময় ওপরের দিকে round; অন্য asset adaptive precision নেয়। Actual token decimal, received fund আর partial-payment remainder exact থাকে। Returned amount অপরিবর্তিত নাও।

expected_amount_atomicinteger stringসব সময়
Display আর actual on-chain unit-এ পুরো locked quote। চেনা fiat stablecoin সর্বোচ্চ দুই quote decimal নেয়, spread-এর পরে সব সময় ওপরের দিকে round; অন্য asset adaptive precision নেয়। Actual token decimal, received fund আর partial-payment remainder exact থাকে। Returned amount অপরিবর্তিত নাও।বিস্তারিত

Display আর actual on-chain unit-এ পুরো locked quote। চেনা fiat stablecoin সর্বোচ্চ দুই quote decimal নেয়, spread-এর পরে সব সময় ওপরের দিকে round; অন্য asset adaptive precision নেয়। Actual token decimal, received fund আর partial-payment remainder exact থাকে। Returned amount অপরিবর্তিত নাও।

minimum_payment_amountdecimalসব সময়

Underpayment tolerance-এর পরে accepted settlement threshold।

minimum_payment_amount_atomicinteger stringসব সময়

Underpayment tolerance-এর পরে accepted settlement threshold।

received_amountdecimalসব সময়

দেখা amount।

received_amount_atomicinteger stringসব সময়

দেখা amount।

remaining_amountdecimal stringসব সময়

Accepted threshold-এ পৌঁছাতে দরকারি exact display amount, শূন্যের নিচে নয়।

remaining_amount_atomicinteger stringসব সময়

Atomic unit-এ accepted threshold-এর shortfall। এটি requested payment amount নয়: tolerance শুধু acceptance-এ লাগে।

confirmed_amountdecimalসব সময়

Confirmed/final amount।

confirmed_amount_atomicinteger stringসব সময়

Confirmed/final amount।

destination_addressstringসব সময়

On-chain destination আর optional reference। Lightning-এ tag ছাড়া payment hash; বদলে bolt11/payment_uri-তে pay করো।

destination_tagstring|nullসব সময়

On-chain destination আর optional reference। Lightning-এ tag ছাড়া payment hash; বদলে bolt11/payment_uri-তে pay করো।

quote_expires_atRFC 3339 timestampসব সময়

Quote expiry।

payment_uristring | nullসব সময়
Chain-aware request: ERC-681, Solana Pay, native URI বা lightning:<bolt11>। Amount-bearing request পুরো expected amount থেকে received fund বাদ দেয়, tolerance threshold নয়। payable false হলে null, accepted tolerated shortfall-এর পরেও। Lightning QR পুরো Lightning request encode করে, payment hash নয়।বিস্তারিত

Chain-aware request: ERC-681, Solana Pay, native URI বা lightning:<bolt11>। Amount-bearing request পুরো expected amount থেকে received fund বাদ দেয়, tolerance threshold নয়। payable false হলে null, accepted tolerated shortfall-এর পরেও। Lightning QR পুরো Lightning request encode করে, payment hash নয়।

qr_urlpath | nullসব সময়

Sequence আর exact-remainder revision-সহ same-origin SVG QR path, অথবা payable false হলে null। SVG no-store।

address_explorer_namestring|nullসব সময়

সমর্থিত হলে verified mainnet explorer fallback।

address_explorer_urlstring|nullসব সময়

সমর্থিত হলে verified mainnet explorer fallback।

transaction_countintegerসব সময়

এই method-এর দেখা মোট distinct public valid transaction।

transactions_truncatedbooleanসব সময়

transaction_count ফেরত দেওয়া recent transaction list-এর বেশি হলে true।

transactions[]object[]সব সময়

সর্বশেষ সর্বোচ্চ ১০ public valid transaction। Exact received total এই display limit থেকে স্বাধীন।

transaction_idstringসব সময়

দেখা transaction identifier।

statusdetected | confirming | finalসব সময়

Public observation state।

confirmationsintegerসব সময়

দেখা confirmation count।

block_heightinteger | nullসব সময়

দেখা block/ledger height।

explorer_namestringফেরত এলে

Verified fixed explorer name।

explorer_urlstringফেরত এলে

Verified fixed mainnet explorer URL।

ব্যবহারের নোট
  • Bearer token লাগে না।
  • Cache-Control no-store আর search indexing বন্ধ।
  • invoice_id-কে customer-facing capability data ধরো; অপ্রয়োজনে প্রকাশ কোরো না।
  • asset_icon_url same-origin local asset; দেখাতে customer checkout-এর CoinGecko-তে যোগাযোগ লাগে না।
  • destination_tag non-null হলে address-এর পাশে দেখাও আর কপি করো: এটি বাধ্যতামূলক XRP destination tag, Stellar memo ID বা TON invoice comment, হুবহু পাঠাতে হবে।
  • Verified token-এ asset_kind token, contract_address exact ERC-20 contract বা SPL mint, token_standard rail আর payment_uri token identity জানায়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETস্টোর চেকআউটের preview/invoice/preview/{project_id}পাবলিক

উদাহরণ amount আর real accepted-asset metadata দিয়ে saved store appearance দেখায়। Payment তৈরি না করে waiting, confirming, paid, underpaid আর expired example বদলাও।

Authentication ও header

পাবলিক

Path parameter

project_idUUIDবাধ্যতামূলক

Authenticated console preview link-এ যে project UUID কপি করে।

Query parameter

store_idUUID,ঐচ্ছিক

এই project-এর store। না দিলে first/default store।

statestring,ঐচ্ছিক

waiting, confirming, paid, underpaid বা expired। শুধু browser-এর illustration।

অনুরোধ

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://pay.example.com/invoice/preview/YOUR_PROJECT_ID?store_id=YOUR_STORE_ID&state=confirming" \
  --output 'checkout-preview.html'

উত্তর 200 text/html

উদাহরণ response
<!doctype html>
<!-- Hosted branding preview; no invoice is created -->
ব্যবহারের নোট
  • Preview শুধু branding-এর; customer-কে payment request হিসেবে কখনো পাঠিয়ো না।
  • Receiving address, payable QR, wallet action, redirect বা payment polling নেই। Example actual invoice status বদলায় না।
  • Response no-store, noindex আর embed করা যায় না।

ত্রুটি

Error code ও retry-এর নিয়ম

GETচেকআউট preview-এর ডেটা/checkout-api/previews/{project_id}পাবলিক

Effective store appearance আর safe accepted-asset metadata দেয়। payment_methods খালি থাকে; preview_methods-এ payment address, quote বা private wallet data নেই।

Authentication ও header

পাবলিক

Path parameter

project_idUUIDবাধ্যতামূলক

Console preview link-এর project UUID।

Query parameter

store_idUUID,ঐচ্ছিক

এই project-এর হতে হবে; mismatched ID-তে 404। Unknown query field প্রত্যাখ্যাত।

অনুরোধ

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID?store_id=YOUR_STORE_ID" \
  --header 'Accept: application/json'

উত্তর 200 application/json

উদাহরণ response
{
  "data": {
    "preview": true,
    "invoice_id": "YOUR_PROJECT_ID",
    "amount": "100.00",
    "currency": "USD",
    "project": {
      "name": "Example project",
      "checkout_title": "Complete your payment",
      "checkout_description": "Choose a network and send the exact amount shown.",
      "theme": "system",
      "accent_color": "#42e39b",
      "logo_url": "/checkout-api/previews/…/logo/…/image.png"
    },
    "appearance": {"inherit_default_store": true, "theme": "system", "accent_color": "#42E39B", "images": {}},
    "preview_methods": [],
    "payment_methods": []
  }
}

Response field

dataobject
previewboolean
invoice_idstring
amountstring
currencystring
projectobject
namestring
checkout_titlestring
checkout_descriptionstring
themestring
accent_colorstring
logo_urlstring
appearanceobject
inherit_default_storebooleanসব সময়

Project-এর default store এই appearance দিলে true। Independent store আর frozen invoice override-এ false।

invoice_overridebooleanসব সময়

Invoice creation-এ checkout_appearance দেওয়া হলে true। Omitted/null হলে false থাকে।

titlestringসব সময়

Plain merchant heading, top message আর bottom message। intro customer_message-এর বদলে আসে; পুরোনো stored copy থাকে। Markup হিসেবে evaluate কোরো না।

introstringসব সময়

Plain merchant heading, top message আর bottom message। intro customer_message-এর বদলে আসে; পুরোনো stored copy থাকে। Markup হিসেবে evaluate কোরো না।

outrostringসব সময়

Plain merchant heading, top message আর bottom message। intro customer_message-এর বদলে আসে; পুরোনো stored copy থাকে। Markup হিসেবে evaluate কোরো না।

intro_font_sizeintegerসব সময়

Pixel-এ font size: 12, 14, 16, 18, 20 বা 24।

outro_font_sizeintegerসব সময়

Pixel-এ font size: 12, 14, 16, 18, 20 বা 24।

customer_messagestringসব সময়

intro-এর পুরোনো compatibility alias। নতুন integration-এ intro নাও।

themesystem | light | dim | darkসব সময়

Customer-device preference বা fixed theme।

accent_colorstringসব সময়

শুধু #RRGGBB color। Automatic value-এর জন্য optional color খালি; foreground contrast হিসাব করা হয়।

background_colorstringসব সময়

শুধু #RRGGBB color। Automatic value-এর জন্য optional color খালি; foreground contrast হিসাব করা হয়।

card_colorstringসব সময়

শুধু #RRGGBB color। Automatic value-এর জন্য optional color খালি; foreground contrast হিসাব করা হয়।

button_colorstringসব সময়

শুধু #RRGGBB color। Automatic value-এর জন্য optional color খালি; foreground contrast হিসাব করা হয়।

logo_sizestringসব সময়

small, medium বা large; left বা center। Image পুরোটা ধরে দেখায়, crop নয়।

logo_alignmentstringসব সময়

small, medium বা large; left বা center। Image পুরোটা ধরে দেখায়, crop নয়।

imagesobjectসব সময়

ঐচ্ছিক logo_light, logo_dark আর favicon URL: scoped, same-origin normalized PNG image।

show_order_idbooleanসব সময়

Order ID visibility, title-এর নিচে description আর শুরুতে order ID expansion। Amount দেখা যায়; display control, data redaction নয়।

show_descriptionbooleanসব সময়

Order ID visibility, title-এর নিচে description আর শুরুতে order ID expansion। Amount দেখা যায়; display control, data redaction নয়।

details_expandedbooleanসব সময়

Order ID visibility, title-এর নিচে description আর শুরুতে order ID expansion। Amount দেখা যায়; display control, data redaction নয়।

show_project_namebooleanসব সময়

Merchant 5.6.0+: header name visibility। দুটো default true। Project/store identity JSON-এ থাকে।

show_store_namebooleanসব সময়

Merchant 5.6.0+: header name visibility। দুটো default true। Project/store identity JSON-এ থাকে।

featured_chains[]arrayসব সময়

ক্রমে রাখা preference, শুধু invoice-এ আগে থাকা method-এ লাগে। Missing বা disabled method উপেক্ষা।

featured_asset_ids[]arrayসব সময়

ক্রমে রাখা preference, শুধু invoice-এ আগে থাকা method-এ লাগে। Missing বা disabled method উপেক্ষা।

default_asset_idUUID | nullসব সময়

প্রস্তাবিত initial method। Valid remembered customer preference বা ইতিমধ্যে অর্থ পাওয়া method আগে।

messagesobjectসব সময়
en, de, es, pt-BR, it, ru, zh-CN, fr, ko আর ja-এর plain text, waiting, confirming, paid, underpaid আর expired key-এ। Merchant message না থাকলে English fallback। সহায়ক; actual status বদলায় না। Merchant-এর লেখা নিজে থেকে translate হয় না।বিস্তারিত

en, de, es, pt-BR, it, ru, zh-CN, fr, ko আর ja-এর plain text, waiting, confirming, paid, underpaid আর expired key-এ। Merchant message না থাকলে English fallback। সহায়ক; actual status বদলায় না। Merchant-এর লেখা নিজে থেকে translate হয় না।

enobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
deobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
esobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
pt-BRobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
itobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
ruobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
zh-CNobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
frobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
koobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
jaobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
support_emailstringসব সময়

ঐচ্ছিক contact আর HTTPS link, URL credential ছাড়া। External link নতুন window-তে খোলে।

support_urlstringসব সময়

ঐচ্ছিক contact আর HTTPS link, URL credential ছাড়া। External link নতুন window-তে খোলে।

terms_urlstringসব সময়

ঐচ্ছিক contact আর HTTPS link, URL credential ছাড়া। External link নতুন window-তে খোলে।

privacy_urlstringসব সময়

ঐচ্ছিক contact আর HTTPS link, URL credential ছাড়া। External link নতুন window-তে খোলে।

return_button_textstringসব সময়

শুধু ঐচ্ছিক label। Success/cancel target আর redirect policy invoice-এরই।

show_return_buttonbooleanসব সময়

Manual return/cancel button visibility; default true। Active আর terminal state-এ লাগে, automatic success redirect-এ নয়। Merchant 8.1.4 থেকে।

preview_methods[]array
payment_methods[]array
ব্যবহারের নোট
  • Bearer token নেওয়া হয় না, দরকারও নেই।
  • Invoice, destination, wallet, transaction, IPN, webhook বা merchant metadata ফেরত আসে না।
  • সঠিক pay-domain preview link পেতে authenticated console নাও।

ত্রুটি

Error code ও retry-এর নিয়ম

GETস্টোর চেকআউটের ছবি/checkout-api/invoices/{invoice_id}/appearance-images/{kind}/{revision}/image.pngপাবলিক

এই invoice-এর normalized store logo বা favicon দেয়। Checkout data-র appearance.images URL নাও।

Authentication ও header

পাবলিক

Path parameter

invoice_idUUIDবাধ্যতামূলক

Public invoice UUID।

kindenumবাধ্যতামূলক

logo_light, logo_dark বা favicon।

revisionUUIDবাধ্যতামূলক

Current image revision।

অনুরোধ

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/appearance-images/logo_light/YOUR_IMAGE_REVISION/image.png" \
  --output 'store-logo.png'

উত্তর 200 image/png

উদাহরণ response
(binary PNG response)
ব্যবহারের নোট
  • Checkout JSON-এর appearance.images নাও। Source store upload বদলালেও বা সরালেও frozen invoice image চলে। Explicitly removed, wrong-invoice, wrong-kind আর unknown revision-এ 404; snapshot current store image fallback নেয় না।
  • Invoice override না থাকলে current effective store image ব্যবহার হয় এবং replaced/removed revision-এ 404। শুধু PNG, nosniff আর private caching।
  • Authenticated console-এ সীমিত PNG, JPEG বা WebP store image upload নেওয়া হয়; SVG, HTML বা remote image URL নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETস্টোর preview-এর ছবি/checkout-api/previews/{project_id}/stores/{store_id}/appearance-images/{kind}/{revision}/image.pngপাবলিক

শুধু matching project, store, kind আর current revision-এর normalized preview image দেয়।

Authentication ও header

পাবলিক

Path parameter

project_idUUIDবাধ্যতামূলক

Project UUID।

store_idUUIDবাধ্যতামূলক

Project-এর store।

kindenumবাধ্যতামূলক

logo_light, logo_dark বা favicon।

revisionUUIDবাধ্যতামূলক

Current image revision।

অনুরোধ

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/appearance-images/logo_light/YOUR_IMAGE_REVISION/image.png" \
  --output 'store-preview-logo.png'

উত্তর 200 image/png

উদাহরণ response
(binary PNG response)
ব্যবহারের নোট
  • Preview data-র appearance.images নাও। Unknown বা mismatched ID-তে 404। Wallet বা payment info প্রকাশিত নয়।

ত্রুটি

Error code ও retry-এর নিয়ম

GETপেমেন্ট QR ছবি/checkout-api/invoices/{invoice_id}/payment-methods/{intent_id}/qr.svgপাবলিক

Invoice payment method-এর exact chain-aware payment payload-এর জন্য 512×512 SVG QR তৈরি করে।

Authentication ও header

পাবলিক

Path parameter

invoice_idUUIDবাধ্যতামূলক

Public invoice UUID।

intent_idUUIDবাধ্যতামূলক

Checkout JSON-এর payment method id।

অনুরোধ

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/payment-methods/YOUR_INTENT_ID/qr.svg" \
  --output 'payment-qr.svg'

উত্তর 200 image/svg+xml

উদাহরণ response
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">…</svg>
ব্যবহারের নোট
  • Bearer token লাগে না।
  • Checkout JSON-এর sequence আর remainder-revisioned qr_url নাও; SVG private আর no-store।
  • Partial payment-এর পরে exact remaining amount চায় এবং সেই asset-এই lock থাকে।
  • Expiry, completion বা অন্য method active হলে 409; request encode-এর জন্য বড় হলে payment_qr_unavailable (422)।

ত্রুটি

Error code ও retry-এর নিয়ম

Wholly Crypto 8.3.2-এর রেফারেন্স। তোমার installed version-এর জন্য console-এ Settings → API access → Documentation খোলো। রিলিজ দেখো.