API REST Bitpay English

REST
API
Overvi
ew
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).
Concept
s
Api
Contract
s
BitPay
considers
the
following
types of API
changes to
be non-
breaking
and
backwards-
compatible:
 exp
osin
ga
new
reso
urce
typ
 add
ing
new
met
hod
to
an
exis
ting
reso
urce
typ
 add
ing
an
opti
onal
pro
pert
y to
an
exis
ting
reso
urce
typ
 add
ing
an
opti
onal
que
ry
par
ame
ter
to
an
exis
ting
reso
urce
met
hod
 dep
reca
ting
an
exis
ting
reso
urce
met
hod
and
pro
vidi
ng
an
alte
rnat
ive
Identitie
s
Authenticati
on in
BitPay's API
utilizes a
specialized
identificatio
scheme, Bit
Auth
Identity
Protocol.
BitAuth
uses the
same
technology
in Bitcoin. A
public
private key
pair is
created
using
elliptic
curve
secp256k1.
The public
SIN (System
identificatio
n number),
like a
bitcoin
address, is
the RIPEMD
160,
SHA256
hash of the
public key.
See the
Bitcoin
Wiki for
complete
details:
 In
eac
req
uest
, the
clie
nt
sign
the
full
url
with
the
req
uest
bod
y
con
cate
nat
ed
if
ther
e is
one.
The
sign
atur
e is
incl
ude
d in
the
x-
sign
atur
e he
ade
and
the
pub
lic
key
is
incl
ude
d in
the
x-
iden
tity
hea
der.
 The
serv
er
verif
ies
that
the
sign
atur
e is
vali
d
and
that
it
mat
che
the
ide
ntit
(the
pub
lic
key)
. It
the
com
put
es
the
SIN
fro
the
pub
lic
key,
and
sees
whe
ther
that
SIN
has
acc
ess
to
the
req
uest
ed
reso
urce
.
For your
convenienc
e, all client
libraries
available
on BitPay's
GitHub
account sup
port this
functionalit
y.
API
Tokens
Authorizati
on in
BitPay's API
utilizes Cap
ability-
based
Security pri
nciples.
Each API
call must be
accompanie
d 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
requiremen
ts (e.g.
'Must be
over 21' or
'Non-
transferrabl
e, 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
correspond
s 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
merchan The broadest set of capabilities against a merchant organization. Allows for
t
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. Access to this facade is not enabled by default,
for more information please contact our support channel.
Gettin
g
Access
To use any
non-public
facade a
token will
need to be
sent with
the API
request.
Tokens can
require
authenticati
on, which
would
requiring
cryptograp
hically
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:
 labe
l (e.
g. M
BitP
ay
Clie
nt)
 id (
e.g.
TfAL
Hhg
U5d
uM4
PAt
FW
gNq
NgY
ZkL
hfw
nf2
Tj)
 faca
de (
e.g.
mer
cha
nt)
This will
respond
with a new
token that
will include
a pairingCo
de. This
pairing
code can
then be
shared with
a merchant
organizatio
administrat
or to
approve
access. This
can be
done by
visiting My
Account ->
API Tokens
and
entering
the pairing
code, or by
visiting the
url
format: bitp
ay.com/api-
access-
request?
pairingCode
=<pairingco
de_goes_her
e>.
Alternativel
y, 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:
 labe
l (e.
g. M
BitP
ay
Clie
nt)
 id (
e.g.
TfAL
Hhg
U5d
uM4
PAt
FW
gNq
NgY
ZkL
hfw
nf2
Tj)
 pair
ingC
ode
(e.g.
As
retri
eve
fro
My
Acc
oun
t ->
API
Tok
ens)
A token
without a
Client ID
authenticati
on
restriction
can be
made, and
a token can
then be
copied
directly to
make API
calls, such
as creating
invoices.
It is also important to note that pairing codes will expire after 24 hours, however once a
token is approved or claimed the expiration is cleared.
Makin
g
Reques
ts
Requests to
the BitPay
REST API
follow
a RESTful
convention
using
standard H
TTP
verbs again
st 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:
 cont
ent-
type
appl
icat
ion/
json
 x-
acce
pt-
vers
ion:
2.0.
 x-
iden
tity
: the
hex
ade
cim
al
pub
lic
key
gen
erat
ed
fro
the
clie
nt
priv
ate
key.
Req
uire
dep
end
ing
on
the
typ
e of
API
tok
en
bein
use
d.
 x-
sign
atur
e:
hea
der
whi
ch
is
cryp
togr
aphi
call
com
put
ed
as
des
crib
ed
bel
ow.
Req
uire
dep
end
ing
on
the
typ
e of
API
tok
en
bein
use
d.
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):
 toke
n(o
btai
ned
duri
ng
clie
nt
regi
stra
tion
pro
cess
abo
ve)
 guid
(an
opti
onal
par
ame
ter
to
enf
orce
ide
mp
ote
nce
for
POS
req
uest
s)
For more
information
about
specific
resource
URIs, please
visit the
resource
documentat
ion.
Signin
g your
reques
t
The x-
signature H
TTP header
is
the ECDSA
signature of
the full
request URL
concatenat
ed 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 r
equest
header.
Cross-
Origin
Resour
ce
Sharin
g
The BitPay
REST API
supports C
ORS, so
that you
may send
requests
directly
from the
client,
however re
member to
never
expose
your
private
key. If your
key
becomes
compromis
ed, you will
want to
disable
your old
Client ID
and register
a new one.
Resour
ces
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 RhH
wkycGaDskr
EhGfXWnR
G.
Name Type returned via facade
public merchant
data array ✓ ✓
policies object ✓ ✓
policy
string ✓ ✓
Can be "sin", "access", "events", "id", or "session"
method
Can be "requireSin", "requireFacadeAccess", string ✓ ✓

"allowEventStream", "invalidated", "inactive",
"unclaimed", "requireSession"
params
array ✓ ✓
Can be "support", SIN value, or null
resource
string ✓
Token identifier. This field can be ignored in
merchant implementations.
token
string ✓ ✓
API token for token resource
facade
string ✓ ✓
Can be "merchant", "pos" or "payroll"
dateCreated string ✓ ✓
UNIX time of creation, in milliseconds
pairingExpiration
number ✓ ✓
UNIX time of expiration, in milliseconds
pairingCode
Access approval code. To be validated via string ✓ ✓

the BitPay dashboard in order to activate the
token returned in the same payload.
Request an
API token
POST
https://bitpay.com/tokens
For e-commerce implementation, we advise merchants to generate a standard pos facade
token directly from the BitPay dashboard (make sure "Require Authentication" is disabled)
and use the below endpoint only to request higher privilege tokens
(typically merchant facade).
Facades
PUBLIC MER
CHANT
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"
Headers
Fields Presence
x-accept-version:
M
must be set to 2.0.0 for requests to the BitPay API
content-type
M
must be set to application/json for requests to the BitPay API
x-identity
the hexadecimal public key generated from the client private key. This header is C
optional for this endpoint when using the public facade, and required when
using a merchant facade token.
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 C
endpoint when using the public facade, and required when using
a merchant facade token.
Body
Parameter Type Presence
id strin M
g
Client identity based on BitAuth identity protocol, also known as
SIN (System Identification Number)
facade
Can be merchant, pos or payroll. If passed in the body of the strin

g C
request together with the id parameter, leave
the pairingCode parameter out.
label
strin
g O
Token label, may include spaces, underscores, and dashes
pairingCode strin C
g
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.
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 reso
urce section
Invoices
Resource
Example of invoice resource (fetched using the merchant facade)
{
"facade": "merchant/invoice",
"data": {
"url": "https://test.bitpay.com/invoice?id=5oACoLiz3NLK5WwiNRWFtK",
"posData": "tx46518",
"status": "complete",
"price": 10,
"currency": "EUR",
"itemDesc": "Item XYZ",
"orderId": "MerchantOrder10112",
"invoiceTime": 1580125699920,
"expirationTime": 1580126599920,
"currentTime": 1580127919253,
"id": "5oACoLiz3NLK5WwiNRWFtK",
"lowFeeDetected": false,
"amountPaid": 65768000000000000,
"displayAmountPaid": "0.065768",
"exceptionStatus": false,
"targetConfirmations": 50,
"transactions": [
{
"amount": 65768000000000000,
"confirmations": 50,
"time": "2020-01-27T11:49:24.000Z",
"receivedTime": "2020-01-27T11:49:24.000Z",
"txid": "0xce0ff4605784e74c38335b969d41681b9638c103ae3a2af405ef737feee58e43",
"exRates": {
"ETH": 1,
"EUR": 152.14850819999998,
"BTC": 0.01938600577765396,
"USD": 167.7,
"BCH": 0.4576965065502184,
"GUSD": 167.7,
"PAX": 167.7,
"USDC": 167.7,
"XRP": 731.3881983514327
}
},
{
"amount": -32747000000000000,
"time": "2020-01-27T12:18:57.284Z",
"receivedTime": "2020-01-27T12:18:57.284Z",
"type": "refundFromLedger",
"txid": "0x5e3c32b8f66b67c9d410044f0b767ec1cac82bfb5fb730026b112537a923f1c3",
"refundAmount": -32747000000000000,
"exRates": {
"ETH": 1,
"EUR": 152.6856309,
"BTC": 0.019354950002587558,
"USD": 168.3,
"BCH": 0.4549878345498784,
"GUSD": 168.3,
"PAX": 168.3,
"USDC": 168.3,
"XRP": 731.357552581262
}
}
],
"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": [
{
"0x2D21469a39FAA0011F18722c672607C0F0042cd3": {
"type": "buyerSupplied",
"date": "2020-01-27T12:07:35.677Z",
"tag": null
}
}
],
"refundAddressRequestPending": false,
"buyerProvidedEmail": "fox.mulder@trustno.one",
"buyerProvidedInfo": {
"phoneNumber": "555-123-456",
"selectedTransactionCurrency": "ETH",
"emailAddress": "fox.mulder@trustno.one"
},
"paymentSubtotals": {
"BTC": 127500,
"BCH": 3016200,
"ETH": 65768000000000000,
"GUSD": 1102,
"PAX": 11020000000000000000,
"USDC": 11020000,
"XRP": 48081546
},
"paymentTotals": {
"BTC": 127600,
"BCH": 3016200,
"ETH": 65768000000000000,
"GUSD": 1102,
"PAX": 11020000000000000000,
"USDC": 11020000,
"XRP": 48081546
},
"paymentDisplayTotals": {
"BTC": "0.001276",
"BCH": "0.030162",
"ETH": "0.065768",
"GUSD": "11.02",
"PAX": "11.02",
"USDC": "11.02",
"XRP": "48.081546"
},
"paymentDisplaySubTotals": {
"BTC": "0.001275",
"BCH": "0.030162",
"ETH": "0.065768",
"GUSD": "11.02",
"PAX": "11.02",
"USDC": "11.02",
"XRP": "48.081546"
},
"exchangeRates": {
"BTC": {
"EUR": 7841.529999999999,
"USD": 8645.62,
"BCH": 23.602566202566205,
"ETH": 51.58176719766124,
"GUSD": 8645.62,
"PAX": 8645.62,
"USDC": 8645.62,
"XRP": 37715.91850979366
},
"BCH": {
"EUR": 331.53999999999996,
"USD": 365.9,
"BTC": 0.04232195918631725,
"ETH": 2.183043971123441,
"GUSD": 365.9,
"PAX": 365.9,
"USDC": 365.9,
"XRP": 1596.2134101121144
},
"ETH": {
"EUR": 152.04870894,
"USD": 167.59,
"BTC": 0.019384359497225768,
"BCH": 0.4575211575211575,
"GUSD": 167.59,
"PAX": 167.59,
"USDC": 167.59,
"XRP": 731.0997687911705
},
"GUSD": {
"EUR": 0.907266,
"USD": 1,
"BTC": 0.00011566537082896217,
"BCH": 0.0027300027300027297,
"ETH": 0.005966231131794046,
"PAX": 1,
"USDC": 1,
"XRP": 4.362430746411901
},
"PAX": {
"EUR": 0.907266,
"USD": 1,
"BTC": 0.00011566537082896217,
"BCH": 0.0027300027300027297,
"ETH": 0.005966231131794046,
"GUSD": 1,
"USDC": 1,
"XRP": 4.362430746411901
},
"USDC": {
"EUR": 0.907266,
"USD": 1,
"BTC": 0.00011566537082896217,
"BCH": 0.0027300027300027297,
"ETH": 0.005966231131794046,
"GUSD": 1,
"PAX": 1,
"XRP": 4.362430746411901
},
"XRP": {
"EUR": 0.20798,
"USD": 0.22911,
"BTC": 0.00002650009311062352,
"BCH": 0.0006254709254709255,
"ETH": 0.0013669232146053339,
"GUSD": 0.22911,
"PAX": 0.22911,
"USDC": 0.22911
}
},
"minerFees": {
"BTC": {
"satoshisPerByte": 1,
"totalFee": 100
},
"BCH": {
"totalFee": 0
},
"ETH": {
"totalFee": 0
},
"GUSD": {
"totalFee": 0
},
"PAX": {
"totalFee": 0
},
"USDC": {
"totalFee": 0
},
"XRP": {
"totalFee": 0
}
},
"shopper": {
"user": "2C2rjTgV4bPHRgg7XBWjdE"
},
"jsonPayProRequired": false,
"refundInfo": [
{
"supportRequest": "SgNXo9DJbVTsisua7x5qzc",
"currency": "EUR",
"amounts": {
"EUR": 5,
"ETH": 0.032747,
"USD": 5.51
}
}
],
"transactionCurrency": "ETH",
"supportedTransactionCurrencies": {
"BTC": {
"enabled": true
},
"BCH": {
"enabled": true
},
"ETH": {
"enabled": true
},
"GUSD": {
"enabled": true
},
"PAX": {
"enabled": true
},
"USDC": {
"enabled": true
},
"XRP": {
"enabled": true
}
},
"paymentCodes": {
"BTC": {
"BIP72b": "bitcoin:?r=https://test.bitpay.com/i/5oACoLiz3NLK5WwiNRWFtK",
"BIP73": "https://test.bitpay.com/i/5oACoLiz3NLK5WwiNRWFtK"
},
"BCH": {
"BIP72b": "bitcoincash:?r=https://test.bitpay.com/i/5oACoLiz3NLK5WwiNRWFtK",
},
"ETH": {
"EIP681": "ethereum:?r=https://test.bitpay.com/i/5oACoLiz3NLK5WwiNRWFtK"
},
"GUSD": {
"EIP681b": "ethereum:?r=https://test.bitpay.com/i/5oACoLiz3NLK5WwiNRWFtK"
},
"PAX": {
},
"USDC": {
},
"XRP": {
"BIP72b": "ripple:?r=https://test.bitpay.com/i/5oACoLiz3NLK5WwiNRWFtK",
"RIP681": "https://test.bitpay.com/i/5oACoLiz3NLK5WwiNRWFtK",
}
},
"token": "3vs8MUB4mCiu9fvLSLnv2SETDXYcXpEo1KRJs6aD7LZpUQQTiy9WE9QgWV2K7RCSHe"
}
}
Invoices are
time-
sensitive
payment
requests
addressed
to specific
buyers. An
invoice has
a fixed
price,
typically
denominate
d in fiat
currency. It
also has an
equivalent
price in the
supported
cryptocurre
ncies,
calculated
by BitPay,
at a locked
exchange
rate with an
expiration
time of 15
minutes.
pub p merch
lic os ant
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
string ✓ ✓ ✓
used to request an invoice
resource
 "merchant/invoice" if
the merchant facade is used to
data
Invoice data object. The following fields
from the initial POST request will be passed object ✓ ✓ ✓
in the response from the server, in addition
to some other fields listed in this section
url
Web address of invoice, expires string ✓ ✓ ✓
at expirationTime
posData string ✓ ✓ ✓
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\" }\"" .
status string ✓ ✓ ✓
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).
price
Fixed price amount for the checkout, in number ✓ ✓ ✓
the "currency" of the invoice object.
currency
ISO 4217 3-character currency code. This is
the currency associated with the price field, string ✓ ✓ ✓
supported currencies are available via
the Currencies resource
itemDesc string ✓ ✓ ✓
Invoice description - will be added as a line
item on the BitPay checkout page, under the
merchant name.
orderId
Can be used by the merchant to assign their
own internal Id to an invoice. If used, there string ✓ ✓ ✓
should be a direct match between
an orderId and an invoice id.
invoiceTime
UNIX time of invoice creation, in number ✓ ✓ ✓
milliseconds
expirationTime
UNIX time when invoice is last available to number ✓ ✓ ✓
be paid, in milliseconds
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 boolea
buyer is too low. Initially set to false when n ✓ ✓ ✓
the invoice is created.
amountPaid number ✓ ✓ ✓
Initially set to 0 when creating the invoice. It
will be updated with the total amount paid
to the invoice, indicated in the smallest
possible unit for the
corresponding transactionCurrency
displayAmountPaid
Initially set to "0" when creating the invoice.
It will be updated with the total amount string ✓ ✓ ✓
paid to the invoice indicated in the base unit
for the corresponding transactionCurrency
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 boolea

n | ✓ ✓ ✓
string
consumer did not send enough
funds when paying the invoice.
 "paidOver": (string) if the consumer
sent to much funds when paying
the invoice.
targetConfirmations number ✓
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 for BTC/BCH/XRP
and 50 for ETH/GUSD/PAX/USDC
transactions
Initially empty when the invoice is created.
This array will be populated with the crypto
currency transaction hashes linked to the
invoice. For instance the consumer's array ✓
transaction hash if the invoice is paid, but
also the refund transaction hash if the
merchant decide to issue a refund to the
purchaser
buyer
Allows merchant to pass buyer related object ✓
information in the invoice 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 string ✓
alpha-2
email
Buyer's email address. If provided during
invoice creation, this will bypass the email string ✓
prompt for the consumer when opening the
invoice.
phone
Buyer's phone number string ✓
notify
Indicates whether a BitPay email boolea
confirmation should be sent to the buyer n ✓
once he has paid the invoice
redirectURL
URL to redirect the shopper back to your
website after a successful purchase. Be sure string ✓ ✓ ✓
to include "http://" or "https://" in the url.
refundAddresses array ✓
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.
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 boolea
n ✓ ✓ ✓
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
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 string ✓
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.
buyerProvidedInfo
Information collected from the buyer during
the process of paying an invoice. Initially object ✓ ✓ ✓
this object is empty.
name
Populated with the buyer's name address if string ✓ ✓ ✓
passed in the buyer object by the merchant
phoneNumber string ✓ ✓ ✓
Populated with the buyer's phone number if
passed in the buyer object by the merchant
selectedTransactionCurrency
This field will be populated with the
cryptocurrency selected to pay the BitPay
invoice, current supported values string ✓ ✓ ✓
are "BTC", "BCH", "ETH", "USDC", "GUSD", "PAX"
and "XRP". If not yet selected, this field will
not be returned.
emailAddress
populated with the buyer's email address if
passed in the buyer object, otherwise this string ✓
field is not returned in the response.
paymentSubtotals
For internal use. This field can be ignored in object ✓ ✓ ✓
merchant implementations.
paymentTotals
For internal use - This field can be ignored object ✓ ✓ ✓
in merchant implementations.
paymentDisplayTotals
The total amount that the purchaser should
pay as displayed on the invoice UI. This is
like paymentDisplaySubTotals but with
the minerFees included. The key is the object ✓ ✓ ✓
currency and the value is an amount
indicated in the base unit for each
supported transactionCurrency.
paymentDisplaySubTotals
Equivalent to price for each
supported transactionCurrency,
excluding minerFees. The key is the currency object ✓ ✓ ✓
and the value is an amount indicated in the
base unit for each
supported transactionCurrency.
exchangeRates
Exchange rates keyed by source and target object ✓ ✓ ✓
currencies.
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 object ✓ ✓ ✓
referenced as "Network Cost" on an invoice,
see this support article for more information
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 object ✓
more information
user
If a shopper signs in on the invoice using his
BitPay ID, this field will contain the unique string ✓
ID assigned by BitPay to this shopper.
billId string ✓
This field will be in the invoice object only if
the invoice was generated from a bill, see
the Bills resource for more information
refundInfo
For a refunded invoice, this object will
contain the details of executed refunds for object ✓
the corresponding invoice.
supportRequest
For a refunded invoice, this field will contain string ✓
the refund requestId once executed.
currency
For a refunded invoice, this field will contain
the base currency selected for the refund. string ✓
Typically the same as the invoice currency.
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 object ✓
equivalent refunded amount from the
invoice in the given currency (thus linked to
the amount debited from the merchant
account to cover the refund)
jsonPayProRequired
Boolean set to false by default. If set
to true, this means that the invoice will only boolea
accept payments from wallets which have n ✓ ✓ ✓
implemented the BitPay JSON Payment
Protocol
transactionCurrency
The cryptocurrency used to pay the invoice.
This field will only be available after a
transaction is applied to the invoice. string ✓ ✓ ✓
Possible values are
currently "BTC", "BCH", "ETH", "GUSD", "USDC",
"PAX" and "XRP".
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 and option. An
extra "reason" parameter is added in the object ✓ ✓ ✓
object if a cryptocurrency is disabled on a
specific invoice. If you disable a currency via
the invoice parameter "paymentCurrencies",
this parameter will be set
to "merchantDisabledByParam"
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.
 For "BTC" and "BCH" - BIP72b and
BIP73 are supported. object ✓ ✓ ✓
 For "ETH", "GUSD" "USDC" and "PAX" -
EIP681 is supported
 For "XRP" - RIP681, BIP72b and
BIP73 is supported
token
invoice resource token. This token is derived
from the API token initially used to create string ✓ ✓ ✓
the invoice and is tied to the specific
resource id created.
Create an
invoice
POST
Facades
POS MERCH
ANT
HTTP
Request
via the pos facade (unsigned requests)

'{"currency":"EUR","price":10,"orderId":"MerchantOrder123","fullNotifications":true,"exte
ndedNotifications":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":tr
ue},"posData":"tx1234","itemDesc":"Item
XYZ","token":"92zP1M2t4T3iHEsATh8EEsYUiKaq9rQjGEezJmURddoW"}'
"https://test.bitpay.com/invoices"
via the merchant facade (signed requests)
curl -X POST -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-

identity: 02e6228330bb3f4887ec4eb650dc52d668172a7de39076281e030c03bba10bd8a6" -H "x-
signature:
3045022100a08c14c060a652d758141c777a6e907338106885b2872a8ee137f016c0be670c02201571921afe7
e077d3713bac9a61d7a9e9486482c90eed61a07001e96385ffba0" -d
'{"currency":"EUR","price":10,"orderId":"MerchantOrder123","fullNotifications":true,"exte
ndedNotifications":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":tr
ue},"posData":"tx1234","itemDesc":"Item
XYZ","token":"6oE1tYw1xMqUjM97dk57cwbda5sxbXTkUgg7UKpwkzEE"}'
"https://test.bitpay.com/invoices"
Headers
fields Presence
x-accept-version:
M
must be set to 2.0.0 for requests to the BitPay API
content-type
M
must be set to application/json for requests to the BitPay API
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 C
using standard pos facade token directly from the BitPay
dashboard (with "Require Authentication" disabled), this header is not needed.
x-signature
request body, signed with your private key. This header is required when using C
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.
Body
Name Type Presenc
e
token
The API token can be retrieved from the dashboard (limited

to pos facade) or using the Tokens resource to get access to
string M
the merchant facade. This is described in the section Request an
API token).
price
Fixed price amount for the checkout, in the "currency" of the

number M
invoice object.
currency
ISO 4217 3-character currency code. This is the currency string M

associated with the price field, supported currencies are available
via the Currencies resource.
orderId
Can be used by the merchant to assign their own internal Id to an string O

invoice. If used, there should be a direct match between
an orderId and an invoice id.
itemDesc
Invoice description - will be added as a line item on the BitPay

string O
checkout page, under the merchant name.
itemCode
"bitcoindonation" for donations, otherwise do not include the

string O
field in the request.
notificationEmail
Merchant email address for notification of invoice status change. string O

It is also possible to configure this email via the account setting
on the BitPay dashboard or disable the email notification
notificationURL
URL to which BitPay sends webhook notifications. HTTPS is

string O
mandatory.
redirectURL
URL to redirect the shopper back to your website after a string O

successful purchase. Be sure to include "http://" or "https://" in
the url.
posData
A passthru variable provided by the merchant during invoice

creation and designed to be used by the merchant to correlate string O
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\" }\"" .
transactionSpeed string O
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.
 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).
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 boolea
n O
for each invoice paid by the consumer. This webhook will be for
the "confirmed" or "complete" invoice status, depending on
the transactionSpeed selected.
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 boolea
n O
automatically set to true. When using
the extendedNotifications parameter, the webhook also have a
payload slightly different from the standard webhooks.
physical
Indicates whether items are physical goods. Alternatives include boolea
n O
digital goods and services.
buyer
Allows merchant to pass buyer related information in the invoice object O
object
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 string O
invoice.
phone
Buyer's phone number string O
notify boolea O
n
Indicates whether a BitPay email confirmation should be sent to
the buyer once he has paid the invoice
paymentCurrencies
Allow the merchant to select the cryptocurrencies available as
payment option on the BitPay invoice. Possible values are
currently "BTC" and/or "BCH", "ETH", "GUSD", "USDC", "PAX" and "XRP array O
". For instance "paymentCurrencies": ["XRP"] will create an
invoice with only XRP available as transaction currency, thus
bypassing the currency selection step on the invoice.
jsonPayProRequired
If set to true, this means that the invoice will only accept
boolea
payments from wallets which have implemented the BitPay JSON n O
Payment Protocol
HTTP
Response
for invoices created via the POS facade (unsigned requests)
{
"facade": "pos/invoice",
"data": {
"url": "https://test.bitpay.com/invoice?id=53HnjdRmRpfggb858StbNn",
"status": "new",
"price": 10,
"currency": "EUR",
"invoiceTime": 1580121460596,
"currentTime": 1580121460750,
"id": "53HnjdRmRpfggb858StbNn",
"amountPaid": 0,
"displayAmountPaid": "0",
"phoneNumber": "555-123-456"
},
"BTC": 127900,
"BCH": 3071000,
"ETH": 66473000000000000,
"GUSD": 1102,
"PAX": 11020000000000000000,
"USDC": 11020000,
"XRP": 48489551
},
"paymentTotals": {
"BTC": 128000,
"BCH": 3071000,
"ETH": 66473000000000000,
"GUSD": 1102,
"PAX": 11020000000000000000,
"USDC": 11020000,
"XRP": 48489551
},
"BTC": "0.001280",
"BCH": "0.030710",
"ETH": "0.066473",
"GUSD": "11.02",
"PAX": "11.02",
"USDC": "11.02",
"XRP": "48.489551"
},
"BTC": "0.001279",
"BCH": "0.030710",
"ETH": "0.066473",
"GUSD": "11.02",
"PAX": "11.02",
"USDC": "11.02",
"XRP": "48.489551"
},
"exchangeRates": {
"BTC": {
"EUR": 7820.759999999999,
"USD": 8614.38,
"BCH": 23.968781302170285,
"ETH": 51.97526245927355,
"GUSD": 8614.38,
"PAX": 8614.38,
"USDC": 8614.38,
"XRP": 37903.72684472213
},
"BCH": {
"EUR": 325.63,
"USD": 358.8999999999999,
"BTC": 0.04166284554100754,
"ETH": 2.1654398455412087,
"GUSD": 358.8999999999999,
"PAX": 358.8999999999999,
"USDC": 358.8999999999999,
"XRP": 1579.1789501474016
},
"ETH": {
"EUR": 150.43593841,
"USD": 165.73,
"BTC": 0.01923873890083918,
"BCH": 0.4611296605453534,
"GUSD": 165.73,
"PAX": 165.73,
"USDC": 165.73,
"XRP": 729.2207506490078
},
"GUSD": {
"EUR": 0.9077170000000001,
"USD": 1,
"BTC": 0.00011608483015048077,
"BCH": 0.002782415136338342,
"ETH": 0.006033546518643658,
"PAX": 1,
"USDC": 1,
"XRP": 4.400052800633607
},
"PAX": {
"EUR": 0.9077170000000001,
"USD": 1,
"BTC": 0.00011608483015048077,
"BCH": 0.002782415136338342,
"ETH": 0.006033546518643658,
"GUSD": 1,
"USDC": 1,
"XRP": 4.400052800633607
},
"USDC": {
"EUR": 0.9077170000000001,
"USD": 1,
"BTC": 0.00011608483015048077,
"BCH": 0.002782415136338342,
"ETH": 0.006033546518643658,
"GUSD": 1,
"PAX": 1,
"XRP": 4.400052800633607
},
"XRP": {
"EUR": 0.20623000000000002,
"USD": 0.22713,
"BTC": 0.0000263663474720787,
"BCH": 0.0006319699499165276,
"ETH": 0.001370399420779534,
"GUSD": 0.22713,
"PAX": 0.22713,
"USDC": 0.22713
}
},
"BTC": {
"enabled": true
},
"BCH": {
"enabled": true
},
"ETH": {
"enabled": true
},
"GUSD": {
"enabled": true
},
"PAX": {
"enabled": true
},
"USDC": {
"enabled": true
},
"XRP": {
"enabled": true
}
},
"minerFees": {
"BTC": {
"totalFee": 100
},
"BCH": {
"totalFee": 0
},
"ETH": {
"totalFee": 0
},
"GUSD": {
"totalFee": 0
},
"PAX": {
"totalFee": 0
},
"USDC": {
"totalFee": 0
},
"XRP": {
"totalFee": 0
}
},
"paymentCodes": {
"BTC": {
"BIP72b": "bitcoin:?r=https://test.bitpay.com/i/53HnjdRmRpfggb858StbNn",
"BIP73": "https://test.bitpay.com/i/53HnjdRmRpfggb858StbNn"
},
"BCH": {
"BIP72b": "bitcoincash:?r=https://test.bitpay.com/i/53HnjdRmRpfggb858StbNn",
},
"ETH": {
"EIP681": "ethereum:?r=https://test.bitpay.com/i/53HnjdRmRpfggb858StbNn"
},
"GUSD": {
"EIP681b": "ethereum:?r=https://test.bitpay.com/i/53HnjdRmRpfggb858StbNn"
},
"PAX": {
},
"USDC": {
},
"XRP": {
"BIP72b": "ripple:?r=https://test.bitpay.com/i/53HnjdRmRpfggb858StbNn",
"RIP681": "https://test.bitpay.com/i/53HnjdRmRpfggb858StbNn",
}
},
"token": "24pcN5BntaZcQEavHzuzVEJ58XH5Gwf1V1LD8T5fYvSMB97MPDXdFETKp1HNqaLHi7"
}
}
For invoices created via the merchant facade (signed requests)
{
"data": {
"url": "https://test.bitpay.com/invoice?id=e6XJ7a5CKophekJwKyJ1M",
"status": "new",
"price": 10,
"currency": "EUR",
"invoiceTime": 1580120872157,
"currentTime": 1580120964939,
"id": "e6XJ7a5CKophekJwKyJ1M",
"amountPaid": 0,
"transactions": [],
"buyer": {
"region": "VA",
"country": "US",
"phone": "555-123-456",
"notify": true
},
"refundAddresses": [],
"phoneNumber": "555-123-456",
},
"BTC": 127800,
"BCH": 3070600,
"ETH": 66409000000000000,
"GUSD": 1102,
"PAX": 11020000000000000000,
"USDC": 11020000,
"XRP": 48435532
},
"paymentTotals": {
"BTC": 127900,
"BCH": 3070600,
"ETH": 66409000000000000,
"GUSD": 1102,
"PAX": 11020000000000000000,
"USDC": 11020000,
"XRP": 48435532
},
"BTC": "0.001279",
"BCH": "0.030706",
"ETH": "0.066409",
"GUSD": "11.02",
"PAX": "11.02",
"USDC": "11.02",
"XRP": "48.435532"
},
"BTC": "0.001278",
"BCH": "0.030706",
"ETH": "0.066409",
"GUSD": "11.02",
"PAX": "11.02",
"USDC": "11.02",
"XRP": "48.435532"
},
"exchangeRates": {
"BTC": {
"EUR": 7824.000000000001,
"USD": 8620.09,
"BCH": 23.991344280545505,
"ETH": 51.95329074252653,
"GUSD": 8620.09,
"PAX": 8620.09,
"USDC": 8620.09,
"XRP": 37910.50224294133
},
"BCH": {
"EUR": 325.6700000000001,
"USD": 358.8195423959139,
"BTC": 0.04162591395332377,
"ETH": 2.162605706739756,
"GUSD": 358.8195423959139,
"PAX": 358.8195423959139,
"USDC": 358.8195423959139,
"XRP": 1578.0611680469929
},
"ETH": {
"EUR": 150.58117313,
"USD": 165.89,
"BTC": 0.019244556327652807,
"BCH": 0.4617033119955469,
"GUSD": 165.89,
"PAX": 165.89,
"USDC": 165.89,
"XRP": 729.5716421848887
},
"GUSD": {
"EUR": 0.9077170000000001,
"USD": 1,
"BTC": 0.00011600793494275007,
"BCH": 0.0027831895352073473,
"ETH": 0.006027000964320154,
"PAX": 1,
"USDC": 1,
"XRP": 4.3979241797871405
},
"PAX": {
"EUR": 0.9077170000000001,
"USD": 1,
"BTC": 0.00011600793494275007,
"BCH": 0.0027831895352073473,
"ETH": 0.006027000964320154,
"GUSD": 1,
"USDC": 1,
"XRP": 4.3979241797871405
},
"USDC": {
"EUR": 0.9077170000000001,
"USD": 1,
"BTC": 0.00011600793494275007,
"BCH": 0.0027831895352073473,
"ETH": 0.006027000964320154,
"GUSD": 1,
"PAX": 1,
"XRP": 4.3979241797871405
},
"XRP": {
"EUR": 0.20646,
"USD": 0.22736999999999996,
"BTC": 0.000026376724167933077,
"BCH": 0.0006328138046200945,
"ETH": 0.0013703592092574734,
"GUSD": 0.22736999999999996,
"PAX": 0.22736999999999996,
"USDC": 0.22736999999999996
}
},
"minerFees": {
"BTC": {
"totalFee": 100
},
"BCH": {
"totalFee": 0
},
"ETH": {
"totalFee": 0
},
"GUSD": {
"totalFee": 0
},
"PAX": {
"totalFee": 0
},
"USDC": {
"totalFee": 0
},
"XRP": {
"totalFee": 0
}
},
"shopper": {},
"BTC": {
"enabled": true
},
"BCH": {
"enabled": true
},
"ETH": {
"enabled": true
},
"GUSD": {
"enabled": true
},
"PAX": {
"enabled": true
},
"USDC": {
"enabled": true
},
"XRP": {
"enabled": true
}
},
"paymentCodes": {
"BTC": {
"BIP72b": "bitcoin:?r=https://test.bitpay.com/i/e6XJ7a5CKophekJwKyJ1M",
"BIP73": "https://test.bitpay.com/i/e6XJ7a5CKophekJwKyJ1M"
},
"BCH": {
"BIP72b": "bitcoincash:?r=https://test.bitpay.com/i/e6XJ7a5CKophekJwKyJ1M",
},
"ETH": {
"EIP681": "ethereum:?r=https://test.bitpay.com/i/e6XJ7a5CKophekJwKyJ1M"
},
"GUSD": {
"EIP681b": "ethereum:?r=https://test.bitpay.com/i/e6XJ7a5CKophekJwKyJ1M"
},
"PAX": {
},
"USDC": {
},
"XRP": {
"BIP72b": "ripple:?r=https://test.bitpay.com/i/e6XJ7a5CKophekJwKyJ1M",
"RIP681": "https://test.bitpay.com/i/e6XJ7a5CKophekJwKyJ1M",
}
},
"token": "3vs8MUB4mCiu9fvLSLnv2SCMjh3mPnTXrF9JdgWEKWXSRE73LZWAkzHqoTYLBGBimM"
}
}
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 resourc
e section.
Fetch an
invoice by
id
GET
https://bitpay.com/invoices/<invoiceid>
Facades
PUBLIC POS
MERCHANT
HTTP
Request
curl -X GET -H "x-accept-version: 2.0.0" -H "content-type: application/json"

"https://test.bitpay.com/invoices/e6XJ7a5CKophekJwKyJ1M?
token=92zP1M2t4T3iHEsATh8EEsYUiKaq9rQjGEezJmURddoW"
curl -X GET -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-

signature:
3045022100bc8271eae18d54ebe5a9d4b40d736fa53630435fa92f7049112ddcd25895275c022040392a66f4a
1904a53cfd612d764f300e026c84fb0be2b2e8f59a47d60cee374"
"https://test.bitpay.com/invoices/e6XJ7a5CKophekJwKyJ1M?
token=6oE1tYw1xMqUjM97dk57cwbda5sxbXTkUgg7UKpwkzEE"
URL
Parameter
s
?token=
when fetching an invoice via the merchant or the pos facade, pass strin

g C
the API token as a URL parameter. No token is required when
viewing an invoice from the public facade.
It is only possible to fetch an invoice via the public facade for 72 hours. Pass this delay, you
would need to fetch the invoice via the pos or merchant facade
Headers
fields Presence
x-accept-version:
M
must be set to 2.0.0 for request to the BitPay API
content-type
M
must be set to application/json for request to the BitPay API
x-identity
x-signature
HTTP
Response
For invoices fetched via the pos facade (unsigned requests)
{
"facade": "pos/invoice",
"data": {
"status": "confirmed",
"price": 10,
"currency": "EUR",
"invoiceTime": 1580120872157,
"currentTime": 1580122935493,
"amountPaid": 127900,
"phoneNumber": "555-123-456",
"selectedTransactionCurrency": "BTC"
},
"BTC": 127800,
"BCH": 3070600,
"ETH": 66409000000000000,
"GUSD": 1102,
"PAX": 11020000000000000000,
"USDC": 11020000,
"XRP": 48435532
},
"paymentTotals": {
"BTC": 127900,
"BCH": 3070600,
"ETH": 66409000000000000,
"GUSD": 1102,
"PAX": 11020000000000000000,
"USDC": 11020000,
"XRP": 48435532
},
"BTC": "0.001279",
"BCH": "0.030706",
"ETH": "0.066409",
"GUSD": "11.02",
"PAX": "11.02",
"USDC": "11.02",
"XRP": "48.435532"
},
"BTC": "0.001278",
"BCH": "0.030706",
"ETH": "0.066409",
"GUSD": "11.02",
"PAX": "11.02",
"USDC": "11.02",
"XRP": "48.435532"
},
"exchangeRates": {
"BTC": {
"EUR": 7824.000000000001,
"USD": 8620.09,
"BCH": 23.991344280545505,
"ETH": 51.95329074252653,
"GUSD": 8620.09,
"PAX": 8620.09,
"USDC": 8620.09,
"XRP": 37910.50224294133
},
"BCH": {
"EUR": 325.6700000000001,
"USD": 358.8195423959139,
"BTC": 0.04162591395332377,
"ETH": 2.162605706739756,
"GUSD": 358.8195423959139,
"PAX": 358.8195423959139,
"USDC": 358.8195423959139,
"XRP": 1578.0611680469929
},
"ETH": {
"EUR": 150.58117313,
"USD": 165.89,
"BTC": 0.019244556327652807,
"BCH": 0.4617033119955469,
"GUSD": 165.89,
"PAX": 165.89,
"USDC": 165.89,
"XRP": 729.5716421848887
},
"GUSD": {
"EUR": 0.9077170000000001,
"USD": 1,
"BTC": 0.00011600793494275007,
"BCH": 0.0027831895352073473,
"ETH": 0.006027000964320154,
"PAX": 1,
"USDC": 1,
"XRP": 4.3979241797871405
},
"PAX": {
"EUR": 0.9077170000000001,
"USD": 1,
"BTC": 0.00011600793494275007,
"BCH": 0.0027831895352073473,
"ETH": 0.006027000964320154,
"GUSD": 1,
"USDC": 1,
"XRP": 4.3979241797871405
},
"USDC": {
"EUR": 0.9077170000000001,
"USD": 1,
"BTC": 0.00011600793494275007,
"BCH": 0.0027831895352073473,
"ETH": 0.006027000964320154,
"GUSD": 1,
"PAX": 1,
"XRP": 4.3979241797871405
},
"XRP": {
"EUR": 0.20646,
"USD": 0.22736999999999996,
"BTC": 0.000026376724167933077,
"BCH": 0.0006328138046200945,
"ETH": 0.0013703592092574734,
"GUSD": 0.22736999999999996,
"PAX": 0.22736999999999996,
"USDC": 0.22736999999999996
}
},
"BTC": {
"enabled": true
},
"BCH": {
"enabled": true
},
"ETH": {
"enabled": true
},
"GUSD": {
"enabled": true
},
"PAX": {
"enabled": true
},
"USDC": {
"enabled": true
},
"XRP": {
"enabled": true
}
},
"minerFees": {
"BTC": {
"totalFee": 100
},
"BCH": {
"totalFee": 0
},
"ETH": {
"totalFee": 0
},
"GUSD": {
"totalFee": 0
},
"PAX": {
"totalFee": 0
},
"USDC": {
"totalFee": 0
},
"XRP": {
"totalFee": 0
}
},
"transactionCurrency": "BTC",
"paymentCodes": {
"BTC": {
},
"BCH": {
},
"ETH": {
},
"GUSD": {
},
"PAX": {
},
"USDC": {
},
"XRP": {
}
},
"token": "24pcN5BntaZcQEavHzuzVEQo7kLpHbC9eXrAvR583AiFm66e7wHidfRHEEYNXdLEJD"
}
}
For invoices fetched via the merchant facade (signed requests)
{
"data": {
"price": 10,
"currency": "EUR",
"invoiceTime": 1580120872157,
"currentTime": 1580123051777,
"transactions": [
{
"amount": 127900,
"confirmations": 4,
"receivedTime": "2020-01-27T10:29:04.199Z",
"txid": "e9f893acaacdbdfc939a0692420c77e5ebf16ca78654da253ce2e51f388c2cc3",
"exRates": {
"BTC": 1,
"EUR": 7824.000000000001,
"USD": 8620.09,
"BCH": 24.031474770002784,
"ETH": 51.987757071346714,
"GUSD": 8620.09,
"PAX": 8620.09,
"USDC": 8620.09,
"XRP": 37910.50224294133
},
"outputIndex": 1
},
{
"amount": -100,
"confirmations": 4,
"receivedTime": "2020-01-27T10:29:04.211Z",
"type": "buyerPaidMinerFee",
"txid": "e9f893acaacdbdfc939a0692420c77e5ebf16ca78654da253ce2e51f388c2cc3"
}
],
"buyer": {
"region": "VA",
"country": "US",
"phone": "555-123-456",
"notify": true
},
"phoneNumber": "555-123-456",
"selectedTransactionCurrency": "BTC",
},
"BTC": 127800,
"BCH": 3070600,
"ETH": 66409000000000000,
"GUSD": 1102,
"PAX": 11020000000000000000,
"USDC": 11020000,
"XRP": 48435532
},
"paymentTotals": {
"BTC": 127900,
"BCH": 3070600,
"ETH": 66409000000000000,
"GUSD": 1102,
"PAX": 11020000000000000000,
"USDC": 11020000,
"XRP": 48435532
},
"BTC": "0.001279",
"BCH": "0.030706",
"ETH": "0.066409",
"GUSD": "11.02",
"PAX": "11.02",
"USDC": "11.02",
"XRP": "48.435532"
},
"BTC": "0.001278",
"BCH": "0.030706",
"ETH": "0.066409",
"GUSD": "11.02",
"PAX": "11.02",
"USDC": "11.02",
"XRP": "48.435532"
},
"exchangeRates": {
"BTC": {
"EUR": 7824.000000000001,
"USD": 8620.09,
"BCH": 23.991344280545505,
"ETH": 51.95329074252653,
"GUSD": 8620.09,
"PAX": 8620.09,
"USDC": 8620.09,
"XRP": 37910.50224294133
},
"BCH": {
"EUR": 325.6700000000001,
"USD": 358.8195423959139,
"BTC": 0.04162591395332377,
"ETH": 2.162605706739756,
"GUSD": 358.8195423959139,
"PAX": 358.8195423959139,
"USDC": 358.8195423959139,
"XRP": 1578.0611680469929
},
"ETH": {
"EUR": 150.58117313,
"USD": 165.89,
"BTC": 0.019244556327652807,
"BCH": 0.4617033119955469,
"GUSD": 165.89,
"PAX": 165.89,
"USDC": 165.89,
"XRP": 729.5716421848887
},
"GUSD": {
"EUR": 0.9077170000000001,
"USD": 1,
"BTC": 0.00011600793494275007,
"BCH": 0.0027831895352073473,
"ETH": 0.006027000964320154,
"PAX": 1,
"USDC": 1,
"XRP": 4.3979241797871405
},
"PAX": {
"EUR": 0.9077170000000001,
"USD": 1,
"BTC": 0.00011600793494275007,
"BCH": 0.0027831895352073473,
"ETH": 0.006027000964320154,
"GUSD": 1,
"USDC": 1,
"XRP": 4.3979241797871405
},
"USDC": {
"EUR": 0.9077170000000001,
"USD": 1,
"BTC": 0.00011600793494275007,
"BCH": 0.0027831895352073473,
"ETH": 0.006027000964320154,
"GUSD": 1,
"PAX": 1,
"XRP": 4.3979241797871405
},
"XRP": {
"EUR": 0.20646,
"USD": 0.22736999999999996,
"BTC": 0.000026376724167933077,
"BCH": 0.0006328138046200945,
"ETH": 0.0013703592092574734,
"GUSD": 0.22736999999999996,
"PAX": 0.22736999999999996,
"USDC": 0.22736999999999996
}
},
"minerFees": {
"BTC": {
"totalFee": 100
},
"BCH": {
"totalFee": 0
},
"ETH": {
"totalFee": 0
},
"GUSD": {
"totalFee": 0
},
"PAX": {
"totalFee": 0
},
"USDC": {
"totalFee": 0
},
"XRP": {
"totalFee": 0
}
},
"shopper": {},
"BTC": {
"enabled": true
},
"BCH": {
"enabled": true
},
"ETH": {
"enabled": true
},
"GUSD": {
"enabled": true
},
"PAX": {
"enabled": true
},
"USDC": {
"enabled": true
},
"XRP": {
"enabled": true
}
},
"paymentCodes": {
"BTC": {
},
"BCH": {
},
"ETH": {
},
"GUSD": {
},
"PAX": {
},
"USDC": {
},
"XRP": {
}
},
}
}
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 resourc
e section.
Retrieves
invoices
filtered by
query
GET
Facades
MERCHANT
HTTP
Request

signature:
3044022046fc85eac5f5131f1a00e94180100f085b2869bd4cc0c7531ec60695cc2da96d022046efb5e12ee2d
a2ab5a6eea2674c640da7cacde8105758d53fd3d8cd824ab521" "https://test.bitpay.com/invoices?
token=6oE1tYw1xMqUjM97dk57cwbda5sxbXTkUgg7UKpwkzEE&status=complete&dateStart=2020-1-
24&dateEnd=2020-1-28&limit=2&offset=0"
URL
Parameter
s
?token=
A merchant facade token can be retrieved using strin

g M
the Tokens resource. This is described in the section Request an
API token).
&dateStart=
strin
g M
the start of the date window to query for invoices. Format YYYY-
MM-DD
&dateEnd=
strin
g M
the end of the date window to query for invoices. Format YYYY-MM-
DD
&status=
strin
g O
the invoice status you want to query on
&orderId=
strin
g O
the optional order id specified at time of invoice creation
&limit=
numbe
maximum results that the query will return (useful for paging r O
results)
&offset=
numbe
number of results to offset (ex. skip 10 will give you results r O
starting with the 11th result)
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
M
the hexadecimal public key generated from the client private key
x-signature M
request body, signed with your private key
HTTP
Response
{
"data": [
{
"url": "https://test.bitpay.com/invoice?id=Fcf2vgGCis8XVCfr8gkQE6",
"price": 10,
"currency": "EUR",
"invoiceTime": 1580123726908,
"currentTime": 1580125266008,
"id": "Fcf2vgGCis8XVCfr8gkQE6",
"amountPaid": 66314000000000000,
"transactions": [
{
"amount": 66314000000000000,
"time": "2020-01-27T11:16:36.000Z",
"receivedTime": "2020-01-27T11:16:36.000Z",
"txid": "0x90b8cf02c3318a8b1873623b97283ceb4e9aea440f0cd9cd4a047fa9567904b7",
"exRates": {
"ETH": 1,
"EUR": 150.95091708,
"BTC": 0.019279303080656042,
"USD": 166.38000000000002,
"BCH": 0.45999447055570913,
"GUSD": 166.38000000000002,
"PAX": 166.38000000000002,
"USDC": 166.38000000000002,
"XRP": 730.8266713520162
}
}
],
"buyer": {
"region": "VA",
"country": "US",
"phone": "555-123-456",
"notify": true
},
"phoneNumber": "555-123-456",
"selectedTransactionCurrency": "ETH",
},
"BTC": 127800,
"BCH": 3057300,
"ETH": 66314000000000000,
"GUSD": 1102,
"PAX": 11020000000000000000,
"USDC": 11020000,
"XRP": 48390999
},
"paymentTotals": {
"BTC": 127900,
"BCH": 3057300,
"ETH": 66314000000000000,
"GUSD": 1102,
"PAX": 11020000000000000000,
"USDC": 11020000,
"XRP": 48390999
},
"BTC": "0.001279",
"BCH": "0.030573",
"ETH": "0.066314",
"GUSD": "11.02",
"PAX": "11.02",
"USDC": "11.02",
"XRP": "48.390999"
},
"BTC": "0.001278",
"BCH": "0.030573",
"ETH": "0.066314",
"GUSD": "11.02",
"PAX": "11.02",
"USDC": "11.02",
"XRP": "48.390999"
},
"exchangeRates": {
"BTC": {
"EUR": 7825.65,
"USD": 8629.99,
"BCH": 23.892552602436325,
"ETH": 51.91908314282277,
"GUSD": 8629.99,
"PAX": 8629.99,
"USDC": 8629.99,
"XRP": 37904.031974701335
},
"BCH": {
"EUR": 327.09,
"USD": 360.79999999999995,
"BTC": 0.04180764774044032,
"ETH": 2.170617254241367,
"GUSD": 360.79999999999995,
"PAX": 360.79999999999995,
"USDC": 360.79999999999995,
"XRP": 1584.680252986648
},
"ETH": {
"EUR": 150.79668186,
"USD": 166.21,
"BTC": 0.019259559675550406,
"BCH": 0.4601605758582504,
"GUSD": 166.21,
"PAX": 166.21,
"USDC": 166.21,
"XRP": 730.0158116654954
},
"GUSD": {
"EUR": 0.907266,
"USD": 1,
"BTC": 0.00011587485515643104,
"BCH": 0.0027685492801771874,
"ETH": 0.006016123210203345,
"PAX": 1,
"USDC": 1,
"XRP": 4.392129304286718
},
"PAX": {
"EUR": 0.907266,
"USD": 1,
"BTC": 0.00011587485515643104,
"BCH": 0.0027685492801771874,
"ETH": 0.006016123210203345,
"GUSD": 1,
"USDC": 1,
"XRP": 4.392129304286718
},
"USDC": {
"EUR": 0.907266,
"USD": 1,
"BTC": 0.00011587485515643104,
"BCH": 0.0027685492801771874,
"ETH": 0.006016123210203345,
"GUSD": 1,
"PAX": 1,
"XRP": 4.392129304286718
},
"XRP": {
"EUR": 0.20665000000000003,
"USD": 0.22755,
"BTC": 0.000026367323290845883,
"BCH": 0.000629983388704319,
"ETH": 0.0013689688364817714,
"GUSD": 0.22755,
"PAX": 0.22755,
"USDC": 0.22755
}
},
"minerFees": {
"BTC": {
"totalFee": 100
},
"BCH": {
"totalFee": 0
},
"ETH": {
"totalFee": 0
},
"GUSD": {
"totalFee": 0
},
"PAX": {
"totalFee": 0
},
"USDC": {
"totalFee": 0
},
"XRP": {
"totalFee": 0
}
},
"shopper": {},
"BTC": {
"enabled": true
},
"BCH": {
"enabled": true
},
"ETH": {
"enabled": true
},
"GUSD": {
"enabled": true
},
"PAX": {
"enabled": true
},
"USDC": {
"enabled": true
},
"XRP": {
"enabled": true
}
},
"paymentCodes": {
"BTC": {
"BIP72b": "bitcoin:?r=https://test.bitpay.com/i/Fcf2vgGCis8XVCfr8gkQE6",
"BIP73": "https://test.bitpay.com/i/Fcf2vgGCis8XVCfr8gkQE6"
},
"BCH": {
"BIP72b": "bitcoincash:?r=https://test.bitpay.com/i/Fcf2vgGCis8XVCfr8gkQE6",
},
"ETH": {
"EIP681": "ethereum:?r=https://test.bitpay.com/i/Fcf2vgGCis8XVCfr8gkQE6"
},
"GUSD": {
"EIP681b": "ethereum:?r=https://test.bitpay.com/i/Fcf2vgGCis8XVCfr8gkQE6"
},
"PAX": {
},
"USDC": {
},
"XRP": {
"BIP72b": "ripple:?r=https://test.bitpay.com/i/Fcf2vgGCis8XVCfr8gkQE6",
"RIP681": "https://test.bitpay.com/i/Fcf2vgGCis8XVCfr8gkQE6",
}
},
"token": "3vs8MUB4mCiu9fvLSLnv2S9KMFCxKrTPcmrNY7z7imrnHob9pMeG2queq3qg1Qw5Ch"
},
{
"price": 10,
"currency": "EUR",
"invoiceTime": 1580120872157,
"currentTime": 1580125266016,
"transactions": [
{
"amount": 127900,
"confirmations": 6,
"receivedTime": "2020-01-27T10:29:04.199Z",
"txid": "e9f893acaacdbdfc939a0692420c77e5ebf16ca78654da253ce2e51f388c2cc3",
"exRates": {
"BTC": 1,
"EUR": 7824.000000000001,
"USD": 8620.09,
"BCH": 24.031474770002784,
"ETH": 51.987757071346714,
"GUSD": 8620.09,
"PAX": 8620.09,
"USDC": 8620.09,
"XRP": 37910.50224294133
},
"outputIndex": 1
},
{
"amount": -100,
"confirmations": 6,
"receivedTime": "2020-01-27T10:29:04.211Z",
"type": "buyerPaidMinerFee",
"txid": "e9f893acaacdbdfc939a0692420c77e5ebf16ca78654da253ce2e51f388c2cc3"
}
],
"buyer": {
"region": "VA",
"country": "US",
"phone": "555-123-456",
"notify": true
},
"phoneNumber": "555-123-456",
"selectedTransactionCurrency": "BTC",
},
"BTC": 127800,
"BCH": 3070600,
"ETH": 66409000000000000,
"GUSD": 1102,
"PAX": 11020000000000000000,
"USDC": 11020000,
"XRP": 48435532
},
"paymentTotals": {
"BTC": 127900,
"BCH": 3070600,
"ETH": 66409000000000000,
"GUSD": 1102,
"PAX": 11020000000000000000,
"USDC": 11020000,
"XRP": 48435532
},
"BTC": "0.001279",
"BCH": "0.030706",
"ETH": "0.066409",
"GUSD": "11.02",
"PAX": "11.02",
"USDC": "11.02",
"XRP": "48.435532"
},
"BTC": "0.001278",
"BCH": "0.030706",
"ETH": "0.066409",
"GUSD": "11.02",
"PAX": "11.02",
"USDC": "11.02",
"XRP": "48.435532"
},
"exchangeRates": {
"BTC": {
"EUR": 7824.000000000001,
"USD": 8620.09,
"BCH": 23.991344280545505,
"ETH": 51.95329074252653,
"GUSD": 8620.09,
"PAX": 8620.09,
"USDC": 8620.09,
"XRP": 37910.50224294133
},
"BCH": {
"EUR": 325.6700000000001,
"USD": 358.8195423959139,
"BTC": 0.04162591395332377,
"ETH": 2.162605706739756,
"GUSD": 358.8195423959139,
"PAX": 358.8195423959139,
"USDC": 358.8195423959139,
"XRP": 1578.0611680469929
},
"ETH": {
"EUR": 150.58117313,
"USD": 165.89,
"BTC": 0.019244556327652807,
"BCH": 0.4617033119955469,
"GUSD": 165.89,
"PAX": 165.89,
"USDC": 165.89,
"XRP": 729.5716421848887
},
"GUSD": {
"EUR": 0.9077170000000001,
"USD": 1,
"BTC": 0.00011600793494275007,
"BCH": 0.0027831895352073473,
"ETH": 0.006027000964320154,
"PAX": 1,
"USDC": 1,
"XRP": 4.3979241797871405
},
"PAX": {
"EUR": 0.9077170000000001,
"USD": 1,
"BTC": 0.00011600793494275007,
"BCH": 0.0027831895352073473,
"ETH": 0.006027000964320154,
"GUSD": 1,
"USDC": 1,
"XRP": 4.3979241797871405
},
"USDC": {
"EUR": 0.9077170000000001,
"USD": 1,
"BTC": 0.00011600793494275007,
"BCH": 0.0027831895352073473,
"ETH": 0.006027000964320154,
"GUSD": 1,
"PAX": 1,
"XRP": 4.3979241797871405
},
"XRP": {
"EUR": 0.20646,
"USD": 0.22736999999999996,
"BTC": 0.000026376724167933077,
"BCH": 0.0006328138046200945,
"ETH": 0.0013703592092574734,
"GUSD": 0.22736999999999996,
"PAX": 0.22736999999999996,
"USDC": 0.22736999999999996
}
},
"minerFees": {
"BTC": {
"totalFee": 100
},
"BCH": {
"totalFee": 0
},
"ETH": {
"totalFee": 0
},
"GUSD": {
"totalFee": 0
},
"PAX": {
"totalFee": 0
},
"USDC": {
"totalFee": 0
},
"XRP": {
"totalFee": 0
}
},
"shopper": {},
"BTC": {
"enabled": true
},
"BCH": {
"enabled": true
},
"ETH": {
"enabled": true
},
"GUSD": {
"enabled": true
},
"PAX": {
"enabled": true
},
"USDC": {
"enabled": true
},
"XRP": {
"enabled": true
}
},
"paymentCodes": {
"BTC": {
},
"BCH": {
},
"ETH": {
},
"GUSD": {
},
"PAX": {
},
"USDC": {
},
"XRP": {
}
},
}
]
}
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 resourc
e 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 MER
CHANT
HTTP
Request

"https://test.bitpay.com/invoices/G1ewS8GaCnPAMB2yhmHffy/events"

signature:
3046022100c713fa3655444a8a3dd1ccd63f9554f05e73ab4d6516521422ca98e224997023022100a21ab2f9f
f27752c41f7dfa21a1713ce0f9b38e3e0449c1ebe0ff8dbc7bc453d"
"https://test.bitpay.com/invoices/5oACoLiz3NLK5WwiNRWFtK/events?
token=6oE1tYw1xMqUjM97dk57cwbda5sxbXTkUgg7UKpwkzEE"
URL
Parameter
s
<invoiceId>
strin
g M
the id of the invoice for which you want to fetch an event token
?token=
A merchant facade token can be retrieved using strin

the Tokens resource. This is described in the section Request an g C
API token) No token is required if fetching the event token via
the public.
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
the hexadecimal public key generated from the client private key. This header is C
required when using tokens with higher privileges ( merchant facade). When
using the standard public facade, this header is not needed.
x-signature
tokens with higher privileges (merchant facade). When using the
standard public facade, this header is not needed.
HTTP
Response
For events token fetched via the public facade (unsigned requests)
{
"facade": "public/invoice",
"data": {
"url": "https://test.bitpay.com/events",
"token": "767cdhmwtn7XgW1QrSkuEwh6YXqY1BLL4fcFUnhk7amKQV8m3az6QmVEjbUFv19UTu",
"events": [
"payment",
"confirmation",
"paymentRejected",
"scanned",
"paymentPosted"
],
"actions": [
"subscribe",
"unsubscribe"
]
}
}
For events token fetched via the merchant facade (signed requests)
{
"data": {
"url": "https://test.bitpay.com/events",
"token": "7Bhs6Y9duMNLKWF7Jy3e7UGMi9K6FAHFtP9iTmcXkSFJ6x3g872QyC1Gx2u3pehncB",
"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.
string
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
data
object
invoices event data object
url
string
base URL where you can subscribe to events (HTTP long polling)
token
string
API token for subscriber resource, passed as ?token= query parameter value
events array
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.
actions
All supported &action= query parameter values. Can array
be subscribe or unsubscribe.
Subscribe
to invoice
events
(HTTP long
polling)
retry: 2000
event: connect
data: {"status":"subscribed","resource":"G1ewS8GaCnPAMB2yhmHffy","facade":"public/
invoice","events":["payment","confirmation","paymentRejected","scanned","paymentPosted"]}
event: state
data: {"url":"https://test.bitpay.com/invoice?
id=G1ewS8GaCnPAMB2yhmHffy","posData":"tx91011","status":"new","price":10,"currency":"EUR"
,"itemDesc":"Item
XYZ","orderId":"MerchantOrder789","invoiceTime":1580125459457,"expirationTime":1580126359
457,"currentTime":1580125560280,"id":"G1ewS8GaCnPAMB2yhmHffy","lowFeeDetected":false,"amo
untPaid":0,"displayAmountPaid":"0","exceptionStatus":false,"redirectURL":"https://
yourredirecturl.com","refundAddressRequestPending":false,"buyerProvidedInfo":{"name":"Fox
Mulder","phoneNumber":"555-123-456"},"paymentSubtotals":
{"BTC":127700,"BCH":3060900,"ETH":66151000000000000,"GUSD":1102,"PAX":1102000000000000000
0,"USDC":11020000,"XRP":48320850},"paymentTotals":
0,"USDC":11020000,"XRP":48320850},"paymentDisplayTotals":
{"BTC":"0.001278","BCH":"0.030609","ETH":"0.066151","GUSD":"11.02","PAX":"11.02","USDC":"
11.02","XRP":"48.320850"},"paymentDisplaySubTotals":
11.02","XRP":"48.320850"},"exchangeRates":{"BTC":
{"EUR":7828.46,"USD":8626.619999999999,"BCH":23.889836610357243,"ETH":51.771109644121715,
"GUSD":8626.619999999999,"PAX":8626.619999999999,"USDC":8626.619999999999,"XRP":37807.862
55861857},"BCH":
{"EUR":326.7,"USD":360.70000000000005,"BTC":0.04181544168792024,"ETH":2.16467622877033,"G
USD":360.70000000000005,"PAX":360.70000000000005,"USDC":360.70000000000005,"XRP":1580.838
8482271992},"ETH":
{"EUR":151.16866091999998,"USD":166.61999999999998,"BTC":0.01931602133086019,"BCH":0.4614
2342841318196,"GUSD":166.61999999999998,"PAX":166.61999999999998,"USDC":166.6199999999999
8,"XRP":730.2449927685498},"GUSD":
{"EUR":0.907266,"USD":1,"BTC":0.0001159285879897983,"BCH":0.0027693159789531985,"ETH":0.0
06001320290463902,"PAX":1,"USDC":1,"XRP":4.382697111802603},"PAX":
06001320290463902,"GUSD":1,"USDC":1,"XRP":4.382697111802603},"USDC":
06001320290463902,"GUSD":1,"PAX":1,"XRP":4.382697111802603},"XRP":
{"EUR":0.20695000000000002,"USD":0.2281,"BTC":0.00002644331092047299,"BCH":0.000631680974
7992247,"ETH":0.001368901158254816,"GUSD":0.2281,"PAX":0.2281,"USDC":0.2281}},"supportedT
ransactionCurrencies":{"BTC":{"enabled":true},"BCH":{"enabled":true},"ETH":
{"enabled":true},"GUSD":{"enabled":true},"PAX":{"enabled":true},"USDC":
{"enabled":true},"XRP":{"enabled":true}},"minerFees":{"BTC":
{"satoshisPerByte":1,"totalFee":100},"BCH":{"satoshisPerByte":0,"totalFee":0},"ETH":
{"satoshisPerByte":0,"totalFee":0},"GUSD":{"satoshisPerByte":0,"totalFee":0},"PAX":
{"satoshisPerByte":0,"totalFee":0},"USDC":{"satoshisPerByte":0,"totalFee":0},"XRP":
{"satoshisPerByte":0,"totalFee":0}},"jsonPayProRequired":false,"paymentCodes":{"BTC":
{"BIP72b":"bitcoin:?r=https://test.bitpay.com/i/
G1ewS8GaCnPAMB2yhmHffy","BIP73":"https://test.bitpay.com/i/
G1ewS8GaCnPAMB2yhmHffy"},"BCH":{"BIP72b":"bitcoincash:?r=https://test.bitpay.com/i/
G1ewS8GaCnPAMB2yhmHffy"},"ETH":{"EIP681":"ethereum:?r=https://test.bitpay.com/i/
G1ewS8GaCnPAMB2yhmHffy"},"GUSD":{"EIP681b":"ethereum:?r=https://test.bitpay.com/i/
G1ewS8GaCnPAMB2yhmHffy"},"PAX":{"EIP681b":"ethereum:?r=https://test.bitpay.com/i/
G1ewS8GaCnPAMB2yhmHffy"},"USDC":{"EIP681b":"ethereum:?r=https://test.bitpay.com/i/
G1ewS8GaCnPAMB2yhmHffy"},"XRP":{"BIP72b":"ripple:?r=https://test.bitpay.com/i/
G1ewS8GaCnPAMB2yhmHffy","RIP681":"https://test.bitpay.com/i/
G1ewS8GaCnPAMB2yhmHffy"}},"token":"767cdhmwtn7XgW1QrSkuEwh6YXqY1BLL4fcFUnhk7amKQV8m3az6Qm
VEjbUFv19UTu"}
: heartbeat
event: scanned
data: {"scanned":true,"userAgent":"bitpay 8.2.5 (iOS 13.3 - iPhone9,3)"}
event: scanned
event: scanned
: heartbeat
event: scanned
event: scanned
event: paymentPosted
data: {"paymentPosted":true}
event: paymentPosted
data: {"paymentPosted":true}
event: statechange
id=G1ewS8GaCnPAMB2yhmHffy","posData":"tx91011","status":"paid","price":10,"currency":"EUR
","itemDesc":"Item
untPaid":127800,"displayAmountPaid":"0.001278","exceptionStatus":false,"redirectURL":"htt
ps://yourredirecturl.com","refundAddressRequestPending":false,"buyerProvidedInfo":
{"name":"Fox Mulder","phoneNumber":"555-123-
456","selectedTransactionCurrency":"BTC"},"paymentSubtotals":
{"EUR":7828.46,"USD":8626.619999999999,"BCH":23.889836610357243,"ETH":51.771109644121715,
"GUSD":8626.619999999999,"PAX":8626.619999999999,"USDC":8626.619999999999,"XRP":37807.862
55861857},"BCH":
{"EUR":326.7,"USD":360.70000000000005,"BTC":0.04181544168792024,"ETH":2.16467622877033,"G
USD":360.70000000000005,"PAX":360.70000000000005,"USDC":360.70000000000005,"XRP":1580.838
8482271992},"ETH":
{"EUR":151.16866091999998,"USD":166.61999999999998,"BTC":0.01931602133086019,"BCH":0.4614
2342841318196,"GUSD":166.61999999999998,"PAX":166.61999999999998,"USDC":166.6199999999999
8,"XRP":730.2449927685498},"GUSD":
06001320290463902,"PAX":1,"USDC":1,"XRP":4.382697111802603},"PAX":
06001320290463902,"GUSD":1,"PAX":1,"XRP":4.382697111802603},"XRP":
{"EUR":0.20695000000000002,"USD":0.2281,"BTC":0.00002644331092047299,"BCH":0.000631680974
{"satoshisPerByte":0,"totalFee":0}},"jsonPayProRequired":false,"transactionCurrency":"BTC
","paymentCodes":{"BTC":{"BIP72b":"bitcoin:?r=https://test.bitpay.com/i/
G1ewS8GaCnPAMB2yhmHffy","BIP73":"https://test.bitpay.com/i/G1ewS8GaCnPAMB2yhmHffy"}}}
: heartbeat
: heartbeat
event: statechange
id=G1ewS8GaCnPAMB2yhmHffy","posData":"tx91011","status":"confirmed","price":10,"currency"
:"EUR","itemDesc":"Item
{"EUR":7828.46,"USD":8626.619999999999,"BCH":23.889836610357243,"ETH":51.771109644121715,
"GUSD":8626.619999999999,"PAX":8626.619999999999,"USDC":8626.619999999999,"XRP":37807.862
55861857},"BCH":
{"EUR":326.7,"USD":360.70000000000005,"BTC":0.04181544168792024,"ETH":2.16467622877033,"G
USD":360.70000000000005,"PAX":360.70000000000005,"USDC":360.70000000000005,"XRP":1580.838
8482271992},"ETH":
{"EUR":151.16866091999998,"USD":166.61999999999998,"BTC":0.01931602133086019,"BCH":0.4614
2342841318196,"GUSD":166.61999999999998,"PAX":166.61999999999998,"USDC":166.6199999999999
8,"XRP":730.2449927685498},"GUSD":
06001320290463902,"PAX":1,"USDC":1,"XRP":4.382697111802603},"PAX":
06001320290463902,"GUSD":1,"PAX":1,"XRP":4.382697111802603},"XRP":
{"EUR":0.20695000000000002,"USD":0.2281,"BTC":0.00002644331092047299,"BCH":0.000631680974
: heartbeat
: heartbeat
event: statechange
{"EUR":7828.46,"USD":8626.619999999999,"BCH":23.889836610357243,"ETH":51.771109644121715,
"GUSD":8626.619999999999,"PAX":8626.619999999999,"USDC":8626.619999999999,"XRP":37807.862
55861857},"BCH":
{"EUR":326.7,"USD":360.70000000000005,"BTC":0.04181544168792024,"ETH":2.16467622877033,"G
USD":360.70000000000005,"PAX":360.70000000000005,"USDC":360.70000000000005,"XRP":1580.838
8482271992},"ETH":
{"EUR":151.16866091999998,"USD":166.61999999999998,"BTC":0.01931602133086019,"BCH":0.4614
2342841318196,"GUSD":166.61999999999998,"PAX":166.61999999999998,"USDC":166.6199999999999
8,"XRP":730.2449927685498},"GUSD":
06001320290463902,"PAX":1,"USDC":1,"XRP":4.382697111802603},"PAX":
06001320290463902,"GUSD":1,"PAX":1,"XRP":4.382697111802603},"XRP":
{"EUR":0.20695000000000002,"USD":0.2281,"BTC":0.00002644331092047299,"BCH":0.000631680974
: heartbeat
: heartbeat
event: statechange
{"EUR":7828.46,"USD":8626.619999999999,"BCH":23.889836610357243,"ETH":51.771109644121715,
"GUSD":8626.619999999999,"PAX":8626.619999999999,"USDC":8626.619999999999,"XRP":37807.862
55861857},"BCH":
{"EUR":326.7,"USD":360.70000000000005,"BTC":0.04181544168792024,"ETH":2.16467622877033,"G
USD":360.70000000000005,"PAX":360.70000000000005,"USDC":360.70000000000005,"XRP":1580.838
8482271992},"ETH":
{"EUR":151.16866091999998,"USD":166.61999999999998,"BTC":0.01931602133086019,"BCH":0.4614
2342841318196,"GUSD":166.61999999999998,"PAX":166.61999999999998,"USDC":166.6199999999999
8,"XRP":730.2449927685498},"GUSD":
06001320290463902,"PAX":1,"USDC":1,"XRP":4.382697111802603},"PAX":
06001320290463902,"GUSD":1,"PAX":1,"XRP":4.382697111802603},"XRP":
{"EUR":0.20695000000000002,"USD":0.2281,"BTC":0.00002644331092047299,"BCH":0.000631680974
: heartbeat
: heartbeat
event: statechange
{"EUR":7828.46,"USD":8626.619999999999,"BCH":23.889836610357243,"ETH":51.771109644121715,
"GUSD":8626.619999999999,"PAX":8626.619999999999,"USDC":8626.619999999999,"XRP":37807.862
55861857},"BCH":
{"EUR":326.7,"USD":360.70000000000005,"BTC":0.04181544168792024,"ETH":2.16467622877033,"G
USD":360.70000000000005,"PAX":360.70000000000005,"USDC":360.70000000000005,"XRP":1580.838
8482271992},"ETH":
{"EUR":151.16866091999998,"USD":166.61999999999998,"BTC":0.01931602133086019,"BCH":0.4614
2342841318196,"GUSD":166.61999999999998,"PAX":166.61999999999998,"USDC":166.6199999999999
8,"XRP":730.2449927685498},"GUSD":
06001320290463902,"PAX":1,"USDC":1,"XRP":4.382697111802603},"PAX":
06001320290463902,"GUSD":1,"PAX":1,"XRP":4.382697111802603},"XRP":
{"EUR":0.20695000000000002,"USD":0.2281,"BTC":0.00002644331092047299,"BCH":0.000631680974
: heartbeat
: heartbeat
event: statechange
{"EUR":7828.46,"USD":8626.619999999999,"BCH":23.889836610357243,"ETH":51.771109644121715,
"GUSD":8626.619999999999,"PAX":8626.619999999999,"USDC":8626.619999999999,"XRP":37807.862
55861857},"BCH":
{"EUR":326.7,"USD":360.70000000000005,"BTC":0.04181544168792024,"ETH":2.16467622877033,"G
USD":360.70000000000005,"PAX":360.70000000000005,"USDC":360.70000000000005,"XRP":1580.838
8482271992},"ETH":
{"EUR":151.16866091999998,"USD":166.61999999999998,"BTC":0.01931602133086019,"BCH":0.4614
2342841318196,"GUSD":166.61999999999998,"PAX":166.61999999999998,"USDC":166.6199999999999
8,"XRP":730.2449927685498},"GUSD":
06001320290463902,"PAX":1,"USDC":1,"XRP":4.382697111802603},"PAX":
06001320290463902,"GUSD":1,"PAX":1,"XRP":4.382697111802603},"XRP":
{"EUR":0.20695000000000002,"USD":0.2281,"BTC":0.00002644331092047299,"BCH":0.000631680974
: 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 EventS
ource specif
ications. 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:
 ?
toke
n= -
you
"bu
pas
s"
retri
eve
fro
the
API
 &act
ion=
usu
ally
"su
bscr
ibe"
but
opti
ons
are
pro
vide
d in
you
bus
pas
 &eve
nts[
]= -
an
arra
y of
eve
nts
to
liste
for
(als
pro
vide
d in
the
bus
pas
s)
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/EventS
ource
specificatio
n, 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
EventSourc
e instance.
There are a
few event
types that
the bus will
expose:
 con
nec
t -
you
req
uest
was
vali
and
you
are
now
sub
scri
bed
to
the
reso
urce
 stat
e -
sent
im
me
diat
ely
foll
owi
ng
the
con
nect
eve
nt
and
con
tain
the
curr
ent
stat
e of
the
reso
urce
 stat
ech
ang
e -
sent
whe
nev
er
the
reso
urce
cha
nge
and
is
pub
lish
ed
to
the
bus
 err
or -
som
ethi
ng
wen
wro
ng,
you
sho
uld
clos
the
con
nect
ion
and
try
agai
n
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 http
s://test.bitp
ay.com/eve
nts?
token=767c
dhmwtn7X
gW1QrSkuE
wh6YXqY1B
LL4fcFUnhk
7amKQV8m
3az6QmVEj
bUFv19UTu
&action=su
bscribe&ev
ents[]=pay
ment&even
ts[]=confir
mation&ev
ents[]=pay
mentReject
ed&events[
]=scanned
&events[]=
paymentPo
sted
Refund an
invoice
POST
https://bitpay.com/invoices/<invoiceid>/refunds
Facades
MERCHANT
HTTP
Request

signature:
3045022100f635f3c07a6e8a0d3ffb14cc0c11c68177327bc29dfb7a623743d4a8696208f40220394882f88a4
69885d459f9ecc2b179086a59b83d0a7ee42aed5f6686af19d1f7" -d
'{"refundEmail":"lyric.brenham@uola.org","amount":5,"currency":"EUR","token":"3vs8MUB4mCi
u9fvLSLnv2SETDXYcXpEo1KRJs6aD7LZpUQQTiy9WE9QgWV2K7RCSHe"}'
"https://test.bitpay.com/invoices/5oACoLiz3NLK5WwiNRWFtK/refunds"
URL
Parameter
s
<invoiceId>
the id of the invoice you want to

string M
refund.
Headers
fields Presence
x-accept-version:
M
must be set to 2.0.0 for request to the BitPay API.
content-type
M
must be set to application/json for request to the BitPay API.
x-identity
M
the hexadecimal public key generated from the client private key.
x-signature
header is the ECDSA signature of the full request URL concatenated with the M
request body, signed with your private key.
Body
Name Type Presence
refundEmail
strin
g M
email address to which you want BitPay to send the refund link.
amount
numbe
The amount to be refunded, denominated in the invoice original r M
currency - partial refunds are supported
currency
strin
The currency in which to price the refund, same as the invoice g M
original currency.
token
The resource token for the <invoiceId> you want to refund. You strin
g M
need to retrieve this token from the invoice object itself, if using
the merchant facade (see section Fetch an invoice by id).
HTTP
Response
{
"success": true
}
Body
Name Type
success
set to true when a refund is successfully requested. At the same time an email boolean
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
Fetch the
status of
all refunds
on an
invoice
GET
https://bitpay.com/invoices/<invoiceid>/refunds
Facades
MERCHANT
HTTP
Request

signature:
3045022100c4300a82061bcc42ebaebcf787a61be13813d3e248ff01a3acf4667c972a774202203bddd290ee3
9cf8fcd4f4b00787e1e5b06ac8bd7aa3aa49b0840d0b71b4b3c9d"
"https://test.bitpay.com/invoices/5oACoLiz3NLK5WwiNRWFtK/refunds?
token=3vs8MUB4mCiu9fvLSLnv2SETDXYcXpEo1KRJs6aD7LZpUQQTiy9WE9QgWV2K7RCSHe"
URL
Parameter
s
<invoiceId>
strin
g M
The id of the invoice you want to look up.
?token=
The resource token for the <invoiceId> you want to look up. You strin
g M
need to retrieve this token from the invoice object itself, using the
merchant facade (see section Fetch an invoice by id).
Headers
fields Presence
x-accept-version: M
content-type
M
x-identity
M
x-signature
HTTP
Response
{
"facade": "merchant/supportRequest",
"data": [
{
"id": "SgNXo9DJbVTsisua7x5qzc",
"requestDate": "2020-01-27T12:07:35.691Z",
"status": "pending",
"params": {
"requesterType": "purchaser",
"requesterEmail": "fox.mulder@trustno.one",
"amount": 5,
"currency": "EUR",
"purchaserNotifyEmail": "lyric.brenham@uola.org",
"destinationTag": null,
"refundAddress": "0x2D21469a39FAA0011F18722c672607C0F0042cd3",
"commit": false,
"doit": false,
"supportRequestEid": "SgNXo9DJbVTsisua7x5qzc"
},
"token": "2GxRfYm8KDrpNvmwVBrHMqT1K9Uh4b8CdV1f2MU6VgDHmf4ZvseHSbLz5gjh3gzdhs"
}
]
}
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
cryptocurre
ncy 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
correspondi
ng refund
object.
Name Type
facade
string
Facade used to view the refund object created on a given invoice, set
to "merchant/supportRequest"
data
Refund objects with status "pending" or "success" created for the

array
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.
id
string
Contains the refund requestId.
requestDate
string
Date/time of the refund request. ISO-8601 format yyyy-mm-ddThh:mm:ssZ.
(UTC)
status
Status of the refund request, can be:
 "pending" If the refund request still needs to be executed by BitPay.

string
 "success" Once the refund request has been executed.
 "failure" If the refund request has been declined.
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 string
to create the invoice.
email
Purchaser's email address stored on the invoice string
purchaserNotifyEmail string
Email address to which the refund link was sent. This is equal to
the refundEmail used when submitting the refund request.
refundAddress
Contains the cryptocurrency address provided by the customer via the refund string
link which was emailed to him.
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 string
refund the invoice and is tied to the specific refund object created.
Fetch the
status of a
specific
refund
request
GET
https://bitpay.com/invoices/<invoiceid>/refunds/<requestid>
Facades
MERCHANT
HTTP
Request

signature:
3046022100db7842c60b3533e72ca42e19964b5fd487436829e6d31d1611f4d3724d9a48f2022100c70709db7
ea3dae0a96164184fbbfc4cbee1abfe7d083b7f4edce7f63dde34a2"
"https://test.bitpay.com/invoices/5oACoLiz3NLK5WwiNRWFtK/refunds/SgNXo9DJbVTsisua7x5qzc?
token=3vs8MUB4mCiu9fvLSLnv2SETDXYcXpEo1KRJs6aD7LZpUQQTiy9WE9QgWV2K7RCSHe"
URL
Parameter
s
<invoiceId>
strin
g M
The id of the invoice you want to look up.
<requestId>
strin
g M
The id of the refund request
?token=
The resource token for the <invoiceId> you want to look up. You strin
g M
need to retrieve this token from the invoice object itself, using the
Headers
fields Presence
x-accept-version: M
content-type
M
x-identity
M
x-signature
HTTP
Response
For a refund request fetched via the merchant facade (signed requests)
{
"facade": "merchant/supportRequest",
"data": {
"id": "SgNXo9DJbVTsisua7x5qzc",
"requestDate": "2020-01-27T12:07:35.691Z",
"status": "success",
"results": {
"type": "partial",
"refundTransactionCurrency": "ETH",
"adhoc": false,
"bitcoinPayouts": [
{
"bitcoinAddress": "0x2D21469a39FAA0011F18722c672607C0F0042cd3",
"invoiceSatoshis": 32747000000000000,
"refundSatoshis": 32747000000000000,
"refundFee": 0,
"exRates": {
"ETH": 1,
"EUR": 152.6856309,
"BTC": 0.019354950002587558,
"USD": 168.3,
"BCH": 0.4549878345498784,
"GUSD": 168.3,
"PAX": 168.3,
"USDC": 168.3,
"XRP": 731.357552581262
},
"amountFiat": 5,
"fiatCurrency": "EUR",
"amountUSD": 5.51,
"requestAmount": 5,
"requestCurrency": "EUR",
"ledgerAmount": 5.51,
"ledgerFeeAmount": 0,
"ledgerCurrency": "USD",
"txid": "0x5e3c32b8f66b67c9d410044f0b767ec1cac82bfb5fb730026b112537a923f1c3"
}
],
"before": {
"status": "paidFull",
"btcPaid": "0.065768",
"btcDue": "0.000000",
"price": 10,
"currency": "EUR",
"balances": {
"BTC": 0.029277,
"USD": 3488.11,
"EUR": 0,
"CAD": 0,
"MXN": 0,
"JPY": 0,
"GBP": 0,
"AUD": 0,
"NZD": 0,
"ZAR": 0
}
},
"after": {
"btcPaid": "0.065768",
"btcDue": "0.000000",
"price": 10,
"currency": "EUR"
},
"numericId": "789949",
"merchantName": "Test Account",
"checks": [
"ValidBitcoinAddress",
"InvoiceSufficientBalance",
"6Confirmations",
"NotBitPayAddress",
"LedgerSufficientBalance"
]
},
"params": {
"requesterType": "purchaser",
"requesterEmail": "fox.mulder@trustno.one",
"amount": 5,
"currency": "EUR",
"purchaserNotifyEmail": "lyric.brenham@uola.org",
"destinationTag": null,
"refundAddress": "0x2D21469a39FAA0011F18722c672607C0F0042cd3",
"commit": false,
"doit": false,
"supportRequestEid": "SgNXo9DJbVTsisua7x5qzc",
"txid": "0x5e3c32b8f66b67c9d410044f0b767ec1cac82bfb5fb730026b112537a923f1c3",
"effects": {
"type": "partial",
"refundTransactionCurrency": "ETH",
"adhoc": false,
"bitcoinPayouts": [
{
"bitcoinAddress": "0x2D21469a39FAA0011F18722c672607C0F0042cd3",
"invoiceSatoshis": 32747000000000000,
"refundSatoshis": 32747000000000000,
"refundFee": 0,
"exRates": {
"ETH": 1,
"EUR": 152.6856309,
"BTC": 0.019354950002587558,
"USD": 168.3,
"BCH": 0.4549878345498784,
"GUSD": 168.3,
"PAX": 168.3,
"USDC": 168.3,
"XRP": 731.357552581262
},
"amountFiat": 5,
"fiatCurrency": "EUR",
"amountUSD": 5.51,
"requestAmount": 5,
"requestCurrency": "EUR",
"ledgerAmount": 5.51,
"ledgerFeeAmount": 0,
"ledgerCurrency": "USD"
}
],
"before": {
"btcPaid": "0.065768",
"btcDue": "0.000000",
"price": 10,
"currency": "EUR",
"balances": {
"BTC": 0.029277,
"USD": 3488.11,
"EUR": 0,
"CAD": 0,
"MXN": 0,
"JPY": 0,
"GBP": 0,
"AUD": 0,
"NZD": 0,
"ZAR": 0
}
},
"after": {
"btcPaid": "0.065768",
"btcDue": "0.000000",
"price": 10,
"currency": "EUR"
},
"numericId": "789949",
"merchantName": "Test Account",
"checks": [
"ValidBitcoinAddress",
"InvoiceSufficientBalance",
"6Confirmations",
"NotBitPayAddress",
"LedgerSufficientBalance"
]
}
},
"token": "2vM2Jiw9Ed4YmGx66BBXjUebSfGDUieZuPGyWjpnV7oXYJJGg2nhyEFFZAsGP6s8bT"
}
}
Body
Name Type
facade
string
Facade used to view the refund object created on a given invoice, set
to "merchant/supportRequest"
data
Refund objects with status "pending" or "success" created for the

array
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.
Cancel a
specific
refund
request
DELETE
https://bitpay.com/invoices/<invoiceid>/refunds/<requestid>
Facades
MERCHANT
HTTP
Request
curl -X DELETE -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-

signature:
3045022100e3507d4b8665923e04699752a209395eb0dc8d597350e1072043a30f42a00eb902203c188af4637
a153f58eb876adb92fc8b1686ce82140407c01e2d8b1d51076230"
"https://test.bitpay.com/invoices/Pspr4saiFdhDyZxw8gy1SX/refunds/3qq5JP7i9eCLyAAHYAZ4cm?
token=sfxVmZyCzRSoNcCktL3t6D1EKREEud2fsLohrKuiZ9TqHFYEhuUzNF3GxNytxBMon"
URL
Parameter
s
<invoiceId>
strin
The id of the invoice for which you want to cancel a pending g M
refund request.
<requestId>
strin
g M
The id of the refund request you want to cancel
?token=
The resource token for the refund request <requestId> you want strin
g M
to cancel. You need to retrieve this token from the refund object
itself (see section Fetch the status of all refund requests).
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
M
x-signature
HTTP
Response
For a refund request fetched via the merchant facade (signed requests)
{
"data": "Success"
}
Body
Name Type
data string
set to "Success" once a refund request is successfully
cancelled
Request a
webhook
to be
resent
POST
https://bitpay.com/invoices/<invoiceid>/notifications
Facades
MERCHANT
HTTP
Request

signature:
3045022100e4dd8045a85f5a49f6d0736fa4b05ce177bb29e1acbdde232b30491570cacedd02200d13d1517e0
f9d64d61718fbfb21356909ca0525c7cbcc0da521c7192f22d305" -d
'{"token":"9A7EeRJpWnh3qpAJiRVSiUHxDrxn8RiPQb2rNgtL779tXrwBGTXRE722Ny7WMG1cKF"}'
"https://test.bitpay.com/invoices/KJr9fCnoiYuzCccGvV68rF/notifications"
URL
Parameter
s
<invoiceId>
strin
The id of the invoice for which you want the last webhook to be g M
resent.
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
M
x-signature
Body
fields Presence
?token=
The resource token for the <invoiceId> you want the webhook to be resent. M
You need to retrieve this token from the invoice object itself, using the
HTTP
Response
Example response when the webhook is successfully resent
{
"data": "Success"
}
Body
Name Type
data
string
set to "Success" once the webhook has been resent for the current invoice
status
Settlem
ents
Settlements
are
transfers of
payment
profits from
BitPay to
bank
accounts
and
cryptocurre
ncy 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
string
Facade used to view settlement objects, set to "merchant/settlement".
data
object
Settlement data object
id
string
String identifying the settlement; this id will also be in the description of the
corresponding bank settlement.
accountId
string
String identifying the BitPay merchant. For internal use, this field can be
ignored in merchant implementations.
status
string
Status of the settlement. Possible statuses are "new", "processing", "rejected"
and "completed".
currency string
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
payoutInfo
string
Object containing the settlement info provided by the Merchant in his BitPay
account settings
label
string
As indicated by the merchant in his settlement settings
bankCountry
string
Country where the merchant's bank account is located
name
string
account holder name
bank
string
Name of the bank used by the merchant
swift
string
SWIFT/BIC code of the merchant's bank.
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
string
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
city
string
City of the merchant bank, field return if the settlement currency is
postal
string
Postal code of the merchant bank, field return if the settlement currency is
account
string
Bank account number of the merchant
sort
string
used to pass country specific bank fields: BSB for AUD
wire
If set to true, this means BitPay will be settling the account using an boolean
international transfer via the SWIFT network instead of local settlement
methods like ACH(United States) or SEPA (European Economic Area)
bankName string
Name of the bank used by the merchant. Field returned if "wire": true in
the "payoutInfo" object
bankAddress
string
Address of the merchant's bank. Field returned if "wire": true in
bankAddress2
string
iban
The merchant's bank account number, in the IBAN (International Bank string
Account Number) format. Field returned if "wire": true in
additionalInformation
When providing the settlement info via the dashboard, this field can be used string
by the merchant to provide additional information about the receiving bank.
Field returned if "wire": true in the "payoutInfo" object
accountHolderName
string
Bank account holder name. Field returned if "wire": true in
accountHolderAddress
string
Bank account holder address. Field returned if "wire": true in
accountHolderAddress2
string
accountHolderPostalCode
string
Bank account holder postal code. Field returned if "wire": true in
accountHolderCity
string
Bank account holder city. Field returned if "wire": true in
accountHolderCountry
string
Bank account holder country. Field returned if "wire": true in
dateCreated
string
timestamp when the settlement was created. UTC date, ISO-8601
format yyyy-mm-ddThh:mm:ssZ
dateExecuted number
timestamp when the settlement was executed. UTC date, ISO-8601
openingDate
corresponds to the closingDate of the previous settlement executed. For the number

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
closingDate
date
Date & time for last ledger entry used for the settlement. UTC date, ISO-8601
openingBalance
string
Balance of the ledger at the openingDate
ledgerEntriesSum
number
Sum of all ledger entries in the settlement, this means all the debits & credits
which happened betwee openingDate and closingDate
withholdings array
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.
withholdingsSum
Sum of all amounts that are withheld from settlement number
totalAmount
total amount sent to the merchant; 2 decimals. number
totalAmount = openingBalance + legderEntriesSum - withholdingsSum
token string
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
Fetch
settlement
s based on
a date
range
GET
https://bitpay.com/settlements
Facades
MERCHANT
HTTP
Request
Fetching settlement objects via the merchant facade (signed requests)

identity: 031b3be2507c3b457da835c0077fa38426129d63ce801dff136a4299b166b24572" -H "x-
signature:
3045022074186fd53d0d06d2cc23beb07f7df5e9780df91d5029246b77c87368d73320ba022100e35da1cfde9
c03465e4ec4770bbc2c11d03e11f221dcbe54288530ed7be3b2b2"
"https://test.bitpay.com/settlements?
token=GcAUe7hgY3F2FSh95Dsy5d&status=processing&startDate=2018-8-22&endDate=2019-8-30"
URL
Parameter
s
?token=
strin
When fetching settlememts, pass a merchant facade token as a g M
URL parameter .
&startDate
strin
The start of the date window to query for settlements. g O
Format YYYY-MM-DD
&endDate=
strin
The end of the date window to query for settlements. g O
Format YYYY-MM-DD
&status=
strin
g O
The settlement status you want to query on
&currency=
strin
g O
The settlement currency you want to query on
&limit=
numbe
Maximum results that the query will return (useful for paging r O
results)
&offset=
numbe
Number of results to offset (ex. skip 10 will give you results r O
starting with the 11th result)
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
M
x-signature
HTTP
Response
Example response when fetching settlement objects for a given date range
{
"data": [
{
"id": "DNFnN3fFjjzLn6if5bdGJC",
"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",
"ledgerEntriesSum": -8372.07,
"withholdings": [],
"withholdingsSum": 0,
"token": "5T1T5yGDEtFDYe8jEVBSYLGmzjACKGtmfPg3UgbFE9z3XHtBstnF5u2EniUFa63W9K"
},
{
"currency": "USD",
"payoutInfo": {
"label": "Test",
"bankName": "Test",
"iban": "NL85ABNA0000000000",
"accountHolderCountry": "United States",
"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",
"withholdings": [
{
"amount": 590.08,
"code": "W005",
}
],
}
]
}
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 r
esource sec
tion.
Fetch a
specific
settlement
GET
https://bitpay.com/settlements/<settlementid>
Facades
MERCHANT
HTTP
Request
Fetching a settlement object via the merchant facade (signed requests)

signature:
3046022100a9d1ec54237bf0733b6c0903bed401173313792c6a6e1f4abe7629d754b69114022100951954060
a8e02fcfe2ef9ee4e43b0b159b146152aff5dad8e9262aca824f964"
"https://test.bitpay.com/settlements/DNFnN3fFjjzLn6if5bdGJC?token=GcAUe7hgY3F2FSh95Dsy5d"
URL
Parameter
s
<settlementId>
strin
g M
id of the specific settlement resource to be fetched
?token=
strin
when fetching settlememts, pass a merchant facade token as a g M
URL parameter .
Headers
fields Presence
x-accept-version:
M
content-type M
x-identity
M
x-signature
HTTP
Response
Example of settlement object
{
"data": {
"currency": "USD",
"payoutInfo": {
"label": "Test",
"bankName": "Test",
"iban": "NL85ABNA0000000000",
"accountHolderCountry": "Netherlands",
"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",
"withholdings": [
{
"amount": 590.08,
"code": "W005",
}
],
}
}
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 r
esource sec
tion.
Fetch a
reconciliati
on 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

signature:
3045022100ef23db87d03ceedaac437d98a57f78788c06535b0462b0a396c2bbdd35b8fa840220418a3e84769
e1b714c3b47ccda85d0ac4d1be2531471d00e662cd070588f81ec"
"https://test.bitpay.com/settlements/RvNuCTMAkURKimwgvSVEMP/reconciliationReport?
token=5T1T5yGDEtFDYe8jEVBSYLHKewPYXZrDLvZxtXBzn69fBbZYitYQYH4BFYFvvaVU7D"
URL
Parameter
s
<settlementId>
strin
g M
id of the specific settlement resource to be fetched
?token=
when fetching the reconciliation report for a specific settlement, strin

use the API token linked to the corresponding settlement g M
resource. This token can be retrieved via the endpoint GET
https://bitpay.com/settlements/<settlementId> .
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
M
x-signature
HTTP
Response
example of reconciliation report
{
"data": {
"currency": "USD",
"payoutInfo": {
"label": "Test",
"bankName": "Test",
"iban": "NL85ABNA0000000000",
"accountHolderCountry": "United States",
"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",
"withholdings": [
{
"amount": 590.08,
"code": "W005",
}
],
"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,
"timestamp": "2018-08-01T20:20:25.258Z",
"amount": 5.84,
"invoiceId": "PbPTukHvymCZYA8FGDa5wh",
"invoiceData": {
"date": "2018-08-01T19:37:52.790Z",
"price": 5,
"currency": "EUR",
"USD": 100
}
}
},
{
"code": 1023,
"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",
"USD": 100
}
}
},
{
"code": 1023,
"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",
"USD": 100
}
}
},
{
"code": 1023,
"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",
"USD": 100
}
}
},
{
"code": 1023,
"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",
"USD": 100
}
}
},
{
"code": 1023,
"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",
"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,
"timestamp": "2018-08-07T10:06:35.804Z",
"amount": 5.8,
"invoiceId": "LWgqvm3CH47psfgy83DvLX",
"invoiceData": {
"date": "2018-08-07T09:14:09.106Z",
"price": 5,
"currency": "EUR",
"USD": 100
}
}
},
{
"code": 1023,
"timestamp": "2018-08-07T10:06:35.804Z",
"amount": -0.06,
"invoiceId": "LWgqvm3CH47psfgy83DvLX"
},
{
"code": 1000,
"timestamp": "2018-08-08T12:52:29.384Z",
"amount": 3.43,
"invoiceId": "932QfiTCd4ALwaLfqxH5ae",
"invoiceData": {
"date": "2018-08-08T12:40:00.622Z",
"price": 2.96,
"currency": "EUR",
"USD": 100
}
}
},
{
"code": 1023,
"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,
"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",
"USD": 100
}
}
},
{
"code": 1023,
"timestamp": "2018-08-14T11:13:38.374Z",
"amount": -5.82,
"invoiceId": "WxY7d2qUzJawZTTqpXUHov"
},
{
"code": 1000,
"timestamp": "2018-08-14T11:22:12.577Z",
"amount": 3000,
"invoiceId": "76ZQGxLuKwKJ5vBMvjdAbh",
"invoiceData": {
"date": "2018-08-14T10:37:06.348Z",
"price": 3000,
"currency": "USD",
"USD": 100
}
}
},
{
"code": 1023,
"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,
"timestamp": "2018-08-14T11:45:08.017Z",
"amount": -45.02
},
{
"code": 1011,
"timestamp": "2018-08-14T11:45:08.073Z",
"amount": 1000.35
},
{
"code": 1000,
"timestamp": "2018-08-14T13:10:18.890Z",
"amount": 3000,
"invoiceId": "RSPnAH9L5yDWUFNYTGDJmi",
"invoiceData": {
"date": "2018-08-14T11:58:30.028Z",
"price": 3000,
"currency": "USD",
"USD": 100
}
}
},
{
"code": 1023,
"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",
"USD": 100
}
}
},
{
"code": 1023,
"timestamp": "2018-08-16T13:32:23.205Z",
"amount": -0.1,
"invoiceId": "WwCouQindnn6TYW9PvRMSU"
}
]
}
}
Body
Name Type
facade
string
Facade used to view settlement objects, set to "merchant/settlement".
data
object
Settlement data object
id
string
String identifying the settlement; this id will also be in the description of the
corresponding bank settlement.
accountId
string
String identifying the BitPay merchant. For internal use, this field can be
ignored in merchant implementations.
status
string
Status of the settlement. Possible statuses are "new", "processing", "rejected"
and "completed".
currency
ISO 4217 3-character currency code. This is the currency associated with the string
settlement. Supported settlement currencies are listed on
https://bitpay.com/docs/settlement
payoutInfo
string
Object containing the settlement info provided by the Merchant in his BitPay
account settings
label
string
As indicated by the merchant in his settlement settings
bankCountry
string
Country where the merchant's bank account is located
name
string
account holder name
bank
string
Name of the bank used by the merchant
swift
string
SWIFT/BIC code of the merchant's bank.
address string
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
city
string
City of the merchant bank, field return if the settlement currency is
postal
string
Postal code of the merchant bank, field return if the settlement currency is
account
string
Bank account number of the merchant
sort
string
used to pass country specific bank fields: BSB for AUD
wire
If set to true, this means BitPay will be settling the account using an boolean
international transfer via the SWIFT network instead of local settlement
methods like ACH(United States) or SEPA (European Economic Area)
bankName
string
Name of the bank used by the merchant. Field returned if "wire": true in
bankAddress string
bankAddress2
string
iban
The merchant's bank account number, in the IBAN (International Bank string
Account Number) format. Field returned if "wire": true in
additionalInformation
When providing the settlement info via the dashboard, this field can be used string
by the merchant to provide additional information about the receiving bank.
Field returned if "wire": true in the "payoutInfo" object
accountHolderName
string
Bank account holder name. Field returned if "wire": true in
accountHolderAddress
string
accountHolderAddress2
string
accountHolderPostalCode
string
Bank account holder postal code. Field returned if "wire": true in
accountHolderCity
string
Bank account holder city. Field returned if "wire": true in
accountHolderCountry
string
Bank account holder country. Field returned if "wire": true in
dateCreated
string
timestamp when the settlement was created. UTC date, ISO-8601
dateExecuted
number
timestamp when the settlement was executed. UTC date, ISO-8601
openingDate number
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
closingDate
date
Date & time for last ledger entry used for the settlement. UTC date, ISO-8601
openingBalance
string
Balance of the ledger at the openingDate
ledgerEntriesSum
number
Sum of all ledger entries in the settlement, this means all the debits & credits
which happened betwee openingDate and closingDate
withholdings array
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.
withholdingsSum
Sum of all amounts that are withheld from settlement number
totalAmount
total amount sent to the merchant; 2 decimals. number
totalAmount = openingBalance + legderEntriesSum - withholdingsSum
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 string
required to fetch the reconciliation report
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 array
field ledgerEntriesSum. A description of all ledger codes can be found
Name Type Ledger Codes
1 1 1 1 1 1
0 0 0 0 0 0
0 1 2 2 3 3
0 1 0 3 0 9
code
Contai
ns the string ✓ ✓ ✓ ✓ ✓ ✓
Ledge
r entry
code
timest
amp
Date
and
time
of the
ledger
entry string ✓ ✓ ✓ ✓ ✓ ✓
(UTC).
ISO-
8601
forma
t yyyy
-mm-
ddThh:
mm:ssZ
amount string ✓ ✓ ✓ ✓ ✓ ✓
Amou
nt for
the
ledger
entry.
Can
be
positiv
e of
negati
ve
depen
ding
on the
type
of
entry
(debit
or
credit)
descri string ✓ ✓ ✓ ✓ ✓
ption
Ledge
r entry
descri
ption.
This
field
often
contai
ns
an id
depen
ding
on the
type
of
entry
(for
instan
ce
payou
t
batch
id,
settle
ment
id,
invoic
e orde
rId et
c...)
invoic
eId
BitPay string ✓ ✓
invoic
e Id
invoic
eData
Object
contai
ning
releva
nt number ✓ ✓
inform
ation
from
the
paid
invoic
e
order string ✓ ✓
Id
Invoic
e orde
rId pr
ovide
d
during
invoic
e
creati
on.
date
Date
at
which
the
invoic
e was
create string ✓ ✓
d
(UTC).
ISO-
8601
forma
t yyyy
-mm-
ddThh:
mm:ssZ
price
Invoic
e
price
in the amount ✓ ✓
invoic
e
origin
al curr
ency
curre
ncy
Invoic string ✓ ✓
e
curren
cy
trans
action
Curren
cy
Crypt
ocurre
ncy
select
ed by string ✓ ✓
the
consu
mer
when
payin
g the
invoic
e.
payou string ✓ ✓
tPerce
ntage
The
payou
t
perce
ntage
define
d by
the
merch
ant on
his Bit
Pay
accou
nt
settin
gs
refun
dInfo
Object
contai
ning
inform
ation
about
string ✓
the
refund
execut
ed for
the
invoic
e
suppo
rtRequ
est
string ✓
The
refund
reques
tId
curre string ✓
ncy
Refere
nce
curren
cy
used
for
the
refund
,
usuall
y the
same
as the
curren
cy
used
to
create
the
invoic
e
amoun string ✓
ts
For a
refund
ed
invoic
e, this
object
will
contai
n the
crypto
curren
cy
amou
nt
refund
ed by
BitPay
to the
consu
mer
(in the
select
ed tra
nsacti
onCurr
ency)
and
the
equiva
lent
refund
ed
amou
nt
from
the
invoic
e in
the
given
curren
cy (th
us
linked
to the
amou
nt
debite
d
from
the
merch
ant
accou
nt to
cover
the
refund
)
Ledgers
Ledgers are
records of
money
movement.
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)

signature:
304402205f299b2699ffb3a09055251ef85c0044dea2cfbcd6f6492793aa18f906bcf48502202be49cecd5a5a
bc9d4edded7e0569845d0395ccb9b459f1697691eefcdaccadd" "https://test.bitpay.com/ledgers?
token=GcAUe7hgY3F2FSh95Dsy5d"
URL
Parameter
s
?token=
strin
when fetching ledger entries, pass a merchant facade token as a g M
URL parameter.
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
M
x-signature
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
Array of objects indicating the balance for each currency
currency
string
Ledger currency
balance
number
Ledger balance in the corresponding currency
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)

signature:
304402204e7f82044475d08a4e87df0ddd809e58852bc1b252e3a5d336c9f7ce508c5e16022019e5a8e1e1f03
f06d6f56d30238dcb6cecb9eaa01fa6d4671f1cd31ef882687d"
"https://test.bitpay.com/ledgers/USD?
token=6oE1tYw1xMqUjM97dk57cwbda5sxbXTkUgg7UKpwkzEE&startDate=2020-1-24&endDate=2020-1-28"
URL
Parameter
s
<currency>
strin
g M
ISO 4217 3-character currency code for your merchant account
?token=
strin
When fetching ledger entries, pass a merchant facade token as a g M
URL parameter
&startDate=
strin
g M
The start date for fetching ledger entries. Format YYYY-MM-DD
&endDate=
strin
g M
The end date for fetching ledger entries. Format YYYY-MM-DD
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
M
x-signature
HTTP
Response
Example of ledger entries
[
{
"type": "Invoice",
"amount": 1102000000,
"code": 1000,
"description": "MerchantOrder456",
"timestamp": "2020-01-27T11:19:52.387Z",
"txType": "sale",
"scale": 100000000,
"invoiceId": "Fcf2vgGCis8XVCfr8gkQE6",
"buyerFields": {
"buyerName": "Fox Mulder",
"buyerAddress1": "2630 Hegal Place",
"buyerAddress2": "Apt 42",
"buyerCity": "Alexandria",
"buyerState": "VA",
"buyerZip": "23242",
"buyerCountry": "US",
"buyerPhone": "555-123-456",
"buyerNotify": true
},
"invoiceAmount": 10,
"invoiceCurrency": "EUR",
"id": "W8VF6qTLJnbyjQX4sPhxKj"
},
{
"type": "Invoice Fee",
"amount": -11000000,
"code": 1023,
"timestamp": "2020-01-27T11:19:52.387Z",
"txType": "Invoice Fee",
"scale": 100000000,
"invoiceId": "Fcf2vgGCis8XVCfr8gkQE6",
"buyerFields": {
"buyerState": "VA",
"buyerPhone": "555-123-456",
"buyerNotify": true
},
"id": "Vc1NLNYDjdy4DiYeyxWgVf"
},
{
"type": "Invoice",
"amount": 1102000000,
"code": 1000,
"timestamp": "2020-01-27T11:24:24.649Z",
"txType": "sale",
"scale": 100000000,
"invoiceId": "e6XJ7a5CKophekJwKyJ1M",
"buyerFields": {
"buyerState": "VA",
"buyerPhone": "555-123-456",
"buyerNotify": true
},
"id": "D5gzQN9hXg24irV9zt8y6r"
},
{
"amount": -11000000,
"code": 1023,
"timestamp": "2020-01-27T11:24:24.649Z",
"scale": 100000000,
"invoiceId": "e6XJ7a5CKophekJwKyJ1M",
"buyerFields": {
"buyerState": "VA",
"buyerPhone": "555-123-456",
"buyerNotify": true
},
"id": "Kd6GejLSvSkD26QHptzUkJ"
},
{
"type": "Invoice",
"amount": 1102000000,
"code": 1000,
"timestamp": "2020-01-27T11:52:40.609Z",
"txType": "sale",
"scale": 100000000,
"invoiceId": "5oACoLiz3NLK5WwiNRWFtK",
"buyerFields": {
"buyerState": "VA",
"buyerPhone": "555-123-456",
"buyerNotify": true
},
"id": "15CFyQCgSdgttbVbmK7kiz"
},
{
"amount": -11000000,
"code": 1023,
"timestamp": "2020-01-27T11:52:40.609Z",
"scale": 100000000,
"buyerFields": {
"buyerState": "VA",
"buyerPhone": "555-123-456",
"buyerNotify": true
},
"id": "TVqJoUoKBPMGFb3xmdh8rb"
},
{
"type": "Invoice Refund",
"supportRequest": "SgNXo9DJbVTsisua7x5qzc",
"amount": -551000000,
"code": 1020,
"description": "Invoice Refund",
"timestamp": "2020-01-27T12:18:57.299Z",
"txType": "Invoice Refund",
"scale": 100000000,
"buyerFields": {
"buyerState": "VA",
"buyerPhone": "555-123-456",
"buyerNotify": true
},
"id": "MP1tFUnVvmxHZxywvLAnjd"
}
]
Body
Some
ledger
entries have
additional
specific
fields. The
table
indicates
which fields
are
returned for
the main
ledger
entries.
Name Type Ledger Codes
1 1 1 1 1 1 1 1 1 1 1
0 0 0 0 0 0 0 0 0 0 0
0 0 1 1 2 2 2 3 3 3 4
0 6 1 7 0 2 3 0 4 9 0
type
Contai
ns the
Ledge
r entry
name. string ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
See
the list
of Led
ger
Entry
Codes.
amount number ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Ledge
r entry
amou
nt,
relativ
e to
the
scale.
The
decim
al
amou
nt can
be
obtain
ed by
dividin
g
the am
ount fi
eld by
the sc
ale pa
ramet
er.
code
Contai
ns the
Ledge
r entry
code. number ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
See
the list
of Led
ger
Entry
Codes.
timest string ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
amp
Date
and
time
of the
ledger
entry
(UTC).
ISO-
8601
format
yyyy-
mm-
ddThh:
mm:ssZ
curren
cy
Ledge
r entry
curren
cy for
string ✓ ✓ ✓ ✓ ✓ ✓ ✓
the
corres
pondi
ng amo
unt
txType
[DEPR
ECRAT string ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
ED]
see ty
pe
scale
Power
of 10
used
string ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
for
conver
sion
id string ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Ledge
r
resour
ce Id
suppor
tReque
st
The
string ✓
refund
reques
tId
descri string ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
ption
Ledge
r entry
descri
ption.
Also
contai
ns
an id
depen
ding
on the
type
of
entry
(for
instan
ce
payou
t
batch
id,
settle
ment i
d,
invoic
e orde
rId etc
...)
invoic
eId
BitPay string ✓ ✓ ✓ ✓
invoic
e Id
buyerF
ields
If
provid
ed by
the
merch
ant in string ✓ ✓ ✓ ✓
the bu
yer ob
ject
during
invoic
e
creatio
n
buyer string ✓ ✓ ✓ ✓
Name
If
provid
ed by
the
merch
ant in
the bu
yer ob
ject
during
invoic
e
creatio
n
buyer
Addres
s1
If
provid
ed by
the
merch
the bu
yer ob
ject
during
invoic
e
creatio
n
Addres
s2
If
provid
ed by
the
merch
ant in
the bu
yer ob
ject
during
invoic
e
creatio
n
buyer
City
If
provid
ed by
the
merch
the bu
yer ob
ject
during
invoic
e
creatio
n
buyer
State
If
provid
ed by
the
merch
the bu
yer ob
ject
during
invoic
e
creatio
n
buyer
Zip
If
provid
ed by
the
merch
the bu
yer ob
ject
during
invoic
e
creatio
n
buyer
Countr
y
If
provid
ed by
the
merch
the bu
yer ob
ject
during
invoic
e
creatio
n
Phone
If
provid
ed by
the
merch
ant in
the bu
yer ob
ject
during
invoic
e
creatio
n
buyer
Notify
If
provid
ed by
the
merch
the bu
yer ob
ject
during
invoic
e
creatio
n
Email
If
provid
ed by
the
merch
ant in
the bu
yer ob
ject
during
invoic
e
creatio
n
invoic
eAmoun
t
Invoic
e price
in the string ✓ ✓ ✓ ✓
invoic
e
origin
al
curren
cy
invoic
eCurre
ncy
Curren
cy
used string ✓ ✓ ✓ ✓
for
invoic
e
creatio
n
transa string ✓ ✓ ✓ ✓
ctionC
urrenc
y
Crypto
curren
cy
selecte
d by
the
consu
mer
when
paying
an
invoic
e.
Payouts
Payouts are
batches of
bitcoin
payments
to
employees,
customers,
partners,
etc.
Resource
Example of payout batch after begin executed.
{
"facade": "payroll/payoutRequest",
"data": {
"id": "85Krn4jvdtTJtGc6T4gcaK",
"account": "YJCgTf3jrXHkUVzLQ7y4eg",
"reference": "test",
"supportPhone": "1-855-4-BITPAY",
"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",
"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",
"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 request. When
string
the payroll facade is used to create a payout request, the BitPay server returns
the payout object as seen from the payroll facade, that
is "payroll/payoutRequest"
data
object
payout data object
id
string
Resource id
account
string
String identifying the BitPay merchant, for internal use
reference string
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
supportPhone
string
Phone number for BitPay. For immediate support visit support@bitpay.com
status
Payout batch status, the possible values are:
 "new" - initial status when the batch is created
 "funded" - if there are enough funds available on the merchant
account, the batches are set to funded. This happens at the daily
cutoff time for payout processing, e.g. 2pm and 9pm UTC string
 "complete" - when the payout batches has been executed and the
bitcoin sent to each recipient included in the batch
 "cancelled" - when the merchant cancels a batch (only possible for
batches in the status "new" or "funded")
amount
The total amount of the batch in fiat currency. This amount must equal the sum number
of the instruction's amounts
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 number
payout is executed (including the fee)
btc
The total amount of btc that was sent for the batch once the batch is number
processed
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, string
AUD, ZAR
requestDate
Date and time (UTC) when BitPay received the batch. ISO-8601 format yyyy-mm- string
ddThh:mm:ssZ.
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 string
09:00:00.000 UTC time if only the day is specified (yyyy-mm-dd)
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 instruction objects array
id
Resource id for the instruction string
amount
amount to be sent to the customer bitcoin address. The minimum amount per string
instruction is $1 USD equivalent
btc
Initially empty, it will contain the amount of bitcoin sent to the consumer once object
the payout batch status is set to complete
unpaid
Initially set to null, will be set to 0 once the payout batch status is set number
to complete
paid
Initially set to 0, will contain the amount of BTC paid to the consumer once the number
payout batch status is set to complete
address
Bitcoin address provided by the consumer string
label
For merchant use, pass through - can be a unique reference ID assigned to a string
given consumer
transactions
Contains the bitcoin transaction details for the executed payout instruction array
txid
Bitcoin transaction hash for the executed payout. string
amount
amount of BTC sent to the requested address. number
date
Date and time (UTC) when the bitcoin transaction is broadcasted. ISO-8601 string
format yyyy-mm-ddThh:mm:ssZ.
status
set to "unpaid" when you create the payout request. Will be set to "paid" once string
the payout batch is processed by BitPay (main batch status set to "complete"
token
API token for the corresponding payouts resource. This token is actually
derived from the API token used to submit the payout request and is tied to string
the specific resource id created.
Create a
payout
batch
POST
https://bitpay.com/payouts
Facades
PAYROLL
HTTP
Request
via the payroll facade (signed requests)

signature:
304402202a99c97c3b08dfc268ccc51a7c9ed1efd6561966f1b2e01e300ebcf2da2db59e02207ff15c4ccbce3
e1ba89ab1ee626a391ec6ac605f46b1ac45ec4949a1bdaf1363" -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,"wall
etProvider":"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}],"toke
n":"Gj9kD64NcorFoYwsdZXVfwpfWQ543Bq2ZoC2PKbrCfMS"}' "https://test.bitpay.com/payouts"
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
M
x-signature M
Body
Name Type Presence
amount
numbe
The total amount of the batch in fiat currency. This amount must r M
equal the sum of the instruction's amounts
currency
Currency code set for the batch amount (ISO 4217 3-character strin
g M
currency code). Supported currency codes for payout batches are
EUR, USD, GBP, CAD, NZD, AUD, ZAR
reference
For the merchant to pass their own reference label for this batch. strin
g O
It will be passed-through on each response for you to identify the
batch in your system. Maximum string length is 100 characters
effectiveDate
Effective date and time (UTC) for the batch. ISO-8601 format yyyy- strin
mm-ddThh:mm:ssZ - Note that the time of day will automatically be g M
set to 09:00:00.000 UTC time if only the day is specified ( yyyy-mm-
dd)
notificationEmail
strin
g O
Merchant email address for notification of payout status change.
notificationURL
strin
URL to which BitPay sends webhook notifications. HTTPS is g O
mandatory.
instructions
array M
This is an array containing the detailed payout instruction objects
address
strin
g M
Bitcoin address provided by the customer
amount
strin
g M
amount to be sent to the customer bitcoin address. The minimum
amount per instruction is $1 USD equivalent
label
strin
g O
For merchant use, pass through - could be customer name or
unique reference ID
walletProvider
Name of the bitcoin wallet provider used by the customer to

strin
receive the funds. This field is only required if the consumer is g C
using one of the listed wallet providers to receive the funds and if
the corresponding instruction amount is superior or equal to
$3000 USD
receiverInfo strin C
g
JSON object containing the below nested fields. To be provided if
the walletProvider is provided
name
strin
g C
Customer’s name as indicated on the proof of ID collected.
email
strin
g C
Customer’s email address.
address
objec
t C
object containing the detailed address of the payout recipient.
streetAddress1
strin
g C
Must match the customer’s street / house number on the proof of
address document collected.
streetAddress2
strin
g C
For merchant use, pass through - could be customer name or
unique reference ID.
locality
strin
g C
Must match the City/Town on the proof of address document
collected.
region
strin
g C
If applicable in the country selected, equivalent to state or
province.
postalCode
strin
g C
Must match the postal code on the proof of address document
collected.
country
strin
Must match on the proof of address document collected. See g C
Appendix 2 for the list of countries supported (English short
names).
token
strin
API token retrieved via endpoint POST g M
https://bitpay.com/tokens (payroll facade)
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
HTTP
Response
Example of payout batch
{
"data": {
"id": "RekNSp4pMU4B2mBEjFqiPF",
"reference": "test_batch_XYZ",
"status": "new",
"amount": 42,
"percentFee": 1,
"fee": 0.42,
"btc": null,
"currency": "USD",
"requestDate": "2019-05-30T12:02:22.880Z",
"notificationURL": "https://yournotificationurl.com",
"instructions": [
{
"id": "BSWJg8pacu4iCk5cArZu7t",
"amount": 25.84,
"btc": {
"unpaid": null,
"paid": 0
},
"transactions": [],
"status": "unpaid"
},
{
"id": "H8jVYReN2CK7bg5Kq6tByE",
"amount": 10.54,
"btc": {
"unpaid": null,
"paid": 0
},
"transactions": [],
"status": "unpaid"
},
{
"id": "F6JnxZSTZBNeu12HNE6X6v",
"amount": 5.62,
"btc": {
"unpaid": null,
"paid": 0
},
"transactions": [],
"status": "unpaid"
}
],
"token": "7tGdAPbGiQZnaB88VGNhxX4KS2edirqdu9wigvTGFqQqfJaKDtzQHbZpNUXjJMNcTP"
}
}
On the
right side,
you will find
an example
payout
object
returned in
the
response
you will get
from the
BitPay
server. A
description
of all
payout
fields is
available in
the resourc
e section.
Fetch
payout
batches
based on
status
GET
https://bitpay.com/payouts
Facades
PAYROLL
HTTP
Request

signature:
304502207c25fe37b8b3ea4c4b398e51ed92711ef9f85ce85c55dbcb3c36ca40d431b43602210089ca06723cc
f54e259bbda54c965d93e94141a65c8b5475ec1bd3488fc8e3cb7" "https://test.bitpay.com/payouts?
token=Gj9kD64NcorFoYwsdZXVfwpfWQ543Bq2ZoC2PKbrCfMS&status=new"
URL
Parameter
s
?token=
strin
https://bitpay.com/tokens (payroll facade).
&status=
strin
g M
the payout status you want to query on
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
M
x-signature
HTTP
Response
Example of payout batches
{
"data": [
{
"id": "RekNSp4pMU4B2mBEjFqiPF",
"reference": "test_batch_XYZ",
"status": "new",
"amount": 42,
"percentFee": 1,
"fee": 0.42,
"btc": null,
"currency": "USD",
"requestDate": "2019-05-30T12:02:22.880Z",
"instructions": [
{
"id": "BSWJg8pacu4iCk5cArZu7t",
"amount": 25.84,
"btc": {
"unpaid": null,
"paid": 0
},
"transactions": [],
"status": "unpaid"
},
{
"id": "H8jVYReN2CK7bg5Kq6tByE",
"amount": 10.54,
"btc": {
"unpaid": null,
"paid": 0
},
"transactions": [],
"status": "unpaid"
},
{
"id": "F6JnxZSTZBNeu12HNE6X6v",
"amount": 5.62,
"btc": {
"unpaid": null,
"paid": 0
},
"transactions": [],
"status": "unpaid"
}
],
"token": "7tGdAPbGiQZnaB88VGNhxX4KS2edirqdu9wigvTGFqQqfJaKDtzQHbZpNUXjJMNcTP"
},
{
"id": "FskHro8BsHngfao4e9UtV1",
"reference": "test_batch_ABC",
"status": "new",
"amount": 42,
"percentFee": 1,
"fee": 0.42,
"btc": null,
"currency": "USD",
"requestDate": "2019-05-30T14:03:50.711Z",
"instructions": [
{
"id": "KVu2nCSa7FUcY1tmJX9ubQ",
"amount": 25.84,
"btc": {
"unpaid": null,
"paid": 0
},
"transactions": [],
"status": "unpaid"
},
{
"id": "9GvgE9L1n5wR9xGsimvfFb",
"amount": 10.54,
"btc": {
"unpaid": null,
"paid": 0
},
"transactions": [],
"status": "unpaid"
},
{
"id": "DbVANPHf6XKw12tyzXdMgk",
"amount": 5.62,
"btc": {
"unpaid": null,
"paid": 0
},
"transactions": [],
"status": "unpaid"
}
],
"token": "7tGdAPbGiQZnaB88VGNhxWxEnLRKiMUvty1fdtBaX5PNU65UL6NmbJfzbucixDidwP"
}
]
}
On the
right side,
you will find
an example
payout
objects
returned in
the
response
you will get
from the
BitPay
server. A
description
of all
payout
fields is
available in
the resourc
e section.
Fetch a
specific
payout
batch
GET
https://bitpay.com/payouts/<payoutid>
Facades
PAYROLL
HTTP
Request

signature:
3044022000f91c108c48a867bdd86bb2f3c3553d16342cbc9bf54d7987cfd5f4de1bce6f0220684e90ff57b2b
88079f976c65184ae5cf0fceacbcdd05d1e498d02f79dcc00b2"
"https://test.bitpay.com/payouts/85Krn4jvdtTJtGc6T4gcaK?
token=Gj9kD64NcorFoYwsdZXVfwpfWQ543Bq2ZoC2PKbrCfMS"
URL
Parameter
s
<payoutId>
strin
g M
the specific payout batch Id you want to fetch
?token=
strin
https://bitpay.com/tokens (payroll facade).
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
M
x-signature
HTTP
Response
Example of complete payout batch
{
"data": {
"amount": 5,
"percentFee": 1,
"fee": 0.05,
"rate": 5147.62,
"btc": 0.000972,
"currency": "USD",
"requestDate": "2019-04-29T15:16:40.706Z",
"notificationURL": "",
"instructions": [
{
"amount": 1,
"btc": {
"unpaid": 0,
"paid": 0.000194
},
"transactions": [
{
"amount": 0.000194,
"date": "2019-04-29T15:21:24.182Z"
}
],
"status": "paid"
},
{
"amount": 2,
"btc": {
"unpaid": 0,
"paid": 0.000389
},
"transactions": [
{
"amount": 0.000389,
"date": "2019-04-29T15:21:24.903Z"
}
],
"status": "paid"
},
{
"amount": 2,
"btc": {
"unpaid": 0,
"paid": 0.000389
},
"transactions": [
{
"amount": 0.000389,
"date": "2019-04-29T15:21:25.641Z"
}
],
"status": "paid"
}
],
"dateExecuted": "2019-04-29T15:21:24.177Z",
"token": "7tGdAPbGiQZnaB88VGNhxWwCceJ6XKuv5XPx8YLWvFHqQgKCoUQS5RK67AS4CLawsh"
}
}
On the
right side,
you will find
an example
payout
object
returned in
the
response
you will get
from the
BitPay
server. A
description
of all
payout
fields is
available in
the resourc
e section.
Cancel a
specific
payout
batch
DELETE
https://bitpay.com/payouts/<payoutid>
Facades
PAYROLL
HTTP
Request
curl -X DELETE -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-

signature:
304502203130ccb010f9058d7ef403e11636e5afcdcf94e378808751d3aa66e89995e34e022100ea4c5b436b3
d95ae8e1f106e172cdbf8ee04875e7166e5c56900c2bbd4074685"
"https://test.bitpay.com/payouts/FskHro8BsHngfao4e9UtV1?
token=7tGdAPbGiQZnaB88VGNhxWxEnLRKiMUvty1fdtBaX5PNU65UL6NmbJfzbucixDidwP"
URL
Parameter
s
<payoutId>
strin
g M
the payout status you want to cancel
?token=
API token for the <payoutId> you want to cancel. This token can strin
g M
be retrieve from the payout object via a GET
https://bitpay.com/payouts/<payoutId> .
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
M
x-signature
HTTP
Response
Example of cancelled payout batch
{
"data": {
"id": "FskHro8BsHngfao4e9UtV1",
"reference": "test_batch_ABC",
"status": "cancelled",
"amount": 42,
"percentFee": 1,
"fee": 0.42,
"btc": null,
"currency": "USD",
"requestDate": "2019-05-30T14:03:50.711Z",
"instructions": [
{
"id": "KVu2nCSa7FUcY1tmJX9ubQ",
"amount": 25.84,
"btc": {
"unpaid": null,
"paid": 0
},
"transactions": [],
"status": "unpaid"
},
{
"id": "9GvgE9L1n5wR9xGsimvfFb",
"amount": 10.54,
"btc": {
"unpaid": null,
"paid": 0
},
"transactions": [],
"status": "unpaid"
},
{
"id": "DbVANPHf6XKw12tyzXdMgk",
"amount": 5.62,
"btc": {
"unpaid": null,
"paid": 0
},
"transactions": [],
"status": "unpaid"
}
],
"token": "32zJbBoHWUUtzgwXr3hexwtuFhjw7h1MnZg9fimFs71AKxJg2CZmuiZHX4WswWh9Cj"
}
}
On the
right side,
you will find
an example
of cancelled
payout
object
returned in
the
response
you will get
from the
BitPay
server. A
description
of all
payout
fields is
available in
the resourc
e section.
Bills
Bills are
payment
requests
addressed
to specific
buyers. Bill
line items
have fixed
prices,
typically
denominate
d in fiat
currency.
Resource
Example of bill object via the pos facade
{
"facade": "pos/bill",
"data": {
"status": "draft",
"url": "https://test.bitpay.com/bill?id=Jq9riJvJtnWofT1rBjdwH2&resource=bills",
"number": "test-xyz",
"createdDate": "2019-08-26T18:24:48.723Z",
"dueDate": "2019-09-30T00:00:00.000Z",
"currency": "USD",
"cc": [
"melvin.frohike@thelonegunmen.com"
],
"passProcessingFee": true,
"id": "Jq9riJvJtnWofT1rBjdwH2",
"items": [
{
"id": "T7zruzLU1Fmie464Muc6hW",
"description": "test item 1",
"price": 10,
"quantity": 1
},
{
"id": "6Hmxi2fVWoAHCMRnLU3qYm",
"price": 20,
"quantity": 1
},
{
"id": "TN7CHfXVeCeHSEg7jhJEtT",
"price": 30,
"quantity": 1
}
],
"token": "3d3HCEvroJsdGrpne886iHvd5QzZSTZJ4qTqXrzqdz4ygtUe2wTXuntfSRRTGShD3X"
}
}
Example of bill object via the merchant facade
{
"facade": "merchant/bill",
"data": {
"status": "draft",
"url": "https://test.bitpay.com/bill?id=EnshCou5PvcGFaXSC5FF6R&resource=bills",
"createdDate": "2019-08-26T18:21:40.087Z",
"dueDate": "2019-09-30T00:00:00.000Z",
"currency": "USD",
"city": "Alexandria",
"state": "VA",
"zip": "23242",
"country": "US",
"cc": [
],
"phone": "555-123-456",
"emailBill": true,
"id": "EnshCou5PvcGFaXSC5FF6R",
"merchant": "YJCgTf3jrXHkUVzLQ7y4eg",
"items": [
{
"id": "7At4wBJkuW6eXrGMAobzEY",
"price": 10,
"quantity": 1
},
{
"id": "4dwXez3nWK1XGQYHCAEaHB",
"price": 20,
"quantity": 1
},
{
"id": "Hy7SEirqDzfrWmv2X68v7U",
"price": 30,
"quantity": 1
}
],
"token": "9nc1UKjDDrmkei5VsJqpNQ9fCSXxmq3gc12Vn3HkAVnQHmCktbVNRZAqETrWjYTPSK"
}
}
Bills are
payment
requests
addressed
to specific
buyers. Bill
line items
have fixed
prices,
typically
denominate
d in fiat
currency.
pos merchant
facade string ✓ ✓
This field indicates the facade from which the bill is

being requested:
 "pos/bill" if the pos facade is used to

 "merchant/bill" if the merchant facade is
used to request an invoice resource
data
bill data object object ✓ ✓
status
Can "draft", "sent", "new", "paid", or "complete" string ✓ ✓
url
Web address of bill string ✓ ✓
number
Bill identifier, specified by merchant string ✓ ✓
createdDate
Date and time of Bill creation, ISO-8601 format string ✓ ✓
yyyy-mm-ddThh:mm:ssZ. (UTC)
dueDate
Date and time at which a bill is due, ISO-8601 string ✓ ✓
format yyyy-mm-ddThh:mm:ssZ. (UTC)
currency
ISO 4217 3-character currency code. This is the string ✓ ✓
currency associated with the price field
name
Bill recipient's name string ✓
address1
Bill recipient's address string ✓
address2
Bill recipient's address string ✓
city
Bill recipient's city string ✓
state
Bill recipient's state or province string ✓
zip
Bill recipient's ZIP code string ✓
country
Bill recipient's country string ✓
email
Bill recipient's email address string ✓ ✓
cc
Email addresses to which a copy of the bill must be array ✓ ✓
sent
phone
Bill recipient's phone number string ✓
passProcessingFee
If set to true, BitPay's processing fee will be boolean ✓ ✓
included in the amount charged on the invoice
id
Bill resource id string ✓ ✓
merchant
Internal identifier for BitPay, this field can be string ✓
ignored by the merchants.
items
List of line items array ✓ ✓
id
item resource Id string ✓ ✓
description
Line item description string ✓ ✓
price
Line item unit price for the corresponding currency number ✓ ✓
quantity
Line item number of units number ✓ ✓
token
API token for bill resource. This token is actually
derived from the API token used to create the bill string ✓ ✓
and is tied to the specific resource id created.
Create a
bill
POST
https://bitpay.com/bills
Facades
POS MERCH
ANT
HTTP
Request

'{"number":"test-xyz","currency":"USD","name":"Fox Mulder","address1":"2630 Hegal
Place","address2":"Apt
42","city":"Alexandria","state":"VA","zip":23242,"country":"US","email":"fox.mulder@trust
no.one","cc":["melvin.frohike@thelonegunmen.com"],"phone":"555-123-456","dueDate":"2019-
9-30","passProcessingFee":true,"items":[{"description":"test item
1","price":10,"quantity":1},{"description":"test item 2","price":20,"quantity":1},
{"description":"test item 3","price":30,"quantity":1}],"token":"Tqi5NhskgZHW3ZUv6y1AZg"}'
"https://test.bitpay.com/bills"

signature:
3046022100c4d9a7d913dd7bc334bc0acf3587a86b91ce647f116de9190764689284d697ed022100b5afd75ff
35c5bbf3f00fa3c674c0d320d6081ce27ddef2818958470b93dd1c6" -d '{"number":"test-
xyz","currency":"USD","name":"Fox Mulder","address1":"2630 Hegal Place","address2":"Apt
{"description":"test item 3","price":30,"quantity":1}],"token":"GcAUe7hgY3F2FSh95Dsy5d"}'
"https://test.bitpay.com/bills"
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
x-signature
Body
Name Type Presence
number
string O
Bill identifier, specified by merchant
currency
ISO 4217 3-character currency code. This is the currency

string M
associated with the price field
name
string O
Bill recipient's name
address1
string O
Bill recipient's address
address2
string O
Bill recipient's address
city
string O
Bill recipient's city
state
string O
Bill recipient's state or province
zip
string O
Bill recipient's ZIP code
country
string O
Bill recipient's country
email
string M
Bill recipient's email address
cc
array O
Email addresses to which a copy of the bill must be sent
phone
string O
Bill recipient's phone number
dueDate
Date and time at which a bill is due, ISO-8601 format yyyy-mm-

string O
ddThh:mm:ssZ. (UTC)
passProcessingFee
If set to true, BitPay's processing fee will be included in the

boolean O
amount charged on the invoice
items
array M
List of line items
description
string M
Line item description
price number M
Line item unit price for the corresponding currency
quantity
number M
Line item number of units
token
The API token can be retrieved from the dashboard (limited

to pos facade) or using the Tokens resource to get access to
string M
the merchant facade. This is described in the section Request an
API token).
HTTP
Response
{
"data": {
"status": "draft",
"url": "https://test.bitpay.com/bill?id=Jq9riJvJtnWofT1rBjdwH2&resource=bills",
"createdDate": "2019-08-26T18:24:48.723Z",
"dueDate": "2019-09-30T00:00:00.000Z",
"currency": "USD",
"cc": [
],
"id": "Jq9riJvJtnWofT1rBjdwH2",
"items": [
{
"id": "T7zruzLU1Fmie464Muc6hW",
"price": 10,
"quantity": 1
},
{
"id": "6Hmxi2fVWoAHCMRnLU3qYm",
"price": 20,
"quantity": 1
},
{
"id": "TN7CHfXVeCeHSEg7jhJEtT",
"price": 30,
"quantity": 1
}
],
"token": "3d3HCEvroJsdGrpne886iHvd5QzZSTZJ4qTqXrzqdz4ygtUe2wTXuntfSRRTGShD3X"
}
}
{
"data": {
"status": "draft",
"url": "https://test.bitpay.com/bill?id=EnshCou5PvcGFaXSC5FF6R&resource=bills",
"createdDate": "2019-08-26T18:21:40.087Z",
"dueDate": "2019-09-30T00:00:00.000Z",
"currency": "USD",
"state": "VA",
"zip": "23242",
"country": "US",
"cc": [
],
"phone": "555-123-456",
"emailBill": true,
"id": "EnshCou5PvcGFaXSC5FF6R",
"items": [
{
"id": "7At4wBJkuW6eXrGMAobzEY",
"price": 10,
"quantity": 1
},
{
"id": "4dwXez3nWK1XGQYHCAEaHB",
"price": 20,
"quantity": 1
},
{
"id": "Hy7SEirqDzfrWmv2X68v7U",
"price": 30,
"quantity": 1
}
],
"token": "9nc1UKjDDrmkei5VsJqpNQ9fCSXxmq3gc12Vn3HkAVnQHmCktbVNRZAqETrWjYTPSK"
}
}
On the
right side,
you will find
an example
of the bill
object
returned in
the
response
you will get
from the
BitPay
server. A
description
of all bill
fields is
available in
the resourc
e section.
Fetch bills
GET
https://bitpay.com/bills
Facades
MERCHANT
HTTP
Request

signature:
304402203c2a125cd69707df2ac75b6dc2f923ff44c8012d0742dea17dcb472c6ceee5b902201abdb88cb56fd
256113ca6f4f538735ef83d1a181757adbffc7c91796de67dc4" "https://test.bitpay.com/bills?
token=GcAUe7hgY3F2FSh95Dsy5d&status=draft"
URL
Parameter
s
?token=
strin
URL parameter .
&status=
strin
g O
the bill status you want to query on
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
M
x-signature
HTTP
Response
{
"data": [
{
"status": "draft",
"url": "https://test.bitpay.com/bill?id=Wz7JMiGPG5iKSJaknrcjjV&resource=bills",
"createdDate": "2019-05-29T12:44:31.800Z",
"dueDate": "2019-05-31T00:00:00.000Z",
"currency": "USD",
"state": "VA",
"zip": "23242",
"country": "US",
"cc": [
],
"phone": "555-123-456",
"id": "Wz7JMiGPG5iKSJaknrcjjV",
"items": [
{
"id": "RvZiAZ3YudeAYjrBw3QJrS",
"price": 10,
"quantity": 1
},
{
"id": "T5YjEkeQTxpNTbzHZegdFL",
"price": 20,
"quantity": 1
},
{
"id": "T54r5uSzxjcW8Vugwe7ws5",
"price": 30,
"quantity": 1
}
],
"token": "9nc1UKjDDrmkei5VsJqpNQ8crNQcmwTB4doavjiVyugzEsYcKknNr14vLAniKo56er"
},
{
"status": "draft",
"url": "https://test.bitpay.com/bill?id=D6dzrNUFgEHHzZuReaudSU&resource=bills",
"createdDate": "2019-05-29T12:56:18.371Z",
"dueDate": "2019-05-31T00:00:00.000Z",
"currency": "USD",
"state": "VA",
"zip": "23242",
"country": "US",
"cc": [
],
"phone": "555-123-456",
"id": "D6dzrNUFgEHHzZuReaudSU",
"items": [
{
"id": "Mf8YES5LQ2PUxSszt9mgCv",
"price": 10,
"quantity": 1
},
{
"id": "TBvA49YXTYVFkiALX8a8td",
"price": 20,
"quantity": 1
},
{
"id": "WTmyZGjTEovJUfjsU7bMrg",
"price": 30,
"quantity": 1
}
],
"token": "9nc1UKjDDrmkei5VsJqpNQ83Eh7Jrs8BN3AXrQgVuLf8aRV9ApJ4VEkoAJ92UVizeF"
}
]
}
On the
right side,
you will find
an example
of the bill
object
returned in
the
response
you will get
from the
BitPay
server. A
description
of all bill
fields is
available in
the resourc
e section.
Fetch a
specific bill
GET
https://bitpay.com/bills/<billid>
Facades
POS MERCH
ANT
HTTP
Request

"https://test.bitpay.com/bills/D6dzrNUFgEHHzZuReaudSU?token=Tqi5NhskgZHW3ZUv6y1AZg"

signature:
3046022100ad7d2b9ba239f1f9d744d4c01fdd9aee302be4d0e6d3eb49ee3eaf653e357d4c022100cc0fbc0e0
be16d90bc7583835be83109d0fe55fd0654ad68a428a29e169548cf"
"https://test.bitpay.com/bills/D6dzrNUFgEHHzZuReaudSU?token=GcAUe7hgY3F2FSh95Dsy5d"
URL
Parameter
s
?token=
strin
URL parameter .
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
x-signature
HTTP
Response
{
"data": {
"status": "draft",
"createdDate": "2019-05-29T12:56:18.371Z",
"dueDate": "2019-05-31T00:00:00.000Z",
"currency": "USD",
"cc": [
],
"items": [
{
"price": 10,
"quantity": 1
},
{
"price": 20,
"quantity": 1
},
{
"price": 30,
"quantity": 1
}
],
"token": "3d3HCEvroJsdGrpne886iHweeSCWC9S6FyKA9iE4Nbzv1j1CWetoXPajxxeBGfLDpV"
}
}
{
"data": {
"status": "draft",
"createdDate": "2019-05-29T12:56:18.371Z",
"dueDate": "2019-05-31T00:00:00.000Z",
"currency": "USD",
"state": "VA",
"zip": "23242",
"country": "US",
"cc": [
],
"phone": "555-123-456",
"items": [
{
"price": 10,
"quantity": 1
},
{
"price": 20,
"quantity": 1
},
{
"price": 30,
"quantity": 1
}
],
"token": "9nc1UKjDDrmkei5VsJqpNQ83Eh7Jrs8BN3AXrQgVuLf8aRV9ApJ4VEkoAJ92UVizeF"
}
}
On the
right side,
you will find
an example
of the bill
object
returned in
the
response
you will get
from the
BitPay
server. A
description
of all bill
fields is
available in
the resourc
e section.
Update a
bill
PUT
https://bitpay.com/bills/<billid>
Facades
MERCHANT
HTTP
Request
curl -X PUT -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-

signature:
3045022100b7f19ffaea92005979d05faefb477e8fa4b385ca00fee1e860c5ed34b4d0fd8f022022c21bfba72
d5b28e800e73d41ba33e4ca1c524c0599117a3b43324fc15ea647" -d '{"items":[{"description":"test
item
4","price":40,"quantity":1}],"token":"9nc1UKjDDrmkei5VsJqpNQ83Eh7Jrs8BN3AXrQgVuLf8aRV9ApJ
4VEkoAJ92UVizeF"}' "https://test.bitpay.com/bills/D6dzrNUFgEHHzZuReaudSU"
URL
Parameter
s
<billId>
string M
the id of the bill you want to update .
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
M
x-signature
Body
Name Type Presence
items array O
description strin
g O
price numbe
r O
quantity numbe
r O
currency
ISO 4217 3-character currency code. This is the currency strin

g O
associated with the price field, supported currencies are listed on
https://bitpay.com/bitcoin-exchange-rates
email strin
g O
HTTP
Response
{
"data": {
"createdDate": "2019-05-29T12:56:18.371Z",
"dueDate": "2019-05-31T00:00:00.000Z",
"currency": "USD",
"state": "VA",
"zip": "23242",
"country": "US",
"cc": [
],
"phone": "555-123-456",
"items": [
{
"id": "9oFUs8zoxRDXtDU9kcoSKY",
"price": 40,
"quantity": 1
}
],
"token": "9tey2wdA6AG9G1nU53L2E1zWCkyvFfQFrdrCdYi6f5KMnSSjr65TnDjbiHDqpZbU7M"
}
}
On the
right side,
you will find
an example
of the bill
object
returned in
the
response
you will get
from the
BitPay
server. A
description
of all bill
fields is
available in
the resourc
e section.
Deliver a
bill via
email
POST
https://bitpay.com/bills/<billid>/deliveries
Facades
POS MERCH
ANT
HTTP
Request

'{"token":"3d3HCEvroJsdGrpne886iHnyxHoVK7ooaNKRWNWGzURqmb6SDxfzh8buzqhHgzNjqb"}'
"https://test.bitpay.com/bills/Wz7JMiGPG5iKSJaknrcjjV/deliveries"

signature:
3045022100d424521cd62d5f083bf6c023bbe7918240cdfcc89862edfd29fb046f178566cb022023c574458ca
875f0a7cb2441f12ae0d7a6ea9047f5ec751029b7e62755986264" -d
'{"token":"9nc1UKjDDrmkei5VsJqpNQ6zv1c2XwxsDVbLuCQCswVWkfUoZ9woUnEN8WzK6q71Rg"}'
"https://test.bitpay.com/bills/GvKJ2Esw5yHCeHco22vyPn/deliveries"
URL
Parameter
s
<billId>
strin
g M
the id of the bill you want to deliver via email .
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
x-signature
Body
Name Type Presence
token
API token for the bill you want to send via email. This token can be strin
g M
retrieve from the bill object <billId> via a GET
https://bitpay.com/bills/<invoiceId>.
HTTP
Response
Response to a successful bill delivery
{
"data": "Success"
}
Body
Name Type
data
string
set to "Success" once a bill is successfully sent via
email
Subscrip
tions
Subscriptio
ns are
repeat
billing
agreements
with
specific
buyers.
BitPay
sends bill
emails to
buyers
identified in
active
subscriptio
ns
according
to the
specified
schedule.
Resource
Example of subscription object via the merchant facade
{
"facade": "merchant/subscription",
"data": {
"id": "62Sh4rL4oVsbudGJjdXLJR",
"status": "draft",
"billData": {
"emailBill": true,
"cc": [
],
"currency": "USD",
"state": "VA",
"zip": "23242",
"country": "US",
"phone": "555-123-456",
"dueDate": "2019-05-31T00:00:00.000Z",
"items": [
{
"price": 10,
"quantity": 1
},
{
"price": 20,
"quantity": 1
},
{
"price": 30,
"quantity": 1
}
],
"merchant": "5a685a814ca200cb09b3d6b2"
},
"schedule": "0 0 0 * * 5",
"nextDelivery": "2019-05-29T00:00:00.000Z",
"createdDate": "2019-05-29T14:30:41.817Z",
"token": "6KkGHoxM8Gx5WM2tQWGtuafkiJTY1hG3gmMS8sFNGnxa2Vf22D6YT4NMqmFDkTwUPo"
}
}
Name Type
facade
string
Facade used to view subscription objects, set to "merchant/subscription".
data
object
Subscription data object
id
string
Subscription resource Id
status
string
Subscription object status. Can be draft, active or cancelled. Subscriptions in
active state will create new Bills on the nextDelivery date.
billData
object
Object containing the recurring billing information
emailBill
boolean
If set the true, BitPay will automatically issue recurring bills to
the email address provided once the status of the subscription is set to active.
cc
array
Email addresses to which a copy of the recurring bill must be sent
number
string
Recurring bill identifier, specified by merchant
currency
string
ISO 4217 3-character currency code. This is the currency associated with the
price field
name
string
Recurring Bill recipient's name
address1
string
Recurring Bill recipient's address
address2
string
city
string
Recurring Bill recipient's city
state
string
Recurring Bill recipient's state or province
zip
string
Recurring Bill recipient's ZIP code
country
string
Recurring Bill recipient's country
email
string
Recurring Bill recipient's email address
phone
string
Recurring Bill recipient's phone
dueDate
string
Date and time at which a bill is due, ISO-8601 format yyyy-mm-ddThh:mm:ssZ
(UTC).
passProcessingFee boolean
If set to true, BitPay's processing fee will be included in the amount charged
on the invoice
items
array
List of line items
description
string
price
number
quantity
number
merchant
string
Internal identifier for BitPay, this field can be ignored by the merchants.
schedule string
Schedule of repeat bill due dates. Can be weekly, monthly, quarterly, yearly, or

a simple cron expression specifying seconds, minutes, hours, day of month,
month, and day of week. BitPay maintains the difference between the due
date and the delivery date in all subsequent, automatically-generated bills.
+-------------- second (0 - 59)

| +------------ minute (0 - 59)
| | +---------- hour (0 - 23)
| | | +-------- day of month (1 - 31)
| | | | +------ month (1 - 12)
| | | | | +---- day of week (0 - 6) (Sunday=0 or 7)
| | | | | |
* * * * * * Cron expression
nextDelivery
Default is current date & time, ISO-8601 format yyyy-mm-ddThh:mm:ssZ
(UTC). Current or past date indicates that the bill can be delivered string
immediately. BitPay may modify the hh:mm:ss values in order to distribute
deliveries evenly throughout the day.
createdDate
Date and time of recurring billing creation, ISO-8601 format yyyy-mm- string
ddThh:mm:ssZ (UTC)
token
API token for subscription resource. This token is actually derived from the API
token used to create the subscription and is tied to the specific resource id string
created.
Create a
subscriptio
n
POST
https://bitpay.com/subscriptions
Facades
MERCHANT
HTTP
Request

signature:
30450221008d5f19cc140160ff6410d9c84c55d9f5abfffa01a1ac2aa05f47ce8207b78cf602201c4e60f18da
2aa4c49851aaed0441c060d7b07fe69d8183db725d4ad4c157795" -d '{"billData":{"number":"test-
xyz","currency":"USD","name":"Fox Mulder","address1":"2630 Hegal Place","address2":"Apt
{"description":"test item 3","price":30,"quantity":1}]},"nextDelivery":"2020-2-
20","schedule":"weekly","token":"GcAUe7hgY3F2FSh95Dsy5d"}'
"https://test.bitpay.com/subscriptions"
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
M
x-signature
Body
Name Type Presence
billData
object M
cc
array O
Email addresses to which a copy of the recurring bill must be sent
number
string O
currency
string M
name
string O
address1 string O
address2
string O
city
string O
state
string O
zip
string O
country
string O
email
string M
phone string O
dueDate
string M
ddThh:mm:ssZ (UTC).
passProcessingFee
boolean O
items
array M
List of line items
description
string M
price
number M
quantity
number M
schedule string M
Schedule of repeat bill due dates. Can
be weekly, monthly, quarterly, yearly, or a simple cron expression
specifying seconds, minutes, hours, day of month, month, and
day of week. BitPay maintains the difference between the due
date and the delivery date in all subsequent, automatically-
generated bills.
+-------------- second (0 - 59)
| +------------ minute (0 - 59)
| | +---------- hour (0 - 23)
| | | +-------- day of month (1 - 31)
| | | | +------ month (1 - 12)
| | | | | |
nextDelivery
Default is current date & time, ISO-8601 format yyyy-mm-
ddThh:mm:ssZ (UTC). Current or past date indicates that the bill string O
can be delivered immediately. BitPay may modify the hh:mm:ss
values in order to distribute deliveries evenly throughout the day.
token
API token retrieved via endpoint POST string M
https://bitpay.com/tokens (merchant facade)
HTTP
Response
{
"data": {
"status": "draft",
"billData": {
"emailBill": true,
"cc": [
],
"currency": "USD",
"state": "VA",
"zip": "23242",
"country": "US",
"phone": "555-123-456",
"dueDate": "2019-05-31T00:00:00.000Z",
"items": [
{
"price": 10,
"quantity": 1
},
{
"price": 20,
"quantity": 1
},
{
"price": 30,
"quantity": 1
}
],
},
"schedule": "0 0 0 * * 5",
"nextDelivery": "2019-05-29T00:00:00.000Z",
"createdDate": "2019-05-29T14:30:41.817Z",
}
}
On the
right side,
you will find
an example
of the
subscriptio
n object
returned in
the
response
you will get
from the
BitPay
server. A
description
of all
subscriptio
n fields is
available in
the resourc
e section.
Fetch
subscriptio
ns based
on status
GET
https://bitpay.com/subscriptions
Facades
MERCHANT
HTTP
Request

signature:
304502205d0dcc2e3a699ccd71bef8ca8186a88eb072ff7d8fd04a3b9ad2baa641ed3cba02210095a92bba087
b1515fe9169e2cbbacf226aea87c23f339bdd78c8418bfac816ca"
"https://test.bitpay.com/subscriptions?token=GcAUe7hgY3F2FSh95Dsy5d&status=draft"
URL
Parameter
s
?token=
strin
when fetching subscriptions, pass a merchant facade token as a g M
URL parameter .
&status=
strin
g O
the subscription status you want to query on
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
M
x-signature
HTTP
Response
{
"data": [
{
"id": "WZZnSk2ohWq6A88YmRYkoy",
"status": "draft",
"billData": {
"emailBill": true,
"cc": [],
"dueDate": "2019-05-10T00:00:00.000Z",
"number": "test-subscription",
"state": "VA",
"zip": "23242",
"country": "US",
"currency": "USD",
"phone": "555-123-456",
"items": [
{
"description": "item A",
"price": 10,
"quantity": 2
},
{
"description": "item B",
"price": 20,
"quantity": 1
},
{
"description": "item C",
"price": 30,
"quantity": 1
}
],
},
"schedule": "0 0 0 10 * *",
"nextDelivery": "2019-05-10T00:00:00.000Z",
"createdDate": "2019-05-10T12:50:08.815Z",
"token": "6KkGHoxM8Gx5WM2tQWGtuaioAFQfpcKdriHka4vyy6JkGKBbPphKC9fX7LYsErw5LQ"
},
{
"status": "draft",
"billData": {
"emailBill": true,
"cc": [
],
"currency": "USD",
"state": "VA",
"zip": "23242",
"country": "US",
"phone": "555-123-456",
"dueDate": "2019-05-31T00:00:00.000Z",
"items": [
{
"price": 10,
"quantity": 1
},
{
"price": 20,
"quantity": 1
},
{
"price": 30,
"quantity": 1
}
],
},
"schedule": "0 0 0 * * 5",
"nextDelivery": "2019-05-29T00:00:00.000Z",
"createdDate": "2019-05-29T14:30:41.817Z",
}
]
}
On the
right side,
you will find
an example
of the
subscriptio
n object
returned in
the
response
you will get
from the
BitPay
server. A
description
of all
subscriptio
n fields is
available in
the resourc
e section.
Fetch a
specific
subscriptio
n
GET
https://bitpay.com/subscriptions/<subscriptionid>
Facades
MERCHANT
HTTP
Request

signature:
304402202459075c07af2dbfbd95b75e583fcee37a152d256c97fc165e465f62e03bd37f0220152d3232978d7
539b4c62f49cfdd472dcf5d262a00b3c426a2b1b5b4a56eeebc"
"https://test.bitpay.com/subscriptions/62Sh4rL4oVsbudGJjdXLJR?
token=GcAUe7hgY3F2FSh95Dsy5d"
URL
Parameter
s
<subscriptionId>
strin
g O
the subscription status you want to query on
?token=
strin
when fetching subscriptions, pass a merchant facade token as a g M
URL parameter .
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
M
x-signature
HTTP
Response
{
"data": {
"status": "draft",
"billData": {
"emailBill": true,
"cc": [
],
"currency": "USD",
"state": "VA",
"zip": "23242",
"country": "US",
"phone": "555-123-456",
"dueDate": "2019-05-31T00:00:00.000Z",
"items": [
{
"price": 10,
"quantity": 1
},
{
"price": 20,
"quantity": 1
},
{
"price": 30,
"quantity": 1
}
],
},
"schedule": "0 0 0 * * 5",
"nextDelivery": "2019-05-29T00:00:00.000Z",
"createdDate": "2019-05-29T14:30:41.817Z",
}
}
On the
right side,
you will find
an example
of the
subscriptio
n object
returned in
the
response
you will get

from the
BitPay
server. A
description
of all
subscriptio
n fields is
available in
the resourc
e section.
Update a
specific
subscriptio
n
PUT
https://bitpay.com/subscriptions/<subscriptionid>
Facades
MERCHANT
HTTP
Request
curl -X PUT -H "x-accept-version: 2.0.0" -H "content-type: application/json" -H "x-

signature:
304402203fa240bbd06f0fc32ca53b15f8b7f2d06eac09f92aa00207ad91df6630aea25002204e2fe38727992
a4adf5f998f72b8d2220133a5560cbe0e652dfd7e5f7eef3f9b" -d
'{"status":"active","token":"6KkGHoxM8Gx5WM2tQWGtuafkiJTY1hG3gmMS8sFNGnxa2Vf22D6YT4NMqmFD
kTwUPo"}' "https://test.bitpay.com/subscriptions/62Sh4rL4oVsbudGJjdXLJR"
URL
Parameter
s
<subscriptionId>
the subscription you want to

string M
update
Headers
fields Presence
x-accept-version:
M
content-type
M
x-identity
M
x-signature
Body
Name Type Presence
status
Can be "draft" or "active" or "cancelled`. Subscriptions in active

string O
state will create new Bills on the nextDelivery date.
billData
object O
cc
array O
Email addresses to which a copy of the recurring bill must be
sent
number
string O
currency
string O
name
string O
address1
string O
address2
string O
city
string O
state
string O
zip
string O
country
string O
email
string O
phone
string O
dueDate string O
ddThh:mm:ssZ (UTC).
passProcessingFee
boolean O
items
array O
List of line items
description
string
price
number O
quantity
number O
schedule string O
Schedule of repeat bill due dates. Can

be weekly, monthly, quarterly, yearly, or a simple cron expression
specifying seconds, minutes, hours, day of month, month, and
day of week. BitPay maintains the difference between the due
date and the delivery date in all subsequent, automatically-
generated bills.
+-------------- second (0 - 59)
| +------------ minute (0 - 59)
| | +---------- hour (0 - 23)
| | | +-------- day of month (1 - 31)
| | | | +------ month (1 - 12)
| | | | | |
nextDelivery
Default is current date & time, ISO-8601 format yyyy-mm-
ddThh:mm:ssZ (UTC). Current or past date indicates that the bill
can be delivered immediately. BitPay may modify the hh:mm:ss string O
values in order to distribute deliveries evenly throughout the
day.
token
API token for the subscription you want to modify. This token
can be retrieve from the subscription object <subscriptionId> via string M
a GET https://bitpay.com/subscriptions/<subscriptionId>.
HTTP
Response
Example of activated subscription
{
"data": {
"status": "active",
"billData": {
"emailBill": true,
"cc": [
],
"currency": "USD",
"state": "VA",
"zip": "23242",
"country": "US",
"phone": "555-123-456",
"dueDate": "2019-05-31T00:00:00.000Z",
"items": [
{
"price": 10,
"quantity": 1
},
{
"price": 20,
"quantity": 1
},
{
"price": 30,
"quantity": 1
}
],
},
"schedule": "0 0 0 * * 5",
"nextDelivery": "2019-05-29T00:00:00.000Z",
"createdDate": "2019-05-29T14:30:41.817Z",
"token": "5qo69Typ9E5UzE824SA3z4Y1GVUwLMwADX14CqbfnBwek2xKLBE8Fkh3ic5wB4Pq9c"
}
}
On the
right side,
you will find
an example
of the
subscriptio
n object
returned in
the
response
you will get
from the
BitPay
server. A
description
of all
subscriptio
n fields is
available in
the resourc
e section.
Rates
Rates are
exchange
rates,
representin
g the
number of
fiat
currency
units
equivalent
to one BTC.
Fetch the
rates used
by BitPay
for a
specific
cryptocurr
ency
GET
https://bitpay.com/rates/<basecurrency>
Facades
PUBLIC
HTTP
Request
via the public facade

"https://test.bitpay.com/rates/BTC"
URL
Parameter
s
<baseCurrency> strin M
g
the cryptocurrency for which you want to fetch the rates. Current
supported values are BTC and BCH
Headers
fields Presence
x-accept-version:
M
content-type
must be set to application/json for request to the BitPay M

API
HTTP
Response
Example of rates, for BTC as baseCurrency
{
"data": [
{
"code": "BTC",
"name": "Bitcoin",
"rate": 1
},
{
"code": "BCH",
"name": "Bitcoin Cash",
"rate": 23.55
},
{
"code": "USD",
"name": "US Dollar",
"rate": 8735.56
},
{
"code": "EUR",
"name": "Eurozone Euro",
"rate": 7914.5
},
{
"code": "ETH",
"name": "Ether",
"rate": 51.58
},
{
"code": "XRP",
"name": "Ripple",
"rate": 37770.49
},
{
"code": "GBP",
"name": "Pound Sterling",
"rate": 6687.25
},
{
"code": "JPY",
"name": "Japanese Yen",
"rate": 951813.51
},
{
"code": "CAD",
"name": "Canadian Dollar",
"rate": 11514.6
},
{
"code": "AUD",
"name": "Australian Dollar",
"rate": 12904.85
},
{
"code": "CNY",
"name": "Chinese Yuan",
"rate": 60595.96
},
...
]
}
Body
Name Type
data
array
array of currency rates for the requested <baseCurrency>
code string
ISO 4217 3-character currency code
name
string
detailed currency name
rate
number
rate for the requested <baseCurrency> /<currency> pair
Fetch the
rates used
by BitPay
for a
specific
cryptocurr
ency / fiat
pair
GET
https://bitpay.com/rates/<basecurrency>/<currency>
Facades
PUBLIC
HTTP
Request
via the public facade

"https://test.bitpay.com/rates/BCH/EUR"
URL
Parameter
s
<baseCurrency>
strin
the cryptocurrency for which you want to fetch the rates. Current g M
supported values are BTC and BCH
<currency>
strin
the fiat currency for which you want to fetch g M
the <baseCurrency> rates
Headers
fields Presence
x-accept-version:
M
content-type

API
HTTP
Response
{
"data": {
"code": "EUR",
"rate": 419.83
}
}
Body
Name Type
data
object
rate data object
code
string
name
string
detailed currency name
rate
number
rate for the
requested <baseCurrency> /<currency> pair
Sessions
API
sessions are
an optional
feature of
our API
which can
be utilized
to provide
even
greater
security and
reliability. In
particular it
protects
against repl
ay
attacks and
ensures api
requests
are
processed
in the same
order they
are
received.
An API
session can
be created
by issuing
a POST to /s
essions.
The server
responds
with
a sessionId.
The session
Id is used in
each
subsequent
request
along with
a requestNu
mber. These
fields, sessi
onId and re
questNumber
are
included as
parameters
either in the
URL for
a GET or in
the data
body
for POST an
d PUT. On
the first
request,
the request
Number shou
ld be 1.
Each
additional
request
should
increment
the request
Number by 1.
If the server
receives a
request out
of order it
will return
an error. If
the client
does not
hear back
from the
server
because of
an
interruption
in network
connectivity
or some
other
problem,
the client
may retry
by sending
the same
request
with the
same
requestNu
mber. The
server will
then
respond
with a
cached
copy of the
data if it
had already
serviced
that request
but was
interrupted
when
delivering it
to the
client. API
sessions
timeout
after 15
minutes of
inactivity.
After 15
minutes,
clients will
get an
error, and
must create
a new
session.
Clients can
be
programme
d to handle
creation of
new
sessions
and
timeouts
automatical
ly. Please
see the
Node.js
client
library for a
working
implementa
tion.
Creates an
API session
Creates an
API session
to protect
against
replay
attacks and
ensure
requests
are received
in the same
order they
are sent.
POST
https://bitpay.com/sessions
Facades
PUBLIC
HTTP
Request
curl -X POST -H "x-accept-version: 2.0.0" -H "content-type: application/json" -d ''

"https://test.bitpay.com/sessions"
Headers
fields Presence
x-accept-version:
M
content-type

API
HTTP
Response
{
"data": "9d3dc999f49eec7a96854a802f800efa0ba1e883f5a7d509a8d34ea0133bd7c8"
}
Body
Name Type
data
string
the API sessionId is returned in this
field
Currenci
es
Currencies
are fiat
currencies
supported
by BitPay
Fetch the
supported
currencies
GET
https://bitpay.com/currencies
Facades
PUBLIC
HTTP
Request

"https://test.bitpay.com/currencies"
Headers
fields Presence
x-accept-version:
M
content-type

API
HTTP
Response
Example response
{
"data": [
{
"code": "BTC",
"symbol": "฿",
"precision": 6,
"name": "Bitcoin",
"plural": "Bitcoin",
"alts": "btc",
"minimum": 0.000006,
"sanctioned": false,
"decimals": 8,
"chain": "BTC"
},
...
...
{
"code": "XRP",
"symbol": "Ʀ",
"precision": 6,
"name": "Ripple",
"plural": "Ripple",
"alts": "xrp",
"minimum": 0.000006,
"decimals": 6,
"chain": "XRP"
},
...
...
{
"code": "EUR",
"symbol": "€",
"precision": 2,
"plural": "Eurozone Euros",
"alts": "eur",
"minimum": 0.01,
"decimals": 2
},
...
...
{
"code": "USD",
"symbol": "$",
"precision": 2,
"name": "US Dollar",
"plural": "US Dollars",
"alts": "usd bucks",
"minimum": 0.01,
"decimals": 2
},
{
"code": "USDC",
"symbol": "$",
"precision": 2,
"name": "Circle USD Coin",
"plural": "Circle USD Coin",
"alts": "",
"minimum": 0.01,
"decimals": 6,
"chain": "ETH"
},
...
...
]
}
Body
Name Type
data
array
Array of supported currencies
code
string
symbol
string
Display symbol
precision
number
Number of decimal places
name string
English currency name
plural
string
English plural form
alts
string
Alternative currency name(s)
minimum
string
Minimum supported value when creating an invoice, bill or payout for
instance
sanctionned
boolean
If the currency is linked to a sanctionned country
decimals
number
decimal precision
chain
string
For cryptocurrencies or tokens, the corresponding chain is also specified. For
instance, with USDC (Circle USD Coin), the chain is ETH.
Legd
er
entry
code
s
Code Name type Description
once an invoice reaches

100 the "complete" status, the corresponding
Invoice credit
0 amount is credited to the merchant
account in the selected settlement currency
100
Fee Refund credit
4
This entry indicates that BitPay transfered

your balance from one ledger currency
(recorded as a debit) to another ledger
debit
100 currency (recorded as a credit). This
Exchange &
6 typically happens if a merchant needs to
credit
change settlement currency and exchange
the pending balance from one currency to
another
100
Exchange Fee debit
7
For merchants on a legacy SaaS plan, this
100
Plan Charge debit entry is used to debit the merchant
8
account with the monthly fee
100 Plan Prorated For merchants on a legacy SaaS plan, this

credit
9 Credit entry is used to adjust the amount charged.
Plan For merchants on a legacy SaaS plan, this

101
Underutilization credit entry is used to adjust the amount debited
0
Credit (account not used)
This entry does not have any additional

fields. It corresponds to an automatic
transfer made by BitPay from one ledger
currency to another. Typically to cover
debit refund or payout requests. For instance, if
101 Payoff Negative
& you execute a refund request where EUR is
1 Balance
credit the base currency but your active ledger
(linked to the settlement currency) is in
USD, you will see such "Payoff Negative
Balance" entry appear on both ledger (a
debit on the USD ledger and a credit)
101
Donation credit
2
debit Code used by BitPay for general purpose

101
Custom & custom entries. It may be use to correct an
6
credit invalid entry on your ledger
101 Account debit This entry is written to debit the merchant

7 Settlement balance for a given account settlement
This entry is written once a refund request

102 made on an invoice is executed. The
Invoice Refund debit
0 merchant balance is debited with the
refund amount requested.
Indicates a previous settlement failed (for

Corrective for instance invalid settlement info). In such
102
Failed Account credit scenario BitPay credits the amount back to
2
Settlement the merchant account using this ledger
code.
Once an invoice reaches

102
Invoice Fee debit the "complete" status, the corresponding
3
fee is credited using this ledger code
102
Bitcoin Deposit credit
4
When a merchant makes a bank transfer to

102 BitPay, the deposited amount is credited to
Fiat Deposit credit
5 the merchant account using this ledger
code
102
Donation Fee debit
6
102 Custom Fee debit

7
For merchants who onboarded business

103 Affiliate under their referral link, the commissions
credit
0 Commission are credited to the account using this
ledger code
103 Manual Affiliate

credit
1 Commission
103 Merchant Card

debit
2 Deposit
103 Custom Plan

debit
3 Charge
This entry is written once BitPay sets a

103 Funding Payout payout request to the status funded. This
debit
4 Request means that part of the merchant balance
has been allocated to execute a payout.
Manually
103
Funding Payout debit
5
Request
103 Custom Fee

credit
6 Reimbursement
Custom Plan
103
Charge credit
7
Reimbursement
Testnet BTC/BCH settlements

103 Testnet Bitcoin
debit (test.bitpay.com) are recorded using this
8 Settlement
ledger code
This entry will be immediately written next

103 to the "Invoice Refund". The refund fee is
Refund Fee debit
9 the actual cost of broadcasting the refund
transaction on the selected blockchain
This entry is written once BitPay sets a

104 payout request to the status funded. This is
Payout Fee debit
0 the fee charged for each payout request
executed
104
Wire Fee debit
1
Notif
icati
ons
Webho
oks
Webhooks
are an HTTP
POST
message
sent from
the BitPay
server to
the
merchant’s
eCommerce
server.
Instant
Payment
Notificat
ions
The only
webhook
available at
the
moment is
the Instant
Payment
Notificatio
n (IPN).
The primary
purpose of
an IPN is to
alert the
merchant’s
ecommerce
server that
the status
of a
resource
(invoice,
payout) has
changed.
The
messages
are sent to
the notific
ationURL fie
ld when
creating the
invoice or
payout
request.
Handling
BitPay does not sign IPNs, so the information in the payload should never be trusted
outright
1. The
IPN
shal
l be
use
d as
trig
ger
to
verif
the
stat
us
of a
spe
cific
invo
ice
or
pay
out.
This
can
be
don
e by
fetc
hin
the
corr
esp
ond
ing i
nvoi
ce o
r pa
you
batc
h,
sinc
e
bot
invo
ice
id
and
pay
out
batc
h id
are
pro
vide
d in
the
bod
y of
the
IPN.
2. Car
efull
y
sele
ct
the
stat
us
of a
give
reso
urce
bef
ore
pro
cess
ing
an
ord
er.
For
inst
anc
the
invo
ice
"pai
d" s
tatu
doe
not
repr
ese
nt a
pay
me
nt
gua
rant
ee,
so
mer
cha
nts
sho
uld
only
pro
cess
an
ord
er
afte
the
corr
esp
ond
ing
BitP
ay
invo
ice
has
reac
hed
the
stat
us "
conf
irme
d" o
r "c
ompl
ete"
. For
mor
info
rma
tion
plea
se
hav
ea
look
at
the
invo
ice
stat
use
s
sect
ion.
3. The
BitP
ay
serv
er
exp
ects
an
HTT
200.
Any
oth
er
HTT
resp
ons
e is
con
side
red
by
BitP
ay
as a
faile
deli
very
4. Mak
sure
to
not
rely
on
whit
elist
ing
BitP
ay’s
sen
din
g IP
add
ress
es,
as
thes
e IP
add
ress
es
are
subj
ect
to
cha
nge
with
out
noti
ce.
5. Mak
e
sure
to
use
HTT
PS
for
you
r no
tifi
cati
onUR
L.
The BitPay
server
attempts to
send IPNs
multiple
times until
the send is
either
successful
or the
BitPay
server gives
up. The
BitPay
server
attempts
retries
using an
exponential
back on the
following
schedule:
 2
minu
te
delay
 7
minu
te
delay
 17
minu
te
delay
 34
minu
te
delay
 60
minu
te
delay
 97
minu
te
delay
 147
minu
te
delay
 212
minu
te
delay
 294
minu
te
delay
 395
minu
te
delay
 517
minu
te
delay
 662
minu
te
delay
 832
minu
te
delay
 1028
minu
te
delay
Invoices
The body of
the IPNs
sent by
BitPay is a
JSON-
formatted
string
(Content-
Type:
application
/json) and
comes in 2
different
formats.
The standar
d format is
used by
default for
the invoice
resource.
Standard
IPN format
This format
is only
applicable
for the
invoice
resource.
BitPay strongly advise merchants to use instead the extended format for the invoice
resource by passing the parameter "extendedNotifications": true in the body of the invoice
request.
Headers
Header Value
Accept application/json
Content-Type application/json
Body
Example of webhook - standard format
{
"id": "FDz8kZFQeDHjKG6PMgXoLZ",
"url": "https://test.bitpay.com/invoice?id=FDz8kZFQeDHjKG6PMgXoLZ",
"price": 10,
"currency": "EUR",
"invoiceTime": 1580129696201,
"currentTime": 1580129768472,
"buyerFields": {
"buyerState": "VA",
"buyerPhone": "555-123-456",
"buyerNotify": true,
"buyerEmail": "fox.mulder@trustno.one"
},
"BTC": 126600,
"BCH": 2987400,
"ETH": 65254000000000000,
"GUSD": 1102,
"PAX": 11020000000000000000,
"USDC": 11020000,
"XRP": 47915668
},
"paymentTotals": {
"BTC": 126700,
"BCH": 2987400,
"ETH": 65254000000000000,
"GUSD": 1102,
"PAX": 11020000000000000000,
"USDC": 11020000,
"XRP": 47915668
},
"exchangeRates": {
"BTC": {
"EUR": 7900.97,
"USD": 8709,
"BCH": 23.56331168831169,
"ETH": 51.55389806428698,
"GUSD": 8709,
"PAX": 8709,
"USDC": 8709,
"XRP": 37852.05146036161
},
"BCH": {
"EUR": 334.74,
"USD": 369.1000000000001,
"BTC": 0.04238090918589845,
"ETH": 2.1849286686793348,
"GUSD": 369.1000000000001,
"PAX": 369.1000000000001,
"USDC": 369.1000000000001,
"XRP": 1604.2246175243397
},
"ETH": {
"EUR": 153.24810916,
"USD": 168.92000000000002,
"BTC": 0.019395782117805377,
"BCH": 0.45703463203463196,
"GUSD": 168.92000000000002,
"PAX": 168.92000000000002,
"USDC": 168.92000000000002,
"XRP": 734.1794158553547
},
"GUSD": {
"EUR": 0.907223,
"USD": 1,
"BTC": 0.00011482229527471808,
"BCH": 0.0027056277056277055,
"ETH": 0.00591961167347422,
"PAX": 1,
"USDC": 1,
"XRP": 4.346314325452017
},
"PAX": {
"EUR": 0.907223,
"USD": 1,
"BTC": 0.00011482229527471808,
"BCH": 0.0027056277056277055,
"ETH": 0.00591961167347422,
"GUSD": 1,
"USDC": 1,
"XRP": 4.346314325452017
},
"USDC": {
"EUR": 0.907223,
"USD": 1,
"BTC": 0.00011482229527471808,
"BCH": 0.0027056277056277055,
"ETH": 0.00591961167347422,
"GUSD": 1,
"PAX": 1,
"XRP": 4.346314325452017
},
"XRP": {
"EUR": 0.2087,
"USD": 0.22994,
"BTC": 0.000026402238575468675,
"BCH": 0.0006221320346320346,
"ETH": 0.0013611555081986621,
"GUSD": 0.22994,
"PAX": 0.22994,
"USDC": 0.22994
}
},
"amountPaid": 65254000000000000,
"transactionCurrency": "ETH"
}
Name Type
id
string
BitPay invoice id
url
string
BitPay invoice URL
posData string
As passed by the merchant during invoice creation
status
string
current invoice status given by the IPN, see Invoice resource for more
information
price
number
Fixed price amount for the checkout as indicated by the merchant during
invoice creation, in the selected "currency"
currency
string
ISO 4217 3-character currency code passed by the merchant during invoice
creation
invoiceTime
string
UNIX time of invoice creation, in milliseconds
expirationTime
string
UNIX time when invoice is last available to be paid, in milliseconds
currentTime
string
UNIX time of API call, in milliseconds
exceptionStatus string
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.
buyerFields
If provided by the merchant in the buyer object during invoice creation object
buyerName
If provided by the merchant in the buyer object during invoice creation string
buyerAddress1
buyerAddress2
buyerCity
buyerState
buyerZip
buyerCountry
buyerPhone
buyerNotify
If provided by the merchant in the buyer object during invoice creation boolean
buyerEmail
paymentSubtotals
For internal use - This field can be ignored in merchant implementations. object
paymentTotals
exchangeRates
Exchange rate used for this invoice, depending on the invoice currency and object
the transactionCurrency selected
amountPaid
The total amount paid to the invoice in terms of the
invoice transactionCurrency indicated in the smallest possible unit for the number
corresponding transactionCurrency (e.g satoshis for BTC and BCH)
orderId
As passed by the merchant during invoice creation string
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" string
or "BCH"
Extended
IPN format
This is the
recommend
ed IPN
format that
BitPay
advises for
all new
implementa
tions. This
will allow
merchants
to get
additional
status
notification
which are
not sent if
the
standard
format is
used
(expired
invoice,
refunded
invoice etc).
Headers
Header Value
Body
Example or IPN using the extended format
{
"event": {
"code": 1005,
"name": "invoice_confirmed"
},
"data": {
"id": "4tGXJ8dygCCDeRx8eidd9B",
"url": "https://test.bitpay.com/invoice?id=4tGXJ8dygCCDeRx8eidd9B",
"price": 10,
"currency": "EUR",
"invoiceTime": 1580128649702,
"currentTime": 1580128716381,
"buyerFields": {
"buyerState": "VA",
"buyerPhone": "555-123-456",
"buyerNotify": true,
"buyerEmail": "fox.mulder@trustno.one"
},
"BTC": 126600,
"BCH": 2983700,
"ETH": 65157000000000000,
"GUSD": 1102,
"PAX": 11020000000000000000,
"USDC": 11020000,
"XRP": 47846890
},
"paymentTotals": {
"BTC": 126700,
"BCH": 2983700,
"ETH": 65157000000000000,
"GUSD": 1102,
"PAX": 11020000000000000000,
"USDC": 11020000,
"XRP": 47846890
},
"exchangeRates": {
"BTC": {
"EUR": 7897.969999999998,
"USD": 8710.87,
"BCH": 23.4037345513165,
"ETH": 51.488769358080155,
"GUSD": 8710.87,
"PAX": 8710.87,
"USDC": 8710.87,
"XRP": 37789.55359854237
},
"BCH": {
"EUR": 335.15,
"USD": 371.5,
"BTC": 0.042647815146116125,
"ETH": 2.195886038538834,
"GUSD": 371.5,
"PAX": 371.5,
"USDC": 371.5,
"XRP": 1611.643746475207
},
"ETH": {
"EUR": 153.47491491,
"USD": 169.17,
"BTC": 0.01942054074904028,
"BCH": 0.45451370231058574,
"GUSD": 169.17,
"PAX": 169.17,
"USDC": 169.17,
"XRP": 733.8944080517114
},
"GUSD": {
"EUR": 0.907223,
"USD": 1,
"BTC": 0.00011479896405414838,
"BCH": 0.0026867275658248252,
"ETH": 0.005910864168341411,
"PAX": 1,
"USDC": 1,
"XRP": 4.338206585397597
},
"PAX": {
"EUR": 0.907223,
"USD": 1,
"BTC": 0.00011479896405414838,
"BCH": 0.0026867275658248252,
"ETH": 0.005910864168341411,
"GUSD": 1,
"USDC": 1,
"XRP": 4.338206585397597
},
"USDC": {
"EUR": 0.907223,
"USD": 1,
"BTC": 0.00011479896405414838,
"BCH": 0.0026867275658248252,
"ETH": 0.005910864168341411,
"GUSD": 1,
"PAX": 1,
"XRP": 4.338206585397597
},
"XRP": {
"EUR": 0.209,
"USD": 0.23048000000000002,
"BTC": 0.00002645886523520012,
"BCH": 0.0006192369693713058,
"ETH": 0.0013623359735193286,
"GUSD": 0.23048000000000002,
"PAX": 0.23048000000000002,
"USDC": 0.23048000000000002
}
},
"amountPaid": 65157000000000000,
"transactionCurrency": "ETH"
}
}
Name Type
event object
Webhook event object
code
number
See the list of available Webhook notification codes for more information
name
string
data
object
Webhook data object, containing invoice parameters
id
string
BitPay invoice id
url
string
BitPay invoice URL
posData
string
As passed by the merchant during invoice creation
status
string
current invoice status given by the IPN, see Invoice resource for more
information
price
number
Fixed price amount for the checkout as indicated by the merchant during
invoice creation, in the selected "currency"
currency
string
ISO 4217 3-character currency code passed by the merchant during invoice
creation
invoiceTime
string
UNIX time of invoice creation, in milliseconds
expirationTime
string
UNIX time when invoice is last available to be paid, in milliseconds
currentTime
string
UNIX time of API call, in milliseconds
exceptionStatus string
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.
buyerFields
If provided by the merchant in the buyer object during invoice creation object
buyerName
buyerAddress1
buyerAddress2
buyerCity
buyerState
buyerZip
buyerCountry
buyerPhone
buyerNotify
If provided by the merchant in the buyer object during invoice creation boolean
buyerEmail
paymentSubtotals
paymentTotals
exchangeRates
Exchange rate used for this invoice, depending on the invoice currency and object
the transactionCurrency selected
amountPaid
The total amount paid to the invoice in terms of the
invoice transactionCurrency indicated in the smallest possible unit for the number
corresponding transactionCurrency.
orderId
As passed by the merchant during invoice creation string
transactionCurrency string
The cryptocurrency used to pay the invoice. This field will only be available
after a transaction is applied to the invoice.
Webhook
Notificatio
n Codes
Codes for
invoice
events with
webhook
notification
BitPay Name Purpose

code
1003 To notify merchant that an invoice has

"invoice_paidInFull"
reached the status paid
1004 To notify a merchant that an invoice has

"invoice_expired"
expired without being paid

"invoice_confirmed"
reached the status confirmed
1006 "invoice_completed" To notify merchant that an invoice has

reached the status completed

"invoice_failedToConfirm"
reached the status invalid
1016 To notify a merchant that a refund request

"invoice_refundComplete"
has been successfully processed
Payouts
IPN format
See below examples of extended webhooks for the payout resource
{
"event": {
"code": 2001,
"name": "payoutRequest_funded"
},
"data": {
"status": "funded",
"amount": 5,
"percentFee": 1,
"fee": 0.05,
"rate": 5147.62,
"btc": 0.000972,
"currency": "USD",
"requestDate": "2019-04-29T15:16:40.706Z",
"instructions": [
{
"amount": 1,
"btc": {
"unpaid": 0,
"paid": 0.000194
},
"transactions": [],
"status": "unpaid"
},
{
"amount": 2,
"btc": {
"unpaid": 0,
"paid": 0.000389
},
"transactions": [],
"status": "unpaid"
},
{
"amount": 2,
"btc": {
"unpaid": 0,
"paid": 0.000389
},
"transactions": [],
"status": "unpaid"
}
]
}
}
{
"event": {
"code": 2002,
"name": "payoutRequest_completed"
},
"data": {
"amount": 5,
"percentFee": 1,
"fee": 0.05,
"rate": 5147.62,
"btc": 0.000972,
"currency": "USD",
"requestDate": "2019-04-29T15:16:40.706Z",
"instructions": [
{
"amount": 1,
"btc": {
"unpaid": 0,
"paid": 0.000194
},
"transactions": [
{
"amount": 0.000194,
"date": "2019-04-29T15:21:24.182Z"
}
],
"status": "paid"
},
{
"amount": 2,
"btc": {
"unpaid": 0,
"paid": 0.000389
},
"transactions": [
{
"amount": 0.000389,
"date": "2019-04-29T15:21:24.903Z"
}
],
"status": "paid"
},
{
"amount": 2,
"btc": {
"unpaid": 0,
"paid": 0.000389
},
"transactions": [
{
"amount": 0.000389,
"date": "2019-04-29T15:21:25.641Z"
}
],
"status": "paid"
}
],
"dateExecuted": "2019-04-29T15:21:24.177Z"
}
}
Headers
Header Value
Body
Name Type
event
object
Webhook event object
code
number
name
string
data
object
Webhook data object, containing the payout object data. A description of all
payout fields is available in the payout resource section
Webhook
Notificatio
n Codes
Codes for
payout
events with
webhook
notification
BitPay Name Purpose

code
2001 To notify a merchant that a payout batch has

"payoutRequest_funded"
been set to the status funded

"payoutRequest_completed"
been set to the status complete

"payoutRequest_cancelled"
been set to the status cancelled

API REST Bitpay English

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

API REST Bitpay English

Uploaded by

Copyright:

Available Formats

REST

may call the

Facade Capabilities Description

ed, you will

Name Type returned via facade

Can be "requireSin", "requireFacadeAccess", string ✓ ✓

Access approval code. To be validated via string ✓ ✓

Can be merchant, pos or payroll. If passed in the body of the strin

 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,

 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

just like the other facades with higher privileges.

you will find

Example of invoice resource (fetched using the merchant facade)

Name Type returned via facade

This field indicates the facade from which

request an invoice resource

request an invoice resource

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

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

overpaid amount on an invoice is

automatically refunded by BitPay

 "confirmed": This is the invoice

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

account level via a dashboard

 "complete": When an invoice has the

status complete, it means that

BitPay has credited the merchant