Payments API Guide

Process, track, and manage payments with automatic invoice generation and Mexican tax compliance. The Payments API handles payment registration, processing, refunds, and automated CFDI creation.

📋 Overview

The Payments API provides comprehensive payment management with flexible automation options. Register payments manually, create payment requests, process refunds, and automatically generate compliant invoices.

🔑 Key Features

Payment Registration - Record payments with optional invoice automation

Payment Requests - Create shareable payment links

Refund Processing - Full or partial refund support

Invoice Automation - Automatic PUE/PPD invoice creation

Multiple Processors - Support for various payment gateways

Status Tracking - Real-time payment status updates

Idempotency - Prevent duplicate payment processing

📚 Endpoints

List Payments

Retrieve a paginated list of payments.

Query Parameters:

limit (integer, 1-100) - Number of results per page (default: 10)

next (string) - Pagination cursor for next page

team (string) - gigstack Connect: Target team ID

Example Request:

Example Response:

{
    "message": "Payments retrieved successfully",
    "data": [
        {
            "id": "payment_1234567890",
            "client": {
                "id": "client_1234567890",
                "name": "Juan Pérez García",
                "tax_id": "PEGJ800101ABC"
            },
            "status": "succeeded",
            "total": 1160.0,
            "subtotal": 1000.0,
            "taxes": 160.0,
            "currency": "MXN",
            "payment_form": "03",
            "invoices": ["invoice_1234567890"],
            "created_at": 1677651234,
            "succeeded_at": 1677651234,
            "payment_processor": "stripe",
            "short_url": "https://pay.gigstack.io/p/abc123"
        }
    ],
    "has_more": false,
    "total_results": 1
}

Register Payment

Register a payment that has already been received. This endpoint marks the payment as 'succeeded' immediately and is used for recording payments that have already been completed through external means (bank transfers, cash, etc.).

Key Features:

Payment is marked as 'succeeded' immediately

Requires payment_form field (Mexican SAT payment form code)

Optional invoice automation

Used for payments already received

Automation Types:

pue_invoice - Create PUE (Pago en Una sola Exhibición) invoice immediately

ppd_invoice_and_complement - Create PPD invoice and payment complement

none - No automation, register payment only

Request Body:

{
    "client": {
        "id": "client_1234567890"
    },
    "automation_type": "pue_invoice",
    "currency": "MXN",
    "exchange_rate": 1.0,
    "payment_form": "03",
    "items": [
        {
            "id": "service_1234567890",
            "quantity": 2,
            "unit_price": 1000.0
        }
    ],
    "metadata": {
        "order_id": "ORD-12345",
        "customer_reference": "REF-789"
    }
}

Payment Form Codes:

01 - Cash

02 - Check

03 - Electronic transfer

04 - Credit card

05 - Electronic money

06 - Digital money

99 - To be defined

Example with Client Search:

Request Payment

Create a payment request that generates a shareable payment link. This endpoint creates a payment in 'requires_payment_method' status and provides customers with various payment options to complete the transaction.

Key Features:

Payment is created with 'requires_payment_method' status

Generates shareable payment link

Supports multiple payment methods

Optional email notifications

Used for requesting future payments

Payment Methods:

card - Credit/debit card payments (requires Stripe integration)

spei - Mexican bank transfer (SPEI)

oxxo - OXXO convenience store payments (requires Stripe integration)

stripe-spei - Customer balance payments (requires Stripe integration)

Note: card, oxxo, and stripe-spei payment methods are only available when your team has Stripe connected.

Request Body:

{
    "client": {
        "id": "client_1234567890"
    },
    "currency": "MXN",
    "items": [
        {
            "id": "service_1234567890",
            "quantity": 1
        }
    ],
    "automation_type": "pue_invoice",
    "allowed_payment_methods": ["card", "bank", "oxxo"],
    "send_email": true,
    "emails": ["client@example.com"],
    "idempotency_key": "payment-request-12345",
    "metadata": {
        "invoice_number": "INV-2024-001"
    }
}

Example Request:

Response with Payment Link:

{
    "message": "Payment request created successfully",
    "data": {
        "id": "payment_1234567890",
        "short_url": "https://pay.gigstack.io/p/abc123",
        "status": "requires_payment_method",
        "total": 11600.0
    }
}

Get Payment

Retrieve a specific payment by ID.

Example Request:

Mark Payment as Paid

Mark a pending payment as paid.

Example Request:

Cancel Payment

Cancel a payment request.

Example Request:

Refund Payment

Process a refund for a payment.

Request Body (Optional):

{
    "amount": 500.0,
    "reason": "Partial refund for service adjustment",
    "items": [
        {
            "id": "service_1234567890",
            "quantity": 1
        }
    ]
}

Example Request:

🏗️ Payment Structure

Payment Status

Status	Description
`requires_payment_method`	Waiting for payment method
`succeeded`	Payment completed successfully
`canceled`	Payment canceled

Payment Processors

stripe - Stripe payment gateway

mercado_pago - MercadoPago

paypal - PayPal

manual - Manual/bank transfer

📊 Complex Payment Examples

Register Payment with Multiple Items

{
    "client": {
        "id": "client_1234567890"
    },
    "automation_type": "pue_invoice",
    "currency": "MXN",
    "payment_form": "04",
    "items": [
        {
            "id": "service_001",
            "quantity": 2,
            "unit_price": 1000.0
        },
        {
            "description": "Installation service",
            "quantity": 1,
            "unit_price": 500.0,
            "product_key": "72121400",
            "unit_key": "E48",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16
                }
            ]
        },
        {
            "description": "Express shipping",
            "quantity": 1,
            "unit_price": 200.0,
            "product_key": "78102200",
            "unit_key": "E48",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16
                }
            ]
        }
    ]
}

Register Payment with Withholding Taxes

{
    "client": {
        "id": "client_1234567890"
    },
    "automation_type": "pue_invoice",
    "currency": "MXN",
    "payment_form": "03",
    "items": [
        {
            "description": "Professional services",
            "quantity": 1,
            "unit_price": 10000.0,
            "product_key": "80141503",
            "unit_key": "E48",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16,
                    "withholding": false
                },
                {
                    "type": "ISR",
                    "rate": 0.1,
                    "withholding": true
                },
                {
                    "type": "IVA",
                    "rate": 0.106667,
                    "withholding": true
                }
            ]
        }
    ]
}

Payment Request with Custom Invoice Config

{
    "client": {
        "id": "client_1234567890"
    },
    "currency": "MXN",
    "items": [
        {
            "id": "service_1234567890",
            "quantity": 1
        }
    ],
    "automation_type": "ppd_invoice_and_complement",
    "allowed_payment_methods": ["card", "bank"],
    "send_email": true,
    "emails": ["client@example.com"],
    "invoice_config": {
        "serie": "B",
        "folio": "456"
    },
    "metadata": {
        "project_id": "PROJ-2024-001",
        "department": "Engineering"
    }
}

Register USD Payment with Exchange Rate

{
    "client": {
        "id": "client_1234567890"
    },
    "automation_type": "pue_invoice",
    "currency": "USD",
    "exchange_rate": 18.5,
    "payment_form": "03",
    "items": [
        {
            "description": "International consulting",
            "quantity": 10,
            "unit_price": 100.0,
            "product_key": "80141503",
            "unit_key": "HUR",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.0,
                    "factor": "Exento"
                }
            ]
        }
    ]
}

🎯 Common Scenarios

1. Register Completed Payment (Bank Transfer)

2. Create Payment Link

3. Register Cash Payment

4. Partial Refund

🔄 Payment Workflows

Immediate Payment (PUE)

Deferred Payment (PPD)

Payment Request Flow

💡 Best Practices

Use idempotency keys - Prevent duplicate payments

Set automation_type correctly - Choose based on your workflow

Include all items - Ensure complete payment information

Validate clients first - Check fiscal data before processing

Use metadata - Track internal references and data

Handle webhooks - Process payment status updates

Test in staging - Validate workflows before production

Clients API - Manage payment recipients

Services API - Configure payment items

Invoices API - Generated invoices from payments

Teams API - Configure payment settings

🚨 Error Handling

Invalid Client

{
    "message": "Client not found",
    "error": "The specified client does not exist"
}

Invalid Item Configuration

{
    "message": "Invalid item",
    "error": "Service service_xyz not found"
}

Payment Already Processed

{
    "message": "Payment already succeeded",
    "error": "Cannot modify a completed payment"
}

Refund Error

{
    "message": "Refund failed",
    "error": "Refund amount exceeds payment total"
}

Automation Error

{
    "message": "Invoice creation failed",
    "error": "Missing required tax configuration"
}

Failed Client Fiscal Information

{
    "message": "Payment registration failed",
    "error": "Client fiscal information validation failed. RFC is invalid or client is in EFOS blacklist."
}

When a client's fiscal information fails validation (invalid RFC or EFOS blacklist), the payment will be rejected. Update the client information before retrying.

Need help with payment processing? Check our support documentation or contact support@gigstack.io

📋 Overview#

🔑 Key Features#

📚 Endpoints#

List Payments#

Register Payment#

Request Payment#

Get Payment#

Mark Payment as Paid#

Cancel Payment#

Refund Payment#

🏗️ Payment Structure#

Payment Status#

Payment Processors#

📊 Complex Payment Examples#

Register Payment with Multiple Items#

Register Payment with Withholding Taxes#

Payment Request with Custom Invoice Config#

Register USD Payment with Exchange Rate#

🎯 Common Scenarios#

1. Register Completed Payment (Bank Transfer)#

2. Create Payment Link#

3. Register Cash Payment#

4. Partial Refund#

🔄 Payment Workflows#

Immediate Payment (PUE)#

Deferred Payment (PPD)#

Payment Request Flow#

💡 Best Practices#

🔗 Related Resources#

🚨 Error Handling#

Invalid Client#

Invalid Item Configuration#

Payment Already Processed#

Refund Error#

Automation Error#

Failed Client Fiscal Information#

📋 Overview

🔑 Key Features

📚 Endpoints

List Payments

Register Payment

Request Payment

Get Payment

Mark Payment as Paid

Cancel Payment

Refund Payment

🏗️ Payment Structure

Payment Status

Payment Processors

📊 Complex Payment Examples

Register Payment with Multiple Items

Register Payment with Withholding Taxes

Payment Request with Custom Invoice Config

Register USD Payment with Exchange Rate

🎯 Common Scenarios

1. Register Completed Payment (Bank Transfer)

2. Create Payment Link

3. Register Cash Payment

4. Partial Refund

🔄 Payment Workflows

Immediate Payment (PUE)

Deferred Payment (PPD)

Payment Request Flow

💡 Best Practices

🔗 Related Resources

🚨 Error Handling

Invalid Client

Invalid Item Configuration

Payment Already Processed

Refund Error

Automation Error

Failed Client Fiscal Information