Jump to Content

Recipients

Recipient webhook events notify your application when a recipient's compliance review status changes, including automatic approval and approval or rejection through the compliance review process.

Events

Event Name	Status	Description
`recipient.approved`	success	Recipient approved automatically or through compliance review
`recipient.rejected`	blocked	Recipient rejected through compliance review

recipient.approved

Triggered when a recipient is approved, either automatically or through compliance review. Check each associated bank account's status separately before using it for a withdrawal.

Payload

{
  "event_name": "recipient.approved",
  "resource": {
    "type": "recipients",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "idempotency_key": "678160c6-ca41-40ee-bfe7-35057ade157d"
  },
  "data": {
    "status": "success",
    "customer_id": "cus_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "account_id": "BZ-ABCD-1234",
    "recipient_id": "550e8400-e29b-41d4-a716-446655440000",
    "business_type": "INDIVIDUAL",
    "full_name": "John Doe",
    "nickname": "John's Business",
    "email": "[email protected]",
    "relationship": "CUSTOMER",
    "address": {
      "country_code": "USA",
      "address_line1": "123 Main St",
      "address_line2": null,
      "city": "New York",
      "region": "NY",
      "postal_code": "10001"
    },
    "created_at": "2024-01-22T12:00:00.000Z",
    "modified_at": "2024-01-22T12:30:00.000Z"
  }
}

Fields

Field	Type	Description
`status`	string	Always `"success"` for this event
`customer_id`	string	The customer (portfolio) ID that owns this recipient
`account_id`	string \| null	Account ID of the customer, or `null` when unavailable
`recipient_id`	string	Unique identifier for the recipient
`business_type`	string	`"INDIVIDUAL"` or `"COMPANY"`
`full_name`	string	Full name of the recipient (first + last for individual, company name for company)
`nickname`	string/null	User-defined nickname, or `null` if not set
`email`	string/null	Email address, or `null` if not set
`relationship`	string/null	Relationship to the customer (e.g., `"CUSTOMER"`, `"VENDOR"`, `"EMPLOYEE"`)
`address`	object/null	Recipient address details, or `null` if not provided
`address.country_code`	string	ISO 3166-1 alpha-3 country code (e.g., `"USA"`)
`address.address_line1`	string	Primary address line
`address.address_line2`	string/null	Secondary address line
`address.city`	string	City name
`address.region`	string/null	State or region
`address.postal_code`	string	Postal or ZIP code
`created_at`	string	ISO 8601 timestamp of when the recipient was created
`modified_at`	string	ISO 8601 timestamp of the last modification

recipient.rejected

Triggered when a recipient is rejected during compliance review. A rejected recipient cannot be used for transactions, and any associated bank accounts will be marked as failed.

Payload

{
  "event_name": "recipient.rejected",
  "resource": {
    "type": "recipients",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "idempotency_key": "678160c6-ca41-40ee-bfe7-35057ade157d"
  },
  "data": {
    "status": "blocked",
    "customer_id": "cus_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "account_id": "BZ-ABCD-1234",
    "recipient_id": "550e8400-e29b-41d4-a716-446655440000",
    "business_type": "INDIVIDUAL",
    "full_name": "John Doe",
    "nickname": "John's Business",
    "email": "[email protected]",
    "relationship": "OTHER",
    "address": {
      "country_code": "USA",
      "address_line1": "123 Main St",
      "address_line2": null,
      "city": "New York",
      "region": "NY",
      "postal_code": "10001"
    },
    "created_at": "2024-01-22T12:00:00.000Z",
    "modified_at": "2024-01-22T14:00:00.000Z"
  }
}

Fields

Field	Type	Description
`status`	string	Always `"blocked"` for this event
`customer_id`	string	The customer (portfolio) ID that owns this recipient
`account_id`	string \| null	Account ID of the customer, or `null` when unavailable
`recipient_id`	string	Unique identifier for the recipient
`business_type`	string	`"INDIVIDUAL"` or `"COMPANY"`
`full_name`	string	Full name of the recipient
`nickname`	string/null	User-defined nickname, or `null` if not set
`email`	string/null	Email address, or `null` if not set
`relationship`	string/null	Relationship to the customer
`address`	object/null	Recipient address details, or `null` if not provided
`created_at`	string	ISO 8601 timestamp of when the recipient was created
`modified_at`	string	ISO 8601 timestamp reflecting when the rejection occurred

Common Rejection Reasons

Compliance restrictions based on recipient relationship type
Suspicious recipient activity patterns
Recipient count threshold exceeded for the customer account