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

Payment Splitting - Split payments between master and connect teams (marketplace)

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"
                }
            ]
        }
    ]
}

Payment Splitting (Marketplace)

Split payments between a master team (platform) and a connect team (merchant) in marketplace scenarios. This is only available for master teams with marketplace-enabled billing accounts.

Important: When using transfer_data, the team and livemode fields are automatically extracted from the authentication token. Developers do not need to send these fields in the request body.

{
    "client": {
        "id": "client_1234567890"
    },
    "automation_type": "pue_invoice",
    "currency": "MXN",
    "payment_form": "03",
    "items": [
        {
            "description": "Professional consulting services",
            "quantity": 1,
            "unit_price": 1000.0,
            "product_key": "80141503",
            "unit_key": "E48",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16
                }
            ]
        }
    ],
    "transfer_data": {
        "master": 60,
        "connect": "ABC123456789",
        "master_to": "client",
        "connect_to": "client"
    }
}

Transfer Data Configuration:

master (number, 0-100) - Percentage of the payment for the master team

connect (string) - Tax ID (RFC) or Team ID of the connect team. If not found, a new team will be created

master_to (string: 'client' | 'connect') - Client assignment for master payment:

client: Use the original client from the request

connect: Create the connect team as a client for the master payment

connect_to (string: 'client' | 'master') - Client assignment for connect payment:

client: Use the original client from the request

master: Create the master team as a client for the connect payment

connect_custom_config (object, optional) - Customize items in the connect payment:

product_key (string) - SAT product key for connect payment items

unit_key (string) - SAT unit key for connect payment items

custom_description (string) - Custom description for connect payment items

custom_price (number) - Fixed amount for connect payment (overrides percentage calculation)

taxes (array) - Custom tax configuration for connect payment items

Split Payment Response:

{
    "message": "Split payment registered successfully",
    "data": {
        "splitReference": "split_abc123xyz",
        "masterPaymentId": "payment_master_123",
        "connectPaymentId": "payment_connect_456",
        "masterAmount": 696.0,
        "connectAmount": 464.0,
        "totalAmount": 1160.0,
        "masterPayment": {
            "id": "payment_master_123",
            "client": "client_1234567890",
            "amount": 696.0,
            "team": "team_master_123",
            "splitRole": "master"
        },
        "connectPayment": {
            "id": "payment_connect_456",
            "client": "client_connect_789",
            "amount": 464.0,
            "team": "team_connect_456",
            "splitRole": "connect"
        },
        "connectTeam": {
            "id": "team_connect_456",
            "tax_id": "EMP800101ABC",
            "legal_name": "Empresa Ejemplo SA de CV",
            "created": true,
            "onboardingUrl": "https://api.gigstack.com/onboarding/team_connect_456?token=abc123"
        }
    }
}

When a new team is created:

If the connect team doesn't exist, the response includes an onboardingUrl that can be sent to the merchant to complete their team setup.

Advanced: Split Payment with Custom Configuration

{
    "client": {
        "search": {
            "on_key": "tax_id",
            "on_value": "PEGJ800101ABC",
            "auto_create": true
        },
        "name": "Juan Pérez García",
        "email": "juan.perez@ejemplo.com",
        "tax_id": "PEGJ800101ABC",
        "tax_system": "601"
    },
    "automation_type": "pue_invoice",
    "currency": "MXN",
    "payment_form": "03",
    "items": [
        {
            "description": "Platform service with marketplace split",
            "quantity": 1,
            "unit_price": 1000.0,
            "product_key": "80141503",
            "unit_key": "E48",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16
                }
            ]
        }
    ],
    "transfer_data": {
        "master": 30,
        "connect": "EMP800101ABC",
        "master_to": "client",
        "connect_to": "master",
        "connect_custom_config": {
            "product_key": "01010101",
            "unit_key": "E48",
            "custom_description": "Professional consulting services",
            "taxes": [
                {
                    "key": "002",
                    "name": "IVA",
                    "type": "federal",
                    "tax_mode": "tax",
                    "percentage": 16
                }
            ]
        }
    }
}

Fixed Commission Fee (Custom Price)

Instead of percentage-based splitting, you can charge a fixed commission fee using custom_price. This is useful when you want to charge a flat platform fee regardless of the transaction amount.

{
    "client": {
        "id": "client_1234567890"
    },
    "automation_type": "pue_invoice",
    "currency": "MXN",
    "payment_form": "03",
    "items": [
        {
            "description": "Product sale",
            "quantity": 1,
            "unit_price": 1000.0,
            "product_key": "80141503",
            "unit_key": "E48",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16
                }
            ]
        }
    ],
    "transfer_data": {
        "master": 0,
        "connect": "EMP800101ABC",
        "master_to": "client",
        "connect_to": "master",
        "connect_custom_config": {
            "custom_price": 50.00,
            "custom_description": "Platform service fee"
        }
    }
}

Key Points:

When custom_price is set, it overrides the percentage calculation

The connect team gets the exact custom_price amount (e.g., $50)

The master team gets the remainder (e.g.,

1110 o na

1160 total)

The master percentage field is ignored when using custom_price

Useful for fixed platform fees, minimum commissions, or tiered pricing

Response with Custom Price:

{
    "message": "Split payment registered successfully",
    "data": {
        "splitReference": "split_abc123xyz",
        "masterPaymentId": "payment_master_123",
        "connectPaymentId": "payment_connect_456",
        "masterAmount": 1110.00,
        "connectAmount": 50.00,
        "totalAmount": 1160.00,
        "usedCustomPrice": true
    }
}

🎯 Common Scenarios

1. Register Completed Payment (Bank Transfer)

2. Create Payment Link

3. Register Cash Payment

4. Partial Refund

5. Marketplace Payment Split (Platform Fee)

Response includes split payment details with master (10%) and connect (90%) payment IDs.

6. Marketplace Payment with Fixed Commission

Connect (marketplace) receives fixed

25 co mmi ss i o n, ma s t er (v e n d or) rece i v es t h ere main d er (

1135 from $1160 total).

🔄 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

Payments API Guide

Payments API Guide#

📋 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#

Payment Splitting (Marketplace)#

Advanced: Split Payment with Custom Configuration#

Fixed Commission Fee (Custom Price)#

🎯 Common Scenarios#

1. Register Completed Payment (Bank Transfer)#

2. Create Payment Link#

3. Register Cash Payment#

4. Partial Refund#

5. Marketplace Payment Split (Platform Fee)#

6. Marketplace Payment with Fixed Commission#

🔄 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#

Payments API Guide

📋 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

Payment Splitting (Marketplace)

Advanced: Split Payment with Custom Configuration

Fixed Commission Fee (Custom Price)

🎯 Common Scenarios

1. Register Completed Payment (Bank Transfer)

2. Create Payment Link

3. Register Cash Payment

4. Partial Refund

5. Marketplace Payment Split (Platform Fee)

6. Marketplace Payment with Fixed Commission

🔄 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