BaaS Webhooks

The B2B API offers a webhook mechanism to notify about events that occur asynchronously. For Banking as a Service (BaaS), there are two types of notifications sent via webhooks: event notifications and IPN (Instant Payment Notification) webhooks. Event notifications inform about specific actions such as verification completions or account creations, while IPN webhooks notify about transaction events like deposits and withdrawals.

Verification Submission Webhook

For the KYC flow, a notification is sent when the verification process reaches a final status: KYC.COMPLETED when the user is approved, KYC.FAILED when they are not. The payload will be as follows:

{
    "event_type": "KYC.COMPLETED",
    "issue_datetime": "2026-10-20T16:54:42.096Z",
    "payload":  {
        "submission_id": "6295fdf3-fae8-4a3f-a16b-6b43b258a6c0",
        "end_user_id": "customer_10",
        "provider_url": "https://kyc.ripio.com/?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...&id=20809&schema=B2B_AR",
        "status": "COMPLETED",
        "created_at": "2026-10-20T16:45:56.778460Z"
    }
}

Key	Type	Description
`event_type`	string	Indicate which type of event the currently sent webhook corresponds to: `KYC.COMPLETED` or `KYC.FAILED`.
`issue_datetime`	string	Indicate the datetime the webhook was sent.
`payload`	object	Payload with the information about the verification submission.
`submission_id`	string	KYC Submission unique identifier.
`end_user_id`	string	Identifier of the End User the KYC Submission belongs to.
`provider_url`	string or null	URL of Ripio’s KYC platform the user was redirected to for the ID document upload and liveness check. Null if the flow did not require that step.
`status`	string	KYC Submission status: `COMPLETED` or `FAILED`.
`created_at`	string	ISO datetime indicating Verification Submission creation date.

The same submission can produce more than one notification while the verification is in progress, with event_type KYC.IN_REVIEW. Act on KYC.COMPLETED and KYC.FAILED, and use the status of the payload as the source of truth. You can always check it with Retrieve KYC Submission.

Fiat Account Creation Webhook

In the Fiat Account creation flow, a notification will be sent once the Fiat Account creation has been completed. The payload will be as follows:

{
    "event_type": "FIAT_ACCOUNT.ENABLED",
    "issue_datetime": "2025-02-14T15:11:47.910383Z",
    "payload":  {
        "fiat_account_id": "0816ecf8-4ebc-4abb-a273-ab70bc992d1e",
        "created_at": "2025-02-14T15:11:47.910383Z",
        "payment_method_type": "bank_transfer",
        "currency": "ARS",
        "status": "ENABLED",
        "fiat_payment_instructions": {
            "cvu": "0000465160000000100092"
        },
        "end_user_id": "customer_10"
    }
}

Key	Type	Description
`event_type`	string	Indicate which type of event the currently sent webhook corresponds to, in this case `FIAT_ACCOUNT.ENABLED`
`issue_datetime`	string	Indicate the datetime the webhook was sent.
`payload`	string	Payload with the information about the enabled fiat account.
`fiat_account_id`	string	UUID4 formatted unique id.
`payment_method_type`	string	It indicates the account type. Usually `bank_transfer`.
`currency`	string	It defines the currency that the FiatAccount accepts.
`status`	string	Indicates the Fiat Account status. Only when “ENABLED”, the fiat payment instructions will be provided.
`fiat_payment_instructions`	string	JSON fields with account identification details. It varies based on the account type.
`cvu`	string	Account identifier number for AR Fiat Accounts.
`created_at`	string	ISO datetime indicating Fiat Account creation date.
`end_user_id`	string	End user’s external ref

Beneficiary Fiat Account Creation Webhook

When a beneficiary fiat account is enabled, a notification will be sent with the following structure:

{
  "event_type": "BENEFICIARY_FIAT_ACCOUNT.ENABLED",
  "issue_datetime": "2025-06-04T12:42:26.061Z",
  "payload": {
    "status": "ENABLED",
    "currency": "ARS",
    "created_at": "2025-06-04T12:42:25.816728Z",
    "end_user_id": "customer_10",
    "payment_method_type": "bank_transfer",
    "fiat_payment_instructions": {
      "cvu": "0000465160000000100092"
    },
    "beneficiary_fiat_account_id": "e7e6178a-eda7-4217-bcde-a06a1b1670fa"
  }
}

Key	Type	Description
`event_type`	string	Indicate which type of event the currently sent webhook corresponds to, in this case `BENEFICIARY_FIAT_ACCOUNT.ENABLED`
`issue_datetime`	string	Indicate the datetime the webhook was sent.
`payload`	string	Payload with the information about the enabled beneficiary fiat account.
`beneficiary_fiat_account_id`	string	UUID4 formatted unique id.
`payment_method_type`	string	It indicates the account type. Usually `bank_transfer`.
`currency`	string	It defines the currency that the Beneficiary Fiat Account accepts.
`status`	string	Indicates the Beneficiary Fiat Account status. Only when “ENABLED”, the fiat payment instructions will be provided.
`fiat_payment_instructions`	string	JSON fields with account identification details. It varies based on the account type.
`cvu`	string	Account identifier number for AR Beneficiary Fiat Accounts.
`created_at`	string	ISO datetime indicating Beneficiary Fiat Account creation date.
`end_user_id`	string	End user’s external ref

IPN Fiat Deposit Webhook

When a Fiat Deposit is credited to a specific Fiat Account, an IPN will be sent with the following structure:

{
    "message_id": "9d1f3b57-6a8c-4e0c-b4df-0f2e4a6c8b9d",
    "event_type": "FIAT_DEPOSIT.COMPLETED",
    "issue_datetime": "2025-02-14T15:11:47.910383Z",
    "payload":   {
        "id": "8142b065-79c4-4f48-9e33-11b17bc658d4",
        "created_at": "2024-04-23T14:48:33.895551Z",
        "updated_at": "2024-04-23T14:49:25.342111Z",
        "currency_code": "ARS",
        "end_user_id": "customer_10",
        "amount": "12345.67",
        "status": "COMPLETED",
        "refunded": false,
        "refund_fiat_withdrawal_id": null,
        "origin_account_identifier": "0000465160000000100092",
        "origin_account_holder_id": "20388003629",
        "origin_account_holder_name": "Carlos Pineda"
    }
}

Key	Type	Description
`message_id`	string	Unique identifier of this message. The same message delivered again on a retry, or read from the List IPN Messages endpoint, carries this same value: use it to discard duplicates.
`event_type`	string	Indicate which type of event the currently sent webhook corresponds to, in this case `FIAT_DEPOSIT.COMPLETED`
`issue_datetime`	string	Indicate the datetime the webhook was sent.
`payload`	string	Payload with the information about the completed Fiat Deposit.
`id`	string	Unique ID for this Fiat Deposit.
`created_at`	string	Indicates the creation date of the Fiat Deposit.
`updated_at`	string	Indicates the update date of the Fiat Deposit.
`currency_code`	string	Indicates the currency that has been deposited.
`end_user_id`	string	End user’s external ref, usually a UUID. Indicates the end user that has received the Fiat Deposit.
`amount`	string	Indicates the amount deposited.
`status`	string	Indicates Fiat Deposit status.
`refunded`	boolean	Indicates if the fiat deposit was refunded.
`refund_fiat_withdrawal_id`	string or null	Indicates the Fiat Withdrawal id associated with the refund, could be null.
`origin_account_identifier`	string	Indicates the identifier of the fiat deposit’s issuing account.
`origin_account_holder_id`	string	Indicates the identification of the fiat deposit’s issuing account holder.
`origin_account_holder_name`	string	Indicates the name of the fiat deposit’s issuing account holder.

If a Fiat Deposit is blocked due to limits, an IPN will be sent with the event_type value equal to: FIAT_DEPOSIT.BLOCKED_LIMIT_EXCEEDED. If a Fiat Deposit is refunded, an IPN will be sent with the following information:

{
    "message_id": "a0e2c468-7b9d-4f1d-c5ea-1a3f5b7d9c0e",
    "event_type": "FIAT_DEPOSIT.CANCELLED",
    "issue_datetime": "2025-02-14T15:11:47.910383Z",
    "payload":   {
        "id": "8142b065-79c4-4f48-9e33-11b17bc658d4",
        "created_at": "2024-04-23T14:48:33.895551Z",
        "updated_at": "2024-04-23T14:49:25.342111Z",
        "currency_code": "ARS",
        "end_user_id": "customer_10",
        "amount": "12345.67",
        "status": "CANCELLED",
        "refunded": true,
        "refund_fiat_withdrawal_id": "6f907606-14f8-421c-80e2-e9c2c777aeec",
        "origin_account_identifier": "0000465160000000100092",
        "origin_account_holder_id": "20388003629",
        "origin_account_holder_name": "Carlos Pineda"
    }
}

IPN Fiat Withdrawal Webhook

When a Fiat Withdrawal is completed, an IPN will be sent with the following structure:

{
    "message_id": "b1f3d579-8c0e-4a2e-d6fb-2b4a6c8e0d1f",
    "event_type": "FIAT_WITHDRAWAL.COMPLETED",
    "issue_datetime": "2025-02-14T15:11:47.910383Z",
    "payload":   {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "transaction_id": "0fec1e58-b197-4052-99cf-2218496c5482",
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:18:22Z",
        "end_user_id": "customer_10",
        "amount": "12345.67",
        "status": "COMPLETED",
        "external_ref": "ac243840-ac04-4b3a-9efb-176554d4a029",
        "beneficiary_fiat_account_id": "4123e456-e89b-12d3-a456-4bedc4266abc",
        "is_fiat_deposit_refund": false,
        "refunded_fiat_deposit": null
    }
}

Key	Type	Description
`message_id`	string	Unique identifier of this message. The same message delivered again on a retry, or read from the List IPN Messages endpoint, carries this same value: use it to discard duplicates.
`event_type`	string	Indicate which type of event the currently sent webhook corresponds to, in this case `FIAT_WITHDRAWAL.COMPLETED`
`issue_datetime`	string	Indicate the datetime the webhook was sent.
`payload`	string	Payload with the information about the completed Fiat Withdrawal.
`id`	string	UUID used as Fiat Withdrawal identifier.
`created_at`	string	Indicates the creation date of the Fiat Withdrawal.
`updated_at`	string	Indicates the update date of the Fiat Withdrawal.
`currency_code`	string	Indicates the asset name involved in the Fiat Withdrawal.
`end_user_id`	string	End user’s external ref, usually a UUID. Identifies the user that owns this operation.
`amount`	string	Indicates the fiat amount withdrawed.
`status`	string	Specifies the Fiat Withdrawal status.
`external_ref`	string	Client side identification reference. Usually a UUID.
`beneficiary_fiat_account_id`	string or null	Indicates the Fiat Withdrawal id associated with the refund, could be null.
`is_fiat_deposit_refund`	boolean	Indicates the identifier of the fiat deposit’s issuing account.
`refunded_fiat_deposit`	string	Indicates the identification of the fiat deposit’s issuing account holder.

If a Fiat Withdrawal is not completed due to an external issue, it will remain in a CANCELLED state, and an IPN will be sent with event_type equal to: FIAT_WITHDRAWAL.CANCELLED. When a Fiat Withdrawal is created, it will be in a PENDING status, and an IPN will be sent with event_type equal to: FIAT_WITHDRAWAL.PENDING.

Overview

Crypto Widget

API Integration

Verification Submission Webhook

Fiat Account Creation Webhook

Beneficiary Fiat Account Creation Webhook

IPN Fiat Deposit Webhook

IPN Fiat Withdrawal Webhook

​Verification Submission Webhook

​Fiat Account Creation Webhook

​Beneficiary Fiat Account Creation Webhook

​IPN Fiat Deposit Webhook

​IPN Fiat Withdrawal Webhook

Verification Submission Webhook

Fiat Account Creation Webhook

Beneficiary Fiat Account Creation Webhook

IPN Fiat Deposit Webhook

IPN Fiat Withdrawal Webhook