---
title: "Request payment"
method: POST
path: "/payments/request"
tags: ["Payments"]
---

# Request payment

`POST /payments/request`

Create a payment request that creates a payment in 'requires_payment_method' status.

**gigstack Connect:** Create payment requests for other teams using the `team` parameter.

## Payment Request Flow

This endpoint creates a payment request that customers can complete using various payment methods.
The payment will be created with status 'requires_payment_method'.

## Allowed Payment Methods

Control which payment methods are available to the customer:

- **`card`**: Credit/debit card payments
- **`spei`**: Mexican bank transfer (SPEI)
- **`oxxo`**: OXXO convenience store payments
- **`stripe-spei`**: Customer balance payments

## Query parameters

- `team` string

## Request body

- RequestPaymentInput
  - `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
  - `send_email` boolean, nullable — Whether to send an email notification to the customer
  - `emails` string[], nullable — List of email addresses to send the payment request to
  - `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 latest rate from our rates collection will be used automatically.
  - `allowed_payment_methods` string[], required — Payment methods available to the customer: - `card`: Credit/debit card payments (requires Stripe integration) - `bank`: Mexican bank transfer (SPEI) - `oxxo`: OXXO convenience store payments (requires Stripe integration) - `stripe-spei`: Customer balance payments (requires Stripe integration)
  - `idempotency_key` string, nullable — Unique key to prevent duplicate payment requests
  - `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
  - `metadata` object, nullable — Additional metadata to store with the payment
  - `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.

## Response `200`

Payment request created successfully

- object
  - `message` string
  - `data` 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.
            - 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)
      - `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

---

[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)