Jump to Content

Recipients

Recipient webhook events notify your application when a recipient's compliance review status changes. These events are triggered after an admin approves or rejects a recipient through the compliance review process.

Events

Event Name	Status	Description
`recipient.approved`	APPROVED	Recipient has been approved by compliance review
`recipient.rejected`	REJECTED	Recipient has been rejected by compliance review

recipient.approved

Triggered when a recipient passes compliance review and is approved for use. After approval, the recipient's associated bank accounts will be submitted to the payment vendor for verification.

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	Account ID of the customer
`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	Account ID of the customer
`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