Request payment

curl --request POST \
  --url https://api.gigstack.io/v2/payments/request \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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']
  })
};

fetch('https://api.gigstack.io/v2/payments/request', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.gigstack.io/v2/payments/request"

payload = {
    "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"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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://gigstack.xyz/Xk3mP9",
    "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": []
  }
}

Payments

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.

POST

payments

request

Request payment

curl --request POST \
  --url https://api.gigstack.io/v2/payments/request \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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']
  })
};

fetch('https://api.gigstack.io/v2/payments/request', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.gigstack.io/v2/payments/request"

payload = {
    "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"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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://gigstack.xyz/Xk3mP9",
    "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": []
  }
}

Authorizations

Authorization

string

header

required

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

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.

Query Parameters

team

string

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

Body

application/json

Unknown top-level keys are rejected (400 validation_failed / unexpected_key). team, livemode and owner are reserved: they are injected by the auth middleware and any value you send for them is discarded.

client

object

required

Show child attributes

currency

string

required

Currency code (ISO 4217)

Example:

"MXN"

items

object[]

required

Show child attributes

send_email

boolean | null

Whether to send an email notification to the customer. Defaults to true. Overridden by ignore_emails.

Example:

true

ignore_emails

boolean | null

Suppress all notification emails for this payment. Takes precedence over send_email — the handler stores ignore_emails ?? (send_email === false).

Example:

false

emails

string[] | null

List of email addresses to send the payment request to

Example:

["customer@example.com"]

automation_type

enum<string> | null

Payment automation type. Optional; defaults to none.

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

Available options:

pue_invoice,

ppd_invoice_and_complement,

none,

null

Example:

"pue_invoice"

exchange_rate

number | null

Exchange rate for currency conversion. If not provided, the latest rate from our rates collection will be used automatically.

Example:

1

ppd_invoice_id

string | null

allowed_payment_methods

enum<string>[] | null

Payment methods available to the customer. Optional; when the field is absent it defaults to ['card'], which every connected processor accepts. An explicit empty list is kept as sent.

card: Credit/debit card payments
bank: Mexican bank transfer (SPEI)
oxxo: OXXO convenience store payments
stripe-spei: Stripe customer balance payments
mercadopago-wallet: Mercado Pago wallet (requires payment_processor: mercadopago)

The handler additionally restricts the list to the methods supported by the selected payment_processor — see the operation description.

Available options:

card,

bank,

oxxo,

stripe-spei,

mercadopago-wallet

Example:

["card", "bank", "oxxo"]

idempotency_key

string | null

Unique key to prevent duplicate payment requests

Example:

"payment-request-12345"

metadata

object | null

Additional metadata to store with the payment

invoice_config

object | null

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.

Show child attributes

payment_processor

enum<string> | null

Processor that will host the checkout. Defaults to stripe. Every processor other than stripe requires currency: MXN.

Available options:

stripe,

mercadopago,

openpay,

pagoralia,

conekta,

null

Example:

"stripe"

success_url

string<uri> | null

Where the hosted payment page returns the payer once the payment succeeds. Use it so a checkout does not dead-end on the payment page: point it at your order confirmation page.

The payer is shown the destination host and redirected a few seconds after the payment is confirmed; they can also return immediately with a button. For asynchronous methods (SPEI, OXXO) the redirect happens when the payment is confirmed, which may be after the payer has closed the page.

Validated on write — a 400 is returned unless the URL:

uses https
carries no credentials (https://user:pass@host)
contains no whitespace or control characters
resolves to a fully qualified, publicly reachable host (loopback, private and link-local ranges are rejected)
is at most 2048 characters

Maximum string length: 2048

Example:

"https://tienda.com/pedido/1234/gracias"

Response

Payment request created successfully

message

string

Example:

"Payment request created successfully"

data

object

Show child attributes

Clients

Services

Descarga Masiva SAT

Invoices

Payments

Receipts

Retentions

Teams

Users

Webhooks

Catalogs

Auth

SAT Lists

Documents

Platform Payouts

Request payment

Payment Request Flow

Allowed Payment Methods

Required fields

Email suppression

Unknown fields

Authorizations

Query Parameters

Body

Response