> ## Documentation Index
> Fetch the complete documentation index at: https://docs.riseworks.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Events

> Webhook events related to payment processing and execution

Payment events are triggered during various stages of the payment lifecycle, from group creation to individual payment completion. These events provide real-time updates about payment status and execution details.

## Overview

Rise supports the following payment-related webhook events:

<CardGroup cols={2}>
  <Card title="payment.group.created" icon="layer-group" href="#payment-group-created">
    Payment group created with multiple payments
  </Card>

  <Card title="payment.sent" icon="paper-plane" href="#payment-sent">
    Individual payment processed and sent
  </Card>
</CardGroup>

***

## payment.group.created

When a payment group is created, this event is triggered. A payment group represents a collection of payments that are processed together as a single batch.

### Field reference

<ParamField path="object" type="string" required>
  The type of object this webhook represents (always "event")
</ParamField>

<ParamField path="created" type="number" required>
  The Unix timestamp when the event was created
</ParamField>

<ParamField path="event_type" type="string" required>
  The type of event that occurred
</ParamField>

<ParamField path="event_version" type="string" required>
  The version of the event schema
</ParamField>

<ParamField path="request_id" type="string">
  A unique identifier for the API request that triggered this event (optional)
</ParamField>

<ParamField path="idempotency_key" type="string" required>
  Primary identifier for the webhook event and a unique key to ensure it is processed only once
</ParamField>

<Expandable title="payment_group" defaultOpen>
  <ParamField path="nanoid" type="string" required>
    Primary key of the payment group (nanoid)
  </ParamField>

  <ParamField path="onchain_id" type="string" required>
    Identifier of the payment group on the blockchain
  </ParamField>

  <ParamField path="created_at" type="string" required>
    ISO-8601 timestamp when the payment group was created
  </ParamField>

  <ParamField path="updated_at" type="string" required>
    ISO-8601 timestamp when the payment group was last updated
  </ParamField>

  <ParamField path="invoice_type" type="string">
    Type of invoice (e.g., "time\_entry", "flat", "recurring")
  </ParamField>

  <ParamField path="invoice_description" type="string">
    Description of the work or service being paid for
  </ParamField>

  <ParamField path="role_description" type="string">
    Role or position description for the work
  </ParamField>

  <ParamField path="currency" type="string">
    Currency code for the payment (e.g., "USD", "EUR")
  </ParamField>

  <ParamField path="payments" type="array" required>
    Array of individual payments within this group
  </ParamField>

  <Expandable title="payments[]" defaultOpen>
    <ParamField path="nanoid" type="string" required>
      Primary key of the payment (nanoid)
    </ParamField>

    <ParamField path="onchain_id" type="string" required>
      Identifier of the payment on the blockchain
    </ParamField>

    <ParamField path="group_onchain_id" type="string" required>
      On-chain group ID that this payment belongs to
    </ParamField>

    <ParamField path="invoice_nanoid" type="string" required>
      Reference to the associated invoice nanoid
    </ParamField>

    <ParamField path="creation_transaction" type="string">
      Transaction nanoid of the blockchain tx that created the payment
    </ParamField>

    <ParamField path="process_transaction" type="string">
      Transaction nanoid of the blockchain tx that processed the payment
    </ParamField>

    <ParamField path="created_at" type="string" required>
      ISO-8601 timestamp when the payment row was created
    </ParamField>

    <ParamField path="updated_at" type="string" required>
      ISO-8601 timestamp when the payment row was last updated
    </ParamField>

    <ParamField path="pay_at_time" type="string" required>
      Unix timestamp (seconds) when the payment becomes executable
    </ParamField>

    <ParamField path="pay_type" type="string" required>
      Numeric enum value describing the on-chain payment type
    </ParamField>

    <ParamField path="token" type="object" required>
      Token information for this payment
    </ParamField>

    <Expandable title="token">
      <ParamField path="address" type="string" required>
        ERC-20 token contract address
      </ParamField>

      <ParamField path="name" type="string" required>
        Token name (e.g., "USD Coin")
      </ParamField>

      <ParamField path="symbol" type="string" required>
        Token symbol (e.g., "USDC")
      </ParamField>

      <ParamField path="decimals" type="number" required>
        Number of decimal places for the token
      </ParamField>
    </Expandable>

    <ParamField path="recipients" type="array" required>
      Array of payment recipients
    </ParamField>

    <Expandable title="recipients[]">
      <ParamField path="nanoid" type="string" required>
        Primary key of the recipient (nanoid)
      </ParamField>

      <ParamField path="email" type="string" required>
        Email address of the recipient
      </ParamField>

      <ParamField path="name" type="string" required>
        Name of the recipient
      </ParamField>

      <ParamField path="entity_type" type="string" required>
        The type of entity (user, team, company)
      </ParamField>

      <ParamField path="recipient_address" type="string" required>
        Blockchain wallet address of the recipient (payee).
      </ParamField>
    </Expandable>

    <ParamField path="payer_address" type="string" required>
      Blockchain wallet address of the paying team account.
    </ParamField>

    <ParamField path="amount" type="string" required>
      Payment amount in the token smallest units
    </ParamField>

    <ParamField path="amount_cents" type="number" required>
      The payment amount in cents (USD equivalent)
    </ParamField>
  </Expandable>
</Expandable>

***

## payment.sent

When an individual payment is processed and sent, this event is triggered. This occurs after a payment has been successfully executed on the blockchain.

### Field reference

<ParamField path="object" type="string" required>
  The type of object this webhook represents (always "event")
</ParamField>

<ParamField path="created" type="number" required>
  The Unix timestamp when the event was created
</ParamField>

<ParamField path="event_type" type="string" required>
  The type of event that occurred
</ParamField>

<ParamField path="event_version" type="string" required>
  The version of the event schema
</ParamField>

<ParamField path="request_id" type="string">
  A unique identifier for the API request that triggered this event (optional)
</ParamField>

<ParamField path="idempotency_key" type="string" required>
  A unique key to ensure the webhook is processed only once
</ParamField>

<ParamField path="payment" type="object" required>
  Payment information and details
</ParamField>

<Expandable title="payment" defaultOpen>
  <ParamField path="nanoid" type="string" required>
    Primary key of the payment (nanoid)
  </ParamField>

  <ParamField path="onchain_id" type="string" required>
    Identifier of the payment on the blockchain
  </ParamField>

  <ParamField path="group_onchain_id" type="string" required>
    On-chain group ID that this payment belongs to
  </ParamField>

  <ParamField path="invoice_nanoid" type="string" required>
    Reference to the associated invoice nanoid
  </ParamField>

  <ParamField path="creation_transaction" type="string">
    Transaction nanoid of the blockchain tx that created the payment
  </ParamField>

  <ParamField path="process_transaction" type="string">
    Transaction nanoid of the blockchain tx that processed the payment
  </ParamField>

  <ParamField path="created_at" type="string" required>
    ISO-8601 timestamp when the payment row was created
  </ParamField>

  <ParamField path="updated_at" type="string" required>
    ISO-8601 timestamp when the payment row was last updated
  </ParamField>

  <ParamField path="pay_at_time" type="string" required>
    Unix timestamp (seconds) when the payment becomes executable
  </ParamField>

  <ParamField path="pay_type" type="string" required>
    Numeric enum value describing the on-chain payment type
  </ParamField>

  <ParamField path="token" type="object" required>
    Token information for this payment
  </ParamField>

  <Expandable title="token">
    <ParamField path="address" type="string" required>
      ERC-20 token contract address
    </ParamField>

    <ParamField path="name" type="string" required>
      Token name (e.g., "USD Coin")
    </ParamField>

    <ParamField path="symbol" type="string" required>
      Token symbol (e.g., "USDC")
    </ParamField>

    <ParamField path="decimals" type="number" required>
      Number of decimal places for the token
    </ParamField>
  </Expandable>

  <ParamField path="recipients" type="array" required>
    Array of payment recipients
  </ParamField>

  <Expandable title="recipients[]">
    <ParamField path="nanoid" type="string" required>
      Primary key of the recipient (nanoid)
    </ParamField>

    <ParamField path="email" type="string" required>
      Email address of the recipient
    </ParamField>

    <ParamField path="name" type="string" required>
      Name of the recipient
    </ParamField>

    <ParamField path="entity_type" type="string" required>
      The type of entity (user, team, company)
    </ParamField>

    <ParamField path="recipient_address" type="string" required>
      Blockchain wallet address of the recipient (payee).
    </ParamField>
  </Expandable>

  <ParamField path="payer_address" type="string" required>
    Blockchain wallet address of the paying team account.
  </ParamField>

  <ParamField path="amount" type="string" required>
    Payment amount in the token smallest units
  </ParamField>

  <ParamField path="amount_cents" type="number" required>
    Payment amount in cents (USD equivalent)
  </ParamField>

  <ParamField path="invoice_type" type="string">
    Type of invoice (e.g., "time\_entry", "flat", "recurring")
  </ParamField>

  <ParamField path="invoice_description" type="string">
    Description of the work or service being paid for
  </ParamField>

  <ParamField path="role_description" type="string">
    Role or position description for the work
  </ParamField>

  <ParamField path="currency" type="string">
    Currency code for the payment (e.g., "USD", "EUR")
  </ParamField>

  <ParamField path="payment_group" type="object" required>
    Information about the payment group this payment belongs to
  </ParamField>

  <Expandable title="payment_group">
    <ParamField path="nanoid" type="string" required>
      Primary key of the payment group (nanoid)
    </ParamField>

    <ParamField path="onchain_id" type="string" required>
      Identifier of the payment group on the blockchain
    </ParamField>

    <ParamField path="created_at" type="string" required>
      ISO-8601 timestamp when the payment group was created
    </ParamField>

    <ParamField path="updated_at" type="string" required>
      ISO-8601 timestamp when the payment group was last updated
    </ParamField>
  </Expandable>
</Expandable>

<RequestExample>
  ```json payment.group.created (v1) theme={null}
  {
    "object": "event",
    "created": 1751590453,
    "request_id": "req-1751590452487",
    "event_type": "payment.group.created",
    "event_version": "1.0",
    "idempotency_key": "85420805-0b5e-4b11-b7f4-c6f05db7120b",
    "payment_group": {
      "nanoid": "pg-abc123def456789",
      "onchain_id": "12345",
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z",
      "invoice_type": "time_entry",
      "invoice_description": "Development work for Q1 2024",
      "role_description": "Senior Frontend Developer",
      "currency": "USD",
      "payments": [
        {
          "nanoid": "pa-xyz789abc123456",
          "onchain_id": "67890",
          "group_onchain_id": "12345",
          "invoice_nanoid": "iv-def456ghi789012",
          "creation_transaction": "tx-abc123def456789",
          "process_transaction": null,
          "created_at": "2024-01-15T10:30:00.000Z",
          "updated_at": "2024-01-15T10:30:00.000Z",
          "pay_at_time": "1705312200",
          "pay_type": "1",
          "token": {
            "address": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
            "name": "USD Coin",
            "symbol": "USDC",
            "decimals": 6
          },
          "recipients": [
            {
              "nanoid": "pa-xyz789abc123456",
              "email": "contractor@example.com",
              "name": "John Doe",
              "entity_type": "user",
              "recipient_address": "0x24D5ad606b98A25287e393Ad0EF410F489F5E780"
            }
          ],
          "payer_address": "0x47448085d91b06F3A1D592e9E189B78a867594Ef",
          "amount": "1000000000",
          "amount_cents": 100000
        }
      ]
    }
  }
  ```

  ```json payment.sent (v1) theme={null}
  {
    "object": "event",
    "created": 1751590453,
    "request_id": "req-1751590452487",
    "event_type": "payment.sent",
    "event_version": "1.0",
    "idempotency_key": "85420805-0b5e-4b11-b7f4-c6f05db7120b",
    "payment": {
      "nanoid": "pa-xyz789abc123456",
      "onchain_id": "67890",
      "group_onchain_id": "12345",
      "invoice_nanoid": "iv-def456ghi789012",
      "creation_transaction": "tx-abc123def456789",
      "process_transaction": "tx-def456ghi789012",
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:35:00.000Z",
      "pay_at_time": "1705312200",
      "pay_type": "1",
      "token": {
        "address": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6
      },
      "recipients": [
        {
          "nanoid": "pa-xyz789abc123456",
          "email": "contractor@example.com",
          "name": "John Doe",
          "entity_type": "user",
          "recipient_address": "0x24D5ad606b98A25287e393Ad0EF410F489F5E780"
        }
      ],
      "payer_address": "0x47448085d91b06F3A1D592e9E189B78a867594Ef",
      "amount": "1000000000",
      "amount_cents": 100000,
      "invoice_type": "time_entry",
      "invoice_description": "Development work for Q1 2024",
      "role_description": "Senior Frontend Developer",
      "currency": "USD",
      "payment_group": {
        "nanoid": "pg-abc123def456789",
        "onchain_id": "12345",
        "created_at": "2024-01-15T10:30:00.000Z",
        "updated_at": "2024-01-15T10:30:00.000Z"
      }
    }
  }
  ```
</RequestExample>

***

## Implementation Notes

<Info>
  **Payment lifecycle**: Payment groups are created first (triggering `payment.group.created`), then individual payments within the group are processed and sent (triggering `payment.sent` for each).
</Info>

<Warning>
  **Processing order**: Always handle `payment.group.created` before individual `payment.sent` events, as the group must exist before payments can be processed.
</Warning>

<Tip>
  **Idempotency**: Use the `idempotency_key` field to ensure your webhook handlers don't process the same payment multiple times.
</Tip>