API & SDK Documentation

Recipients

📘

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

HeaderValue
Acceptapplication/json
Content-Typeapplication/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:

  • invited
  • unverified
  • verified
  • active
  • paused
  • removed

 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)