Receipts

The Receipts API provides full CRUD operations for receipts with client integration, allowing you to manage receipt records for all transactions.

Overview

Use the Receipts API to:

Create receipts for payments and transactions

Track receipt status and history

Manage receipt-client relationships

Update receipt information

Delete receipt records

Generate receipt documentation

Endpoints

POST /v2/receipts

Create a new receipt.

Authentication Required: Yes

Request Body

{
  "clientId": "client_123",
  "amount": 500.0,
  "currency": "MXN",
  "description": "Payment receipt for consulting services",
  "receiptNumber": "REC-2024-001",
  "issueDate": "2024-01-15T10:30:00.000Z",
  "paymentMethod": "transfer",
  "items": [
    {
      "description": "Consulting hours",
      "quantity": 5,
      "unitPrice": 100.0,
      "amount": 500.0
    }
  ],
  "metadata": {
    "paymentId": "pay_789",
    "invoiceId": "inv_456",
    "transactionRef": "TXN123456"
  }
}

Parameters

Parameter	Type	Required	Description
`clientId`	string	Yes	Client identifier
`amount`	number	Yes	Receipt total amount
`currency`	string	No	Currency code (default: MXN)
`description`	string	No	Receipt description
`receiptNumber`	string	No	Custom receipt number
`issueDate`	string	No	Receipt issue date (ISO 8601)
`paymentMethod`	string	No	Payment method used
`items`	array	No	Receipt line items
`metadata`	object	No	Additional receipt information

Response

Success Response (201 Created):

{
  "data": {
    "id": "receipt_321",
    "client": {
      "rfc": "XAXX010101000",
      "name": "Cliente Example",
      "email": "cliente@example.com"
    },
    "amount": 500.0,
    "currency": "MXN",
    "description": "Payment receipt for consulting services",
    "receiptNumber": "REC-2024-001",
    "issueDate": "2024-01-15T10:30:00.000Z",
    "paymentMethod": "transfer",
    "status": "issued",
    "items": [
      {
        "description": "Consulting hours",
        "quantity": 5,
        "unitPrice": 100.0,
        "amount": 500.0
      }
    ],
    "metadata": {
      "paymentId": "pay_789",
      "invoiceId": "inv_456",
      "transactionRef": "TXN123456"
    },
    "timestamp": "2024-01-15T10:30:00.000Z"
  },
  "message": "Receipt created successfully"
}

GET /v2/receipts

List receipts with optional filtering.

Authentication Required: Yes

Query Parameters

Parameter	Type	Description
`limit`	number	Number of results to return (default: 20, max: 100)
`offset`	number	Number of results to skip
`clientId`	string	Filter by client ID
`status`	string	Filter by receipt status
`receiptNumber`	string	Filter by receipt number
`from`	string	Filter receipts from date (ISO 8601)
`to`	string	Filter receipts to date (ISO 8601)
`minAmount`	number	Filter by minimum amount
`maxAmount`	number	Filter by maximum amount

Response

Success Response (200 OK):

{
  "data": [
    {
      "id": "receipt_321",
      "client": {
        "rfc": "XAXX010101000",
        "name": "Cliente Example"
      },
      "amount": 500.0,
      "currency": "MXN",
      "receiptNumber": "REC-2024-001",
      "status": "issued",
      "issueDate": "2024-01-15T10:30:00.000Z",
      "timestamp": "2024-01-15T10:30:00.000Z"
    }
  ],
  "message": "Receipts retrieved successfully",
  "totalResults": 1,
  "hasMore": false,
  "next": null
}

GET /v2/receipts/{receiptId}

Get a specific receipt by ID.

Authentication Required: Yes

Response

Success Response (200 OK):

{
  "data": {
    "id": "receipt_321",
    "client": {
      "rfc": "XAXX010101000",
      "name": "Cliente Example",
      "email": "cliente@example.com"
    },
    "amount": 500.0,
    "currency": "MXN",
    "description": "Payment receipt for consulting services",
    "receiptNumber": "REC-2024-001",
    "issueDate": "2024-01-15T10:30:00.000Z",
    "paymentMethod": "transfer",
    "status": "issued",
    "items": [
      {
        "description": "Consulting hours",
        "quantity": 5,
        "unitPrice": 100.0,
        "amount": 500.0
      }
    ],
    "metadata": {
      "paymentId": "pay_789",
      "invoiceId": "inv_456",
      "transactionRef": "TXN123456"
    },
    "timestamp": "2024-01-15T10:30:00.000Z"
  },
  "message": "Receipt retrieved successfully"
}

PUT /v2/receipts/{receiptId}

Update an existing receipt.

Authentication Required: Yes

Request Body

{
  "description": "Updated payment receipt for consulting services",
  "paymentMethod": "credit_card",
  "metadata": {
    "paymentId": "pay_789",
    "invoiceId": "inv_456",
    "transactionRef": "TXN123456",
    "updated": true
  }
}

Response

Success Response (200 OK):

{
  "data": {
    "id": "receipt_321",
    "client": {
      "rfc": "XAXX010101000",
      "name": "Cliente Example"
    },
    "amount": 500.0,
    "description": "Updated payment receipt for consulting services",
    "paymentMethod": "credit_card",
    "metadata": {
      "paymentId": "pay_789",
      "invoiceId": "inv_456",
      "transactionRef": "TXN123456",
      "updated": true
    },
    "timestamp": "2024-01-15T10:30:00.000Z"
  },
  "message": "Receipt updated successfully"
}

DELETE /v2/receipts/{receiptId}

Delete a receipt.

Authentication Required: Yes

Response

Success Response (200 OK):

{
  "data": {
    "id": "receipt_321",
    "deleted": true
  },
  "message": "Receipt deleted successfully"
}

Receipt Status

Status	Description
`draft`	Receipt is in draft state
`issued`	Receipt has been issued
`sent`	Receipt has been sent to client
`archived`	Receipt has been archived
`cancelled`	Receipt has been cancelled

Payment Methods

Common payment methods include:

Method	Description
`cash`	Cash payment
`transfer`	Bank transfer
`credit_card`	Credit card payment
`debit_card`	Debit card payment
`check`	Check payment
`other`	Other payment method

Code Examples

Create a Receipt

JavaScript/Node.js:

Python:

Update a Receipt

JavaScript/Node.js:

List and Filter Receipts

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",
      "receiptNumber": "Receipt number must be unique"
    }
  },
  "message": "Request validation failed"
}

Not Found Error (404 Not Found):

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Receipt not found"
  },
  "message": "The requested receipt does not exist"
}

Best Practices

Unique Receipt Numbers: Use a consistent numbering scheme

Complete Information: Include all relevant transaction details

Client Integration: Always associate receipts with clients

Status Management: Update receipt status appropriately

Metadata Usage: Store transaction references in metadata

Regular Cleanup: Archive old receipts periodically

Integration Examples

Creating Receipt from Payment

Linking Receipt to Invoice

Next Steps

Process payments and create receipts

Link receipts to invoices

Manage client receipt history

Receipts

Receipts#

Overview#

Endpoints#

POST /v2/receipts#

Request Body#

Parameters#

Response#

GET /v2/receipts#

Query Parameters#

Response#

GET /v2/receipts/{receiptId}#

Response#

PUT /v2/receipts/{receiptId}#

Request Body#

Response#

DELETE /v2/receipts/{receiptId}#

Response#

Receipt Status#

Payment Methods#

Code Examples#

Create a Receipt#

Update a Receipt#

List and Filter Receipts#

Error Handling#

Common Error Responses#

Best Practices#

Integration Examples#

Creating Receipt from Payment#

Linking Receipt to Invoice#

Next Steps#

Receipts

Overview

Endpoints

POST /v2/receipts

Request Body

Parameters

Response

GET /v2/receipts

Query Parameters

Response

GET /v2/receipts/{receiptId}

Response

PUT /v2/receipts/{receiptId}

Request Body

Response

DELETE /v2/receipts/{receiptId}

Response

Receipt Status

Payment Methods

Code Examples

Create a Receipt

Update a Receipt

List and Filter Receipts

Error Handling

Common Error Responses

Best Practices

Integration Examples

Creating Receipt from Payment

Linking Receipt to Invoice

Next Steps