Sheepy merchant API Documentation (1.13.14)

The Sheepy API provides merchants with access to crypto processing services and information.

We have two environments:

• Sandbox: This is only needed when testing out your integration with Sheepy.
• Production: In order to provide you with access to the production environment, we require that the integration is tested first. We just want to make sure that everything works the way it should.

Both environments are available via https://api.sheepy.com and are controlled by the switch in the top left corner of the dashboard. API access is regulated through the use of the X-Token authorization header value.

All API queries must be made over HTTPS, and plain HTTP will be refused.

Getting access

API resources are available with a token, which must first be created on the API integration page. For each environment (Sandbox and Production), individual tokens are created and work only with that environment.

In the token settings, you can specify the permissions and the list of allowed IP addresses (if the list is empty, requests are accepted from any addresses).

The term "token" refers to a combination of api_key and secret_key, necessary for API authentication and authorization. Merchants can generate these keys through the Create New API Key section on the Sheepy Integration Page.

With each token, a secret key is generated, which is displayed only once at the time of token creation. Keep the secret key in a safe place because, in the future, it will not be possible to copy or edit it, only to generate a new one.

For each environment, you can create an unlimited number of tokens, which you can use and manage independently.

Making a request

Requests to the Sheepy API follow a RESTful convention using standard HTTP verbs. The API responds with a JSON payload. When a data payload should be provided, it expects parameters to be passed in valid JSON.

Each request should include the following HTTP headers:

• Accept: application/json
• Content-Type: application/json

All requests must contain the following headers:

• X-Token - an API key that you generate on the API integration page.
• X-Signature - signature of the request (see below).
• X-Timestamp - the number of seconds since Unix Epoch in UTC.

Signing a request

The value of the X-Signature is generated by a SHA-256 HMAC algorithm using a secret key (provided upon API Token generation) on the bytes obtained by concatenating the following information:

• A timestamp (value of the X-Timestamp header) taken as a string.
• An HTTP method name in uppercase, e.g., GET or POST.
• URL of the request starting with (1) https://api.sheepy.com, (2) slash /, (3) all query parameters, e.g., https://api.sheepy.com/api/v1/invoices?requestTtl=1.
• Request body, taken exactly as it will be sent.

An example of generating a signature in PHP:

$timestamp = time();
$httpMethod = 'POST'; // or 'GET'
$url = 'https://api.sheepy.com/api/v1/invoices';
$body = json_encode(['amount' => 1000]);

$signature = hash_hmac('sha256', $timestamp . strtoupper($httpMethod) . $url . $body, $secretKey);

Additionally, you can specify the request lifetime using the optional query parameter requestTtl with a value from 5 to 60 seconds (the default value is 5 second).

There is a limit on the number of requests to API resources, which is set at 600 per minute per user. When this limit is reached, the response code for any further requests will be 429. Additionally, the Retry-After header will specify the number of seconds to wait before making another request.

A webhook is an HTTP POST request sent to a target you define in the notification URL on the Integration Profile page.

Please note that we do not send any info to endpoints using HTTP (HTTPS only).

Any notification is sent only once, regardless of the webhook endpoint response.

Webhook types

• invoice_status_changed
  Change the status of an invoice

  {
      "type": "invoice_status_changed",
      "timestamp": 1674041910,
      "data": {
          "invoice": {
              ...
          }
      }
  }
  

• new_deposit
  New deposit by deposit address:

  {
      "type": "new_deposit",
      "timestamp": 1674041910,
      "data": {
          "address": {
              ...
          },
          "invoice": {
              ...
          }
      }
  }
  

• order_status_changed
  Change the status of an order:

  {
      "type": "order_status_changed",
      "timestamp": 1674041910,
      "data": {
          "order": {
              ...
          }
      }
  }
  

• payout_status_changed
  Change the status of a payout:

  {
      "type": "payout_status_changed",
      "timestamp": 1674041910,
      "data": {
          "payout": {
              ...
          }
      }
  }
  

The data in the attribute invoice, address, order, payout have the same format as in the requests for their retrieval:

• Retrieve invoice
• Retrieve deposit address
• Retrieve order
• Retrieve payout

Verifying webhook sender

It's better not to rely on our IP addresses for whitelisting them as webhook sender because they change from time to time.

To make sure that a webhook is sent by us, we have the option to sign it with the SHA-256 HMAC algorithm, similar to signing a request when accessing API resources (see the "Signing a request" section).

If you want to utilize this feature, you can reveal a Secret Key value on the Integration Profile page.

To verify that a webhook is sent by us:

1. Get the webhook X-Signature header value and payload as it is without any alteration or converting to JSON.
2. Receive the HTTP webhook body in bytes.
3. Perform calculations on your side to create a digest using Secret Key, raw webhook payload in bytes, and the SHA-256 HMAC algorithm.
4. Compare the X-Signature header value with the calculated digest.

This changelog presents a comprehensive record of all modifications and enhancements made to the Sheepy API, arranged in chronological order for easy tracking.

November 12, 2024

• Added underpaid setting to Invoice endpoints.

November 5, 2024

• Added pending status to invoices.
• Added autocomplete_overpaid setting to Invoice endpoints.

August 12, 2024

• Added explorer template links to Gates endpoint.
• Added webhook order_status_changed.

July 29, 2024

• Added create, detail and list orders Fiat-to-crypto onramp endpoints

July 08, 2024

• Added properties to Invoice endpoints.

June 10, 2024

• Added properties to Invoice endpoints.

April 08, 2024

• Added Fiat-to-crypto onramp endpoints.

February 12, 2024

• Added invoices and payouts limits description
• The self_transfer attribute has been added to the Payout creation endpoint to indicate the ownership of the wallet address

December 11, 2023

• Added endpoint for simultaneous address and memo validation

November 27, 2023

• Added endpoints for payouts: Payout endpoints

October 23, 2023

• Added settings.service_fee_percent and settings.conversion_fee_percent to methods responses: List all invoices, Create a new invoice, Retrieve invoice

October 09, 2023

• Added settings.service_fee and settings.conversion_fee to method request: Create a new invoice

September 25, 2023

• Added the ability to retrieve balances: Retrieve wallet balances
• Added gate network fees output to list responses for the following method: Get gates
• Added deposit type to method request and responses, as well as deposit options to method responses: Deposit addresses
• Added the ability to get rates: Get rate

September 11, 2023

• Added invoice settings output to list responses for the following method: List all invoices, Create a new invoice, Retrieve invoice

August 1, 2023

• Added invoice configurations that override the default integration profile settings: Create a new invoice
• The parameters - currency, fees, notification_url, autocomplete, gates, and conversion - can now be overridden when creating an invoice

May 2, 2023

• Removed support for the deprecated gate_id parameter for gate identifiers. Now all methods only use the gate parameter with the gate name
• Removed support for the deprecated notification format

April 17, 2023

• Added the ability to specify a gate name when creating an invoice
• Added deposit addresses
• Updated notification format

April 3, 2023

• Added gate name output to method responses: Get gates, List all invoices, Retrieve invoice, Create payout
• The gate_id query parameter is declared deprecated, and the gate parameter should now be used instead

The current list of supported cryptocurrencies. Each gate has a unique name/ticker that does not change over time.

Production gates

Gate	Currency	Payment method	Confirmations	Network	Payout limits
bitcoin	BTC	Bitcoin	2	BTC	Min: 0.000003 Max: 0.8
litecoin	LTC	Litecoin	6	LTC	Min: 0.0001 Max: 750
bitcoincash	BCH	Bitcoin Cash	2	BCH	Min: 0.0001 Max: 150
smartchain	BNB	Binance Smart Chain	12	BNB	Min: 0.00000001 Max: –
dogecoin	DOGE	Dogecoin	15	DOGE	Min: 0.0001 Max: –
ethereum	ETH	Ethereum	12	ETH	Min: 0.00000001 Max: 16
tethererc20	USDT	ERC-20 Tether	12	ETH	Min: 0.0001 Max: 55000
erc20dai	DAI	ERC-20 DAI	12	ETH	Min: 0.0001 Max: –
usdcoin	USDC	ERC-20 USD Coin	12	ETH	Min: 0.0001 Max: –
tron	TRX	TRON	21	TRX	Min: 1 Max: –
trc20usdt	USDT	TRC-20 Tether	21	TRX	Min: 0.01 Max: 55000
xrp	XRP	XRP	1	XRP	Min: 0.0001 Max: 90000

Sandbox gates

Gate	Currency	Payment method	Confirmations	Network	Payout limits
bitcointestnet	BTCT	Bitcoin Testnet	2	BTCT	Min: 0.0001 Max: 0.0026
litecointestnet	LTCT	Litecoin Testnet	6	LTCT	Min: 0.0001 Max: 1.5
ethereumtestnet	ETHT	Ethereum Sepolia	12	ETHT	Min: 0.0001 Max: 0.05
xrptestnet	XRPT	XRP Testnet	1	XRPT	Min: 0.0001 Max: 175

Here is the current list of gates equipped with conversion capability. You can configure the conversion settings on the Integration Profile page.

Production gates conversion table

Convert from	Convert to
Bitcoin bitcoin	Ethereum ethereum ERC-20 Tether tethererc20 TRC-20 Tether trc20usdt Euro eur
Litecoin litecoin	Bitcoin bitcoin Ethereum ethereum ERC-20 Tether tethererc20 TRC-20 Tether trc20usdt Euro eur
Bitcoin Cash bitcoincash	Bitcoin bitcoin ERC-20 Tether tethererc20 TRC-20 Tether trc20usdt Euro eur
Binance Smart Chain smartchain	Bitcoin bitcoin Ethereum ethereum ERC-20 Tether tethererc20 TRC-20 Tether trc20usdt Euro eur
Dogecoin dogecoin
Ethereum ethereum	Bitcoin bitcoin ERC-20 Tether tethererc20 TRC-20 Tether trc20usdt Euro eur
ERC-20 Tether tethererc20	Bitcoin bitcoin Ethereum ethereum Euro eur
ERC-20 DAI erc20dai	Bitcoin bitcoin Ethereum ethereum ERC-20 Tether tethererc20 TRC-20 Tether trc20usdt Euro eur
ERC-20 USD Coin usdcoin	Bitcoin bitcoin Ethereum ethereum ERC-20 Tether tethererc20 TRC-20 Tether trc20usdt Euro eur
TRON tron
TRC-20 Tether trc20usdt	Bitcoin bitcoin Ethereum ethereum Euro eur
XRP xrp	Bitcoin bitcoin Ethereum ethereum ERC-20 Tether tethererc20 TRC-20 Tether trc20usdt Euro eur

Sandbox gates conversion table

Convert from	Convert to
Bitcoin Testnet bitcointestnet	Ethereum Sepolia ethereumtestnet Euro eur
Litecoin Testnet litecointestnet	Bitcoin Testnet bitcointestnet Ethereum Sepolia ethereumtestnet Euro eur
Ethereum Sepolia ethereumtestnet	Bitcoin Testnet bitcointestnet Euro eur
XRP Testnet xrptestnet	Bitcoin Testnet bitcointestnet Ethereum Sepolia ethereumtestnet Euro eur

The list of available Sheepy merchant balances.

This section provides details on the available Sheepy merchant balances. Each gateway maintains its balance separately. Merchants can transfer funds from one gateway to another by using the manual conversion feature.

There are two primary methods to increase your balance:

• Invoice payments by your clients: You can create invoices for your clients using the API method Create a new invoice.
• Deposits to your deposit address by you or your clients: generate a new deposit address with the API method Create a new deposit address.

Debits from your balance occur when initiating withdrawals, payouts, mass payouts, and refunds.

An invoice is a form used by customers to make payments to Sheepy merchants. Merchants create invoices via a request to Sheepy API. Invoice request generates a secure Sheepy-hosted page where customers can view the items, amounts, fees, rates and other invoice details.

The invoice is valid for 15 minutes starting from the invoice creation, when time runs out and the invoice becomes invalid. Invoice status changes are accompanied by notifications being sent to the merchant's URL specified in the integration profile settings. Notifications about invoice statuses can also be sent to customers if the merchant specifies their email addresses when creating invoices.

Invoice amount excluding fees should not be less than 1 Euro and more than 15000 Euro.

Status	Description
new	A new invoice that must be paid within 15 minutes. If not, the invoice gets expired status.
partially_paid	An invoice has been partially paid within 15 minutes after its creation. After the invoice lifetime expires, the status may change to invalid or done, depending on the settings of the Integration Profile.
overpaid	The invoice has been paid more than the required amount. After this, the invoice gets invalid status.
confirming	The invoice is in mempool and being confirmed by the network.
expired *	Invoice with an expired 15 minutes payment term.
invalid	Invoice that requires manual approval in the merchant's dashboard.
done *	Successfully completed invoice.
refund_requested	Invoice with initiated refund request.
refunded *	Partially or fully refunded invoice.
error	Unexpected invoice error. Technical support assistance is required.
pending	Invoice transaction is pending processing.

* Final statuses

You have the option to create a deposit address and subsequently provide it to your clients (type customer_deposit). It is not necessary to create new invoices for each deposit address.

Upon receipt of payment to the designated deposit address, our system will generate an invoice and issue a corresponding notification to you. The invoice will be marked as "done" immediately, and the amount paid (minus fees) will be credited to your wallet. If you have configured conversion in your profile, it will be applied accordingly.

It is required to assign a unique text label to the customer's deposit address, such as a user_id in your system. This text label will be incorporated into notifications for paid invoices.

You can also create a deposit address for self-funding your account in both cryptocurrency and fiat currency (type merchant_deposit). Only one such account can be created for each gateway.

Status	Description
customer_deposit	A deposit address for tracking customer transactions and balances.
merchant_deposit	A deposit address for managing merchant transactions.

The "Mass Payouts" feature in our API facilitates the execution of bulk cryptocurrency transactions. To leverage this, validate your addresses using the Validate address and memo endpoint to ensure accuracy. Utilize the Create payout endpoint to initiate each payout, observing the specific Limits and Quotas as well as individual gate payout limits. Each payout is processed independently, offering status notifications for tracking.

For reviewing previously executed payouts, the List of payouts endpoint can be used with relevant query parameters. Additionally, mass payouts can be managed through the Payouts section of your personal dashboard, where all transactions are logged in the History page.

The payout method allows the merchant to make a cryptocurrency outgoing transaction in cryptocurrency. It is suitable for both one-time and regular transactions. To create a payout, the merchant must have an available balance equal to or bigger than the payout amount, including applicable fees. Also, payout amount excluding applicable fees should be in accordance with the "Payout limits" in gates table.

Status	Description
new	Newly created payout request.
pending	Payout request approved, balance debit pre-authorized.
queue	Transaction has been created and is waiting to be sent to the network.
confirming	Payout transaction is in mempool and being confirmed by the network.
done *	Successfully completed payout.
error	Unexpected invoice error. Technical support assistance is required.
canceled *	Cancelled payout.

* Final statuses

This method allows the merchant to retrieve real-time fiat to cryptocurrency exchange rates. This feature is essential for accurately setting prices or conducting transactions in multiple cryptocurrencies. The rates are updated dynamically to reflect current market conditions.

The Sheepy’s onramp service streamlines the direct purchase of cryptocurrencies using credit cards. The purchased funds are deposited directly into the merchant's wallet, integrating seamlessly into a single payment flow (refer to the deposit addresses feature mentioned previously). The API methods outlined below facilitate the redirection of customers to the cryptocurrency purchase interface, with pre-filled parameters such as amount and currencies. Successful deposits can be tracked on the dashboard under the History page. The onramp service is operational only after KYB verification and switching to the production profile.

There are several integration options:

• Redirect via link
  Obtain your unique link from support and place it on your site. API integration is not required. Your client follows the link, completes the payment, and the funds are credited to your balance.

• Pre-calculated order amount
  Configure API integration. Display currently available fiat and cryptocurrencies on your site and show a preliminary calculation of the crypto amount based on the fiat amount. Specify additional GET parameters such as payment currency, deposit currency, and amount when redirecting clients to the payment page. More details about GET parameters are in the Onramp parameters section.

• Creating an order with custom settings
  Create an order using the API with pre-set currencies and amount before redirecting the client to the payment page. Specify that the user cannot change the cryptocurrency and add an address where Sheepy will send the purchased crypto funds instead of crediting your balance.

You can obtain the address of the payment page from support. The address includes one mandatory and several optional GET parameters:

• merchant (mandatory) - a unique hash
• from (optional) - specifies the ticker of the fiat currency for payment, e.g., from=EUR. Obtain the list of fiat currencies using the Currencies API endpoint in the sources field.
• to (optional) - specifies the ticker of the cryptocurrency being purchased. For cryptocurrencies with multiple networks (e.g., USDT), specify the network with an underscore, e.g., to=USDT_ETH. Obtain the list of available cryptocurrencies using the Currencies API endpoint in the destinations field.
• amount_from (optional) - specifies the amount in fiat currency to be paid by the client. The crypto amount will be calculated automatically.
• amount_to (optional) - specifies the amount in cryptocurrency to be received by the client. The fiat payment amount will be calculated automatically. Only one parameter should be set: amount_from or amount_to. If both are set, preference is given to amount_from.
• reference (optional) - specifies the unique identifier used by a merchant.

The address provided by support will include only the mandatory parameter. You can add other GET parameters at your discretion.