---
title: "Register payment"
method: POST
path: "/payments/register"
tags: ["Payments"]
---

# Register payment

`POST /payments/register`

Register a payment with optional automation for invoice creation.

**gigstack Connect:** Register payments for other teams using the `team` parameter.

## Automation Types

Control what happens automatically when registering a payment:

- **`pue_invoice`**: Creates a PUE (Pago en Una sola Exhibición) invoice immediately
- **`none`**: No automation, registers payment only

## Payment Form

The `payment_form` field specifies the Mexican SAT payment form code:

Common codes include: `01` (cash), `02` (check), `03` (electronic transfer), `04` (credit card), etc.

The payment will be marked as 'succeeded' immediately upon registration.

## Query parameters

- `team` string

## Request body

- RegisterPaymentInput
  - `client` object, required
    - `id` string, nullable
    - `search` object
      - `on_key` string
      - `on_value` string
      - `auto_create` boolean
    - `address` ClientAddress, nullable
      - `country` string, nullable
      - `street` string, nullable
      - `zip` string, nullable
      - `city` string, nullable
      - `state` string, nullable
      - `exterior` string, nullable
      - `interior` string, nullable
      - `municipality` string, nullable
      - `neighborhood` string, nullable
    - `name` string, nullable
    - `company` string, nullable
    - `phone` string, nullable
    - `email` string, email, nullable
    - `bcc` string[]
    - `metadata` object
    - `legal_name` string, nullable
    - `tax_id` string, nullable
    - `use` string, nullable
    - `tax_system` string, nullable
  - `automation_type` 'pue_invoice' | 'ppd_invoice_and_complement' | 'none', nullable — 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
  - `currency` string, required — Currency code (ISO 4217)
  - `exchange_rate` number, nullable — 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.
  - `items` object[], required
    - `id` string, nullable
    - `search` object
      - `on_key` string
      - `on_value` string
      - `auto_create` boolean
    - `quantity` number, required
    - `description` string, nullable
    - `sku` string, nullable
    - `product_key` string, nullable
    - `unit_key` string, nullable
    - `unit_name` string, nullable
    - `unit_price` number, nullable
    - `taxes` TaxSchema[]
      - `base` union — Taxable base amount. Accepts number or numeric string. If null, calculated automatically from item price.
        - number
        - string
      - `factor` string, nullable
      - `inclusive` boolean, nullable
      - `rate` number, nullable
      - `type` 'IVA' | 'ISR' | 'IEPS', nullable
      - `withholding` boolean, nullable
    - `third_party` object
      - `legal_name` string, nullable
      - `tax_id` string, nullable
      - `tax_system` string, nullable
      - `zip` string, nullable
  - `payment_form` '01' | '02' | '03' | '04' | '05' | '06' | '08' | '12' | '13' | '14' | '15' | '17' | '23' | '24' | '25' | '26' | '27' | '28' | '29' | '30' | '31' | '99', required — 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
  - `metadata` object, nullable — Additional metadata to store with the payment
  - `idempotency_key` string, nullable — Unique key to prevent duplicate payment registrations. If a payment with this key already exists, the existing payment will be returned.
  - `date` number, nullable — Unix timestamp (in milliseconds) for when the payment was received. Must be in the past. Defaults to current time if not provided.
  - `invoice_config` object, nullable — Optional invoice configuration to force specific folio and/or serie for the invoice. If folio is null or not provided, the automatic incrementing folio will be used.
    - `serie` string, nullable — Invoice serie. Will set/create the series for the team if provided.
    - `folio` number, nullable — Invoice folio number. If null or not provided, uses automatic incrementing folio. Note: when provided, duplicates may occur.
  - `transfer_data` object, nullable — Configuration for splitting payments between master and connect teams in a marketplace. Only available for master teams with marketplace-enabled billing accounts.
    - `master` number — Percentage of the payment for the master team (0-100)
    - `connect` string — Tax ID (RFC) or Team ID of the connect team. If not found, a new team will be created.
    - `master_to` 'client' | 'connect' — 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
    - `connect_to` 'client' | 'master' — 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
    - `connect_custom_config` object, nullable — Optional configuration to customize items in the connect payment
      - `product_key` string — SAT product key to use for connect payment items
      - `unit_key` string — SAT unit key to use for connect payment items
      - `custom_description` string — Custom description for connect payment items
      - `custom_price` number — Fixed amount for connect payment (overrides percentage calculation). When set, connect gets this exact amount and master gets the remainder.
      - `taxes` object[] — Custom tax configuration for connect payment items (uses same schema as regular item taxes)
        - `type` 'IVA' | 'ISR' | 'IEPS', required — Tax type
        - `rate` number, required — Tax rate as decimal (0.16 = 16%)
        - `withholding` boolean, required — true = retention (deducted from total), false = regular tax (added to subtotal)
        - `base` number, nullable — Optional tax base amount
        - `factor` string, nullable — Optional tax factor
        - `inclusive` boolean, nullable — Whether tax is included in the price

## Response `200`

Payment registered successfully

- object
  - `message` string
  - `data` union
    - ApiPublicPayment
      - `id` string, required — Unique payment identifier
      - `client` ApiPublicClient, required
        - `id` string, required — Unique client identifier
        - `address` ClientAddress, nullable
          - `country` string, nullable
          - `street` string, nullable
          - `zip` string, nullable
          - `city` string, nullable
          - `state` string, nullable
          - `exterior` string, nullable
          - `interior` string, nullable
          - `municipality` string, nullable
          - `neighborhood` string, nullable
        - `name` string, nullable — Client name
        - `company` string, nullable — Client company name
        - `phone` string, nullable — Client phone number
        - `email` string, email, nullable, required — Client email address
        - `bcc` string[], nullable — BCC email addresses for client communications
        - `metadata` object, nullable — Additional metadata for the client
        - `is_valid` boolean, nullable — Whether the client data is valid
        - `from` string, required — Source of client creation
        - `legal_name` string, nullable — Legal name for tax purposes
        - `livemode` boolean, required — Whether this client is in live mode
        - `owner` string, required — User ID who owns this client
        - `tax_id` string, nullable — RFC (Tax ID) for Mexican tax compliance
        - `use` string, nullable — CFDI use code
        - `tax_system` string, nullable — SAT tax system code
        - `team` string, required — Team ID this client belongs to
        - `created_at` number, required — Unix timestamp of client creation
        - `efos` object, nullable — EFOS (SAT blacklist) validation status
          - `is_valid` boolean, nullable — Whether the client is valid according to SAT EFOS list
        - `defaults` object, nullable — Client default settings
          - `keep_full_legal_name` boolean, nullable — Keep full legal name in documents
          - `issue_automatic_invoices` boolean, nullable — Issue automatic invoices
          - `issue_invoiceable_receipts` boolean, nullable — Issue invoiceable receipts
      - `emails` string[], nullable — Email addresses to notify
      - `currency` string, required — Payment currency
      - `allowed_payment_methods` PaymentAllowedMethod[], nullable — Allowed payment methods
        - `id` string, required — Payment method identifier
      - `exchange_rate` number, required — Exchange rate used for currency conversion
      - `items` PaymentItem[], required — Items included in this payment
        - `id` string, nullable — Unique service identifier
        - `description` string, nullable — Service description
        - `from` string, nullable — Source of service creation
        - `sku` string, nullable — Stock Keeping Unit identifier
        - `product_key` string, nullable — SAT product key for tax compliance
        - `unit_key` string, nullable — SAT unit key for tax compliance
        - `unit_name` string, nullable — Unit name for the service
        - `unit_price` number, nullable — Price per unit
        - `taxes` TaxElement[], nullable — Tax configuration for this service
          - `base` union — Taxable base amount. Accepts number or numeric string. If null, calculated automatically from item price.
            - number
            - string
          - `factor` string, nullable — SAT tax factor (Tasa, Cuota, Exento)
          - `inclusive` boolean, nullable — Whether the tax is included in the unit price
          - `rate` number, required — Tax rate (e.g., 0.16 for 16% IVA)
          - `type` 'IVA' | 'ISR' | 'IEPS', required — Type of tax
          - `withholding` boolean, nullable — Whether this is a withholding tax
        - `team` string, required — Team ID this service belongs to
        - `created_at` number, required — Unix timestamp of service creation
        - `quantity` number, nullable — Quantity (used in transactions)
        - `third_party` ApiPublicThirdParty
          - `legal_name` string, required — Legal name of the third party
          - `tax_id` string, required — RFC (Tax ID) of the third party
          - `tax_system` string, required — SAT tax system code
          - `zip` string, required — Postal code of the third party
        - `search` ApiPublicSearch
          - `on_key` string, required — Field to search on
          - `on_value` string, required — Value to search for
          - `auto_create` boolean, required — Whether to create the resource if not found
          - `safety_check` boolean — When true, prevents using multiple matching results (returns error). When false, uses the first result found. Default: false
      - `metadata` object — Additional metadata for the payment
      - `invoice_config` ApiPublicInvoiceConfig
        - `serie` string, nullable — Invoice series
        - `folio` string, nullable — Invoice folio number
      - `team` string, required — Team ID this payment belongs to
      - `idempotency_key` string, required — Idempotency key to prevent duplicate payments
      - `from` string, required — Source of payment creation
      - `invoices` string[], required — Associated invoice IDs
      - `livemode` boolean, required — Whether this payment is in live mode
      - `owner` string, required — User ID who owns this payment
      - `payment_form` string, required — SAT payment form code
      - `payments` string[], required — Related payment IDs
      - `receipts` string[], required — Associated receipt IDs
      - `refunds` ApiPublicRefund[], required — Refunds associated with this payment
        - `id` string, required — Unique refund identifier
        - `items` ApiPublicService[], nullable — Items being refunded
          - `id` string, nullable — Unique service identifier
          - `description` string, nullable — Service description
          - `from` string, nullable — Source of service creation
          - `sku` string, nullable — Stock Keeping Unit identifier
          - `product_key` string, nullable — SAT product key for tax compliance
          - `unit_key` string, nullable — SAT unit key for tax compliance
          - `unit_name` string, nullable — Unit name for the service
          - `unit_price` number, nullable — Price per unit
          - `taxes` TaxElement[], nullable — Tax configuration for this service
            - `base` union — Taxable base amount. Accepts number or numeric string. If null, calculated automatically from item price.
              - …
            - `factor` string, nullable — SAT tax factor (Tasa, Cuota, Exento)
            - `inclusive` boolean, nullable — Whether the tax is included in the unit price
            - `rate` number, required — Tax rate (e.g., 0.16 for 16% IVA)
            - `type` 'IVA' | 'ISR' | 'IEPS', required — Type of tax
            - `withholding` boolean, nullable — Whether this is a withholding tax
          - `team` string, required — Team ID this service belongs to
          - `created_at` number, required — Unix timestamp of service creation
          - `quantity` number, nullable — Quantity (used in transactions)
        - `reason` string, required — Reason for the refund
        - `created_at` number, required — Unix timestamp of when the refund was created
        - `total` number, required — Total refund amount
      - `short_url` string, required — Short URL for payment page
      - `status` 'requires_payment_method' | 'succeeded' | 'canceled', required — Current payment status
      - `total` number, required — Total payment amount including taxes
      - `total_refunded` number, required — Total amount refunded
      - `subtotal` number, required — Subtotal before taxes
      - `taxes` number, required — Total tax amount
      - `discount` number, required — Discount applied
      - `withholding_taxes` number, required — Withholding taxes amount
      - `created_at` number, required — Unix timestamp of payment creation
      - `succeeded_at` number, nullable, required — Unix timestamp when payment succeeded
      - `payment_processor` string, required — Payment processor used
      - `payment_processor_details` ApiPublicPaymentProcessorDetails
    - object — Split payment result
      - `split_reference` string
      - `master_payment_id` string
      - `connect_payment_id` string
      - `master_amount` number
      - `connect_amount` number
      - `total_amount` number
      - `master_payment` object
      - `connect_payment` object
      - `connect_team` object, nullable
        - `id` string
        - `tax_id` string
        - `legal_name` string
        - `is_newly_created` boolean
        - `onboarding_url` string

## Other responses

- `400` — Bad Request - Invalid payment data or automation type
- `401` — Unauthorized
- `500` — Internal Server Error

---

[API](https://skmtc.dev/disruptive-learning/apis/gigstack-api-v2.md) · [All operations](https://skmtc.dev/disruptive-learning/apis/gigstack-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/disruptive-learning/gigstack-api-v2/revisions/5cf53ffd7580/schema)