Webhook Events

curl --request GET \
  --url https://api.vitawallet.io/api/businesses/events \
  --header 'Authorization: <api-key>' \
  --header 'x-date: <api-key>' \
  --header 'x-login: <api-key>' \
  --header 'x-trans-key: <api-key>'

import requests

url = "https://api.vitawallet.io/api/businesses/events"

headers = {
    "x-login": "<api-key>",
    "x-trans-key": "<api-key>",
    "x-date": "<api-key>",
    "Authorization": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'x-login': '<api-key>',
    'x-trans-key': '<api-key>',
    'x-date': '<api-key>',
    Authorization: '<api-key>'
  }
};

fetch('https://api.vitawallet.io/api/businesses/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vitawallet.io/api/businesses/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "x-date: <api-key>",
    "x-login: <api-key>",
    "x-trans-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vitawallet.io/api/businesses/events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-login", "<api-key>")
	req.Header.Add("x-trans-key", "<api-key>")
	req.Header.Add("x-date", "<api-key>")
	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.vitawallet.io/api/businesses/events")
  .header("x-login", "<api-key>")
  .header("x-trans-key", "<api-key>")
  .header("x-date", "<api-key>")
  .header("Authorization", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vitawallet.io/api/businesses/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-login"] = '<api-key>'
request["x-trans-key"] = '<api-key>'
request["x-date"] = '<api-key>'
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "events": [
    {
      "id": "f339fbfa-a0b2-4180-a34a-176333ae7334",
      "event_type": "transaction.time_out",
      "status": "sent",
      "payload": {
        "id": "8b67895b-c612-4ad5-ab30-643fa5d5d6ea",
        "total": 20250,
        "amount": 20000,
        "status": "time_out",
        "category": "deposit",
        "currency": "clp",
        "fee_type": "percentage",
        "fee_value": 1.25,
        "total_fee": 250,
        "created_at": "2025-07-16T22:44:46.271Z"
      },
      "attempts": 1,
      "created_at": "2026-01-09T19:52:37.116Z",
      "updated_at": "2026-01-09T19:52:42.569Z",
      "sent_at": "2026-01-09T19:52:42.568Z"
    },
    {
      "id": "822aca65-3b54-4c8b-8e90-e108cf47743e",
      "event_type": "transaction.time_out",
      "status": "sent",
      "payload": {
        "id": "8b67895b-c612-4ad5-ab30-643fa5d5d6ea",
        "total": 20250,
        "amount": 20000,
        "status": "time_out",
        "category": "deposit",
        "currency": "clp",
        "fee_type": "percentage",
        "fee_value": 1.25,
        "total_fee": 250,
        "created_at": "2025-07-16T22:44:46.271Z"
      },
      "attempts": 1,
      "created_at": "2026-01-09T19:28:15.861Z",
      "updated_at": "2026-01-09T19:29:07.942Z",
      "sent_at": "2026-01-09T19:29:07.942Z"
    },
    {
      "id": "ff83166c-7f4b-46fd-bd86-484ee11ed1d7",
      "event_type": "transaction.time_out",
      "status": "sent",
      "payload": {
        "id": "8b67895b-c612-4ad5-ab30-643fa5d5d6ea",
        "total": 20250,
        "amount": 20000,
        "status": "time_out",
        "category": "deposit",
        "currency": "clp",
        "fee_type": "percentage",
        "fee_value": 1.25,
        "total_fee": 250,
        "created_at": "2025-07-16T22:44:46.271Z"
      },
      "attempts": 1,
      "created_at": "2026-01-09T19:27:38.343Z",
      "updated_at": "2026-01-09T19:29:07.297Z",
      "sent_at": "2026-01-09T19:29:07.281Z"
    },
    {
      "id": "9f4b8ec6-d243-48d9-aaf6-077bafb4bc35",
      "event_type": "transaction.time_out",
      "status": "processing",
      "payload": {
        "id": "8b67895b-c612-4ad5-ab30-643fa5d5d6ea",
        "total": 20250,
        "amount": 20000,
        "status": "time_out",
        "category": "deposit",
        "currency": "clp",
        "fee_type": "percentage",
        "fee_value": 1.25,
        "total_fee": 250,
        "created_at": "2025-07-16T22:44:46.271Z"
      },
      "attempts": 0,
      "created_at": "2026-01-09T19:25:21.613Z",
      "updated_at": "2026-01-09T19:25:21.613Z",
      "sent_at": null
    },
    {
      "id": "7a2bdd0c-b9ba-459f-90d2-608511239a29",
      "event_type": "transaction.time_out",
      "status": "processing",
      "payload": {
        "id": "8b67895b-c612-4ad5-ab30-643fa5d5d6ea",
        "total": 20250,
        "amount": 20000,
        "status": "time_out",
        "category": "deposit",
        "currency": "clp",
        "fee_type": "percentage",
        "fee_value": 1.25,
        "total_fee": 250,
        "created_at": "2025-07-16T22:44:46.271Z"
      },
      "attempts": 0,
      "created_at": "2026-01-09T19:24:26.582Z",
      "updated_at": "2026-01-09T19:24:26.582Z",
      "sent_at": null
    },
    {
      "id": "3a09985c-1a1f-4de0-a74e-ca60b9ceaecf",
      "event_type": "transaction.time_out",
      "status": "processing",
      "payload": {
        "id": "8b67895b-c612-4ad5-ab30-643fa5d5d6ea",
        "total": 20250,
        "amount": 20000,
        "status": "time_out",
        "category": "deposit",
        "currency": "clp",
        "fee_type": "percentage",
        "fee_value": 1.25,
        "total_fee": 250,
        "created_at": "2025-07-16T22:44:46.271Z"
      },
      "attempts": 0,
      "created_at": "2026-01-09T19:23:26.359Z",
      "updated_at": "2026-01-09T19:23:26.359Z",
      "sent_at": null
    },
    {
      "id": "1dbaf13a-4d2b-41a7-af06-a75a1361c10c",
      "event_type": "transaction.time_out",
      "status": "processing",
      "payload": {
        "id": "8b67895b-c612-4ad5-ab30-643fa5d5d6ea",
        "total": 20250,
        "amount": 20000,
        "status": "time_out",
        "category": "deposit",
        "currency": "clp",
        "fee_type": "percentage",
        "fee_value": 1.25,
        "total_fee": 250,
        "created_at": "2025-07-16T22:44:46.271Z"
      },
      "attempts": 0,
      "created_at": "2026-01-09T19:22:09.244Z",
      "updated_at": "2026-01-09T19:22:09.244Z",
      "sent_at": null
    },
    {
      "id": "30de59b6-91ea-4a1d-b3a0-b7cec64694be",
      "event_type": "transaction.time_out",
      "status": "processing",
      "payload": {
        "id": "8b67895b-c612-4ad5-ab30-643fa5d5d6ea",
        "total": 20250,
        "amount": 20000,
        "status": "time_out",
        "category": "deposit",
        "currency": "clp",
        "fee_type": "percentage",
        "fee_value": 1.25,
        "total_fee": 250,
        "created_at": "2025-07-16T22:44:46.271Z"
      },
      "attempts": 0,
      "created_at": "2026-01-09T19:15:47.568Z",
      "updated_at": "2026-01-09T19:15:47.568Z",
      "sent_at": null
    }
  ],
  "total": 8,
  "limit": 10
}

Webhooks

Webhook Events

Retrieves the 10 most recent events generated for your business account, ordered by creation date in descending order. Each event includes the transaction payload, delivery status, attempt history, and the server response received from your endpoint.

Use this endpoint to:

Debug webhook delivery issues by inspecting which events failed and why.
Audit recent activity to verify that your server is correctly receiving and acknowledging events.
Validate integration health by confirming that the event types and payloads match your handlers.

Response Structure

Field	Type	Description
`events`	Array	List of events (maximum 10).
`total`	Integer	Total number of events available for the business.
`limit`	Integer	Limit of events returned per response (always 10).

Event Object

Field	Type	Description
`id`	string	Unique identifier of the event. Opaque text identifier — do not validate as a UUID.
`event_type`	string	Type of event (e.g., `transaction.completed`, `transaction.failed`).
`status`	string	Delivery status: `pending`, `processing`, `sent`, `failed`, `expired`.
`payload`	object	Event data (structure depends on the transaction category).
`attempts`	integer	Number of delivery attempts made.
`created_at`	string (ISO 8601)	Event creation timestamp.
`next_retry_at`	string (ISO 8601)	null
`sent_at`	string (ISO 8601)	null
`server_response`	string	null

Delivery and Retry Policy

Only an HTTP 200 response from your server counts as a successful delivery. Other 2xx codes (201, 202, 204, etc.) are not treated as success and will trigger a retry — respond with exactly 200.
Failed deliveries are retried up to 5 times, with increasing delays between attempts: 1 minute, 5 minutes, 15 minutes, 1 hour, 6 hours. After the 5th failed attempt, the event’s status becomes failed.
Events that remain undelivered for more than 30 days are marked expired.

Event Payload Structure

The contents of the payload field vary by transaction category. The base attributes below are included in all transaction event payloads, regardless of category.

Base Attributes (All Categories)

Field	Type	Description
`id`	string	Transaction identifier. Opaque text identifier — most real values include a numeric suffix (e.g. `...-24544`); do not validate as a UUID.
`order`	string	null
`category`	string	Transaction category (`deposit`, `payment`, `sent`, `received`, `exchange`, `fee`, etc.).
`status`	string	Transaction status (`started`, `completed`, `pending`, `denied`, `processed`, `failed`, `time_out`, `checking`).
`amount`	string (decimal)	Transaction amount (before fees), sent as a quoted string, e.g. `"789000.0"` — not a JSON number.
`total`	string (decimal)	Total transaction amount (including fees), also sent as a string.
`currency`	string	Currency code (`eth`, `btc`, `clp`, `usd`, `cop`, `usdt`, `usdc`, `ars`, `mxn`, `brl`, `eur`).
`created_at`	string (ISO 8601)	Transaction creation timestamp.
`description`	string	Transaction description.
`statuses`	Array	Transaction status history (see below).

Status History Object

Each entry in the statuses array describes a status change in the transaction’s lifecycle.

Field	Type	Description
`status`	string	Status value at this point in time.
`created_at`	string (ISO 8601)	When this status was set.
`description`	string	Description of the status change.
`transaction_operation_type`	string	Type of operation that caused this status change.

Category-Specific Attributes

In addition to base attributes, each category may include extra fields specific to its nature.

Category: `deposit`

Field	Type	Description
`funding_source__user_name`	string	null
`funding_source__user_document_type`	string	null
`funding_source__user_document_number`	string	null
`funding_source__user_email`	string	null
`funding_source__account`	string	null
`funding_source__ID_provider`	string	null
`total_fee`	decimal	null
`fee_value`	decimal	null
`fee_type`	string	null

Funding source fields are populated whenever the payment provider reports payer data — this is not limited to any specific provider. If a given provider doesn’t report this data, the corresponding funding_source__* fields will be null. Fee fields are always included but may be null when no fees apply.

Category: `payment`

Field	Type	Description
`funding_source__user_name`	string	null
`funding_source__user_document_number`	string	null
`funding_source__user_email`	string	null
`funding_source__account`	string	null
`funding_source__ID_provider`	string	null
`spread`	decimal	null
`fixed_cost`	decimal	null
`country_code`	string	null

Payment data is retrieved from the associated PaymentOrder using the business_order field. If business_order is missing or the PaymentOrder is not found, all payment-specific fields will be null. Remember: you only receive payment category transaction events (and payment_order.* / payment_order_attempt.* events) if you are subscribed to the payment category.

Category: `sent`

Used for outgoing transfers.

Field	Type	Description
`hash_result`	string	null
`from_address`	string	null
`to_address`	string	null
`network_name`	string	null
`total_fee`	decimal	null
`fee_value`	decimal	null
`fee_type`	string	null

Hash and address fields are blockchain-specific and may be null for non-crypto transactions.

Category: `received`

Used for incoming transfers. Same structure as sent.

Field	Type	Description
`hash_result`	string	null
`from_address`	string	null
`to_address`	string	null
`network_name`	string	null
`total_fee`	decimal	null
`fee_value`	decimal	null
`fee_type`	string	null

Category: `exchange`

Used for currency conversions.

Field	Type	Description
`hash_result`	string	null
`total_fee`	decimal	null
`fee_value`	decimal	null
`fee_type`	string	null

Category: `fee` (and other categories)

Used for fee transactions and any other categories not explicitly handled.

Field	Type	Description
`total_fee`	decimal	null
`fee_value`	decimal	null
`fee_type`	string	null

Categories such as withdrawal, transfer, vita_card, tax, cash_back_coupon, service_payment, adjustment, and similar will return only the base attributes plus these fee attributes.

GET

api

businesses

events

Webhook Events

curl --request GET \
  --url https://api.vitawallet.io/api/businesses/events \
  --header 'Authorization: <api-key>' \
  --header 'x-date: <api-key>' \
  --header 'x-login: <api-key>' \
  --header 'x-trans-key: <api-key>'

import requests

url = "https://api.vitawallet.io/api/businesses/events"

headers = {
    "x-login": "<api-key>",
    "x-trans-key": "<api-key>",
    "x-date": "<api-key>",
    "Authorization": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'x-login': '<api-key>',
    'x-trans-key': '<api-key>',
    'x-date': '<api-key>',
    Authorization: '<api-key>'
  }
};

fetch('https://api.vitawallet.io/api/businesses/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vitawallet.io/api/businesses/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "x-date: <api-key>",
    "x-login: <api-key>",
    "x-trans-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vitawallet.io/api/businesses/events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-login", "<api-key>")
	req.Header.Add("x-trans-key", "<api-key>")
	req.Header.Add("x-date", "<api-key>")
	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.vitawallet.io/api/businesses/events")
  .header("x-login", "<api-key>")
  .header("x-trans-key", "<api-key>")
  .header("x-date", "<api-key>")
  .header("Authorization", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vitawallet.io/api/businesses/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-login"] = '<api-key>'
request["x-trans-key"] = '<api-key>'
request["x-date"] = '<api-key>'
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "events": [
    {
      "id": "f339fbfa-a0b2-4180-a34a-176333ae7334",
      "event_type": "transaction.time_out",
      "status": "sent",
      "payload": {
        "id": "8b67895b-c612-4ad5-ab30-643fa5d5d6ea",
        "total": 20250,
        "amount": 20000,
        "status": "time_out",
        "category": "deposit",
        "currency": "clp",
        "fee_type": "percentage",
        "fee_value": 1.25,
        "total_fee": 250,
        "created_at": "2025-07-16T22:44:46.271Z"
      },
      "attempts": 1,
      "created_at": "2026-01-09T19:52:37.116Z",
      "updated_at": "2026-01-09T19:52:42.569Z",
      "sent_at": "2026-01-09T19:52:42.568Z"
    },
    {
      "id": "822aca65-3b54-4c8b-8e90-e108cf47743e",
      "event_type": "transaction.time_out",
      "status": "sent",
      "payload": {
        "id": "8b67895b-c612-4ad5-ab30-643fa5d5d6ea",
        "total": 20250,
        "amount": 20000,
        "status": "time_out",
        "category": "deposit",
        "currency": "clp",
        "fee_type": "percentage",
        "fee_value": 1.25,
        "total_fee": 250,
        "created_at": "2025-07-16T22:44:46.271Z"
      },
      "attempts": 1,
      "created_at": "2026-01-09T19:28:15.861Z",
      "updated_at": "2026-01-09T19:29:07.942Z",
      "sent_at": "2026-01-09T19:29:07.942Z"
    },
    {
      "id": "ff83166c-7f4b-46fd-bd86-484ee11ed1d7",
      "event_type": "transaction.time_out",
      "status": "sent",
      "payload": {
        "id": "8b67895b-c612-4ad5-ab30-643fa5d5d6ea",
        "total": 20250,
        "amount": 20000,
        "status": "time_out",
        "category": "deposit",
        "currency": "clp",
        "fee_type": "percentage",
        "fee_value": 1.25,
        "total_fee": 250,
        "created_at": "2025-07-16T22:44:46.271Z"
      },
      "attempts": 1,
      "created_at": "2026-01-09T19:27:38.343Z",
      "updated_at": "2026-01-09T19:29:07.297Z",
      "sent_at": "2026-01-09T19:29:07.281Z"
    },
    {
      "id": "9f4b8ec6-d243-48d9-aaf6-077bafb4bc35",
      "event_type": "transaction.time_out",
      "status": "processing",
      "payload": {
        "id": "8b67895b-c612-4ad5-ab30-643fa5d5d6ea",
        "total": 20250,
        "amount": 20000,
        "status": "time_out",
        "category": "deposit",
        "currency": "clp",
        "fee_type": "percentage",
        "fee_value": 1.25,
        "total_fee": 250,
        "created_at": "2025-07-16T22:44:46.271Z"
      },
      "attempts": 0,
      "created_at": "2026-01-09T19:25:21.613Z",
      "updated_at": "2026-01-09T19:25:21.613Z",
      "sent_at": null
    },
    {
      "id": "7a2bdd0c-b9ba-459f-90d2-608511239a29",
      "event_type": "transaction.time_out",
      "status": "processing",
      "payload": {
        "id": "8b67895b-c612-4ad5-ab30-643fa5d5d6ea",
        "total": 20250,
        "amount": 20000,
        "status": "time_out",
        "category": "deposit",
        "currency": "clp",
        "fee_type": "percentage",
        "fee_value": 1.25,
        "total_fee": 250,
        "created_at": "2025-07-16T22:44:46.271Z"
      },
      "attempts": 0,
      "created_at": "2026-01-09T19:24:26.582Z",
      "updated_at": "2026-01-09T19:24:26.582Z",
      "sent_at": null
    },
    {
      "id": "3a09985c-1a1f-4de0-a74e-ca60b9ceaecf",
      "event_type": "transaction.time_out",
      "status": "processing",
      "payload": {
        "id": "8b67895b-c612-4ad5-ab30-643fa5d5d6ea",
        "total": 20250,
        "amount": 20000,
        "status": "time_out",
        "category": "deposit",
        "currency": "clp",
        "fee_type": "percentage",
        "fee_value": 1.25,
        "total_fee": 250,
        "created_at": "2025-07-16T22:44:46.271Z"
      },
      "attempts": 0,
      "created_at": "2026-01-09T19:23:26.359Z",
      "updated_at": "2026-01-09T19:23:26.359Z",
      "sent_at": null
    },
    {
      "id": "1dbaf13a-4d2b-41a7-af06-a75a1361c10c",
      "event_type": "transaction.time_out",
      "status": "processing",
      "payload": {
        "id": "8b67895b-c612-4ad5-ab30-643fa5d5d6ea",
        "total": 20250,
        "amount": 20000,
        "status": "time_out",
        "category": "deposit",
        "currency": "clp",
        "fee_type": "percentage",
        "fee_value": 1.25,
        "total_fee": 250,
        "created_at": "2025-07-16T22:44:46.271Z"
      },
      "attempts": 0,
      "created_at": "2026-01-09T19:22:09.244Z",
      "updated_at": "2026-01-09T19:22:09.244Z",
      "sent_at": null
    },
    {
      "id": "30de59b6-91ea-4a1d-b3a0-b7cec64694be",
      "event_type": "transaction.time_out",
      "status": "processing",
      "payload": {
        "id": "8b67895b-c612-4ad5-ab30-643fa5d5d6ea",
        "total": 20250,
        "amount": 20000,
        "status": "time_out",
        "category": "deposit",
        "currency": "clp",
        "fee_type": "percentage",
        "fee_value": 1.25,
        "total_fee": 250,
        "created_at": "2025-07-16T22:44:46.271Z"
      },
      "attempts": 0,
      "created_at": "2026-01-09T19:15:47.568Z",
      "updated_at": "2026-01-09T19:15:47.568Z",
      "sent_at": null
    }
  ],
  "total": 8,
  "limit": 10
}

Authorizations

Business xLogin

x-trans-key

string

header

required

Business xTransKey

x-date

string

header

required

ISO8601 datetime

Authorization

string

header

required

V2-HMAC-SHA256 signature. Example: V2-HMAC-SHA256, Signature: <hash>

Response

200 - application/json

Successful response.

Payins

Exchange

Payouts

Transactions

Users

Webhooks

Webhook Events

Response Structure

Event Object

Delivery and Retry Policy

Event Payload Structure

Base Attributes (All Categories)

Status History Object

Category-Specific Attributes

Category: `deposit`

Category: `payment`

Category: `sent`

Category: `received`

Category: `exchange`

Category: `fee` (and other categories)

Authorizations

Response