Skip to main content

Documentation Index

Fetch the complete documentation index at: https://doc.raliopay.com/llms.txt

Use this file to discover all available pages before exploring further.

Event Name: related_party.kyc_session_created
This event is fired when the onboarding team creates a KYC verification session for a related party (Shareholder, UBO or Authorized Representative) of a business user. Use it to inform the related party — usually via email — that they need to complete the verification before the session expires. The session state at this point is always NOT_STARTED, which is reflected as KYC_PENDING on the related party.

​
Event Payload

The webhook payload contains the following structure:
Example Payload
{
  "eventId": "8fbb9c6a-1f4c-4b3f-9b4a-c0fda4c3e3a1",
  "eventType": "related_party.kyc_session_created",
  "timestamp": "2026-04-29T12:50:22.227Z",
  "data": {
    "businessUser": {
      "id": 1234,
      "name": "Acme Corp S.L."
    },
    "relatedParty": {
      "id": "f6c8c8c8-1234-4abc-9def-0123456789ab",
      "roleType": "UBO",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phoneNumber": "+34911223344",
      "nationality": "ES",
      "ownershipPercentage": 30,
      "residentialAddress": {
        "addressLine1": "123 Main Street",
        "city": "Madrid",
        "provinceState": "Madrid",
        "postalCode": "28001",
        "country": "ES"
      },
      "status": "KYC_PENDING"
    },
    "kycSession": {
      "id": "a1b2c3d4-5678-49ab-9cde-f0123456789a",
      "provider": "mati",
      "url": "https://signup.getmati.com/?merchantToken=...&flowId=...",
      "expiresAt": "2026-05-06T12:50:22.227Z"
    }
  }
}

​
Field Description

​
eventId
string
required
Unique event identifier (UUID).
​
eventType
string
required
Event type — always related_party.kyc_session_created for this webhook.
​
timestamp
string
required
Event timestamp in ISO 8601 format.
​
data
object
required
Contains the event data.
​
data.businessUser
object
required
Business user that the related party belongs to.
​
data.businessUser.id
integer
required
Internal numeric identifier of the business user.
​
data.businessUser.name
string
required
Legal name of the business user.
​
data.relatedParty
object
required
Related party for whom the KYC session was created.
​
data.relatedParty.id
string
required
Unique related party identifier (UUID).
​
data.relatedParty.roleType
string
required
Role of the related party within the business. Possible values: SHAREHOLDER, UBO, AUTHORIZED_REPRESENTATIVE.
​
data.relatedParty.firstName
string
required
Related party’s first name.
​
data.relatedParty.lastName
string
required
Related party’s last name.
​
data.relatedParty.email
string
required
Email address used to contact the related party for the verification.
​
data.relatedParty.phoneNumber
string
Related party’s phone number, when available.
​
data.relatedParty.nationality
string
required
ISO 3166-1 alpha-2 country code of the related party’s nationality.
​
data.relatedParty.ownershipPercentage
integer
Percentage of the business owned by the related party. Omitted when not applicable (e.g. authorized representatives).
​
data.relatedParty.residentialAddress
object
required
Residential address of the related party.
​
data.relatedParty.residentialAddress.addressLine1
string
required
Street address line.
​
data.relatedParty.residentialAddress.city
string
required
City.
​
data.relatedParty.residentialAddress.provinceState
string
required
Province or state.
​
data.relatedParty.residentialAddress.postalCode
string
required
Postal or ZIP code.
​
data.relatedParty.residentialAddress.country
string
required
ISO 3166-1 alpha-2 country code.
​
data.relatedParty.status
string
required
KYC status of the related party at the time the session is created. Always KYC_PENDING for this event.
​
data.kycSession
object
required
Newly created KYC session.
​
data.kycSession.id
string
required
Unique KYC session identifier (UUID).
​
data.kycSession.provider
string
required
Identity verification provider. Currently mati.
​
data.kycSession.url
string
required
Hosted URL the related party must visit to complete the verification.
​
data.kycSession.expiresAt
string
ISO 8601 timestamp at which the session expires. May be omitted when the provider does not return an expiration.

​
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', async (req, res) => {
  const { eventType, data } = req.body;

  if (eventType === 'related_party.kyc_session_created') {
    const { businessUser, relatedParty, kycSession } = data;

    console.log(
      `KYC session ${kycSession.id} created for related party ${relatedParty.id} of ${businessUser.name}`,
    );

    await sendKycInvitation({
      to: relatedParty.email,
      verificationUrl: kycSession.url,
      expiresAt: kycSession.expiresAt,
      businessName: businessUser.name,
      relatedPartyName: `${relatedParty.firstName} ${relatedParty.lastName}`,
    });

    res.status(200).json({ received: true });
  }
});