API Endpoints

This section describes the available API endpoints for creating and managing sales through the zazpay API. Authentication is required for all endpoints as described in the auth.md documentation.

Create a Sale

POST /commerce/generate-sale

Creates a new sale transaction.

Input Parameters

Parameter	Type	Required	Description
total	number	Yes	Total transaction amount
clientUsername	string	One of	Username of the client. Provide phone number or email
salesmanIdentifier	string	One of	Salesman reference. Provide either salesmanIdentifier or salesmanId
salesmanId	string	One of	Salesman ID. Provide either salesmanId or salesmanIdentifier
storeId	string	Yes	Store ID (external or internal)
comments	string	No	Optional comments/description
folioExternal	string	Yes	External reference for idempotency and sandbox behavior toggles

Notes:

• Exactly one of clientUsername or clientId is required.
• Exactly one of salesmanIdentifier or salesmanId is required.

Response (data)

{
  "apiSaleId": "string",
  "id": "string",
  "folio": 12345,
  "folioExternal": "EXT-001",
  "status": "IN_PROGRESS",
  "store": { "name": "Store name" }
}

Exceptions

Error Code	Description
COMPANY-NOT-FOUND	Company not found
STORE-NOT-FOUND	Store not found
STORE-NOT-BELONG-TO-COMPANY	Store does not belong to your company
SALESMAN-NOT-FOUND	Salesman not found
CLIENT-NOT-FOUND	Client not found
SALE-CREATION-03	Minimum amount not reached
SALE-CREATION-04	Client credit line insufficient
TRANSACTION-NOT-FOUND	Transaction not found

Note: Some gateway-originated errors are passed through with their original statusCode and errorCode (e.g., C-PF-TRANSACTION-1001).

Retrieve Sale Status

POST /commerce/transaction-status

Retrieves the current status of a sale transaction by folio.

Input Parameters

Parameter	Type	Required	Description
folio	number	No	Transaction folio to look up
folioExternal	string	No	Transaction folio external to look up

Response (data)

{
  "folio": 12345,
  "folioExternal": "string",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:35:00.000Z",
  "salesmanId": "string",
  "storeId": "string",
  "status": "APPROVED",
  "total": 1500,
  "clientId": "string",
  "comments": "string"
}

Exceptions

Error Code	Description
TRANSACTION-NOT-FOUND	Transaction not found

Cancel a sale

POST /commerce/cancel-transaction

Cancels a sale that hasn't been accepted yet.

Input Parameters

Parameter	Type	Required	Description
folio	number	No	The transaction folio to cancel
folioExternal	string	No	The transaction external folio to cancel

Response (data)

{
  "folio": 12345,
  "status": "CANCELED",
  "cancelledAt": "2024-01-15T10:40:00.000Z"
}

Exceptions

Error Code	Description
SALE-CANCEL-01	Sale not found
SALE-CANCEL-02	Sale already cancelled
SALE-CANCEL-03	Sale cannot be cancelled (already processed)

Parameter reference

• folioExternal: External identifier supplied by your system. Used for idempotency and, in sandbox, to simulate outcomes.
• ticket: Optional POS receipt/reference. Free-form string (recommended max 64 chars).

Sandbox behavior and test patterns

In the sandbox environment, the folioExternal field controls the outcome of a sale created via /commerce/generate-sale. Include one of the following keywords anywhere in the folioExternal string to trigger the desired scenario:

Keyword in folioExternal	Resulting status	Description
(none)	APPROVED	Sale automatically transitions to APPROVED after ~5 seconds
REJECTED	REJECTED	Sale automatically transitions to REJECTED after ~5 seconds
NO_CANCEL	IN_PROGRESS	Sale stays IN_PROGRESS indefinitely — no automatic transition. Useful for testing the manual cancellation flow via /commerce/cancel-transaction

Examples

folioExternal: "ORDER-001"              → APPROVED  (~5s)
folioExternal: "ORDER-001-REJECTED"     → REJECTED  (~5s)
folioExternal: "ORDER-001-NO_CANCEL"    → IN_PROGRESS (no automatic transition)

tip

Combine these patterns with the predefined sandbox test clients to cover all integration scenarios.