If you would like to receive webhook notifications about the status of each recipient, you must submit a Recipient IPN within the merchant dashboard. This can be completed by the following flow: Settings > General > Payout Settings > Recipient IPN
IPN Format
Headers
Header | Value |
---|---|
Accept | application/json |
Content-Type | application/json |
Body
Name | Type |
---|---|
event
Webhook event object
|
object
|
code
See the list of available Webhook notification codes for more information
|
number
|
name
See the list of available Webhook notification codes for more information
|
string
|
data
Recipient data object.
|
object
|
email
Recipient email address
|
string
|
label
For merchant use, pass through - could be customer name or unique reference.
|
string
|
status
Recipient status, can have the following values:
|
string
|
id
Unique recipient
id assigned by BitPay for a given customer email . |
string
|
shopperId
This is the unique id assigned by BitPay if the shopper used his personal BitPay account to authenticate and pay an invoice. For customers signing up for a brand new BitPay personal account, this id will only be created as part of the payout onboarding. The same field would also be available on paid invoices if the customer signed in with his BitPay personal account before completing the payment. This can allow merchants to monitor the activity of a customer (deposits & payouts). |
string
|
{
"event": {
"code": 4003,
"name": "recipient_verified"
},
"data": {
"id":"8Gq174SFAnQpdLDxRZCBPB",
"shopperId":"5QZnQKyanj8o7qohDf2zC2",
"email":"[email protected]",
"label":"Alice",
"status":"verified",
}
}
{
"event": {
"code": 4004,
"name": "recipient_active"
},
"data": {
"id":"X3icwc4tE8KJ5hEPNPpDXW",
"shopperId":"A1G8wUmG9Br6RuNY5RTodM",
"email":"[email protected]",
"label":"Bob",
"status":"active",
}
}
Webhook Notification Codes
Codes for recipient events with webhook notifications
BitPay code | Name | Purpose |
---|---|---|
4001 | recipient_invited |
To notify merchants that a recipient has reached the status invited |
4002 | recipient_unverified |
To notify merchants that a recipient has reached the status unverified |
4003 | recipient_verified |
To notify merchants that a recipient has reached the status verified |
4004 | recipient_active |
To notify merchants that a recipient has reached the status active |
4005 | recipient_paused |
To notify merchants that a recipient has reached the status paused |
4006 | recipient_removed |
To notify merchants that a recipient has reached the status removed |
4007 | recipient_manuallyNotified |
Whenever a merchant request for the last notification to be resent (see section Request a webhook to be resent) |