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/identifier of the client. Provide either clientUsername or clientId
clientId	string	One of	Client ID. Provide either clientId or clientUsername
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 following patterns apply when creating a sale (/commerce/generate-sale):

• If folioExternal contains REJECTED, the sale will transition to REJECTED after ~5 seconds.
• If folioExternal does not contain REJECTED, it will transition to APPROVED after ~5 seconds.
• If folioExternal contains NO_CANCEL, the automatic transition is disabled (stays IN_PROGRESS until manually cancelled).