Download OpenAPI specification:Download
The Sheepy API provides merchants with access to crypto processing services and information.
We have two environments:
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.
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.
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.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:
X-Timestamp
header) taken as a string.https://api.sheepy.com
, (2) slash /
, (3) all query parameters, e.g., https://api.sheepy.com/api/v1/invoices?requestTtl=1
.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.
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:
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:
X-Signature
header value and payload as it is without any alteration or converting to JSON.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.
underpaid
setting to Invoice endpoints.pending
status to invoices.success_url
input to requests and to method responses on onramp orders creation.reference
to create Fiat-to-crypto onramp order.settings.network_fee
input to requests and settings.network_fee_type
to method responses on invoice creation.order_status_changed
.overpaid
status to invoices.network
, deposit_enabled
, withdrawal_enabled
, deposit_fee
, withdrawal_fee
, withdrawal_min
, withdrawal_max
, memo
outputs to Get gates method responses.self_transfer
attribute has been added to the Payout creation endpoint to indicate the ownership of the wallet address.decimals
output to Get gates method response.settings.service_fee_percent
and settings.conversion_fee_percent
to methods responses: List all invoices, Create a new invoice, Retrieve invoice.currency
, fees
, notification_url
, autocomplete
, gates
, and conversion
- can now be overridden when creating an invoice.gate_id
parameter for gate identifiers. Now all methods only use the gate
parameter with the gate name.gate_id
query parameter is declared deprecated, and the gate
parameter should now be used instead.success_url
when creating an invoice.The current list of supported cryptocurrencies. Each gate has a unique name/ticker that does not change over time.
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 |
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.
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 |
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 |
Get a list of supported cryptocurrencies (assets available for payment processing). Manage the list of selected cryptocurrencies on the Integration Profile page.
{- "data": [
- {
- "name": "tethererc20",
- "ticker": "USDT",
- "title": "Tether ERC20",
- "network": "ETH",
- "deposit_enabled": true,
- "withdrawal_enabled": true,
- "deposit_fee": "0.00003000",
- "withdrawal_fee": "0.00003000",
- "withdrawal_min": "0.1",
- "withdrawal_max": "1000.0",
- "memo": "string",
- "decimals": 6,
}
]
}
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:
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 autocomplete setting. |
overpaid |
The invoice has been paid more than the required amount within 15 minutes after its creation. After the invoice lifetime expires, the status may change to invalid or done , depending on the autocomplete setting. |
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
This endpoint allows to get a list of invoices. Please use this endpoint to get detailed information on all invoices associated with your merchant account.
id | string or null Example: id=01JE3EH7FKVDQRH63HAS914PTQ filters by invoice identifier |
created_from | string or null <date-time> Example: created_from=2023-01-01 00:12:01 filters by creation datetime from the specified date |
created_to | string or null <date-time> Example: created_to=2023-02-01 15:42:01 filters by creation datetime up to the specified date |
status | Array of strings or null Enum: "new" "partially_paid" "overpaid" "confirming" "expired" "invalid" "refunded" "refund_requested" "done" "error" "pending" Example: status=new status filter |
limit | integer or null [ 1 .. 500 ] Default: 50 Example: limit=12 sets the number of invoices per response |
{- "data": [
- {
- "id": "01JE3EH7GR4F0WKE2979HZ38VW",
- "status": "done",
- "reference": "Order #12345",
- "description": "Payment for goods or services",
- "back_url": "https://example.com/merchant_back_url",
- "success_url": "https://example.com/merchant_success_url",
- "created_at": "2024-12-02T10:26:52.056184Z",
- "expires_at": "2024-12-02T10:41:52.056190Z",
- "invoice_amount": 102.23,
- "invoice_currency": "EUR",
- "price": 101.01,
- "taxes": 20.01,
- "final_amount": 120.02,
- "payment": {
- "gate": "tethererc20",
- "address": "n61udDbLFhOymUSjzIkp8h6wQm9hRVmHwH6fH0GB",
- "memo": "Memo string",
- "txid": [
- "0x9b4480ddub8e21cdc4f3378a113597229c3fe9181513b5fdf520fdc44c47502a"
], - "requested_amount": "107.12",
- "paid_amount": "107.12",
- "currency": "USDT",
- "network": "ETH"
}, - "fees": {
- "network": "0.0003",
- "service": "0.012",
- "total": "0.0123"
}, - "rate": "123.456",
- "onramp_order": {
- "id": "01JE3EH7GQJ7STDYYTM6FJKVRC",
- "status": "new",
- "invoice_id": "01JE3EH7GQJ7STDYYTM6FJKVRD",
- "request_amount": 100,
- "request_currency": "EUR",
- "payment_currency": "USD",
- "final_amount": 95,
- "crypto_amount": 0.123,
- "gate": "tethererc20",
- "network": "ETH",
- "rate": "0.00012456",
- "success_url": "https://example.com/onramp-success",
- "fixed_gate": true,
- "reference": "Order #12345",
- "company_name": "Some Company LLC"
}, - "settings": {
- "service_fee_type": "included",
- "service_fee_percent": 0.99,
- "conversion_fee_type": "included",
- "conversion_fee_percent": 1.5,
- "network_fee_type": "on_top",
- "taxes_type": "inclusive",
- "taxes_rate": 0.12,
- "conversion": {
- "type": "partial",
- "percent": 22.53,
- "gate": "bitcoin"
}, - "autocomplete": true,
- "autocomplete_overpaid": true,
- "underpaid": 0,
- "gates": [
- "bitcoin"
]
}
}
]
}
This endpoint is used to generate a new invoice and specify all necessary business details. Once created, the invoice can be sent to the customer for payment.
Possible errors:
Invoice data
amount required | double [ 1 .. 15000 ] invoice amount between 1 EUR and 15000 EUR |
reference | string or null <= 255 characters a unique identifier used by a merchant |
description | string or null <= 255 characters purpose of payment |
string or null <= 255 characters customer's email address | |
back_url | string or null <= 255 characters a web address that redirects customers back to the merchant's website after payment or cancellation of an invoice |
success_url | string or null <= 255 characters a web address that redirects customer when the invoice payment is completed |
gate | string or null <= 255 characters an identifier used to select the correct gateway which can be modified by customers while making a payment |
object configurations that override the default integration profile settings |
{- "amount": "101.22",
- "reference": "Order #12345",
- "description": "the purpose of payment",
- "back_url": "https://example.com/merchant_back_url",
- "success_url": "https://example.com/merchant_success_url",
- "gate": "bitcoin",
- "settings": {
- "currency": "EUR",
- "service_fee": "on_top",
- "conversion_fee": "on_top",
- "network_fee": "on_top",
- "notification_url": "https://example.com/merchant_notifications_goes_here",
- "autocomplete": true,
- "autocomplete_overpaid": true,
- "underpaid": 0,
- "gates": [
- "bitcoin",
- "ethereum",
- "dash"
], - "conversion": {
- "type": "partial",
- "gate": "ethereum",
- "percent": 1
}
}
}
{- "data": {
- "id": "01JE3EH7GQJ7STDYYTM6FJKVRF",
- "status": "done",
- "reference": "Order #12345",
- "description": "Payment for goods or services",
- "back_url": "https://example.com/merchant_back_url",
- "success_url": "https://example.com/merchant_success_url",
- "created_at": "2024-12-02T10:26:52.055879Z",
- "expires_at": "2024-12-02T10:41:52.055886Z",
- "invoice_amount": 102.23,
- "invoice_currency": "EUR",
- "price": 101.01,
- "taxes": 20.01,
- "final_amount": 120.02,
- "payment": {
- "gate": "tethererc20",
- "address": "SwWK8kmiP6NPYRf0GkRkhdgPOYJszJvt8Hu2i1Wv",
- "memo": "Memo string",
- "txid": [
- "0x9b4480ddub8e21cdc4f3378a113597229c3fe9181513b5fdf520fdc44c47502a"
], - "requested_amount": "107.12",
- "paid_amount": "107.12",
- "currency": "USDT",
- "network": "ETH"
}, - "fees": {
- "network": "0.0003",
- "service": "0.012",
- "total": "0.0123"
}, - "rate": "123.456",
- "onramp_order": {
- "id": "01JE3EH7GQJ7STDYYTM6FJKVRC",
- "status": "new",
- "invoice_id": "01JE3EH7GQJ7STDYYTM6FJKVRD",
- "request_amount": 100,
- "request_currency": "EUR",
- "payment_currency": "USD",
- "final_amount": 95,
- "crypto_amount": 0.123,
- "gate": "tethererc20",
- "network": "ETH",
- "rate": "0.00012456",
- "success_url": "https://example.com/onramp-success",
- "fixed_gate": true,
- "reference": "Order #12345",
- "company_name": "Some Company LLC"
}, - "settings": {
- "service_fee_type": "included",
- "service_fee_percent": 0.99,
- "conversion_fee_type": "included",
- "conversion_fee_percent": 1.5,
- "network_fee_type": "on_top",
- "taxes_type": "inclusive",
- "taxes_rate": 0.12,
- "conversion": {
- "type": "partial",
- "percent": 22.53,
- "gate": "bitcoin"
}, - "autocomplete": true,
- "autocomplete_overpaid": true,
- "underpaid": 0,
- "gates": [
- "bitcoin"
]
}
}
}
This endpoint allows to retrieve a specific invoice by its unique identifier id
. This can be useful for looking up the details of a specific payment, such as the amount, payment status etc.
invoiceId required | string invoice identifier |
{- "data": {
- "id": "01JE3EH7GR4F0WKE2979HZ38VW",
- "status": "done",
- "reference": "Order #12345",
- "description": "Payment for goods or services",
- "back_url": "https://example.com/merchant_back_url",
- "success_url": "https://example.com/merchant_success_url",
- "created_at": "2024-12-02T10:26:52.056184Z",
- "expires_at": "2024-12-02T10:41:52.056190Z",
- "invoice_amount": 102.23,
- "invoice_currency": "EUR",
- "price": 101.01,
- "taxes": 20.01,
- "final_amount": 120.02,
- "payment": {
- "gate": "tethererc20",
- "address": "n61udDbLFhOymUSjzIkp8h6wQm9hRVmHwH6fH0GB",
- "memo": "Memo string",
- "txid": [
- "0x9b4480ddub8e21cdc4f3378a113597229c3fe9181513b5fdf520fdc44c47502a"
], - "requested_amount": "107.12",
- "paid_amount": "107.12",
- "currency": "USDT",
- "network": "ETH"
}, - "fees": {
- "network": "0.0003",
- "service": "0.012",
- "total": "0.0123"
}, - "rate": "123.456",
- "onramp_order": {
- "id": "01JE3EH7GQJ7STDYYTM6FJKVRC",
- "status": "new",
- "invoice_id": "01JE3EH7GQJ7STDYYTM6FJKVRD",
- "request_amount": 100,
- "request_currency": "EUR",
- "payment_currency": "USD",
- "final_amount": 95,
- "crypto_amount": 0.123,
- "gate": "tethererc20",
- "network": "ETH",
- "rate": "0.00012456",
- "success_url": "https://example.com/onramp-success",
- "fixed_gate": true,
- "reference": "Order #12345",
- "company_name": "Some Company LLC"
}, - "settings": {
- "service_fee_type": "included",
- "service_fee_percent": 0.99,
- "conversion_fee_type": "included",
- "conversion_fee_percent": 1.5,
- "network_fee_type": "on_top",
- "taxes_type": "inclusive",
- "taxes_rate": 0.12,
- "conversion": {
- "type": "partial",
- "percent": 22.53,
- "gate": "bitcoin"
}, - "autocomplete": true,
- "autocomplete_overpaid": true,
- "underpaid": 0,
- "gates": [
- "bitcoin"
]
}
}
}
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. |
This endpoint retrieves a list of deposit addresses.
limit | integer or null [ 1 .. 1000 ] Default: 100 Example: limit=10 specify the number of records to return (the default value is 100) |
offset | integer or null >= 0 Default: 0 Example: offset=100 set the offset in the result set (the default value is 0) |
{- "data": [
- {
- "id": "01JE3EH7GR4F0WKE2979HZ38VV",
- "type": "customer_deposit",
- "reference": "John address",
- "gate": "bitcoin",
- "address": "tb1qf47cy0rnz606ua0wh0lf8ugl9agk6ahtxqfys8",
- "memo": "Memo string",
- "created_at": "2024-12-02T10:26:52.056107Z",
- "options": {
- "bic": "SXPYDKKKXXX",
- "company_name": "Some Company LLC"
}
}
]
}
This endpoint creates a new deposit address.
Possible Errors:
customer_deposit
, a fiat gateway cannot be specified, as your customers can only make deposits in cryptocurrency.merchant_deposit
is used in the Sandbox profile.Address data
gate required | string unique name of supported cryptocurrency |
type required | string Enum: "merchant_deposit" "customer_deposit" address type |
reference | string <= 255 characters assign a unique (if type = "customer_deposit") text label that is exclusive to the profile, required if type = customer_deposit |
{- "gate": "bitcoin",
- "type": "merchant_deposit",
- "reference": "John's address"
}
{- "data": {
- "id": "01JE3EH7GR4F0WKE2979HZ38VV",
- "type": "customer_deposit",
- "reference": "John address",
- "gate": "bitcoin",
- "address": "tb1qf47cy0rnz606ua0wh0lf8ugl9agk6ahtxqfys8",
- "memo": "Memo string",
- "created_at": "2024-12-02T10:26:52.056107Z",
- "options": {
- "bic": "SXPYDKKKXXX",
- "company_name": "Some Company LLC"
}
}
}
This endpoint retrieves a deposit address by id.
address_id required | string address identifier |
{- "data": {
- "id": "01JE3EH7GR4F0WKE2979HZ38VV",
- "type": "customer_deposit",
- "reference": "John address",
- "gate": "bitcoin",
- "address": "tb1qf47cy0rnz606ua0wh0lf8ugl9agk6ahtxqfys8",
- "memo": "Memo string",
- "created_at": "2024-12-02T10:26:52.056107Z",
- "options": {
- "bic": "SXPYDKKKXXX",
- "company_name": "Some Company LLC"
}
}
}
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 endpoint provides a list of all payouts associated with a specific merchant account. It is designed to offer detailed information about each payout transaction.
id | string or null Example: id=01JE3EH7FP05HQC1B40QVXSCZC filter by payout identifier |
created_from | string or null <date> Example: created_from=2023-01-23 00:12:01 set start date and time to list payouts from that point |
created_to | string or null <date> Example: created_to=2023-01-23 01:00:00 set end date and time to list payouts up to that point |
status | Array of strings or null Enum: "new" "pending" "queue" "confirming" "done" "error" Example: status=new filter by status |
gate | string or null Example: gate=bitcoin filter by payout gate name |
address | string or null Example: address=tb1qxx35aezapey4m8pnaavkc6ttm7934axcepk2ad filter by payout address |
memo | string or null Example: memo=some memo filter by payout memo |
txid | string or null Example: txid=0x8b3180cccb8e21cdc4f3378a113597229c3fe3781513b5fdf520fdc44c47502a filter by transaction ID |
limit | integer or null [ 1 .. 500 ] Default: 50 Example: limit=12 the maximum number of payouts per response |
{- "data": [
- {
- "id": "01JE3EH7GQJ7STDYYTM6FJKVRB",
- "status": "new",
- "currency": "BTC",
- "gate": "bitcoin",
- "amount": "0.0123",
- "address": "tb1qf47cy0rnz606ua0wh0lf8ugl9agk6ahtxqfys8",
- "memo": "Memo string",
- "self_transfer": false,
- "description": "Monthly payment",
- "created_at": "2024-12-02T10:26:52.055760Z",
- "txid": "0x8b3180cccb8e21cdc4f3378a113597229c3fe3781513b5fdf520fdc44c47502a",
- "network_fee": "0.0123",
- "settings": {
- "notification_url": "https://example.com/notifications"
}
}
]
}
This endpoint creates a new payout.
Possible errors:
gate required | string unique name of supported cryptocurrency |
amount required | double payout amount |
address required | string recipient’s cryptocurrency blockchain address |
memo required | string or null recipient's memo (NULL if missing or not supported) |
self_transfer | boolean or null is a label used to designate one's own address |
description | string or null <= 255 characters purpose of payment |
object overrides default integration profile settings for payouts |
{- "gate": "bitcoin",
- "amount": "0.0123",
- "address": "tb1qf47cy0rnz606ua0wh0lf8ugl9agk6ahtxqfys8",
- "memo": "Memo string",
- "self_transfer": true,
- "description": "Monthly payment",
- "settings": {
- "notification_url": "https://example.com/notifications"
}
}
{- "data": {
- "id": "01JE3EH7GQJ7STDYYTM6FJKVRB",
- "status": "new",
- "currency": "BTC",
- "gate": "bitcoin",
- "amount": "0.0123",
- "address": "tb1qf47cy0rnz606ua0wh0lf8ugl9agk6ahtxqfys8",
- "memo": "Memo string",
- "self_transfer": false,
- "description": "Monthly payment",
- "created_at": "2024-12-02T10:26:52.055760Z",
- "txid": "0x8b3180cccb8e21cdc4f3378a113597229c3fe3781513b5fdf520fdc44c47502a",
- "network_fee": "0.0123",
- "settings": {
- "notification_url": "https://example.com/notifications"
}
}
}
This endpoint retrieves detailed information about a specific payout using its unique identifier id
.
payoutId required | string |
{- "data": {
- "id": "01JE3EH7GQJ7STDYYTM6FJKVRB",
- "status": "new",
- "currency": "BTC",
- "gate": "bitcoin",
- "amount": "0.0123",
- "address": "tb1qf47cy0rnz606ua0wh0lf8ugl9agk6ahtxqfys8",
- "memo": "Memo string",
- "self_transfer": false,
- "description": "Monthly payment",
- "created_at": "2024-12-02T10:26:52.055760Z",
- "txid": "0x8b3180cccb8e21cdc4f3378a113597229c3fe3781513b5fdf520fdc44c47502a",
- "network_fee": "0.0123",
- "settings": {
- "notification_url": "https://example.com/notifications"
}
}
}
gate required | string unique name of supported cryptocurrency |
address required | string recipient’s cryptocurrency blockchain address |
memo | string or null recipient's memo |
{- "gate": "bitcoin",
- "address": "tb1qf47cy0rnz606ua0wh0lf8ugl9agk6ahtxqfys8",
- "memo": "Memo string"
}
{- "data": {
- "gate": "bitcoin",
- "address": "tb1qf47cy0rnz606ua0wh0lf8ugl9agk6ahtxqfys8",
- "memo": "Memo string",
- "address_is_valid": true,
- "memo_is_valid": true,
- "errors": [ ]
}
}
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.
from required | string Example: from=BTC ticker of the fiat or cryptocurrency to be converted from |
to required | string Example: to=EUR ticker of the fiat or cryptocurrency to be converted to |
{- "data": {
- "from": "BTC",
- "to": "EUR",
- "rate": "25429.1910500001937002022"
}
}
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 hashfrom
(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.
This endpoint retrieves the list of fiat and cryptocurrencies, along with the supported pairs between them. Each fiat and cryptocurrency possesses a permanent, unique name, which can be utilized in other endpoints, such as the one for calculating amounts.
You can use this endpoint to perform a preliminary calculation of cryptocurrency based on fiat currency.
{- "data": {
- "sources": [
- {
- "name": "eur",
- "ticker": "EUR",
- "title": "Euro",
- "decimals": 2
}
], - "destinations": [
- {
- "name": "tethererc20",
- "ticker": "USDT",
- "title": "Tether ERC20",
- "network": "ETH",
- "deposit_enabled": true,
- "withdrawal_enabled": true,
- "deposit_fee": "0.00003000",
- "withdrawal_fee": "0.00003000",
- "withdrawal_min": "0.1",
- "withdrawal_max": "1000.0",
- "memo": "string",
- "decimals": 6,
}
], - "pairs": [
- {
- "source_name": "eur",
- "source_min": "20",
- "source_max": "2000",
- "destination_name": "bitcoin",
- "destination_min": "0.00001",
- "destination_max": "0.1",
- "rate": "12345.6789"
}
]
}
}
This endpoint retrieves the list of onramp supported countries and territories. Customers from permitted countries will be able to undergo identity verification and purchase cryptocurrency.
{- "data": [
- {
- "iso2": "US",
- "iso3": "USA",
- "name": "United States of America"
}
]
}
This endpoint calculates the amount of cryptocurrency that can be purchased with a specified fiat amount. The name of the fiat currency and the cryptocurrency must be selected from the results provided by the Currencies endpoint. You can use this endpoint for a preliminary calculation of cryptocurrency based on a fiat currency.
Calculate destination data
source_name required | string unique name of supported fiat currency |
destination_name required | string unique name of supported cryptocurrency |
source_amount required | number amount in fiat currency |
{- "source_name": "eur",
- "destination_name": "bitcoin",
- "source_amount": 1000
}
{- "data": {
- "source_name": "eur",
- "source_min": "20",
- "source_max": "2000",
- "destination_name": "bitcoin",
- "destination_min": "0.00001",
- "destination_max": "0.1",
- "rate": "12345.6789",
- "source_amount": 1000,
- "destination_amount": "0.123456"
}
}
This endpoint calculates the amount of fiat currency that can be purchased with a specified crypto amount. The name of the fiat currency and the cryptocurrency must be selected from the results provided by the Currencies endpoint. You can use this endpoint for a preliminary calculation of fiat currency based on a cryptocurrency.
Calculate source data
source_name required | string unique name of supported fiat currency |
destination_name required | string unique name of supported cryptocurrency |
destination_amount required | number amount in crypto currency |
{- "source_name": "eur",
- "destination_name": "bitcoin",
- "destination_amount": 0.123
}
{- "data": {
- "source_name": "eur",
- "source_min": "20",
- "source_max": "2000",
- "destination_name": "bitcoin",
- "destination_min": "0.00001",
- "destination_max": "0.1",
- "rate": "12345.6789",
- "source_amount": 1000,
- "destination_amount": "0.123456"
}
}
This endpoint is used to create a new onramp order.
Order data
source_name required | string unique name of supported fiat currency |
destination_name required | string unique name of supported cryptocurrency |
source_amount required | number amount in fiat currency. If specified, than request should be without 'destination_amount' field |
destination_amount required | number amount in cryptocurrency. If specified, than request should be without 'source_amount' field |
fix_destination | boolean whether the destination can be changed or not |
fix_amount | boolean or null determined if the amount is to be fixed. E. g. if the amount is fixed, and 'source_amount' given than customer can't change the fiat currency amount. |
reference | string or null <= 255 characters a unique identifier used by a merchant |
success_url | string or null <= 1000 characters a web address that redirects customer when the order payment is completed |
company_name | string or null <= 255 characters company name label for current order |
{- "source_name": "eur",
- "destination_name": "bitcoin",
- "source_amount": 101.22,
- "destination_amount": 0.0024156,
- "fix_destination": true,
- "fix_amount": true,
- "reference": "Order #12345",
- "success_url": "https://example.com/success_url",
- "company_name": "Some Company LLC"
}
{- "data": {
- "id": "01JE3EH7GQJ7STDYYTM6FJKVRC",
- "status": "new",
- "invoice_id": "01JE3EH7GQJ7STDYYTM6FJKVRD",
- "request_amount": 100,
- "request_currency": "EUR",
- "payment_currency": "USD",
- "final_amount": 95,
- "crypto_amount": 0.123,
- "gate": "tethererc20",
- "network": "ETH",
- "rate": "0.00012456",
- "success_url": "https://example.com/onramp-success",
- "fixed_gate": true,
- "reference": "Order #12345",
- "company_name": "Some Company LLC"
}
}
This endpoint retrieves a list of onramp orders.
id | string or null Example: id=01JE3EH7FNV96E9T38JYF9YKX8 filters by order identifier |
currency | string or null Example: currency=EUR filters by ticker of fiat currency |
gate | string or null Example: gate=bitcoin filter by specified cryptocurrency |
status | Array of strings or null Enum: "new" "pending" "error" "confirming" "done" Example: status=new status filter |
amount_from | number Example: amount_from=954.12 filters by amount in fiat currency |
amount_to | string <double> Example: amount_to=0.124422 filters by amount in cryptocurrency |
date_from | string or null <date-time> Example: date_from=2023-01-01 00:12:01 filters by creation date from the specified date |
date_to | string or null <date-time> Example: date_to=2023-02-01 15:42:01 filters by creation date up to the specified date |
reference | string or null Example: reference=Order #12345 filters by unique merchant identifier |
limit | integer or null [ 1 .. 500 ] Default: 50 Example: limit=12 sets the number of orders per response |
{- "data": [
- {
- "id": "01JE3EH7GQJ7STDYYTM6FJKVRC",
- "status": "new",
- "invoice_id": "01JE3EH7GQJ7STDYYTM6FJKVRD",
- "request_amount": 100,
- "request_currency": "EUR",
- "payment_currency": "USD",
- "final_amount": 95,
- "crypto_amount": 0.123,
- "gate": "tethererc20",
- "network": "ETH",
- "rate": "0.00012456",
- "success_url": "https://example.com/onramp-success",
- "fixed_gate": true,
- "reference": "Order #12345",
- "company_name": "Some Company LLC"
}
]
}
This endpoint retrieves a specific order by its unique identifier.
orderId required | string order identifier |
{- "data": {
- "id": "01JE3EH7GQJ7STDYYTM6FJKVRC",
- "status": "new",
- "invoice_id": "01JE3EH7GQJ7STDYYTM6FJKVRD",
- "request_amount": 100,
- "request_currency": "EUR",
- "payment_currency": "USD",
- "final_amount": 95,
- "crypto_amount": 0.123,
- "gate": "tethererc20",
- "network": "ETH",
- "rate": "0.00012456",
- "success_url": "https://example.com/onramp-success",
- "fixed_gate": true,
- "reference": "Order #12345",
- "company_name": "Some Company LLC"
}
}
This endpoint allows to get a list of invoices generated through a single payment flow, where the purchased cryptocurrencies are deposited directly into the merchant's balance under the deposit address feature. Using this endpoint, you can retrieve a list of invoices that have been created following the successful purchase of cryptocurrency by your customers.
id | string or null Example: id=01JE3EH7FP05HQC1B40QVXSCZ3 filters by invoice identifier |
created_from | string or null <date-time> Example: created_from=2023-01-01 00:12:01 filters by creation datetime from the specified date |
created_to | string or null <date-time> Example: created_to=2023-02-01 15:42:01 filters by creation datetime up to the specified date |
limit | integer or null [ 1 .. 500 ] Default: 50 Example: limit=12 sets the number of invoices per response |
{- "data": [
- {
- "id": "01JE3EH7GR4F0WKE2979HZ38VW",
- "status": "done",
- "reference": "Order #12345",
- "description": "Payment for goods or services",
- "back_url": "https://example.com/merchant_back_url",
- "success_url": "https://example.com/merchant_success_url",
- "created_at": "2024-12-02T10:26:52.056184Z",
- "expires_at": "2024-12-02T10:41:52.056190Z",
- "invoice_amount": 102.23,
- "invoice_currency": "EUR",
- "price": 101.01,
- "taxes": 20.01,
- "final_amount": 120.02,
- "payment": {
- "gate": "tethererc20",
- "address": "n61udDbLFhOymUSjzIkp8h6wQm9hRVmHwH6fH0GB",
- "memo": "Memo string",
- "txid": [
- "0x9b4480ddub8e21cdc4f3378a113597229c3fe9181513b5fdf520fdc44c47502a"
], - "requested_amount": "107.12",
- "paid_amount": "107.12",
- "currency": "USDT",
- "network": "ETH"
}, - "fees": {
- "network": "0.0003",
- "service": "0.012",
- "total": "0.0123"
}, - "rate": "123.456",
- "onramp_order": {
- "id": "01JE3EH7GQJ7STDYYTM6FJKVRC",
- "status": "new",
- "invoice_id": "01JE3EH7GQJ7STDYYTM6FJKVRD",
- "request_amount": 100,
- "request_currency": "EUR",
- "payment_currency": "USD",
- "final_amount": 95,
- "crypto_amount": 0.123,
- "gate": "tethererc20",
- "network": "ETH",
- "rate": "0.00012456",
- "success_url": "https://example.com/onramp-success",
- "fixed_gate": true,
- "reference": "Order #12345",
- "company_name": "Some Company LLC"
}, - "settings": {
- "service_fee_type": "included",
- "service_fee_percent": 0.99,
- "conversion_fee_type": "included",
- "conversion_fee_percent": 1.5,
- "network_fee_type": "on_top",
- "taxes_type": "inclusive",
- "taxes_rate": 0.12,
- "conversion": {
- "type": "partial",
- "percent": 22.53,
- "gate": "bitcoin"
}, - "autocomplete": true,
- "autocomplete_overpaid": true,
- "underpaid": 0,
- "gates": [
- "bitcoin"
]
}
}
]
}
This endpoint allows to retrieve a specific invoice by its unique identifier (ID) generated through a single payment flow, where the purchased cryptocurrencies are deposited directly into the merchant's balance under the deposit address feature. Using this endpoint, you can obtain detailed information about an invoice by its unique identifier that have been created following the successful purchase of cryptocurrency by your customers. The invoice ID is included in the GET parameters of the page to which your client is redirected after the successful purchase of cryptocurrency.
invoiceId required | string invoice identifier |
{- "data": {
- "id": "01JE3EH7GR4F0WKE2979HZ38VW",
- "status": "done",
- "reference": "Order #12345",
- "description": "Payment for goods or services",
- "back_url": "https://example.com/merchant_back_url",
- "success_url": "https://example.com/merchant_success_url",
- "created_at": "2024-12-02T10:26:52.056184Z",
- "expires_at": "2024-12-02T10:41:52.056190Z",
- "invoice_amount": 102.23,
- "invoice_currency": "EUR",
- "price": 101.01,
- "taxes": 20.01,
- "final_amount": 120.02,
- "payment": {
- "gate": "tethererc20",
- "address": "n61udDbLFhOymUSjzIkp8h6wQm9hRVmHwH6fH0GB",
- "memo": "Memo string",
- "txid": [
- "0x9b4480ddub8e21cdc4f3378a113597229c3fe9181513b5fdf520fdc44c47502a"
], - "requested_amount": "107.12",
- "paid_amount": "107.12",
- "currency": "USDT",
- "network": "ETH"
}, - "fees": {
- "network": "0.0003",
- "service": "0.012",
- "total": "0.0123"
}, - "rate": "123.456",
- "onramp_order": {
- "id": "01JE3EH7GQJ7STDYYTM6FJKVRC",
- "status": "new",
- "invoice_id": "01JE3EH7GQJ7STDYYTM6FJKVRD",
- "request_amount": 100,
- "request_currency": "EUR",
- "payment_currency": "USD",
- "final_amount": 95,
- "crypto_amount": 0.123,
- "gate": "tethererc20",
- "network": "ETH",
- "rate": "0.00012456",
- "success_url": "https://example.com/onramp-success",
- "fixed_gate": true,
- "reference": "Order #12345",
- "company_name": "Some Company LLC"
}, - "settings": {
- "service_fee_type": "included",
- "service_fee_percent": 0.99,
- "conversion_fee_type": "included",
- "conversion_fee_percent": 1.5,
- "network_fee_type": "on_top",
- "taxes_type": "inclusive",
- "taxes_rate": 0.12,
- "conversion": {
- "type": "partial",
- "percent": 22.53,
- "gate": "bitcoin"
}, - "autocomplete": true,
- "autocomplete_overpaid": true,
- "underpaid": 0,
- "gates": [
- "bitcoin"
]
}
}
}