NAV Navbar
cURL C# Java PHP Node.js Go Python Ruby

REST API

Overview

BitPay provides a standards-based REST interface which enables application developers to interact in a powerful, yet secure way with their BitPay account. Using the BitPay API, clients can create and manage invoices, issue refunds, manage bills, retrieve real-time rates information, view merchant ledger entries, and much more. Developers may call the API directly over HTTPS using the language of their choice, or take advantage of one of BitPay's code libraries (Java, C#, PHP etc).

Concepts

Api Contracts

BitPay considers the following types of API changes to be non-breaking and backwards-compatible:

Identities

Authentication in BitPay's API utilizes a specialized identification scheme, BitAuth Identity Protocol. Every Identity is represented in public form as a Client ID, which much like the Bitcoin protocol, is simply a hash of the identity's public key. For your convenience, all of BitPay's Client Libraries support this functionality.

API Tokens

Authorization in BitPay's API utilizes Capability-based Security principles. Each API call must be accompanied by an API Token which grants access to the requested capability. API Tokens are analagous to a real-world event ticket, which grants access to a specific event when presented at the door. Also like tickets, they may grant broad or narrow privileges (e.g. 'General Admission' vs. 'Seat 44B') as well as add bearer requirements (e.g. 'Must be over 21' or 'Non-transferrable, must show ID').

New tokens are provided with each response from the API. For example, creating a new Invoice with one token will provide a new, second token that grants access to view and interact with that Invoice exclusively. If not using BitPay's Client Libraries, you will need to keep track of these tokens on your own.

Facades

Facades named collections of capabilities that can be granted, such as the ability to create invoices or grant refunds. In the ticket analogy, this corresponds to the ticket 'level', where a 'VIP' ticket would confer broader access than a 'Standard' level ticket. When registering an Identity, it is against a specific facade. Best practices suggest that the requested facade should be limited to the minimum level that grants the required capabilities.

Facade Capabilities Description
public The implicit facade applied when no token is provided. Provides access to public methods for generating merchant applications, generating and claiming tokens, or checking exchange rates.
pos Limited to creating new invoice or bills and search specific invoices or bills based on their id for the merchant's organization
merchant The broadest set of capabilities against a merchant organization. Allows for create, search, and view actions for Invoices and Bills; ledger download, as well as the creation of new merchant or pos tokens associated with the account.
payroll This is the facade which allows merchant to access the /payouts resource and the corresponding endpoints

Getting Access

To use any non-public facade a token will need to be sent with the API request. Tokens can require authentication, which would requiring cryptographically signing each request. You can either generate a token directly from an API client or via the My Account -> API Tokens page. To receive a token directly from an API client, send a POST request to bitpay.com/tokens with the following query parameters:

This will respond with a new token that will include a pairingCode. This pairing code can then be shared with a merchant organization administrator to approve access. This can be done by visiting My Account -> API Tokens and entering the pairing code, or by visiting the url format: bitpay.com/api-access-request?pairingCode=<pairingcode_goes_here>.

Alternatively, pairing codes can be generated directly at My Account -> API Tokens, and can then be claimed by API clients which associates a Client ID with the token, and will activate it for further usage. To claim a token from an API client, send a POST request to bitpay.com/tokens with the following parameters:

A token without a Client ID authentication restriction can be made, and a token can then be copied directly to make API calls, such as creating invoices.

Making Requests

Requests to the BitPay REST API follow a RESTful convention using standard HTTP verbs against various BitPay resources to return JSON formatted responses. Once again the mechanics of this exchange may be simplified through the use of one of the BitPay libraries.

Each request should include in the HTTP headers:

To make an API request send an HTTP request with a HTTP method to a resource URI and include in the body JSON parameters of the following (plus any additional parameters needed):

For more information about specific resource URIs, please visit the resource documentation.

Signing your request

The x-signature HTTP header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key. So if you are sending a request to:

https://bitpay.com/invoices

And your request body is:

{"price":500,"currency":"USD","token":"GcAUe7hgY3F2FSh95Dsy5d"}

The string you will sign is:

https://bitpay.com/invoices{"price":500,"currency":"USD","token":"GcAUe7hgY3F2FSh95Dsy5d"}

The result should be included as the value of the x-signature request header.

Cross-Origin Resource Sharing

The BitPay REST API supports CORS, so that you may send requests directly from the client, however remember to never expose your private key. If your key becomes compromised, you will want to disable your old Client ID and register a new one.

Resources

Tokens

Resource

Tokens are API access identifiers which are associated with a set of capabilities. A capability may be very broad, for example, retrieve the list of all exchange rates. Or a capability may be very specific, for example, refund invoice RhHwkycGaDskrEhGfXWnRG.

Name Type returned via facade
public merchant
data array
policies object
policy
Can be "sin", "access", "events", "id", or "session"
string
method
Can be "requireSin", "requireFacadeAccess", "allowEventStream", "invalidated", "inactive", "unclaimed", "requireSession"
string
params
Can be "support", SIN value, or null
array
resource
Token identifier. This field can be ignored in merchant implementations.
string
token
API token for token resource
string
facade
Can be "merchant", "pos" or "payroll"
string
dateCreated
UNIX time of creation, in milliseconds
string
pairingExpiration
UNIX time of expiration, in milliseconds
number
pairingCode
Access approval code. To be validated via the BitPay dashboard in order to activate the token returned in the same payload.
string

Request an API token

POST
https://bitpay.com/tokens
Facades

public merchant

HTTP Request

via the public facade (unsigned requests)

curl -X POST -H "x-accept-version: 2.0.0" -H "content-type: application/json" -d '{"id":"TfALHhgU5duM4PAtFWgNqNgYZkLhfwnf2Tj","facade":"merchant"}' "https://test.bitpay.com/tokens"
var resourceUrl = "https://test.bitpay.com/tokens";

var httpWebRequest = (System.Net.HttpWebRequest)System.Net.WebRequest.Create(resourceUrl);
httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "POST";

string json = "{" +
                  "\"id\": \"TfALHhgU5duM4PAtFWgNqNgYZkLhfwnf2Tj\"," +
                  "\"facade\": \"merchant\"" +
              "}";

using (var streamWriter = new System.IO.StreamWriter(httpWebRequest.GetRequestStream()))
{
    streamWriter.Write(json);
    streamWriter.Flush();
    streamWriter.Close();
}

var httpResponse = (System.Net.HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new System.IO.StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/tokens";
var json = "{" +
               "\"id\": \"TfALHhgU5duM4PAtFWgNqNgYZkLhfwnf2Tj\"," +
               "\"facade\": \"merchant\"" +
           "}";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .uri(URI.create(resourceUrl))
   .POST(HttpRequest.BodyPublishers.ofString(json))
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/tokens';

$postData = json_encode([
   'id' => 'TfALHhgU5duM4PAtFWgNqNgYZkLhfwnf2Tj',
   'facade' => 'merchant'
]);

$curlCli = curl_init($resourceUrl);

curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json'
]);

curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curlCli, CURLOPT_POSTFIELDS, stripslashes($postData));

$result = curl_exec($curlCli);
$resultData = json_decode($result, TRUE);
curl_close($curlCli);

echo $resultData;

?>
let request = require('request');

let resource_url = 'https://test.bitpay.com/tokens';
let post_data = {
   "id": "TfALHhgU5duM4PAtFWgNqNgYZkLhfwnf2Tj",
   "facade": "merchant"
};
let headers = {"x-accept-version": "2.0.0", "Content-type": "application/json"};
let options = {
   url: resource_url,
   method: 'POST',
   json: post_data,
   headers: headers
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/tokens"
postData := []byte(`{
   "id": "TfALHhgU5duM4PAtFWgNqNgYZkLhfwnf2Tj",
   "facade": "merchant"
 }`)

request, err := http.NewRequest("POST", resourceUrl, bytes.NewBuffer(postData))
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}
defer response.Body.Close()

body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/tokens'
post_data = {
   'id': 'TfALHhgU5duM4PAtFWgNqNgYZkLhfwnf2Tj',
   'facade': 'merchant'
}
headers = {'x-accept-version': '2.0.0', 'Content-type': 'application/json'}
response = requests.post(url=resource_url, data=json.dumps(post_data), headers=headers).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/tokens"
post_data = {
 "id": "TfALHhgU5duM4PAtFWgNqNgYZkLhfwnf2Tj",
 "facade": "merchant"
}
headers = {"x-accept-version": "2.0.0", "Content-type": "application/json"}
uri = URI.parse(resource_url)
request = Net::HTTP::Post.new(uri.to_s, headers)
request.body = post_data.to_json

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body
Headers
Fields Presence
x-accept-version:
must be set to 2.0.0 for requests to the BitPay API
M
content-type
must be set to application/json for requests to the BitPay API
M
x-identity
the hexadecimal public key generated from the client private key. This header is optional for this endpoint when using the public facade, and required when using a merchant facade token.
C
x-signature
header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key. This header is optional for this endpoint when using the public facade, and required when using a merchant facade token.
C
Body
Parameter Type Presence
id
Client identity based on BitAuth identity protocol, also known as SIN (System Identification Number)
string M
facade
Can be merchant, pos or payroll. If passed in the body of the request together with the id parameter, leave the pairingCode parameter out.
string C
label
Token label, may include spaces, underscores, and dashes
string O
pairingCode
Access approval code:

  • Client Initiated Pairing: If you do not pass a pairing code in the body of the request, you need to send the id and facade parameters. This will allow you to request API tokens with higher privileges (merchant, or payroll facades)
  • Server Initiated Pairing: If you pass a pairing code in the body of the request, leave the facade parameter out. The pairing code which can be generated from the BitPay dashboard (with "Require Authentication" enabled) only allows you to request a pos facade token with authentication, meaning it will be necessary to cryptographically sign every request using this token, just like the other facades with higher privileges.

string C
HTTP Response
{
  "data": [
    {
      "policies": [
        {
          "policy": "id",
          "method": "inactive",
          "params": [
            "TfALHhgU5duM4PAtFWgNqNgYZkLhfwnf2Tj"
          ]
        }
      ],
      "token": "6cPAzk6jdcsLQPwoB4cn8J",
      "facade": "merchant",
      "dateCreated": 1558525586681,
      "pairingExpiration": 1558611986681,
      "pairingCode": "ZHcXiqX"
    }
  ]
}

On the right side, you will find an example of the token object returned in the response you will get from the BitPay server. A description of each field is available in the Tokens resource section.

Invoices

Resource

Example of invoice resource (fetched using the merchant facade)

{
  "facade": "merchant/invoice",
  "data": {
    "url": "https://test.bitpay.com/invoice?id=RhHwkycGaDskrEhGfXWnRG",
    "posData":"\"{ \"ref\" : 711454, \"item\" : \"test_item\" }\"",
    "status": "complete",
    "price": 60.61,
    "currency": "USD",
    "itemDesc": "Item XYZ",
    "orderId": "test-abc",
    "invoiceTime": 1556804235791,
    "expirationTime": 1556805135791,
    "currentTime": 1559297397907,
    "id": "RhHwkycGaDskrEhGfXWnRG",
    "lowFeeDetected": false,
    "amountPaid": 1132400,
    "exceptionStatus": false,
    "targetConfirmations": 6,
    "transactions": [
      {
        "amount": 1132400,
        "confirmations": 6,
        "receivedTime": "2019-05-02T13:37:30.431Z",
        "txid": "5cf78d4351f65ef852f757f511ad91bfce1944afe96544b4b9560a1456374e34",
        "exRates": {
          "BTC": 1,
          "USD": 5353.21,
          "BCH": 20.04947565543071
        },
        "outputIndex": 0
      },
      {
        "amount": -200,
        "confirmations": 6,
        "receivedTime": "2019-05-02T13:37:30.431Z",
        "type": "buyerPaidMinerFee",
        "txid": "5cf78d4351f65ef852f757f511ad91bfce1944afe96544b4b9560a1456374e34"
      },
      {
        "amount": -1060900,
        "confirmations": 6,
        "time": "2019-05-03T15:57:11.925Z",
        "receivedTime": "2019-05-03T15:57:11.925Z",
        "type": "refundFromLedger",
        "txid": "edc80538322d9f8215a0f1e8b20d56b0407488f0b0d7444290a9f6b8207be0e7",
        "refundAmount": -1060900,
        "exRates": {
          "BTC": 1,
          "USD": 5713.250000000001,
          "BCH": 19.87217391304348
        }
      }
    ],
    "buyer": {
      "address1": "2630 Hegal Place, Apt 42",
      "address2": "Apt 42",
      "locality": "Alexandria",
      "region": "Virginia",
      "postalCode": "23242",
      "email": "fox.mulder@trustno.one"
    },
    "refundAddresses": [
      {
        "mo1HjNzzxnPdyEmFGU52onfNoe455Eo8uA": {
          "type": "buyerSupplied",
          "date": "2019-05-03T15:53:20.970Z"
        }
      }
    ],
    "refundAddressRequestPending": false,
    "buyerProvidedEmail": "fox.mulder@trustno.one",
    "buyerProvidedInfo": {
      "selectedTransactionCurrency": "BTC",
      "emailAddress": "fox.mulder@trustno.one"
    },
    "paymentSubtotals": {
      "BTC": 1132200,
      "BCH": 22708900
    },
    "paymentTotals": {
      "BTC": 1132400,
      "BCH": 22708900
    },
    "paymentDisplayTotals": {
      "BTC": "0.011324",
      "BCH": "0.227089"
    },
    "paymentDisplaySubTotals": {
      "BTC": "0.011322",
      "BCH": "0.227089"
    },
    "exchangeRates": {
      "BTC": {
        "USD": 5353.21,
        "BCH": 20.04947565543071
      },
      "BCH": {
        "USD": 266.9,
        "BTC": 0.049845923989167984
      }
    },
    "minerFees": {
      "BTC": {
        "satoshisPerByte": 1.02,
        "totalFee": 200
      },
      "BCH": {
        "satoshisPerByte": 0,
        "totalFee": 0
      }
    },
    "shopper": { 
      "user": "37SysActbPgLYfn9QJh8AB"
    },
    "billId": "DrUSEQ6phH9V31t8Xqydi6",
    "refundInfo": [
      {
        "supportRequest": "BpRciwDGMXYR4kDPynsaRA",
        "currency": "USD",
        "amounts": {
          "USD": 60.61,
          "BTC": 0.010609
        }
      }
    ],
    "transactionCurrency": "BTC",
    "supportedTransactionCurrencies": {
      "BTC": {
        "enabled": true
      },
      "BCH": {
        "enabled": true
      }
    },
    "paymentCodes": {
      "BTC": {
        "BIP72b": "bitcoin:?r=https://test.bitpay.com/i/RhHwkycGaDskrEhGfXWnRG",
        "BIP73": "https://test.bitpay.com/i/RhHwkycGaDskrEhGfXWnRG"
      },
      "BCH": {
        "BIP72b": "bitcoincash:?r=https://test.bitpay.com/i/RhHwkycGaDskrEhGfXWnRG",
        "BIP73": "https://test.bitpay.com/i/RhHwkycGaDskrEhGfXWnRG"
      }
    },
    "token": "5z1h2xr2RRrxrZf3k7SScizDGeDj4VZ8Xi8MHqKopdj1xH2zqrSBKVHtEdEUYAARQT"
  }
}

Invoices are time-sensitive payment requests addressed to specific buyers. An invoice has a fixed price, typically denominated in fiat currency. It also has an equivalent price in the supported cryptocurrencies, calculated by BitPay, at a locked exchange rate with an expiration time of 15 minutes.

Name Type returned via facade
public pos merchant
facade
This field indicates the facade from which the invoice is being requested:

  • "public/invoice" if the public facade is used to request an invoice resource
  • "pos/invoice" if the pos facade is used to request an invoice resource
  • "merchant/invoice" if the merchant facade is used to request an invoice resource

string
data
Invoice data object. The following fields from the initial POST request will be passed in the response from the server, in addition to some other fields listed in this section
object
url
Web address of invoice, expires at expirationTime
string
posData
A passthru variable provided by the merchant and designed to be used by the merchant to correlate the invoice with an order or other object in their system. This passthru variable can be a serialized object, e.g.: "posData": "\"{ \"ref\" : 711454, \"item\" : \"test_item\" }\"".
string
status
Invoice status, can have the following values:

  • "new": An invoice starts in this state. When in this state and only in this state, payments broadcasted by purchasers will be applied to the invoice (there is a 15 minute window for the purchaser to send a payment from their crypto wallet). If an invoice has received a partial payment, it will still reflect a status of new to the merchant. From a merchant system perspective, an invoice is either paid or not paid, partial payments are automatically refunded by BitPay to the consumer.
  • "paid" As soon as payment is received it is evaluated against the invoice requested amount. If the amount paid is equal to or greater than the amount expected then the invoice is marked as being paid. To detect whether the invoice has been overpaid consult the invoice exception status (exceptionStatus parameter). The overpaid amount on an invoice is automatically refunded by BitPay to the consumer.
  • "confirmed": This is the invoice status to be monitored by merchants in order to fulfil orders placed by the consumer. Merchants can configure the timing at which BitPay sets this specific invoice status, depending on the number of confirmation achieved by the consumer's transaction in the selected cryptocurrency. This can be configured during invoice creation using the transactionSpeed parameter (section Create an invoice), or at account level via a dashboard setting.
  • "complete": When an invoice has the status complete, it means that BitPay has credited the merchant account, in the currency indicated in the settlement settings. For instance, with invoices paid in Bitcoin (BTC), 6 confirmation blocks on the bitcoin network are required for an invoice to be complete, this takes on average 1 hour.
  • "expired": An invoice reaches the expired status if no payment was received and the 15 minute payment window has elapsed.
  • "invalid" An invoice is considered invalid when it was paid, but the corresponding cryptocurrency transaction was not confirmed within 1 hour on the corresponding blockchain. It is possible that some transactions can take longer than 1 hour to be included in a block. If the transaction confirms after 1 hour, BitPay will update the invoice state from invalid to confirmed or complete (6 confirmations for transactions on the bitcoin network for instance).

string
price
Fixed price amount for the checkout, in the "currency" of the invoice object.
number
currency
ISO 4217 3-character currency code. This is the currency associated with the price field, supported currencies are available via the Currencies resource
string
itemDesc
Invoice description - will be added as a line item on the BitPay checkout page, under the merchant name.
string
orderId
Can be used by the merchant to assign their own internal Id to an invoice. If used, there should be a direct match between an orderId and an invoice id.
string
invoiceTime
UNIX time of invoice creation, in milliseconds
number
expirationTime
UNIX time when invoice is last available to be paid, in milliseconds
number
currentTime
UNIX time of API call, in milliseconds
number
id
Invoice resource id
string
lowFeeDetected
Flag to indicate if the miner fee used by the buyer is too low. Initially set to false when the invoice is created.
boolean
amountPaid
The total amount paid to the invoice in terms of the invoice transactionCurrency indicated in the smallest possible unit for the corresponding transactionCurrency (e.g satoshis for BTC and BCH. Initially set to 0 when creating the invoice
number
exceptionStatus
Initially a boolean false, this parameter will indicate if the purchaser sent too much ("paidOver") or not enough funds ("paidPartial") in the transaction to pay the BitPay invoice. Possible values are

  • false: default value (boolean) unless an exception is triggered.
  • "paidPartial": (string) if the consumer did not send enough funds when paying the invoice.
  • "paidOver": (string) if the consumer sent to much funds when paying the invoice.

boolean | string
targetConfirmations
Indicates the number of block confirmation of the crypto currency transaction which are required to credit a paid invoice to the merchant accoun. Currently the value set is set to 6 by default as the supported cryptocurrencies are BTC and BCH
number
transactions
Initially empty when the invoice is created. This array will be populated with the crypto currency linked to the invoice. For instance the consumer's transaction if the invoice is paid, but also the refund transaction if you decide to issue a refundn to the purchaser
array
buyer
Allows merchant to pass buyer related information in the invoice object
object
name
Buyer's name
string
address1
Buyer's address
string
address2
Buyer's appartment or suite number
string
locality
Buyer's city or locality
string
region
Buyer's state or province
string
postalCode
Buyer's Zip or Postal Code
string
country
Buyer's Country code. Format ISO 3166-1 alpha-2
string
email
Buyer's email address. If provided during invoice creation, this will bypass the email prompt for the consumer when opening the invoice.
string
phone
Buyer's phone number
string
notify
Indicates whether a BitPay email confirmation should be sent to the buyer once he has paid the invoice
boolean
redirectURL
URL to redirect the shopper back to your website after a successful purchase. Be sure to include "http://" or "https://" in the url.
string
refundAddresses
Initially empty when the invoice is created. This field will be populated with the refund address provided by the customer if you request a refund of the specific invoice.
array
refundAddressRequestPending
Initially set to false when the invoice is created, this field will be set to true once a refund request has been issued by the merchant. This flag is here to indicate that the refund request is pending action from the buyer to provide an address for the refund, via the secure link which has been automatically emailed to him
boolean
buyerProvidedEmail
Populated with the buyer's email address if passed in the buyer object by the merchant, otherwise this field is not returned for newly created invoices. If the merchant does not pass the buyer email in the invoice request, the bitpay invoice UI will prompt the user to enter his email address and this field will be populated with the email submitted.
string
buyerProvidedInfo
Information collected from the buyer during the process of paying an invoice. Initially this object is empty.
object
name
Populated with the buyer's name address if passed in the buyer object by the merchant
string
phoneNumber
Populated with the buyer's phone number if passed in the buyer object by the merchant
string
selectedTransactionCurrency
This field will be populated with the cryptocurrency selected to pay the BitPay invoice, current supported values are BTC and BCH. If not yet selected, this field will not be returned
string
emailAddress
populated with the buyer's email address if passed in the buyer object, otherwise this field is not returned in the response.
string
paymentSubtotals
Equivalent to price for each supported transactionCurrency, excluding minerFees.The key is the currency and the value is an amount indicated in the smallest possible unit for each supported transactionCurrency (e.g satoshis for BTC and BCH).
object
paymentTotals
The total amount that the purchaser should pay. This is like paymentSubtotals but with the minerFees included. The key is the currency and the value is an amount indicated in the smallest possible unit for each supported transactionCurrency (e.g satoshis for BTC and BCH).
object
paymentDisplayTotals
The total amount that the purchaser should pay as displayed on the invoice UI. This is like paymentSubtotals but with the minerFees included. The key is the currency and the value is an amount indicated in the base unit for each supported transactionCurrency (thus BTC or BCH).
object
paymentDisplaySubTotals
Equivalent to price for each supported transactionCurrency, excluding minerFees. The key is the currency and the value is an amount indicated in the base unit for each supported transactionCurrency (thus BTC or BCH).
object
exchangeRates
Exchange rates keyed by source and target currencies.
object
minerFees
The total amount of fees that the purchaser will pay to cover BitPay's UTXO sweep cost for an invoice. The key is the currency and the value is an amount in satoshis. This is referenced as "Network Cost" on an invoice, see this support article for more information
.
object
shopper
This object will be available on the invoice if a shopper signs in on an invoice using his BitPay ID. See the following blogpost for more information
.
object
user
If a shopper signs in on the invoice using his BitPay ID, this field will contain the unique ID assigned by BitPay to this shopper.
.
string
billId
This field will be in the invoice object only if the invoice was generated from a bill, see the Bills resource for more information
string
refundInfo
For a refunded invoice, this object will contain the details of executed refunds for the corresponding invoice.
object
supportRequest
For a refunded invoice, this field will contain the refund requestId once executed.
string
currency
For a refunded invoice, this field will contain the base currency selected for the refund. Typically the same as the invoice currency.
string
amounts
For a refunded invoice, this object will contain the crypto currency amount refunded by BitPay to the consumer (in the selected transactionCurrency) and the equivalent refunded amount from the invoice in the given currency (thus linked to the amount debited from the merchant account to cover the refund)
object
transactionCurrency
The cryptocurrency used to pay the invoice. This field will only be available after a transaction is applied to the invoice. Possible values are currently "BTC" or "BCH".
string
supportedTransactionCurrencies
The currencies that may be used to pay this invoice. The object is keyed by currency code. The values are objects with an "enabled" boolean. If a cryptocurrency is disabled on a specific invoice, an extra "reason" parameter is added in the object.
object
paymentCodes
The URIs for sending a transaction to the invoice. The first key is the transaction currency. The transaction currency maps to an object containing the payment URIs. The key of this object is the BIP number and the value is the payment URI. BIP72b and BIP73 are supported.
object
token
invoice resource token. This token is derived from the API token initially used to create the invoice and is tied to the specific resource id created.
string

Create an invoice

POST
https://bitpay.com/invoices
Facades

pos merchant

HTTP Request

via the pos facade (unsigned requests)

curl -X POST -H "x-accept-version: 2.0.0" -H "content-type: application/json" -d '{"currency":"USD","price":5,"orderId":"MerchantOrder123","fullNotifications":true,"extendedNotifications":true,"transactionSpeed":"medium","notificationURL":"https://yournotificationurl.com","notificationEmail":"merchant@email.com","redirectURL":"https://yourredirecturl.com","buyer":{"email":"fox.mulder@trustno.one","name":"Fox Mulder","phone":"555-123-456","address1":"2630 Hegal Place","address2":"Apt 42","locality":"Alexandria","region":"VA","postalCode":"23242","country":"US","notify":true},"itemDesc":"Item XYZ","token":"Tqi5NhskgZHW3ZUv6y1AZg"}' "https://test.bitpay.com/invoices"
var resourceUrl = "https://test.bitpay.com/invoices";

var httpWebRequest = (HttpWebRequest)WebRequest.Create(resourceUrl);

httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "POST";

string json = "{" +
    "\"currency\":\"USD\"," +
    "\"price\":5," +
    "\"orderId\":\"MerchantOrder123\"," +
    "\"fullNotifications\":true," +
    "\"extendedNotifications\":true," +
    "\"transactionSpeed\":\"medium\"," +
    "\"notificationURL\":\"https://yournotificationurl.com\"," +
    "\"notificationEmail\":\"merchant@email.com\"," +
    "\"redirectURL\":\"https://yourredirecturl.com\"," +
    "\"buyer\":{" +
        "\"email\":\"fox.mulder@trustno.one\"," +
        "\"name\":\"Fox Mulder\"," +
        "\"phone\":\"555-123-456\"," +
        "\"address1\":\"2630 Hegal Place\"," +
        "\"address2\":\"Apt 42\"," +
        "\"locality\":\"Alexandria\"," +
        "\"region\":\"VA\"," +
        "\"postalCode\":\"23242\"," +
        "\"country\":\"US\"," +
        "\"notify\":true" +
    "}," +
    "\"itemDesc\":\"Item XYZ\"," +
    "\"token\":\"Tqi5NhskgZHW3ZUv6y1AZg\"" +
"}";
"\"itemDesc\":\"Item XYZ\"," +
"\"token\":\"Tqi5NhskgZHW3ZUv6y1AZg\"" +
"}";

using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
{
    streamWriter.Write(json);
    streamWriter.Flush();
    streamWriter.Close();
}

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/invoices";
var json = "{" +
             "\"currency\":\"USD\"," +
             "\"price\":5," +
             "\"orderId\":\"MerchantOrder123\"," +
             "\"fullNotifications\":true," +
             "\"extendedNotifications\":true," +
             "\"transactionSpeed\":\"medium\"," +
             "\"notificationURL\":\"https://yournotificationurl.com\"," +
             "\"notificationEmail\":\"merchant@email.com\"," +
             "\"redirectURL\":\"https://yourredirecturl.com\"," +
             "\"buyer\":{" +
                 "\"email\":\"fox.mulder@trustno.one\"," +
                 "\"name\":\"Fox Mulder\"," +
                 "\"phone\":\"555-123-456\"," +
                 "\"address1\":\"2630 Hegal Place\"," +
                 "\"address2\":\"Apt 42\"," +
                 "\"locality\":\"Alexandria\"," +
                 "\"region\":\"VA\"," +
                 "\"postalCode\":\"23242\"," +
                 "\"country\":\"US\"," +
                 "\"notify\":true" +
             "}," +
             "\"itemDesc\":\"Item XYZ\"," +
             "\"token\":\"Tqi5NhskgZHW3ZUv6y1AZg\"" +
         "}";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request=HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .uri(URI.create(resourceUrl))
   .POST(HttpRequest.BodyPublishers.ofString(json))
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/invoices';

$postData = json_encode([
   'currency' => 'USD',
   'price' => 5,
   'orderId' => 'MerchantOrder123',
   'fullNotifications' => true,
   'extendedNotifications' => true,
   'transactionSpeed' => 'medium',
   'notificationURL' => 'https://yournotificationurl.com',
   'notificationEmail' => 'merchant@email.com',
   'redirectURL' => 'https://yourredirecturl.com',
   'buyer' => [
       'email' => 'fox.mulder@trustno.one',
       'name' => 'Fox Mulder',
       'phone' => '555-123-456',
       'address1' => '2630 Hegal Place',
       'address2' => 'Apt 42',
       'locality' => 'Alexandria',
       'region' => 'VA',
       'postalCode' => '23242',
       'country' => 'US',
       'notify' => true
   ],
   'itemDesc' => 'Item XYZ',
   'token' => 'Tqi5NhskgZHW3ZUv6y1AZg'
]);

$curlCli = curl_init($resourceUrl);

curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json'
]);

curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curlCli, CURLOPT_POSTFIELDS, stripslashes($postData));

$result = curl_exec($curlCli);
$resultData = json_decode($result, TRUE);
curl_close($curlCli);

echo $resultData;

?>
let request = require('request');

let resource_url = 'https://test.bitpay.com/invoices';
let post_data = {
   "currency": "USD",
   "price": 5,
   "orderId": "MerchantOrder123",
   "fullNotifications": true,
   "extendedNotifications": true,
   "transactionSpeed": "medium",
   "notificationURL": "https://yournotificationurl.com",
   "notificationEmail": "merchant@email.com",
   "redirectURL": "https://yourredirecturl.com",
   "buyer": {
       "email": "fox.mulder@trustno.one",
       "name": "Fox Mulder",
       "phone": "555-123-456",
       "address1": "2630 Hegal Place",
       "address2": "Apt 42",
       "locality": "Alexandria",
       "region": "VA",
       "postalCode": "23242",
       "country": "US",
       "notify": true
   },
   "itemDesc": "Item XYZ",
   "token": "Tqi5NhskgZHW3ZUv6y1AZg"
};
let headers = {"x-accept-version": "2.0.0", "Content-type": "application/json"};
let options = {
   url: resource_url,
   method: 'POST',
   json: post_data,
   headers: headers
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/invoices"
postData := []byte(`{
     "currency": "USD",
     "price": 5,
     "orderId": "MerchantOrder123",
     "fullNotifications": true,
     "extendedNotifications": true,
     "transactionSpeed": "medium",
     "notificationURL": "https://yournotificationurl.com",
     "notificationEmail": "merchant@email.com",
     "redirectURL": "https://yourredirecturl.com",
     "buyer": {
         "email": "fox.mulder@trustno.one",
         "name": "Fox Mulder",
         "phone": "555-123-456",
         "address1": "2630 Hegal Place",
         "address2": "Apt 42",
         "locality": "Alexandria",
         "region": "VA",
         "postalCode": "23242",
         "country": "US",
         "notify": true
     },
     "itemDesc": "Item XYZ",
     "token": "Tqi5NhskgZHW3ZUv6y1AZg"
 }`)

request, err := http.NewRequest("POST", resourceUrl, bytes.NewBuffer(postData))
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}
defer response.Body.Close()

body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/invoices'
post_data = {
   'currency': 'USD',
   'price': 5,
   'orderId': 'MerchantOrder123',
   'fullNotifications': True,
   'extendedNotifications': True,
   'transactionSpeed': 'medium',
   'notificationURL': 'https://yournotificationurl.com',
   'notificationEmail': 'merchant@email.com',
   'redirectURL': 'https://yourredirecturl.com',
   'buyer': {
       'email': 'fox.mulder@trustno.one',
       'name': 'Fox Mulder',
       'phone': '555-123-456',
       'address1': '2630 Hegal Place',
       'address2': 'Apt 42',
       'locality': 'Alexandria',
       'region': 'VA',
       'postalCode': '23242',
       'country': 'US',
       'notify': True
   },
   'itemDesc': 'Item XYZ',
   'token': 'Tqi5NhskgZHW3ZUv6y1AZg'
}
headers = {'x-accept-version': '2.0.0', 'Content-type': 'application/json'}
response = requests.post(url=resource_url, data=json.dumps(post_data), headers=headers).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/invoices"
post_data = {
   "currency": "USD",
   "price": 5,
   "orderId": "MerchantOrder123",
   "fullNotifications": true,
   "extendedNotifications": true,
   "transactionSpeed": "medium",
   "notificationURL": "https://yournotificationurl.com",
   "notificationEmail": "merchant@email.com",
   "redirectURL": "https://yourredirecturl.com",
   "buyer": {
       "email": "fox.mulder@trustno.one",
       "name": "Fox Mulder",
       "phone": "555-123-456",
       "address1": "2630 Hegal Place",
       "address2": "Apt 42",
       "locality": "Alexandria",
       "region": "VA",
       "postalCode": "23242",
       "country": "US",
       "notify": true
   },
   "itemDesc": "Item XYZ",
   "token": "Tqi5NhskgZHW3ZUv6y1AZg"
}
headers = {"x-accept-version": "2.0.0", "Content-type": "application/json"}
uri = URI.parse(resource_url)
request = Net::HTTP::Post.new(uri.to_s, headers)
request.body = post_data.to_json

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body

via the merchant facade (signed requests)

curl -X POST -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572" -H "x-signature: 30460221008184d6cea3c7d1ed6cf7e49e593bfa497b9d15ed5fd63a07e33ee61f66652d81022100f6462521d26f2362b5cac64523121691b529fda8c33874f9c70cae56b6d00396" -d '{"currency":"USD","price":5,"orderId":"MerchantOrder123","fullNotifications":true,"extendedNotifications":true,"transactionSpeed":"medium","notificationURL":"https://yournotificationurl.com","notificationEmail":"merchant@email.com","redirectURL":"https://yourredirecturl.com","buyer":{"email":"fox.mulder@trustno.one","name":"Fox Mulder","phone":"555-123-456","address1":"2630 Hegal Place","address2":"Apt 42","locality":"Alexandria","region":"VA","postalCode":"23242","country":"US","notify":true},"posData":"tx1234","itemDesc":"Item XYZ","token":"GcAUe7hgY3F2FSh95Dsy5d"}' "https://test.bitpay.com/invoices"
var resourceUrl = "https://test.bitpay.com/invoices";

var httpWebRequest = (HttpWebRequest)WebRequest.Create(resourceUrl);

httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.Headers.Add(
    "x-identity",
    "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
    );
httpWebRequest.Headers.Add(
    "x-signature",
    "30460221008184d6cea3c7d1ed6cf7e49e593bfa497b9d15ed5fd63a07e33ee61f66652d81022100f6462521d26f2362b5cac64523121691b529fda8c33874f9c70cae56b6d00396"
    );
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "POST";

string json = "{" +
                "\"currency\":\"USD\"," +
                "\"price\":5," +
                "\"orderId\":\"MerchantOrder123\"," +
                "\"fullNotifications\":true," +
                "\"extendedNotifications\":true," +
                "\"transactionSpeed\":\"medium\"," +
                "\"notificationURL\":\"https://yournotificationurl.com\"," +
                "\"notificationEmail\":\"merchant@email.com\"," +
                "\"redirectURL\":\"https://yourredirecturl.com\"," +
                "\"buyer\":{" +
                    "\"email\":\"fox.mulder@trustno.one\"," +
                    "\"name\":\"Fox Mulder\"," +
                    "\"phone\":\"555-123-456\"," +
                    "\"address1\":\"2630 Hegal Place\"," +
                    "\"address2\":\"Apt 42\"," +
                    "\"locality\":\"Alexandria\"," +
                    "\"region\":\"VA\"," +
                    "\"postalCode\":\"23242\"," +
                    "\"country\":\"US\"," +
                    "\"notify\":true" +
                "}," +
                "\"paymentCurrencies\":{" +
                "\"ETH\"" +
                "}," +
                "\"posData\":\"tx1234\"," +
                "\"itemDesc\":\"Item XYZ\"," +
                "\"token\":\"GcAUe7hgY3F2FSh95Dsy5d\"" +
              "}";

using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
{
    streamWriter.Write(json);
    streamWriter.Flush();
    streamWriter.Close();
}

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/invoices";
var json = "{" +
             "\"currency\":\"USD\"," +
             "\"price\":5," +
             "\"orderId\":\"MerchantOrder123\"," +
             "\"fullNotifications\":true," +
             "\"extendedNotifications\":true," +
             "\"transactionSpeed\":\"medium\"," +
             "\"notificationURL\":\"https://yournotificationurl.com\"," +
             "\"notificationEmail\":\"merchant@email.com\"," +
             "\"redirectURL\":\"https://yourredirecturl.com\"," +
             "\"buyer\":{" +
                 "\"email\":\"fox.mulder@trustno.one\"," +
                 "\"name\":\"Fox Mulder\"," +
                 "\"phone\":\"555-123-456\"," +
                 "\"address1\":\"2630 Hegal Place\"," +
                 "\"address2\":\"Apt 42\"," +
                 "\"locality\":\"Alexandria\"," +
                 "\"region\":\"VA\"," +
                 "\"postalCode\":\"23242\"," +
                 "\"country\":\"US\"," +
                 "\"notify\":true" +
             "}," +
             "\"posData\":\"tx1234\"," +
             "\"itemDesc\":\"Item XYZ\"," +
             "\"token\":\"GcAUe7hgY3F2FSh95Dsy5d\"" +
         "}";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request=HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .header(
       "x-identity",
       "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
   )
   .header(
       "x-signature",
       "30460221008184d6cea3c7d1ed6cf7e49e593bfa497b9d15ed5fd63a07e33ee61f66652d81022100f6462521d26f2362b5cac64523121691b529fda8c33874f9c70cae56b6d00396"
   )
   .uri(URI.create(resourceUrl))
   .POST(HttpRequest.BodyPublishers.ofString(json))
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/invoices';

$postData = json_encode([
   'currency' => 'USD',
   'price' => 5,
   'orderId' => 'MerchantOrder123',
   'fullNotifications' => true,
   'extendedNotifications' => true,
   'transactionSpeed' => 'medium',
   'notificationURL' => 'https://yournotificationurl.com',
   'notificationEmail' => 'merchant@email.com',
   'redirectURL' => 'https://yourredirecturl.com',
   'buyer' => [
       'email' => 'fox.mulder@trustno.one',
       'name' => 'Fox Mulder',
       'phone' => '555-123-456',
       'address1' => '2630 Hegal Place',
       'address2' => 'Apt 42',
       'locality' => 'Alexandria',
       'region' => 'VA',
       'postalCode' => '23242',
       'country' => 'US',
       'notify' => true
   ],
   'posData' => 'tx1234',
   'itemDesc' => 'Item XYZ',
   'token' => 'GcAUe7hgY3F2FSh95Dsy5d'
]);

$curlCli = curl_init($resourceUrl);

curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json',
   'x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature: 30460221008184d6cea3c7d1ed6cf7e49e593bfa497b9d15ed5fd63a07e33ee61f66652d81022100f6462521d26f2362b5cac64523121691b529fda8c33874f9c70cae56b6d00396'
]);

curl_setopt($curlCli, CURLOPT_POSTFIELDS, stripslashes($postData));

$result = curl_exec($curlCli);
curl_close($curlCli);

echo $result;

?>
let request = require('request');

let resource_url = 'https://test.bitpay.com/invoices';
let post_data = {
   "currency": "USD",
   "price": 5,
   "orderId": "MerchantOrder123",
   "fullNotifications": true,
   "extendedNotifications": true,
   "transactionSpeed": "medium",
   "notificationURL": "https://yournotificationurl.com",
   "notificationEmail": "merchant@email.com",
   "redirectURL": "https://yourredirecturl.com",
   "buyer": {
       "email": "fox.mulder@trustno.one",
       "name": "Fox Mulder",
       "phone": "555-123-456",
       "address1": "2630 Hegal Place",
       "address2": "Apt 42",
       "locality": "Alexandria",
       "region": "VA",
       "postalCode": "23242",
       "country": "US",
       "notify": true
   },
   "posData": "tx1234",
   "itemDesc": "Item XYZ",
   "token": "GcAUe7hgY3F2FSh95Dsy5d"
};
let headers = {
   "x-accept-version": "2.0.0",
   "Content-type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "30460221008184d6cea3c7d1ed6cf7e49e593bfa497b9d15ed5fd63a07e33ee61f66652d81022100f6462521d26f2362b5cac64523121691b529fda8c33874f9c70cae56b6d00396"
};
let options = {
   url: resource_url,
   method: 'POST',
   json: post_data,
   headers: headers
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/invoices"
postData := []byte(`{
     "currency": "USD",
     "price": 5,
     "orderId": "MerchantOrder123",
     "fullNotifications": true,
     "extendedNotifications": true,
     "transactionSpeed": "medium",
     "notificationURL": "https://yournotificationurl.com",
     "notificationEmail": "merchant@email.com",
     "redirectURL": "https://yourredirecturl.com",
     "buyer": {
         "email": "fox.mulder@trustno.one",
         "name": "Fox Mulder",
         "phone": "555-123-456",
         "address1": "2630 Hegal Place",
         "address2": "Apt 42",
         "locality": "Alexandria",
         "region": "VA",
         "postalCode": "23242",
         "country": "US",
         "notify": true
     },
     "posData": "tx1234",
     "itemDesc": "Item XYZ",
     "token": "GcAUe7hgY3F2FSh95Dsy5d"
 }`)

request, err := http.NewRequest("POST", resourceUrl, bytes.NewBuffer(postData))
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")
request.Header.Set("x-identity", "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572")
request.Header.Set("x-signature", "30460221008184d6cea3c7d1ed6cf7e49e593bfa497b9d15ed5fd63a07e33ee61f66652d81022100f6462521d26f2362b5cac64523121691b529fda8c33874f9c70cae56b6d00396")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}
defer response.Body.Close()

body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/invoices'
post_data = {
   'currency': 'USD',
   'price': 5,
   'orderId': 'MerchantOrder123',
   'fullNotifications': True,
   'extendedNotifications': True,
   'transactionSpeed': 'medium',
   'notificationURL': 'https://yournotificationurl.com',
   'notificationEmail': 'merchant@email.com',
   'redirectURL': 'https://yourredirecturl.com',
   'buyer': {
       'email': 'fox.mulder@trustno.one',
       'name': 'Fox Mulder',
       'phone': '555-123-456',
       'address1': '2630 Hegal Place',
       'address2': 'Apt 42',
       'locality': 'Alexandria',
       'region': 'VA',
       'postalCode': '23242',
       'country': 'US',
       'notify': True
   },
   'posData': 'tx1234',
   'itemDesc': 'Item XYZ',
   'token': 'GcAUe7hgY3F2FSh95Dsy5d'
}
headers = {
   'x-accept-version': '2.0.0',
   'Content-Type': 'application/json',
   'x-identity': '031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature': '30460221008184d6cea3c7d1ed6cf7e49e593bfa497b9d15ed5fd63a07e33ee61f66652d81022100f6462521d26f2362b5cac64523121691b529fda8c33874f9c70cae56b6d00396'
}
response = requests.post(url=resource_url, data=json.dumps(post_data), headers=headers).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/invoices"
post_data = {
   "currency": "USD",
   "price": 5,
   "orderId": "MerchantOrder123",
   "fullNotifications": true,
   "extendedNotifications": true,
   "transactionSpeed": "medium",
   "notificationURL": "https://yournotificationurl.com",
   "notificationEmail": "merchant@email.com",
   "redirectURL": "https://yourredirecturl.com",
   "buyer": {
       "email": "fox.mulder@trustno.one",
       "name": "Fox Mulder",
       "phone": "555-123-456",
       "address1": "2630 Hegal Place",
       "address2": "Apt 42",
       "locality": "Alexandria",
       "region": "VA",
       "postalCode": "23242",
       "country": "US",
       "notify": true
   },
   "posData": "tx1234",
   "itemDesc": "Item XYZ",
   "token": "GcAUe7hgY3F2FSh95Dsy5d"
}
headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "30460221008184d6cea3c7d1ed6cf7e49e593bfa497b9d15ed5fd63a07e33ee61f66652d81022100f6462521d26f2362b5cac64523121691b529fda8c33874f9c70cae56b6d00396"
}
uri = URI.parse(resource_url)
request = Net::HTTP::Post.new(uri.to_s, headers)
request.body = post_data.to_json

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body
Headers
fields Presence
x-accept-version:
must be set to 2.0.0 for requests to the BitPay API
M
content-type
must be set to application/json for requests to the BitPay API
M
x-identity
the hexadecimal public key generated from the client private key. This header is required when using tokens with higher privileges (merchant facade). When using standard pos facade token directly from the BitPay dashboard (with "Require Authentication" disabled), this header is not needed.
C
x-signature
header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key. This header is required when using tokens with higher privileges (merchant facade). When using standard pos facade token directly from the BitPay dashboard (with "Require Authentication" disabled), this header is not needed.
C
Body
Name Type Presence
token
The API token can be retrieved from the dashboard (limited to pos facade) or using the Tokens resource to get access to the merchant facade. This is described in the section Request an API token).
string M
price
Fixed price amount for the checkout, in the "currency" of the invoice object.
number M
currency
ISO 4217 3-character currency code. This is the currency associated with the price field, supported currencies are available via the Currencies resource.
string M
orderId
Can be used by the merchant to assign their own internal Id to an invoice. If used, there should be a direct match between an orderId and an invoice id.
string O
itemDesc
Invoice description - will be added as a line item on the BitPay checkout page, under the merchant name.
string O
itemCode
"bitcoindonation" for donations, otherwise do not include the field in the request.
string O
notificationEmail
Merchant email address for notification of invoice status change. It is also possible to configure this email via the account setting on the BitPay dashboard or disable the email notification
string O
notificationURL
URL to which BitPay sends webhook notifications. HTTPS is mandatory.
string O
redirectURL
URL to redirect the shopper back to your website after a successful purchase. Be sure to include "http://" or "https://" in the url.
string O
posData
A passthru variable provided by the merchant during invoice creation and designed to be used by the merchant to correlate the invoice with an order or other object in their system. This passthru variable can be a serialized object, e.g.: "posData": "\"{ \"ref\" : 711454, \"item\" : \"test_item\" }\"".
string O
transactionSpeed
This is a risk mitigation parameter for the merchant to configure how they want to fulfil orders depending on the number of block confirmations for the transaction made by the consumer on the selected cryptocurrency (BTC, BCH, etc).

  • high: The invoice is marked as "confirmed" by BitPay as soon as full payment is received but not yet validated on the corresponding blockchain. The invoice will go from a status of "new" to "confirmed", bypassing the "paid" status. If you want an immediate notification for a payment, you can use the high speed setting. However, it makes you more susceptible to receiving fraudulent payments, so it is not recommended.
  • medium: (Recommended for most merchants) The invoice is marked as "confirmed" after the transaction has received basic confirmation on the corresponding blockchain. For invoices paid in Bitcoin (BTC), this means 1 confirmation on the blockchain which takes on average 10 minutes. The invoice will go from a status of "new" to "paid" followed by "confirmed" and then "complete"
  • low: The invoice is marked as "confirmed" once BitPay has credited the funds to the merchant account. The invoice will go from a status of "new" to "paid" followed by "complete", thus bypassing the "confirmed" status. For invoices paid in Bitcoin (BTC), this means 6 confirmations on the blockchain which takes on average an hour

If not set on the invoice, transactionSpeed will default to the account-level Order Settings.

Note : orders are only credited to your BitPay Account Summary for settlement after the invoice reaches the status "complete" (regardless of this setting).

string O
fullNotifications
This parameter is set to true by default, meaning all standard notifications are being sent for a payment made to an invoice. If you decide to set it to false instead, only 1 webhook will be sent for each invoice paid by the consumer. This webhook will be for the "confirmed" or "complete" invoice status, depending on the transactionSpeed selected.
boolean O
extendedNotifications
Allows merchants to get access to additional webhooks. For instance when an invoice expires without receiving a payment or when it is refunded. If set to true, then fullNotifications is automatically set to true. When using the extendedNotifications parameter, the webhook also have a payload slightly different from the standard webhooks.
boolean O
physical
Indicates whether items are physical goods. Alternatives include digital goods and services.
boolean O
buyer
Allows merchant to pass buyer related information in the invoice object
object O
name
Buyer's name
string O
address1
Buyer's address
string O
address2
Buyer's appartment or suite number
string O
locality
Buyer's city or locality
string O
region
Buyer's state or province
string O
postalCode
Buyer's Zip or Postal Code
string O
country
Buyer's Country code. Format ISO 3166-1 alpha-2
string O
email
Buyer's email address. If provided during invoice creation, this will bypass the email prompt for the consumer when opening the invoice.
string O
phone
Buyer's phone number
string O
notify
Indicates whether a BitPay email confirmation should be sent to the buyer once he has paid the invoice
boolean O
paymentCurrencies
Allow the merchant to select the cryptocurrencies available as payment option on the BitPay invoice. Possible values are currently "BTC" and/or "BCH". For instance "paymentCurrencies": ["BTC"] will create an invoice with only BTC available as transaction currency, thus bypassing the currency selection step on the invoice.
array O
HTTP Response

for invoices created via the POS facade (unsigned requests)

{
  "facade":"pos/invoice",
  "data":{
    "url":"https://test.bitpay.com/invoice?id=Dp1FUgJiLJPHEES6Dj27kW",
    "posData": "tx1234",
    "status":"new",
    "price":5,
    "currency":"USD",
    "itemDesc": "Item XYZ",
    "orderId":"MerchantOrder123",
    "invoiceTime":1558535182282,
    "expirationTime":1558536082282,
    "currentTime":1558535182314,
    "id":"Dp1FUgJiLJPHEES6Dj27kW",
    "lowFeeDetected":false,
    "amountPaid":0,
    "exceptionStatus":false,
    "redirectURL":"https://yourredirecturl.com",
    "refundAddressRequestPending":false,
    "buyerProvidedInfo":{
      "name":"Fox Mulder",
      "phoneNumber":"555-123-456"
    },
    "paymentSubtotals":{
      "BTC":63500,
      "BCH":1227600
    },
    "paymentTotals":{
      "BTC":63600,
      "BCH":1227600
    },
    "paymentDisplayTotals":{
      "BTC":"0.000636",
      "BCH":"0.012276"
    },
    "paymentDisplaySubTotals":{
      "BTC":"0.000635",
      "BCH":"0.012276"
    },
    "exchangeRates":{
      "BTC":{
        "USD":7878.180000000001,
        "BCH":19.313998529051243
      },
      "BCH":{
        "USD":407.30000000000007,
        "BTC":0.051696805155211
      }
    },
    "supportedTransactionCurrencies":{
      "BTC":{
        "enabled":true
      },
      "BCH":{
        "enabled":true
      }
    },
    "minerFees":{
      "BTC":{
        "satoshisPerByte":1,
        "totalFee":100
      },
      "BCH":{
        "satoshisPerByte":0,
        "totalFee":0
      }
    },
    "paymentCodes":{
      "BTC":{
        "BIP72b":"bitcoin:?r=https://test.bitpay.com/i/Dp1FUgJiLJPHEES6Dj27kW",
        "BIP73":"https://test.bitpay.com/i/Dp1FUgJiLJPHEES6Dj27kW"
      },
      "BCH":{
        "BIP72b":"bitcoincash:?r=https://test.bitpay.com/i/Dp1FUgJiLJPHEES6Dj27kW",
        "BIP73":"https://test.bitpay.com/i/Dp1FUgJiLJPHEES6Dj27kW"
      }
    },
    "token":"4KzBnJ4DGC3kPSa3VdpVDf9akqSyMPXsQfp5t3791AhNEFtpi2Q98bgBWzcXXN3kUF"
  }
}

For invoices created via the merchant facade (signed requests)

{
  "facade": "merchant/invoice",
  "data": {
    "url": "https://test.bitpay.com/invoice?id=D3Zzaoh8AAEJixkGtrQEjH",
    "posData": "tx1234",
    "status": "new",
    "price": 5,
    "currency": "USD",
    "itemDesc": "Item XYZ",
    "orderId": "MerchantOrder123",
    "invoiceTime": 1558611123182,
    "expirationTime": 1558612023182,
    "currentTime": 1558611123206,
    "id": "D3Zzaoh8AAEJixkGtrQEjH",
    "lowFeeDetected": false,
    "amountPaid": 0,
    "exceptionStatus": false,
    "targetConfirmations": 6,
    "transactions": [],
    "buyer": {
      "name": "Fox Mulder",
      "address1": "2630 Hegal Place",
      "address2": "Apt 42",
      "locality": "Alexandria",
      "region": "VA",
      "postalCode": "23242",
      "country": "US",
      "email": "fox.mulder@trustno.one",
      "phone": "555-123-456",
      "notify": true
    },
    "redirectURL": "https://yourredirecturl.com",
    "refundAddresses": [],
    "refundAddressRequestPending": false,
    "buyerProvidedEmail": "fox.mulder@trustno.one",
    "buyerProvidedInfo": {
      "name": "Fox Mulder",
      "phoneNumber": "555-123-456",
      "emailAddress": "fox.mulder@trustno.one"
    },
    "paymentSubtotals": {
      "BTC": 65700,
      "BCH": 1300400
    },
    "paymentTotals": {
      "BTC": 65800,
      "BCH": 1300400
    },
    "paymentDisplayTotals": {
      "BTC": "0.000658",
      "BCH": "0.013004"
    },
    "paymentDisplaySubTotals": {
      "BTC": "0.000657",
      "BCH": "0.013004"
    },
    "exchangeRates": {
      "BTC": {
        "USD": 7608.97,
        "BCH": 19.76869316705638
      },
      "BCH": {
        "USD": 384.49999999999994,
        "BTC": 0.05052569057252375
      }
    },
    "minerFees": {
      "BTC": {
        "satoshisPerByte": 1,
        "totalFee": 100
      },
      "BCH": {
        "satoshisPerByte": 0,
        "totalFee": 0
      }
    },
    "shopper": { 
      "user": "37SysActbPgLYfn9QJh8AB"
    },
    "supportedTransactionCurrencies": {
      "BTC": {
        "enabled": true
      },
      "BCH": {
        "enabled": true
      }
    },
    "paymentCodes": {
      "BTC": {
        "BIP72b": "bitcoin:?r=https://test.bitpay.com/i/D3Zzaoh8AAEJixkGtrQEjH",
        "BIP73": "https://test.bitpay.com/i/D3Zzaoh8AAEJixkGtrQEjH"
      },
      "BCH": {
        "BIP72b": "bitcoincash:?r=https://test.bitpay.com/i/D3Zzaoh8AAEJixkGtrQEjH",
        "BIP73": "https://test.bitpay.com/i/D3Zzaoh8AAEJixkGtrQEjH"
      }
    },
    "token": "5z1h2xr2RRrxrZf3k7SScjADx9GR9st4Z41bHajajCMusLhiyWaBtthXsii8jqWqu2"
  }
}

On the right side, you will find an example of the invoice object returned in the response you will get from the BitPay server. A description of all invoice fields is available in the resource section.

Fetch an invoice by id

GET
https://bitpay.com/invoices/<invoiceId>
Facades

public pos merchant

HTTP Request

via the pos facade (unsigned requests)

curl -X GET -H "x-accept-version: 2.0.0" -H "content-type: application/json" "https://test.bitpay.com/invoices/RhHwkycGaDskrEhGfXWnRG?token=Tqi5NhskgZHW3ZUv6y1AZg"
var resourceUrl = "https://test.bitpay.com/invoices";
var invoiceId = "RhHwkycGaDskrEhGfXWnRG";
var token = "Tqi5NhskgZHW3ZUv6y1AZg";

var httpWebRequest = (HttpWebRequest)WebRequest.Create(resourceUrl + "/" + invoiceId + "?token=" + token);
httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "GET";

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/invoices";
var invoiceId = "RhHwkycGaDskrEhGfXWnRG";
var token = "Tqi5NhskgZHW3ZUv6y1AZg";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request=HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .uri(URI.create(resourceUrl + "/" + invoiceId + "?token=" + token))
   .GET()
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/invoices';
$invoiceId = 'RhHwkycGaDskrEhGfXWnRG';
$token = 'Tqi5NhskgZHW3ZUv6y1AZg';

$curlCli = curl_init($resourceUrl . '/' . $invoiceId . '?token=' . $token);

curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json'
]);

$result = curl_exec($curlCli);
$resultData = json_decode($result, TRUE);
curl_close($curlCli);

echo $resultData;

?>
let request = require('request');

let resource_url = 'https://test.bitpay.com/invoices';
let invoice_id = 'RhHwkycGaDskrEhGfXWnRG';
let token = 'Tqi5NhskgZHW3ZUv6y1AZg';
let headers = {"x-accept-version": "2.0.0", "Content-type": "application/json"};
let options = {
   url: resource_url + '/' + invoice_id + '?token=' + token,
   method: 'GET',
   headers: headers,
   json: true
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/invoices"
invoiceId := "RhHwkycGaDskrEhGfXWnRG"
token := "Tqi5NhskgZHW3ZUv6y1AZg"

request, err := http.NewRequest("GET", resourceUrl + "/" + invoiceId + "?token=" + token, nil)
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}
defer response.Body.Close()

body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/invoices'
invoice_id = 'RhHwkycGaDskrEhGfXWnRG'
token = 'Tqi5NhskgZHW3ZUv6y1AZg'
headers = {'x-accept-version': '2.0.0', 'Content-type': 'application/json'}
response = requests.get(url=resource_url + '/' + invoice_id + '?token=' + token, headers=headers).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/invoices"
invoice_id = "RhHwkycGaDskrEhGfXWnRG"
token = "Tqi5NhskgZHW3ZUv6y1AZg"
headers = {"x-accept-version": "2.0.0", "Content-type": "application/json"}
uri = URI.parse(resource_url + "/" + invoice_id + "?token=" + token)
request = Net::HTTP::Get.new(uri.to_s, headers)

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body

via the merchant facade (signed requests)

curl -X GET -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572" -H "x-signature: 3045022100befaa7170cb6c1f4c4132838f75845cd015b274386763e6fc070a5c7a01bf56c02204ba49ee013c7bd221aa9e8d64f21bce14cfdff724723e42f0823fd209e982e2a" "https://test.bitpay.com/invoices/RhHwkycGaDskrEhGfXWnRG?token=GcAUe7hgY3F2FSh95Dsy5d"
var resourceUrl = "https://test.bitpay.com/invoices";
var invoiceId = "RhHwkycGaDskrEhGfXWnRG";
var token = "GcAUe7hgY3F2FSh95Dsy5d";
var httpWebRequest = (HttpWebRequest)WebRequest.Create(resourceUrl + "/" + invoiceId + "?token=" + token);
httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.Headers.Add(
    "x-identity",
    "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
);
httpWebRequest.Headers.Add(
    "x-signature",
    "3045022100befaa7170cb6c1f4c4132838f75845cd015b274386763e6fc070a5c7a01bf56c02204ba49ee013c7bd221aa9e8d64f21bce14cfdff724723e42f0823fd209e982e2a"
);
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "GET";

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/invoices";
var invoiceId = "RhHwkycGaDskrEhGfXWnRG";
var token = "GcAUe7hgY3F2FSh95Dsy5d";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request=HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .header(
           "x-identity",
           "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
   )
   .header(
           "x-signature",
           "3045022100befaa7170cb6c1f4c4132838f75845cd015b274386763e6fc070a5c7a01bf56c02204ba49ee013c7bd221aa9e8d64f21bce14cfdff724723e42f0823fd209e982e2a"
   )
   .uri(URI.create(resourceUrl + "/" + invoiceId + "?token=" + token))
   .GET()
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/invoices';
$invoiceId = 'RhHwkycGaDskrEhGfXWnRG';
$token = 'GcAUe7hgY3F2FSh95Dsy5d';

$curlCli = curl_init($resourceUrl . '/' . $invoiceId . '?token=' . $token);

curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json',
   'x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature: 3045022100befaa7170cb6c1f4c4132838f75845cd015b274386763e6fc070a5c7a01bf56c02204ba49ee013c7bd221aa9e8d64f21bce14cfdff724723e42f0823fd209e982e2a'
]);

$result = curl_exec($curlCli);
$resultData = json_decode($result, TRUE);
curl_close($curlCli);

echo $resultData;

?>
let request = require('request');
let resource_url = 'https://test.bitpay.com/invoices';
let invoice_id = 'RhHwkycGaDskrEhGfXWnRG';
let token = 'GcAUe7hgY3F2FSh95Dsy5d';
let headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "3045022100befaa7170cb6c1f4c4132838f75845cd015b274386763e6fc070a5c7a01bf56c02204ba49ee013c7bd221aa9e8d64f21bce14cfdff724723e42f0823fd209e982e2a"
};
let options = {
   url: resource_url + '/' + invoice_id + '?token=' + token,
   method: 'GET',
   headers: headers,
   json: true
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/invoices"
invoiceId := "RhHwkycGaDskrEhGfXWnRG"
token := "GcAUe7hgY3F2FSh95Dsy5d"

request, err := http.NewRequest("GET", resourceUrl + "/" + invoiceId + "?token=" + token, nil)
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")
request.Header.Set("x-identity", "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572")
request.Header.Set("x-signature", "3045022100befaa7170cb6c1f4c4132838f75845cd015b274386763e6fc070a5c7a01bf56c02204ba49ee013c7bd221aa9e8d64f21bce14cfdff724723e42f0823fd209e982e2a")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}
defer response.Body.Close()

body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/invoices'
invoice_id = 'RhHwkycGaDskrEhGfXWnRG'
token = 'GcAUe7hgY3F2FSh95Dsy5d'
headers = {
   'x-accept-version': '2.0.0',
   'Content-Type': 'application/json',
   'x-identity': '031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature': '3045022100befaa7170cb6c1f4c4132838f75845cd015b274386763e6fc070a5c7a01bf56c02204ba49ee013c7bd221aa9e8d64f21bce14cfdff724723e42f0823fd209e982e2a'
}
response = requests.get(url=resource_url + '/' + invoice_id + '?token=' + token, headers=headers).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/invoices"
invoice_id = "RhHwkycGaDskrEhGfXWnRG"
token = "GcAUe7hgY3F2FSh95Dsy5d"
headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "3045022100befaa7170cb6c1f4c4132838f75845cd015b274386763e6fc070a5c7a01bf56c02204ba49ee013c7bd221aa9e8d64f21bce14cfdff724723e42f0823fd209e982e2a"
}
uri = URI.parse(resource_url + "/" + invoice_id + "?token=" + token)
request = Net::HTTP::Get.new(uri.to_s, headers)

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body
URL Parameters
Parameter Type Presence
?token=
when fetching an invoice via the merchant or the pos facade, pass the API token as a URL parameter. No token is required when viewing an invoice from the public facade.
string C
Headers
fields Presence
x-accept-version:
must be set to 2.0.0 for request to the BitPay API
M
content-type
must be set to application/json for request to the BitPay API
M
x-identity
the hexadecimal public key generated from the client private key. This header is required when using tokens with higher privileges (merchant facade). When using standard pos facade token directly from the BitPay dashboard (with "Require Authentication" disabled), this header is not needed.
C
x-signature
header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key. This header is required when using tokens with higher privileges (merchant facade). When using standard pos facade token directly from the BitPay dashboard (with "Require Authentication" disabled), this header is not needed.
C
HTTP Response

For invoices fetched via the pos facade (unsigned requests)

{
  "facade": "pos/invoice",
  "data": {
    "url": "https://test.bitpay.com/invoice?id=RhHwkycGaDskrEhGfXWnRG",
    "status": "complete",
    "price": 60.61,
    "currency": "USD",
    "orderId": "test-abc",
    "invoiceTime": 1556804235791,
    "expirationTime": 1556805135791,
    "currentTime": 1561708784111,
    "id": "RhHwkycGaDskrEhGfXWnRG",
    "lowFeeDetected": false,
    "amountPaid": 1132400,
    "exceptionStatus": false,
    "refundAddressRequestPending": false,
    "buyerProvidedInfo": {
      "selectedTransactionCurrency": "BTC"
    },
    "paymentSubtotals": {
      "BTC": 1132200,
      "BCH": 22708900
    },
    "paymentTotals": {
      "BTC": 1132400,
      "BCH": 22708900
    },
    "paymentDisplayTotals": {
      "BTC": "0.011324",
      "BCH": "0.227089"
    },
    "paymentDisplaySubTotals": {
      "BTC": "0.011322",
      "BCH": "0.227089"
    },
    "exchangeRates": {
      "BTC": {
        "USD": 5353.21,
        "BCH": 20.04947565543071
      },
      "BCH": {
        "USD": 266.9,
        "BTC": 0.049845923989167984
      }
    },
    "supportedTransactionCurrencies": {
      "BTC": {
        "enabled": true
      },
      "BCH": {
        "enabled": true
      }
    },
    "minerFees": {
      "BTC": {
        "satoshisPerByte": 1.02,
        "totalFee": 200
      },
      "BCH": {
        "satoshisPerByte": 0,
        "totalFee": 0
      }
    },
    "transactionCurrency": "BTC",
    "paymentCodes": {
      "BTC": {
        "BIP72b": "bitcoin:?r=https://test.bitpay.com/i/RhHwkycGaDskrEhGfXWnRG",
        "BIP73": "https://test.bitpay.com/i/RhHwkycGaDskrEhGfXWnRG"
      },
      "BCH": {
        "BIP72b": "bitcoincash:?r=https://test.bitpay.com/i/RhHwkycGaDskrEhGfXWnRG",
        "BIP73": "https://test.bitpay.com/i/RhHwkycGaDskrEhGfXWnRG"
      }
    },
    "token": "4KzBnJ4DGC3kPSa3VdpVDfBZ9qwTbxCK6gw2uJez9u8v2J5p5kUisuk4n3A1tL4hdT"
  }
}

For invoices fetched via the merchant facade (signed requests)

{
  "facade": "merchant/invoice",
  "data": {
    "url": "https://test.bitpay.com/invoice?id=RhHwkycGaDskrEhGfXWnRG",
    "posData": "tx1234",
    "status": "complete",
    "price": 60.61,
    "currency": "USD",
    "itemDesc": "Item XYZ",
    "orderId": "test-abc",
    "invoiceTime": 1556804235791,
    "expirationTime": 1556805135791,
    "currentTime": 1559297397907,
    "id": "RhHwkycGaDskrEhGfXWnRG",
    "lowFeeDetected": false,
    "amountPaid": 1132400,
    "exceptionStatus": false,
    "targetConfirmations": 6,
    "transactions": [
      {
        "amount": 1132400,
        "confirmations": 6,
        "receivedTime": "2019-05-02T13:37:30.431Z",
        "txid": "5cf78d4351f65ef852f757f511ad91bfce1944afe96544b4b9560a1456374e34",
        "exRates": {
          "BTC": 1,
          "USD": 5353.21,
          "BCH": 20.04947565543071
        },
        "outputIndex": 0
      },
      {
        "amount": -200,
        "confirmations": 6,
        "receivedTime": "2019-05-02T13:37:30.431Z",
        "type": "buyerPaidMinerFee",
        "txid": "5cf78d4351f65ef852f757f511ad91bfce1944afe96544b4b9560a1456374e34"
      },
      {
        "amount": -1060900,
        "confirmations": 6,
        "time": "2019-05-03T15:57:11.925Z",
        "receivedTime": "2019-05-03T15:57:11.925Z",
        "type": "refundFromLedger",
        "txid": "edc80538322d9f8215a0f1e8b20d56b0407488f0b0d7444290a9f6b8207be0e7",
        "refundAmount": -1060900,
        "exRates": {
          "BTC": 1,
          "USD": 5713.250000000001,
          "BCH": 19.87217391304348
        }
      }
    ],
    "buyer": {
      "address1": "2630 Hegal Place, Apt 42",
      "address2": "Apt 42",
      "locality": "Alexandria",
      "region": "Virginia",
      "postalCode": "23242",
      "email": "fox.mulder@trustno.one"
    },
    "refundAddresses": [
      {
        "mo1HjNzzxnPdyEmFGU52onfNoe455Eo8uA": {
          "type": "buyerSupplied",
          "date": "2019-05-03T15:53:20.970Z"
        }
      }
    ],
    "refundAddressRequestPending": false,
    "buyerProvidedEmail": "fox.mulder@trustno.one",
    "buyerProvidedInfo": {
      "selectedTransactionCurrency": "BTC",
      "emailAddress": "fox.mulder@trustno.one"
    },
    "paymentSubtotals": {
      "BTC": 1132200,
      "BCH": 22708900
    },
    "paymentTotals": {
      "BTC": 1132400,
      "BCH": 22708900
    },
    "paymentDisplayTotals": {
      "BTC": "0.011324",
      "BCH": "0.227089"
    },
    "paymentDisplaySubTotals": {
      "BTC": "0.011322",
      "BCH": "0.227089"
    },
    "exchangeRates": {
      "BTC": {
        "USD": 5353.21,
        "BCH": 20.04947565543071
      },
      "BCH": {
        "USD": 266.9,
        "BTC": 0.049845923989167984
      }
    },
    "minerFees": {
      "BTC": {
        "satoshisPerByte": 1.02,
        "totalFee": 200
      },
      "BCH": {
        "satoshisPerByte": 0,
        "totalFee": 0
      }
    },
    "shopper": { 
      "user": "37SysActbPgLYfn9QJh8AB"
    },
    "billId": "DrUSEQ6phH9V31t8Xqydi6",
    "refundInfo": [
      {
        "supportRequest": "BpRciwDGMXYR4kDPynsaRA",
        "currency": "USD",
        "amounts": {
          "USD": 60.61,
          "BTC": 0.010609
        }
      }
    ],
    "transactionCurrency": "BTC",
    "supportedTransactionCurrencies": {
      "BTC": {
        "enabled": true
      },
      "BCH": {
        "enabled": true
      }
    },
    "paymentCodes": {
      "BTC": {
        "BIP72b": "bitcoin:?r=https://test.bitpay.com/i/RhHwkycGaDskrEhGfXWnRG",
        "BIP73": "https://test.bitpay.com/i/RhHwkycGaDskrEhGfXWnRG"
      },
      "BCH": {
        "BIP72b": "bitcoincash:?r=https://test.bitpay.com/i/RhHwkycGaDskrEhGfXWnRG",
        "BIP73": "https://test.bitpay.com/i/RhHwkycGaDskrEhGfXWnRG"
      }
    },
    "token": "5z1h2xr2RRrxrZf3k7SScizDGeDj4VZ8Xi8MHqKopdj1xH2zqrSBKVHtEdEUYAARQT"
  }
}

On the right side, you will find an example of the invoice object returned in the response you will get from the BitPay server. A description of all invoice fields is available in the resource section.

Retrieves invoices filtered by query

GET
https://bitpay.com/invoices
Facades

merchant

HTTP Request

via the merchant facade (signed requests)

curl -X GET -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572" -H "x-signature: 3044022042667b30b0ad832589ef9200af5e2f0312edc5610b7e91015754f50549a1c20302206ba0bec89787d9dc3d5608245a74d3248dbd8f15cecf49fb630e8b48f5e578d0" "https://test.bitpay.com/invoices?token=GcAUe7hgY3F2FSh95Dsy5d&status=complete&dateStart=2019-5-1&dateEnd=2050-5-24&limit=10&offset=1"
var resourceUrl = "https://test.bitpay.com/invoices";
var token = "GcAUe7hgY3F2FSh95Dsy5d";

var status = "complete";
var dateStart = "2019-5-1";
var dateEnd = "2050-5-24";
var limit = 10;
var offset = 1;

var httpWebRequest = (HttpWebRequest)WebRequest.Create(
                        resourceUrl +
                        "?token=" + token +
                        "&status=" + status +
                        "&dateStart=" + dateStart +
                        "&dateEnd=" + dateEnd +
                        "&limit=" + limit +
                        "&offset=" + offset
                    );
httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.Headers.Add(
    "x-identity",
    "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
);
httpWebRequest.Headers.Add(
    "x-signature",
    "3044022042667b30b0ad832589ef9200af5e2f0312edc5610b7e91015754f50549a1c20302206ba0bec89787d9dc3d5608245a74d3248dbd8f15cecf49fb630e8b48f5e578d0"
);
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "GET";

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/invoices";
var token = "GcAUe7hgY3F2FSh95Dsy5d";

var status = "complete";
var dateStart = "2019-5-1";
var dateEnd = "2050-5-24";
var limit = 10;
var offset = 1;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request=HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .header(
           "x-identity",
           "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
   )
   .header(
           "x-signature",
           "3044022042667b30b0ad832589ef9200af5e2f0312edc5610b7e91015754f50549a1c20302206ba0bec89787d9dc3d5608245a74d3248dbd8f15cecf49fb630e8b48f5e578d0"
   )
   .uri(URI.create(
       resourceUrl +
       "?token=" + token +
       "&status=" + status +
       "&dateStart=" + dateStart +
       "&dateEnd=" + dateEnd +
       "&limit=" + limit +
       "&offset=" + offset
   ))
   .GET()
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/invoices';
$token = 'GcAUe7hgY3F2FSh95Dsy5d';

$status = 'complete';
$dateStart = '2019-5-1';
$dateEnd = '2050-5-24';
$limit = 10;
$offset = 1;

$curlCli = curl_init(
   $resourceUrl .
   '?token=' . $token .
   '&status=' . $status .
   '&dateStart=' . $dateStart .
   '&dateEnd=' . $dateEnd .
   '&limit=' . $limit .
   '&offset=' . $offset);

curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json',
   'x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature: 3044022042667b30b0ad832589ef9200af5e2f0312edc5610b7e91015754f50549a1c20302206ba0bec89787d9dc3d5608245a74d3248dbd8f15cecf49fb630e8b48f5e578d0'
]);

$result = curl_exec($curlCli);
$resultData = json_decode($result, TRUE);
curl_close($curlCli);

echo $resultData;

?>
let request = require('request');

let resource_url = 'https://test.bitpay.com/invoices';
let token = 'GcAUe7hgY3F2FSh95Dsy5d';
let status = 'complete';
let dateStart = '2019-5-1';
let dateEnd = '2050-5-24';
let limit = '10';
let offset = '1';
let headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "3044022042667b30b0ad832589ef9200af5e2f0312edc5610b7e91015754f50549a1c20302206ba0bec89787d9dc3d5608245a74d3248dbd8f15cecf49fb630e8b48f5e578d0"
};
let options = {
   url: resource_url +
       '?token=' + token +
       '&status=' + status +
       '&dateStart=' + dateStart +
       '&dateEnd=' + dateEnd +
       '&limit=' + limit +
       '&offset=' + offset,
   method: 'GET',
   headers: headers,
   json: true
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/invoices"
token := "GcAUe7hgY3F2FSh95Dsy5d"
status := "complete"
dateStart := "2019-5-1"
dateEnd := "2050-5-24"
limit := "10"
offset := "1"

request, err := http.NewRequest(
   "GET",
   resourceUrl +
   "?token=" + token +
   "&status=" + status +
   "&dateStart=" + dateStart +
   "&dateEnd=" + dateEnd +
   "&limit=" + limit +
   "&offset=" + offset,
   nil)
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")
request.Header.Set("x-identity", "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572")
request.Header.Set("x-signature", "3044022042667b30b0ad832589ef9200af5e2f0312edc5610b7e91015754f50549a1c20302206ba0bec89787d9dc3d5608245a74d3248dbd8f15cecf49fb630e8b48f5e578d0")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}
defer response.Body.Close()

body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/invoices'
token = 'GcAUe7hgY3F2FSh95Dsy5d'
status = 'complete'
dateStart = '2019-5-1'
dateEnd = '2050-5-24'
limit = '10'
offset = '1'
headers = {
   'x-accept-version': '2.0.0',
   'Content-Type': 'application/json',
   'x-identity': '031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature': '3044022042667b30b0ad832589ef9200af5e2f0312edc5610b7e91015754f50549a1c20302206ba0bec89787d9dc3d5608245a74d3248dbd8f15cecf49fb630e8b48f5e578d0'
}
response = requests.get(
   url=resource_url +
       '?token=' + token +
       '&status=' + status +
       '&dateStart=' + dateStart +
       '&dateEnd=' + dateEnd +
       '&limit=' + limit +
       '&offset=' + offset,
   headers=headers
).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/invoices"
token = "GcAUe7hgY3F2FSh95Dsy5d"
status = "complete"
dateStart = "2019-5-1"
dateEnd = "2050-5-24"
limit = "10"
offset = "1"
headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "3044022042667b30b0ad832589ef9200af5e2f0312edc5610b7e91015754f50549a1c20302206ba0bec89787d9dc3d5608245a74d3248dbd8f15cecf49fb630e8b48f5e578d0"
}
uri = URI.parse(
   resource_url +
   "?token=" + token +
   "&status=" + status +
   "&dateStart=" + dateStart +
   "&dateEnd=" + dateEnd +
   "&limit=" + limit +
   "&offset=" + offset
)
request = Net::HTTP::Get.new(uri.to_s, headers)

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body
URL Parameters
Parameter Type Presence
?token=
A merchant facade token can be retrieved using the Tokens resource. This is described in the section Request an API token).
string M
&dateStart=
the start of the date window to query for invoices. Format YYYY-MM-DD
string M
&dateEnd=
the end of the date window to query for invoices. Format YYYY-MM-DD
string M
&status=
the invoice status you want to query on
string O
&orderId=
the optional order id specified at time of invoice creation
string O
&limit=
maximum results that the query will return (useful for paging results)
number O
&offset=
number of results to offset (ex. skip 10 will give you results starting with the 11th result)
number O
Headers
fields Presence
x-accept-version:
must be set to 2.0.0 for request to the BitPay API
M
content-type
must be set to application/json for request to the BitPay API
M
x-identity
the hexadecimal public key generated from the client private key
M
x-signature
header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key
M
HTTP Response

For invoices fetched via the merchant facade (signed requests)

{
  "facade": "merchant/invoice",
  "data": [
    {
      "url": "https://test.bitpay.com/invoice?id=Pspr4saiFdhDyZxw8gy1SX",
      "status": "complete",
      "price": 5,
      "currency": "USD",
      "itemDesc": "Item XYZ",
      "orderId": "MerchantOrder123",
      "invoiceTime": 1558526878436,
      "expirationTime": 1558527778436,
      "currentTime": 1558620935651,
      "id": "Pspr4saiFdhDyZxw8gy1SX",
      "lowFeeDetected": false,
      "amountPaid": 63800,
      "exceptionStatus": false,
      "targetConfirmations": 6,
      "transactions": [
        {
          "amount": 63800,
          "confirmations": 6,
          "receivedTime": "2019-05-22T12:09:01.119Z",
          "txid": "572b8bf4296f8a2a17fa94a9db6ea42774a89362cda7bbd7267153212f3e8310",
          "exRates": {
            "BTC": 1,
            "USD": 7850.011886801999,
            "BCH": 19.27802524077731
          },
          "outputIndex": 1
        },
        {
          "amount": -100,
          "confirmations": 6,
          "receivedTime": "2019-05-22T12:09:01.119Z",
          "type": "buyerPaidMinerFee",
          "txid": "572b8bf4296f8a2a17fa94a9db6ea42774a89362cda7bbd7267153212f3e8310"
        }
      ],
      "buyer": {
        "name": "Fox Mulder",
        "address1": "2630 Hegal Place",
        "address2": "Apt 42",
        "locality": "Alexandria",
        "region": "VA",
        "postalCode": "23242",
        "country": "US",
        "email": "fox.mulder@trustno.one",
        "phone": "555-123-456",
        "notify": true
      },
      "refundAddresses": [],
      "refundAddressRequestPending": false,
      "buyerProvidedEmail": "fox.mulder@trustno.one",
      "buyerProvidedInfo": {
        "name": "Fox Mulder",
        "phoneNumber": "555-123-456",
        "selectedTransactionCurrency": "BTC",
        "emailAddress": "fox.mulder@trustno.one"
      },
      "paymentSubtotals": {
        "BTC": 63700,
        "BCH": 1229400
      },
      "paymentTotals": {
        "BTC": 63800,
        "BCH": 1229400
      },
      "paymentDisplayTotals": {
        "BTC": "0.000638",
        "BCH": "0.012294"
      },
      "paymentDisplaySubTotals": {
        "BTC": "0.000637",
        "BCH": "0.012294"
      },
      "exchangeRates": {
        "BTC": {
          "USD": 7845.99,
          "BCH": 19.258689248895436
        },
        "BCH": {
          "USD": 406.7,
          "BTC": 0.051835330104511856
        }
      },
      "minerFees": {
        "BTC": {
          "satoshisPerByte": 1,
          "totalFee": 100
        },
        "BCH": {
          "satoshisPerByte": 0,
          "totalFee": 0
        }
      },
      "shopper": { 
        "user": "37SysActbPgLYfn9QJh8AB"
      },
      "transactionCurrency": "BTC",
      "supportedTransactionCurrencies": {
        "BTC": {
          "enabled": true
        },
        "BCH": {
          "enabled": true
        }
      },
      "paymentCodes": {
        "BTC": {
          "BIP72b": "bitcoin:?r=https://test.bitpay.com/i/Pspr4saiFdhDyZxw8gy1SX",
          "BIP73": "https://test.bitpay.com/i/Pspr4saiFdhDyZxw8gy1SX"
        },
        "BCH": {
          "BIP72b": "bitcoincash:?r=https://test.bitpay.com/i/Pspr4saiFdhDyZxw8gy1SX",
          "BIP73": "https://test.bitpay.com/i/Pspr4saiFdhDyZxw8gy1SX"
        }
      },
      "token": "5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn"
    },
    {
      "url": "https://test.bitpay.com/invoice?id=4VHDtHFuRmDg8s6ZdVkwGn",
      "status": "complete",
      "price": 1,
      "currency": "USD",
      "invoiceTime": 1558433474129,
      "expirationTime": 1558434374129,
      "currentTime": 1558620935672,
      "id": "4VHDtHFuRmDg8s6ZdVkwGn",
      "lowFeeDetected": false,
      "amountPaid": 12700,
      "exceptionStatus": false,
      "targetConfirmations": 6,
      "transactions": [
        {
          "amount": 12700,
          "confirmations": 6,
          "receivedTime": "2019-05-21T10:11:39.492Z",
          "txid": "e2e9f47dff2c8082b31c32e8f526492ea96af62327bb49b05558feb92d6eac03",
          "exRates": {
            "BTC": 1,
            "USD": 7931.900000000001
          },
          "outputIndex": 1
        },
        {
          "amount": -100,
          "confirmations": 6,
          "receivedTime": "2019-05-21T10:11:39.492Z",
          "type": "buyerPaidMinerFee",
          "txid": "e2e9f47dff2c8082b31c32e8f526492ea96af62327bb49b05558feb92d6eac03"
        }
      ],
      "buyer": {},
      "refundAddresses": [],
      "refundAddressRequestPending": false,
      "buyerProvidedEmail": "croland@bitpay.com",
      "buyerProvidedInfo": {
        "selectedTransactionCurrency": "BTC",
        "emailAddress": "croland@bitpay.com"
      },
      "paymentSubtotals": {
        "BTC": 12600,
        "BCH": 244000
      },
      "paymentTotals": {
        "BTC": 12700,
        "BCH": 244000
      },
      "paymentDisplayTotals": {
        "BTC": "0.000127",
        "BCH": "0.002440"
      },
      "paymentDisplaySubTotals": {
        "BTC": "0.000126",
        "BCH": "0.002440"
      },
      "exchangeRates": {
        "BTC": {
          "USD": 7931.900000000001
        },
        "BCH": {
          "USD": 409.9
        }
      },
      "minerFees": {
        "BTC": {
          "satoshisPerByte": 1,
          "totalFee": 100
        },
        "BCH": {
          "satoshisPerByte": 0,
          "totalFee": 0
        }
      },
      "transactionCurrency": "BTC",
      "supportedTransactionCurrencies": {
        "BTC": {
          "enabled": true
        },
        "BCH": {
          "enabled": true
        }
      },
      "paymentCodes": {
        "BTC": {
          "BIP72b": "bitcoin:?r=https://test.bitpay.com/i/4VHDtHFuRmDg8s6ZdVkwGn",
          "BIP73": "https://test.bitpay.com/i/4VHDtHFuRmDg8s6ZdVkwGn"
        },
        "BCH": {
          "BIP72b": "bitcoincash:?r=https://test.bitpay.com/i/4VHDtHFuRmDg8s6ZdVkwGn",
          "BIP73": "https://test.bitpay.com/i/4VHDtHFuRmDg8s6ZdVkwGn"
        }
      },
      "token": "5z1h2xr2RRrxrZf3k7SScivbK6axpc42NWdTWWaQLhDtXveWAkoDEa75sEHcwtyafd"
    },
    {
      "url": "https://test.bitpay.com/invoice?id=52Y6r1qinXaZbVnivm7yas",
      "status": "complete",
      "price": 1,
      "currency": "USD",
      "invoiceTime": 1558433415215,
      "expirationTime": 1558434315215,
      "currentTime": 1558620935674,
      "id": "52Y6r1qinXaZbVnivm7yas",
      ...
    }
  ]
}

On the right side, you will find an example array of invoice objects returned in the response you will get from the BitPay server. A description of all invoice fields is available in the resource section.

Retrieve an event token for an invoice

Retrieves a bus token which can be used to subscribe to invoice events.

GET
https://bitpay.com/invoices/<invoiceId>/events
Facades

public merchant

HTTP Request

via the public facade (unsigned requests)

curl -X GET -H "x-accept-version: 2.0.0" -H "content-type: application/json" "https://test.bitpay.com/invoices/HTaH7F5KircpUCMWubCwzV/events"
var resourceUrl = "https://test.bitpay.com/invoices";
var invoiceId = "HTaH7F5KircpUCMWubCwzV";
var httpWebRequest = (HttpWebRequest)WebRequest.Create(resourceUrl + "/" + invoiceId + "/events");
httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "GET";

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/invoices";
var invoiceId = "HTaH7F5KircpUCMWubCwzV";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request=HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .uri(URI.create(resourceUrl + "/" + invoiceId + "/events"))
   .GET()
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/invoices';
$invoiceId = 'HTaH7F5KircpUCMWubCwzV';

$curlCli = curl_init($resourceUrl . '/' . $invoiceId . '/events' );

curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json'
]);

$result = curl_exec($curlCli);
$resultData = json_decode($result, TRUE);
curl_close($curlCli);

echo $resultData;

?>
let request = require('request');

let resource_url = 'https://test.bitpay.com/invoices';
let invoice_id = 'HTaH7F5KircpUCMWubCwzV';
let headers = {"x-accept-version": "2.0.0", "Content-type": "application/json"};
let options = {
   url: resource_url + '/' + invoice_id + '/events',
   method: 'GET',
   headers: headers,
   json: true
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/invoices"
invoiceId := "HTaH7F5KircpUCMWubCwzV"

request, err := http.NewRequest("GET", resourceUrl + "/" + invoiceId + "/events", nil)
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}
defer response.Body.Close()

body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/invoices'
invoice_id = 'HTaH7F5KircpUCMWubCwzV'
headers = {'x-accept-version': '2.0.0', 'Content-type': 'application/json'}
response = requests.get(url=resource_url + '/' + invoice_id + '/events', headers=headers).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/invoices"
invoice_id = "HTaH7F5KircpUCMWubCwzV"
headers = {"x-accept-version": "2.0.0", "Content-type": "application/json"}
uri = URI.parse(resource_url + "/" + invoice_id + "/events")
request = Net::HTTP::Get.new(uri.to_s, headers)

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body

via the merchant facade (signed requests)

curl -X GET -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572" -H "x-signature: 30460221008270efc83b98108da714a5d834974801908140c3c8579d1740bd63cd129aefcc022100bb2a93b5e1c932c972130a9381e158cd74d8d8db161a32ace5d8deeeafbb0336" "https://test.bitpay.com/invoices/F5a8amXMh8pi2hLWXQtEvg/events?token=GcAUe7hgY3F2FSh95Dsy5d"
var resourceUrl = "https://test.bitpay.com/invoices";
var invoiceId = "F5a8amXMh8pi2hLWXQtEvg";
var token = "GcAUe7hgY3F2FSh95Dsy5d";
var httpWebRequest = (HttpWebRequest)WebRequest.Create(resourceUrl + "/" + invoiceId + "/events?token=" + token);
httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.Headers.Add(
    "x-identity",
    "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
);
httpWebRequest.Headers.Add(
    "x-signature",
    "30460221008270efc83b98108da714a5d834974801908140c3c8579d1740bd63cd129aefcc022100bb2a93b5e1c932c972130a9381e158cd74d8d8db161a32ace5d8deeeafbb0336"
);
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "GET";

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/invoices";
var invoiceId = "F5a8amXMh8pi2hLWXQtEvg";
var token = "GcAUe7hgY3F2FSh95Dsy5d";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request=HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .header(
           "x-identity",
           "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
   )
   .header(
           "x-signature",
           "30460221008270efc83b98108da714a5d834974801908140c3c8579d1740bd63cd129aefcc022100bb2a93b5e1c932c972130a9381e158cd74d8d8db161a32ace5d8deeeafbb0336"
   )
   .uri(URI.create(resourceUrl + "/" + invoiceId + "/events?token=" + token))
   .GET()
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/invoices';
$invoiceId = 'F5a8amXMh8pi2hLWXQtEvg';
$token = 'GcAUe7hgY3F2FSh95Dsy5d';

$curlCli = curl_init($resourceUrl . '/' . $invoiceId . '/events?token=' . $token);

curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json',
   'x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature: 30460221008270efc83b98108da714a5d834974801908140c3c8579d1740bd63cd129aefcc022100bb2a93b5e1c932c972130a9381e158cd74d8d8db161a32ace5d8deeeafbb0336'
]);

$result = curl_exec($curlCli);
$resultData = json_decode($result, TRUE);
curl_close($curlCli);

echo $resultData;

?>
let request = require('request');

let resource_url = 'https://test.bitpay.com/invoices';
let invoice_id = 'F5a8amXMh8pi2hLWXQtEvg';
let token = 'GcAUe7hgY3F2FSh95Dsy5d';
let headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "30460221008270efc83b98108da714a5d834974801908140c3c8579d1740bd63cd129aefcc022100bb2a93b5e1c932c972130a9381e158cd74d8d8db161a32ace5d8deeeafbb0336"
};
let options = {
   url: resource_url + '/' + invoice_id + '/events?token=' + token,
   method: 'GET',
   headers: headers,
   json: true
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/invoices"
invoiceId := "F5a8amXMh8pi2hLWXQtEvg"
token := "GcAUe7hgY3F2FSh95Dsy5d"

request, err := http.NewRequest("GET", resourceUrl + "/" + invoiceId + "/events?token=" + token, nil)
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")
request.Header.Set("x-identity", "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572")
request.Header.Set("x-signature", "3045022100befaa7170cb6c1f4c4132838f75845cd015b274386763e6fc070a5c7a01bf56c02204ba49ee013c7bd221aa9e8d64f21bce14cfdff724723e42f0823fd209e982e2a")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}
defer response.Body.Close()

body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/invoices'
invoice_id = 'F5a8amXMh8pi2hLWXQtEvg'
token = 'GcAUe7hgY3F2FSh95Dsy5d'
headers = {
   'x-accept-version': '2.0.0',
   'Content-Type': 'application/json',
   'x-identity': '031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature': '30460221008270efc83b98108da714a5d834974801908140c3c8579d1740bd63cd129aefcc022100bb2a93b5e1c932c972130a9381e158cd74d8d8db161a32ace5d8deeeafbb0336'
}
response = requests.get(url=resource_url + '/' + invoice_id + '/events?token=' + token, headers=headers).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/invoices"
invoice_id = "F5a8amXMh8pi2hLWXQtEvg"
token = "GcAUe7hgY3F2FSh95Dsy5d"
headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "30460221008270efc83b98108da714a5d834974801908140c3c8579d1740bd63cd129aefcc022100bb2a93b5e1c932c972130a9381e158cd74d8d8db161a32ace5d8deeeafbb0336"
}
uri = URI.parse(resource_url + "/" + invoice_id + "/events?token=" + token)
request = Net::HTTP::Get.new(uri.to_s, headers)

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body
URL Parameters
Parameter Type Presence
<invoiceId>
the id of the invoice for which you want to fetch an event token
string M
?token=
A merchant facade token can be retrieved using the Tokens resource. This is described in the section Request an API token) No token is required if fetching the event token via the public.
string C
Headers
fields Presence
x-accept-version:
must be set to 2.0.0 for request to the BitPay API
M
content-type
must be set to application/json for request to the BitPay API
M
x-identity
the hexadecimal public key generated from the client private key. This header is required when using tokens with higher privileges (merchant facade). When using the standard public facade, this header is not needed.
C
x-signature
header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key. This header is required when using tokens with higher privileges (merchant facade). When using the standard public facade, this header is not needed.
C
HTTP Response

For events token fetched via the public facade (unsigned requests)

{
  "facade": "public/invoice",
  "data": {
    "url": "https://test.bitpay.com/events",
    "token": "767cdhmwtn7XgW1QrSkuEwiwvxjgArt7y5pRoSVfXCZjr7ysjQBS8WXhwgvsP2J4ut",
    "events": [
      "payment",
      "confirmation",
      "paymentRejected",
      "scanned",
      "paymentPosted"
    ],
    "actions": [
      "subscribe",
      "unsubscribe"
    ]
  }
}

For events token fetched via the merchant facade (signed requests)

{
  "facade": "merchant/invoice",
  "data": {
    "url": "https://test.bitpay.com/events",
    "token": "7Bhs6Y9duMNLKWF7Jy3e7UK4iSKkJfYbYDmTnZXD7uLPq7WgmXhnTD132Bh77tYxBR",
    "events": [
      "payment",
      "confirmation"
    ],
    "actions": [
      "subscribe",
      "unsubscribe"
    ]
  }
}
Body

Common fields across facades

Name Type
facade
this indicates the facade used to fetch the event token for a given invoice. When the merchant facade is used, the BitPay server returns the event object for an invoice as seen from the merchant facade that is "merchant/invoice" and "public/invoice" if the public facade is used instead
string
data
invoices event data object
object
url
base URL where you can subscribe to events (HTTP long polling)
string
token
API token for subscriber resource, passed as ?token= query parameter value
string
events
All supported &events[]= query parameter values.

If the public facade is used to fetch the invoice event object. The possible values are:

  • scanned - this event indicates if the consumer scanned the QR code or clicked on the "Pay with BitPay" button on the invoice. This event can be logged multiple times in a row when listening to the websocket
  • paymentPosted - this event indicates when the consumer has initiated the payment from his crypto wallet. This event can be logged multiple times in a row when listening to the websocket
  • payment - This allows you to be informed when the BitPay invoice reaches the status "paid", meaning the transaction has been applied to the invoice, but has not been confirmed yet. When listening to the websocket, this will be logged under the event: statechange
  • confirmation - This allows you to track the number of block confirmations for the transaction made to an invoice. When listening to the websocket, this will be logged under the event: statechange
  • paymentRejected - indicates if the invoice rejected the payment proposal made by the consumer wallet (miner fees too low, wrong amount).

If the merchant facade is used to fetch the invoice event object. The possible values are:

  • payment - This allows you to be informed when the BitPay invoice reaches the status "paid", meaning the transaction has been applied to the invoice, but has not been confirmed yet. When listening to the websocket, this will be logged under the event: statechange. The invoice payload will contain the additional fields related to the merchant facade.
  • confirmation - This allows you to track the number of block confirmations for the transaction made to an invoice. When listening to the websocket, this will be logged under the event: statechange. The invoice payload will contain the additional fields related to the merchant facade.

array
actions
All supported &action= query parameter values. Can be subscribe or unsubscribe.
array

Subscribe to invoice events (HTTP long polling)

:                                                                                                                                                         
retry: 2000
event: connect
data: {"status":"subscribed","resource":"HTaH7F5KircpUCMWubCwzV","facade":"public/invoice","events":["payment","confirmation","paymentRejected","scanned","paymentPosted"]}

event: state
data: {"url":"https://test.bitpay.com/invoice?id=HTaH7F5KircpUCMWubCwzV","status":"new","price":2,"currency":"USD","orderId":"Test invoice 1","invoiceTime":1561024511370,"expirationTime":1561025411370,"currentTime":1561024532341,"guid":"2be8c694-84d6-a0ff-3b47-9c859ba5d817","id":"HTaH7F5KircpUCMWubCwzV","lowFeeDetected":false,"amountPaid":0,"exceptionStatus":false,"refundAddressRequestPending":false,"buyerProvidedInfo":{"name":"Fox Mulder","phoneNumber":"555-123-456"},"paymentSubtotals":{"BTC":21600,"BCH":489700},"paymentTotals":{"BTC":21700,"BCH":489700},"paymentDisplayTotals":{"BTC":"0.000217","BCH":"0.004897"},"paymentDisplaySubTotals":{"BTC":"0.000216","BCH":"0.004897"},"exchangeRates":{"BTC":{"USD":9250,"BCH":22.627201565557733},"BCH":{"USD":408.4,"BTC":0.044184453866518376}},"supportedTransactionCurrencies":{"BTC":{"enabled":true},"BCH":{"enabled":true}},"minerFees":{"BTC":{"satoshisPerByte":1,"totalFee":100},"BCH":{"satoshisPerByte":0,"totalFee":0}},"paymentCodes":{"BTC":{"BIP72b":"bitcoin:?r=https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV","BIP73":"https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV"},"BCH":{"BIP72b":"bitcoincash:?r=https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV","BIP73":"https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV"}},"token":"767cdhmwtn7XgW1QrSkuEwiwvxjgArt7y5pRoSVfXCZjr7ysjQBS8WXhwgvsP2J4ut"}

: heartbeat
: heartbeat
: heartbeat
event: scanned
data: {"scanned":true,"userAgent":"bitpay 5.9.1 (iOS 12.3.1 - iPhone9,3)"}

event: scanned
data: {"scanned":true,"userAgent":"bitpay 5.9.1 (iOS 12.3.1 - iPhone9,3)"}

event: scanned
data: {"scanned":true,"userAgent":"bitpay 5.9.1 (iOS 12.3.1 - iPhone9,3)"}

event: scanned
data: {"scanned":true,"userAgent":"bitpay 5.9.1 (iOS 12.3.1 - iPhone9,3)"}

event: paymentPosted
data: {"paymentPosted":true}

: heartbeat
event: paymentPosted
data: {"paymentPosted":true}

event: statechange
data: {"url":"https://test.bitpay.com/invoice?id=HTaH7F5KircpUCMWubCwzV","status":"paid","price":2,"currency":"USD","orderId":"Test invoice 1","invoiceTime":1561024511370,"expirationTime":1561025411370,"currentTime":1561024586930,"guid":"2be8c694-84d6-a0ff-3b47-9c859ba5d817","id":"HTaH7F5KircpUCMWubCwzV","lowFeeDetected":false,"amountPaid":21700,"exceptionStatus":false,"refundAddressRequestPending":false,"buyerProvidedInfo":{"name":"Fox Mulder","phoneNumber":"555-123-456","selectedTransactionCurrency":"BTC"},"paymentSubtotals":{"BTC":21600,"BCH":489700},"paymentTotals":{"BTC":21700,"BCH":489700},"paymentDisplayTotals":{"BTC":"0.000217","BCH":"0.004897"},"paymentDisplaySubTotals":{"BTC":"0.000216","BCH":"0.004897"},"exchangeRates":{"BTC":{"USD":9250,"BCH":22.627201565557733},"BCH":{"USD":408.4,"BTC":0.044184453866518376}},"supportedTransactionCurrencies":{"BTC":{"enabled":true},"BCH":{"enabled":true}},"minerFees":{"BTC":{"satoshisPerByte":1,"totalFee":100},"BCH":{"satoshisPerByte":0,"totalFee":0}},"transactionCurrency":"BTC","paymentCodes":{"BTC":{"BIP72b":"bitcoin:?r=https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV","BIP73":"https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV"},"BCH":{"BIP72b":"bitcoincash:?r=https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV","BIP73":"https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV"}}}

: heartbeat
: heartbeat
: heartbeat
event: statechange
data: {"url":"https://test.bitpay.com/invoice?id=HTaH7F5KircpUCMWubCwzV","status":"confirmed","price":2,"currency":"USD","orderId":"Test invoice 1","invoiceTime":1561024511370,"expirationTime":1561025411370,"currentTime":1561024635301,"guid":"2be8c694-84d6-a0ff-3b47-9c859ba5d817","id":"HTaH7F5KircpUCMWubCwzV","lowFeeDetected":false,"amountPaid":21700,"exceptionStatus":false,"refundAddressRequestPending":false,"buyerProvidedInfo":{"name":"Fox Mulder","phoneNumber":"555-123-456","selectedTransactionCurrency":"BTC"},"paymentSubtotals":{"BTC":21600,"BCH":489700},"paymentTotals":{"BTC":21700,"BCH":489700},"paymentDisplayTotals":{"BTC":"0.000217","BCH":"0.004897"},"paymentDisplaySubTotals":{"BTC":"0.000216","BCH":"0.004897"},"exchangeRates":{"BTC":{"USD":9250,"BCH":22.627201565557733},"BCH":{"USD":408.4,"BTC":0.044184453866518376}},"supportedTransactionCurrencies":{"BTC":{"enabled":true},"BCH":{"enabled":true}},"minerFees":{"BTC":{"satoshisPerByte":1,"totalFee":100},"BCH":{"satoshisPerByte":0,"totalFee":0}},"transactionCurrency":"BTC","paymentCodes":{"BTC":{"BIP72b":"bitcoin:?r=https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV","BIP73":"https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV"},"BCH":{"BIP72b":"bitcoincash:?r=https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV","BIP73":"https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV"}}}

: heartbeat
: heartbeat
event: statechange
data: {"url":"https://test.bitpay.com/invoice?id=HTaH7F5KircpUCMWubCwzV","status":"confirmed","price":2,"currency":"USD","orderId":"Test invoice 1","invoiceTime":1561024511370,"expirationTime":1561025411370,"currentTime":1561024759602,"guid":"2be8c694-84d6-a0ff-3b47-9c859ba5d817","id":"HTaH7F5KircpUCMWubCwzV","lowFeeDetected":false,"amountPaid":21700,"exceptionStatus":false,"refundAddressRequestPending":false,"buyerProvidedInfo":{"name":"Fox Mulder","phoneNumber":"555-123-456","selectedTransactionCurrency":"BTC"},"paymentSubtotals":{"BTC":21600,"BCH":489700},"paymentTotals":{"BTC":21700,"BCH":489700},"paymentDisplayTotals":{"BTC":"0.000217","BCH":"0.004897"},"paymentDisplaySubTotals":{"BTC":"0.000216","BCH":"0.004897"},"exchangeRates":{"BTC":{"USD":9250,"BCH":22.627201565557733},"BCH":{"USD":408.4,"BTC":0.044184453866518376}},"supportedTransactionCurrencies":{"BTC":{"enabled":true},"BCH":{"enabled":true}},"minerFees":{"BTC":{"satoshisPerByte":1,"totalFee":100},"BCH":{"satoshisPerByte":0,"totalFee":0}},"transactionCurrency":"BTC","paymentCodes":{"BTC":{"BIP72b":"bitcoin:?r=https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV","BIP73":"https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV"},"BCH":{"BIP72b":"bitcoincash:?r=https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV","BIP73":"https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV"}}}

: heartbeat
: heartbeat
: heartbeat
event: statechange
data: {"url":"https://test.bitpay.com/invoice?id=HTaH7F5KircpUCMWubCwzV","status":"confirmed","price":2,"currency":"USD","orderId":"Test invoice 1","invoiceTime":1561024511370,"expirationTime":1561025411370,"currentTime":1561025160469,"guid":"2be8c694-84d6-a0ff-3b47-9c859ba5d817","id":"HTaH7F5KircpUCMWubCwzV","lowFeeDetected":false,"amountPaid":21700,"exceptionStatus":false,"refundAddressRequestPending":false,"buyerProvidedInfo":{"name":"Fox Mulder","phoneNumber":"555-123-456","selectedTransactionCurrency":"BTC"},"paymentSubtotals":{"BTC":21600,"BCH":489700},"paymentTotals":{"BTC":21700,"BCH":489700},"paymentDisplayTotals":{"BTC":"0.000217","BCH":"0.004897"},"paymentDisplaySubTotals":{"BTC":"0.000216","BCH":"0.004897"},"exchangeRates":{"BTC":{"USD":9250,"BCH":22.627201565557733},"BCH":{"USD":408.4,"BTC":0.044184453866518376}},"supportedTransactionCurrencies":{"BTC":{"enabled":true},"BCH":{"enabled":true}},"minerFees":{"BTC":{"satoshisPerByte":1,"totalFee":100},"BCH":{"satoshisPerByte":0,"totalFee":0}},"transactionCurrency":"BTC","paymentCodes":{"BTC":{"BIP72b":"bitcoin:?r=https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV","BIP73":"https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV"},"BCH":{"BIP72b":"bitcoincash:?r=https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV","BIP73":"https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV"}}}

: heartbeat
: heartbeat
event: statechange
data: {"url":"https://test.bitpay.com/invoice?id=HTaH7F5KircpUCMWubCwzV","status":"confirmed","price":2,"currency":"USD","orderId":"Test invoice 1","invoiceTime":1561024511370,"expirationTime":1561025411370,"currentTime":1561025193519,"guid":"2be8c694-84d6-a0ff-3b47-9c859ba5d817","id":"HTaH7F5KircpUCMWubCwzV","lowFeeDetected":false,"amountPaid":21700,"exceptionStatus":false,"refundAddressRequestPending":false,"buyerProvidedInfo":{"name":"Fox Mulder","phoneNumber":"555-123-456","selectedTransactionCurrency":"BTC"},"paymentSubtotals":{"BTC":21600,"BCH":489700},"paymentTotals":{"BTC":21700,"BCH":489700},"paymentDisplayTotals":{"BTC":"0.000217","BCH":"0.004897"},"paymentDisplaySubTotals":{"BTC":"0.000216","BCH":"0.004897"},"exchangeRates":{"BTC":{"USD":9250,"BCH":22.627201565557733},"BCH":{"USD":408.4,"BTC":0.044184453866518376}},"supportedTransactionCurrencies":{"BTC":{"enabled":true},"BCH":{"enabled":true}},"minerFees":{"BTC":{"satoshisPerByte":1,"totalFee":100},"BCH":{"satoshisPerByte":0,"totalFee":0}},"transactionCurrency":"BTC","paymentCodes":{"BTC":{"BIP72b":"bitcoin:?r=https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV","BIP73":"https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV"},"BCH":{"BIP72b":"bitcoincash:?r=https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV","BIP73":"https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV"}}}

event: statechange
data: {"url":"https://test.bitpay.com/invoice?id=HTaH7F5KircpUCMWubCwzV","status":"confirmed","price":2,"currency":"USD","orderId":"Test invoice 1","invoiceTime":1561024511370,"expirationTime":1561025411370,"currentTime":1561025198412,"guid":"2be8c694-84d6-a0ff-3b47-9c859ba5d817","id":"HTaH7F5KircpUCMWubCwzV","lowFeeDetected":false,"amountPaid":21700,"exceptionStatus":false,"refundAddressRequestPending":false,"buyerProvidedInfo":{"name":"Fox Mulder","phoneNumber":"555-123-456","selectedTransactionCurrency":"BTC"},"paymentSubtotals":{"BTC":21600,"BCH":489700},"paymentTotals":{"BTC":21700,"BCH":489700},"paymentDisplayTotals":{"BTC":"0.000217","BCH":"0.004897"},"paymentDisplaySubTotals":{"BTC":"0.000216","BCH":"0.004897"},"exchangeRates":{"BTC":{"USD":9250,"BCH":22.627201565557733},"BCH":{"USD":408.4,"BTC":0.044184453866518376}},"supportedTransactionCurrencies":{"BTC":{"enabled":true},"BCH":{"enabled":true}},"minerFees":{"BTC":{"satoshisPerByte":1,"totalFee":100},"BCH":{"satoshisPerByte":0,"totalFee":0}},"transactionCurrency":"BTC","paymentCodes":{"BTC":{"BIP72b":"bitcoin:?r=https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV","BIP73":"https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV"},"BCH":{"BIP72b":"bitcoincash:?r=https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV","BIP73":"https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV"}}}

: heartbeat
: heartbeat
: heartbeat
: heartbeat
event: statechange
data: {"url":"https://test.bitpay.com/invoice?id=HTaH7F5KircpUCMWubCwzV","status":"complete","price":2,"currency":"USD","orderId":"Test invoice 1","invoiceTime":1561024511370,"expirationTime":1561025411370,"currentTime":1561025255051,"guid":"2be8c694-84d6-a0ff-3b47-9c859ba5d817","id":"HTaH7F5KircpUCMWubCwzV","lowFeeDetected":false,"amountPaid":21700,"exceptionStatus":false,"refundAddressRequestPending":false,"buyerProvidedInfo":{"name":"Fox Mulder","phoneNumber":"555-123-456","selectedTransactionCurrency":"BTC"},"paymentSubtotals":{"BTC":21600,"BCH":489700},"paymentTotals":{"BTC":21700,"BCH":489700},"paymentDisplayTotals":{"BTC":"0.000217","BCH":"0.004897"},"paymentDisplaySubTotals":{"BTC":"0.000216","BCH":"0.004897"},"exchangeRates":{"BTC":{"USD":9250,"BCH":22.627201565557733},"BCH":{"USD":408.4,"BTC":0.044184453866518376}},"supportedTransactionCurrencies":{"BTC":{"enabled":true},"BCH":{"enabled":true}},"minerFees":{"BTC":{"satoshisPerByte":1,"totalFee":100},"BCH":{"satoshisPerByte":0,"totalFee":0}},"transactionCurrency":"BTC","paymentCodes":{"BTC":{"BIP72b":"bitcoin:?r=https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV","BIP73":"https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV"},"BCH":{"BIP72b":"bitcoincash:?r=https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV","BIP73":"https://test.bitpay.com/i/HTaH7F5KircpUCMWubCwzV"}}}

: heartbeat

The "event bus" provides a real-time interface for API consumers to subscribe to changes that occur to a given resource. The bus implements HTTP long-polling and is compatible with the SSE (Server Sent Events) and EventSource specifications. API consumers need only a valid resource token retrieved from the existing REST API in order to subscribe.

In order to access an event stream via the bus, you have to request a "bus pass" for the resource to which you'd like to subscribe. These are special tokens that may only be used for receiving events via the bus. Bus passes are issued via API request. For example, to request a bus pass for a given invoice.

Once you have retrieved the bus pass, It's pretty simple. Send a GET request to the path configured for the bus - let's say it's bitpay.com/events including the appropriate parameters:

Once you've opened the connection, you'll want to listen for chunks of data to be passed to you. Each chunk represents an event. Since the bus adheres to the SSE/EventSource specification, chunks are passed back in the format:

event: <event_type>

data: {"some":"json"}

Type of Events

Browsers interpret the "event" property of each chunk and allow you to listen for it by adding an event listener directly to your EventSource instance. There are a few event types that the bus will expose:

See below an example of constructed URL which can be used to listen to invoice events. In this example, the invoice QR code was scanned and paid using a BitPay wallet.

As this "bus pass" was retrieved using the public facade https://test.bitpay.com/events?token=767cdhmwtn7XgW1QrSkuEwiwvxjgArt7y5pRoSVfXCZjr7ysjQBS8WXhwgvsP2J4ut&action=subscribe&events[]=payment&events[]=confirmation&events[]=paymentRejected&events[]=scanned&events[]=paymentPosted

Refund an invoice

POST
https://bitpay.com/invoices/<invoiceId>/refunds
Facades

merchant

HTTP Request

via the merchant facade (signed requests)

curl -X POST -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572" -H "x-signature: 3045022100fd0e5bdf6552a30fab4c546d790414e30e3e2cfb859b66a125340cd5e24ed2ba02203d0e4a4d5ed1e0c9a53cf68916afe29fe91bb989bb3550adf4b546cad9d40a08" -d '{"refundEmail":"fox.mulder@trustno.one","amount":5,"currency":"USD","token":"5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn"}' "https://test.bitpay.com/invoices/Pspr4saiFdhDyZxw8gy1SX/refunds"
var resourceUrl = "https://test.bitpay.com/invoices";
var invoiceId = "Pspr4saiFdhDyZxw8gy1SX";
var httpWebRequest = (HttpWebRequest)WebRequest.Create(resourceUrl + "/" + invoiceId + "/refunds");
httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.Headers.Add(
    "x-identity",
    "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
    );
httpWebRequest.Headers.Add(
    "x-signature",
    "3045022100fd0e5bdf6552a30fab4c546d790414e30e3e2cfb859b66a125340cd5e24ed2ba02203d0e4a4d5ed1e0c9a53cf68916afe29fe91bb989bb3550adf4b546cad9d40a08"
    );
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "POST";

string json = "{" +
                  "\"refundEmail\":\"fox.mulder@trustno.one\"," +
                  "\"amount\":5," +
                  "\"currency\":\"USD\"," +
                  "\"token\":\"5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn\"" +
              "}";

using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
{

    streamWriter.Write(json);
    streamWriter.Flush();
    streamWriter.Close();
}

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/invoices";
var invoiceId = "Pspr4saiFdhDyZxw8gy1SX";

var json = "{" +
                 "\"refundEmail\":\"fox.mulder@trustno.one\"," +
                 "\"amount\":5," +
                 "\"currency\":\"USD\"," +
                 "\"token\":\"5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn\"" +
             "}";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request=HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .header(
           "x-identity",
           "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
   )
   .header(
           "x-signature",
           "3045022100fd0e5bdf6552a30fab4c546d790414e30e3e2cfb859b66a125340cd5e24ed2ba02203d0e4a4d5ed1e0c9a53cf68916afe29fe91bb989bb3550adf4b546cad9d40a08"
   )
   .uri(URI.create(resourceUrl + "/" + invoiceId + "/refunds"))
   .POST(HttpRequest.BodyPublishers.ofString(json))
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/invoices';
$invoiceId = 'Pspr4saiFdhDyZxw8gy1SX';

$postData = json_encode([
   'refundEmail' => 'fox.mulder@trustno.one',
   'amount' => 5,
   'currency' => 'USD',
   'token' => '5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn'
]);

$curlCli = curl_init($resourceUrl . '/' . $invoiceId . '/refunds');

curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json',
   'x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature: 3045022100fd0e5bdf6552a30fab4c546d790414e30e3e2cfb859b66a125340cd5e24ed2ba02203d0e4a4d5ed1e0c9a53cf68916afe29fe91bb989bb3550adf4b546cad9d40a08'
]);

curl_setopt($curlCli, CURLOPT_POSTFIELDS, stripslashes($postData));

$result = curl_exec($curlCli);
$resultData = json_decode($result, TRUE);
curl_close($curlCli);

echo $resultData;

?>
let request = require('request');

let resource_url = 'https://test.bitpay.com/invoices';
let invoice_id = 'Pspr4saiFdhDyZxw8gy1SX';
let post_data = {
   "refundEmail": "fox.mulder@trustno.one",
   "amount": 5,
   "currency": "USD",
   "token": "5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn"
};
let headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "X-Identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "X-Signature": "3045022100fd0e5bdf6552a30fab4c546d790414e30e3e2cfb859b66a125340cd5e24ed2ba02203d0e4a4d5ed1e0c9a53cf68916afe29fe91bb989bb3550adf4b546cad9d40a08"
};
let options = {
   url: resource_url + '/' + invoice_id + '/refunds',
   method: 'POST',
   json: post_data,
   headers: headers
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/invoices"
invoiceId := "Pspr4saiFdhDyZxw8gy1SX"
postData := []byte(`{
   "refundEmail": "fox.mulder@trustno.one",
   "amount": 5,
   "currency": "USD",
   "token": "5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn"
}`)

request, err := http.NewRequest("POST", resourceUrl + "/" + invoiceId + "/refunds", bytes.NewBuffer(postData))
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")
request.Header.Set("x-identity", "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572")
request.Header.Set("x-signature", "3045022100fd0e5bdf6552a30fab4c546d790414e30e3e2cfb859b66a125340cd5e24ed2ba02203d0e4a4d5ed1e0c9a53cf68916afe29fe91bb989bb3550adf4b546cad9d40a08")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}
defer response.Body.Close()

body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/invoices'
invoice_id = 'Pspr4saiFdhDyZxw8gy1SX'
post_data = {
   'refundEmail': 'fox.mulder@trustno.one',
   'amount': 5,
   'currency': 'USD',
   'token': '5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn'
}
headers = {
   'x-accept-version': '2.0.0',
   'Content-Type': 'application/json',
   'x-identity': '031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature': '3045022100fd0e5bdf6552a30fab4c546d790414e30e3e2cfb859b66a125340cd5e24ed2ba02203d0e4a4d5ed1e0c9a53cf68916afe29fe91bb989bb3550adf4b546cad9d40a08'
}
response = requests.post(url=resource_url + '/' + invoice_id + '/refunds', data=json.dumps(post_data),
                        headers=headers).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/invoices"
invoice_id = "Pspr4saiFdhDyZxw8gy1SX"
post_data = {
   "refundEmail": "fox.mulder@trustno.one",
   "amount": 5,
   "currency": "USD",
   "token": "5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn"
}
headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "X-Identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "X-Signature": "3045022100fd0e5bdf6552a30fab4c546d790414e30e3e2cfb859b66a125340cd5e24ed2ba02203d0e4a4d5ed1e0c9a53cf68916afe29fe91bb989bb3550adf4b546cad9d40a08"
}
uri = URI.parse(resource_url + "/" + invoice_id + "/refunds")
request = Net::HTTP::Post.new(uri.to_s, headers)
request.body = post_data.to_json

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body
URL Parameters
Parameter Type Presence
<invoiceId>
the id of the invoice you want to refund.
string M
Headers
fields Presence
x-accept-version:
must be set to 2.0.0 for request to the BitPay API.
M
content-type
must be set to application/json for request to the BitPay API.
M
x-identity
the hexadecimal public key generated from the client private key.
M
x-signature
header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key.
M
Body
Name Type Presence
refundEmail
email address to which you want BitPay to send the refund link.
string M
amount
The amount to be refunded, denominated in the invoice original currency - partial refunds are supported
number M
currency
The currency in which to price the refund, same as the invoice original currency.
string M
token
The resource token for the <invoiceId> you want to refund. You need to retrieve this token from the invoice object itself, if using the merchant facade (see section Fetch an invoice by id).
string M
HTTP Response

For invoices fetched via the merchant facade (signed requests)

{
  "success": true
}
Body
Name Type
success
set to true when a refund is successfully requested. At the same time an email is sent to the refundEmail address provided in the HTTP request. It contains a link to the invoice where the buyer can provide his address for the refund
boolean

Fetch the status of all refunds on an invoice

GET
https://bitpay.com/invoices/<invoiceId>/refunds
Facades

merchant

HTTP Request

via the merchant facade (signed requests)

curl -X GET -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572" -H "x-signature: 3045022100e60e20c2f42c66d0ab6d95485607c880c1412f5e3f1a3c6716db20fc12266d15022047fe67ff944a5754ec67075ea81e5ae57df94d061a034daa920144bd01ba51b1" "https://test.bitpay.com/invoices/Pspr4saiFdhDyZxw8gy1SX/refunds?token=5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn"
var resourceUrl = "https://test.bitpay.com/invoices";
var invoiceId = "Pspr4saiFdhDyZxw8gy1SX";
var token = "5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn";
var httpWebRequest = (HttpWebRequest)WebRequest.Create(resourceUrl + "/" + invoiceId + "/refunds?token=" + token);
httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.Headers.Add(
    "x-identity",
    "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
);
httpWebRequest.Headers.Add(
    "x-signature",
    "3045022100e60e20c2f42c66d0ab6d95485607c880c1412f5e3f1a3c6716db20fc12266d15022047fe67ff944a5754ec67075ea81e5ae57df94d061a034daa920144bd01ba51b1"
);
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "GET";

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/invoices";
var invoiceId = "Pspr4saiFdhDyZxw8gy1SX";
var token = "5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request=HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .header(
           "x-identity",
           "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
   )
   .header(
           "x-signature",
           "3045022100e60e20c2f42c66d0ab6d95485607c880c1412f5e3f1a3c6716db20fc12266d15022047fe67ff944a5754ec67075ea81e5ae57df94d061a034daa920144bd01ba51b1"
   )
   .uri(URI.create(resourceUrl + "/" + invoiceId + "/refunds?token=" + token))
   .GET()
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/invoices';
$invoiceId = 'Pspr4saiFdhDyZxw8gy1SX';
$token = '5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn';

$curlCli = curl_init($resourceUrl . '/' . $invoiceId . '/refunds?token=' . $token);

curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json',
   'x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature: 3045022100e60e20c2f42c66d0ab6d95485607c880c1412f5e3f1a3c6716db20fc12266d15022047fe67ff944a5754ec67075ea81e5ae57df94d061a034daa920144bd01ba51b1'
]);

$result = curl_exec($curlCli);
$resultData = json_decode($result, TRUE);
curl_close($curlCli);

echo $resultData;

?>
let request = require('request');

let resource_url = 'https://test.bitpay.com/invoices';
let invoice_id = 'Pspr4saiFdhDyZxw8gy1SX';
let token = '5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn';
let headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "3045022100e60e20c2f42c66d0ab6d95485607c880c1412f5e3f1a3c6716db20fc12266d15022047fe67ff944a5754ec67075ea81e5ae57df94d061a034daa920144bd01ba51b1"
};
let options = {
   url: resource_url + '/' + invoice_id + '/refunds?token=' + token,
   method: 'GET',
   headers: headers,
   json: true
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/invoices"
invoiceId := "Pspr4saiFdhDyZxw8gy1SX"
token := "5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn"

request, err := http.NewRequest("GET", resourceUrl + "/" + invoiceId + "/refunds?token=" + token, nil)
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")
request.Header.Set("x-identity", "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572")
request.Header.Set("x-signature", "3045022100e60e20c2f42c66d0ab6d95485607c880c1412f5e3f1a3c6716db20fc12266d15022047fe67ff944a5754ec67075ea81e5ae57df94d061a034daa920144bd01ba51b1")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}

defer response.Body.Close()
body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/invoices'
invoice_id = 'Pspr4saiFdhDyZxw8gy1SX'
token = '5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn'
headers = {
   'x-accept-version': '2.0.0',
   'Content-Type': 'application/json',
   'x-identity': '031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature': '3045022100e60e20c2f42c66d0ab6d95485607c880c1412f5e3f1a3c6716db20fc12266d15022047fe67ff944a5754ec67075ea81e5ae57df94d061a034daa920144bd01ba51b1'
}
response = requests.get(url=resource_url + '/' + invoice_id + '/refunds?token=' + token, headers=headers).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/invoices"
invoice_id = "Pspr4saiFdhDyZxw8gy1SX"
token = "5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn"
headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "3045022100e60e20c2f42c66d0ab6d95485607c880c1412f5e3f1a3c6716db20fc12266d15022047fe67ff944a5754ec67075ea81e5ae57df94d061a034daa920144bd01ba51b1"
}
uri = URI.parse(resource_url + "/" + invoice_id + "/refunds?token=" + token)
request = Net::HTTP::Get.new(uri.to_s, headers)

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body
URL Parameters
Parameter Type Presence
<invoiceId>
The id of the invoice you want to look up.
string M
?token=
The resource token for the <invoiceId> you want to look up. You need to retrieve this token from the invoice object itself, using the merchant facade (see section Fetch an invoice by id).
string M
Headers
fields Presence
x-accept-version:
must be set to 2.0.0 for request to the BitPay API
M
content-type
must be set to application/json for request to the BitPay API
M
x-identity
the hexadecimal public key generated from the client private key
M
x-signature
header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key
M
HTTP Response

For invoices fetched via the merchant facade (signed requests)

{
  "facade": "merchant/supportRequest",
  "data": [
    {
      "id": "3qq5JP7i9eCLyAAHYAZ4cm",
      "requestDate": "2019-05-24T08:30:20.006Z",
      "status": "pending",
      "params": {
        "requesterType": "purchaser",
        "requesterEmail": "fox.mulder@trustno.one",
        "amount": 5,
        "currency": "USD",
        "email": "fox.mulder@trustno.one",
        "purchaserNotifyEmail": "fox.mulder@trustno.one",
        "refundAddress": "moUHUvgGqUwDHvdi8GRpAU6MC2xpQqgCGU",
        "commit": false,
        "doit": false,
        "supportRequestEid": "3qq5JP7i9eCLyAAHYAZ4cm"
      },
      "token": "sfxVmZyCzRSoNcCktL3t6D1EKREEud2fsLohrKuiZ9TqHFYEhuUzNF3GxNytxBMon"
    }
  ]
}
Body

The response from the BitPay server will contain a refund object if a refund request was successfully created for a given invoice.

When you submit a refund request via the API, BitPay sends an email to the consumer containing a secure link for him to submit his refund address, in the same cryptocurrency used to initially pay the invoice.

The refund object is only created in the system after the consumer submitted his refund address. This endpoint allows you to view the corresponding refund object.

Name Type
facade
Facade used to view the refund object created on a given invoice, set to "merchant/supportRequest"
string
data
Refund objects with status "pending" or "success" created for the corresponding invoice will be logged in this array. If no refund objects were successfully created, the array will be empty. Cancelled refund requests are also not logged in this array.
array
id
Contains the refund requestId.
string
requestDate
Date/time of the refund request. ISO-8601 format yyyy-mm-ddThh:mm:ssZ. (UTC)
string
status
Status of the refund request, can be:

  • "pending" If the refund request still needs to be executed by BitPay.
  • "success" Once the refund request has been executed.
  • "failure" If the refund request has been declined.

string
params
Object containing the refund request parameters.
object
requesterType
set to "purchaser"
string
requesterEmail
Purchaser's email address stored on the invoice
string
amount
Amount to be refunded in the currency indicated in the refund object.
string
currency
Reference currency used for the refund, usually the same as the currency used to create the invoice.
string
email
Purchaser's email address stored on the invoice
string
purchaserNotifyEmail
Email address to which the refund link was sent. This is equal to the refundEmail used when submitting the refund request.
string
refundAddress
Contains the cryptocurrency address provided by the customer via the refund link which was emailed to him.
string
commit
For internal use. This field can be ignored in merchant implementations.
string
doit
For internal use. This field can be ignored in merchant implementations.
string
supportRequestEid
Contains the refund requestId.
string
token
refund resource token. This token is derived from the API token initially used to refund the invoice and is tied to the specific refund object created.
string

Fetch the status of a specific refund request

GET
https://bitpay.com/invoices/<invoiceId>/refunds/<requestId>
Facades

merchant

HTTP Request

via the merchant facade (signed requests)

curl -X GET -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572" -H "x-signature: 3044022023f60638d74d2f6af1ba02106b677165a64e7c36f483216248bfc0a516da9d1b022005a36994ffeefe0a7ae65e8db827e3d4cef9c0eeed3081548210b5653dee3d94" "https://test.bitpay.com/invoices/RhHwkycGaDskrEhGfXWnRG/refunds/BpRciwDGMXYR4kDPynsaRA?token=5z1h2xr2RRrxrZf3k7SScizDGeDj4VZ8Xi8MHqKopdj1xH2zqrSBKVHtEdEUYAARQT"
var resourceUrl = "https://test.bitpay.com/invoices";
var invoiceId = "RhHwkycGaDskrEhGfXWnRG";
var refundRequestId = "BpRciwDGMXYR4kDPynsaRA";
var token = "5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn";
var httpWebRequest = (HttpWebRequest)WebRequest.Create(resourceUrl + "/" + invoiceId + "/refunds/" + refundRequestId + "?token=" + token);

httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.Headers.Add(
    "x-identity",
    "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
);
httpWebRequest.Headers.Add(
    "x-signature",
    "3044022023f60638d74d2f6af1ba02106b677165a64e7c36f483216248bfc0a516da9d1b022005a36994ffeefe0a7ae65e8db827e3d4cef9c0eeed3081548210b5653dee3d94"
);
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "GET";

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/invoices";
var invoiceId = "RhHwkycGaDskrEhGfXWnRG";
var refundRequestId = "BpRciwDGMXYR4kDPynsaRA";
var token = "5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request=HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .header(
       "x-identity",
       "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
   )
   .header(
       "x-signature",
       "3044022023f60638d74d2f6af1ba02106b677165a64e7c36f483216248bfc0a516da9d1b022005a36994ffeefe0a7ae65e8db827e3d4cef9c0eeed3081548210b5653dee3d94"
   )
   .uri(URI.create(resourceUrl + "/" + invoiceId + "/refunds/" + refundRequestId + "?token=" + token))
   .GET()
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/invoices';
$invoiceId = 'RhHwkycGaDskrEhGfXWnRG';
$refundRequestId = 'BpRciwDGMXYR4kDPynsaRA';
$token = '5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn';

$curlCli = curl_init($resourceUrl . '/' . $invoiceId . '/refunds/' . $refundRequestId . '?token=' . $token);

curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json',
   'x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature: 3044022023f60638d74d2f6af1ba02106b677165a64e7c36f483216248bfc0a516da9d1b022005a36994ffeefe0a7ae65e8db827e3d4cef9c0eeed3081548210b5653dee3d94'
]);

$result = curl_exec($curlCli);
$resultData = json_decode($result, TRUE);
curl_close($curlCli);

echo $resultData;

?>
let request = require('request');

let resource_url = 'https://test.bitpay.com/invoices';
let invoice_id = 'RhHwkycGaDskrEhGfXWnRG';
let refundRequestId = 'BpRciwDGMXYR4kDPynsaRA';
let token = '5z1h2xr2RRrxrZf3k7SScizDGeDj4VZ8Xi8MHqKopdj1xH2zqrSBKVHtEdEUYAARQT';
let headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "3044022023f60638d74d2f6af1ba02106b677165a64e7c36f483216248bfc0a516da9d1b022005a36994ffeefe0a7ae65e8db827e3d4cef9c0eeed3081548210b5653dee3d94"
};
let options = {
   url: resource_url + '/' + invoice_id + '/refunds/' + refundRequestId + '?token=' + token,
   method: 'GET',
   headers: headers,
   json: true
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/invoices"
invoiceId := "RhHwkycGaDskrEhGfXWnRG"
refundRequestId := "BpRciwDGMXYR4kDPynsaRA"
token := "5z1h2xr2RRrxrZf3k7SScizDGeDj4VZ8Xi8MHqKopdj1xH2zqrSBKVHtEdEUYAARQT"

request, err := http.NewRequest("GET", resourceUrl + "/" + invoiceId + "/refunds/" + refundRequestId + "?token=" + token, nil)
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")
request.Header.Set("x-identity", "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572")
request.Header.Set("x-signature", "3044022023f60638d74d2f6af1ba02106b677165a64e7c36f483216248bfc0a516da9d1b022005a36994ffeefe0a7ae65e8db827e3d4cef9c0eeed3081548210b5653dee3d94")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}
defer response.Body.Close()

body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/invoices'
invoice_id = 'RhHwkycGaDskrEhGfXWnRG'
refundRequestId = 'BpRciwDGMXYR4kDPynsaRA'
token = '5z1h2xr2RRrxrZf3k7SScizDGeDj4VZ8Xi8MHqKopdj1xH2zqrSBKVHtEdEUYAARQT'
headers = {
   'x-accept-version': '2.0.0',
   'Content-Type': 'application/json',
   'x-identity': '031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature': '3044022023f60638d74d2f6af1ba02106b677165a64e7c36f483216248bfc0a516da9d1b022005a36994ffeefe0a7ae65e8db827e3d4cef9c0eeed3081548210b5653dee3d94'
}
response = requests.get(url=resource_url + '/' + invoice_id + '/refunds/' + refundRequestId + '?token=' + token,
                       headers=headers).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/invoices"
invoice_id = "RhHwkycGaDskrEhGfXWnRG"
refundRequestId = "BpRciwDGMXYR4kDPynsaRA"
token = "5z1h2xr2RRrxrZf3k7SScizDGeDj4VZ8Xi8MHqKopdj1xH2zqrSBKVHtEdEUYAARQT"
headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "3044022023f60638d74d2f6af1ba02106b677165a64e7c36f483216248bfc0a516da9d1b022005a36994ffeefe0a7ae65e8db827e3d4cef9c0eeed3081548210b5653dee3d94"
}
uri = URI.parse(resource_url + "/" + invoice_id + "/refunds/" + refundRequestId + "?token=" + token)
request = Net::HTTP::Get.new(uri.to_s, headers)

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body
URL Parameters
Parameter Type Presence
<invoiceId>
The id of the invoice you want to look up.
string M
<requestId>
The id of the refund request
string M
?token=
The resource token for the <invoiceId> you want to look up. You need to retrieve this token from the invoice object itself, using the merchant facade (see section Fetch an invoice by id).
string M
Headers
fields Presence
x-accept-version:
must be set to 2.0.0 for request to the BitPay API
M
content-type
must be set to application/json for request to the BitPay API
M
x-identity
the hexadecimal public key generated from the client private key
M
x-signature
header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key
M
HTTP Response

For a refund request fetched via the merchant facade (signed requests)

{
  "facade": "merchant/supportRequest",
  "data": {
    "id": "BpRciwDGMXYR4kDPynsaRA",
    "requestDate": "2019-05-03T15:53:21.068Z",
    "status": "success",
    "results": {
      "id": "RhHwkycGaDskrEhGfXWnRG",
      "type": "full (current rate)",
      "refundTransactionCurrency": "BTC",
      "adhoc": false,
      "bitcoinPayouts": [
        {
          "bitcoinAddress": "mo1HjNzzxnPdyEmFGU52onfNoe455Eo8uA",
          "invoiceSatoshis": 1060900,
          "refundSatoshis": 1060900,
          "refundFee": 200,
          "exRates": {
            "BTC": 1,
            "USD": 5713.250000000001,
            "BCH": 19.87217391304348
          },
          "amountFiat": 60.61,
          "fiatCurrency": "USD",
          "amountUSD": 60.61,
          "requestAmount": 60.61,
          "requestCurrency": "USD",
          "ledgerAmount": 60.61,
          "ledgerFeeAmount": 0.01,
          "ledgerCurrency": "USD",
          "processed": true,
          "txid": "edc80538322d9f8215a0f1e8b20d56b0407488f0b0d7444290a9f6b8207be0e7"
        }
      ],
      "before": {
        "status": "paidFull",
        "btcPaid": "0.011322",
        "btcDue": "0.000000",
        "price": 60.61,
        "currency": "USD",
        "balances": {
          "BTC": 0.000287,
          "USD": 137.72,
          "EUR": 0,
          "CAD": 0,
          "MXN": 0,
          "JPY": 0,
          "GBP": 0,
          "AUD": 0,
          "NZD": 0,
          "ZAR": 0
        }
      },
      "after": {
        "status": "paidFull",
        "btcPaid": "0.011322",
        "btcDue": "0.000000",
        "price": 60.61,
        "currency": "USD"
      },
      "numericId": "789949",
      "merchantName": "Test Account",
      "checks": [
        "ValidBitcoinAddress",
        "InvoiceSufficientBalance",
        "6Confirmations",
        "NotBitPayAddress",
        "LedgerSufficientBalance"
      ]
    },
    "params": {
      "requesterType": "purchaser",
      "requesterEmail": "fox.mulder@trustno.one",
      "amount": 60.61,
      "currency": "USD",
      "email": "fox.mulder@trustno.one",
      "purchaserNotifyEmail": "fox.mulder@trustno.one",
      "refundAddress": "mo1HjNzzxnPdyEmFGU52onfNoe455Eo8uA",
      "commit": false,
      "doit": false,
      "supportRequestEid": "BpRciwDGMXYR4kDPynsaRA",
      "txid": "edc80538322d9f8215a0f1e8b20d56b0407488f0b0d7444290a9f6b8207be0e7",
      "effects": {
        "id": "RhHwkycGaDskrEhGfXWnRG",
        "type": "full (current rate)",
        "refundTransactionCurrency": "BTC",
        "adhoc": false,
        "bitcoinPayouts": [
          {
            "bitcoinAddress": "mo1HjNzzxnPdyEmFGU52onfNoe455Eo8uA",
            "invoiceSatoshis": 1060900,
            "refundSatoshis": 1060900,
            "refundFee": 200,
            "exRates": {
              "BTC": 1,
              "USD": 5713.250000000001,
              "BCH": 19.87217391304348
            },
            "amountFiat": 60.61,
            "fiatCurrency": "USD",
            "amountUSD": 60.61,
            "requestAmount": 60.61,
            "requestCurrency": "USD",
            "ledgerAmount": 60.61,
            "ledgerFeeAmount": 0.01,
            "ledgerCurrency": "USD",
            "processed": true,
            "txid": "edc80538322d9f8215a0f1e8b20d56b0407488f0b0d7444290a9f6b8207be0e7"
          }
        ],
        "before": {
          "status": "paidFull",
          "btcPaid": "0.011322",
          "btcDue": "0.000000",
          "price": 60.61,
          "currency": "USD",
          "balances": {
            "BTC": 0.000287,
            "USD": 137.72,
            "EUR": 0,
            "CAD": 0,
            "MXN": 0,
            "JPY": 0,
            "GBP": 0,
            "AUD": 0,
            "NZD": 0,
            "ZAR": 0
          }
        },
        "after": {
          "status": "paidFull",
          "btcPaid": "0.011322",
          "btcDue": "0.000000",
          "price": 60.61,
          "currency": "USD"
        },
        "numericId": "789949",
        "merchantName": "Test Account",
        "checks": [
          "ValidBitcoinAddress",
          "InvoiceSufficientBalance",
          "6Confirmations",
          "NotBitPayAddress",
          "LedgerSufficientBalance"
        ]
      }
    },
    "token": "5waZy3ps27krLq856KTAwXSYtmGfdrGJA7SsNc1SrFaW3ED7PetjaEgX24KEVTrXQj"
  }
}
Body
Name Type
facade
Facade used to view the refund object created on a given invoice, set to "merchant/supportRequest"
string
data
Refund objects with status "pending" or "success" created for the corresponding invoice will be logged in this array. If no refund objects were successfully created, the array will be empty. Cancelled refund requests are also not logged in this field.
array

Cancel a specific refund request

DELETE
https://bitpay.com/invoices/<invoiceId>/refunds/<requestId>
Facades

merchant

HTTP Request

via the merchant facade (signed requests)

curl -X DELETE -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572" -H "x-signature: 3045022100e3507d4b8665923e04699752a209395eb0dc8d597350e1072043a30f42a00eb902203c188af4637a153f58eb876adb92fc8b1686ce82140407c01e2d8b1d51076230" "https://test.bitpay.com/invoices/Pspr4saiFdhDyZxw8gy1SX/refunds/3qq5JP7i9eCLyAAHYAZ4cm?token=sfxVmZyCzRSoNcCktL3t6D1EKREEud2fsLohrKuiZ9TqHFYEhuUzNF3GxNytxBMon"
var resourceUrl = "https://test.bitpay.com/invoices";
var invoiceId = "Pspr4saiFdhDyZxw8gy1SX";
var refundRequestId = "3qq5JP7i9eCLyAAHYAZ4cm";
var token = "sfxVmZyCzRSoNcCktL3t6D1EKREEud2fsLohrKuiZ9TqHFYEhuUzNF3GxNytxBMon";
var httpWebRequest = (HttpWebRequest)WebRequest.Create(resourceUrl + "/" + invoiceId + "/refunds/" + refundRequestId + "?token=" + token);

httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.Headers.Add(
    "x-identity",
    "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
);
httpWebRequest.Headers.Add(
    "x-signature",
    "3045022100e3507d4b8665923e04699752a209395eb0dc8d597350e1072043a30f42a00eb902203c188af4637a153f58eb876adb92fc8b1686ce82140407c01e2d8b1d51076230"
);
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "DELETE";

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/invoices";
var invoiceId = "Pspr4saiFdhDyZxw8gy1SX";
var refundRequestId = "3qq5JP7i9eCLyAAHYAZ4cm";
var token = "sfxVmZyCzRSoNcCktL3t6D1EKREEud2fsLohrKuiZ9TqHFYEhuUzNF3GxNytxBMon";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request=HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .header(
           "x-identity",
           "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
   )
   .header(
           "x-signature",
           "3045022100e3507d4b8665923e04699752a209395eb0dc8d597350e1072043a30f42a00eb902203c188af4637a153f58eb876adb92fc8b1686ce82140407c01e2d8b1d51076230"
   )
   .uri(URI.create(resourceUrl + "/" + invoiceId + "/refunds/" + refundRequestId + "?token=" + token))
   .DELETE()
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/invoices';
$invoiceId = 'Pspr4saiFdhDyZxw8gy1SX';
$refundRequestId = '3qq5JP7i9eCLyAAHYAZ4cm';
$token = 'sfxVmZyCzRSoNcCktL3t6D1EKREEud2fsLohrKuiZ9TqHFYEhuUzNF3GxNytxBMon';

$curlCli = curl_init($resourceUrl . '/' . $invoiceId . '/refunds/' . $refundRequestId . '?token=' . $token);

curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json',
   'x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature: 3045022100e3507d4b8665923e04699752a209395eb0dc8d597350e1072043a30f42a00eb902203c188af4637a153f58eb876adb92fc8b1686ce82140407c01e2d8b1d51076230'
]);

$result = curl_exec($curlCli);
$resultData = json_decode($result, TRUE);
curl_close($curlCli);

echo $resultData;

?>
let request = require('request');

let resource_url = 'https://test.bitpay.com/invoices';
let invoice_id = 'Pspr4saiFdhDyZxw8gy1SX';
let refundRequestId = '3qq5JP7i9eCLyAAHYAZ4cm';
let token = 'sfxVmZyCzRSoNcCktL3t6D1EKREEud2fsLohrKuiZ9TqHFYEhuUzNF3GxNytxBMon';
let headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "3045022100e3507d4b8665923e04699752a209395eb0dc8d597350e1072043a30f42a00eb902203c188af4637a153f58eb876adb92fc8b1686ce82140407c01e2d8b1d51076230"
};
let options = {
   url: resource_url + '/' + invoice_id + '/refunds/' + refundRequestId + '?token=' + token,
   method: 'DELETE',
   headers: headers,
   json: true
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/invoices"
invoiceId := "Pspr4saiFdhDyZxw8gy1SX"
refundRequestId := "3qq5JP7i9eCLyAAHYAZ4cm"
token := "sfxVmZyCzRSoNcCktL3t6D1EKREEud2fsLohrKuiZ9TqHFYEhuUzNF3GxNytxBMon"

request, err := http.NewRequest("DELETE", resourceUrl + "/" + invoiceId + "/refunds/" + refundRequestId + "?token=" + token, nil)
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")
request.Header.Set("x-identity", "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572")
request.Header.Set("x-signature", "3045022100e3507d4b8665923e04699752a209395eb0dc8d597350e1072043a30f42a00eb902203c188af4637a153f58eb876adb92fc8b1686ce82140407c01e2d8b1d51076230")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}
defer response.Body.Close()

body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/invoices'
invoice_id = 'Pspr4saiFdhDyZxw8gy1SX'
refundRequestId = '3qq5JP7i9eCLyAAHYAZ4cm'
token = 'sfxVmZyCzRSoNcCktL3t6D1EKREEud2fsLohrKuiZ9TqHFYEhuUzNF3GxNytxBMon'
headers = {
   'x-accept-version': '2.0.0',
   'Content-Type': 'application/json',
   'x-identity': '031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature': '3045022100e3507d4b8665923e04699752a209395eb0dc8d597350e1072043a30f42a00eb902203c188af4637a153f58eb876adb92fc8b1686ce82140407c01e2d8b1d51076230'
}
response = requests.delete(url=resource_url + '/' + invoice_id + '/refunds/' + refundRequestId + '?token=' + token,
                          headers=headers).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/invoices"
invoice_id = "Pspr4saiFdhDyZxw8gy1SX"
refundRequestId = "3qq5JP7i9eCLyAAHYAZ4cm"
token = "sfxVmZyCzRSoNcCktL3t6D1EKREEud2fsLohrKuiZ9TqHFYEhuUzNF3GxNytxBMon"
headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "3045022100e3507d4b8665923e04699752a209395eb0dc8d597350e1072043a30f42a00eb902203c188af4637a153f58eb876adb92fc8b1686ce82140407c01e2d8b1d51076230"
}
uri = URI.parse(resource_url + "/" + invoice_id + "/refunds/" + refundRequestId + "?token=" + token)
request = Net::HTTP::Delete.new(uri.to_s, headers)

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body
URL Parameters
Parameter Type Presence
<invoiceId>
The id of the invoice for which you want to cancel a pending refund request.
string M
<requestId>
The id of the refund request you want to cancel
string M
?token=
The resource token for the refund request <requestId> you want to cancel. You need to retrieve this token from the refund object itself (see section Fetch the status of all refund requests).
string M
Headers
fields Presence
x-accept-version:
must be set to 2.0.0 for request to the BitPay API
M
content-type
must be set to application/json for request to the BitPay API
M
x-identity
the hexadecimal public key generated from the client private key
M
x-signature
header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key
M
HTTP Response

For a refund request fetched via the merchant facade (signed requests)

{
  "data": "Success"
}
Body
Name Type
data
set to "Success" once a refund request is successfully cancelled
string

Request a webhook to be resent

POST
https://bitpay.com/invoices/<invoiceId>/notifications
Facades

merchant

HTTP Request

via the merchant facade (signed requests)

curl -X POST -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572" -H "x-signature: 3045022054c60285c76e44539ef8c570e79409175b8d419d95a7380e2b15d01767a095be0221009b32ecb2dc8fc1d0fada07d345ad73ad904855a6a3bc4411c301895bbecaa02f" -d '{"token":"5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn"}' "https://test.bitpay.com/invoices/Pspr4saiFdhDyZxw8gy1SX/notifications"
var resourceUrl = "https://test.bitpay.com/invoices";
var invoiceId = "Pspr4saiFdhDyZxw8gy1SX";
var httpWebRequest = (HttpWebRequest)WebRequest.Create(resourceUrl + "/" + invoiceId + "/notifications");

httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.Headers.Add(
    "x-identity",
    "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
);
httpWebRequest.Headers.Add(
    "x-signature",
    "3045022054c60285c76e44539ef8c570e79409175b8d419d95a7380e2b15d01767a095be0221009b32ecb2dc8fc1d0fada07d345ad73ad904855a6a3bc4411c301895bbecaa02f"
);
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "POST";

string json = "{" +
                "\"token\":\"5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn\"" +
              "}";

using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
{

    streamWriter.Write(json);
    streamWriter.Flush();
    streamWriter.Close();
}

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/invoices";
var invoiceId = "Pspr4saiFdhDyZxw8gy1SX";

var json = "{" +
               "\"token\":\"5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn\"" +
             "}";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request=HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .header(
           "x-identity",
           "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
   )
   .header(
           "x-signature",
           "3045022054c60285c76e44539ef8c570e79409175b8d419d95a7380e2b15d01767a095be0221009b32ecb2dc8fc1d0fada07d345ad73ad904855a6a3bc4411c301895bbecaa02f"
   )
   .uri(URI.create(resourceUrl + "/" + invoiceId + "/notifications"))
   .POST(HttpRequest.BodyPublishers.ofString(json))
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/invoices';
$invoiceId = 'Pspr4saiFdhDyZxw8gy1SX';

$postData = json_encode([
   'token' => '5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn'
]);

$curlCli = curl_init($resourceUrl . '/' . $invoiceId . '/notifications');

curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json',
   'x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature: 3045022054c60285c76e44539ef8c570e79409175b8d419d95a7380e2b15d01767a095be0221009b32ecb2dc8fc1d0fada07d345ad73ad904855a6a3bc4411c301895bbecaa02f'
]);

curl_setopt($curlCli, CURLOPT_POSTFIELDS, stripslashes($postData));

$result = curl_exec($curlCli);
$resultData = json_decode($result, TRUE);
curl_close($curlCli);

echo $resultData;

?>
let request = require('request');

let resource_url = 'https://test.bitpay.com/invoices';
let invoice_id = 'Pspr4saiFdhDyZxw8gy1SX';
let post_data = {
   "token": "5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn"
};
let headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "3045022054c60285c76e44539ef8c570e79409175b8d419d95a7380e2b15d01767a095be0221009b32ecb2dc8fc1d0fada07d345ad73ad904855a6a3bc4411c301895bbecaa02f"
};
let options = {
   url: resource_url + '/' + invoice_id + '/notifications',
   method: 'POST',
   json: post_data,
   headers: headers
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/invoices"
invoiceId := "Pspr4saiFdhDyZxw8gy1SX"
postData := []byte(`{
   "token": "5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn"
}`)

request, err := http.NewRequest("POST", resourceUrl + "/" + invoiceId + "/notifications", bytes.NewBuffer(postData))
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")
request.Header.Set("x-identity", "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572")
request.Header.Set("x-signature", "3045022054c60285c76e44539ef8c570e79409175b8d419d95a7380e2b15d01767a095be0221009b32ecb2dc8fc1d0fada07d345ad73ad904855a6a3bc4411c301895bbecaa02f")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}
defer response.Body.Close()

body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/invoices'
invoice_id = 'Pspr4saiFdhDyZxw8gy1SX'
post_data = {
   'token': '5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn'
}
headers = {
   'x-accept-version': '2.0.0',
   'Content-Type': 'application/json',
   'x-identity': '031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature': '3045022054c60285c76e44539ef8c570e79409175b8d419d95a7380e2b15d01767a095be0221009b32ecb2dc8fc1d0fada07d345ad73ad904855a6a3bc4411c301895bbecaa02f'
}
response = requests.post(url=resource_url + '/' + invoice_id + '/notifications', data=json.dumps(post_data),
                        headers=headers).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/invoices"
invoice_id = "Pspr4saiFdhDyZxw8gy1SX"
post_data = {
   "token": "5z1h2xr2RRrxrZf3k7SSciwmtgpGzh6Bktk8QPWyFtzFDvNBA2UuCwtgTsVfTLoQEn"
}
headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "3045022054c60285c76e44539ef8c570e79409175b8d419d95a7380e2b15d01767a095be0221009b32ecb2dc8fc1d0fada07d345ad73ad904855a6a3bc4411c301895bbecaa02f"
}
uri = URI.parse(resource_url + "/" + invoice_id + "/notifications")
request = Net::HTTP::Post.new(uri.to_s, headers)
request.body = post_data.to_json

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body
URL Parameters
Parameter Type Presence
<invoiceId>
The id of the invoice for which you want the last webhook to be resent.
string M
Headers
fields Presence
x-accept-version:
must be set to 2.0.0 for request to the BitPay API
M
content-type
must be set to application/json for request to the BitPay API
M
x-identity
the hexadecimal public key generated from the client private key
M
x-signature
header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key
M
Body
fields Presence
?token=
The resource token for the <invoiceId> you want the webhook to be resent. You need to retrieve this token from the invoice object itself, using the merchant facade (see section Fetch an invoice by id).
M
HTTP Response

Example response when the webhook is successfully resent

{
  "data": "Success"
}
Body
Name Type
data
set to "Success" once the webhook has been resent for the current invoice status
string

Settlements

Settlements are transfers of payment profits from BitPay to bank accounts and bitcoin wallets owned by merchants, partners, etc. This endpoint exposes reports detailing these settlements.

Resource

Example of settlement object

{
  "facade": "merchant/settlement",
  "data": {
    "id": "RvNuCTMAkURKimwgvSVEMP",
    "accountId": "YJCgTf3jrXHkUVzLQ7y4eg",
    "status": "processing",
    "currency": "USD",
    "payoutInfo": {
      "label": "Test",
      "bankCountry": "Netherlands",
      "bankAddress": "test",
      "bankAddress2": "test",
      "bankName": "Test",
      "iban": "NL85ABNA0000000000",
      "swift": "RABONL2U",
      "accountHolderCountry": "Netherlands",
      "accountHolderCity": "test",
      "accountHolderPostalCode": "test",
      "accountHolderAddress": "test",
      "accountHolderAddress2": "test",
      "accountHolderName": "test",
      "wire": true
    },
    "dateCreated": "2018-08-23T20:45:22.742Z",
    "dateExecuted": "2018-08-23T20:47:06.912Z",
    "openingDate": "2018-08-01T13:00:00.000Z",
    "closingDate": "2018-08-23T13:00:00.000Z",
    "openingBalance": 23.13,
    "ledgerEntriesSum": 2956.77,
    "withholdings": [
      {
        "amount": 590.08,
        "code": "W005",
        "description": "Pending Refunds"
      }
    ],
    "withholdingsSum": 590.08,
    "totalAmount": 2389.82,
    "token": "5T1T5yGDEtFDYe8jEVBSYLHKewPYXZrDLvZxtXBzn69fBbZYitYQYH4BFYFvvaVU7D"
  }
}
Name Type
facade
Facade used to view settlement objects, set to "merchant/settlement".
string
data
Settlement data object
object
id
String identifying the settlement; this id will also be in the description of the corresponding bank settlement.
string
accountId
String identifying the BitPay merchant. For internal use, this field can be ignored in merchant implementations.
string
status
Status of the settlement. Possible statuses are "new", "processing", "rejected" and "completed".
string
currency
ISO 4217 3-character currency code. This is the currency associated with the settlement. Supported settlement currencies are listed on https://bitpay.com/docs/settlement
string
payoutInfo
Object containing the settlement info provided by the Merchant in his BitPay account settings
string
label
As indicated by the merchant in his settlement settings
string
bankCountry
Country where the merchant's bank account is located
string
name
account holder name
string
bank
Name of the bank used by the merchant
string
swift
SWIFT/BIC code of the merchant's bank.
string
address
This field is used to indicate the wallet address used for the settlement, if the settlement currency selected by the merchant is one of the supported crypto currency: Bitcoin (BTC), Bitcoin Cash (BCH), Paxos Standard (PAX), Gemini Dollar (GUSD) or Circle USD coin (USDC). If the settlement currency used is AUD, GBP, NZD, MXN, ZAR - this field is used to indicate the address of the merchant's bank
string
city
City of the merchant bank, field return if the settlement currency is
string
postal
Postal code of the merchant bank, field return if the settlement currency is
string
account
Bank account number of the merchant
string
sort
used to pass country specific bank fields: BSB for AUD
string
wire
If set to true, this means BitPay will be settling the account using an international transfer via the SWIFT network instead of local settlement methods like ACH(United States) or SEPA (European Economic Area)
boolean
bankName
Name of the bank used by the merchant. Field returned if "wire": true in the "payoutInfo" object
string
bankAddress
Address of the merchant's bank. Field returned if "wire": true in the "payoutInfo" object
string
bankAddress2
Address of the merchant's bank. Field returned if "wire": true in the "payoutInfo" object
string
iban
The merchant's bank account number, in the IBAN (International Bank Account Number) format. Field returned if "wire": true in the "payoutInfo" object
string
additionalInformation
When providing the settlement info via the dashboard, this field can be used by the merchant to provide additional information about the receiving bank. Field returned if "wire": true in the "payoutInfo" object
string
accountHolderName
Bank account holder name. Field returned if "wire": true in the "payoutInfo" object
string
accountHolderAddress
Bank account holder address. Field returned if "wire": true in the "payoutInfo" object
string
accountHolderAddress2
Bank account holder address. Field returned if "wire": true in the "payoutInfo" object
string
accountHolderPostalCode
Bank account holder postal code. Field returned if "wire": true in the "payoutInfo" object
string
accountHolderCity
Bank account holder city. Field returned if "wire": true in the "payoutInfo" object
string
accountHolderCountry
Bank account holder country. Field returned if "wire": true in the "payoutInfo" object
string
dateCreated
timestamp when the settlement was created. UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ
string
dateExecuted
timestamp when the settlement was executed. UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ
number
openingDate
corresponds to the closingDate of the previous settlement executed. For the first settlement of an account the value will be the BitPay merchant account creation date. UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ
number
closingDate
Date & time for last ledger entry used for the settlement. UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ
date
openingBalance
Balance of the ledger at the openingDate
string
ledgerEntriesSum
Sum of all ledger entries in the settlement, this means all the debits & credits which happened betwee openingDate and closingDate
number
withholdings
array of withholdings. Withholdings are kept on the ledger to be used later and thus withheld from this settlement. Each withholding is a JSON object containing a code, amount and description field. The possible withholding codes are:

  • W001 - Refund Reserve: a merchant can set a refund reserve for his account. This code indicate the current amount in the reserve at the moment the settlement is generated.
  • W002 - Settlement Fee: in case BitPay is charging the bank fees to the merchant, via a SWIFT wire for instance, will be posted to the ledger when the settlementReport goes into status ‘processing’. This code is not used for SEPA or ACH transfers
  • W003 - Liquidity Withholding : Used when BitPay's balance at the specific settlement bank is unsufficient to payout the full amount today
  • W004 - Insufficient Balance : in the event a case the ledger balance of the merchant drops after the settlement cut-off, the settlement amount will be adjusted.
  • W005 - Pending Refunds : in order to make sure enough funds are left on the account to execute pending refund requests.

array
withholdingsSum
Sum of all amounts that are withheld from settlement
number
totalAmount
total amount sent to the merchant; 2 decimals.

totalAmount = openingBalance + legderEntriesSum - withholdingsSum

number
token
API token for the corresponding settlement resource. This token is actually derived from the merchant facade token used during the query. This token is required to fetch the reconciliation report
string

Fetch settlements based on a date range

GET
https://bitpay.com/settlements
Facades

merchant

HTTP Request

Fetching settlement objects via the merchant facade (signed requests)

curl -X GET -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572" -H "x-signature: 3045022074186fd53d0d06d2cc23beb07f7df5e9780df91d5029246b77c87368d73320ba022100e35da1cfde9c03465e4ec4770bbc2c11d03e11f221dcbe54288530ed7be3b2b2" "https://test.bitpay.com/settlements?token=GcAUe7hgY3F2FSh95Dsy5d&status=processing&startDate=2018-8-22&endDate=2019-8-30"
var resourceUrl = "https://test.bitpay.com/settlements";
var token = "GcAUe7hgY3F2FSh95Dsy5d";
var status = "processing";
var startDate = "2019-5-1";
var endDate = "2050-5-24";

var httpWebRequest = (HttpWebRequest)WebRequest.Create(
    resourceUrl +
    "?token=" + token +
    "&status=" + status +
    "&startDate=" + startDate +
    "&endDate=" + endDate
);
httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.Headers.Add(
    "x-identity",
    "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
);
httpWebRequest.Headers.Add(
    "x-signature",
    "3045022074186fd53d0d06d2cc23beb07f7df5e9780df91d5029246b77c87368d73320ba022100e35da1cfde9c03465e4ec4770bbc2c11d03e11f221dcbe54288530ed7be3b2b2"
);
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "GET";

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/settlements";
var token = "GcAUe7hgY3F2FSh95Dsy5d";
var status = "processing";
var startDate = "2019-5-1";
var endDate = "2050-5-24";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request=HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .header(
           "x-identity",
           "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
   )
   .header(
           "x-signature",
           "3045022074186fd53d0d06d2cc23beb07f7df5e9780df91d5029246b77c87368d73320ba022100e35da1cfde9c03465e4ec4770bbc2c11d03e11f221dcbe54288530ed7be3b2b2"
   )
   .uri(URI.create(
           resourceUrl +
           "?token=" + token +
           "&status=" + status +
           "&startDate=" + startDate +
           "&endDate=" + endDate
   ))
   .GET()
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/settlements';
$token = 'GcAUe7hgY3F2FSh95Dsy5d';
$status = 'processing';
$startDate = '2019-5-1';
$endDate = '2050-5-24';

$curlCli = curl_init(
   $resourceUrl .
   '?token=' . $token .
   '&status=' . $status .
   '&startDate=' . $startDate .
   '&endDate=' . $endDate
);

curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json',
   'x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature: 3045022074186fd53d0d06d2cc23beb07f7df5e9780df91d5029246b77c87368d73320ba022100e35da1cfde9c03465e4ec4770bbc2c11d03e11f221dcbe54288530ed7be3b2b2'
]);

$result = curl_exec($curlCli);
$resultData = json_decode($result, TRUE);
curl_close($curlCli);

echo $resultData;

?>
let request = require('request');

let resource_url = 'https://test.bitpay.com/settlements';
let token = 'GcAUe7hgY3F2FSh95Dsy5d';
let status = 'processing';
let startDate = '2018-8-22';
let endDate = '2019-8-30';
let headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "3045022074186fd53d0d06d2cc23beb07f7df5e9780df91d5029246b77c87368d73320ba022100e35da1cfde9c03465e4ec4770bbc2c11d03e11f221dcbe54288530ed7be3b2b2"
};
let options = {
   url: resource_url +
       '?token=' + token +
       '&status=' + status +
       '&startDate=' + startDate +
       '&endDate=' + endDate,
   method: 'GET',
   headers: headers,
   json: true
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/settlements"
token := "GcAUe7hgY3F2FSh95Dsy5d"
status := "processing"
startDate := "2018-8-22"
endDate := "2019-8-30"

request, err := http.NewRequest(
   "GET",
   resourceUrl +
   "?token=" + token +
   "&status=" + status +
   "&startDate=" + startDate +
   "&endDate=" + endDate,
   nil)
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")
request.Header.Set("x-identity", "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572")
request.Header.Set("x-signature", "3045022074186fd53d0d06d2cc23beb07f7df5e9780df91d5029246b77c87368d73320ba022100e35da1cfde9c03465e4ec4770bbc2c11d03e11f221dcbe54288530ed7be3b2b2")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}
defer response.Body.Close()

body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/settlements'
token = 'GcAUe7hgY3F2FSh95Dsy5d'
status = 'processing'
startDate = '2019-5-1'
endDate = '2050-5-24'
headers = {
   'x-accept-version': '2.0.0',
   'Content-Type': 'application/json',
   'x-identity': '031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature': '3045022074186fd53d0d06d2cc23beb07f7df5e9780df91d5029246b77c87368d73320ba022100e35da1cfde9c03465e4ec4770bbc2c11d03e11f221dcbe54288530ed7be3b2b2'
}
response = requests.get(
   url=resource_url +
       '?token=' + token +
       '&status=' + status +
       '&startDate=' + startDate +
       '&endDate=' + endDate,
   headers=headers
).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/settlements"
token = "GcAUe7hgY3F2FSh95Dsy5d"
status = "processing"
startDate = "2018-8-22"
endDate = "2019-8-30"
headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "3045022074186fd53d0d06d2cc23beb07f7df5e9780df91d5029246b77c87368d73320ba022100e35da1cfde9c03465e4ec4770bbc2c11d03e11f221dcbe54288530ed7be3b2b2"
}
uri = URI.parse(resource_url +
   "?token=" + token +
   "&status=" + status +
   "&startDate=" + startDate +
   "&endDate=" + endDate
)
request = Net::HTTP::Get.new(uri.to_s, headers)

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body
URL Parameters
Parameter Type Presence
?token=
When fetching settlememts, pass a merchant facade token as a URL parameter .
string M
&startDate
The start of the date window to query for settlements. Format YYYY-MM-DD
string O
&endDate=
The end of the date window to query for settlements. Format YYYY-MM-DD
string O
&status=
The settlement status you want to query on
string O
¤cy=
The settlement currency you want to query on
string O
&limit=
Maximum results that the query will return (useful for paging results)
number O
&offset=
Number of results to offset (ex. skip 10 will give you results starting with the 11th result)
number O
Headers
fields Presence
x-accept-version:
must be set to 2.0.0 for request to the BitPay API
M
content-type
must be set to application/json for request to the BitPay API
M
x-identity
the hexadecimal public key generated from the client private key
M
x-signature
header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key
M
HTTP Response

Example response when fetching settlement objects for a given date range

{
  "facade": "merchant/settlement",
  "data": [
    {
      "id": "DNFnN3fFjjzLn6if5bdGJC",
      "accountId": "YJCgTf3jrXHkUVzLQ7y4eg",
      "status": "processing",
      "currency": "EUR",
      "payoutInfo": {
        "label": "Test Bank",
        "bankCountry": "United States",
        "wire": true,
        "bankName": "Test Bank",
        "bankAddress": "123 Sesame St",
        "iban": "DE91100000000123456789",
        "swift": "BOFAUS3N",
        "accountHolderName": "John Doe",
        "accountHolderAddress": "123 Sesame St",
        "accountHolderCountry": "United States"
      },
      "dateCreated": "2019-02-27T12:04:22.789Z",
      "dateExecuted": "2019-02-27T12:04:44.305Z",
      "openingDate": "2018-01-31T09:00:00.000Z",
      "closingDate": "2019-02-27T10:00:00.000Z",
      "openingBalance": 9847.5,
      "ledgerEntriesSum": -8372.07,
      "withholdings": [],
      "withholdingsSum": 0,
      "totalAmount": 1475.43,
      "token": "5T1T5yGDEtFDYe8jEVBSYLGmzjACKGtmfPg3UgbFE9z3XHtBstnF5u2EniUFa63W9K"
    },
    {
      "id": "RvNuCTMAkURKimwgvSVEMP",
      "accountId": "YJCgTf3jrXHkUVzLQ7y4eg",
      "status": "processing",
      "currency": "USD",
      "payoutInfo": {
        "label": "Test",
        "bankCountry": "Netherlands",
        "bankAddress2": "test",
        "bankAddress": "test",
        "bankName": "Test",
        "iban": "NL85ABNA0000000000",
        "swift": "RABONL2U",
        "accountHolderCountry": "United States",
        "accountHolderCity": "test",
        "accountHolderPostalCode": "test",
        "accountHolderAddress2": "test",
        "accountHolderAddress": "test",
        "accountHolderName": "test",
        "wire": true
      },
      "dateCreated": "2018-08-23T20:45:22.742Z",
      "dateExecuted": "2018-08-23T20:47:06.912Z",
      "openingDate": "2018-08-01T13:00:00.000Z",
      "closingDate": "2018-08-23T13:00:00.000Z",
      "openingBalance": 23.13,
      "ledgerEntriesSum": 2956.77,
      "withholdings": [
        {
          "amount": 590.08,
          "code": "W005",
          "description": "Pending Refunds"
        }
      ],
      "withholdingsSum": 590.08,
      "totalAmount": 2389.82,
      "token": "5T1T5yGDEtFDYe8jEVBSYLHKewPYXZrDLvZxtXBzn69fBbZYitYQYH4BFYFvvaVU7D"
    }
  ]
}

On the right side, you will find an example array of settlement objects returned in the response you will get from the BitPay server. A description of all fields is available in the settlement resource section.

Fetch a specific settlement

GET
https://bitpay.com/settlements/<settlementId>
Facades

merchant

HTTP Request

Fetching a settlement object via the merchant facade (signed requests)

curl -X GET -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572" -H "x-signature: 3046022100a9d1ec54237bf0733b6c0903bed401173313792c6a6e1f4abe7629d754b69114022100951954060a8e02fcfe2ef9ee4e43b0b159b146152aff5dad8e9262aca824f964" "https://test.bitpay.com/settlements/DNFnN3fFjjzLn6if5bdGJC?token=GcAUe7hgY3F2FSh95Dsy5d"
var resourceUrl = "https://test.bitpay.com/settlements";
var settlementId = "DNFnN3fFjjzLn6if5bdGJC";
var token = "GcAUe7hgY3F2FSh95Dsy5d";

var httpWebRequest = (HttpWebRequest)WebRequest.Create(resourceUrl + "/" + settlementId + "?token=" + token);
httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.Headers.Add(
    "x-identity",
    "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
);
httpWebRequest.Headers.Add(
    "x-signature",
    "3046022100a9d1ec54237bf0733b6c0903bed401173313792c6a6e1f4abe7629d754b69114022100951954060a8e02fcfe2ef9ee4e43b0b159b146152aff5dad8e9262aca824f964"
);
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "GET";

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/settlements";
var settlementId = "DNFnN3fFjjzLn6if5bdGJC";
var token = "GcAUe7hgY3F2FSh95Dsy5d";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request=HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .header(
           "x-identity",
           "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
   )
   .header(
           "x-signature",
           "3046022100a9d1ec54237bf0733b6c0903bed401173313792c6a6e1f4abe7629d754b69114022100951954060a8e02fcfe2ef9ee4e43b0b159b146152aff5dad8e9262aca824f964"
   )
   .uri(URI.create(resourceUrl + "/" + settlementId + "?token=" + token))
   .GET()
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/settlements';
$settlementId = "DNFnN3fFjjzLn6if5bdGJC";
$token = 'GcAUe7hgY3F2FSh95Dsy5d';

$curlCli = curl_init($resourceUrl . '/' . $settlementId . $token);

curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json',
   'x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature: 3046022100a9d1ec54237bf0733b6c0903bed401173313792c6a6e1f4abe7629d754b69114022100951954060a8e02fcfe2ef9ee4e43b0b159b146152aff5dad8e9262aca824f964'
]);

$result = curl_exec($curlCli);
$resultData = json_decode($result, TRUE);
curl_close($curlCli);

echo $resultData;

?>
let request = require('request');

let resource_url = 'https://test.bitpay.com/settlements';
let settlement_id = 'DNFnN3fFjjzLn6if5bdGJC';
let token = 'GcAUe7hgY3F2FSh95Dsy5d';
let headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "3046022100a9d1ec54237bf0733b6c0903bed401173313792c6a6e1f4abe7629d754b69114022100951954060a8e02fcfe2ef9ee4e43b0b159b146152aff5dad8e9262aca824f964"
};
let options = {
   url: resource_url + '/' + settlement_id + '?token=' + token,
   method: 'GET',
   headers: headers,
   json: true
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/settlements"
settlementId := "DNFnN3fFjjzLn6if5bdGJC"
token := "GcAUe7hgY3F2FSh95Dsy5d"

request, err := http.NewRequest("GET", resourceUrl + "/" + settlementId + "?token=" + token, nil)
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")
request.Header.Set("x-identity", "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572")
request.Header.Set("x-signature", "3046022100a9d1ec54237bf0733b6c0903bed401173313792c6a6e1f4abe7629d754b69114022100951954060a8e02fcfe2ef9ee4e43b0b159b146152aff5dad8e9262aca824f964")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}
defer response.Body.Close()

body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/settlements'
settlement_id = "DNFnN3fFjjzLn6if5bdGJC"
token = 'GcAUe7hgY3F2FSh95Dsy5d'
headers = {
   'x-accept-version': '2.0.0',
   'Content-Type': 'application/json',
   'x-identity': '031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature': '3046022100a9d1ec54237bf0733b6c0903bed401173313792c6a6e1f4abe7629d754b69114022100951954060a8e02fcfe2ef9ee4e43b0b159b146152aff5dad8e9262aca824f964'
}
response = requests.get(url=resource_url + '/' + settlement_id + '?token=' + token, headers=headers).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/settlements"
settlement_id = "DNFnN3fFjjzLn6if5bdGJC"
token = "GcAUe7hgY3F2FSh95Dsy5d"
headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "3046022100a9d1ec54237bf0733b6c0903bed401173313792c6a6e1f4abe7629d754b69114022100951954060a8e02fcfe2ef9ee4e43b0b159b146152aff5dad8e9262aca824f964"
}
uri = URI.parse(resource_url + "/" + settlement_id + "?token=" + token)
request = Net::HTTP::Get.new(uri.to_s, headers)

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body

URL Parameters
Parameter Type Presence
<settlementId>
id of the specific settlement resource to be fetched
string M
?token=
when fetching settlememts, pass a merchant facade token as a URL parameter .
string M
Headers
fields Presence
x-accept-version:
must be set to 2.0.0 for request to the BitPay API
M
content-type
must be set to application/json for request to the BitPay API
M
x-identity
the hexadecimal public key generated from the client private key
M
x-signature
header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key
M
HTTP Response

Example of settlement object

{
  "facade": "merchant/settlement",
  "data": {
    "id": "RvNuCTMAkURKimwgvSVEMP",
    "accountId": "YJCgTf3jrXHkUVzLQ7y4eg",
    "status": "processing",
    "currency": "USD",
    "payoutInfo": {
      "label": "Test",
      "bankCountry": "Netherlands",
      "bankAddress": "test",
      "bankAddress2": "test",
      "bankName": "Test",
      "iban": "NL85ABNA0000000000",
      "swift": "RABONL2U",
      "accountHolderCountry": "Netherlands",
      "accountHolderCity": "test",
      "accountHolderPostalCode": "test",
      "accountHolderAddress": "test",
      "accountHolderAddress2": "test",
      "accountHolderName": "test",
      "wire": true
    },
    "dateCreated": "2018-08-23T20:45:22.742Z",
    "dateExecuted": "2018-08-23T20:47:06.912Z",
    "openingDate": "2018-08-01T13:00:00.000Z",
    "closingDate": "2018-08-23T13:00:00.000Z",
    "openingBalance": 23.13,
    "ledgerEntriesSum": 2956.77,
    "withholdings": [
      {
        "amount": 590.08,
        "code": "W005",
        "description": "Pending Refunds"
      }
    ],
    "withholdingsSum": 590.08,
    "totalAmount": 2389.82,
    "token": "5T1T5yGDEtFDYe8jEVBSYLHKewPYXZrDLvZxtXBzn69fBbZYitYQYH4BFYFvvaVU7D"
  }
}

On the right side, you will find an example of the settlement object returned in the response you will get from the BitPay server. A description of all fields is available in the settlement resource section.

Fetch a reconciliation report

This endpoint allows merchant to retrieve a detailed report of the activity within the settlement period, in order to reconcile incoming settlements from BitPay.

GET
https://bitpay.com/settlements/<settlementId>/reconciliationReport
Facades

merchant

HTTP Request

via the merchant facade (signed requests)

curl -X GET -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572" -H "x-signature: 3045022100ef23db87d03ceedaac437d98a57f78788c06535b0462b0a396c2bbdd35b8fa840220418a3e84769e1b714c3b47ccda85d0ac4d1be2531471d00e662cd070588f81ec" "https://test.bitpay.com/settlements/RvNuCTMAkURKimwgvSVEMP/reconciliationReport?token=5T1T5yGDEtFDYe8jEVBSYLHKewPYXZrDLvZxtXBzn69fBbZYitYQYH4BFYFvvaVU7D"
var resourceUrl = "https://test.bitpay.com/settlements";
var settlementId = "RvNuCTMAkURKimwgvSVEMP";
var token = "5T1T5yGDEtFDYe8jEVBSYLHKewPYXZrDLvZxtXBzn69fBbZYitYQYH4BFYFvvaVU7D";

var httpWebRequest = (HttpWebRequest)WebRequest.Create(resourceUrl + "/" + settlementId + "/reconciliationReport?token=" + token);
httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.Headers.Add(
    "x-identity",
    "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
);
httpWebRequest.Headers.Add(
    "x-signature",
    "3045022100ef23db87d03ceedaac437d98a57f78788c06535b0462b0a396c2bbdd35b8fa840220418a3e84769e1b714c3b47ccda85d0ac4d1be2531471d00e662cd070588f81ec"
);
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "GET";

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/settlements";
var settlementId = "RvNuCTMAkURKimwgvSVEMP";
var token = "5T1T5yGDEtFDYe8jEVBSYLHKewPYXZrDLvZxtXBzn69fBbZYitYQYH4BFYFvvaVU7D";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request=HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .header(
           "x-identity",
           "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
   )
   .header(
           "x-signature",
           "3045022100ef23db87d03ceedaac437d98a57f78788c06535b0462b0a396c2bbdd35b8fa840220418a3e84769e1b714c3b47ccda85d0ac4d1be2531471d00e662cd070588f81ec"
   )
   .uri(URI.create(resourceUrl + "/" + settlementId + "/reconciliationReport?token=" + token))
   .GET()
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/settlements';
$settlementId = "RvNuCTMAkURKimwgvSVEMP";
$token = '5T1T5yGDEtFDYe8jEVBSYLHKewPYXZrDLvZxtXBzn69fBbZYitYQYH4BFYFvvaVU7D';

$curlCli = curl_init($resourceUrl . '/' . $settlementId . '/reconciliationReport?token=' . $token);

curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json',
   'x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature: 3045022100ef23db87d03ceedaac437d98a57f78788c06535b0462b0a396c2bbdd35b8fa840220418a3e84769e1b714c3b47ccda85d0ac4d1be2531471d00e662cd070588f81ec'
]);

$result = curl_exec($curlCli);
$resultData = json_decode($result, TRUE);
curl_close($curlCli);

echo $resultData;

?>
let request = require('request');

let resource_url = 'https://test.bitpay.com/settlements';
let settlement_id = 'RvNuCTMAkURKimwgvSVEMP';
let token = '5T1T5yGDEtFDYe8jEVBSYLHKewPYXZrDLvZxtXBzn69fBbZYitYQYH4BFYFvvaVU7D';
let headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "3045022100ef23db87d03ceedaac437d98a57f78788c06535b0462b0a396c2bbdd35b8fa840220418a3e84769e1b714c3b47ccda85d0ac4d1be2531471d00e662cd070588f81ec"
};
let options = {
   url: resource_url + '/' + settlement_id + '/reconciliationReport?token=' + token,
   method: 'GET',
   headers: headers,
   json: true
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/settlements"
settlementId := "RvNuCTMAkURKimwgvSVEMP"
token := "5T1T5yGDEtFDYe8jEVBSYLHKewPYXZrDLvZxtXBzn69fBbZYitYQYH4BFYFvvaVU7D"

request, err := http.NewRequest("GET", resourceUrl + "/" + settlementId + "/reconciliationReport?token=" + token, nil)
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")
request.Header.Set("x-identity", "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572")
request.Header.Set("x-signature", "3045022100ef23db87d03ceedaac437d98a57f78788c06535b0462b0a396c2bbdd35b8fa840220418a3e84769e1b714c3b47ccda85d0ac4d1be2531471d00e662cd070588f81ec")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}
defer response.Body.Close()

body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/settlements'
settlement_id = "RvNuCTMAkURKimwgvSVEMP"
token = '5T1T5yGDEtFDYe8jEVBSYLHKewPYXZrDLvZxtXBzn69fBbZYitYQYH4BFYFvvaVU7D'
headers = {
   'x-accept-version': '2.0.0',
   'Content-Type': 'application/json',
   'x-identity': '031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature': '3045022100ef23db87d03ceedaac437d98a57f78788c06535b0462b0a396c2bbdd35b8fa840220418a3e84769e1b714c3b47ccda85d0ac4d1be2531471d00e662cd070588f81ec'
}
response = requests.get(url=resource_url + '/' + settlement_id + '/reconciliationReport?token=' + token,
                       headers=headers).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/settlements"
settlement_id = "RvNuCTMAkURKimwgvSVEMP"
token = "5T1T5yGDEtFDYe8jEVBSYLHKewPYXZrDLvZxtXBzn69fBbZYitYQYH4BFYFvvaVU7D"
headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "3045022100ef23db87d03ceedaac437d98a57f78788c06535b0462b0a396c2bbdd35b8fa840220418a3e84769e1b714c3b47ccda85d0ac4d1be2531471d00e662cd070588f81ec"
}
uri = URI.parse(resource_url + "/" + settlement_id + "/reconciliationReport?token=" + token)
request = Net::HTTP::Get.new(uri.to_s, headers)

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body
URL Parameters
Parameter Type Presence
<settlementId>
id of the specific settlement resource to be fetched
string M
?token=
when fetching the reconciliation report for a specific settlement, use the API token linked to the corresponding settlement resource. This token can be retrieved via the endpoint GET https://bitpay.com/settlements/<settlementId>.
string M
Headers
fields Presence
x-accept-version:
must be set to 2.0.0 for request to the BitPay API
M
content-type
must be set to application/json for request to the BitPay API
M
x-identity
the hexadecimal public key generated from the client private key
M
x-signature
header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key
M
HTTP Response

example of reconciliation report

{
  "data": {
    "id": "RvNuCTMAkURKimwgvSVEMP",
    "accountId": "YJCgTf3jrXHkUVzLQ7y4eg",
    "status": "processing",
    "currency": "USD",
    "payoutInfo": {
      "label": "Test",
      "bankCountry": "Netherlands",
      "bankAddress": "test",
      "bankAddress2": "test",
      "bankName": "Test",
      "iban": "NL85ABNA0000000000",
      "swift": "RABONL2U",
      "accountHolderCountry": "United States",
      "accountHolderCity": "test",
      "accountHolderPostalCode": "test",
      "accountHolderAddress": "test",
      "accountHolderAddress2": "test",
      "accountHolderName": "test",
      "wire": true
    },
    "dateCreated": "2018-08-23T20:45:22.742Z",
    "dateExecuted": "2018-08-23T20:47:06.912Z",
    "openingDate": "2018-08-01T13:00:00.000Z",
    "closingDate": "2018-08-23T13:00:00.000Z",
    "openingBalance": 23.13,
    "ledgerEntriesSum": 2956.77,
    "withholdings": [
      {
        "amount": 590.08,
        "code": "W005",
        "description": "Pending Refunds"
      }
    ],
    "withholdingsSum": 590.08,
    "totalAmount": 2389.82,
    "ledgerEntries": [
      {
        "code": 1000,
        "description": "Test invoice BCH",
        "timestamp": "2018-08-01T20:16:03.742Z",
        "amount": 5.83,
        "invoiceId": "E1pJQNsHP2oHuMo2fagpe6",
        "invoiceData": {
          "orderId": "Test invoice BCH",
          "date": "2018-08-01T19:24:42.789Z",
          "price": 5,
          "currency": "EUR",
          "transactionCurrency": "BCH",
          "payoutPercentage": {
            "USD": 100
          }
        }
      },
      {
        "code": 1023,
        "description": "Invoice Fee",
        "timestamp": "2018-08-01T20:16:03.742Z",
        "amount": -0.06,
        "invoiceId": "E1pJQNsHP2oHuMo2fagpe6"
      },
      {
        "code": 1017,
        "description": "Account Settlement XGJqZmdSGDwi5exXqQusJf",
        "timestamp": "2018-08-01T20:19:54.394Z",
        "amount": -23.13
      },
      {
        "code": 1000,
        "description": "Test invoice BCH",
        "timestamp": "2018-08-01T20:20:25.258Z",
        "amount": 5.84,
        "invoiceId": "PbPTukHvymCZYA8FGDa5wh",
        "invoiceData": {
          "orderId": "Test invoice BCH",
          "date": "2018-08-01T19:37:52.790Z",
          "price": 5,
          "currency": "EUR",
          "transactionCurrency": "BCH",
          "payoutPercentage": {
            "USD": 100
          }
        }
      },
      {
        "code": 1023,
        "description": "Invoice Fee",
        "timestamp": "2018-08-01T20:20:25.258Z",
        "amount": -0.06,
        "invoiceId": "PbPTukHvymCZYA8FGDa5wh"
      },
      {
        "code": 1000,
        "description": "Bill 2",
        "timestamp": "2018-08-02T13:54:16.656Z",
        "amount": 1010.1,
        "invoiceId": "GfcuUrvc2TAeCdSzAupbe8",
        "invoiceData": {
          "orderId": "Bill 2",
          "date": "2018-08-02T12:11:15.760Z",
          "price": 1010.1,
          "currency": "USD",
          "transactionCurrency": "BTC",
          "payoutPercentage": {
            "USD": 100
          }
        }
      },
      {
        "code": 1023,
        "description": "Invoice Fee",
        "timestamp": "2018-08-02T13:54:16.656Z",
        "amount": -10.1,
        "invoiceId": "GfcuUrvc2TAeCdSzAupbe8"
      },
      {
        "code": 1000,
        "description": "Bill 2",
        "timestamp": "2018-08-02T13:54:16.663Z",
        "amount": 1010.1,
        "invoiceId": "C3ak5sJD3k15nxTePgVYBv",
        "invoiceData": {
          "orderId": "Bill 2",
          "date": "2018-08-02T12:01:44.613Z",
          "price": 1010.1,
          "currency": "USD",
          "transactionCurrency": "BTC",
          "payoutPercentage": {
            "USD": 100
          }
        }
      },
      {
        "code": 1023,
        "description": "Invoice Fee",
        "timestamp": "2018-08-02T13:54:16.663Z",
        "amount": -10.1,
        "invoiceId": "C3ak5sJD3k15nxTePgVYBv"
      },
      {
        "code": 1000,
        "description": "Test bill 1",
        "timestamp": "2018-08-03T10:15:39.714Z",
        "amount": 1311.81,
        "invoiceId": "5Bfnr8eamNCAYjhVYfzJxs",
        "invoiceData": {
          "orderId": "Test bill 1",
          "date": "2018-08-03T09:22:55.518Z",
          "price": 1010.1,
          "currency": "GBP",
          "transactionCurrency": "BTC",
          "payoutPercentage": {
            "USD": 100
          }
        }
      },
      {
        "code": 1023,
        "description": "Invoice Fee",
        "timestamp": "2018-08-03T10:15:39.714Z",
        "amount": -13.12,
        "invoiceId": "5Bfnr8eamNCAYjhVYfzJxs"
      },
      {
        "code": 1000,
        "description": "test bill",
        "timestamp": "2018-08-06T13:41:58.036Z",
        "amount": 1010.1,
        "invoiceId": "RMUkvBHVQnr9wLDHgD646u",
        "invoiceData": {
          "orderId": "test bill",
          "date": "2018-08-06T13:24:43.826Z",
          "price": 1010.1,
          "currency": "USD",
          "transactionCurrency": "BTC",
          "payoutPercentage": {
            "USD": 100
          }
        }
      },
      {
        "code": 1023,
        "description": "Invoice Fee",
        "timestamp": "2018-08-06T13:41:58.036Z",
        "amount": -10.1,
        "invoiceId": "RMUkvBHVQnr9wLDHgD646u"
      },
      {
        "code": 1020,
        "description": "Invoice Refund",
        "timestamp": "2018-08-07T08:34:49.842Z",
        "amount": -1010.1,
        "invoiceId": "RMUkvBHVQnr9wLDHgD646u",
        "invoiceData": {
          "orderId": "test bill",
          "date": "2018-08-06T13:24:43.826Z",
          "price": 1010.1,
          "currency": "USD",
          "transactionCurrency": "BTC",
          "payoutPercentage": {
            "USD": 100
          },
          "refundInfo": {
            "supportRequest": "Cw4dQ1wnEaL11EkfLrBQAC",
            "currency": "USD",
            "amounts": {
              "USD": 1010.1,
              "BTC": 0.145439
            }
          }
        }
      },
      {
        "code": 1039,
        "description": "Refund Fee",
        "timestamp": "2018-08-07T08:34:49.842Z",
        "amount": -0.92
      },
      {
        "code": 1000,
        "description": "Test invoice BCH",
        "timestamp": "2018-08-07T10:06:35.804Z",
        "amount": 5.8,
        "invoiceId": "LWgqvm3CH47psfgy83DvLX",
        "invoiceData": {
          "orderId": "Test invoice BCH",
          "date": "2018-08-07T09:14:09.106Z",
          "price": 5,
          "currency": "EUR",
          "transactionCurrency": "BCH",
          "payoutPercentage": {
            "USD": 100
          }
        }
      },
      {
        "code": 1023,
        "description": "Invoice Fee",
        "timestamp": "2018-08-07T10:06:35.804Z",
        "amount": -0.06,
        "invoiceId": "LWgqvm3CH47psfgy83DvLX"
      },
      {
        "code": 1000,
        "description": "Test invoice BCH",
        "timestamp": "2018-08-08T12:52:29.384Z",
        "amount": 3.43,
        "invoiceId": "932QfiTCd4ALwaLfqxH5ae",
        "invoiceData": {
          "orderId": "Test invoice BCH",
          "date": "2018-08-08T12:40:00.622Z",
          "price": 2.96,
          "currency": "EUR",
          "transactionCurrency": "BTC",
          "payoutPercentage": {
            "USD": 100
          }
        }
      },
      {
        "code": 1023,
        "description": "Invoice Fee",
        "timestamp": "2018-08-08T12:52:29.384Z",
        "amount": -0.03,
        "invoiceId": "932QfiTCd4ALwaLfqxH5ae"
      },
      {
        "code": 1011,
        "timestamp": "2018-08-09T13:04:49.607Z",
        "amount": -340.19
      },
      {
        "code": 1011,
        "timestamp": "2018-08-13T14:14:25.311Z",
        "amount": -1.06
      },
      {
        "code": 1011,
        "timestamp": "2018-08-13T14:15:09.605Z",
        "amount": -1.33
      },
      {
        "code": 1011,
        "timestamp": "2018-08-13T14:15:18.557Z",
        "amount": -1.06
      },
      {
        "code": 1034,
        "description": "PayoutRequest TDZZuBiqnsNnLjaX93ydcb",
        "timestamp": "2018-08-13T14:17:01.081Z",
        "amount": -1
      },
      {
        "code": 1040,
        "description": "Payout Fee",
        "timestamp": "2018-08-13T14:17:01.081Z",
        "amount": -0.01
      },
      {
        "code": 1011,
        "timestamp": "2018-08-13T14:17:21.617Z",
        "amount": -1.11
      },
      {
        "code": 1011,
        "timestamp": "2018-08-13T14:17:30.296Z",
        "amount": -1.29
      },
      {
        "code": 1011,
        "timestamp": "2018-08-13T14:29:52.473Z",
        "amount": -1.09
      },
      {
        "code": 1034,
        "description": "PayoutRequest BhKWi3WPSoGmCQfvvzfV9B",
        "timestamp": "2018-08-14T10:34:39.372Z",
        "amount": -3000
      },
      {
        "code": 1040,
        "description": "Payout Fee",
        "timestamp": "2018-08-14T10:34:39.372Z",
        "amount": -30
      },
      {
        "code": 1011,
        "timestamp": "2018-08-14T10:34:39.434Z",
        "amount": 69.78
      },
      {
        "code": 1000,
        "description": "Test invoice",
        "timestamp": "2018-08-14T11:13:38.374Z",
        "amount": 582.49,
        "invoiceId": "WxY7d2qUzJawZTTqpXUHov",
        "invoiceData": {
          "orderId": "Test invoice",
          "date": "2018-08-14T10:32:11.015Z",
          "price": 1000,
          "currency": "BGN",
          "transactionCurrency": "BCH",
          "payoutPercentage": {
            "USD": 100
          }
        }
      },
      {
        "code": 1023,
        "description": "Invoice Fee",
        "timestamp": "2018-08-14T11:13:38.374Z",
        "amount": -5.82,
        "invoiceId": "WxY7d2qUzJawZTTqpXUHov"
      },
      {
        "code": 1000,
        "description": "Test invoice",
        "timestamp": "2018-08-14T11:22:12.577Z",
        "amount": 3000,
        "invoiceId": "76ZQGxLuKwKJ5vBMvjdAbh",
        "invoiceData": {
          "orderId": "Test invoice",
          "date": "2018-08-14T10:37:06.348Z",
          "price": 3000,
          "currency": "USD",
          "transactionCurrency": "BTC",
          "payoutPercentage": {
            "USD": 100
          }
        }
      },
      {
        "code": 1023,
        "description": "Invoice Fee",
        "timestamp": "2018-08-14T11:22:12.577Z",
        "amount": -30,
        "invoiceId": "76ZQGxLuKwKJ5vBMvjdAbh"
      },
      {
        "code": 1034,
        "description": "PayoutRequest NkdbgovhHE8CED1ogUJ9Yg",
        "timestamp": "2018-08-14T11:45:08.017Z",
        "amount": -4502
      },
      {
        "code": 1040,
        "description": "Payout Fee",
        "timestamp": "2018-08-14T11:45:08.017Z",
        "amount": -45.02
      },
      {
        "code": 1011,
        "timestamp": "2018-08-14T11:45:08.073Z",
        "amount": 1000.35
      },
      {
        "code": 1000,
        "description": "Test invoice",
        "timestamp": "2018-08-14T13:10:18.890Z",
        "amount": 3000,
        "invoiceId": "RSPnAH9L5yDWUFNYTGDJmi",
        "invoiceData": {
          "orderId": "Test invoice",
          "date": "2018-08-14T11:58:30.028Z",
          "price": 3000,
          "currency": "USD",
          "transactionCurrency": "BTC",
          "payoutPercentage": {
            "USD": 100
          }
        }
      },
      {
        "code": 1023,
        "description": "Invoice Fee",
        "timestamp": "2018-08-14T13:10:18.890Z",
        "amount": -30,
        "invoiceId": "RSPnAH9L5yDWUFNYTGDJmi"
      },
      {
        "code": 1000,
        "description": "Iphone-Order 1",
        "timestamp": "2018-08-16T13:32:23.205Z",
        "amount": 10,
        "invoiceId": "WwCouQindnn6TYW9PvRMSU",
        "invoiceData": {
          "orderId": "Iphone-Order 1",
          "date": "2018-08-16T12:01:32.513Z",
          "price": 10,
          "currency": "USD",
          "transactionCurrency": "BTC",
          "payoutPercentage": {
            "USD": 100
          }
        }
      },
      {
        "code": 1023,
        "description": "Invoice Fee",
        "timestamp": "2018-08-16T13:32:23.205Z",
        "amount": -0.1,
        "invoiceId": "WwCouQindnn6TYW9PvRMSU"
      }
    ]
  }
}
Body
Name Type
facade
Facade used to view settlement objects, set to "merchant/settlement".
string
data
Settlement data object
object
id
String identifying the settlement; this id will also be in the description of the corresponding bank settlement.
string
accountId
String identifying the BitPay merchant. For internal use, this field can be ignored in merchant implementations.
string
status
Status of the settlement. Possible statuses are "new", "processing", "rejected" and "completed".
string
currency
ISO 4217 3-character currency code. This is the currency associated with the settlement. Supported settlement currencies are listed on https://bitpay.com/docs/settlement
string
payoutInfo
Object containing the settlement info provided by the Merchant in his BitPay account settings
string
label
As indicated by the merchant in his settlement settings
string
bankCountry
Country where the merchant's bank account is located
string
name
account holder name
string
bank
Name of the bank used by the merchant
string
swift
SWIFT/BIC code of the merchant's bank.
string
address
This field is used to indicate the wallet address used for the settlement, if the settlement currency selected by the merchant is one of the supported crypto currency: Bitcoin (BTC), Bitcoin Cash (BCH), Paxos Standard (PAX), Gemini Dollar (GUSD) or Circle USD coin (USDC). If the settlement currency used is AUD, GBP, NZD, MXN, ZAR - this field is used to indicate the address of the merchant's bank
string
city
City of the merchant bank, field return if the settlement currency is
string
postal
Postal code of the merchant bank, field return if the settlement currency is
string
account
Bank account number of the merchant
string
sort
used to pass country specific bank fields: BSB for AUD
string
wire
If set to true, this means BitPay will be settling the account using an international transfer via the SWIFT network instead of local settlement methods like ACH(United States) or SEPA (European Economic Area)
boolean
bankName
Name of the bank used by the merchant. Field returned if "wire": true in the "payoutInfo" object
string
bankAddress
Address of the merchant's bank. Field returned if "wire": true in the "payoutInfo" object
string
bankAddress2
Address of the merchant's bank. Field returned if "wire": true in the "payoutInfo" object
string
iban
The merchant's bank account number, in the IBAN (International Bank Account Number) format. Field returned if "wire": true in the "payoutInfo" object
string
additionalInformation
When providing the settlement info via the dashboard, this field can be used by the merchant to provide additional information about the receiving bank. Field returned if "wire": true in the "payoutInfo" object
string
accountHolderName
Bank account holder name. Field returned if "wire": true in the "payoutInfo" object
string
accountHolderAddress
Bank account holder address. Field returned if "wire": true in the "payoutInfo" object
string
accountHolderAddress2
Bank account holder address. Field returned if "wire": true in the "payoutInfo" object
string
accountHolderPostalCode
Bank account holder postal code. Field returned if "wire": true in the "payoutInfo" object
string
accountHolderCity
Bank account holder city. Field returned if "wire": true in the "payoutInfo" object
string
accountHolderCountry
Bank account holder country. Field returned if "wire": true in the "payoutInfo" object
string
dateCreated
timestamp when the settlement was created. UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ
string
dateExecuted
timestamp when the settlement was executed. UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ
number
openingDate
corresponds to the closingDate of the previous settlement executed. For the first settlement of an account the value will be the BitPay merchant account creation date. UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ
number
closingDate
Date & time for last ledger entry used for the settlement. UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ
date
openingBalance
Balance of the ledger at the openingDate
string
ledgerEntriesSum
Sum of all ledger entries in the settlement, this means all the debits & credits which happened betwee openingDate and closingDate
number
withholdings
array of withholdings. Withholdings are kept on the ledger to be used later and thus withheld from this settlement. Each withholding is a JSON object containing a code, amount and description field. The possible withholding codes are:

  • W001 - Refund Reserve: a merchant can set a refund reserve for his account. This code indicate the current amount in the reserve at the moment the settlement is generated.
  • W002 - Settlement Fee: in case BitPay is charging the bank fees to the merchant, via a SWIFT wire for instance, will be posted to the ledger when the settlementReport goes into status ‘processing’. This code is not used for SEPA or ACH transfers
  • W003 - Liquidity Withholding : Used when BitPay's balance at the specific settlement bank is unsufficient to payout the full amount today
  • W004 - Insufficient Balance : in the event a case the ledger balance of the merchant drops after the settlement cut-off, the settlement amount will be adjusted.
  • W005 - Pending Refunds : in order to make sure enough funds are left on the account to execute pending refund requests.

array
withholdingsSum
Sum of all amounts that are withheld from settlement
number
totalAmount
total amount sent to the merchant; 2 decimals.

totalAmount = openingBalance + legderEntriesSum - withholdingsSum

number
token
API token for the corresponding settlement resource. This token is actually derived from the merchant facade token used during the query. This token is required to fetch the reconciliation report
string
ledgerEntries
Array of ledger entries listing the various debits and credits which are settled in the report. The total sum of all ledger entries is reported in the field ledgerEntriesSum. A description of all ledger codes can be found
array
Name Type Ledger Codes
1000 1006 1011 1017 1020 1022 1023 1025 1030 1034 1039 1040
code
Contains the Ledger entry code
string
timestamp
Date and time of the ledger entry (UTC). ISO-8601 format yyyy-mm-ddThh:mm:ssZ
string
amount
Amount for the ledger entry. Can be positive of negative depending on the type of entry (debit or credit)
string
description
Ledger entry description. This field often contains an id depending on the type of entry (for instance payout batch id, settlement id, invoice orderId etc...)
string
invoiceId
BitPay invoice Id
string
invoiceData
Object containing relevant information from the paid invoice
number
orderId
Invoice orderId provided during invoice creation.
string
date
Date at which the invoice was created (UTC). ISO-8601 format yyyy-mm-ddThh:mm:ssZ
string
price
Invoice price in the invoice original currency
amount
currency
Invoice currency
string
transactionCurrency
Cryptocurrency selected by the consumer when paying the invoice. Currently Bitcoin (BTC) or Bitcoin Cash (BCH)
string
payoutPercentage
The payout percentage defined by the merchant on his BitPay account settings
string
refundInfo
Object containing information about the refund executed for the invoice
string
supportRequest
The refund requestId
string
currency
Reference currency used for the refund, usually the same as the currency used to create the invoice
string
amounts
For a refunded invoice, this object will contain the crypto currency amount refunded by BitPay to the consumer (in the selected transactionCurrency) and the equivalent refunded amount from the invoice in the given currency (thus linked to the amount debited from the merchant account to cover the refund)
string

Ledgers

Fetch the account balance for each currency

GET
https://bitpay.com/ledgers
Facades

merchant

HTTP Request

Fetching a ledger entries via the merchant facade (signed requests)

curl -X GET -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572" -H "x-signature: 304402205f299b2699ffb3a09055251ef85c0044dea2cfbcd6f6492793aa18f906bcf48502202be49cecd5a5abc9d4edded7e0569845d0395ccb9b459f1697691eefcdaccadd" "https://test.bitpay.com/ledgers?token=GcAUe7hgY3F2FSh95Dsy5d"
var resourceUrl = "https://test.bitpay.com/ledgers";
var token = "GcAUe7hgY3F2FSh95Dsy5d";

var httpWebRequest = (HttpWebRequest)WebRequest.Create(resourceUrl + "?token=" + token);
httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.Headers.Add(
    "x-identity",
    "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
);
httpWebRequest.Headers.Add(
    "x-signature",
    "304402205f299b2699ffb3a09055251ef85c0044dea2cfbcd6f6492793aa18f906bcf48502202be49cecd5a5abc9d4edded7e0569845d0395ccb9b459f1697691eefcdaccadd"
);
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "GET";

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/ledgers";
var token = "GcAUe7hgY3F2FSh95Dsy5d";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request=HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .header(
           "x-identity",
           "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
   )
   .header(
           "x-signature",
           "304402205f299b2699ffb3a09055251ef85c0044dea2cfbcd6f6492793aa18f906bcf48502202be49cecd5a5abc9d4edded7e0569845d0395ccb9b459f1697691eefcdaccadd"
   )
   .uri(URI.create(resourceUrl + "?token=" + token))
   .GET()
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/ledgers';
$token = 'GcAUe7hgY3F2FSh95Dsy5d';

$curlCli = curl_init($resourceUrl . '?token=' . $token);

curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json',
   'x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature: 304402205f299b2699ffb3a09055251ef85c0044dea2cfbcd6f6492793aa18f906bcf48502202be49cecd5a5abc9d4edded7e0569845d0395ccb9b459f1697691eefcdaccadd'
]);

$result = curl_exec($curlCli);
$resultData = json_decode($result, TRUE);
curl_close($curlCli);

echo $resultData;

?>
let request = require('request');

let resource_url = 'https://test.bitpay.com/ledgers';
let token = 'GcAUe7hgY3F2FSh95Dsy5d';
let headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "304402205f299b2699ffb3a09055251ef85c0044dea2cfbcd6f6492793aa18f906bcf48502202be49cecd5a5abc9d4edded7e0569845d0395ccb9b459f1697691eefcdaccadd"
};
let options = {
   url: resource_url + '?token=' + token,
   method: 'GET',
   headers: headers,
   json: true
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/ledgers"
token := "GcAUe7hgY3F2FSh95Dsy5d"

    request, err := http.NewRequest("GET", resourceUrl + "?token=" + token, nil)
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")
request.Header.Set("x-identity", "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572")
request.Header.Set("x-signature", "304402205f299b2699ffb3a09055251ef85c0044dea2cfbcd6f6492793aa18f906bcf48502202be49cecd5a5abc9d4edded7e0569845d0395ccb9b459f1697691eefcdaccadd")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}
defer response.Body.Close()

body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/ledgers'
token = 'GcAUe7hgY3F2FSh95Dsy5d'
headers = {
   'x-accept-version': '2.0.0',
   'Content-Type': 'application/json',
   'x-identity': '031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature': '304402205f299b2699ffb3a09055251ef85c0044dea2cfbcd6f6492793aa18f906bcf48502202be49cecd5a5abc9d4edded7e0569845d0395ccb9b459f1697691eefcdaccadd'
}
response = requests.get(url=resource_url + '?token=' + token, headers=headers).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/ledgers"
token = "GcAUe7hgY3F2FSh95Dsy5d"
headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "304402205f299b2699ffb3a09055251ef85c0044dea2cfbcd6f6492793aa18f906bcf48502202be49cecd5a5abc9d4edded7e0569845d0395ccb9b459f1697691eefcdaccadd"
}
uri = URI.parse(resource_url + "?token=" + token)
request = Net::HTTP::Get.new(uri.to_s, headers)

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body
URL Parameters
Parameter Type Presence
?token=
when fetching ledger entries, pass a merchant facade token as a URL parameter.
string M
Headers
fields Presence
x-accept-version:
must be set to 2.0.0 for request to the BitPay API
M
content-type
must be set to application/json for request to the BitPay API
M
x-identity
the hexadecimal public key generated from the client private key
M
x-signature
header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key
M
HTTP Response

Example of ledger balances

{
  "data": [
    {
      "currency": "EUR",
      "balance": 0
    },
    {
      "currency": "USD",
      "balance": 2389.82
    },
    {
      "currency": "BTC",
      "balance": 0.000287
    }
  ]
}
Body
Name Type
data
Array of objects indicating the balance for each currency
array
currency
Ledger currency
string
balance
Ledger balance in the corresponding currency
number

Fetch ledger entries based on a date range

GET
https://bitpay.com/ledgers/<currency>
Facades

merchant

HTTP Request

Fetching a ledger entries via the merchant facade (signed requests)

curl -X GET -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572" -H "x-signature: 304502204bf41a0b2483311a2d97a2565b01176eb580cdbbd41c45ba3d70f8c9d8710ac102210090eead4d34f4fea713a459fc3e6c3fbcedc628a0b227ba9d42ced62f470ae4c0" "https://test.bitpay.com/ledgers/USD?token=GcAUe7hgY3F2FSh95Dsy5d&startDate=2019-5-1&endDate=2019-5-31"
var resourceUrl = "https://test.bitpay.com/ledgers/USD";
var token = "GcAUe7hgY3F2FSh95Dsy5d";
var startDate = "2019-5-1";
var endDate = "2019-5-31";

var httpWebRequest = (HttpWebRequest)WebRequest.Create(
    resourceUrl +
    "?token=" + token +
    "&startDate=" + startDate +
    "&endDate=" + endDate
);
httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.Headers.Add(
    "x-identity",
    "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
);
httpWebRequest.Headers.Add(
    "x-signature",
    "304502204bf41a0b2483311a2d97a2565b01176eb580cdbbd41c45ba3d70f8c9d8710ac102210090eead4d34f4fea713a459fc3e6c3fbcedc628a0b227ba9d42ced62f470ae4c0"
);
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "GET";

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/ledgers/USD";
var token = "GcAUe7hgY3F2FSh95Dsy5d";
var startDate = "2019-5-1";
var endDate = "2019-5-31";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request=HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .header(
           "x-identity",
           "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
   )
   .header(
           "x-signature",
           "304502204bf41a0b2483311a2d97a2565b01176eb580cdbbd41c45ba3d70f8c9d8710ac102210090eead4d34f4fea713a459fc3e6c3fbcedc628a0b227ba9d42ced62f470ae4c0"
   )
   .uri(URI.create(
           resourceUrl +
           "?token=" + token +
           "&startDate=" + startDate +
           "&endDate=" + endDate
   ))
   .GET()
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/ledgers/USD';
$token = 'GcAUe7hgY3F2FSh95Dsy5d';
$startDate = '2019-5-1';
$endDate = '2050-5-31';

$curlCli = curl_init(
   $resourceUrl .
   '?token=' . $token .
   '&startDate=' . $startDate .
   '&endDate=' . $endDate
);

curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json',
   'x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature: 304502204bf41a0b2483311a2d97a2565b01176eb580cdbbd41c45ba3d70f8c9d8710ac102210090eead4d34f4fea713a459fc3e6c3fbcedc628a0b227ba9d42ced62f470ae4c0'
]);

$result = curl_exec($curlCli);
$resultData = json_decode($result, TRUE);
curl_close($curlCli);

echo $resultData;

?>
let request = require('request');

let resource_url = 'https://test.bitpay.com/ledgers/USD';
let token = 'GcAUe7hgY3F2FSh95Dsy5d';
let startDate = '2019-5-1';
let endDate = '2019-5-31';
let headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "304502204bf41a0b2483311a2d97a2565b01176eb580cdbbd41c45ba3d70f8c9d8710ac102210090eead4d34f4fea713a459fc3e6c3fbcedc628a0b227ba9d42ced62f470ae4c0"
};
let options = {
   url: resource_url +
       '?token=' + token +
       '&startDate=' + startDate +
       '&endDate=' + endDate,
   method: 'GET',
   headers: headers,
   json: true
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/ledgers/USD"
token := "GcAUe7hgY3F2FSh95Dsy5d"
startDate := "2019-5-1"
endDate := "2019-5-31"

request, err := http.NewRequest("GET",
   resourceUrl +
   "?token=" + token +
   "&startDate=" + startDate +
   "&endDate=" + endDate,
   nil)
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")
request.Header.Set("x-identity", "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572")
request.Header.Set("x-signature", "304502204bf41a0b2483311a2d97a2565b01176eb580cdbbd41c45ba3d70f8c9d8710ac102210090eead4d34f4fea713a459fc3e6c3fbcedc628a0b227ba9d42ced62f470ae4c0")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}
defer response.Body.Close()

body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/ledgers/USD'
token = 'GcAUe7hgY3F2FSh95Dsy5d'
startDate = '2019-5-1'
endDate = '2050-5-31'
headers = {
   'x-accept-version': '2.0.0',
   'Content-Type': 'application/json',
   'x-identity': '031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature': '304502204bf41a0b2483311a2d97a2565b01176eb580cdbbd41c45ba3d70f8c9d8710ac102210090eead4d34f4fea713a459fc3e6c3fbcedc628a0b227ba9d42ced62f470ae4c0'
}
response = requests.get(
   resource_url +
   '?token=' + token +
   '&startDate=' + startDate +
   '&endDate=' + endDate,
   headers=headers
).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/ledgers/USD"
token = "GcAUe7hgY3F2FSh95Dsy5d"
startDate = "2019-5-1"
endDate = "2019-5-31"
headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "304502204bf41a0b2483311a2d97a2565b01176eb580cdbbd41c45ba3d70f8c9d8710ac102210090eead4d34f4fea713a459fc3e6c3fbcedc628a0b227ba9d42ced62f470ae4c0"
}
uri = URI.parse(
   resource_url +
   "?token=" + token +
   "&startDate=" + startDate +
   "&endDate=" + endDate
)
request = Net::HTTP::Get.new(uri.to_s, headers)

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body
URL Parameters
Parameter Type Presence
<currency>
ISO 4217 3-character currency code for your merchant account
string M
?token=
when fetching ledger entries, pass a merchant facade token as a URL parameter. Format YYYY-MM-DD
string M
&startDate=
YYYY-MM-DD format. The start date for fetching ledger entries. Format YYYY-MM-DD
string M
&endDate=
YYYY-MM-DD format. The end date for fetching ledger entries.
string M
Headers
fields Presence
x-accept-version:
must be set to 2.0.0 for request to the BitPay API
M
content-type
must be set to application/json for request to the BitPay API
M
x-identity
the hexadecimal public key generated from the client private key
M
x-signature
header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key
M
HTTP Response

Example of ledger entries

[
  ...
  {
    "type": "Invoice",
    "amount": 6061000000,
    "code": 1000,
    "description": "test-abc",
    "timestamp": "2019-05-02T14:22:53.923Z",
    "txType": "sale",
    "scale": 100000000,
    "invoiceId": "RhHwkycGaDskrEhGfXWnRG",
    "buyerFields": {
      "buyerAddress1": "2630 Hegal Place, Apt 42",
      "buyerCity": "Alexandria",
      "buyerState": "Virginia",
      "buyerZip": "23242"
    },
    "invoiceAmount": 60.61,
    "invoiceCurrency": "USD",
    "transactionCurrency": "BTC",
    "id": "Ljv9NrQjpcckmV6RDhriUa"
  },
  {
    "type": "Invoice Fee",
    "amount": -61000000,
    "code": 1023,
    "description": "Invoice Fee",
    "timestamp": "2019-05-02T14:22:53.923Z",
    "txType": "Invoice Fee",
    "scale": 100000000,
    "invoiceId": "RhHwkycGaDskrEhGfXWnRG",
    "buyerFields": {
      "buyerAddress1": "2630 Hegal Place, Apt 42",
      "buyerCity": "Alexandria",
      "buyerState": "Virginia",
      "buyerZip": "23242"
    },
    "invoiceAmount": 60.61,
    "invoiceCurrency": "USD",
    "transactionCurrency": "BTC",
    "id": "TkSkGV6CnQ5XgNpemUxcKE"
  },
  {
    "type": "Invoice Refund",
    "supportRequest": "BpRciwDGMXYR4kDPynsaRA",
    "amount": -6061000000,
    "code": 1020,
    "description": "Invoice Refund",
    "timestamp": "2019-05-03T15:57:11.937Z",
    "txType": "Invoice Refund",
    "scale": 100000000,
    "invoiceId": "RhHwkycGaDskrEhGfXWnRG",
    "buyerFields": {
      "buyerAddress1": "2630 Hegal Place, Apt 42",
      "buyerCity": "Alexandria",
      "buyerState": "Virginia",
      "buyerZip": "23242"
    },
    "invoiceAmount": 60.61,
    "invoiceCurrency": "USD",
    "transactionCurrency": "BTC",
    "id": "SCM2XEdK3ZwWp7JwWQTZ3W"
  },
  {
    "type": "Refund Fee",
    "amount": -1000000,
    "code": 1039,
    "description": "Refund Fee",
    "timestamp": "2019-05-03T15:57:11.937Z",
    "txType": "Refund Fee",
    "scale": 100000000,
    "invoiceId": "RhHwkycGaDskrEhGfXWnRG",
    "buyerFields": {
      "buyerAddress1": "2630 Hegal Place, Apt 42",
      "buyerCity": "Alexandria",
      "buyerState": "Virginia",
      "buyerZip": "23242"
    },
    "invoiceAmount": 60.61,
    "invoiceCurrency": "USD",
    "transactionCurrency": "BTC",
    "id": "9aKRjYUU2bWqEqz89wEHpt"
  },
  {
    "type": "Account Settlement",
    "amount": -12081000000,
    "reference": "ING_wire",
    "code": 1017,
    "description": "Account Settlement 2NXw5bbcGcZekjNiAaAoKc",
    "timestamp": "2019-05-04T11:58:21.721Z",
    "currency": "USD",
    "txType": "Account Settlement",
    "scale": 100000000,
    "id": "GYfYqydAqvDw2TEWu8fvVW"
  },
  ...
]
Body

Some ledger entries have additional specific fields. The table indicates which fields are returned for the main ledger entries.

Name Type Ledger Codes
1000 1006 1011 1017 1020 1022 1023 1030 1034 1039 1040
type
Contains the Ledger code name
string
amount
Ledger entry amount, relative to the scale. The decimal amount can be obtained by dividing the amount field by the scale parameter.
string
code
Contains the Ledger code
string
timestamp
Date and time of the ledger entry (UTC). ISO-8601 format yyyy-mm-ddThh:mm:ssZ
string
currency
Contains the Ledger code name
string
txType
Contains the Ledger code name
string
scale
Power of 10 used for conversion
string
id
Ledger resource Id
string
supportRequest
The refund requestId
string
description
Ledger entry description. Also contains an id depending on the type of entry (for instance payout batch id, settlement id, invoice orderId etc...)
string
invoiceId
BitPay invoice Id
string
buyerFields
If provided by the merchant in the buyer object during invoice creation
string
buyerName
If provided by the merchant in the buyer object during invoice creation
string
buyerAddress1
If provided by the merchant in the buyer object during invoice creation
string
buyerAddress2
If provided by the merchant in the buyer object during invoice creation
string
buyerCity
If provided by the merchant in the buyer object during invoice creation
string
buyerState
If provided by the merchant in the buyer object during invoice creation
string
buyerZip
If provided by the merchant in the buyer object during invoice creation
string
buyerCountry
If provided by the merchant in the buyer object during invoice creation
string
buyerPhone
If provided by the merchant in the buyer object during invoice creation
string
buyerNotify
If provided by the merchant in the buyer object during invoice creation
string
buyerEmail
If provided by the merchant in the buyer object during invoice creation
string
invoiceAmount
Invoice price in the invoice original currency
string
invoiceCurrency
Currency used for invoice creation
string
transactionCurrency
Cryptocurrency selected by the consumer when paying an invoice. Currently Bitcoin (BTC) or Bitcoin Cash (BCH)
string

Payouts

Resource

Example of payout batch after begin executed.

{
  "facade": "payroll/payoutRequest",
  "data": {
    "id": "85Krn4jvdtTJtGc6T4gcaK",
    "account": "YJCgTf3jrXHkUVzLQ7y4eg",
    "reference": "test",
    "supportPhone": "1-855-4-BITPAY",
    "status": "complete",
    "amount": 5,
    "percentFee": 1,
    "fee": 0.05,
    "depositTotal": 5.05,
    "rate": 5147.62,
    "btc": 0.000972,
    "currency": "USD",
    "requestDate": "2019-04-29T15:16:40.706Z",
    "effectiveDate": "2018-01-28T09:00:00.000Z",
    "notificationURL": "",
    "notificationEmail": "merchant@email.com",
    "instructions": [
      {
        "id": "KSRi4uLwX72DZvXAYV4zyq",
        "amount": 1,
        "btc": {
          "unpaid": 0,
          "paid": 0.000194
        },
        "address": "mghaHDxTSrNvxiJ2soP1pB1NTVK1Lff5EJ",
        "label": "Customer1",
        "transactions": [
          {
            "txid": "56eae489be891fffa78c3a51ea78d34b3fca0f8027e4137b9d5a30ff5d98a926",
            "amount": 0.000194,
            "date": "2019-04-29T15:21:24.182Z"
          }
        ],
        "status": "paid"
      },
      {
        "id": "BbCYHLm1AEa3cJAWedPZsT",
        "amount": 2,
        "btc": {
          "unpaid": 0,
          "paid": 0.000389
        },
        "address": "muNZpawharBgL8t28kr8KBdjqphEDfvmz9",
        "label": "Customer2",
        "transactions": [
          {
            "txid": "31090e1d6220fe4fa0205f21f3bfd28e0f5cf80e27c91d5cfa3046ef6e4d2f5a",
            "amount": 0.000389,
            "date": "2019-04-29T15:21:24.903Z"
          }
        ],
        "status": "paid"
      },
      {
        "id": "6jWmLwKUXejoeunVDAfzGS",
        "amount": 2,
        "btc": {
          "unpaid": 0,
          "paid": 0.000389
        },
        "address": "miCgREyUhfDqHXQ8K2Q2u5h1CjkA8JwLxV",
        "label": "Customer3",
        "transactions": [
          {
            "txid": "dc107757902ff44c74aa5cd4a5065f15cc07df53d4f50686096cd5849ca8153d",
            "amount": 0.000389,
            "date": "2019-04-29T15:21:25.641Z"
          }
        ],
        "status": "paid"
      }
    ],
    "dateExecuted": "2019-04-29T15:21:24.177Z",
    "token": "7tGdAPbGiQZnaB88VGNhxWwCceJ6XKuv5XPx8YLWvFHqQgKCoUQS5RK67AS4CLawsh"
  }
}
Name Type
facade
this indicates the facade used to create the payout. When the payroll facade is used to create a payout request, the BitPay server returns the invoice data as seen from the payroll facade, that is "payroll/payoutRequest"
string
data
payout data object
object
id
Resource id
string
account
String identifying the BitPay merchant
string
reference
Present only if specified in the request to create the batch. This is your reference label for this batch. It will be passed-through on each response for you to identify the batch in your system. Maximum string length is 100 characters
string
supportPhone
Phone number for BitPay. For immediate support visit support@bitpay.com
string
status
set to "new" when you create the payout request
string
amount
The total amount of the batch in fiat currency. This amount must equal the sum of the instruction's amounts
number
percentFee
The rate in % as a transaction fee associated to the merchant account
number
fee
The fee amount for the batch
number
depositTotal
The total amount which will be debited from the merchant balance once the payout is executed (including the fee)
number
btc
The total amount of btc that was sent for the batch once the batch is processed
number
currency
Currency code set for the batch amount (ISO 4217 3-character currency code). Supported currency codes for payout batches are EUR, USD, GBP, CAD, NZD, AUD, ZAR
string
requestDate
Date and time (UTC) when BitPay received the batch. ISO-8601 format yyyy-mm-ddThh:mm:ssZ.
string
effectiveDate
Effective date and time (UTC) for the batch. ISO-8601 format yyyy-mm-ddThh:mm:ssZ - Note that the time of day will automatically be set to 09:00:00.000 UTC time for the given day
string
notificationURL
URL to which BitPay sends webhook notifications. HTTPS is mandatory.
string
notificationEmail
Merchant email address for notification of payout status change.
string
instructions
This is an array containing the detailed payout instructions
array
id
Resource id for the instruction
string
amount
amount to be sent to the customer bitcoin address. The minimum amount per instruction is $1 USD equivalent
string
btc
Initially empty, it will contain the amount of bitcoin sent to the consumer once the payout batch status is set to complete
object
unpaid
Initially set to null, will be set to 0 once the payout batch status is set to complete
number
paid
Initially set to 0, will contain the amount of BTC paid to the consumer once the payout batch status is set to complete
number
address
Bitcoin address provided by the consumer
string
label
For merchant use, pass through - can be a unique reference ID assigned to a given consumer
string
walletProvider
Name of the bitcoin wallet provider used by the customer to receive the funds. This field is only required if the consumer is using one of the listed wallet providers to receive the funds and if the corresponding instruction amount is superior or equal to $3000 USD
string
receiverInfo
JSON object containing the below nested fields. To be provided if the walletProvider is provided. If passed, this object is not returned in the server response from BitPay.
string
name
Customer’s name as indicated on the proof of ID collected.
string
email
Customer’s email address.
string
address
object containing the detailed address of the payout recipient.
object
streetAddress1
Must match the customer’s street / house number on the proof of address document collected.
string
streetAddress2
For merchant use, pass through - could be customer name or unique reference ID.
string
locality
Must match the City/Town on the proof of address document collected.
string
region
If applicable in the country selected, equivalent to state or province.
string
postalCode
Must match the postal code on the proof of address document collected.
string
country
Must match on the proof of address document collected. See Appendix 2 for the list of countries supported (English short names).
string
transactions
set to "unpaid" when you create the payout request
array
status
set to "unpaid" when you create the payout request
string
token
API token retrieved via endpoint POST https://bitpay.com/tokens (payroll facade)
string
Wallet providers
BitPay code description
bitgo If the consumer is requesting a withdrawal to a BitGo address
uphold If the consumer is requesting a withdrawal to an UpHold address
circle If the consumer is requesting a withdrawal to a Circle address
coinbase If the consumer is requesting a withdrawal to a Coinbase address
gdax If the consumer is requesting a withdrawal to a GDAX address
gemini If the consumer is requesting a withdrawal to a Gemini address
itbit If the consumer is requesting a withdrawal to a ItBit address
kraken If the consumer is requesting a withdrawal to a Kraken address

Create a payout batch

POST
https://bitpay.com/payouts
Facades

payroll

HTTP Request

via the payroll facade (signed requests)

curl -X POST -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572" -H "x-signature: 304402202a99c97c3b08dfc268ccc51a7c9ed1efd6561966f1b2e01e300ebcf2da2db59e02207ff15c4ccbce3e1ba89ab1ee626a391ec6ac605f46b1ac45ec4949a1bdaf1363" -d '{"amount":42,"currency":"USD","reference":"test_batch_XYZ","effectiveDate":"2019-5-30","notificationEmail":"merchant@email.com","notificationURL":"https://yournotificationurl.com","instructions":[{"label":"Customer1","address":"mghaHDxTSrNvxiJ2soP1pB1NTVK1Lff5EJ","amount":25.84,"walletProvider":"coinbase","receiverInfo":{"name":"","emailAddress":"fox.mulder@trustno.one","address":{"streetAddress1":"2630 Hegal Place","streetAddress2":"Apt. 42","locality":"Alexandria","region":"VA","postalCode":"23242","country":"United States"}}},{"label":"Customer2","address":"muNZpawharBgL8t28kr8KBdjqphEDfvmz9","amount":10.54},{"label":"Customer3","address":"miCgREyUhfDqHXQ8K2Q2u5h1CjkA8JwLxV","amount":5.62}],"token":"Gj9kD64NcorFoYwsdZXVfwpfWQ543Bq2ZoC2PKbrCfMS"}' "https://test.bitpay.com/payouts"
var resourceUrl = "https://test.bitpay.com/payouts";
var httpWebRequest = (HttpWebRequest)WebRequest.Create(resourceUrl);
httpWebRequest.Headers.Add("x-accept-version", "2.0.0");
httpWebRequest.Headers.Add(
    "x-identity",
    "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
    );
httpWebRequest.Headers.Add(
    "x-signature",
    "304402202a99c97c3b08dfc268ccc51a7c9ed1efd6561966f1b2e01e300ebcf2da2db59e02207ff15c4ccbce3e1ba89ab1ee626a391ec6ac605f46b1ac45ec4949a1bdaf1363"
    );
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "POST";

string json = "{" +
                "\"amount\":42," +
                "\"currency\":\"USD\"," +
                "\"reference\":\"test_batch_XYZ\"," +
                "\"effectiveDate\":\"2019-5-30\"," +
                "\"notificationEmail\":\"merchant@email.com\"," +
                "\"notificationURL\":\"https://yournotificationurl.com\"," +
                "\"instructions\":[" +
                    "{" +
                        "\"label\":\"Customer1\"," +
                        "\"address\":\"mghaHDxTSrNvxiJ2soP1pB1NTVK1Lff5EJ\"," +
                        "\"amount\":25.84," +
                        "\"walletProvider\":\"coinbase\"," +
                        "\"receiverInfo\":{" +
                            "\"name\":\"\"," +
                            "\"emailAddress\":\"fox.mulder@trustno.one\"," +
                            "\"address\":{" +
                                "\"streetAddress1\":\"2630 Hegal Place\"," +
                                "\"streetAddress2\":\"Apt. 42\"," +
                                "\"locality\":\"Alexandria\"," +
                                "\"region\":\"VA\"," +
                                "\"postalCode\":\"23242\"," +
                                "\"country\":\"United States\"" +
                            "}" +
                        "}" +
                    "}," +
                    "{" +
                        "\"label\":\"Customer2\"," +
                        "\"address\":\"muNZpawharBgL8t28kr8KBdjqphEDfvmz9\"," +
                        "\"amount\":10.54" +
                    "}," +
                    "{" +
                        "\"label\":\"Customer3\"," +
                        "\"address\":\"miCgREyUhfDqHXQ8K2Q2u5h1CjkA8JwLxV\"," +
                        "\"amount\":5.62" +
                    "}" +
                "]," +
                "\"token\":\"Gj9kD64NcorFoYwsdZXVfwpfWQ543Bq2ZoC2PKbrCfMS\"" +
              "}";

using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
{

    streamWriter.Write(json);
    streamWriter.Flush();
    streamWriter.Close();
}

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
}
var resourceUrl = "https://test.bitpay.com/payouts";

var json = "{" +
               "\"amount\":42," +
               "\"currency\":\"USD\"," +
               "\"reference\":\"test_batch_XYZ\"," +
               "\"effectiveDate\":\"2019-5-30\"," +
               "\"notificationEmail\":\"merchant@email.com\"," +
               "\"notificationURL\":\"https://yournotificationurl.com\"," +
               "\"instructions\":[" +
                   "{" +
                       "\"label\":\"Customer1\"," +
                       "\"address\":\"mghaHDxTSrNvxiJ2soP1pB1NTVK1Lff5EJ\"," +
                       "\"amount\":25.84," +
                       "\"walletProvider\":\"coinbase\"," +
                       "\"receiverInfo\":{" +
                           "\"name\":\"\"," +
                           "\"emailAddress\":\"fox.mulder@trustno.one\"," +
                           "\"address\":{" +
                               "\"streetAddress1\":\"2630 Hegal Place\"," +
                               "\"streetAddress2\":\"Apt. 42\"," +
                               "\"locality\":\"Alexandria\"," +
                               "\"region\":\"VA\"," +
                               "\"postalCode\":\"23242\"," +
                               "\"country\":\"United States\"" +
                           "}" +
                       "}" +
                   "}," +
                   "{" +
                       "\"label\":\"Customer2\"," +
                       "\"address\":\"muNZpawharBgL8t28kr8KBdjqphEDfvmz9\"," +
                       "\"amount\":10.54" +
                   "}," +
                   "{" +
                       "\"label\":\"Customer3\"," +
                       "\"address\":\"miCgREyUhfDqHXQ8K2Q2u5h1CjkA8JwLxV\"," +
                       "\"amount\":5.62" +
                   "}" +
               "]," +
               "\"token\":\"Gj9kD64NcorFoYwsdZXVfwpfWQ543Bq2ZoC2PKbrCfMS\"" +
             "}";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request=HttpRequest.newBuilder()
   .header("content-type","application/json")
   .header("x-accept-version","2.0.0")
   .header(
           "x-identity",
           "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572"
   )
   .header(
           "x-signature",
           "304402202a99c97c3b08dfc268ccc51a7c9ed1efd6561966f1b2e01e300ebcf2da2db59e02207ff15c4ccbce3e1ba89ab1ee626a391ec6ac605f46b1ac45ec4949a1bdaf1363"
   )
   .uri(URI.create(resourceUrl))
   .POST(HttpRequest.BodyPublishers.ofString(json))
   .build();

HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());
<?php

$resourceUrl = 'https://test.bitpay.com/payouts';

$postData = json_encode([
   'amount' => 42,
   'currency' => 'USD',
   'reference' => 'test_batch_XYZ',
   'effectiveDate' => '2019-5-30',
   'notificationEmail' => 'merchant@email.com',
   'notificationURL' => 'https://yournotificationurl.com',
   'instructions' => [
       [
           'label' => 'Customer1',
           'address' => 'mghaHDxTSrNvxiJ2soP1pB1NTVK1Lff5EJ',
           'amount' => 25.84,
           'walletProvider' => 'coinbase',
           'receiverInfo' => [
               'name' => '',
               'emailAddress' => 'fox.mulder@trustno.one',
               'address' => [
                   'streetAddress1' => '2630 Hegal Place',
                   'streetAddress2' => 'Apt. 42',
                   'locality' => 'Alexandria',
                   'region' => 'VA',
                   'postalCode' => '23242',
                   'country' => 'United States',
               ],
           ],
       ],
       [
           'label' => 'Customer2',
           'address' => 'muNZpawharBgL8t28kr8KBdjqphEDfvmz9',
           'amount' => 10.54,
       ],
       [
           'label' => 'Customer3',
           'address' => 'miCgREyUhfDqHXQ8K2Q2u5h1CjkA8JwLxV',
           'amount' => 5.62,
       ],
   ],
   'token' => 'Gj9kD64NcorFoYwsdZXVfwpfWQ543Bq2ZoC2PKbrCfMS',
]);

$curlCli = curl_init($resourceUrl);
curl_setopt($curlCli, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curlCli, CURLOPT_HTTPHEADER, [
   'x-accept-version: 2.0.0',
   'Content-Type: application/json',
   'x-identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature: 304402202a99c97c3b08dfc268ccc51a7c9ed1efd6561966f1b2e01e300ebcf2da2db59e02207ff15c4ccbce3e1ba89ab1ee626a391ec6ac605f46b1ac45ec4949a1bdaf1363'
]);

curl_setopt($curlCli, CURLOPT_POSTFIELDS, stripslashes($postData));

$result = curl_exec($curlCli);
$resultData = json_decode($result, TRUE);
curl_close($curlCli);

echo $resultData;

?>
let request = require('request');

let resource_url = 'https://test.bitpay.com/payouts';
let post_data = {
   "amount": 42,
   "currency": "USD",
   "reference": "test_batch_XYZ",
   "effectiveDate": "2019-5-30",
   "notificationEmail": "merchant@email.com",
   "notificationURL": "https://yournotificationurl.com",
   "instructions": [
       {
           "label": "Customer1",
           "address": "mghaHDxTSrNvxiJ2soP1pB1NTVK1Lff5EJ",
           "amount": 25.84,
           "walletProvider": "coinbase",
           "receiverInfo": {
               "name": "",
               "emailAddress": "fox.mulder@trustno.one",
               "address": {
                   "streetAddress1": "2630 Hegal Place",
                   "streetAddress2": "Apt. 42",
                   "locality": "Alexandria",
                   "region": "VA",
                   "postalCode": "23242",
                   "country": "United States"
               }
           }
       },
       {
           "label": "Customer2",
           "address": "muNZpawharBgL8t28kr8KBdjqphEDfvmz9",
           "amount": 10.54
       },
       {
           "label": "Customer3",
           "address": "miCgREyUhfDqHXQ8K2Q2u5h1CjkA8JwLxV",
           "amount": 5.62
       }
   ],
   "token": "Gj9kD64NcorFoYwsdZXVfwpfWQ543Bq2ZoC2PKbrCfMS"
};
let headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "304402202a99c97c3b08dfc268ccc51a7c9ed1efd6561966f1b2e01e300ebcf2da2db59e02207ff15c4ccbce3e1ba89ab1ee626a391ec6ac605f46b1ac45ec4949a1bdaf1363"
};
let options = {
   url: resource_url,
   method: 'POST',
   json: post_data,
   headers: headers
};

request(options, function (error, response, body) {
   console.log(body);
});
resourceUrl := "https://test.bitpay.com/payouts"
postData := []byte(`{
   "amount": 42,
   "currency": "USD",
   "reference": "test_batch_XYZ",
   "effectiveDate": "2019-5-30",
   "notificationEmail": "merchant@email.com",
   "notificationURL": "https://yournotificationurl.com",
   "instructions": [
      {
         "label": "Customer1",
         "address": "mghaHDxTSrNvxiJ2soP1pB1NTVK1Lff5EJ",
         "amount": 25.84,
         "walletProvider": "coinbase",
         "receiverInfo": {
            "name": "",
            "emailAddress": "fox.mulder@trustno.one",
            "address": {
               "streetAddress1": "2630 Hegal Place",
               "streetAddress2": "Apt. 42",
               "locality": "Alexandria",
               "region": "VA",
               "postalCode": "23242",
               "country": "United States"
            }
         }
      },
      {
         "label": "Customer2",
         "address": "muNZpawharBgL8t28kr8KBdjqphEDfvmz9",
         "amount": 10.54
      },
      {
         "label": "Customer3",
         "address": "miCgREyUhfDqHXQ8K2Q2u5h1CjkA8JwLxV",
         "amount": 5.62
      }
   ],
   "token": "Gj9kD64NcorFoYwsdZXVfwpfWQ543Bq2ZoC2PKbrCfMS"
}`)

request, err := http.NewRequest("POST", resourceUrl, bytes.NewBuffer(postData))
if err != nil {
   log.Fatal(err)
}

request.Header.Set("x-accept-version", "2.0.0")
request.Header.Set("Content-type", "application/json")
request.Header.Set("x-identity", "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572")
request.Header.Set("x-signature", "304402202a99c97c3b08dfc268ccc51a7c9ed1efd6561966f1b2e01e300ebcf2da2db59e02207ff15c4ccbce3e1ba89ab1ee626a391ec6ac605f46b1ac45ec4949a1bdaf1363")

client := &http.Client{Timeout: time.Second * 10}

response, err := client.Do(request)
if err != nil {
   log.Fatal(err)
}
defer response.Body.Close()

body, err := ioutil.ReadAll(response.Body)

fmt.Printf("%s\n", body)
resource_url = 'https://test.bitpay.com/payouts'
post_data = {
   "amount": 42,
   "currency": "USD",
   "reference": "test_batch_XYZ",
   "effectiveDate": "2019-5-30",
   "notificationEmail": "merchant@email.com",
   "notificationURL": "https://yournotificationurl.com",
       "instructions": [
           {
            "label": "Customer1",
             "address": "mghaHDxTSrNvxiJ2soP1pB1NTVK1Lff5EJ",
             "amount": 25.84,
             "walletProvider": "coinbase",
             "receiverInfo": {
                 "name": "",
                      "emailAddress": "fox.mulder@trustno.one",
                      "address": {
                          "streetAddress1": "2630 Hegal Place",
                              "streetAddress2": "Apt. 42",
                              "locality": "Alexandria",
                              "region": "VA",
                              "postalCode": "23242",
                              "country": "United States"
                      }
             }
           },
           {
             "label": "Customer2",
             "address": "muNZpawharBgL8t28kr8KBdjqphEDfvmz9",
             "amount": 10.54
           },
           {
             "label": "Customer3",
             "address": "miCgREyUhfDqHXQ8K2Q2u5h1CjkA8JwLxV",
             "amount": 5.62
           }
       ],
       "token": "Gj9kD64NcorFoYwsdZXVfwpfWQ543Bq2ZoC2PKbrCfMS"
}
headers = {
   'x-accept-version': '2.0.0',
   'Content-Type': 'application/json',
   'x-identity': '031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572',
   'x-signature': '304402202a99c97c3b08dfc268ccc51a7c9ed1efd6561966f1b2e01e300ebcf2da2db59e02207ff15c4ccbce3e1ba89ab1ee626a391ec6ac605f46b1ac45ec4949a1bdaf1363'
}
response = requests.post(url=resource_url, data=json.dumps(post_data), headers=headers).content
print(response.decode(json.detect_encoding(response)))
resource_url = "https://test.bitpay.com/payouts"
post_data = {
   "amount": 42,
   "currency": "USD",
   "reference": "test_batch_XYZ",
   "effectiveDate": "2019-5-30",
   "notificationEmail": "merchant@email.com",
   "notificationURL": "https://yournotificationurl.com",
   "instructions": [
       {
        "label": "Customer1",
         "address": "mghaHDxTSrNvxiJ2soP1pB1NTVK1Lff5EJ",
         "amount": 25.84,
         "walletProvider": "coinbase",
         "receiverInfo": {
             "name": "",
                  "emailAddress": "fox.mulder@trustno.one",
                  "address": {
                      "streetAddress1": "2630 Hegal Place",
                          "streetAddress2": "Apt. 42",
                          "locality": "Alexandria",
                          "region": "VA",
                          "postalCode": "23242",
                          "country": "United States"
                  }
         }
       },
       {
         "label": "Customer2",
         "address": "muNZpawharBgL8t28kr8KBdjqphEDfvmz9",
         "amount": 10.54
       },
       {
         "label": "Customer3",
         "address": "miCgREyUhfDqHXQ8K2Q2u5h1CjkA8JwLxV",
         "amount": 5.62
       }
   ],
   "token": "Gj9kD64NcorFoYwsdZXVfwpfWQ543Bq2ZoC2PKbrCfMS"
}
headers = {
   "x-accept-version": "2.0.0",
   "Content-Type": "application/json",
   "x-identity": "031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572",
   "x-signature": "304402202a99c97c3b08dfc268ccc51a7c9ed1efd6561966f1b2e01e300ebcf2da2db59e02207ff15c4ccbce3e1ba89ab1ee626a391ec6ac605f46b1ac45ec4949a1bdaf1363"
}
uri = URI.parse(resource_url)
request = Net::HTTP::Post.new(uri.to_s, headers)
request.body = post_data.to_json

response = Net::HTTP.new(uri.host, uri.port).tap do |http|
   http.use_ssl = true
   http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

puts response.request(request).body
Headers
fields Presence
x-accept-version:
must be set to 2.0.0 for request to the BitPay API
M
content-type
must be set to application/json for request to the BitPay API
M
x-identity
the hexadecimal public key generated from the client private key
M
x-signature
header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key
M
Body
Name Type Presence
amount
number M
currency
ISO 4217 3-character currency code. This is the currency associated with the amount field, supported currencies are available via the following API endpoint GET: https://bitpay.com/currencies
string M
reference
For the merchant to pass their own reference label for this batch. It will be passed-through on each response for you to identify the batch in your system. Maximum string length is 100 characters
string O
effectiveDate
Effective date and time (UTC) for the batch. ISO-8601 format yyyy-mm-ddThh:mm:ssZ - Note that the time of day will automatically be set to 09:00:00.000 UTC time for the given day
string M
notificationEmail
Merchant email address for notification of payout status change.
string O
notificationURL
URL to which BitPay sends webhook notifications. HTTPS is mandatory.
string O
instructions
This is an array containing the details of the payout transactions to be executed within the batch.
array M
address
Bitcoin address provided by the customer
string M
amount
amount to be sent to the customer bitcoin address. The minimum amount per instruction is $1 USD equivalent
string M
label
For merchant use, pass through - could be customer name or unique reference ID
string O
walletProvider
Name of the bitcoin wallet provider used by the customer to receive the funds. This field is only required if the consumer is using one of the listed wallet providers to receive the funds and if the corresponding instruction amount is superior or equal to $3000 USD
string C
receiverInfo
JSON object containing the below nested fields. To be provided if the walletProvider is provided
string C
name
Customer’s name as indicated on the proof of ID collected.
string C
email
Customer’s email address.
string C
address
object containing the detailed address of the payout recipient.
object C
streetAddress1
Must match the customer’s street / house number on the proof of address document collected.
string C
streetAddress2
For merchant use, pass through - could be customer name or unique reference ID.
string C
locality
Must match the City/Town on the proof of address document collected.
string C
region
If applicable in the country selected, equivalent to state or province.
</