> ## 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. # Register a batch of payments > Accepts up to **10,000** payments in one request and registers them in the background. Each item is exactly the body of `POST /payments/register`, and must carry its own `idempotency_key`, unique within the batch. To register more than 10,000 payments, send more batches, each with its own `Idempotency-Key`. **What happens in the request.** Every item is validated against the `POST /payments/register` body schema, with no I/O. An invalid item is listed in `rejected` with its reason and the rest go ahead; only an empty or missing `payments` array, or more than 10,000 items, refuses the whole request (`400`). The answer is `202` with the batch in `processing`; the first items may already have started. **What happens after.** Each accepted item is registered by the same code as `POST /payments/register`, with the credential that created the batch, so it fails for the same reasons (a client or service that does not resolve, a date in the future, a currency with no exchange rate) and triggers the same automations (`automation_type`, `ppd_invoice_id`). A temporary failure is retried automatically, up to 6 attempts per item. Items run about 10 at a time per team, sharing the queue with the team's income invoice batches, and a worker pauses about a second after each payment whose automation stamps an invoice, so a large batch reaches proserver at a few stamps a second. Follow the batch with `GET /payments/register/batch/{id}`, or subscribe a webhook to `payment_batch.completed` (body `PaymentBatchCompletedWebhookEvent`, signed, sent once and never retried; see the `webhookEvent` callback of `POST /webhooks`), then read the per-item results with `GET /payments/register/batch/{id}/items`. **Two levels of idempotency.** - The `Idempotency-Key` header names the **batch**. The batch id is derived from your team, the credential's mode and the header, so the same key with the same body returns the same batch (`200`), and nothing is created again. The same key with a different body is `409` `idempotency_key_reused`. Bodies are compared as sent, including key order, so resend the exact same JSON. - Each item's `idempotency_key` names the **payment**. It is the same key `POST /payments/register` uses: a payment already registered under it, by an earlier batch or a single call, is not registered again, and the item ends `duplicate`. So a new batch that repeats items of a previous one is safe. **gigstack Connect:** create the batch for a connected team with the `team` parameter, and read it with the same `team`. **Mode.** `livemode` comes only from the credential: a test key creates a test batch. Not supported here: split payments (`transfer_data`), which are rejected per item; register those one at a time with `POST /payments/register`. ## OpenAPI ````yaml openapi.json POST /payments/register/batch 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: post: tags: - Payments summary: Register a batch of payments description: > Accepts up to **10,000** payments in one request and registers them in the background. Each item is exactly the body of `POST /payments/register`, and must carry its own `idempotency_key`, unique within the batch. To register more than 10,000 payments, send more batches, each with its own `Idempotency-Key`. **What happens in the request.** Every item is validated against the `POST /payments/register` body schema, with no I/O. An invalid item is listed in `rejected` with its reason and the rest go ahead; only an empty or missing `payments` array, or more than 10,000 items, refuses the whole request (`400`). The answer is `202` with the batch in `processing`; the first items may already have started. **What happens after.** Each accepted item is registered by the same code as `POST /payments/register`, with the credential that created the batch, so it fails for the same reasons (a client or service that does not resolve, a date in the future, a currency with no exchange rate) and triggers the same automations (`automation_type`, `ppd_invoice_id`). A temporary failure is retried automatically, up to 6 attempts per item. Items run about 10 at a time per team, sharing the queue with the team's income invoice batches, and a worker pauses about a second after each payment whose automation stamps an invoice, so a large batch reaches proserver at a few stamps a second. Follow the batch with `GET /payments/register/batch/{id}`, or subscribe a webhook to `payment_batch.completed` (body `PaymentBatchCompletedWebhookEvent`, signed, sent once and never retried; see the `webhookEvent` callback of `POST /webhooks`), then read the per-item results with `GET /payments/register/batch/{id}/items`. **Two levels of idempotency.** - The `Idempotency-Key` header names the **batch**. The batch id is derived from your team, the credential's mode and the header, so the same key with the same body returns the same batch (`200`), and nothing is created again. The same key with a different body is `409` `idempotency_key_reused`. Bodies are compared as sent, including key order, so resend the exact same JSON. - Each item's `idempotency_key` names the **payment**. It is the same key `POST /payments/register` uses: a payment already registered under it, by an earlier batch or a single call, is not registered again, and the item ends `duplicate`. So a new batch that repeats items of a previous one is safe. **gigstack Connect:** create the batch for a connected team with the `team` parameter, and read it with the same `team`. **Mode.** `livemode` comes only from the credential: a test key creates a test batch. Not supported here: split payments (`transfer_data`), which are rejected per item; register those one at a time with `POST /payments/register`. operationId: createPaymentRegisterBatch parameters: - $ref: '#/components/parameters/TeamParameter' - name: Idempotency-Key in: header required: true description: > Your identifier for this batch, 8-128 characters of `A-Z a-z 0-9 . _ : -`. Reusing it with the same body returns the batch it first created; reusing it with a different body is `409 idempotency_key_reused`. schema: type: string minLength: 8 maxLength: 128 pattern: ^[A-Za-z0-9._:-]{8,128}$ example: settlement-2026-10-22-part-1 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PaymentBatchCreateInput' example: payments: - idempotency_key: txn-2026-10-000123 automation_type: pue_invoice currency: MXN payment_form: '03' date: 1790700000000 client: id: client_1234567890 items: - id: service_1234567890 quantity: 1 unit_price: 1000 metadata: order_id: ORD-000123 - idempotency_key: txn-2026-10-000124 automation_type: none currency: MXN payment_form: '01' client: id: client_0987654321 items: - description: Annual support plan product_key: '81111811' unit_key: E48 unit_price: 2500 quantity: 1 taxes: - type: IVA rate: 0.16 factor: Tasa withholding: false responses: '200': description: > Retry of an earlier request with the same `Idempotency-Key` and the same body: the batch it created, as it is now. Nothing is created again. If the first request died while writing the batch, this request finishes creating it. content: application/json: schema: allOf: - $ref: '#/components/schemas/StandardSuccessResponse' - type: object properties: data: $ref: '#/components/schemas/ApiPublicPaymentBatch' example: 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 '202': description: > Batch created. `status` is `processing`; the accepted items are being registered in the background. Items refused by validation are in `rejected` and will not be registered. A batch in which every item was rejected has nothing to do and is usually already `completed`, with `result: failed`. content: application/json: schema: allOf: - $ref: '#/components/schemas/StandardSuccessResponse' - type: object properties: data: $ref: '#/components/schemas/ApiPublicPaymentBatch' example: 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: 119 registered: 0 failed: 0 duplicate: 0 created_at: 1790780400000 completed_at: null timestamp: 1790780401250 '400': description: > The request was refused and no batch was created. `error.code`: - `invalid_request_body`: the `Idempotency-Key` header is missing or malformed. - `invalid_body`: the body is not `{ "payments": [ … ] }` with at least one item. - `too_many_items`: more than 10,000 items. Split them into several batches. Problems with a single item don't refuse the request; they are listed in the batch's `rejected`. content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' examples: missing_idempotency_key: summary: Idempotency-Key header missing value: success: false error: code: invalid_request_body message: Idempotency-Key header is required timestamp: 1790780400000 invalid_body: summary: No payments array value: success: false error: code: invalid_body message: >- Body must be { "payments": [ ... ] } with at least one payment timestamp: 1790780400000 too_many_items: summary: More than 10,000 payments value: success: false error: code: too_many_items message: >- A batch holds at most 10000 payments; send the rest in more batches timestamp: 1790780400000 '401': $ref: '#/components/responses/Unauthorized' '403': description: > Either the authentication layer refused the credential (raw body, see `AuthForbidden`), or a user-scoped token (MCP, dashboard) lacks `editor` permission on payments (standardized envelope, `forbidden`). API keys and OAuth tokens act as the team and are not role-checked. content: application/json: schema: anyOf: - $ref: '#/components/schemas/StandardErrorResponse' - $ref: '#/components/schemas/AuthMiddlewareError' examples: missing_payments_permission: summary: User-scoped token without editor permission on payments value: success: false error: code: forbidden message: This action requires editor access to payments timestamp: 1790780400000 revoked_api_key: summary: Authentication layer - API key revoked or disabled value: message: API Key inválida. details: Invalid API Key '409': description: > `idempotency_key_reused`: the `Idempotency-Key` was already used with a **different body**. Nothing was created. Send the new body under a new key; to read the original batch, use `GET /payments/register/batch/{id}`. content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' example: success: false error: code: idempotency_key_reused message: >- This Idempotency-Key was already used with a different body. Use a new key for a different batch. timestamp: 1790780400000 '500': description: > Unexpected failure (`internal_server_error`). Retrying with the **same** `Idempotency-Key` and body is safe: it returns the batch if it was created, or creates it. content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' example: success: false error: code: internal_server_error message: An internal server error occurred timestamp: 1790780400000 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: PaymentBatchCreateInput: type: object description: > Up to 10,000 payments to register. Each item is **exactly** the body of `POST /payments/register`, and must carry its own `idempotency_key`, unique within the batch. Items are validated one by one: an invalid item is listed in the batch's `rejected` and the others go ahead. Only a body without a non-empty `payments` array (`invalid_body`) or with more than 10,000 items (`too_many_items`) refuses the whole request. `livemode`, `team` and `owner` in an item are ignored (they come from the credential). `transfer_data` (a split payment) is not accepted in a batch: the item is rejected with `transfer_data_not_supported`. Keep the whole JSON body under 20 MB. required: - payments properties: payments: type: array minItems: 1 maxItems: 10000 description: >- The payments, in the order you want them reported. An item's `index` is its position here (from 0). items: $ref: '#/components/schemas/PaymentBatchItemInput' 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 `": "` strings. example: - 'currency: Field is required' timestamp: type: integer format: int64 description: Server time in epoch milliseconds. example: 1767225600000 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 PaymentBatchItemInput: description: >- One payment of a batch. The body of `POST /payments/register`, with `idempotency_key` required. allOf: - $ref: '#/components/schemas/RegisterPaymentInput' - type: object required: - idempotency_key properties: idempotency_key: type: string minLength: 1 maxLength: 256 description: > Your identifier for this payment (for example your order or transaction id), unique within the batch. Surrounding spaces are trimmed. It is the same key as on `POST /payments/register`, so a payment already registered under it, by an earlier batch or a single call, is not registered again: the item ends `duplicate`. example: txn-2026-10-000123 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 UnauthorizedError: allOf: - $ref: '#/components/schemas/StandardErrorResponse' example: success: false error: code: unauthorized message: Unauthorized access timestamp: 1767225600000 RegisterPaymentInput: description: > Unknown top-level keys are rejected (`400 validation_failed` / `unexpected_key`). `team`, `livemode` and `owner` are reserved and injected by the auth middleware. type: object additionalProperties: false required: - client - automation_type - currency - items - payment_form properties: client: $ref: '#/components/schemas/EmbeddedClientInput' automation_type: description: > Payment automation type: - `pue_invoice`: Create PUE (Pago en Una sola Exhibición) invoice immediately when payment succeeds - `ppd_invoice_and_complement`: Create PPD (Pago en Parcialidades o Diferido) invoice immediately, then payment complement when payment succeeds - `none`: No automation, register payment only example: pue_invoice type: string enum: - pue_invoice - ppd_invoice_and_complement - none currency: description: Currency code (ISO 4217) example: MXN type: string exchange_rate: description: >- Exchange rate for currency conversion. If not provided, the rate from the payment date (or current date if no date specified) will be fetched automatically from our rates collection. example: 1 type: number nullable: true idempotency_key: description: >- Stable key for one business event. A duplicate returns HTTP 400 with error.code resource_conflict, not the existing payment as a successful response. Reconcile the existing record and retain this key; do not create a new key for a retry. Required on every item of `POST /payments/register/batch`. example: payment-register-12345 type: string nullable: true items: type: array items: $ref: '#/components/schemas/ItemSchema' minItems: 1 payment_form: description: | Mexican SAT payment form code: - `01`: Cash - `02`: Check - `03`: Electronic transfer - `04`: Credit card - `05`: Electronic money - `06`: Digital money - `08`: Gift voucher - `12`: Credit for unregistered bills - `13`: Payment by subrogation - `14`: Payment by consignment - `15`: Condonation - `17`: Compensation - `23`: Novation - `24`: Confusion - `25`: Remission of debt - `26`: Prescription or expiration - `27`: To creditor's satisfaction - `28`: Credit card - `29`: Debit card - `30`: Service card - `31`: Applicable only to the complementary concept of donations - `99`: To be defined example: '03' type: string enum: - '01' - '02' - '03' - '04' - '05' - '06' - '08' - '12' - '13' - '14' - '15' - '17' - '23' - '24' - '25' - '26' - '27' - '28' - '29' - '30' - '31' - '99' metadata: description: Additional metadata to store with the payment type: object additionalProperties: true properties: {} nullable: true invoice_config: description: > Optional invoice configuration. Every field is optional. Controls the folio/serie the generated invoice will use, its issue date, the global (EOM) period it belongs to, and how long the self-invoicing window stays open. type: object additionalProperties: false properties: serie: description: >- Invoice serie. Will set/create the series for the team if provided. example: A type: string nullable: true folio: description: >- Invoice folio number. If omitted, the automatic incrementing folio is used. When provided, duplicates may occur. example: 123 type: number nullable: true date: description: >- Invoice issue date as a Unix epoch timestamp in **milliseconds**. example: 1767225600000 type: number nullable: true global: description: >- Period of the global (factura global / EOM) invoice this document belongs to. type: object additionalProperties: false properties: year: description: Fiscal year, four digits. example: 2026 type: number nullable: true months: description: > SAT `c_Meses` code. `01`–`12` for a single month; `13`–`18` for the bimonthly periods (`13` = Jan–Feb … `18` = Nov–Dec). example: '01' type: string nullable: true periodicity: description: > SAT `c_Periodicidad` code: `01` daily, `02` weekly, `03` fortnightly, `04` monthly, `05` bimonthly. example: '04' type: string nullable: true nullable: true validUntil: description: >- Expiry of the self-invoicing window, Unix epoch **milliseconds**. example: 1769817600000 type: number nullable: true nullable: true date: description: >- Unix epoch timestamp in **milliseconds** (13 digits) for when the payment was received. Must be in the past. Defaults to now. example: 1767225600000 type: number nullable: true send_email: description: > Accepted for compatibility, but on this endpoint it has **no effect** — only `ignore_emails` is persisted onto the payment. Use `ignore_emails` to suppress mail. example: true type: boolean nullable: true ignore_emails: description: > Suppress email and WhatsApp notifications for this payment and any documents it automates (invoices, receipts). Defaults to `false`. example: false type: boolean nullable: true ppd_invoice_id: description: >- UUID of an existing PPD invoice to link this payment to. When provided, a payment complement (complemento de pago) will be automatically generated and linked to the PPD invoice. The referenced invoice must have payment_method='PPD', status='valid' and invoice_type='I' — a payment complement only ever settles an income CFDI, never an egress one. example: invoice_ppd_1234567890 type: string nullable: true transfer_data: description: > Configuration for splitting payments between master and connect teams in a marketplace. Only available for master teams with marketplace-enabled billing accounts. **All-or-nothing:** the object itself is optional, but when it is present `master`, `connect`, `master_to` and `connect_to` are **all required**. Sending `transfer_data` with any of them missing fails validation with `400 validation_failed`. `connect_custom_config` stays optional. type: object additionalProperties: false required: - master - connect - master_to - connect_to properties: master: description: >- Required when `transfer_data` is present. Percentage of the payment retained by the master team. Must be between 0 and 100 inclusive. example: 10 type: number minimum: 0 maximum: 100 connect: description: >- Required when `transfer_data` is present. Tax ID (RFC) or Team ID of the connect team. If not found, a new team will be created. example: ABC123456789 type: string minLength: 1 master_to: description: > Determines which client to assign to the master payment: - `client`: Use the original client from the request - `connect`: Create the connect team as a client for the master payment example: client type: string enum: - client - connect connect_to: description: > Determines which client to assign to the connect payment: - `client`: Use the original client from the request - `master`: Create the master team as a client for the connect payment example: client type: string enum: - client - master connect_custom_config: description: Optional configuration to customize items in the connect payment type: object additionalProperties: false properties: product_key: description: SAT product key to use for connect payment items example: '01010101' type: string nullable: true unit_key: description: SAT unit key to use for connect payment items example: E48 type: string nullable: true taxes: description: >- Custom tax configuration for connect payment items (uses same schema as regular item taxes) type: array items: type: object additionalProperties: false required: - type - rate - withholding properties: type: description: Tax type example: IVA type: string enum: - IVA - ISR - IEPS rate: description: Tax rate as decimal (0.16 = 16%) example: 0.16 type: number withholding: description: >- true = retention (deducted from total), false = regular tax (added to subtotal) example: false type: boolean base: description: Optional tax base amount type: number nullable: true factor: description: Optional tax factor example: Tasa type: string nullable: true inclusive: description: Whether tax is included in the price type: boolean nullable: true nullable: true custom_description: description: Custom description for connect payment items example: Professional consulting services type: string nullable: true custom_price: description: >- Fixed amount for connect payment (overrides percentage calculation). When set, connect gets this exact amount and master gets the remainder. example: 250 type: number nullable: true minimum: 0 nullable: true nullable: true 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' EmbeddedClientInput: type: object additionalProperties: false properties: id: type: string nullable: true search: type: object additionalProperties: false required: - on_key - on_value properties: on_key: type: string on_value: type: string auto_create: type: boolean nullable: true safety_check: type: boolean nullable: true update: type: boolean nullable: true nullable: true address: additionalProperties: false properties: country: maxLength: 3 type: string nullable: true street: type: string nullable: true zip: type: string nullable: true city: type: string nullable: true state: type: string nullable: true exterior: type: string nullable: true interior: type: string nullable: true municipality: type: string nullable: true neighborhood: type: string nullable: true type: object nullable: true name: type: string nullable: true company: type: string nullable: true phone: type: string nullable: true email: type: string nullable: true bcc: type: array items: type: string metadata: type: object additionalProperties: true properties: {} legal_name: type: string nullable: true tax_id: type: string nullable: true use: type: string nullable: true tax_system: type: string nullable: true document_type: description: DIAN identification document code type: string enum: - '' - '11' - '12' - '13' - '21' - '22' - '31' - '41' - '42' - '47' - '48' - '50' - '91' - null nullable: true organization_type: description: 1 = persona jurídica, 2 = persona natural oneOf: - type: string enum: - '' - '1' - '2' - null nullable: true - type: number enum: - 1 - 2 tribute_code: description: '''01'' = responsable de IVA, ''ZZ'' = no aplica' type: string enum: - '' - '01' - ZZ - null nullable: true fiscal_responsibilities: description: >- DIAN responsabilidades fiscales (lista 53). Omitted means 'R-99-PN' (no responsable) type: array items: type: string enum: - O-13 - O-15 - O-23 - O-47 - R-99-PN nullable: true dv: description: NIT verification digit type: string nullable: true pattern: ^[0-9]?$ municipality_code: description: DANE municipality code, only for clients domiciled in Colombia type: string nullable: true pattern: ^([0-9]{5})?$ ItemSchema: description: > A line item on an invoice, receipt or payment. Only `quantity` is required; everything else is optional, or resolved from the referenced service when `id`/`search` is used. `id` and `search` are mutually exclusive — supplying both is a `400`. Unknown keys are rejected. Note there is no per-item `metadata` field. type: object additionalProperties: false required: - quantity properties: id: description: Service/product ID reference example: service_1234567890 type: string nullable: true search: type: object additionalProperties: false required: - on_key - on_value properties: on_key: description: Field to search on (sku, name, etc.) example: sku type: string on_value: description: Value to search for example: CONS-001 type: string auto_create: description: Create service if not found example: true type: boolean nullable: true safety_check: description: >- When true, prevents using multiple matching results (returns error). When false, uses the first result found. Default: false example: false type: boolean nullable: true update: type: boolean nullable: true nullable: true quantity: description: Item quantity example: 1 type: number description: description: Item description example: Consulting services type: string nullable: true sku: description: Stock keeping unit example: CONS-001 type: string nullable: true product_key: description: SAT product key (c_ClaveProdServ) example: '80141503' type: string nullable: true unit_key: description: SAT unit key (c_ClaveUnidad) example: E48 type: string nullable: true unit_name: description: Unit name example: Servicio type: string nullable: true unit_price: description: Unit price example: 1000 type: number nullable: true discount: description: >- Discount amount (absolute value in the item currency, not a percentage) example: 0 type: number nullable: true taxability: description: SAT `c_ObjetoImp` — whether the item is subject to tax. example: '02' type: string enum: - '01' - '02' - '03' - '04' - '05' - '06' - '07' - '08' - null nullable: true taxes: description: Tax elements applied to this item type: array items: type: object additionalProperties: false properties: base: description: >- Taxable base amount. Accepts number or numeric string. If null, calculated automatically from item price. example: 100 oneOf: - type: number nullable: true - type: string description: Numeric string accepted by the request validator. factor: type: string nullable: true example: Tasa description: SAT tax factor (Tasa, Cuota, Exento) inclusive: type: boolean nullable: true example: false description: Whether the tax is included in the unit price rate: description: Tax rate (e.g., 0.16 for 16% IVA) example: 0.16 type: number nullable: true type: description: Type of tax example: IVA type: string enum: - IVA - ISR - IEPS - null nullable: true withholding: type: boolean nullable: true example: false description: Whether this is a withholding tax nullable: true third_party: description: Third party information for items provided by external parties type: object additionalProperties: false properties: legal_name: description: Third party legal name example: Third Party SA type: string nullable: true tax_id: description: Third party RFC (tax ID) example: TPR800101ABC type: string nullable: true tax_system: description: Third party tax system example: '601' type: string nullable: true zip: description: Third party ZIP code example: '03100' type: string nullable: true nullable: true item_complement: description: CFDI item-level complement. type: object additionalProperties: false properties: hydrocarbons: description: >- Complemento de hidrocarburos. All four fields are required when this object is present. type: object additionalProperties: false required: - permit_type - permit_number - fuel_code - fuel_sub_product properties: permit_type: example: PL/12345/EXP/ES/2020 type: string permit_number: example: '12345' type: string fuel_code: example: PR03 type: string fuel_sub_product: example: '10' type: string nullable: true nullable: true 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 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.