Skip to main content
Event Name: fund_error
This event is triggered when a funding operation fails. This can occur due to various reasons such as insufficient funds, card issues, transaction rejected by the bank, or any other error in the funding process.

​
Event Payload

The webhook payload contains the following structure: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "fund_error",
  "timestamp": "2025-06-19T16:04:13.123Z",
  "data": {
    "method": "card",
    "source": {
      "bankAccountNumber": "ES9121000418450200051332",
      "bankRoutingType": "IBAN",
      "cardBin": "411111",
      "cardLastFour": "1111",
      "internalAccountId": "550e8400-e29b-41d4-a716-446655440002",
      "transferId": "550e8400-e29b-41d4-a716-446655440003"
    },
    "fundingId": "550e8400-e29b-41d4-a716-446655440000",
    "accountId": "550e8400-e29b-41d4-a716-446655440001",
    "reference": "PAGO-12345",
    "error": {
      "message": "Insufficient funds"
    }
  }
}

​
Field Description

​
id
string
required
Unique event identifier (UUID)
​
event
string
required
Event type - always fund_error for this webhook
​
timestamp
string
required
Event timestamp in ISO 8601 format
​
data
object
required
Contains the event data
​
data.method
string
required
Payment method used (card, bank_transfer, internal_transfer)
​
data.source
object
required
Payment origin information
​
data.source.bankAccountNumber
string
Complete bank account number (e.g., IBAN)
​
data.source.bankRoutingType
string
Bank routing type (e.g., “IBAN”, “SORT CODE”)
​
data.source.cardBin
string
First 6-8 digits of the payment card
​
data.source.cardLastFour
string
Last 4 digits of the payment card
​
data.source.internalAccountId
string
Internal account ID (UUID, for internal transfers)
​
data.source.transferId
string
Transfer reference ID (UUID)
​
data.fundingId
string
required
Unique funding operation ID (UUID)
​
data.accountId
string
required
ID of the receiving account (UUID)
​
data.reference
string
required
Reference of the payment (provided during creation)
​
data.error
object
required
Error information
​
data.error.message
string
required
Descriptive error message

​
Expected Responses

Success Response

HTTP 200 OKThe webhook was processed successfully.

Client Error

HTTP 4xx StatusClient-side error. Will not be retried.

Server Error

HTTP 5xx StatusServer-side error. Will be retried with exponential backoff.

​
Implementation Example

app.post('/webhooks/ralio', (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'fund_error') {
    const { fundingId, accountId, method, error } = data;
    
    // Process funding error
    console.log(`Funding ${fundingId} failed for account ${accountId}`);
    console.log(`Method: ${method}, Error: ${error.message}`);
    
    // Update your internal systems
    await updateFundingStatus(fundingId, 'ERROR');
    await logFundingError(fundingId, error.message);
    
    // Notify user or take appropriate action
    await notifyFundingFailure(accountId, fundingId, error.message);
    
    // Respond with success
    res.status(200).json({ received: true });
  }
});