Webhooks Event types

Once a payment link is created and the US sender (User) begins the payment process, your registered webhook URL will start receiving real-time updates. These webhook events allow your system to stay synchronized with each stage of the transaction from creation to payout.

Webhooks Sequence

sequenceDiagram
    participant Sender as EE.UU. Sender
    participant Kira as Kira
    participant Webhook as Kira Client webhook URL

    Note over Sender, Webhook: User Creation & KYC Verification
    
    Sender->>Kira: Completes Payment Link<br/>KYC verification
    Kira->>Webhook: Event: user.created
    Kira->>Webhook: Event: user.verification.accepted

    Note over Sender, Webhook: Payment
    
    Sender->>Kira: Completes payment via the<br/>Payment Link using card or cash.
    Kira->>Webhook: Event: card_payment /<br/>barcode_generated

    Note over Sender, Webhook: Payout
    
    Kira->>Webhook: Event: transaction_update

Step 1: User Creation & KYC Verification Webhooks

Before the US sender can complete a payment, they must first be onboarded as a user and go through identity verification (KYC). The following webhook events are sent to your system to track this process.

1.1 user.created

Sent right after a user is created. Initially, the user will be marked as "unverified".

Body Schema

User Creation Event

{
  "event": "user.created",
  "data": {
    "type": "individual",
    "email": "[email protected]",
    "phone": "+15550000000",
    "status": "active",
    "user_id": "00000000-0000-0000-0000-000000000000",
    "event_id": "11111111-1111-1111-1111-111111111111",
    "metadata": {
      "ip_address": "192.0.2.123",
      "ext_reference": "YOUR_INTERNAL_REFERENCE"
    },
    "created_at": "2025-09-23T18:09:05.017Z",
    "verification_status": "unverified"
  }
}

1.2 user.verification.accepted

Sent when the user completes identity verification. This webhook may be triggered twice:

• Once for kyc_type: simplified or full
• Again (if applicable) for kyc_type: full

Body Schema

User Verification Event

{
  "event": "user.verification.accepted",
  "data": {
    "id": "22222222-2222-2222-2222-222222222222",
    "kyc_type": "simplified",
    "user_id": "00000000-0000-0000-0000-000000000000",
    "event_id": "33333333-3333-3333-3333-333333333333",
    "verification_status": "verified"
  }
}

Step 2: Payment Webhooks

Once a payment is initiated via a Payment Link, your system will receive real-time webhook updates according to the payment method used and status progression.

This section describes the expected webhook events for:

• Card Payments
• Cash Deposits

2.1 card_payment

This flow is triggered when the sender chooses to pay using a card.

Body Schema

Card Payment Event

{
  "event": "card_payment",
  "data": {
    "pct_fee": "0.0100",
    "user_id": "00000000-0000-0000-0000-000000000000",
    "event_id": "11111111-2222-3333-4444-555555555555",
    "metadata": {
      "rate": "0.0000",
      "quote_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "fixed_fee": "0.00",
      "balam_rate": "0.0000",
      "pct_fx_fee": "0.000",
      "quote_amount": "0.00"
    },
    "requestid": "",
    "base_amount": "0.00",
    "client_uuid": "12345678-1234-1234-1234-123456789abc",
    "referenceid": "YOUR_INTERNAL_REFERENCE",
    "recipient_id": "ffffffff-eeee-dddd-cccc-bbbbbbbbbbbb",
    "base_currency": "USD",
    "quote_currency": "USD",
    "card_request_id": "99999999-8888-7777-6666-555555555555",
    "payment_link_id": "44444444-3333-2222-1111-000000000000",
    "card_request_status": "CREATED"
  }
}

2.2 barcode_generated

This flow is triggered when the sender chooses to pay in cash using a barcode.

Body Schema

Allowed values: MXN, COP, USDC, PEN, PAUSD, ARS, CLP, ECUSD, UYU, PYG, CRC, BRL, DOP, USD, GTQ, PEUSD | | cash_request_id | Unique Identifier of the cash transaction. | | payment_link_id | Unique Identifier of the payment link through which the cash transaction was executed. | | cash_request_status | Status of the cash transaction. |

Cash Payment Event

{
  "event": "barcode_generated",
  "data": {
    "pct_fee": "0.01",
    "user_id": "00000000-0000-0000-0000-000000000000",
    "metadata": {
      "rate": "0.0000",
      "quote_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "fixed_fee": "0",
      "balam_rate": "0.0000",
      "pct_fx_fee": "0.000",
      "quote_amount": "0.00"
    },
    "requestid": "",
    "base_amount": "0.00",
    "client_uuid": "11111111-2222-3333-4444-555555555555",
    "referenceid": "YOUR_INTERNAL_REFERENCE",
    "recipient_id": "ffffffff-eeee-dddd-cccc-bbbbbbbbbbbb",
    "base_currency": "USD",
    "quote_currency": "MXN",
    "cash_request_id": "cshdprq_XXXXXX000000GENERIC",
    "payment_link_id": "99999999-8888-7777-6666-555555555555",
    "cash_request_status": "CREATED"
  }
}

Step 3: Payout Webhooks

Once the user has completed the payment — either in cash or by card — Kira will process the payout to the designated bank account. You will then receive status updates regarding the status of the transfer of the collected funds to the recipient’s bank account.

3.1 transaction_update

This flow applies to instant or individual settlement payouts after the payment is confirmed.

Body Schema

Payout Event

{
  "event": "transaction_update",
  "data": {
    "event_id": "11111111-2222-3333-4444-555555555555",
    "transfer_data": {
      "status": "CREATED",
      "reference": "YOUR_INTERNAL_REFERENCE",
      "created_ts": "2025-01-01T00:00:00.000Z",
      "updated_ts": "2025-01-01T00:00:00.000Z",
      "transfer_uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "extra_info": {
        "payment_link_uuid": "ffffffff-eeee-dddd-cccc-bbbbbbbbbbbb"
      }
    }
  }
}

Final Notes

• Always track the status and event values to update your internal transaction state.
• You may receive PROCESSING or FAILED in intermediate steps depending on the provider’s response.