Orb Payment method webhooks API

openapi: 3.2.0
info:
  title: Reference Payment method webhooks API
  description: 'Orb''s API is built with the following principles in mind:


    1. **Predictable developer experience**: Where applicable, the Orb API uses industry-standard patterns such as

    cursor-based pagination and standardized error output. To help with debugging in critical API

    actions, the API always strives to provide detailed and actionable error messages. Aliases

    such as external customer IDs aid in fast integration times.

    2. **Reliably real time**: Orb''s event-based APIs, such as event ingestion are designed to handle extremely high

    throughput and scale with concurrent load. Orb also provides a real-time event-level credits

    ledger and a highly performant webhooks architecture.

    3. **Flexibility at the forefront**: Features like timezone localization and the ability to amend historical usage

    show the flexible nature of the platform.


    You can download the latest OpenAPI spec here - pass `?version=3.0` for an

    OpenAPI 3.0-compatible spec.'
  contact:
    name: Orb, Inc.
    url: https://www.withorb.com/
    email: team@withorb.com
  version: '1.0'
servers:
- url: https://api.withorb.com/v1
  description: Production server
security:
- APIKeyAuth: []
tags:
- name: Payment method webhooks
  description: Payloads Orb delivers for payment method events. Endpoint configuration, retries and signature verification are covered in the webhooks guide.
paths: {}
webhooks:
  payment_method.created:
    post:
      tags:
      - Payment method webhooks
      summary: payment_method.created
      description: Issued when a payment method is created.
      parameters:
      - description: '`v1=` followed by the hex HMAC-SHA256 of `v1:{X-Orb-Timestamp}:{raw request body}`, keyed by the endpoint''s webhook secret. The header may carry several space-separated signatures during a secret rotation; a receiver accepts the delivery when any `v1` signature matches. Compare in constant time, and sign the bytes as received rather than a re-serialized body.'
        required: true
        schema:
          type: string
        name: X-Orb-Signature
        in: header
      - description: When the delivery was signed, ISO 8601 to milliseconds. It is part of the signed message, so a receiver must reject timestamps outside its tolerance to stop replays.
        required: true
        schema:
          type: string
          format: date-time
        name: X-Orb-Timestamp
        in: header
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentMethodCreatedWebhookEventMessage'
        required: true
      responses:
        2XX:
          description: Any 2xx acknowledges receipt.
      security: []
      x-hidden: true
      x-mint:
        metadata:
          sidebarTitle: payment_method.created
          title: Payment method created
          authMethod: none
  payment_method.deleted:
    post:
      tags:
      - Payment method webhooks
      summary: payment_method.deleted
      description: Issued when a payment method is deleted.
      parameters:
      - description: '`v1=` followed by the hex HMAC-SHA256 of `v1:{X-Orb-Timestamp}:{raw request body}`, keyed by the endpoint''s webhook secret. The header may carry several space-separated signatures during a secret rotation; a receiver accepts the delivery when any `v1` signature matches. Compare in constant time, and sign the bytes as received rather than a re-serialized body.'
        required: true
        schema:
          type: string
        name: X-Orb-Signature
        in: header
      - description: When the delivery was signed, ISO 8601 to milliseconds. It is part of the signed message, so a receiver must reject timestamps outside its tolerance to stop replays.
        required: true
        schema:
          type: string
          format: date-time
        name: X-Orb-Timestamp
        in: header
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentMethodDeletedWebhookEventMessage'
        required: true
      responses:
        2XX:
          description: Any 2xx acknowledges receipt.
      security: []
      x-hidden: true
      x-mint:
        metadata:
          sidebarTitle: payment_method.deleted
          title: Payment method deleted
          authMethod: none
components:
  schemas:
    PaymentMethodDeletedWebhookEventMessage:
      properties:
        id:
          type: string
          description: The ID of this webhook event.
        created_at:
          type: string
          format: date-time
          description: The time at which this event was created, to the second.
        type:
          type: string
          enum:
          - payment_method.deleted
          description: The event this payload describes.
        payload_style:
          type: string
          enum:
          - expanded
          - standard
          description: The serialization style this payload was rendered in, as configured on the endpoint.
        payment_method:
          $ref: '#/components/schemas/PaymentMethod'
        properties:
          $ref: '#/components/schemas/EmptyWebhookEventProperties'
      type: object
      required:
      - id
      - created_at
      - type
      - payload_style
      - payment_method
      - properties
      title: PaymentMethodDeletedWebhookEventMessage
      description: Issued when a payment method is deleted.
      x-orb-webhook-event: payment_method.deleted
    EmptyWebhookEventProperties:
      properties: {}
      type: object
      title: EmptyWebhookEventProperties
    PaymentMethodCreatedWebhookEventMessage:
      properties:
        id:
          type: string
          description: The ID of this webhook event.
        created_at:
          type: string
          format: date-time
          description: The time at which this event was created, to the second.
        type:
          type: string
          enum:
          - payment_method.created
          description: The event this payload describes.
        payload_style:
          type: string
          enum:
          - expanded
          - standard
          description: The serialization style this payload was rendered in, as configured on the endpoint.
        payment_method:
          $ref: '#/components/schemas/PaymentMethod'
        properties:
          $ref: '#/components/schemas/EmptyWebhookEventProperties'
      type: object
      required:
      - id
      - created_at
      - type
      - payload_style
      - payment_method
      - properties
      title: PaymentMethodCreatedWebhookEventMessage
      description: Issued when a payment method is created.
      x-orb-webhook-event: payment_method.created
    PaymentMethod:
      properties:
        id:
          type: string
          title: Id
          description: The Orb-assigned unique identifier for the payment method.
        payment_method_type:
          type: string
          enum:
          - card
          - us_bank_account
          - link
          - amazon_pay
          - crypto
          title: Payment Method Type
          description: The type of the underlying payment instrument, e.g. `card` or `us_bank_account`.
        provider_type:
          oneOf:
          - type: string
          - type: 'null'
          title: Provider Type
          description: The external payment provider this method belongs to, derived from the linked payment gateway connection (e.g. `adyen` or `stripe`). Null if the connection has been removed.
        external_payment_method_id:
          type: string
          title: External Payment Method Id
          description: The identifier of this payment method in the external payment provider.
        customer_id:
          type: string
          title: Customer Id
          description: The ID of the Orb customer this payment method is attached to.
        default:
          type: boolean
          title: Default
          description: Whether this is the customer's default payment method.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The time at which the payment method was created.
      type: object
      required:
      - id
      - payment_method_type
      - provider_type
      - external_payment_method_id
      - customer_id
      - default
      - created_at
      title: PaymentMethod
      description: 'A payment method represents a customer''s stored payment instrument held with an external payment

        provider (such as Adyen or Stripe).


        The serialization is intentionally minimal for now; provider-pulled details (e.g. card display

        metadata) will be added over time.'
  securitySchemes:
    APIKeyAuth:
      type: http
      description: API Keys can be issued in the Orb's web application.
      scheme: bearer