iotoms Docs

Record a payment collection

POST
/api/v1/payments/contexts/{contextType}/{contextId}

Records cash, digital or credit tenders collected for a store visit, POS order or delivery (contextType and contextId). The tender amounts are checked to add up before the cash ledger is updated.

How to use it

  1. Put the visit, order or delivery in the path and the session it belongs to (e.g. the day cycle from Get the active day cycle) in the body.
  2. Send contextAmount and split it into cashReceived, digitalReceived and creditIssued; the three must add up to contextAmount exactly.
  3. List each tender in paymentModes; their amounts must add up to the same total. Mismatches are rejected.
  4. Send a clientPaymentId so retries return the first record; sending again for the same context replaces its amounts.
  5. The collection then counts in Get a payment summary for a session for that session.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Path Parameters

contextType*string

What the money is for: STORE_VISIT, POS_ORDER or ECOM_DELIVERY (DAY_CYCLE, STORE, ORDER_RETURN, TRANSACTION and OTHER are also accepted).

Value in"STORE_VISIT""POS_ORDER""ECOM_DELIVERY""DAY_CYCLE""STORE""ORDER_RETURN""TRANSACTION""OTHER"
contextId*string

ID of the store visit, POS order or delivery the money was collected for.

Formatuuid

Header Parameters

Request Body

application/json
  1. body
clientPaymentId?|

Your own unique ID for this collection, e.g. from the device. A retry with the same value returns the first record instead of saving twice.

contextType*string

Must be present in the body, but the value is replaced by the context type in the URL path.

Value in"STORE_VISIT""POS_ORDER""ECOM_DELIVERY""DAY_CYCLE""STORE""ORDER_RETURN""TRANSACTION""OTHER"
contextId*string

Must be present in the body, but the value is replaced by the context ID in the URL path.

Formatuuid
sessionType*string

Kind of session the collection belongs to: DAY_CYCLE (van-sales day), POS_SHIFT, ECOM_BATCH or INVENTORY_SESSION.

Value in"DAY_CYCLE""POS_SHIFT""ECOM_BATCH""INVENTORY_SESSION"
sessionId*string

ID of the session the money counts towards, e.g. the van's day cycle from Get the active day cycle.

Formatuuid
contextAmount*number

Total value of the visit, order or delivery in the merchant's currency. cashReceived + digitalReceived + creditIssued must equal it exactly.

cashReceived*number

Cash taken in the merchant's currency. Zero or more.

digitalReceived*number

Card, UPI or bank transfer money taken in the merchant's currency. Zero or more.

creditIssued*number

Amount left on credit for the customer to pay later, in the merchant's currency. Zero or more.

paymentModes*array<>

One row per tender used, at least one. The row amounts must add up to cash + digital + credit.

referenceNumber?|

Optional payment reference such as a slip number. Currently not stored by the server.

notes?|

Free-text notes to keep with the collection.

collectedAt*string

When the money was collected (ISO 8601 date-time). Defaults to the time of the call.

Formatdate-time

Response Body

OK

*/*
  1. response
status*string

Outcome of the call: SUCCESS when the request was processed; otherwise an error status.

message*string

Short human-readable message describing the outcome, e.g. which record was saved or why the call failed.

data?

The payment collection as saved.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/payments/contexts/STORE_VISIT/497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{  "contextType": "STORE_VISIT",  "contextId": "84451116-c600-49e2-9c60-5b6b34fae0d6",  "sessionType": "DAY_CYCLE",  "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",  "contextAmount": 0,  "cashReceived": 0,  "digitalReceived": 0,  "creditIssued": 0,  "paymentModes": [    {      "mode": "CASH",      "amount": 0    }  ],  "collectedAt": "2019-08-24T14:15:22Z"}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",    "clientPaymentId": "string",    "contextType": "STORE_VISIT",    "contextId": "84451116-c600-49e2-9c60-5b6b34fae0d6",    "sessionType": "DAY_CYCLE",    "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",    "cashReceived": 0,    "digitalReceived": 0,    "creditIssued": 0,    "totalCollected": 0,    "collectedAt": "2019-08-24T14:15:22Z",    "notes": "string"  }}