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

# Get a payment batch

> Returns the batch: the items rejected up front, and the progress of the accepted ones in `counts`. Poll it
until `status` is `completed`, then read `result`, not `status`, to know how it went: `completed`
(everything registered), `partially_completed` (some items have no payment) or `failed` (none registered).

For each payment's outcome, page through `GET /payments/register/batch/{id}/items`.

A batch of another team, of the other mode (a live batch read with a test key), or an invoice batch
(`ibatch_…`) answers `404`. Under gigstack Connect, send the same `team` the batch was created with.




## OpenAPI

````yaml openapi.json GET /payments/register/batch/{id}
openapi: 3.0.3
info:
  title: gigstack API v2
  description: >
    # gigstack API v2


    Build customer, invoice and payment integrations. Start with the
    [quickstart](https://docs.gigstack.io/quickstart), then select the [issuing
    country](https://docs.gigstack.io/concepts/shared-fields).


    ## Authentication and environments


    Use Authorization: Bearer YOUR_API_KEY. Standard live and test keys use
    https://api.gigstack.io/v2. Internal staging uses
    https://gigstack-staging-9z9nnaat.uc.gateway.dev/v2 and separate keys. Test
    mode is a data mode within an environment; a body field does not switch a
    key's mode.


    See [authentication](https://docs.gigstack.io/authentication) for key
    handling, OAuth team scope and gigstack Connect. Internal partner
    provisioning is outside this public contract; health probes have their own
    security declarations. Operations marked unavailable have no configured
    public gateway route.


    ## Read the operation contract


    Response envelopes, pagination and retry rules differ by endpoint. HTTP
    success alone does not prove external fiscal completion or movement of
    money. Reconcile ambiguous writes before retrying. Use [responses and
    recovery](https://docs.gigstack.io/responses) and the operation's error
    codes; document credits and daily limits are not generic retryable rate
    limits.


    The issuing team's configuration selects Mexico or Colombia; customer
    country and currency do not. Read
    [Mexico](https://docs.gigstack.io/countries/mexico) or
    [Colombia](https://docs.gigstack.io/countries/colombia) before choosing
    fiscal fields. Accepted public input differs from a provider's direct
    payload.


    Examples and schema checks do not imply every operation has been executed
    live. [Verification coverage](https://docs.gigstack.io/verification)
    distinguishes source review, offline checks and observed staging behavior.
    Documentation describes operations and does not authorize execution.
  version: 2.0.0
  contact:
    name: Gigstack API Support
    url: https://gigstack.io
    email: support@gigstack.io
  license:
    name: Proprietary
    url: https://gigstack.io/terms
  termsOfService: https://gigstack.io/terms
servers:
  - url: https://api.gigstack.io/v2
    description: >
      Public API for standard live and test-mode keys. Test data is isolated by
      the key mode

      (`livemode: false`). Internal staging is a separate deployment and key
      store; see

      https://docs.gigstack.io/authentication#environments for its base URL.
security:
  - bearerAuth: []
externalDocs:
  description: Complete API Documentation & Guides
  url: https://docs.gigstack.io
paths:
  /payments/register/batch/{id}:
    get:
      tags:
        - Payments
      summary: Get a payment batch
      description: >
        Returns the batch: the items rejected up front, and the progress of the
        accepted ones in `counts`. Poll it

        until `status` is `completed`, then read `result`, not `status`, to know
        how it went: `completed`

        (everything registered), `partially_completed` (some items have no
        payment) or `failed` (none registered).


        For each payment's outcome, page through `GET
        /payments/register/batch/{id}/items`.


        A batch of another team, of the other mode (a live batch read with a
        test key), or an invoice batch

        (`ibatch_…`) answers `404`. Under gigstack Connect, send the same `team`
        the batch was created with.
      operationId: getPaymentRegisterBatch
      parameters:
        - $ref: '#/components/parameters/TeamParameter'
        - name: id
          in: path
          required: true
          description: Batch id, as returned by `POST /payments/register/batch`.
          schema:
            type: string
          example: pbatch_7f3a9c1e5b2d4f6a8c0e2a4b6d8f0a1c
      responses:
        '200':
          description: The batch.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/StandardSuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ApiPublicPaymentBatch'
              examples:
                processing:
                  summary: Still registering
                  value:
                    success: true
                    data:
                      id: pbatch_7f3a9c1e5b2d4f6a8c0e2a4b6d8f0a1c
                      object: payment_batch
                      livemode: true
                      status: processing
                      result: null
                      total: 120
                      accepted: 119
                      rejected:
                        - index: 7
                          idempotency_key: txn-2026-10-000130
                          error:
                            code: invalid_body
                            message: 'payment_form: Invalid enum value'
                      counts:
                        queued: 60
                        registered: 58
                        failed: 0
                        duplicate: 1
                      created_at: 1790780400000
                      completed_at: null
                    timestamp: 1790781000000
                partially_completed:
                  summary: Finished, some items have no payment
                  value:
                    success: true
                    data:
                      id: pbatch_7f3a9c1e5b2d4f6a8c0e2a4b6d8f0a1c
                      object: payment_batch
                      livemode: true
                      status: completed
                      result: partially_completed
                      total: 120
                      accepted: 119
                      rejected:
                        - index: 7
                          idempotency_key: txn-2026-10-000130
                          error:
                            code: invalid_body
                            message: 'payment_form: Invalid enum value'
                      counts:
                        queued: 0
                        registered: 117
                        failed: 1
                        duplicate: 1
                      created_at: 1790780400000
                      completed_at: 1790784000000
                    timestamp: 1790784060000
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AuthForbidden'
        '404':
          description: No payment batch with this id in your team and mode (`not_found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
              example:
                success: false
                error:
                  code: not_found
                  message: Payment batch not found
                timestamp: 1790781000000
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - bearerAuth: []
components:
  parameters:
    TeamParameter:
      name: team
      in: query
      required: false
      schema:
        type: string
      description: >
        **gigstack Connect:** Target team ID for multi-team access.


        Requires gigstack Connect enabled on your team and shared billing
        account.


        Also requires the `multipleIssuerAccounts` feature on your plan.
        Requests targeting a

        team other than the one your API key belongs to return `403` without it.


        Only API keys can use it: an OAuth access token sent with another team's
        id is rejected with

        `403 Team mismatch with OAuth token`.


        **Optional — omit it entirely** unless you are acting on another team.
        It deliberately

        carries no example value so generated snippets do not emit
        `?team=undefined`; when the

        parameter is absent, the team is derived from your API key.


        **Example:** `?team=team_xyz789`
  schemas:
    StandardSuccessResponse:
      type: object
      description: |
        Standardized success envelope emitted by `sendSuccessResponse`.
      required:
        - success
        - data
        - timestamp
      properties:
        success:
          type: boolean
          enum:
            - true
          example: true
        data:
          type: object
          description: The operation payload.
        message:
          type: string
          description: Human-readable summary. Present only when the handler supplies one.
          example: Operation completed successfully
        timestamp:
          type: integer
          format: int64
          description: Server time in **epoch milliseconds** (`Luxon.now().toMillis()`).
          example: 1767225600000
    ApiPublicPaymentBatch:
      type: object
      description: >
        A payment batch: how many payments it received, which were rejected up
        front, and the progress of the

        rest. Timestamps are epoch milliseconds.
      required:
        - id
        - object
        - livemode
        - status
        - result
        - total
        - accepted
        - rejected
        - counts
        - created_at
        - completed_at
      properties:
        id:
          type: string
          description: >
            Batch id. Derived from your team, the credential's mode and the
            `Idempotency-Key` you sent, so the

            same key always names the same batch. An invoice batch created under
            the same key has a

            different id (`ibatch_…`).
          pattern: ^pbatch_[0-9a-f]{32}$
          example: pbatch_7f3a9c1e5b2d4f6a8c0e2a4b6d8f0a1c
        object:
          type: string
          enum:
            - payment_batch
          example: payment_batch
        livemode:
          type: boolean
          description: >-
            Mode of the credential that created the batch. A test key only ever
            sees test batches.
          example: true
        status:
          $ref: '#/components/schemas/InvoiceBatchStatusEnum'
        result:
          allOf:
            - $ref: '#/components/schemas/InvoiceBatchResultEnum'
          description: >
            How a finished batch turned out. `null` while `status` is
            `processing`. `completed`: every item

            was registered (`registered`, or `duplicate` because it had been
            registered before) and nothing

            was rejected. `partially_completed`: at least one item was
            registered and at least one was not.

            `failed`: no item was registered.
        total:
          type: integer
          description: Payments in the request.
          example: 120
        accepted:
          type: integer
          description: Payments that passed validation and are processed.
          example: 119
        rejected:
          type: array
          description: >
            Payments refused by validation, in request order. Empty when every
            item was accepted. `error.code`

            is one of the invoice batch's (`invalid_item`,
            `idempotency_key_required`,

            `invalid_idempotency_key`, `duplicate_idempotency_key`,
            `invalid_body`, the last against the

            `POST /payments/register` body) or `transfer_data_not_supported`.
          items:
            $ref: '#/components/schemas/InvoiceBatchRejectedItem'
        counts:
          $ref: '#/components/schemas/PaymentBatchCounts'
        created_at:
          type: integer
          format: int64
          description: When the batch was created (epoch ms).
          example: 1790780400000
        completed_at:
          type: integer
          format: int64
          nullable: true
          description: >-
            When the last item reached a final status (epoch ms). `null` while
            `processing`.
          example: 1790784000000
    StandardErrorResponse:
      type: object
      description: >
        Standardized error envelope emitted by `sendErrorResponse` and its
        helpers

        (`sendValidationError`, `sendNotFoundError`, `sendUnauthorizedError`,

        `sendForbiddenError`, `sendConflictError`, `sendBadRequestError`,

        `sendInternalServerError`).
      required:
        - success
        - error
        - timestamp
      properties:
        success:
          type: boolean
          enum:
            - false
          example: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: >
                Stable machine-readable code. Values emitted by the shared
                helpers:

                `unauthorized`, `forbidden`, `invalid_token`,
                `validation_failed`,

                `invalid_request_body`, `missing_required_field`,
                `invalid_field_value`,

                `resource_not_found`, `resource_already_exists`,
                `resource_conflict`,

                `business_rule_violation`, `operation_not_allowed`,

                `insufficient_permissions`, `external_service_error`,

                `payment_processor_error`, `cfdi_service_error`,

                `internal_server_error`, `service_unavailable`,
                `rate_limit_exceeded`,

                `database_error`, `data_integrity_error`, `file_not_found`,

                `file_upload_error`, `invalid_file_format`. Individual handlers
                may

                emit additional endpoint-specific codes, documented per
                operation.
              example: validation_failed
            message:
              type: string
              example: Request validation failed
            details:
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
              description: >
                Present only when the handler supplies detail. Validation
                failures

                emit an array of `"<field path>: <message>"` strings.
              example:
                - 'currency: Field is required'
        timestamp:
          type: integer
          format: int64
          description: Server time in epoch milliseconds.
          example: 1767225600000
    InvoiceBatchStatusEnum:
      type: string
      description: >
        - `processing`: some accepted items are still queued.

        - `completed`: every accepted item has a final status. Read `result` to
        know how it went.
      enum:
        - processing
        - completed
      example: processing
    InvoiceBatchResultEnum:
      type: string
      nullable: true
      description: >
        How a finished batch turned out. `null` while `status` is `processing`.


        - `completed`: every item was issued (`stamped`, or `duplicate` because
        it had been issued before), and
          nothing was rejected.
        - `partially_completed`: at least one item was issued, and at least one
        was not (`failed`,
          `needs_review` or rejected up front).
        - `failed`: no item was issued.
      enum:
        - completed
        - partially_completed
        - failed
        - null
      example: partially_completed
    InvoiceBatchRejectedItem:
      type: object
      description: >-
        An item refused by validation when the batch was created. Nothing was
        stamped or charged for it.
      required:
        - index
        - idempotency_key
        - error
      properties:
        index:
          type: integer
          description: Position of the item in `invoices` (from 0).
          example: 17
        idempotency_key:
          type: string
          nullable: true
          description: >-
            The item's key, trimmed. `null` when the item was not an object or
            had no key.
          example: order-2026-09-000140
        error:
          allOf:
            - $ref: '#/components/schemas/InvoiceBatchError'
          description: >
            `code` is one of:


            - `invalid_item`: the item is not a JSON object.

            - `idempotency_key_required`: no `idempotency_key`, or an empty one.

            - `invalid_idempotency_key`: the key is longer than 256 characters.

            - `duplicate_idempotency_key`: an earlier item of this batch has the
            same key (the message names its index).

            - `invalid_body`: the item fails the `POST /invoices/income` body
            validation; the message lists
              each `path: message`.
    PaymentBatchCounts:
      type: object
      description: >
        Accepted items by status. `queued` is what is still in flight, so it
        reaches `0` when the batch completes.

        The four counts add up to `accepted`; rejected items are not counted
        here.
      required:
        - queued
        - registered
        - failed
        - duplicate
      properties:
        queued:
          type: integer
          description: Waiting for, or in, a registration attempt.
          example: 0
        registered:
          type: integer
          description: Registered by this batch.
          example: 117
        failed:
          type: integer
          description: Ended without a payment. See each item's `error`.
          example: 1
        duplicate:
          type: integer
          description: >-
            Already registered under the same `idempotency_key` before; not
            registered again.
          example: 1
    AuthMiddlewareError:
      type: object
      description: >
        Raw error body produced by the authentication layer (before any endpoint
        runs). It is not

        the standardized envelope: there is no `success` and no `timestamp`.
      required:
        - message
      properties:
        message:
          type: string
          description: >-
            Human-readable reason. Some messages are in Spanish; branch on the
            HTTP status, not on this text.
          example: Unauthorized
        error:
          type: string
          description: >-
            OAuth error code. Present only when an OAuth access token was
            presented.
          enum:
            - invalid_token
            - token_expired
            - token_revoked
            - server_error
          example: token_expired
        error_description:
          type: string
          description: Same text as `message`. Present only alongside `error`.
          example: Access token has expired. Please refresh your token.
        details:
          description: >-
            Extra detail, e.g. `Invalid API Key` when a revoked key is rejected
            with `403`.
          oneOf:
            - type: string
            - type: object
          example: Invalid API Key
    UnauthorizedError:
      allOf:
        - $ref: '#/components/schemas/StandardErrorResponse'
      example:
        success: false
        error:
          code: unauthorized
          message: Unauthorized access
        timestamp: 1767225600000
    InvoiceBatchError:
      type: object
      description: Why an item was rejected or did not produce an invoice.
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: >-
            Machine-readable reason. See the operation descriptions for the
            possible values.
          example: CFDI40147
        message:
          type: string
          description: >-
            Human-readable reason, at most 500 characters. Stamping errors are
            in Spanish, as on `POST /invoices/income`.
          example: 'Error al timbrar la factura: El campo UsoCFDI no es válido'
  responses:
    Unauthorized:
      description: >
        Authentication failed. Two different bodies can come back with a `401`:


        1. **From the authentication layer**, before the endpoint runs: a raw
        object with
           `message` and — for OAuth access tokens only — `error` / `error_description`. It does
           **not** use the standardized envelope (`success` and `timestamp` are absent). Messages:
           `Unauthorized` (missing header, missing `Bearer ` prefix, unparseable token),
           `Unauthorized, missing team in token`, `Unauthorized, not a master team` and
           `Unauthorized, no matched teams` (gigstack Connect), `Invalid access token`,
           `Access token has expired. Please refresh your token.`, `Access token has been revoked`.
        2. **From the endpoint itself**: the standardized envelope with
        `error.code: unauthorized`.


        Branch on the HTTP status, not on the body shape.
      content:
        application/json:
          schema:
            anyOf:
              - $ref: '#/components/schemas/AuthMiddlewareError'
              - $ref: '#/components/schemas/UnauthorizedError'
          examples:
            missing_or_invalid_key:
              summary: Authentication layer — missing or unparseable API key
              value:
                message: Unauthorized
            oauth_token_expired:
              summary: Authentication layer — expired OAuth access token
              value:
                message: Access token has expired. Please refresh your token.
                error: token_expired
                error_description: Access token has expired. Please refresh your token.
            connect_not_master_team:
              summary: >-
                Authentication layer — `team` sent by a team without gigstack
                Connect
              value:
                message: Unauthorized, not a master team
            endpoint_envelope:
              summary: Endpoint — standardized envelope
              value:
                success: false
                error:
                  code: unauthorized
                  message: Unauthorized access
                timestamp: 1767225600000
    AuthForbidden:
      description: >
        Rejected by the authentication layer after the credential was
        recognised. The body is a raw

        object (`message`, sometimes `details`), **not** the standardized
        envelope. Causes:


        - The API key was revoked or disabled: `message: "API Key inválida."`,
        `details: "Invalid API Key"`.

        - The billing account's plan does not include API access. `message` is a
        Spanish sentence
          containing an HTML link to `https://app.gigstack.pro/memberships`. Branch on the status
          code; do not display or match the text.
        - gigstack Connect: the plan lacks the `multipleIssuerAccounts` feature
        (Spanish message
          starting `Tu plan no incluye múltiples cuentas emisoras.`), or an OAuth access token was
          sent with a `team` other than its own (`Team mismatch with OAuth token`).

        An endpoint may also answer `403` for its own reasons; those are
        documented on the

        operation when they exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthMiddlewareError'
          examples:
            revoked_api_key:
              summary: API key revoked or disabled
              value:
                message: API Key inválida.
                details: Invalid API Key
            plan_without_api_access:
              summary: Plan does not include API access
              value:
                message: >-
                  La API se encuentra disponible para un plan más grande, por
                  favor actualiza tu plan <a
                  href='https://app.gigstack.pro/memberships'>aquí</a> o ponte
                  en contacto con soporte.
            connect_plan_without_multiple_issuers:
              summary: gigstack Connect — plan lacks multipleIssuerAccounts
              value:
                message: >-
                  Tu plan no incluye múltiples cuentas emisoras. Actualiza tu
                  plan en https://app.gigstack.pro/memberships o ponte en
                  contacto con soporte para operar sobre otros equipos.
            oauth_team_mismatch:
              summary: gigstack Connect — OAuth token used for another team
              value:
                message: Team mismatch with OAuth token
    ServerError:
      description: >-
        Unexpected server error (`error.code: internal_server_error`). The
        failure is logged on gigstack's side.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StandardErrorResponse'
          example:
            success: false
            error:
              code: internal_server_error
              message: An internal server error occurred
            timestamp: 1767225600000
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        **Authentication Method:** HTTP Bearer token.


        The runtime requires the literal `Bearer ` prefix — a bare token in the

        `Authorization` header is rejected with `401 unauthorized`.


        **Header Format:** `Authorization: Bearer YOUR_API_KEY`


        Your API key is a JWT. Live keys operate on live data (`livemode:
        true`);

        test keys operate on isolated test data (`livemode: false`).


        **Get your key at:**
        [app.gigstack.pro/settings?tab=api](https://app.gigstack.pro/settings?tab=api)


        **Errors:** credential failures are answered by the authentication layer
        with a raw

        `{ "message": … }` body, not the standardized envelope — `401` for a
        missing, malformed or

        expired token, `403` for a revoked key or a plan without API access. See
        the `Unauthorized`

        and `AuthForbidden` responses.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.