Sign in

v1

latestOpenAPI 3.0.3Proprietaryraw.githubusercontent.com2026-03-067260437.0 KB
Payments

Register payment

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.

post/payments/register

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

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 rate from the payment date (or current date if no date specified) will be fetched automatically from our rates collection.

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
metadataobject nullable

Additional metadata to store with the payment

idempotency_keystring nullable

Unique key to prevent duplicate payment registrations. If a payment with this key already exists, the existing payment will be returned.

datenumber nullable

Unix timestamp (in milliseconds) for when the payment was received. Must be in the past. Defaults to current time if not provided.

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"
  },
  "automation_type": "pue_invoice",
  "currency": "MXN",
  "exchange_rate": 1,
  "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"
      }
    }
  ],
  "payment_form": "03",
  "idempotency_key": "payment-register-12345",
  "date": 1677651234000,
  "invoice_config": {
    "serie": "A",
    "folio": 123
  },
  "transfer_data": {
    "master": 10,
    "connect": "ABC123456789",
    "master_to": "client",
    "connect_to": "client",
    "connect_custom_config": {
      "product_key": "01010101",
      "unit_key": "E48",
      "custom_description": "Professional consulting services",
      "custom_price": 250,
      "taxes": [
        {
          "type": "IVA",
          "rate": 0.16,
          "factor": "Tasa"
        }
      ]
    }
  }
}

Response

Payment registered successfully

messagestring

Example response

{
  "message": "Payment registered 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"
      }
    }
  }
}