Sign in

v1

latestOpenAPI 3.0.3Proprietaryraw.githubusercontent.com2026-03-067260437.0 KB
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

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
post/payments/request

Query parameters

teamstring

gigstack Connect: Target team ID for multi-team access.

Requires gigstack Connect enabled on your team and shared billing account.

Example: ?team=team_xyz789

Request body

send_emailboolean nullable

Whether to send an email notification to the customer

emailsstring[] 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
currencystring required

Currency code (ISO 4217)

exchange_ratenumber nullable

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

allowed_payment_methodsstring[] 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_keystring nullable

Unique key to prevent duplicate payment requests

metadataobject nullable

Additional metadata to store with the payment

Example request

{
  "client": {
    "id": "client_1234567890",
    "search": {
      "on_key": "tax_id",
      "on_value": "PEGJ800101ABC",
      "auto_create": true
    },
    "address": {
      "country": "MEX",
      "street": "Av. Insurgentes Sur",
      "zip": "03100",
      "city": "Ciudad de México",
      "state": "CDMX",
      "exterior": "123",
      "interior": "4B",
      "municipality": "Benito Juárez",
      "neighborhood": "Del Valle"
    },
    "name": "Juan Pérez García",
    "company": "Empresa SA de CV",
    "phone": "+52 55 1234 5678",
    "email": "juan.perez@ejemplo.com",
    "legal_name": "Juan Pérez García",
    "tax_id": "PEGJ800101ABC",
    "use": "P01",
    "tax_system": "601"
  },
  "send_email": true,
  "emails": [
    "customer@example.com"
  ],
  "automation_type": "pue_invoice",
  "currency": "MXN",
  "exchange_rate": 1,
  "allowed_payment_methods": [
    "card",
    "bank",
    "oxxo"
  ],
  "idempotency_key": "payment-request-12345",
  "items": [
    {
      "id": "service_1234567890",
      "search": {
        "on_key": "sku",
        "on_value": "CONS-001",
        "auto_create": true
      },
      "quantity": 1,
      "description": "Consulting services",
      "sku": "CONS-001",
      "product_key": "80141503",
      "unit_key": "E48",
      "unit_name": "Servicio",
      "unit_price": 1000,
      "taxes": [
        {
          "factor": "Tasa",
          "rate": 0.16,
          "type": "IVA"
        }
      ],
      "third_party": {
        "legal_name": "Third Party SA",
        "tax_id": "TPR800101ABC",
        "tax_system": "601",
        "zip": "03100"
      }
    }
  ],
  "invoice_config": {
    "serie": "A",
    "folio": 123
  }
}

Response

Payment request created successfully

messagestring

Example response

{
  "message": "Payment request created successfully",
  "data": {
    "id": "payment_1234567890",
    "client": {
      "id": "client_1234567890",
      "address": {
        "country": "MEX",
        "street": "Av. Insurgentes Sur",
        "zip": "03100",
        "city": "Ciudad de México",
        "state": "CDMX",
        "exterior": "123",
        "interior": "4B",
        "municipality": "Benito Juárez",
        "neighborhood": "Del Valle"
      },
      "name": "Juan Pérez García",
      "company": "Empresa SA de CV",
      "phone": "+52 55 1234 5678",
      "email": "juan.perez@ejemplo.com",
      "bcc": [
        "admin@empresa.com"
      ],
      "metadata": {
        "custom_field": "value"
      },
      "is_valid": true,
      "from": "api",
      "legal_name": "Juan Pérez García",
      "livemode": true,
      "owner": "user_1234567890",
      "tax_id": "PEGJ800101ABC",
      "use": "P01",
      "tax_system": "601",
      "team": "team_1234567890",
      "created_at": 1677651234,
      "efos": {
        "is_valid": true
      },
      "defaults": {
        "issue_invoiceable_receipts": true
      }
    },
    "emails": [
      "client@example.com"
    ],
    "currency": "MXN",
    "allowed_payment_methods": [
      {
        "id": "card"
      }
    ],
    "exchange_rate": 1,
    "items": [
      {
        "id": "service_1234567890",
        "description": "Consulting services",
        "from": "api",
        "sku": "CONS-001",
        "product_key": "80141503",
        "unit_key": "E48",
        "unit_name": "Servicio",
        "unit_price": 1000,
        "taxes": [
          {
            "factor": "Tasa",
            "rate": 0.16,
            "type": "IVA"
          }
        ],
        "team": "team_1234567890",
        "created_at": 1677651234,
        "quantity": 1,
        "third_party": {
          "legal_name": "Third Party SA de CV",
          "tax_id": "TPR800101ABC",
          "tax_system": "601",
          "zip": "03100"
        },
        "search": {
          "on_key": "tax_id",
          "on_value": "PEGJ800101ABC",
          "auto_create": true
        }
      }
    ],
    "metadata": {
      "order_id": "12345"
    },
    "invoice_config": {
      "serie": "A",
      "folio": "123"
    },
    "team": "team_1234567890",
    "idempotency_key": "unique_key_123",
    "from": "api",
    "invoices": [
      "invoice_1234567890"
    ],
    "livemode": true,
    "owner": "user_1234567890",
    "payment_form": "03",
    "payments": [],
    "receipts": [
      "receipt_1234567890"
    ],
    "refunds": [
      {
        "id": "refund_1234567890",
        "items": [
          {
            "id": "service_1234567890",
            "description": "Consulting services",
            "from": "api",
            "sku": "CONS-001",
            "product_key": "80141503",
            "unit_key": "E48",
            "unit_name": "Servicio",
            "unit_price": 1000,
            "taxes": [
              {
                "factor": "Tasa",
                "rate": 0.16,
                "type": "IVA"
              }
            ],
            "team": "team_1234567890",
            "created_at": 1677651234,
            "quantity": 1
          }
        ],
        "reason": "Customer requested cancellation",
        "created_at": 1677651234,
        "total": 1160
      }
    ],
    "short_url": "https://pay.gigstack.io/p/abc123",
    "status": "succeeded",
    "total": 1160,
    "subtotal": 1000,
    "taxes": 160,
    "created_at": 1677651234,
    "succeeded_at": 1677651234,
    "payment_processor": "stripe",
    "payment_processor_details": {
      "stripe": {
        "payment_intent": "pi_1234567890",
        "charge": "ch_1234567890",
        "invoice": "in_1234567890"
      }
    }
  }
}