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:

payment.group.created

Payment group created with multiple payments

payment.sent

Individual payment processed and sent

payment.failed

Payment transaction failed on-chain

---

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

object · string · required

The type of object this webhook represents (always “event”)

created · number · required

The Unix timestamp when the event was created

event_type · string · required

The type of event that occurred

event_version · string · required

The version of the event schema

request_id · string

A unique identifier for the API request that triggered this event (optional)

idempotency_key · string · required

Primary identifier for the webhook event and a unique key to ensure it is processed only once

Hide payment_group

nanoid · string · required

Primary key of the payment group (nanoid)

onchain_id · string · required

Identifier of the payment group on the blockchain

created_at · string · required

ISO-8601 timestamp when the payment group was created

updated_at · string · required

ISO-8601 timestamp when the payment group was last updated

invoice_type · string

Type of invoice (e.g., “time_entry”, “flat”, “recurring”)

invoice_description · string

Description of the work or service being paid for

role_description · string

Role or position description for the work

currency · string

Currency code for the payment (e.g., “USD”, “EUR”)

payments · array · required

Array of individual payments within this group

Hide payments[]

nanoid · string · required

Primary key of the payment (nanoid)

onchain_id · string · required

Identifier of the payment on the blockchain

group_onchain_id · string · required

On-chain group ID that this payment belongs to

invoice_nanoid · string · required

Reference to the associated invoice nanoid

creation_transaction · string

Transaction nanoid of the blockchain tx that created the payment

process_transaction · string

Transaction nanoid of the blockchain tx that processed the payment

created_at · string · required

ISO-8601 timestamp when the payment row was created

updated_at · string · required

ISO-8601 timestamp when the payment row was last updated

pay_at_time · string · required

Unix timestamp (seconds) when the payment becomes executable

pay_type · string · required

Numeric enum value describing the on-chain payment type

token · object · required

Token information for this payment

Show token

address · string · required

ERC-20 token contract address

name · string · required

Token name (e.g., “USD Coin”)

symbol · string · required

Token symbol (e.g., “USDC”)

decimals · number · required

Number of decimal places for the token

recipients · array · required

Array of payment recipients

Show recipients[]

nanoid · string · required

Primary key of the recipient (nanoid)

email · string · required

Email address of the recipient

name · string · required

Name of the recipient

entity_type · string · required

The type of entity (user, team, company)

recipient_address · string · required

Blockchain wallet address of the recipient (payee).

payer_address · string · required

Blockchain wallet address of the paying team account.

amount · string · required

Payment amount in the token smallest units

amount_cents · number · required

The payment amount in cents (USD equivalent)

---

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

object · string · required

The type of object this webhook represents (always “event”)

created · number · required

The Unix timestamp when the event was created

event_type · string · required

The type of event that occurred

event_version · string · required

The version of the event schema

request_id · string

A unique identifier for the API request that triggered this event (optional)

idempotency_key · string · required

A unique key to ensure the webhook is processed only once

payment · object · required

Payment information and details

Hide payment

nanoid · string · required

Primary key of the payment (nanoid)

onchain_id · string · required

Identifier of the payment on the blockchain

group_onchain_id · string · required

On-chain group ID that this payment belongs to

invoice_nanoid · string · required

Reference to the associated invoice nanoid

creation_transaction · string

Transaction nanoid of the blockchain tx that created the payment

process_transaction · string

Transaction nanoid of the blockchain tx that processed the payment

created_at · string · required

ISO-8601 timestamp when the payment row was created

updated_at · string · required

ISO-8601 timestamp when the payment row was last updated

pay_at_time · string · required

Unix timestamp (seconds) when the payment becomes executable

pay_type · string · required

Numeric enum value describing the on-chain payment type

token · object · required

Token information for this payment

Show token

address · string · required

ERC-20 token contract address

name · string · required

Token name (e.g., “USD Coin”)

symbol · string · required

Token symbol (e.g., “USDC”)

decimals · number · required

Number of decimal places for the token

recipients · array · required

Array of payment recipients

Show recipients[]

nanoid · string · required

Primary key of the recipient (nanoid)

email · string · required

Email address of the recipient

name · string · required

Name of the recipient

entity_type · string · required

The type of entity (user, team, company)

recipient_address · string · required

Blockchain wallet address of the recipient (payee).

payer_address · string · required

Blockchain wallet address of the paying team account.

amount · string · required

Payment amount in the token smallest units

amount_cents · number · required

Payment amount in cents (USD equivalent)

invoice_type · string

Type of invoice (e.g., “time_entry”, “flat”, “recurring”)

invoice_description · string

Description of the work or service being paid for

role_description · string

Role or position description for the work

currency · string

Currency code for the payment (e.g., “USD”, “EUR”)

payment_group · object · required

Information about the payment group this payment belongs to

Show payment_group

nanoid · string · required

Primary key of the payment group (nanoid)

onchain_id · string · required

Identifier of the payment group on the blockchain

created_at · string · required

ISO-8601 timestamp when the payment group was created

updated_at · string · required

ISO-8601 timestamp when the payment group was last updated

---

payment.failed

Triggered when a submitted payment transaction fails on-chain (for example, it reverts). The payment is never created on-chain, so it does not appear in GET /v2/payments. Requests rejected by validation return an error from the API call itself and do not trigger this event.

Field reference

object · string · required

The type of object this webhook represents (always “event”)

created · number · required

The Unix timestamp when the event was created

event_type · string · required

The type of event that occurred

event_version · string · required

The version of the event schema

request_id · string

Nanoid of the failed transaction

idempotency_key · string · required

A unique key to ensure the webhook is processed only once

payment · object · required

Details of the failed payment

Hide payment

tx_nanoid · string · required

Nanoid of the failed blockchain transaction. Matches the transaction returned by PUT /v2/payments

payment_nanoid · string

Primary key of the payment (nanoid), when resolvable

recipient_nanoid · string

Nanoid of the payment recipient (payee)

recipient_name · string

Display name of the payment recipient

payer_nanoid · string · required

Nanoid of the paying team (payer)

payer_name · string

Display name of the payer team

amount_cents · number · required

Payment amount in cents (USD equivalent)

currency · string

Currency code of the payment

error_message · string · required

Failure reason reported for the transaction

failed_at · string · required

ISO-8601 timestamp when the failure was processed

payment.group.created (v1)

{
  "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": "[e-mail]",
            "name": "John Doe",
            "entity_type": "user",
            "recipient_address": "0x24D5ad606b98A25287e393Ad0EF410F489F5E780"
          }
        ],
        "payer_address": "0x47448085d91b06F3A1D592e9E189B78a867594Ef",
        "amount": "1000000000",
        "amount_cents": 100000
      }
    ]
  }
}

---

Implementation Notes

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).

Processing order: Always handle payment.group.created before individual payment.sent events, as the group must exist before payments can be processed.

Tracking outcomes: Use payment.sent and payment.failed as the primary signals for a payment’s outcome, and match them to the transaction returned by PUT /v2/payments. GET /v2/payments only lists payments that exist on-chain, so it can confirm success but cannot distinguish a pending payment from a failed one. A Removed state means the payer cancelled the payment; it is not a failure.

Idempotency: Use the idempotency_key field to ensure your webhook handlers don’t process the same payment multiple times.