Pecunia Merchant (v1.1.0)

Pecunia Wallet provides you the free API to easily receive crypto right to your Pecunia Wallet. There are no fees or limitations: feel free to get donations, conduct real-time commerce, e.g. issue invoices, bills, etc. No excess layers are present: only you, your wallet and your consumer.

Several plug-and-play plugins and SDKs are available. Learn more here.

What we provide

We operate a payment interface and the invoice state-processing engine: invoice creation API, on-chain monitoring, deterministic state transitions and notification delivery. We do not custody funds — all payments occur directly on the blockchain to merchant-controlled addresses.

Data retention

Invoice records are retained for one month and then irreversibly deleted. This retention period is indicative and may change; merchants should not rely on the platform for long-term archival. Historical invoice data is provided for convenience and operational visibility only and is not a guaranteed legal record.

Merchant obligations

Merchants must:

• use the service in good faith and in compliance with applicable laws and this platform's terms;
• provide and maintain a reachable callback endpoint(s) that responds with HTTP 2xx under normal conditions;
• implement idempotent handling of callbacks, tolerate duplicates and out-of-order deliveries, and respect platform rate limits;
• securely store and rotate any API credentials or secrets issued to them; and
• handle business logic not covered by the platform (for example, surplus/overpaid funds handling, refunds, accounting and dispute resolution).

Operational limits and enforcement

The platform provides best-effort delivery and monitoring features, but does not guarantee delivery, ordering or indefinite storage. In case of abusive or non-compliant behaviour (including repeatedly failing to acknowledge callbacks, malicious activity, or breaches of terms), we reserve the right to suspend or terminate the merchant's access, and to disable optional features such as callback delivery. Nevertheless, we are not able to restrict access to the wallet functions.

Practical recommendations

• Export or archive any long-term records you require before they age out of the platform.
• Keep a robust, idempotent consumer for callbacks and a fallback polling strategy (GET /invoices/{id}) for authoritative state.
• Monitor your callback endpoint and provide support contact information to ensure prompt remediation of delivery problems.

Each client is limited to 250 requests per 10 seconds per IP address. This is a soft-enforced, best-effort limit intended to protect platform stability.

Behaviour on exceed

Exceeding the limit may result in HTTP 429 Too Many Requests or temporary rejections. There is no guaranteed Retry-After header — clients must implement their own retry/backoff logic and treat 429 as transient.

Client responsibility

Clients (merchants) are responsible for tracking their own usage and implementing client-side throttling, exponential backoff, idempotent retries and any batching needed to avoid hitting the limit. Monitoring and alerting on the client side is recommended.

No per-account notification

Because access is tied to wallet identifiers rather than user accounts, we cannot automatically notify merchants of changes to service rules. The rate limit and other operational rules may change; merchants must monitor the service documentation/announcements and adapt accordingly.

State transitions

Transitions are driven by blockchain observations (new transactions, confirmations) or internal timers. Functionally there are two non-final internal sub-states grouped as AWAITING (PENDING and STAGGERING) and three final states: COMPLETED, OVERPAID, EXPIRED. All outward transitions from the AWAITING group lead to one of the final states; the only internal transition inside the group is PENDING → STAGGERING.

PENDING

PENDING is the normal awaiting-payment state after invoice creation. The invoice remains in PENDING while waiting for relevant on-chain transactions to appear or reach sufficient confirmations. If a detected transaction already meets finality and amount criteria at detection time, the invoice may transit directly from PENDING to a final successful state. If invoice expires and unconfirmed transactions are insufficient, PENDING will transition to the appropriate final state.

STAGGERING

STAGGERING is an internal extension of PENDING used to manage the case when an invoice's lifetime lapses while there remain unconfirmed transactions that could make the invoice paid once they confirm. Concretely:

• When an invoice's lifetime expires, the system evaluates the sum of currently unconfirmed transactions together with already confirmed amounts.

  • If those unconfirmed transactions are potentially sufficient to satisfy the invoice, the invoice enters STAGGERING.

  • If the unconfirmed transactions are insufficient, the invoice immediately proceeds to the appropriate final state (COMPLETED, OVERPAID, or EXPIRED) per the amount checks described below.

• While in STAGGERING, the invoice continues to be treated as part of AWAITING; the engine will wait only as long as there is a meaningful chance the pending transactions will produce a successful payment. The invoice leaves STAGGERING and moves to a final state when any of the following becomes true:

  • pending transactions confirm and the confirmed amounts satisfy finalization criteria (leading to COMPLETED or OVERPAID), or

  • pending transactions are no longer sufficient to reach the payment threshold (so further waiting is futile), or

  • pending transactions disappear (reorg / mempool eviction) or otherwise resolve so that no meaningful waiting remains.

Important: entering STAGGERING is purely internal and does not trigger callbacks or notifications.

Final states and amount logic

Finalization decisions are based on the invoice amount and its configured inaccuracy. Define minAmount and maxAmount from the invoice amount plus/minus the configured inaccuracy. The platform applies the same checks regardless of whether the invoice was in PENDING or STAGGERING at the time confirmations occurred:

• COMPLETED (final — success): entered when minAmount ≤ confirmedAmount ≤ maxAmount. The invoice is considered paid.

• OVERPAID (final — success): entered when confirmedAmount > maxAmount. OVERPAID is also treated as a successful payment; the platform marks the invoice final, and any handling of surplus funds (refunds, credit, accounting) is the merchant's responsibility.

• EXPIRED (final — failure): entered when waiting is no longer meaningful (TTL elapsed and even after considering pending transactions there is no path to reach minAmount). The invoice is final and considered not paid.

Important: Because some currency conversions expose limited fractional precision, paying the exact decimal amount may be impossible. The platform therefore treats a confirmedAmount within ± one minimal currency unit of the target coin (for example, ±1 satoshi) as satisfying the minAmount ≤ confirmedAmount ≤ maxAmount check; such payments are considered perfectly paid. This one-unit tolerance does not alter the merchant's configured inaccuracy bounds. As a consequence, even with inaccuracy disabled, an invoice finalized as COMPLETED may have received and requested amounts that differ.

Summary

• PENDING — active waiting for payment.
• STAGGERING — internal extended waiting after expire when unconfirmed transactions might still result in success; does not trigger callbacks.
• COMPLETED / OVERPAID — final, successful (OVERPAID is successful but surplus handling is merchant's responsibility).
• EXPIRED — final, unsuccessful.
• All finalization checks respect the invoice's configured inaccuracy; final states are immutable and trigger the platform's final callbacks as described below.

Callbacks are the authoritative record of an invoice. The callback payload is a snapshot of the invoice (equivalent to GET /invoices/{id}) provided for convenience.

Every callback is signed via the X-Signature header, which looks like X-Signature: v1=x[, v0=y]. x and y are hex-encoded HMAC-SHA256 signatures of the callback body. v1 is always present and uses the current secret; v0 is optional and uses the previous secret (for key rotation).

Practical guarantees and rules:

• Notification semantics: callbacks are delivered at-least-once. Duplicate deliveries are possible and expected; merchants must be prepared to handle duplicates idempotently.

• Ordering: there is no guarantee of delivery order. Events may arrive out of order.

• When sent: callbacks are issued when an invoice reaches a final state (COMPLETED, OVERPAID, EXPIRED). Note: entering STAGGERING does not trigger callbacks.

• Callback URLs: three callback URLs are configurable per invoice/account as described below in specification:

  • default — receives all callbacks;
  • success — receives callbacks for successful final states (COMPLETED, OVERPAID);
  • failure — receives callbacks for unsuccessful final states (EXPIRED).

  Each configured URL is called independently. If default equals success or failure, the platform will still perform both calls (duplicates possible).

• Delivery attempts: delivery is best-effort. The platform will retry transient failures, but delivery is not guaranteed; merchants should provide a reachable endpoint and design for retries, duplicates and out-of-order messages.

Input Size

Unless else specified:

• Max string length is 255;
• Number precision is 38 (precision is total digits in a number, either of integer and decimal parts).

Any input that violates these rules will result in errors.

Pagination

Pagination is a technique that allows you to segment response into smaller parts. If an endpoint allows pagination, the next rules are rightful:

• endpoint accepts query parameters pageSize and pageNum;
• if one of pagination params specified, response contains headers X-Items-Remaining, X-Total-Count, X-Page.

Page Size (pageSize)

Describes number of items to be returned. Should be a non-negative integer.

Page Number (pageNum)

Number of pages to be skipped. If presents and pageSize is not, will be returned sublist from pageNum to the collection end. Should be a non-negative integer. Defaults to zero.

Items Remaining (X-Items-Remaining)

Describes the number of items remaining 'till the end of collection.

Total Count (X-Total-Count)

Describes the total number of items in the collection.

Page Number (X-Page)

Describes the number of current page.

Sorting

You can set the order of items at response if allowed. So how it works:

• specify query parameters sort and, optionally, order;
• receive correspondingly ordered collection.

Important!

Unsorted collections (given to a request w/o sorting wanted) must be considered as chaotic, even if you see any regularities, as soon as there are no warranties such order will consist.

Sorting Fields (sort)

Comma-separated names of fields you want to order by

Order Direction (order)

The order direction. One of: asc (ascending), desc (descending)

Filtering

You can filter response entries if allowed. You need to specify query parameter filter, that respects the RSQL specification.

For example: ?filter=operationCoin=in=(LTC,BTC) to get only items that have operationCoin set to LTC or BTC.