Create Payment

​

Body Parameters

​

Required Fields

​

Document Upload (Optional)

​

Manual Payment Data (Required if no document)

​

Response

curl --request POST \
  --url https://api.ambiotec.com/api/payments \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --form 'customerId=456' \
  --form 'document=@/path/to/receipt.pdf' \
  --form 'invoiceId=789'

{
  "success": true,
  "payment": {
    "paymentId": 1234,
    "customerId": 456,
    "amount": 1500.00,
    "currency": "GTQ",
    "paymentMethod": "transferencia",
    "bankCode": "BI",
    "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",
      "extractedReference": "TRX-123456",
      "confidence": {
        "amount": 0.95,
        "date": 0.98,
        "reference": 0.92
      }
    },
    "registeredBy": 42,
    "createdAt": "2026-03-03T15:30:00Z"
  },
  "ocrResult": {
    "requiresManualReview": false,
    "confidence": {
      "amount": 0.95,
      "date": 0.98
    }
  }
}

​

Business Logic

​

OCR Processing Flow

1. Document Upload: File is uploaded to S3 (payments/documents/ folder)
2. OCR Extraction: AWS Textract processes the document to extract:
   • Payment amount
   • Transaction date
   • Reference/transaction number
   • Bank code/name
   • Payment method indicators
3. Confidence Scoring: Each extracted field receives a confidence score (0-1)
4. Manual Review Flag: If confidence is low (below 0.85), requiresManualReview is set to true
5. Data Override: If manualData is provided in the request, it takes precedence over OCR results
6. Payment Creation: Record is saved with status pendiente (pending validation)

​

Payment Status Lifecycle

1. pendiente: Initial state, requires validation
2. validado: Finance team validated the payment
3. rechazado: Payment rejected (invalid, duplicate, etc.)
4. en_proceso_ach: ACH/bank transfer being processed
5. conciliado: Payment reconciled with bank statement
6. aplicado: Payment applied to customer account/invoices

​

Document Storage

• All payment documents are stored in S3 bucket
• Path format: payments/documents/{paymentId}-{filename}
• Documents are retained for compliance and audit purposes
• Access requires authentication

​

Invoice Association

• Payment is linked to a specific invoice
• Helps with automatic payment allocation
• Invoice balance is updated when payment status changes to aplicado

​

Manual vs OCR Data Priority

• Manual data takes precedence for payment record
• OCR data is still stored in ocrData field for comparison
• Useful for correcting OCR errors while maintaining audit trail

​

Notes

• Payments start in pendiente status and require validation
• OCR works best with clear, high-resolution images
• If OCR confidence is low, manual review is recommended
• Multiple payments can be associated with the same invoice
• The system tracks who registered each payment for accountability
• The OCR process is automatically triggered when a payment receipt is uploaded