Skip to main content
GET
/
api
/
payments
curl --request GET \
  --url 'https://api.ambiotec.com/api/payments?limit=20&offset=0' \
  --header 'Authorization: Bearer YOUR_TOKEN'

{
  "success": true,
  "payments": [
    {
      "paymentId": 1234,
      "customerId": 456,
      "customerName": "Juan Pérez",
      "amount": 1500.00,
      "currency": "GTQ",
      "paymentMethod": "transferencia",
      "bankCode": "BI",
      "bankName": "Banco Industrial",
      "reference": "TRX-123456",
      "transactionDate": "2026-03-03",
      "status": "pendiente",
      "documentUrl": "https://s3.amazonaws.com/ambiotec-payments/documents/1234-receipt.pdf",
      "ocrData": {
        "extractedAmount": 1500.00,
        "extractedDate": "2026-03-03",
        "confidence": {
          "amount": 0.95
        }
      },
      "notes": "Pago parcial de factura 789",
      "invoiceId": 789,
      "registeredBy": 42,
      "registeredByName": "María García",
      "validatedBy": null,
      "validatedAt": null,
      "createdAt": "2026-03-03T15:30:00Z",
      "updatedAt": "2026-03-03T15:30:00Z"
    },
    {
      "paymentId": 1235,
      "customerId": 456,
      "customerName": "Juan Pérez",
      "amount": 2500.00,
      "currency": "GTQ",
      "paymentMethod": "deposito",
      "bankCode": "BAM",
      "bankName": "Banco de América Central",
      "reference": "DEP-789012",
      "transactionDate": "2026-03-02",
      "status": "validado",
      "documentUrl": "https://s3.amazonaws.com/ambiotec-payments/documents/1235-receipt.jpg",
      "ocrData": null,
      "notes": null,
      "invoiceId": 788,
      "registeredBy": 42,
      "registeredByName": "María García",
      "validatedBy": 50,
      "validatedAt": "2026-03-03T09:15:00Z",
      "createdAt": "2026-03-02T16:45:00Z",
      "updatedAt": "2026-03-03T09:15:00Z"
    }
  ],
  "total": 2,
  "totalAmount": 4000.00
}
Fetches payment records with support for filtering by customer, status, date range, and text search.

​
Query Parameters

​
paymentId
integer
Filter by specific payment ID
​
customerId
integer
Filter by customer ID to see all payments from a specific customer
​
status
string
Filter by payment statusPossible values:
  • pendiente: Pending validation
  • validado: Validated by finance team
  • rechazado: Rejected payment
  • conciliado: Reconciled with bank statement
  • aplicado: Applied to customer account
  • en_proceso_ach: ACH transfer in process
​
dateFrom
string
Start date for filtering by transaction date (YYYY-MM-DD format)
​
dateTo
string
End date for filtering by transaction date (YYYY-MM-DD format)
​
search
string
Search term to filter by reference number, notes, or customer name
​
limit
integer
default:"10"
Maximum number of records to return
​
offset
integer
default:"0"
Number of records to skip for pagination

​
Response

​
success
boolean
Indicates if the request was successful
​
payments
array
Array of payment objects
​
total
integer
Total number of payments matching the filters (ignoring pagination)
​
totalAmount
number
Sum of all payment amounts matching the filters
curl --request GET \
  --url 'https://api.ambiotec.com/api/payments?limit=20&offset=0' \
  --header 'Authorization: Bearer YOUR_TOKEN'

{
  "success": true,
  "payments": [
    {
      "paymentId": 1234,
      "customerId": 456,
      "customerName": "Juan Pérez",
      "amount": 1500.00,
      "currency": "GTQ",
      "paymentMethod": "transferencia",
      "bankCode": "BI",
      "bankName": "Banco Industrial",
      "reference": "TRX-123456",
      "transactionDate": "2026-03-03",
      "status": "pendiente",
      "documentUrl": "https://s3.amazonaws.com/ambiotec-payments/documents/1234-receipt.pdf",
      "ocrData": {
        "extractedAmount": 1500.00,
        "extractedDate": "2026-03-03",
        "confidence": {
          "amount": 0.95
        }
      },
      "notes": "Pago parcial de factura 789",
      "invoiceId": 789,
      "registeredBy": 42,
      "registeredByName": "María García",
      "validatedBy": null,
      "validatedAt": null,
      "createdAt": "2026-03-03T15:30:00Z",
      "updatedAt": "2026-03-03T15:30:00Z"
    },
    {
      "paymentId": 1235,
      "customerId": 456,
      "customerName": "Juan Pérez",
      "amount": 2500.00,
      "currency": "GTQ",
      "paymentMethod": "deposito",
      "bankCode": "BAM",
      "bankName": "Banco de América Central",
      "reference": "DEP-789012",
      "transactionDate": "2026-03-02",
      "status": "validado",
      "documentUrl": "https://s3.amazonaws.com/ambiotec-payments/documents/1235-receipt.jpg",
      "ocrData": null,
      "notes": null,
      "invoiceId": 788,
      "registeredBy": 42,
      "registeredByName": "María García",
      "validatedBy": 50,
      "validatedAt": "2026-03-03T09:15:00Z",
      "createdAt": "2026-03-02T16:45:00Z",
      "updatedAt": "2026-03-03T09:15:00Z"
    }
  ],
  "total": 2,
  "totalAmount": 4000.00
}

​
Business Logic

​
Filtering Capabilities

The list endpoint supports powerful filtering: By Customer: Get all payments from a specific customer 
?customerId=456
By Status: Filter by payment lifecycle stage 
?status=pendiente
By Date Range: Find payments within a time period 
?dateFrom=2026-03-01&dateTo=2026-03-31
By Search Term: Search across reference numbers, notes, and customer names 
?search=TRX-123
Combined Filters: Apply multiple filters together 
?customerId=456&status=validado&dateFrom=2026-03-01

​
Pagination

For handling large result sets:
  • Default page size: 10 records
  • Maximum page size: 100 records
  • Use offset to navigate pages: offset = page * limit
  • The total field shows total matching records across all pages

​
Aggregate Calculations

  • total: Count of all payments matching filters
  • totalAmount: Sum of all payment amounts (useful for reconciliation)
  • Calculations ignore pagination (apply to all matching records)

​
Payment Status Workflow

Typical payment flow:
  1. pendiente → Payment registered, needs review
  2. validado → Finance verified payment is legitimate
  3. conciliado → Matched with bank statement
  4. aplicado → Applied to customer account
Alternative paths:
  • rechazado → Payment rejected (duplicate, fraud, error)
  • en_proceso_ach → ACH transfer initiated but not completed

​
OCR Data Visibility

The ocrData field contains:
  • Extracted values from document OCR
  • Confidence scores for each field
  • Useful for auditing and quality control
  • Compare OCR values with manual corrections

​
Use Cases

​
Daily Payment Processing

GET /api/payments?status=pendiente&dateFrom=2026-03-03&dateTo=2026-03-03
Get all pending payments from today for validation.

​
Customer Account Reconciliation

GET /api/payments?customerId=456&status=aplicado
View all applied payments for a customer’s account.

​
Monthly Financial Reporting

GET /api/payments?dateFrom=2026-03-01&dateTo=2026-03-31&status=validado
Get all validated payments for the month (use totalAmount for revenue).

​
Search for Specific Transaction

GET /api/payments?search=TRX-123456
Find payment by reference number.

Build docs developers (and LLMs) love

Get started for freeTalk to us