API Docs

Payouts

Payout feature allows merchants to send Bitcoin to any address.

Client will be charged in selected currency using exchange rate at the moment when payout is requested.

When creating a payout, Client can either specify an exact amount of Cryptocurrency (for example BTC) to be send to the destination address, or specify an amount of fiat currency that will be converted using offered exchange rate.

The payouts work as a four steps process:

  1. Get a list of supported currencies
  2. Create payout request - specify how much Client wants to pay out
  3. Receive payout offer - this presents payout offer, which contains exact amounts that will be charged
  4. Approve the offer - after learning how much merchant will be charged, payout can be approved. After the approval, the payout will be queued to be sent. Most payouts are sent in few minutes.

If for some reason you don't want to execute the payout after receiving the offer, you should ignore it.

To avoid exchange rate swings, the payout offer is only valid for a specified amount of time. Approval after expiration time will result in an error.

In case of that please create new payout request, which might use different exchange rate.

Auto-approval

In case API Client wants to skip approval process, Bitclear API provides autoApprove request parameter that can be used for that purpose. Auto-approved payouts are automatically approved during creation and send for processing.

Payout Batching

Bitclear API uses batching to optimize payout sending fees. All payouts approved within short period will be sent as a single cryptocurrency transaction.

As a result if API client requests multiple Payouts to be performed to the single address, Bitclear API will send all Payments as a single cryptocurrency transaction.

Example:

  1. Within 1 minute API Client requests creates 2 Payouts requests:
    a) Payout 1 BTC to address A1
    b) Payout 2 BTC to address A1
  2. API client approves the Payouts
  3. Bitclear API sends 3 BTC to address A1 as a single transaction

Payout states

A payout can be in one of these states:

  • NEW - client had requested a payout, but did not confirm it yet, thus Bitclear API did not send the BTC yet
  • SENT - client had accepted our offer, and Bitclear API sent the BTC to specified address successfully
  • EXPIRED - client had requested a payout, but did not approve it within expiration time, so Bitclear API did not send the outgoing transaction
  • FAILED - client had accepted our offer, but there were some problems while trying to send the money, so the payout was unsuccessful. This should be very rare situation, but if it happens, the user should retry a payout later.
  • QUEUED - client had accepted our offer, and payout has been scheduled to be sent. It will be sent automatically - no further client action is required.

Here is the diagram representing state transitions: Payout state transitions

QUEUED status

Payouts are not executed immediately after the approval - Bitclear API uses queueing mechanism that will send them. In case of any issues, payout will be FAILED and merchant can retry it.

Payout Limits

Bitclear API imposes payout limits, in general, there is a limit for payout defined by merchant balance. The merchant can't do a payout which would be greater than his balance.

To check your limit a request to /v3/payout-limits should be made.

Example response:

{
  "available" : 2.9,
  "minPayoutAmount" : 0.001,
  "currency" : "BTC"
}

The minPayoutAmount is an amount that is related to 20 Euro in asked currency.

To convert limits to specific currency, query parameter should be added: /v3/payout-limits?currency=USD

{
  "available" : 8000,
  "minPayoutAmount" : 10,
  "currency" : "USD"
}

Use cases

The following examples show different approaches to the payout functionality.

In the first one merchant requests an exact amount of Cryptocurreny to be paid out, and the merchant will be charged in selected fiat currency, the fiat amount will be calculated using the current exchange rate.

In the second case merchant knows up front the fiat currency amount and BTC amount is calculated using current exchange rate.

Refund Exact Amount of BTC

A client has paid 0.1 BTC for a product, and he now requests a refund.

Merchant agrees to do the refund and calls our API with the following request:

{
  "transferAmount":0.1,
  "transferCurrency": "BTC",
  "priceCurrency":"USD",
  "address":"2N8hwP1WmJrFF5QWABn38y63uYLhnJYJYTF",
  "comment": "Refund for a purchase of a faulty product",
  "notificationUrl": "https://example.com/payout-callback"
}

In response, API returns the following:

{
  "payoutId": "592cf20b-0174-4b90-b2a4-2e7209a0e3cd",
  "address": "2N8hwP1WmJrFF5QWABn38y63uYLhnJYJYTF",
  "transferAmount": 0.1,
  "transferCurrency": "BTC",
  "priceCurrency": "USD",
  "priceAmount": 111.32,
  "merchantId": "5414d684-2f50-4222-a019-3f01e691f483",
  "comment": "Refund for a purchase of a faulty product",
  "expirationTime": "2018-03-05T12:38:50.246Z",
  "createdTime": "2018-03-05T11:38:50.246Z",
  "status": "NEW"
}

Which means that if merchant approves the payout, there will be a new entry on the USD statement for a fiatTotalAmount = 111.32 for this payout.

If merchant accepts the payout offer before it expires a request to /v3/payouts/approve with the following body must be made:

{
  "payoutId": "55f17894-0f58-44f1-9324-1e0868dd0bb6"
}

In response the API will return the information payout:

{
  "payoutId": "592cf20b-0174-4b90-b2a4-2e7209a0e3cd",
  "address": "2N8hwP1WmJrFF5QWABn38y63uYLhnJYJYTF",
  "transferAmount": 0.1,
  "transferCurrency": "BTC",
  "priceCurrency": "USD",
  "priceAmount": 111.32,
  "merchantId": "5414d684-2f50-4222-a019-3f01e691f483",
  "comment": "Refund for a purchase of a faulty product",
  "expirationTime": "2018-03-05T12:38:50.246Z",
  "createdTime": "2018-03-05T11:38:50.246Z",
  "status": "QUEUED"
}

Send a Specific Amount of Fiat Currency

Merchant wants to pay a contractor an equivalent of 100 USD for the graphic design that was ordered.

Payouts functionality can be used as follows:

{
  "priceAmount": 100,
  "priceCurrency": "USD",
  "transferCurrency": "BTC",
  "address": "2N8hwP1WmJrFF5QWABn38y63uYLhnJYJYTF",
  "comment": "New logo design"
}

In response, API returns the following:

{
  "payoutId": "592cf20b-0174-4b90-b2a4-2e7209a0e3cd",
  "address": "2N8hwP1WmJrFF5QWABn38y63uYLhnJYJYTF",
  "transferAmount":0.099993,
  "transferCurrency": "BTC",
  "priceAmount": 100,
  "priceCurrency": "USD",
  "merchantId": "5414d684-2f50-4222-a019-3f01e691f483",
  "comment": "New logo design",
  "expirationTime": "2018-03-05T12:38:50.246Z",
  "createdTime": "2018-03-05T11:38:50.246Z",
  "status": "NEW"
}

Which means that if merchant approves the payout, there will be a new entry on the USD statement for a fiatTotalAmount = 100 for this payout.

If merchant accepts the payout offer before it expires a request to /v3/payouts/{id}/approve with the empty body.

In response the API will return the information payout confirmation:

{
  "payoutId": "592cf20b-0174-4b90-b2a4-2e7209a0e3cd",
  "address": "2N8hwP1WmJrFF5QWABn38y63uYLhnJYJYTF",
  "transferAmount":0.099993,
  "transferCurrency": "BTC",
  "priceAmount": 100,
  "priceCurrency": "USD",
  "merchantId": "5414d684-2f50-4222-a019-3f01e691f483",
  "comment": "New logo design",
  "expirationTime": "2018-03-05T12:38:50.246Z",
  "createdTime": "2018-03-05T11:38:50.246Z",
  "status": "QUEUED"
}

List Payouts

List of all payouts done by API Client

API endpoint:

/v3/payouts

Full specification