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

# Retrieve a payment method session

> With a secret key, the current state of one of your sessions. With a publishable key and the session `client_secret`, the same object plus `collect`, which is what Payra Elements uses to mount the secure fields. This is the only endpoint a browser calls directly.



## OpenAPI

````yaml /api-reference/openapi-v1.json get /payment-method-sessions/{id}
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:
  /payment-method-sessions/{id}:
    get:
      tags:
        - Payment method sessions
      summary: Retrieve a payment method session
      description: >-
        With a secret key, the current state of one of your sessions. With a
        publishable key and the session `client_secret`, the same object plus
        `collect`, which is what Payra Elements uses to mount the secure fields.
        This is the only endpoint a browser calls directly.
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 64
          required: true
          name: id
          in: path
        - schema:
            type: string
            description: >-
              Required with a publishable key: the secret returned when the
              session was created.
          required: false
          description: >-
            Required with a publishable key: the secret returned when the
            session was created.
          name: client_secret
          in: query
      responses:
        '200':
          description: The session; with a publishable key, also where to collect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethodSessionRetrieved'
        '400':
          description: The session is no longer collecting (publishable key)
          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'
        '404':
          description: No such session in this workspace (secret key)
          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:
    PaymentMethodSessionRetrieved:
      allOf:
        - $ref: '#/components/schemas/PaymentMethodSession'
        - type: object
          properties:
            collect:
              $ref: '#/components/schemas/PaymentMethodSessionCollect'
    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
    PaymentMethodSession:
      type: object
      properties:
        object:
          type: string
          enum:
            - payment_method_session
        id:
          type: string
          example: pms_test_7Hs2kQ9mL1pXv4cR8tWzAbCd
        status:
          type: string
          enum:
            - requires_payment_method
            - succeeded
            - canceled
            - expired
          example: requires_payment_method
        customer:
          type:
            - string
            - 'null'
          format: uuid
          example: null
        payment_method_types:
          type: array
          items:
            type: string
            enum:
              - card
              - us_bank_account
          example:
            - card
        amount:
          type:
            - integer
            - 'null'
          example: null
          description: >-
            What a one-time bank debit will authorize, in the smallest unit of
            `currency`. Null on a card session and when a bank account is being
            saved.
        currency:
          type:
            - string
            - 'null'
          enum:
            - USD
          example: null
        livemode:
          type: boolean
          example: false
        expires_at:
          type: string
          format: date-time
          example: '2026-09-17T18:30:00.000Z'
        canceled_at:
          type:
            - string
            - 'null'
          format: date-time
          example: null
        succeeded_at:
          type:
            - string
            - 'null'
          format: date-time
          example: null
        card:
          $ref: '#/components/schemas/PaymentMethodSessionCard'
        us_bank_account:
          $ref: '#/components/schemas/PaymentMethodSessionBankAccount'
        ach_authorization:
          $ref: '#/components/schemas/PaymentMethodSessionAchAuthorization'
        payment_method:
          type:
            - string
            - 'null'
          example: null
          description: >-
            The payment method your server created from this session, once it
            did.
        created_at:
          type: string
          format: date-time
          example: '2026-09-17T18:00:00.000Z'
      required:
        - object
        - id
        - status
        - customer
        - payment_method_types
        - amount
        - currency
        - livemode
        - expires_at
        - canceled_at
        - succeeded_at
        - card
        - us_bank_account
        - ach_authorization
        - payment_method
        - created_at
    PaymentMethodSessionCollect:
      type: object
      properties:
        tokenizer_id:
          type: string
          example: tntabc123xyz
        environment:
          type: string
          enum:
            - sandbox
            - live
          example: sandbox
        host:
          type:
            - string
            - 'null'
          example: collect-sandbox.payra.com
      required:
        - tokenizer_id
        - environment
        - host
      description: >-
        Present only when retrieved with a publishable key and the session
        client_secret.
    PaymentMethodSessionCard:
      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 once the browser confirmed a card.
      example: null
    PaymentMethodSessionBankAccount:
      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
      required:
        - last4
        - account_type
        - account_holder_type
      description: Set once the browser confirmed a bank account.
      example: null
    PaymentMethodSessionAchAuthorization:
      type:
        - object
        - 'null'
      properties:
        scope:
          type: string
          enum:
            - single
            - standing
          example: single
          description: >-
            `single` authorizes one debit of `amount`; `standing` (a session
            with a customer) authorizes debits for amounts owed until revoked.
        terms_version:
          type: string
          example: 2026-08-21.v1
        short_text:
          type: string
          example: >-
            I authorize Northwind Traders to electronically debit the bank
            account provided for this one-time payment of $213.75, in accordance
            with the ACH Authorization.
          description: The sentence Payra Elements shows next to the checkbox.
        full_text:
          type: string
          description: The complete authorization, paragraphs separated by blank lines.
        accepted_at:
          type:
            - string
            - 'null'
          format: date-time
          example: null
          description: >-
            When the account holder accepted it, by the server clock; null until
            the session succeeds.
      required:
        - scope
        - terms_version
        - short_text
        - full_text
        - accepted_at
      description: >-
        On a `us_bank_account` session: the authorization shown to the account
        holder, and when they accepted it.
      example: null
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        A secret key, `sk_test_...` or `sk_live_...`; a publishable key
        (`pk_...`) on the browser routes only

````