Lago Payment Receipts API

openapi: 3.2.0
info:
  title: Lago API documentation Payment Receipts API
  description: Lago API allows your application to push customer information and metrics (events) from your application to the billing application.
  version: 1.55.0
  license:
    name: AGPLv3
    url: https://github.com/getlago/lago-openapi/blob/main/LICENSE
  contact:
    email: tech@getlago.com
servers:
- url: https://api.getlago.com/api/v1
  description: US Lago cluster
- url: https://api.eu.getlago.com/api/v1
  description: EU Lago cluster
security:
- bearerAuth: []
tags:
- name: payment_receipts
  description: Everything about Payment receipts
  externalDocs:
    description: Find out more
    url: https://getlago.com/docs/api-reference/payment-receipts/payment-receipt-object
paths:
  /payment_receipts:
    get:
      tags:
      - payment_receipts
      summary: List all payment receipts
      description: This endpoint is used to list all existing payment receipts.
      operationId: findAllPaymentReceipts
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      - name: invoice_id
        in: query
        description: Filter payment receipts by invoice. It returns the receipts of the payments made on this invoice, including the payments made through a payment request that covers it.
        required: false
        explode: true
        schema:
          type: string
          format: uuid
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
      responses:
        '200':
          description: Payment receipts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentReceiptsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /payment_receipts/{lago_id}:
    parameters:
    - name: lago_id
      in: path
      description: Unique identifier of the payment receipt.
      required: true
      schema:
        type: string
        format: uuid
        example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
    get:
      tags:
      - payment_receipts
      summary: Retrieve a payment receipt
      description: This endpoint retrieves a specific payment receipt.
      operationId: findPaymentReceipt
      responses:
        '200':
          description: Payment receipt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentReceipt'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    PaymentReceipt:
      type: object
      required:
      - payment_receipt
      properties:
        payment_receipt:
          $ref: '#/components/schemas/PaymentReceiptObject'
    PaginationMeta:
      type: object
      required:
      - current_page
      - total_pages
      - total_count
      properties:
        current_page:
          type: integer
          description: Current page.
          example: 2
        next_page:
          type:
          - integer
          - 'null'
          description: Next page.
          example: 3
        prev_page:
          type:
          - integer
          - 'null'
          description: Previous page.
          example: 1
        total_pages:
          type: integer
          description: Total number of pages.
          example: 4
        total_count:
          type: integer
          description: Total number of records.
          example: 70
    ApiErrorUnprocessableEntity:
      type: object
      required:
      - status
      - error
      - code
      - error_details
      properties:
        status:
          type: integer
          format: int32
          example: 422
        error:
          type: string
          example: Unprocessable entity
        code:
          type: string
          example: validation_errors
        error_details:
          type: object
    ApiErrorNotFound:
      type: object
      required:
      - status
      - error
      - code
      properties:
        status:
          type: integer
          format: int32
          example: 404
        error:
          type: string
          example: Not Found
        code:
          type: string
          example: object_not_found
    ApiErrorUnauthorized:
      type: object
      required:
      - status
      - error
      properties:
        status:
          type: integer
          format: int32
          example: 401
        error:
          type: string
          example: Unauthorized
    PaymentObject:
      type: object
      required:
      - lago_id
      - lago_customer_id
      - external_customer_id
      - invoice_ids
      - invoice_numbers
      - lago_payable_id
      - payable_type
      - amount_cents
      - amount_currency
      - status
      - payment_status
      - type
      - reference
      - payment_provider_code
      - payment_provider_type
      - external_payment_id
      - provider_payment_id
      - provider_customer_id
      - next_action
      - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: The unique identifier of the payment, created by Lago.
          example: 4cf085a7-c196-4f07-a543-97c50ec6e8b2
        lago_customer_id:
          type: string
          format: uuid
          description: Unique identifier of the customer, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_customer_id:
          type: string
          example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
          description: The customer external unique identifier (provided by your own application).
        invoice_ids:
          type: array
          description: List of invoice IDs associated with the payment.
          items:
            type: string
            format: uuid
            example: 486b147a-02a1-4ccf-8603-f3541fc25e7a
        invoice_numbers:
          type: array
          description: List of invoice numbers associated with the payment.
          items:
            type: string
            example: HOO-202D-005-001
        lago_payable_id:
          type: string
          format: uuid
          description: The unique identifier of the paid resource, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        payable_type:
          type: string
          enum:
          - Invoice
          - PaymentRequest
          description: The type of the paid resource, associated with the `lago_payable_id`.
          example: Invoice
        amount_cents:
          type: integer
          description: The amount of the payment in cents.
          example: 1099
        amount_currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of the payment amount.
          example: USD
        status:
          type: string
          description: The status of the payment within the payment provider. It differs from one payment provider to another. It is always `succeeded` for a manual payment.
          example: Completed
        payment_status:
          type: string
          description: The payment status, normalized by Lago so that it is the same for every payment provider.
          enum:
          - succeeded
          - failed
          - pending
          - processing
          example: succeeded
        type:
          type: string
          description: The type of payment.
          enum:
          - manual
          - provider
          example: manual
        reference:
          type:
          - string
          - 'null'
          description: Reference for the payment. Set on manual payments only; it is always `null` for payments collected through a payment provider.
          example: ref1
        payment_provider_code:
          type:
          - string
          - 'null'
          description: Code of the payment provider. It is `null` for manual payments, which are not attached to a payment provider.
          example: stripe_prod
        payment_provider_type:
          type:
          - string
          - 'null'
          enum:
          - null
          - adyen
          - cashfree
          - gocardless
          - stripe
          - flutterwave
          - moneyhash
          description: The type of payment provider. It is `null` for manual payments, which are not attached to a payment provider.
          example: stripe
        external_payment_id:
          type:
          - string
          - 'null'
          deprecated: true
          description: '**Deprecated.** Use `provider_payment_id` instead. It holds the same value.'
          example: pi_5eb0285741bc6ba
        provider_payment_id:
          type:
          - string
          - 'null'
          description: Unique identifier of the payment within the payment provider (if applicable).
          example: pi_5eb0285741bc6ba
        provider_customer_id:
          type:
          - string
          - 'null'
          description: Unique identifier of the customer within the payment provider. It is `null` for manual payments.
          example: cus_5eb0285bcf941bc6ba
        next_action:
          type: object
          additionalProperties: true
          description: The next action to be taken by the customer to complete the payment. Should usually be empty, except when receiving the `payment.requires_action` webhook.
          example:
            type: redirect_to_url
            redirect_to_url:
              url: https://hooks.stripe.com/3d_secure_2/hosted?merchant=acct_AAA&payment_intent=pi_BBB&payment_intent_client_secret=pi_BBB&publishable_key=pk_test_CCC
              return_url: https://app.example.com
        created_at:
          type: string
          format: date-time
          description: Timestamp when the payment was created in Lago's database, not on the payment provider.
          example: '2025-01-21T00:10:29Z'
        payment_method:
          $ref: '#/components/schemas/PaymentMethodObject'
          description: The payment method used for the payment. It is only sent on the `payment.succeeded` webhook, and only when a payment method is attached to the payment.
    PaymentReceiptsPaginated:
      type: object
      required:
      - payment_receipts
      - meta
      properties:
        payment_receipts:
          type: array
          items:
            $ref: '#/components/schemas/PaymentReceiptObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    PaymentReceiptObject:
      type: object
      required:
      - lago_id
      - created_at
      - number
      - file_url
      - xml_url
      - payment
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the payment receipt, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        created_at:
          type: string
          format: date-time
          description: The date and time when the payment receipt was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the payment receipt was initially created.
          example: '2022-04-29T08:59:51Z'
        number:
          type: string
          description: The unique number assigned to the payment receipt.
          example: LAG-1234-001-002
        file_url:
          type:
          - string
          - 'null'
          description: The PDF file of the payment receipt. It is `null` while no PDF has been generated.
          example: https://getlago.com/payment_receipt/file
        xml_url:
          type:
          - string
          - 'null'
          description: The e-invoicing XML file of the payment receipt. It is `null` while no XML file has been generated.
          example: https://getlago.com/payment_receipt/xml
        payment:
          $ref: '#/components/schemas/PaymentObject'
    PaymentMethodObject:
      type: object
      required:
      - lago_id
      - is_default
      - payment_provider_code
      - payment_provider_name
      - payment_provider_type
      - provider_method_id
      - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: The unique identifier of the payment method, created by Lago.
          example: 4cf085a7-c196-4f07-a543-97c50ec6e8b2
        is_default:
          type: boolean
          description: Indicates whether this payment method is the default one for the customer.
          example: true
        payment_provider_code:
          type:
          - string
          - 'null'
          description: Code of the payment provider associated with this payment method.
          example: stripe_prod
        payment_provider_name:
          type:
          - string
          - 'null'
          description: Human-readable name of the payment provider.
          example: Stripe
        payment_provider_type:
          type:
          - string
          - 'null'
          description: The type of the payment provider. It is `null` when the payment method is no longer attached to a payment provider.
          enum:
          - null
          - adyen
          - cashfree
          - gocardless
          - stripe
          - flutterwave
          - moneyhash
          example: stripe
        provider_method_id:
          type: string
          description: Unique identifier of the payment method within the payment provider.
          example: pm_1N8ZQX2eZvKYlo2CkL9Y8XYZ
        created_at:
          type: string
          format: date-time
          description: Timestamp when the payment method was created in Lago's database.
          example: '2025-01-21T00:10:29Z'
    Currency:
      type: string
      example: USD
      enum:
      - AED
      - AFN
      - ALL
      - AMD
      - ANG
      - AOA
      - ARS
      - AUD
      - AWG
      - AZN
      - BAM
      - BBD
      - BDT
      - BGN
      - BIF
      - BMD
      - BND
      - BOB
      - BRL
      - BSD
      - BWP
      - BYN
      - BZD
      - CAD
      - CDF
      - CHF
      - CLF
      - CLP
      - CNY
      - COP
      - CRC
      - CVE
      - CZK
      - DJF
      - DKK
      - DOP
      - DZD
      - EGP
      - ETB
      - EUR
      - FJD
      - FKP
      - GBP
      - GEL
      - GHS
      - GIP
      - GMD
      - GNF
      - GTQ
      - GYD
      - HKD
      - HNL
      - HRK
      - HTG
      - HUF
      - IDR
      - ILS
      - INR
      - ISK
      - JMD
      - JPY
      - KES
      - KGS
      - KHR
      - KMF
      - KRW
      - KYD
      - KZT
      - LAK
      - LBP
      - LKR
      - LRD
      - LSL
      - MAD
      - MDL
      - MGA
      - MKD
      - MMK
      - MNT
      - MOP
      - MRO
      - MUR
      - MVR
      - MWK
      - MXN
      - MYR
      - MZN
      - NAD
      - NGN
      - NIO
      - NOK
      - NPR
      - NZD
      - PAB
      - PEN
      - PGK
      - PHP
      - PKR
      - PLN
      - PYG
      - QAR
      - RON
      - RSD
      - RUB
      - RWF
      - SAR
      - SBD
      - SCR
      - SEK
      - SGD
      - SHP
      - SLL
      - SOS
      - SRD
      - STD
      - SYP
      - SZL
      - THB
      - TJS
      - TND
      - TOP
      - TRY
      - TTD
      - TWD
      - TZS
      - UAH
      - UGX
      - USD
      - UYU
      - UZS
      - VND
      - VUV
      - WST
      - XAF
      - XCD
      - XOF
      - XPF
      - YER
      - ZAR
      - ZMW
  responses:
    NotFound:
      description: Not Found error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorNotFound'
    UnprocessableEntity:
      description: Unprocessable entity error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorUnprocessableEntity'
    Unauthorized:
      description: Unauthorized error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorUnauthorized'
  parameters:
    page:
      name: page
      in: query
      description: Page number.
      required: false
      explode: true
      schema:
        type: integer
        example: 1
    per_page:
      name: per_page
      in: query
      description: Number of records per page.
      required: false
      explode: true
      schema:
        type: integer
        example: 20
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
externalDocs:
  description: Lago Github
  url: https://github.com/getlago
x-provenance:
  method: harvested
  publisher: Lago
  source: https://getlago.com/api/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)