Lune Payments API

openapi: 3.2.0
info:
  title: Lune Payments API
  version: '1.0'
  contact:
    name: Lune Support
    email: support@lune.co
  termsOfService: https://lune.co/terms
  description: 'Operations tagged Payments across 2 of this provider''s published API definitions: openapi.yml, lune-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.lune.co/v1
  description: Lune's REST API
tags:
- name: Payments
  description: Get payments.
  x-lune-component: Payment
paths:
  /payments/by-temporary-id/{temporary_id}:
    get:
      summary: Get a payment by a temporary id
      description: 'Get a specific payment by a temporary id.


        The temporary id will remain valid for 15min from the payment''s creation after which the endpoint will return a 404.'
      operationId: getPaymentByTemporaryId
      tags:
      - Payments
      parameters:
      - name: temporary_id
        in: path
        required: true
        description: The payment's temporary id
        schema:
          type: string
          format: uuid
          example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
      responses:
        '200':
          description: OK
          x-lune-response-component: Payment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    servers:
    - url: https://api.lune.co/v1
      description: Lune's REST API
components:
  schemas:
    OrderPayment:
      x-lune-name: Order payment
      type: object
      required:
      - type
      - order
      properties:
        order:
          allOf:
          - $ref: '#/components/schemas/OrderBase'
          - $ref: '#/components/schemas/OrderByQuantityProperties'
        type:
          type: string
          enum:
          - order
    OrderBase:
      type: object
      description: Order object
      required:
      - id
      - idempotency_key
      - type
      - status
      - currency
      - offset_cost
      - total_cost
      - commission
      - quantity
      - created_at
      - bundles
      - projects
      - certificate
      - public_certificate_url
      - metadata
      - offset_link_id
      - email
      - payment_method
      properties:
        id:
          type: string
          description: The order's unique identifier
          example: va1BER4JZqnzPkYxJgALg0GeQDoXlWO5
        idempotency_key:
          type:
          - string
          - 'null'
          maxLength: 100
          example: 5bd808a954e
          description: 'Account-unique identifier provided by the client.


            `idempotency_key` has two purposes:

            1. Clients can use `idempotency_key` to prevent duplicate orders.

            2. Clients can use `idempotency_key` to reconcile orders with other entities on their system.


            If an order with the same `idempotency_key` already exists, the API returns

            HTTP 409 Conflict with error code `order_idempotency_already_exists`. To

            retrieve the existing order, use the

            `GET /v1/orders/by-idempotency-key/{idempotency_key}` endpoint.

            '
          default: null
        type:
          type: string
          description: Identifies whether the order has been placed by quantity (kg CO2) or value (monetary amount)
          example: quantity
          enum:
          - quantity
          - value
        status:
          type: string
          description: Order status
          example: complete
          enum:
          - received
          - placed
          - paid
          - retiring
          - cancelled
          - complete
          - failed
        currency:
          type: string
          description: Order currency code
          example: GBP
        offset_cost:
          type:
          - string
          - 'null'
          description: 'The net offset cost being purchased. May be lower than `requested_value`.


            This property is set when bundles are assigned to the order.

            Unit: order currency

            '
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '7176.00'
        total_cost:
          type:
          - string
          - 'null'
          description: 'The total cost for the order inclusive of fees.


            Unit: order currency

            '
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '7696.00'
        commission:
          type:
          - string
          - 'null'
          description: 'Lune''s fee.


            This property is set when bundles are assigned to the order.

            Unit: order currency

            '
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '520.00'
        quantity:
          type:
          - string
          - 'null'
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '1040'
          description: Quantity of CO2 offsets purchased in tonnes.
        payment_method:
          description: 'How the order will be paid.

            When `card`, Lune will attempt to charge the card and pay this order. When `invoice`, Lune will email an invoice with payment instructions.'
          type:
          - string
          - 'null'
          enum:
          - invoice
          - card
          - null
        created_at:
          type: string
          format: date-time
          description: Order creation timestamp
        bundles:
          type:
          - array
          - 'null'
          description: 'bundles are set when the order''s status is `placed`, `paid`, `retiring` or `complete`.


            The bundles associated with the order including their relative quantity and cost breakdown.

            '
          items:
            $ref: '#/components/schemas/OrderBundle'
        projects:
          type:
          - array
          - 'null'
          description: 'Projects are set when the order''s status is `retiring` or `complete`.


            The projects associated with the order including their relative quantity and cost breakdown.


            Orders are placed against bundles, not projects. Projects in a bundle may change based on supply.


            This property is set as soon as we can guarantee project supply.

            '
          items:
            $ref: '#/components/schemas/OrderProject'
          example:
          - quantity: '600'
            unit_price: '6.90'
            offset_cost: '4140.00'
            project_id: gMbvJoOaX54V1wpNaRY8dWDGQ7m239Bx
            project_name: Madre De Dios
            project_type: Forest Conservation
            project_slug: madre-de-dios
          - quantity: '440'
            unit_price: '6.90'
            offset_cost: '3036.00'
            project_id: xe1BEV2VZqnzPkYxJgALg0GeQDoXlWO5
            project_name: Alto Mayo
            project_type: Forest Conservation
            project_slug: alto-mayo
        certificate:
          type:
          - string
          - 'null'
          description: 'Carbon credits PDF certificate URL.


            This property is set when an order has state ''complete''


            The property is set (and the certificate is available) regardless of the

            Sustainability page configuration.


            The URL requires API authentication and cannot be accessed anonymously.

            '
          example: https://api.lune.co/v1/orders/08QD7GPaBx5b6Y60ndAONXLvrZljRE2e/certificate
        public_certificate_url:
          type:
          - string
          - 'null'
          description: 'The Carbon credits certificate public URL.


            Once the Sustainability page of the associated account is enabled and configured to include the

            certificate section, and the order is set to ''complete'', this URL will link to the publicly accessible certificate.

            '
          example: https://sustainability.lune.co/account?certificate=1
        metadata:
          $ref: '#/components/schemas/Metadata'
        offset_link_id:
          type:
          - string
          - 'null'
          description: The offset link identifier, if the order was placed through an offset link
          example: UwjfkXjfksoHXzA1qjANL58GhjwqkxpB
        email:
          type:
          - string
          - 'null'
          description: 'End-user email.


            This property is currently populated on orders placed through offset links.

            '
          example: john@doe.com
    Error:
      type: object
      description: Individual error information
      required:
      - error_code
      - message
      properties:
        error_code:
          type: string
          description: Immutable string representing a specific error.
          example: account_suspended
          enum:
          - api_version_invalid
          - account_suspended
          - bundle_selection_ratios_invalid
          - bundle_selection_bundle_invalid
          - order_idempotency_already_exists
          - order_quantity_invalid
          - order_value_invalid
          - bundle_id_invalid
          - id_invalid
          - distance_invalid
          - test_account_name_update_disallowed
          - validation_error
          - bundle_selection_ratios_invalid_format
          - address_not_found
          - port_not_found
          - locode_not_found
          - airport_invalid
          - webhook_limit_reached
          - time_range_invalid
          - exchange_rate_not_found
          - live_account_required
          - unauthorised
          - estimate_not_found
          - estimate_order_already_placed
          - sustainability_page_slug_not_unique
          - sustainability_page_exists
          - pagination_limit_invalid
          - unsupported_image_format
          - source_location_code_invalid
          - destination_location_code_invalid
          - emission_factor_id_invalid
          - emission_factor_unit_mismatch
          - emission_factor_gated
          - account_scope_incorrect
          - service_unavailable
          - handle_not_unique
          - estimate_idempotency_already_exists
          - airport_route_required
          - future_departure_invalid
          - transaction_document_inference_failure
          - transaction_document_creation_failure
          - invalid_selected_account_id
          - account_idempotency_already_exists
          - account_handle_idempotency_key_inconsistency
          - shipment_batch_idempotency_already_exists
          - route_not_found
          - insufficient_credits
          - client_account_mismatch
        message:
          type: string
          description: 'Human readable error message.


            This value can contain some extra information about the error in

            human-readable form. Not suitable for programmatic consumption, the format

            is not guaranteed to be stable.

            '
    Payment:
      description: 'A Payment represents a payment for orders placed through Lune Pay.


        The Payment entity contains a reference to the order.

        '
      oneOf:
      - $ref: '#/components/schemas/OrderPayment'
      discriminator:
        propertyName: type
        mapping:
          order: '#/components/schemas/OrderPayment'
    OrderProject:
      type: object
      required:
      - project_id
      - project_name
      - project_type
      - project_slug
      - quantity
      - unit_price
      - offset_cost
      - status
      properties:
        project_id:
          type: string
          description: The project's unique identifier
          example: xe1BEV2VZqnzPkYxJgALg0GeQDoXlWO5
        project_name:
          type: string
          description: The project's name
          example: Alto Mayo
        project_type:
          type: string
          description: The project's offset type, eg Forest conservation, Afforestation, Direct Air Capture
          example: Forest conservation
        project_slug:
          type: string
          description: The project's unique slug
          example: alto-mayo
        project_logo:
          type: string
          description: URL to the project's logo
          example: https://assets.lune.co/projects/green-sand-logo.png
        quantity:
          type: string
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '1040'
          description: Carbon offset purchased (tonnes CO2)
        unit_price:
          type: string
          description: 'Project unit price per tonne CO2


            Unit: order currency

            '
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '6.09'
        offset_cost:
          type: string
          description: 'The net offset cost being purchased.


            Unit: order currency

            '
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '7176.00'
        status:
          description: 'Describes whether credits for a project have been allocated to an order or retired

            '
          type: string
          enum:
          - allocated
          - retired
          example: retired
    OrderBundle:
      type: object
      required:
      - bundle_id
      - bundle_name
      - quantity
      - unit_price
      - gross_unit_price
      - offset_cost
      - insufficient_available_quantity
      properties:
        bundle_id:
          type: string
          description: The bundle's unique identifier
          example: va1BEV2VZqnzPkYxJgALg0GeQDoXlWO5
        bundle_name:
          type: string
          description: The bundle's name
          example: Latin America Forestry
        primary_image:
          type: string
          description: A bundle's image URL
          example: https://assets.lune.co/bundles/latin-america-forestry.png
        quantity:
          type: string
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '1040'
          description: Quantity for the specific bundle (tonnes CO2)
        unit_price:
          type: string
          description: 'Bundle unit price per tonne CO2


            Unit: order currency

            '
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '6.90'
        gross_unit_price:
          type: string
          description: 'Bundle unit price per tonne CO2 inclusive of fees.


            Unit: order currency

            '
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '7.90'
        offset_cost:
          type: string
          description: 'The bundle''s net offset cost being purchased.


            Unit: order currency

            '
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '7176.00'
        insufficient_available_quantity:
          type:
          - boolean
          - 'null'
          description: 'If true, there is no inventory necessary to fully satisfy the order for this bundle.

            '
          example: true
    ErrorResponse:
      x-lune-name: Error response
      description: 'An error response containing the error details.


        The `error` property provides information about the type of error that occurred.

        Use this property for error handling.


        The `errors` array is present for backwards compatibility purposes. It always

        contains a single error element which is the same seen in the `error` property.

        '
      type: object
      required:
      - errors
      - error
      properties:
        errors:
          type: array
          description: An array containing errors
          items:
            $ref: '#/components/schemas/Error'
        error:
          $ref: '#/components/schemas/Error'
    OrderByQuantityProperties:
      type: object
      required:
      - requested_quantity
      - requested_value
      - estimate_id
      properties:
        requested_quantity:
          type: string
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '1045'
          description: Requested quantity of CO2 offsets to purchase in tonnes.
        requested_value:
          description: Requested value of CO2 offsets to purchase in the account's currency.
          oneOf:
          - $ref: '#/components/schemas/NullEnum'
        estimate_id:
          description: The emission calculation unique identifier
          oneOf:
          - $ref: '#/components/schemas/NullEnum'
    Metadata:
      description: 'An arbitrary dictionary (key-value pairs) to store application-specific information.


        Lune doesn''t use this information for order processing. Its purpose is for the API

        clients to be able to attach arbitrary information (to an order for example) and

        then retrieve it.

        '
      type: object
      additionalProperties:
        type: string
    NullEnum:
      type:
      - string
      - 'null'
      x-lune-name: 'Null'
      description: The property is set to `null`.
      enum:
      - null
  responses:
    BadRequest:
      description: The request is invalid. Parameters may be missing or are invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Too many requests have been made in a short period of time
    NotFound:
      description: The specified resource was not found
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Authorization Bearer API Key (see <a href="#section/Authentication">Authentication</a>)
    AccessToken:
      type: apiKey
      in: query
      name: access_token
      description: 'An API key used to access a resource that accepts it in the URL.


        Note: Lune API keys are not URL-safe, which means that they can''t be included in URLs directly.

        They need to be percent-encoded using a function like JavaScript''s [`encodeURIComponent()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) or

        Python''s [`urllib.parse.quote()`](https://docs.python.org/3/library/urllib.parse.html#urllib.parse.quote).

        '
x-refined-from:
- openapi.yml
- lune-openapi.yml