Receipts

Learn how to create, manage, and void receipts for point-of-sale transactions.

Receipts are used for point-of-sale transactions where payment is received immediately. Unlike invoices, receipts are automatically submitted to ZIMRA upon creation.

Receipts are immutable once created. If you need to reverse a transaction, you must void the receipt and create a new one.

The Receipt Object

The receipt object contains all information about a point-of-sale transaction, including items, taxes, and fiscal compliance data.

Receipt Object
{
  "id": "rcpt_abc123",
  "number": "RCP-2024-0001",
  "status": "completed",
  "type": "sale",
  "customer_id": "cust_xyz789",
  "items": [
    {
      "id": "itm_001",
      "description": "Product A",
      "quantity": 2,
      "unit_price": 25.00,
      "tax_code": "STD",
      "tax_amount": 7.50,
      "total": 57.50
    }
  ],
  "subtotal": 50.00,
  "tax_total": 7.50,
  "total": 57.50,
  "currency": "USD",
  "fiscal_code": "ZW-2024-RCP-ABC123",
  "payment_method": "cash",
  "created_at": "2024-01-15T14:30:00Z"
}

Receipt Types

TypeDescription
saleStandard sale transaction with positive amounts.
refundRefund transaction with negative amounts.
voidVoided receipt that cancels a previous transaction.

Payment Methods

MethodDescription
cashCash payment
cardCredit or debit card
mobileMobile money (EcoCash, OneMoney, etc.)
bank_transferDirect bank transfer
otherOther payment method

Create a Receipt

Create a new receipt for a point-of-sale transaction. The receipt is automatically submitted to ZIMRA and assigned a fiscal code.

POST/v1/receipts
Auth required

Creates a new receipt and submits it to ZIMRA.

Request Body

customer_idstring

The unique identifier of the customer. Optional for receipts.

typestring default: sale

The type of receipt: sale, refund.

payment_methodstring required

The payment method used: cash, card, mobile, bank_transfer, other.

itemsarray required

Array of line items for the receipt.

Example Request

JSON
{
  "customer_id": "cust_xyz789",
  "type": "sale",
  "payment_method": "cash",
  "items": [
    {
      "description": "Product A",
      "quantity": 2,
      "unit_price": 25.00,
      "tax_code": "STD"
    }
  ]
}

Response

201Receipt created successfully
JSON
{
  "id": "rcpt_abc123",
  "number": "RCP-2024-0001",
  "status": "completed",
  "type": "sale",
  "customer_id": "cust_xyz789",
  "items": [
    {
      "id": "itm_001",
      "description": "Product A",
      "quantity": 2,
      "unit_price": 25.00,
      "tax_code": "STD",
      "tax_amount": 7.50,
      "total": 57.50
    }
  ],
  "subtotal": 50.00,
  "tax_total": 7.50,
  "total": 57.50,
  "currency": "USD",
  "fiscal_code": "ZW-2024-RCP-ABC123",
  "payment_method": "cash",
  "created_at": "2024-01-15T14:30:00Z"
}

List Receipts

Retrieve a paginated list of receipts. You can filter by date range, status, and payment method.

GET/v1/receipts
Auth required

Returns a paginated list of receipts.

Query Parameters

typestring

Filter by receipt type: sale, refund, void.

payment_methodstring

Filter by payment method.

fromstring

Start date for date range filter (ISO 8601).

tostring

End date for date range filter (ISO 8601).

Response

200List of receipts
JSON
{
  "data": [
    {
      "id": "rcpt_abc123",
      "number": "RCP-2024-0001",
      "status": "completed",
      "total": 57.50,
      "created_at": "2024-01-15T14:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 156
  }
}

Void a Receipt

Void a receipt to cancel a transaction. A void reason is required for audit purposes.

Important

Voiding a receipt creates a new void transaction with ZIMRA. The original receipt remains in the system for audit purposes.
POST/v1/receipts/{receipt_id}/void
Auth required

Voids the specified receipt.

Path Parameters

receipt_idstring required

The unique identifier of the receipt to void.

Request Body

reasonstring required

The reason for voiding the receipt.

Example: Customer returned items

Response

200Receipt voided successfully
JSON
{
  "id": "rcpt_abc123",
  "status": "voided",
  "voided_at": "2024-01-15T15:00:00Z",
  "void_reason": "Customer returned items"
}
Previous Invoices
NextProducts