Skip to main content

​
Introduction to Account Webhooks

Ripio uses webhooks to notify your application when a customer account changes state. By subscribing to these events, you can react in real time to account lifecycle transitions — for example, learning when a customer’s deposit account is ready to receive funds, or when a customer has been deactivated. Account events cover two parts of the lifecycle:
  • Deposit account readiness (ACCOUNT.PROCESSING, ACCOUNT.ENABLED, ACCOUNT.DISABLED) — emitted while a customer’s fiat deposit account is being prepared, once it becomes ready to operate, and if it later can no longer be operated. These let you react to the account’s usability without polling the API after creation.
  • Account closure (ACCOUNT.CLOSED) — emitted when a customer is deactivated, either from the Ripio partner dashboard or via the Deactivate Customer endpoint.
All account events are sent as POST requests to your configured webhook endpoint. Remember to validate the signature of each incoming webhook as described in the Webhooks Introduction.

​
Event Payload Structure

Each Account event notification contains a JSON-formatted payload with the following top-level structure: 
{
  "eventType": "ACCOUNT.ENABLED",
  "issueDatetime": "2026-05-19T14:30:00.000Z",
  "account": {
    // Fields specific to the event type (see below)
  }
}
  • eventType (String): The specific type of Account event that occurred, following the format ACCOUNT.<STATUS>.
  • issueDatetime (String): UTC timestamp indicating when the event was triggered.
  • account (Object): An object containing details of the account associated with the event. Its fields vary depending on the eventType — see each event type below.

​
Account Event Types

The following event types are available for account lifecycle changes:

​
ACCOUNT.PROCESSING

  • Description: Sent when a customer’s fiat deposit account has been created and is being prepared. For some payment methods the deposit instructions (e.g. the deposit key/identifier) are assigned asynchronously and are not yet available at this point — an ACCOUNT.ENABLED event follows once they are. For payment methods where the account is usable immediately, this event is followed right away by ACCOUNT.ENABLED.
  • account object includes:
{
  "eventType": "ACCOUNT.PROCESSING",
  "issueDatetime": "2026-05-19T14:30:00.000Z",
  "account": {
    "customerId": "7142b065-79c4-4f48-9e33-11b23bg689e2",
    "paymentMethodType": "breb",
    "fiatPaymentInstructions": {
      "brebKey": null,
      "status": "processing"
    }
  }
}

​
ACCOUNT.ENABLED

  • Description: Sent when a customer’s fiat deposit account becomes ready to operate. The fiatPaymentInstructions now carry the deposit details the end user needs to fund an on-ramp order, so you do not need to poll the API after creating the account.
  • account object includes:
{
  "eventType": "ACCOUNT.ENABLED",
  "issueDatetime": "2026-05-19T14:30:05.000Z",
  "account": {
    "customerId": "7142b065-79c4-4f48-9e33-11b23bg689e2",
    "paymentMethodType": "bank_transfer",
    "fiatPaymentInstructions": {
      "cvu": "0000465160000000070078",
      "status": "enabled"
    }
  }
}

​
ACCOUNT.DISABLED

  • Description: Sent when a customer’s fiat deposit account becomes disabled and can no longer be operated. After this event the account should not be used for new on-ramp orders.
  • account object includes:
{
  "eventType": "ACCOUNT.DISABLED",
  "issueDatetime": "2026-05-19T14:30:10.000Z",
  "account": {
    "customerId": "7142b065-79c4-4f48-9e33-11b23bg689e2",
    "paymentMethodType": "bank_transfer",
    "fiatPaymentInstructions": {
      "cvu": "0000465160000000070078",
      "status": "disabled"
    }
  }
}

​
Payload fields (ACCOUNT.PROCESSING / ACCOUNT.ENABLED / ACCOUNT.DISABLED)

The account object contains the following fields:
  • customerId (String, UUID): Your partner-facing customer ID for the affected customer.
  • paymentMethodType (String): The payment method the deposit account is for (e.g. bank_transfer, breb).
  • fiatPaymentInstructions (Object): The deposit instructions for the account. Its structure matches the fiatPaymentInstructions returned by the on-ramp session and order endpoints, and always includes a status field:
    • status (String): processing while the account is being prepared, enabled once it is ready to operate, disabled if it can no longer be operated.
    • While status is processing, the deposit key/identifier (e.g. brebKey, clabe, cvu) may be null; it is populated once the account is enabled.
These events are only emitted for payment methods backed by a persistent fiat deposit account. Payment methods that generate a one-off payment request per order do not produce account readiness events.

​
ACCOUNT.CLOSED

  • Description: Sent when a customer account has been deactivated. After this event, all operations on the customer’s resources (KYC submissions, fiat accounts, on-ramp and off-ramp sessions and orders) will return 404. The account deactivation is irreversible — there is no reactivation endpoint.
  • account object includes:
{
  "eventType": "ACCOUNT.CLOSED",
  "issueDatetime": "2026-05-19T14:30:00.000Z",
  "account": {
    "customerId": "7142b065-79c4-4f48-9e33-11b23bg689e2",
    "isActive": false
  }
}

​
Payload fields (ACCOUNT.CLOSED)

The account object contains the following fields:
  • customerId (String, UUID): Your partner-facing customer ID for the affected customer.
  • isActive (Boolean): The new active state of the customer. Always false for ACCOUNT.CLOSED events.