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

# List events

> Every event your payments, refunds and checkout sessions produced in this environment, newest first, whether or not an endpoint was listening.



## OpenAPI

````yaml /api-reference/openapi-v1.json get /events
openapi: 3.1.0
info:
  title: Payra API
  version: v1
  description: >-
    The Payra API. Authenticate with a secret key: `Authorization: Bearer
    sk_test_...`. The two payment method session endpoints Payra Elements calls
    also take a publishable key with the session's `client_secret`.
servers:
  - url: https://api-dashboard.payra.com/v1
    description: 'Sandbox and live: the key decides which'
security: []
paths:
  /events:
    get:
      tags:
        - Webhooks
      summary: List events
      description: >-
        Every event your payments, refunds and checkout sessions produced in
        this environment, newest first, whether or not an endpoint was
        listening.
      parameters:
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
            example: 20
            description: How many to return, 1 to 100.
          required: false
          description: How many to return, 1 to 100.
          name: limit
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 64
            example: evt_test_7Hs2kQ9mL1pXv4cR8tWzAbCdEf
            description: >-
              The `id` of the last event of the previous page; the page after it
              is returned.
          required: false
          description: >-
            The `id` of the last event of the previous page; the page after it
            is returned.
          name: starting_after
          in: query
        - schema:
            type: string
            enum:
              - payment.processing
              - payment.authorized
              - payment.succeeded
              - payment.failed
              - payment.canceled
              - payment.returned
              - refund.pending
              - refund.succeeded
              - refund.failed
              - checkout_session.completed
              - checkout_session.expired
            example: payment.failed
            description: Only events of this type.
          required: false
          description: Only events of this type.
          name: type
          in: query
      responses:
        '200':
          description: A page of events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventList'
        '400':
          description: >-
            `limit` out of range, or `starting_after` is not an event of this
            workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, invalid or revoked API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The API is not enabled for the workspace, or the key lacks the scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded; see Retry-After
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    EventList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Event'
        has_more:
          type: boolean
      required:
        - object
        - data
        - has_more
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - permission_error
                - rate_limit_error
                - idempotency_error
                - card_error
                - api_error
            code:
              type: string
            message:
              type: string
            param:
              type: string
            request_id:
              type: string
          required:
            - type
            - code
            - message
            - request_id
          additionalProperties:
            type: string
      required:
        - error
    Event:
      type: object
      properties:
        object:
          type: string
          enum:
            - event
        id:
          type: string
          example: evt_test_7Hs2kQ9mL1pXv4cR8tWzAbCdEf
        type:
          type: string
          enum:
            - payment.processing
            - payment.authorized
            - payment.succeeded
            - payment.failed
            - payment.canceled
            - payment.returned
            - refund.pending
            - refund.succeeded
            - refund.failed
            - checkout_session.completed
            - checkout_session.expired
          example: payment.succeeded
        created_at:
          type: string
          example: '2026-09-19T21:04:11.000Z'
          description: >-
            When the object reached this state: by the ledger for a payment or a
            refund, by the session for a checkout session.
        livemode:
          type: boolean
          example: false
        data:
          type: object
          properties:
            object:
              oneOf:
                - $ref: '#/components/schemas/Payment'
                - $ref: '#/components/schemas/Refund'
                - $ref: '#/components/schemas/CheckoutSession'
              discriminator:
                propertyName: object
                mapping:
                  payment:
                    $ref: '#/components/schemas/Payment'
                  refund:
                    $ref: '#/components/schemas/Refund'
                  checkout_session:
                    $ref: '#/components/schemas/CheckoutSession'
              description: >-
                The payment (on a `payment.*` event), the refund (on a
                `refund.*` event) or the checkout session (on a
                `checkout_session.*` event) as it was when the event was filed,
                which can already be a step past the announced `type`; `GET
                /v1/payments/{id}`, `GET /v1/refunds/{id}` and `GET
                /v1/checkout-sessions/{id}` have the current state.
          required:
            - object
      required:
        - object
        - id
        - type
        - created_at
        - livemode
        - data
    Payment:
      type: object
      properties:
        object:
          type: string
          enum:
            - payment
        id:
          type: string
          example: pay_test_7Hs2kQ9mL1pXv4cR8tWzAbCdEf
        status:
          type: string
          enum:
            - processing
            - requires_action
            - authorized
            - succeeded
            - failed
            - canceled
            - returned
          example: succeeded
          description: >-
            `processing` until the processor answers, and, on a bank debit,
            until it settles, that is until the processor sends it to the bank
            in its next batch; `authorized` when it approved but has not
            captured; `succeeded` once a card is captured or a bank debit has
            settled, which does not make a bank debit final (see `returned`);
            `failed` when it refused (the create then answers 402 and this
            object stays readable); `canceled` after a void; `returned` when the
            money came back after success (a bank return or a chargeback, see
            `failure`); `requires_action` if the processor asked for a step this
            server-side charge cannot take.
        amount:
          type: integer
          example: 12550
          description: In the smallest unit of the currency (cents).
        amount_refunded:
          type: integer
          default: 0
          example: 0
          description: >-
            How much of `amount` has been refunded so far, counting refunds that
            succeeded, wherever they were made. `status` stays `succeeded`; `GET
            /v1/refunds?payment=` lists them.
        currency:
          type: string
          enum:
            - USD
            - CAD
          example: USD
        payment_method:
          type: string
          example: pm_test_9kQ2mL7Hs1pXv4cR8tWzAbCdEf
        payment_method_type:
          type: string
          enum:
            - card
            - us_bank_account
          default: card
          example: card
        customer:
          type:
            - string
            - 'null'
          format: uuid
          example: null
        description:
          type:
            - string
            - 'null'
          example: Invoice INV-1042
        reference:
          type:
            - string
            - 'null'
          example: INV-1042
          description: Your reference, as you sent it.
        card:
          $ref: '#/components/schemas/PaymentCard'
        us_bank_account:
          type:
            - object
            - 'null'
          properties:
            last4:
              type: string
              example: '6789'
            account_type:
              type: string
              enum:
                - checking
                - savings
              example: checking
            account_holder_type:
              type: string
              enum:
                - individual
                - company
              example: individual
          default: null
          required:
            - last4
            - account_type
            - account_holder_type
          description: Set when `payment_method_type` is `us_bank_account`.
          example: null
        failure:
          type:
            - object
            - 'null'
          properties:
            code:
              type: string
              enum:
                - card_declined
                - insufficient_funds
                - authentication_failed
                - invalid_payment_method
                - duplicate_transaction
                - ach_returned
                - chargeback
                - processing_error
              example: card_declined
            message:
              type: string
              example: The card was declined.
          required:
            - code
            - message
          description: >-
            Set when `status` is `failed` or `returned`: why, in a fixed
            vocabulary. `card_declined`, `insufficient_funds`,
            `authentication_failed`, `invalid_payment_method` and
            `duplicate_transaction` are the processor refusing the card;
            `ach_returned` and `chargeback` are money coming back after success;
            `processing_error` is a fault on the way to the processor or in the
            request, safe to retry later; a refusal in words Payra cannot
            classify reads `card_declined`. The processor's own text is never
            relayed.
        next_action:
          type:
            - object
            - 'null'
          properties:
            type:
              type: string
              enum:
                - redirect
            url:
              type: string
          required:
            - type
            - url
          example: null
          description: >-
            A server-side charge sends no 3-D Secure return address, so this is
            normally null; if a processor asks for a redirect anyway, it is
            here.
        livemode:
          type: boolean
          example: false
        created_at:
          type: string
          format: date-time
          example: '2026-09-18T20:00:00.000Z'
        succeeded_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2026-09-18T20:00:01.312Z'
          description: When the card was captured, or the bank debit settled.
      required:
        - object
        - id
        - status
        - amount
        - currency
        - payment_method
        - customer
        - description
        - reference
        - card
        - failure
        - next_action
        - livemode
        - created_at
        - succeeded_at
    Refund:
      type: object
      properties:
        object:
          type: string
          enum:
            - refund
        id:
          type: string
          example: re_test_3kQ2mL7Hs1pXv4cR8tWzAbCdEf
        payment:
          type: string
          example: pay_test_7Hs2kQ9mL1pXv4cR8tWzAbCdEf
          description: The payment the money goes back on.
        status:
          type: string
          enum:
            - pending
            - succeeded
            - failed
          example: succeeded
          description: >-
            `pending` while the processor has the refund but has not confirmed
            it (a later webhook says how it ended); `succeeded` once the money
            is on its way back; `failed` when the processor refused (the create
            then answers 402 and this object stays readable).
        amount:
          type: integer
          example: 2500
          description: In the smallest unit of the currency (cents).
        currency:
          type: string
          enum:
            - USD
            - CAD
          example: USD
        reason:
          type:
            - string
            - 'null'
          example: Customer returned the item
        failure:
          type:
            - object
            - 'null'
          properties:
            code:
              type: string
              enum:
                - card_declined
                - insufficient_funds
                - authentication_failed
                - invalid_payment_method
                - duplicate_transaction
                - ach_returned
                - chargeback
                - processing_error
              example: processing_error
            message:
              type: string
              example: The payment could not be processed. Retry later.
          required:
            - code
            - message
          description: >-
            Set when `status` is `failed`: why, in the same fixed vocabulary as
            a payment failure. `processing_error` is a fault on the way to the
            processor, safe to retry with a new Idempotency-Key.
        livemode:
          type: boolean
          example: false
        created_at:
          type: string
          format: date-time
          example: '2026-09-22T20:00:00.000Z'
        succeeded_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2026-09-22T20:00:01.312Z'
      required:
        - object
        - id
        - payment
        - status
        - amount
        - currency
        - reason
        - failure
        - livemode
        - created_at
        - succeeded_at
    CheckoutSession:
      type: object
      properties:
        object:
          type: string
          enum:
            - checkout_session
        id:
          type: string
          example: cs_test_7Hs2kQ9mL1pXv4cR8tWzAbCd
        status:
          type: string
          enum:
            - open
            - complete
            - expired
          example: open
          description: >-
            `open` while the customer can pay; `complete` once one payment
            succeeded (or, for a bank debit, was accepted) on the page;
            `expired` after `expires_at`, or once you expired it. A session pays
            once.
        amount:
          type: integer
          example: 12550
          description: In the smallest unit of the currency (cents).
        currency:
          type: string
          enum:
            - USD
            - CAD
          example: USD
        reference:
          type:
            - string
            - 'null'
          example: '1042'
        description:
          type:
            - string
            - 'null'
          example: 'Northwind order #1042'
        success_url:
          type: string
          example: https://shop.example/thanks?order=1042
        cancel_url:
          type: string
          example: https://shop.example/cart
        customer_email:
          type:
            - string
            - 'null'
          example: ana@example.com
        customer:
          type:
            - string
            - 'null'
          example: null
        payment_method_types:
          type: array
          items:
            type: string
            enum:
              - card
              - us_bank_account
          example:
            - card
        metadata:
          $ref: '#/components/schemas/CheckoutSessionMetadata'
        payment:
          type:
            - string
            - 'null'
          example: pay_test_7Hs2kQ9mL1pXv4cR8tWzAbCdEf
          description: >-
            The payment made on the page, once the session is `complete`; read
            it at `GET /payments/{id}`.
        livemode:
          type: boolean
          example: false
        expires_at:
          type: string
          example: '2026-09-26T12:00:00.000Z'
        completed_at:
          type:
            - string
            - 'null'
          example: null
        created_at:
          type: string
          example: '2026-09-25T12:00:00.000Z'
      required:
        - object
        - id
        - status
        - amount
        - currency
        - reference
        - description
        - success_url
        - cancel_url
        - customer_email
        - customer
        - payment_method_types
        - metadata
        - payment
        - livemode
        - expires_at
        - completed_at
        - created_at
    PaymentCard:
      type:
        - object
        - 'null'
      properties:
        brand:
          type:
            - string
            - 'null'
          example: visa
        last4:
          type: string
          example: '4242'
        exp_month:
          type: integer
          example: 12
        exp_year:
          type: integer
          example: 2030
      required:
        - brand
        - last4
        - exp_month
        - exp_year
      description: Set when `payment_method_type` is `card`.
    CheckoutSessionMetadata:
      type:
        - object
        - 'null'
      additionalProperties:
        type: string
        maxLength: 500
      description: >-
        Up to 20 keys of your own (keys up to 40 characters, values up to 500);
        stored and returned, never interpreted.
      example:
        order_id: '1042'
        cart: a1b2c3
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        A secret key, `sk_test_...` or `sk_live_...`; a publishable key
        (`pk_...`) on the browser routes only

````