Sheepy API integration guide

Getting started with Sheepy API

Sheepy provides a full-stack cryptocurrency payment infrastructure that lets businesses integrate digital asset transactions into their services. With the Sheepy API, merchants can issue invoices, accept multiple cryptocurrencies, process mass payouts, and receive real-time status updates via webhooks.

For a complete technical reference of all endpoints, visit the official API documentation.

Account setup and access

Setting up the test environment

Sheepy provides a dedicated test environment (sandbox) that allows merchants to simulate payments, create invoices, and test webhooks before moving to production. This environment is designed to help technical teams understand how the API works, validate integration logic, and ensure their systems correctly handle different payment statuses without involving real funds.

You can obtain sandbox access by contacting your account manager. Unlike production, sandbox access does not require verification, making it a convenient first step for developers to start experimenting with the API.

Using the test environment is strongly recommended before going live, as it reduces integration errors and helps ensure a smooth customer payment experience once the production keys are activated.

Account verification

Before accessing the Sheepy API in the production environment, every merchant must pass KYB verification to comply with AML requirements. The process is initiated in the Dashboard under the Verification section and includes submitting company and representative documents through Sheepy’s verification partner.

Verification statuses will be displayed directly in the Dashboard.

For detailed requirements and document lists, please refer to the dedicated Merchant Verification Guide.

API overview

The Sheepy API is a RESTful interface that allows businesses to connect their systems directly to Sheepy’s crypto payment infrastructure. All requests and responses use JSON format, which ensures compatibility with any modern programming language or framework.

Every request must be authenticated with an API Key and signed using an HMAC-SHA256 signature generated from your Secret Key. This ensures that only verified merchants can access the system and that no third party can alter the request. In addition, each request must include a timestamp header, which prevents replay attacks and guarantees the security of your transactions.

In Sheepy, every transaction follows a clear lifecycle that ensures transparency and compliance. When a customer makes a payment, the invoice moves from “new” to “confirming” while the blockchain transaction awaits the required number of confirmations. Once verified, it transitions to “done” and the funds are credited to the merchant account. If the amount is less than expected, the invoice may enter “partially_paid”, while excess payments can move it to “overpaid”. An invoice becomes “expired” if no transaction is received within the allotted time, and “invalid” if funds arrive late, fail KYT screening, or do not meet required parameters. Refunds progress from “refund_requested” to “refunded”, and errors are flagged when processing cannot continue without manual intervention. These statuses, combined with KYT checks on all transactions, provide merchants with a consistent framework for monitoring payment flows and handling exceptions reliably.

Outgoing transactions follow the same transparent model. Merchants can execute single payouts, bulk mass payouts, fiat withdrawals, or refunds tied to specific invoices. All outgoing transactions are linked to the relevant gate, ensuring proper handling of the chosen cryptocurrency. Each transaction moves through clearly defined statuses, from initiation to confirmation, and is subject to the same compliance and settlement rules as incoming payments.

The entire lifecycle of each operation, from creation to closure, is logged with full audit data. These records include blockchain transaction IDs, timestamps, amounts, applied fees, and status changes. Merchants can access this data through the API or the Dashboard, enabling detailed reporting, reconciliation, and dispute management. The result is a transaction framework that is reliable, compliant, and transparent, ensuring smooth integration for businesses using the Sheepy API.

Integration setup

Getting access

To work with the Sheepy API, you first need to create a token on the API Integration page in your Dashboard. Tokens are generated separately for Sandbox and Production and can only be used in their respective environments. Both environments operate in parallel and independently of each other, so your Sandbox integration does not affect Production, and vice versa. The environment selected in the Dashboard does not affect this separation.

When generating a token, you can configure permissions and even restrict requests to a specific list of IP addresses. If you leave the list empty, requests will be accepted from any address.

In Sheepy, the term “token” means a pair of values: API Key and Secret Key. Together, they are used for authentication and authorization of all API requests. Each time you create a new API Key, a Secret Key is also generated. The Secret Key is shown only once during creation, so you must store it safely. If it is lost, you cannot recover it, only generate a new one. You can create as many tokens as you need for each environment and manage them independently.

Request structure

The Sheepy API follows standard REST conventions and communicates in JSON. This means that requests are sent through HTTPS using methods such as GET or POST, and the responses are always returned in structured JSON format. Every request must carry additional headers that allow Sheepy to identify the sender and validate authenticity. These headers include the API Key, a digital signature generated with the Secret Key, and a timestamp in UNIX seconds that makes the request valid only at the time it was created.

Signature generation

The signature is a critical element of security, ensuring that the request has not been changed or intercepted on its way to Sheepy. To create it, your system builds a string by concatenating four parts in a strict order: the current timestamp, the HTTP method in uppercase, the full request URL with all query parameters, and the request body in its exact form. This string is then processed with the HMAC-SHA256 algorithm using your Secret Key. The resulting hash is placed in the X-Signature header of the request.

Because the signature is highly sensitive to any mismatch, even a small change - such as a missing query parameter, a lowercase method name, or extra whitespace in the body - will cause the request to fail. To add another layer of protection, Sheepy also allows you to define how long a request remains valid. This is done with the optional requestTtl parameter, which can be set from five to one hundred and twenty seconds, with thirty seconds being the default.

Webhooks and notifications

Webhooks allow Sheepy to notify merchants in real time about important events such as invoice status changes, incoming deposits, payout confirmations, or refunds. These notifications are sent as HTTPS POST requests to the endpoint URL configured in the merchant’s integration settings. Each webhook contains a JSON payload describing the event and is sent immediately after the event occurs.

To ensure security, every webhook is signed in the same way as API requests, using an HMAC-SHA256 signature placed in the X-Signature header. Merchants must validate this signature by recalculating it from the raw request body and their Secret Key, then comparing it with the provided header. This process guarantees that the notification originates from Sheepy and has not been tampered with during transmission.

Webhooks are only delivered once per event, and the server’s response does not influence delivery. If a webhook fails due to a network or application error, it will not be resent automatically. However, all webhook events are logged in the Sheepy Dashboard, where merchants can review and, if needed, trigger a manual resend to their endpoint.

The payload structure is consistent across event types, typically including the operation ID, type of event, current status, relevant amounts, and timestamps. Developers should design their endpoints to handle these payloads idempotently, ensuring that even if a webhook is resent manually, duplicate processing does not occur.

By implementing webhook handling alongside API polling, merchants gain reliable, near real-time visibility into their transactions. This dual approach helps reduce delays in updating order systems, improves customer experience, and ensures seamless automation of payment flows.

Example webhook payload:

{

"operation_id": "inv_1234567890abcdef",

"type": "invoice",

"status": "done",

"amount": "100.00",

"currency": "USDT",

"timestamp": "2025-09-29T12:34:56Z"

}

Support and contacts

If you encounter issues during integration or need clarification about specific API endpoints, Sheepy provides several support options. The primary channel is the Contact us form available on the official website. For merchants with an assigned account manager, technical questions can also be escalated directly through that channel.

Our support team handles functional and technical inquiries related to API usage, payments, and payouts. Response times may vary depending on the complexity of the request, but urgent production incidents are prioritized. For detailed API specifications, error codes, and troubleshooting steps, developers should always refer to the official API documentation.