Request payment

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

allowed_payment_methods is required. The validator accepts exactly these five values:

card — credit/debit card

bank — Mexican bank transfer (SPEI)

oxxo — OXXO convenience store

stripe-spei — Stripe customer balance

mercadopago-wallet — Mercado Pago wallet

The handler then narrows the list per processor and rejects anything outside the
processor's own set:

`payment_processor`	accepted methods	currency
`stripe` (default)	`card`, `oxxo`, `bank`, `stripe-spei`	any
`mercadopago`	`card`, `oxxo`, `mercadopago-wallet`	`MXN` only
`openpay`	`card`, `bank_account`, `store`	`MXN` only
`pagoralia`	`hosted`, `card`, `oxxo`	`MXN` only
`conekta`	`hosted`, `card`, `oxxo`, `spei`	`MXN` only

The processor-specific names in the right-hand column (bank_account, store,
hosted, spei) are not accepted by body validation — only the five enum values
above pass, so those processors are effectively limited to their overlap with the enum.

Required fields

client, currency, allowed_payment_methods, items and automation_type are
all required. automation_type has no default: omitting it fails validation with
missing_required. Allowed values: pue_invoice, ppd_invoice_and_complement, none.

Email suppression

ignore_emails takes precedence over send_email: the handler stores
ignore_emails ?? (send_email === false), so ignore_emails: true suppresses
notifications regardless of send_email.

Unknown fields

Body validation runs in strict allowlist mode — any key not declared in the schema is
rejected with 400 validation_failed / unexpected_key.

curl --location 'https://api.gigstack.io/v2/payments/request?team=undefined' \ --header 'Authorization: <api-key>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client": { "id": "client_1234567890" }, "automation_type": "pue_invoice", "currency": "MXN", "exchange_rate": 1, "allowed_payment_methods": [ "card", "bank", "oxxo" ], "items": [ { "id": "service_1234567890", "quantity": 1, "unit_price": 1000 } ], "send_email": true, "emails": [ "customer@example.com" ] }'

{ "message": "Payment request created successfully", "data": { "id": "payment_1234567890", "client": { "id": "client_1234567890", "name": "Juan Pérez García", "email": "juan.perez@ejemplo.com", "tax_id": "PEGJ800101ABC", "from": "api", "livemode": true, "owner": "user_1234567890", "team": "team_1234567890", "created_at": 1767225600000 }, "status": "requires_payment_method", "currency": "MXN", "exchange_rate": 1, "allowed_payment_methods": [ { "id": "card" }, { "id": "bank" }, { "id": "oxxo" } ], "short_url": "https://pay.gigstack.io/p/abc123", "total": 1160, "subtotal": 1000, "taxes": 160, "discount": 0, "items": [ { "id": "service_1234567890", "description": "Professional consulting services", "quantity": 1, "unit_price": 1000, "product_key": "80141503", "unit_key": "E48", "team": "team_1234567890", "created_at": 1767225600000 } ], "emails": [ "customer@example.com" ], "created_at": 1677651234, "payment_processor": "api", "livemode": true, "team": "team_1234567890", "owner": "user_1234567890", "from": "api", "refunds": [], "total_refunded": 0, "withholding_taxes": 0, "succeeded_at": 1767225600000, "payment_form": "", "idempotency_key": "", "invoices": [], "payments": [], "receipts": [] } }

Payment Request Flow#

Allowed Payment Methods#

Required fields#

Email suppression#

Unknown fields#

Request

Responses

Payment Request Flow

Allowed Payment Methods

Required fields

Email suppression

Unknown fields