Payouts

Payout feature allows merchants to sent Bitcoin to any address.

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

Depending on the selected currency the payout will appear as an entry on a specific statement as a separate entry.

When creating a payout, merchant can either specify an exact amount of BTC to be send to the destination addres, or specify an amount of fiat currency that will be converted using our exchange rate.

The payouts work as a three step process:

  1. Create payout request - specify how much merchant wants to pay out
  2. Receive payout offer - this presents pay out offer, which contains exact amounts that will be charged
  3. Approve 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 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.

Payout states

A payout can be in one of these states:

  • NEW - client had requested a payout, but did not confirm it yet, thus we did not send the BTC yet
  • SENT - client had accepted our offer and we sent the BTC to specified address successfully
  • EXPIRED - client had requested a payout, but did not approve it within expiration time, so we did not send the money
  • FAILED - client had accepted our offer, but there was 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

And here is the diagram representing state transitions: Payout state transistions

QUEUED status

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

Payout Limits

BPG imposes payout limits, in general there is a daily limit defined in BTC. Payout limits reset every day at 00:00 UTC.

To check your limit a request to /v2/payouts/limit should be made.

Example response:

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

To convert limits to specific currency, query parameter should be added: /v2/payouts/limit?currency=USD

{
  "used" : 4000,
  "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 BTC 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:

{
  "btcAmount":0.1,
  "currency":"USD",
  "address":"2N8hwP1WmJrFF5QWABn38y63uYLhnJYJYTF",
  "comment": "Refund for a purchase of a faulty product"
}

In response we return the following:

{
  "payoutId": "592cf20b-0174-4b90-b2a4-2e7209a0e3cd",
  "address": "2N8hwP1WmJrFF5QWABn38y63uYLhnJYJYTF",
  "btcAmount": 0.1,
  "currency": "USD",
  "fiatAmount": 111.32,
  "fiatTotalAmount": 111.32,
  "merchantId": "5414d684-2f50-4222-a019-3f01e691f483",
  "merchantName": "Marco Polo",
  "comment": "Refund for a purchase of a faulty product",
  "expirationTime": "2018-03-05T12:38:50.246Z",
  "time": "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 /v2/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",
  "btcAmount": 0.1,
  "currency": "USD",
  "fiatAmount": 111.32,
  "fiatTotalAmount": 111.32,
  "merchantId": "5414d684-2f50-4222-a019-3f01e691f483",
  "merchantName": "Marco Polo",
  "comment": "Refund for a purchase of a faulty product",
  "expirationTime": "2018-03-05T12:38:50.246Z",
  "time": "2018-03-05T11:38:50.246Z",
  "btcTxId": "e6e010fc062e68351e3362a8e8a1850c352832b5bf6k8a010e778607460bf59ff",
  "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:

{
  "fiatAmount": 100,
  "currency": "USD",
  "address": "2N8hwP1WmJrFF5QWABn38y63uYLhnJYJYTF",
  "comment": "New logo design"
}

In response we return the following:

{
  "payoutId": "592cf20b-0174-4b90-b2a4-2e7209a0e3cd",
  "address": "2N8hwP1WmJrFF5QWABn38y63uYLhnJYJYTF",
  "btcAmount":0.099993,
  "fiatAmount": 100,
  "fiatTotalAmount": 100,
  "currency": "USD",
  "merchantId": "5414d684-2f50-4222-a019-3f01e691f483",
  "merchantName": "Marco Polo",
  "comment": "New logo design",
  "expirationTime": "2018-03-05T12:38:50.246Z",
  "time": "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 /v2/payouts/approve with the following body must be made:

{
  "payoutId": "592cf20b-0174-4b90-b2a4-2e7209a0e3cd"
}

In response the API will return the information payout confirmation:

{
  "payoutId": "592cf20b-0174-4b90-b2a4-2e7209a0e3cd",
  "address": "2N8hwP1WmJrFF5QWABn38y63uYLhnJYJYTF",
  "btcAmount":0.099993,
  "fiatAmount": 100,
  "fiatTotalAmount": 100,
  "currency": "USD",
  "merchantId": "5414d684-2f50-4222-a019-3f01e691f483",
  "merchantName": "Marco Polo",
  "comment": "New logo design",
  "expirationTime": "2018-03-05T12:38:50.246Z",
  "time": "2018-03-05T11:38:50.246Z",
  "btcTxId": "55a53076df59ac162bf562143ef2a85af0d120118tac793253b461c75b0f8b18",
  "status": "QUEUED"
}

Request Payout Offer

API endpoint:

/v2/payouts

Request type: POST

Example request:

{
  "btcAmount":0.1,
  "currency":"USD",
  "address":"2N8hwP1WmJrFF5QWABn38y63uYLhnJYJYTF",
  "comment": "Refund for a purchase of a faulty product",
  "notificationUrl": "https://example.com/payoutCompleted"
}

Explanation of the fields:

Name Presence Description
btcAmount Optional Amount of BTC you want to send (either btcAmount of fiatAmount must be specified)
fiatAmount Optional Amount of fiat you want to send (either btcAmount of fiatAmount must be specified)
currency Required Currency in which you will be charged. Allowed currencies are: USD, EUR, GBP, AUD, JPY
address Required String containing Bitcoin address to which you want to make a payout
comment Optional Optional comment used to describe the payout
notificationUrl Optional After the payout is sent this URL will be called. See Payout Notification

Example response:

{
  "payoutId": "592cf20b-0174-4b90-b2a4-2e7209a0e3cd",
  "address": "2N8hwP1WmJrFF5QWABn38y63uYLhnJYJYTF",
  "btcAmount":0.099993,
  "fiatAmount": 100,
  "fiatTotalAmount": 100,
  "currency": "USD",
  "merchantId": "5414d684-2f50-4222-a019-3f01e691f483",
  "merchantName": "Marco Polo",
  "comment": "New logo design",
  "expirationTime": "2018-03-05T12:38:50.246Z",
  "time": "2018-03-05T11:38:50.246Z",
  "btcTxId": "55a53076df59ac162bf562143ef2a85af0d120118tac793253b461c75b0f8b18",
  "exchangeRate" : 3299.6271,
  "status": "SENT"
}

Explanation of the fields:

Name Presence Description
payoutId Required Unique identifier of this payout
address Required BTC address of the payout recipient
btcAmount Required How much BTC will be paid out
currency Required Currency in which merchant will be charged
fiatAmount Required The equivalent of the btcAmount in fiat currency
fiatTotalAmount Required How much the merchant will be charged for this payout if it's accepted
merchantId Required Merchant identifier
comment Optional Comment describing the payout
merchantName Required Optional comment used to describe the payout
expirationTime Required The date when the payout offer expires and it won't be possible to approve it after
approvalTime Optional The date when the payout offer was approved
approvedBy Optional User name or API key name that approved the payout
btcTxId Optional Bitcoin transaction id, present only when payout is SENT
exchangeRate Required Exchange rate that is rounded to 4 decimal places.
status Required Status of the payout, one of: [NEW, EXPIRED, SENT, FAILED, QUEUED]

Approve Payout Offfer

API endpoint:

/v2/payouts/approve

Request type: POST

Example request:

{
  "payoutId": "592cf20b-0174-4b90-b2a4-2e7209a0e3cd"
}

Explanation of the fields:

Name Presence Description
payoutId Required Unique identifier of this payout

Example response:

{
  "payoutId": "592cf20b-0174-4b90-b2a4-2e7209a0e3cd",
  "address": "2N8hwP1WmJrFF5QWABn38y63uYLhnJYJYTF",
  "btcAmount":0.099993,
  "fiatAmount": 100,
  "fiatTotalAmount": 100,
  "currency": "USD",
  "merchantId": "5414d684-2f50-4222-a019-3f01e691f483",
  "merchantName": "Marco Polo",
  "comment": "New logo design",
  "expirationTime": "2018-03-05T12:38:50.246Z",
  "time": "2018-03-05T11:38:50.246Z",
  "btcTxId": "55a53076df59ac162bf562143ef2a85af0d120118tac793253b461c75b0f8b18",
  "status": "SENT"
}

Explanation of the fields:

Name Presence Description
payoutId Required Unique identifier of this payout
address Required BTC address of the payout recipient
btcAmount Required How much BTC will be paid out
currency Required Currency in which merchant will be charged
fiatAmount Required The equivalent of the btcAmount in fiat currency
fiatTotalAmount Required How much the merchant will be charged for this payout if it's accepted
merchantId Required Merchant identifier
comment Optional Comment describing the payout
merchantName Required Optional comment used to describe the payout
expirationTime Required The date when the payout offer expires and it won't be possible to approve it after
approvalTime Optional The date when the payout offer was approved
approvedBy Optional User name or API key name that approved the payout
btcTxId Optional Bitcoin transaction id, present only when payout is SENT
status Required Status of the payout, one of: [NEW, EXPIRED, SENT, FAILED, QUEUED]

List Payouts

List of all payouts done by merchant

Request type: GET

API endpoint:

/v2/payouts

Available query parameters

Name Presence Description Type Format
timeFrom Optional Lower bound for time(inclusive) in ISO-8601 format string YYYY-MM-DDThh:mm:ssZ
timeTo Optional Upper bound for time(inclusive) in ISO-8601 format string YYYY-MM-DDThh:mm:ssZ
merchantId Optional Search by merchant ID string
address Optional Search by BTC address string
btcTxId Optional Search by transaction ID from Bitcoin blockchain string
btcAmount Optional Search by BTC amount which was paid out number
fiatTotalAmount Optional Search by total fiat amount number

Example response:

{
    "items": [
        {
            "payoutId": "592cf20b-0174-4b90-b2a4-2e7209a0e3cd",
            "address": "2N8hwP1WmJrFF5QWABn38y63uYLhnJYJYTF",
            "btcAmount": 0.00903587,
            "currency": "USD",
            "fiatAmount": 111.32,
            "fiatTotalAmount": 111.32,
            "merchantId": "5414d684-2f50-4222-a019-3f01e691f483",
            "merchantName": "Marco Polo",
            "comment": "Test payout",
            "expirationTime": "2018-03-05T12:38:50.246Z",
            "approvalTime": "2018-03-05T11:58:50.246Z",
            "approvedBy": "[email protected]",
            "time": "2018-03-05T11:38:50.246Z",
            "btcTxId": "2b4fa89199cd55c957b87120b5d59e73f7357ddb7e74840e5e3a58c100e8db7b",
            "status": "SENT"
        }
    ],
    "paginationInfo": {
        "itemsCount": 1,
        "limit": 20,
        "offset": 0
    }
}

Explanation of the fields:

Name Presence Description Type
items Required Array of payouts array
paginationInfo Required Contains total number of items meeting specified criteria and selected limit and offset object

Each item has following format:

Name Presence Description
payoutId Required Unique identifier of this payout
address Required BTC address of the payout recipient
btcAmount Required How much BTC will be paid out
currency Required Currency in which merchant will be charged
fiatAmount Required The equivalent of the btcAmount in fiat currency
fiatTotalAmount Required How much the merchant will be charged for this payout if it's accepted
merchantId Required Merchant identifier
comment Optional Comment describing the payout
merchantName Required Optional comment used to describe the payout
expirationTime Required The date when the payout offer expires and it won't be possible to approve it after
approvalTime Optional The date when the payout offer was approved
approvedBy Optional User name or API key name that approved the payout
btcTxId Optional Bitcoin transaction id, present only when payout is SENT
status Required Status of the payout, one of: [NEW, EXPIRED, SENT, FAILED]