Payments

The Payments API allows you to create, manage, and track payments with comprehensive filtering and status tracking capabilities.

Overview

Use the Payments API to:

Create new payments

List and filter existing payments

Track payment status and history

Manage payment-client relationships

Handle payment updates and modifications

Endpoints

POST /v2/payments

Create a new payment.

Authentication Required: Yes

Request Body

Basic Payment Creation:

{
  "clientId": "client_7kL2mX9pNqR4eWs",
  "items": [
    {
      "name": "Professional Consulting Services",
      "description": "Monthly consulting retainer for business strategy",
      "quantity": 1,
      "total": 1500,
      "product_key": "84111506",
      "unit_key": "E48",
      "unit_name": "Unidad de servicio"
    }
  ],
  "currency": "MXN",
  "metadata": {
    "reference": "REF456789"
  }
}

💡 Amount Handling: Item total amounts are specified in regular currency units (e.g., 1500 = $15.00 MXN). The API automatically converts these to cents for internal processing, so the response amount will be 150000 (cents).

Advanced Payment with Automation:

{
  "client": {
    "name": "Maria Rodriguez Santos",
    "email": "maria.rodriguez@example.com",
    "rfc": "ROSM850315QT8",
    "legal_name": "MARIA RODRIGUEZ SANTOS",
    "tax_system": "601",
    "address": {
      "zip": "06100",
      "country": "MEX"
    },
    "use": "G01"
  },
  "items": [
    {
      "name": "Monthly Software License",
      "description": "Premium SaaS subscription",
      "quantity": 1,
      "total": 1500,
      "product_key": "43232408",
      "unit_key": "E48",
      "unit_name": "Unidad de servicio",
      "taxes": [
        {
          "type": "IVA",
          "rate": 0.16,
          "factor": "Tasa"
        }
      ]
    }
  ],
  "currency": "MXN",
  "automaticInvoice": true,
  "avoidEmail": false,
  "livemode": false,
  "metadata": {
    "internalId": "INV-2024-001",
    "reference": "Monthly subscription"
  }
}

Master Team Payment Creation:

{
  "team": "team_9ZwE3pF8qKmJ7xL",
  "clientId": "client_7kL2mX9pNqR4eWs",
  "items": [
    {
      "name": "Development Services",
      "description": "Custom software development for sub-team",
      "quantity": 1,
      "total": 5000,
      "product_key": "84111506",
      "unit_key": "E48",
      "unit_name": "Unidad de servicio"
    }
  ],
  "currency": "MXN",
  "automaticInvoice": true,
  "metadata": {
    "internalId": "MASTER-SUB-001",
    "masterTeamPayment": "true"
  }
}

Split Billing / Connect Platform Payment:

{
  "clientId": "client_7kL2mX9pNqR4eWs",
  "items": [
    {
      "name": "Marketplace Transaction",
      "description": "Commission-based service",
      "quantity": 1,
      "total": 10000,
      "product_key": "84111506",
      "unit_key": "E48",
      "unit_name": "Unidad de servicio"
    }
  ],
  "currency": "MXN",
  "automaticInvoice": true,
  "metadata": {
    "vendor_id": "team_connectPartner123",
    "marketplace_transaction": "true"
  }
}

Paid Payment (Already Processed):

{
  "clientId": "client_7kL2mX9pNqR4eWs",
  "items": [
    {
      "name": "Completed Project",
      "description": "Website development project",
      "quantity": 1,
      "total": 25000,
      "product_key": "84111506",
      "unit_key": "E48",
      "unit_name": "Unidad de servicio"
    }
  ],
  "paid": true,
  "paymentMethod": "01",
  "date": "2024-01-15T10:30:00Z",
  "automaticInvoice": true,
  "metadata": {
    "projectId": "PROJ-2024-001"
  }
}

Parameters

Parameter	Type	Required	Description
`clientId`	string	No*	Client identifier (required if client object not provided)
`client`	object	No*	Client information object (alternative to clientId)
`email`	string	No	Client email (alternative to client.email)
`items`	array	Yes	Array of payment items (amounts in regular currency units, not cents)
`team`	string	No	Target team ID (master teams only - creates payment for specified team)
`currency`	string	No	Currency code: MXN, USD, EUR (default: MXN)
`exchange`	number	No	Exchange rate (auto-calculated if not provided)
`paymentMethod`	string	No*	Payment method code (required if paid is true)
`paid`	boolean	No	Whether the payment is already paid (default: false)
`date`	string	No	Payment date in ISO format (defaults to current date)
`livemode`	boolean	No	Whether payment is in live mode (default: false)
`avoidEmail`	boolean	No	Skip email notifications (default: false)
`automaticInvoice`	boolean	No	Auto-create invoice on payment (default: false)
`automateInvoiceOnComplete`	boolean	No	Auto-create invoice when completed (default: false)
`automateIncomeInvoiceAndComplement`	boolean	No	Auto PPD invoice and complement (default: false)
`forceReceipt`	boolean	No	Force receipt creation (default: false)
`invoiceConfig`	object	No	Invoice configuration (folio, series, type)
`from`	string	No	Payment source identifier (default: "api")
`metadata`	object	No	Additional payment metadata

*Either clientId or client object is required.

Response

Success Response (200 OK):

{
  "data": {
    "id": "paymentB8M3K7NQWX",
    "fid": "paymentB8M3K7NQWX",
    "team": "team_9ZwE3pF8qKmJ7xL",
    "owner": "5TVadmQLPkh134vuqr892ntHbrS1",
    "billingAccount": "ba_xzpRdFw2KSmVtQm",
    "amount": 150000,
    "currency": "MXN",
    "status": "requires_payment_method",
    "internalStatus": "requires_payment_method",
    "client": {
      "id": "client_7kL2mX9pNqR4eWs",
      "name": "Maria Rodriguez Santos",
      "email": "maria.rodriguez@example.com",
      "rfc": "ROSM850315QT8",
      "legal_name": "MARIA RODRIGUEZ SANTOS",
      "tax_system": "601",
      "address": {
        "zip": "06100",
        "country": "MEX"
      },
      "use": "G01",
      "livemode": true,
      "timestamp": 1745892357421
    },
    "clientId": "client_7kL2mX9pNqR4eWs",
    "items": [
      {
        "id": "serviceR6TYNMQWXZ",
        "name": "Professional Consulting Services",
        "description": "Monthly consulting retainer for business strategy",
        "quantity": 3,
        "total": 450,
        "product_key": "84111506",
        "unit_key": "E48",
        "unit_name": "Unidad de servicio",
        "taxes": [],
        "discount": 0,
        "currency": "MXN",
        "paymentType": {
          "label": "Tarifa fija",
          "value": "fixed"
        }
      }
    ],
    "discount": 0,
    "exchange": 1,
    "payment_form": "01",
    "processor": "api",
    "custom_method_types": [
      {
        "name": "Transferencia bancaria",
        "id": "bank",
        "logo": "https://pro-gigstack.s3.us-east-2.amazonaws.com/icons/+bank.png",
        "details": "Pago con transferencia desde tu cuenta bancaria",
        "manualConfirmation": true
      },
      {
        "name": "Tarjeta de crédito o débito",
        "id": "card",
        "logo": "https://pro-gigstack.s3.us-east-2.amazonaws.com/icons/Cards2.svg",
        "details": "Pago con tarjeta de crédito o débito",
        "manualConfirmation": false,
        "requiredKey": "paymentIntent"
      },
      {
        "name": "OXXO",
        "id": "oxxo",
        "logo": "https://js.stripe.com/v3/fingerprinted/img/oxxo-96b6ab36d23607973cb466bec56d187b.svg",
        "details": "Pago en efectivo en tiendas OXXO",
        "manualConfirmation": false,
        "requiredKey": "paymentIntent"
      }
    ],
    "automations": [
      {
        "action": "create",
        "ref": "payments",
        "type": "invoice",
        "from": "payments"
      }
    ],
    "invoices": [],
    "metadata": {
      "internalID": "paymentB8M3K7NQWX",
      "owner": "5TVadmQLPkh134vuqr892ntHbrS1",
      "items": 1
    },
    "from": "api",
    "timestamp": 1748236547821,
    "created": 1748236547821,
    "succeededTimestamp": null,
    "livemode": false,
    "shortURL": "https://gigstack.xyz/paymentB8M3K7NQWX",
    "shortUrl": "https://gigstack.xyz/paymentB8M3K7NQWX",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "hasStripe": false,
    "paymentIntent": "pi_Q34KLMRVX8HGAS52G792MN4P",
    "client_secret": "pi_Q34KLMRVX8HGAS52G792MN4P_secret_...",
    "stripeGenerated": true,
    "payment_method_options": {
      "card": {
        "installments": null,
        "mandate_options": null,
        "network": null,
        "request_three_d_secure": "automatic"
      },
      "oxxo": {
        "expires_after_days": 3
      }
    }
  },
  "message": "Pago registrado correctamente",
  "next": null
}

GET /v2/payments

List payments with optional filtering.

Authentication Required: Yes

Query Parameters

Parameter	Type	Description
`limit`	number	Number of results to return (default: 10, max: 100)
`starting_after`	string	Cursor for pagination, ID of the item to start after
`order_by`	string	Field to order results by (default: timestamp)
`order_direction`	string	Direction to order results: asc or desc (default: desc)
`amount`	number	Filter by amount
`status`	string	Filter by payment status
`clientId`	string	Filter by client ID
`rfc`	string	Filter by client RFC

Response

Success Response (200 OK):

{
  "data": [
    {
      "id": "paymentB8M3K7NQWX",
      "amount": 150000,
      "status": "completed",
      "clientId": "client_7kL2mX9pNqR4eWs",
      "currency": "MXN",
      "timestamp": 1748236547821,
      "client": {
        "name": "Maria Rodriguez Santos",
        "rfc": "ROSM850315QT8"
      },
      "shortURL": "https://gigstack.xyz/paymentB8M3K7NQWX"
    }
  ],
  "message": "Payments retrieved successfully",
  "totalResults": 1,
  "hasMore": false,
  "next": null
}

GET /v2/payments/{paymentId}

Get a specific payment by ID.

Authentication Required: Yes

Response

Success Response (200 OK):

Returns the complete payment object as shown in the POST response above.

Master Team Features

Master Team Payment Creation

Master teams (teams with isMasterTeam: true) can create payments on behalf of other teams within their billing account using the team parameter.

Use Cases:

Parent company creating payments for subsidiary teams

Agency creating payments for client teams

Marketplace platform creating payments for vendor teams

Requirements:

Authenticated team must have isMasterTeam: true

Target team must belong to the same billing account

All team validations ensure same billing account access only

Example:

{
  "team": "team_subsidiary123",
  "clientId": "client_7kL2mX9pNqR4eWs",
  "items": [
    {
      "name": "Services for Subsidiary",
      "description": "Monthly consulting services",
      "quantity": 1,
      "total": 2500,
      "product_key": "84111506",
      "unit_key": "E48",
      "unit_name": "Unidad de servicio"
    }
  ],
  "automaticInvoice": true,
  "metadata": {
    "masterTeamPayment": "true",
    "internalId": "MASTER-SUB-001"
  }
}

Split Billing / Connect Platform

Split billing enables marketplace functionality where master teams collect a percentage of payments, with the remainder going to connected vendors.

Configuration Requirements

Teams must be configured with:

split_billing: true - Enables split billing

split_amount: 10 - Percentage kept by master team (e.g., 10%)

metadata_split_keys: ["vendor_id", "vendor_code"] - Metadata keys that trigger split billing

split_billing_type: "client" - Client resolution for master team ("client", "master", "connect")

split_billing_type_connect: "client" - Client resolution for connect team ("client", "master", "connect")

How Split Billing Works

Trigger Detection: Payment metadata contains a key from metadata_split_keys array

Team Resolution: System finds connected team using:

Direct ID lookup: metadata.vendor_id = "team_abc123" → Direct document lookup

Metadata matching: metadata.vendor_code = "ABC123" → Query teams where team.metadata.vendor_code = "ABC123"

Payment Creation: Single payment created in connectPaymentsHub collection (not regular payments)

Transfer Configuration: Payment includes transfer_data object with split details

Client Resolution

Three client resolution types:

"client": Use original payment client

"master": Use master team as client

"connect": Use connected team as client

Example Split Billing Payment

Request:

{
  "clientId": "client_customer123",
  "items": [
    {
      "name": "Marketplace Service",
      "description": "Commission-based transaction",
      "quantity": 1,
      "total": 10000,
      "product_key": "84111506",
      "unit_key": "E48",
      "unit_name": "Unidad de servicio"
    }
  ],
  "currency": "MXN",
  "metadata": {
    "vendor_id": "team_vendor456",
    "transaction_type": "marketplace"
  }
}

Response includes transfer_data:

{
  "data": {
    "id": "paymentXYZ123",
    "amount": 1000000,
    "transfer_data": {
      "destination": "team_vendor456",
      "split": 90,
      "splitType": {
        "master": "client",
        "connect": "client"
      }
    }
    // ... rest of payment object
  }
}

Security Features

All team lookups validate same billing account

Prevents cross-billing-account access

Double validation for direct ID lookups

Comprehensive audit logging

Payment Status

Status	Description
`requires_payment_method`	Payment is awaiting payment method
`requires_confirmation`	Payment requires confirmation
`requires_action`	Payment requires additional action
`processing`	Payment is being processed
`requires_capture`	Payment requires manual capture
`canceled`	Payment was canceled
`succeeded`	Payment has been successfully completed

Payment Methods

When creating a payment with paid: true, you must specify a paymentMethod using one of these SAT-compliant codes:

Code	Description
`01`	Efectivo (Cash)
`02`	Cheque nominativo
`03`	Transferencia electrónica de fondos
`04`	Tarjeta de crédito
`05`	Monedero electrónico
`06`	Dinero electrónico
`08`	Vales de despensa
`12`	Dación en pago
`13`	Pago por subrogación
`14`	Pago por consignación
`15`	Condonación
`17`	Compensación
`23`	Novación
`24`	Confusión
`25`	Remisión de deuda
`26`	Prescripción o caducidad
`27`	A satisfacción del acreedor
`28`	Tarjeta de débito
`29`	Tarjeta de servicios
`30`	Aplicación de anticipos
`31`	Intermediario pagos
`99`	Por definir

Currency Support

Supported currencies with automatic exchange rate calculation:

MXN (Mexican Peso) - Default

USD (US Dollar)

EUR (Euro)

Exchange rates are automatically fetched for the current day when a non-MXN currency is used.

Payment Response Fields

Core Fields

id: Unique payment identifier

amount: Payment amount in cents (e.g., 150000 = $1,500.00 MXN)

currency: Payment currency (MXN, USD, etc.)

status: Current payment status

clientId: Associated client ID

timestamp: Payment creation timestamp

⚠️ Important: The response amount is always in cents, while request item total values are in regular currency units. The API handles the conversion automatically.

Client Information

client: Complete client object using unified Client schema

Includes client validation (EFOS) for Mexican tax compliance

Unified Client Schema

All client objects across the API use the same unified schema with the following structure:

Request Fields (for client creation):

name: Client display name

email: Client email address

rfc: Mexican tax ID (RFC)

legal_name: Legal business name

tax_system: Tax system code (SAT catalog)

address: Complete address object

use: CFDI use code

phone: Client phone number (optional)

Response Fields (additional system fields):

id: Unique client identifier

billingAccount: Associated billing account ID

metadata: Additional client metadata

owner: Owner user ID

from: Client creation source (api, dashboard, etc.)

team: Associated team ID

timestamp: Client creation timestamp

livemode: Whether client is in live mode

zip: Legacy postal code field (use address.zip instead)

Example Complete Client Object:

{
  "id": "clientFG4T78PIPLYZ",
  "billingAccount": "ba_uubHbCv9TRkWxOr",
  "metadata": {
    "internalId": "f3e28c9b",
    "reference": "REF-20240615-1"
  },
  "owner": "8UWdgXELUhf022vuoq249mtGytG2",
  "email": "maria.lopez@gmail.com",
  "from": "api",
  "team": "team_1IqJPJdcwTV2xTI",
  "name": "María López",
  "rfc": "LOPM850612AB2",
  "legal_name": "Servicios Integrales López S.A. de C.V.",
  "timestamp": 1750018281145,
  "livemode": false,
  "tax_system": "601",
  "address": {
    "city": "Ciudad de México",
    "country": "México",
    "street": "Av. Insurgentes Sur 1234",
    "zip": "03100",
    "state": "CDMX"
  },
  "phone": "+52 55 1234 5678",
  "use": "G01"
}

Payment Items

items: Array of services/products being paid for

Each item includes SAT catalog codes (product_key, unit_key)

Tax information and discounts

Payment Methods

custom_method_types: Available payment methods (card, bank transfer, OXXO)

paymentIntent: Stripe payment intent ID

client_secret: Stripe client secret for frontend integration

URLs and Tokens

shortURL: Shareable payment link

token: JWT token for payment access

Code Examples

Create a Payment

JavaScript/Node.js:

💰 Amount Note: In the examples below, item total values (1500, 12500, etc.) are in regular currency units. The API response will show these amounts multiplied by 100 in the amount field (e.g., 1500 → 150000 cents).

Python:

💰 Amount Note: Item total values in the examples are in regular currency units (e.g., 1500 = $15.00). The API automatically converts these to cents in the response (1500 → 150000).

List Payments with Filtering

cURL:

Error Handling

Common Error Responses

Validation Error (400 Bad Request):

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "amount": "Amount must be greater than 0",
      "clientId": "Client ID is required"
    }
  },
  "message": "Request validation failed"
}

Not Found Error (404 Not Found):

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Payment not found"
  },
  "message": "The requested payment does not exist"
}

Automation Features

The Payments API supports several automation workflows:

Invoice Automation

automaticInvoice: Creates an invoice immediately when payment is created

automateInvoiceOnComplete: Creates an invoice when payment status becomes "succeeded"

automateIncomeInvoiceAndComplement: Creates a PPD (Por Pagar/Por Definir) invoice and payment complement (cannot be combined with paid: true or paymentMethod)

Email Automation

avoidEmail: Prevents automatic email notifications to clients

Default behavior sends payment links and confirmations to client email

Receipt Automation

forceReceipt: Forces creation of a receipt document regardless of other settings

Validation Rules

Required Fields

items: At least one item is required

clientId OR client: Either reference an existing client or provide client information

paymentMethod: Required when paid: true

Client Validation

RFC format validation for Mexican tax compliance

Email format validation when provided

Address validation for invoice generation

Item Validation

SAT catalog compliance (product_key, unit_key)

Positive amounts and quantities

Tax configuration validation

Business Rules

Cannot combine automateIncomeInvoiceAndComplement with paid: true

Cannot combine automateIncomeInvoiceAndComplement with paymentMethod

Exchange rates auto-calculated for non-MXN currencies

Duplicate metadata.internalId prevention within team scope

Master Team Rules

Only teams with isMasterTeam: true can use the team parameter

Target team must belong to the same billing account as the master team

Duplicate metadata.internalId prevention applies to target team scope

All permissions and validations are checked against the target team

Split Billing Rules

Teams must be pre-configured with split billing settings

Connected teams must belong to the same billing account

Split billing payments are stored separately for marketplace functionality

Transfer data includes destination team and split percentage

Client resolution follows configured billing types (client/master/connect)

Best Practices

Client Management: Use clientId for existing clients, client object for new clients

SAT Compliance: Include proper product_key and unit_key for Mexican tax compliance

Tax Configuration: Specify taxes array for items when applicable (IVA, ISR, IEPS)

Payment URLs: Use the returned shortURL for customer payment links

Status Monitoring: Monitor payment status changes through webhooks

Error Handling: Always implement proper error handling for failed payments

Metadata Usage: Use metadata.internalId for unique payment tracking across systems

Currency Handling: Let the API auto-calculate exchange rates or provide custom rates

Automation Setup: Choose appropriate automation flags based on your workflow needs

10.

Date Handling: Provide ISO format dates when specifying custom payment dates

Stripe Integration

Payments automatically integrate with Stripe when configured:

paymentIntent: Stripe Payment Intent ID

client_secret: Use with Stripe.js for frontend payment processing

payment_method_options: Configured payment method options

Webhooks

Set up webhooks to receive real-time notifications about payment status changes:

{
  "event": "payment.succeeded",
  "data": {
    "id": "paymentB8M3K7NQWX",
    "amount": 150000,
    "status": "succeeded",
    "clientId": "client_7kL2mX9pNqR4eWs",
    "timestamp": 1748236547821
  }
}

Next Steps

Set up webhooks for payment notifications

Create invoices for payments

Manage client information

Payments

Payments#

Overview#

Endpoints#

POST /v2/payments#

Request Body#

Parameters#

Response#

GET /v2/payments#

Query Parameters#

Response#

GET /v2/payments/{paymentId}#

Response#

Master Team Features#

Master Team Payment Creation#

Split Billing / Connect Platform#

Configuration Requirements#

How Split Billing Works#

Client Resolution#

Example Split Billing Payment#

Security Features#

Payment Status#

Payment Methods#

Currency Support#

Payment Response Fields#

Core Fields#

Client Information#

Unified Client Schema#

Payment Items#

Payment Methods#

URLs and Tokens#

Code Examples#

Create a Payment#

List Payments with Filtering#

Error Handling#

Common Error Responses#

Automation Features#

Invoice Automation#

Email Automation#

Receipt Automation#

Validation Rules#

Required Fields#

Client Validation#

Item Validation#

Business Rules#

Master Team Rules#

Split Billing Rules#

Best Practices#

Stripe Integration#

Webhooks#

Next Steps#

Payments

Overview

Endpoints

POST /v2/payments

Request Body

Parameters

Response

GET /v2/payments

Query Parameters

Response

GET /v2/payments/{paymentId}

Response

Master Team Features

Master Team Payment Creation

Split Billing / Connect Platform

Configuration Requirements

How Split Billing Works

Client Resolution

Example Split Billing Payment

Security Features

Payment Status

Payment Methods

Currency Support

Payment Response Fields

Core Fields

Client Information

Unified Client Schema

Payment Items

Payment Methods

URLs and Tokens

Code Examples

Create a Payment

List Payments with Filtering

Error Handling

Common Error Responses

Automation Features

Invoice Automation

Email Automation

Receipt Automation

Validation Rules

Required Fields

Client Validation

Item Validation

Business Rules

Master Team Rules

Split Billing Rules

Best Practices

Stripe Integration

Webhooks

Next Steps