API reference

Merchants

30 methods. Request fields, an example response, and notes on what comes back in data.

Base https://api.groove.com.na Updated October 2026

GET /api/merchant-activation/:token

Fetch one resource by id or token.

Public

Request

Parameter	In	Req.	Description
`token`	path	Y	Opaque session or activation token.
`name`	body	Y	Display name (min 2, max 80).
`password`	body	Y	Account password (min 8, max 128).
`confirmPassword`	body	Y	Text field (min 8, max 128).
`message`	body	Y	Human-readable text body.
`path`	body	Y	Request field. See Zod schema in the route module for constraints.

Example body

{
  "name": "\u2026",
  "password": "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022",
  "confirmPassword": "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022",
  "message": "\u2026",
  "path": "\u2026"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/merchant-activation/:token

Create a resource or run this action.

Public

Request

Parameter	In	Req.	Description
`token`	path	Y	Opaque session or activation token.
`name`	body	Y	Display name (min 2, max 80).
`password`	body	Y	Account password (min 8, max 128).
`confirmPassword`	body	Y	Text field (min 8, max 128).
`message`	body	Y	Human-readable text body.
`path`	body	Y	Request field. See Zod schema in the route module for constraints.

Example body

{
  "name": "\u2026",
  "password": "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022",
  "confirmPassword": "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022",
  "message": "\u2026",
  "path": "\u2026"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

GET /api/merchant-applications

List or read resources for this path.

Bearer token

Request

Parameter	In	Req.	Description
`decision`	body	Y	One of: "approved", "declined".
`declineReason`	body	N	Text field (max 1000).
`reviewerNotes`	body	N	Text field (max 2000).
`riskLevel`	body	N	One of: "low", "medium", "high".

Example body

{
  "decision": "\u2026",
  "declineReason": "\u2026",
  "reviewerNotes": "\u2026",
  "riskLevel": "\u2026"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/merchant-applications

Create a resource or run this action.

Public

Request

Parameter	In	Req.	Description
`amountMinor`	body	Y	Amount in the smallest currency unit (NAD cents).
`destination`	body	Y	Enumerated string.
`mode`	body	Y	One of: "now", "schedule".
`scheduledFor`	body	N	Text field (min 8, max 40).
`marisMsisdn`	body	N	Text field (min 8, max 20).
`idempotencyKey`	body	N	Text field (min 8, max 80).

Example body

{
  "amountMinor": 0,
  "destination": "\u2026",
  "mode": "\u2026",
  "scheduledFor": "\u2026",
  "marisMsisdn": "\u2026",
  "idempotencyKey": "\u2026"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

PATCH /api/merchant-applications/:id

Update selected fields on this resource.

Bearer token

Request

Parameter	In	Req.	Description
`id`	path	Y	Path parameter identifying the resource.
`decision`	body	Y	One of: "approved", "declined".
`declineReason`	body	N	Text field (max 1000).
`reviewerNotes`	body	N	Text field (max 2000).
`riskLevel`	body	N	One of: "low", "medium", "high".

Example body

{
  "decision": "\u2026",
  "declineReason": "\u2026",
  "reviewerNotes": "\u2026",
  "riskLevel": "\u2026"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

GET /api/merchant-applications/docs/:token

Fetch one resource by id or token.

Public

Request

Parameter	In	Req.	Description
`token`	path	Y	Opaque session or activation token.

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/merchant-applications/docs/:token

Create a resource or run this action.

Public

Request

Parameter	In	Req.	Description
`token`	path	Y	Opaque session or activation token.

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

GET /api/merchant-applications/pay/:token

Fetch one resource by id or token.

Public

Request

Parameter	In	Req.	Description
`token`	path	Y	Opaque session or activation token.

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/merchant-applications/pay/:token

Create a resource or run this action.

Public

Request

Parameter	In	Req.	Description
`token`	path	Y	Opaque session or activation token.

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/merchant-applications/pay/:token/maris/verify-otp

Confirm a Maris one-time password.

Public

Request

Parameter	In	Req.	Description
`token`	path	Y	Opaque session or activation token.

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/merchants/change-password

Create a resource or run this action.

Bearer token

Request

Parameter	In	Req.	Description
`currentPassword`	body	Y	Text field (min 1, max 128).
`newPassword`	body	Y	Text field (min 8, max 128).

Example body

{
  "currentPassword": "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022",
  "newPassword": "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

GET /api/merchants/me

List or read resources for this path.

Bearer token

Request

No body or query parameters. Path values above, if any, are enough.

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {
    "id": "66f0a1b2c3d4e5f678901234",
    "name": "Pat Fan",
    "email": "pat@example.com",
    "roles": [
      "customer"
    ],
    "phone": "+264811234567"
  }
}

Response data

Wrapped in the standard envelope (status, success, data, …). See the introduction for envelope fields.

Field	Description
`data.id`	Resource identifier (Mongo ObjectId string).
`data.name`	Human-readable name.
`data.email`	Email address.
`data.roles`	Array. Element shape shown when sample includes objects.
`data.phone`	Phone number when present on the profile.

PATCH /api/merchants/me

Update selected fields on this resource.

Bearer token

Request

Parameter	In	Req.	Description
`name`	body	N	Display name (min 2, max 120).
`phone`	body	N	Contact mobile number in international or local form (min 4, max 32).
`businessName`	body	N	Merchant business / trading name (min 2, max 200).
`stallName`	body	N	Stall label shown on the floor and in reports (max 100).
`payoutDetails`	body	Y	Request field. See Zod schema in the route module for constraints.
`settings`	body	Y	Request field. See Zod schema in the route module for constraints.

Example body

{
  "name": "\u2026",
  "phone": "\u2026",
  "businessName": "\u2026",
  "stallName": "\u2026",
  "payoutDetails": "\u2026",
  "settings": "\u2026"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/merchants/me/delete

Create a resource or run this action.

Bearer token

Request

Parameter	In	Req.	Description
`currentPassword`	body	Y	Text field (min 1).
`confirmation`	body	Y	Request field. See Zod schema in the route module for constraints.

Example body

{
  "currentPassword": "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022",
  "confirmation": "\u2026"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

GET /api/merchants/me/event-invites

List or read resources for this path.

Bearer token

Request

No body or query parameters. Path values above, if any, are enough.

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

GET /api/merchants/me/event-invites/:inviteId

Fetch one resource by id or token.

Bearer token

Request

Parameter	In	Req.	Description
`inviteId`	path	Y	Path parameter identifying the resource.

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

PATCH /api/merchants/me/event-invites/:inviteId

Update selected fields on this resource.

Bearer token

Request

Parameter	In	Req.	Description
`inviteId`	path	Y	Path parameter identifying the resource.

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

GET /api/merchants/me/events

List or read resources for this path.

Bearer token

Request

No body or query parameters. Path values above, if any, are enough.

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

GET /api/merchants/me/events/:eventId/crew

List or read resources for this path.

Bearer token

Request

Parameter	In	Req.	Description
`eventId`	path	Y	Mongo ObjectId of the event.

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

PUT /api/merchants/me/events/:eventId/crew

Replace or upsert this resource.

Bearer token

Request

Parameter	In	Req.	Description
`eventId`	path	Y	Mongo ObjectId of the event.

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

GET /api/merchants/me/events/:eventId/crew/:crewMemberId/stats

List or read resources for this path.

Bearer token

Request

Parameter	In	Req.	Description
`eventId`	path	Y	Mongo ObjectId of the event.
`crewMemberId`	path	Y	Path parameter identifying the resource.

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/merchants/me/events/:eventId/crew/shift-checkout

Create a resource or run this action.

Bearer token

Request

Parameter	In	Req.	Description
`eventId`	path	Y	Mongo ObjectId of the event.
`status`	body	Y	Lifecycle status for the resource.

Example body

{
  "status": "\u2026"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/merchants/me/events/:eventId/crew/shift-verify

Create a resource or run this action.

Bearer token

Request

Parameter	In	Req.	Description
`eventId`	path	Y	Mongo ObjectId of the event.

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/merchants/me/pause

Create a resource or run this action.

Bearer token

Request

No body or query parameters. Path values above, if any, are enough.

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

GET /api/merchants/me/payout-requests

List or read resources for this path.

Bearer token

Request

Parameter	In	Req.	Description
`amountMinor`	body	Y	Amount in the smallest currency unit (NAD cents).
`destination`	body	Y	Enumerated string.
`mode`	body	Y	One of: "now", "schedule".
`scheduledFor`	body	N	Text field (min 8, max 40).
`marisMsisdn`	body	N	Text field (min 8, max 20).
`idempotencyKey`	body	N	Text field (min 8, max 80).

Example body

{
  "amountMinor": 0,
  "destination": "\u2026",
  "mode": "\u2026",
  "scheduledFor": "\u2026",
  "marisMsisdn": "\u2026",
  "idempotencyKey": "\u2026"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/merchants/me/payout-requests

Request a merchant payout.

Public

Request

Parameter	In	Req.	Description
`amountMinor`	body	Y	Amount in the smallest currency unit (NAD cents).
`destination`	body	Y	Enumerated string.
`mode`	body	Y	One of: "now", "schedule".
`scheduledFor`	body	N	Text field (min 8, max 40).
`marisMsisdn`	body	N	Text field (min 8, max 20).
`idempotencyKey`	body	N	Text field (min 8, max 80).

Example body

{
  "amountMinor": 0,
  "destination": "\u2026",
  "mode": "\u2026",
  "scheduledFor": "\u2026",
  "marisMsisdn": "\u2026",
  "idempotencyKey": "\u2026"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/merchants/me/payout-requests/:id/cancel

Request a merchant payout.

Public

Request

Parameter	In	Req.	Description
`id`	path	Y	Path parameter identifying the resource.

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

GET /api/merchants/me/payout-requests/availability

List or read resources for this path.

Bearer token

Request

Parameter	In	Req.	Description
`amountMinor`	body	Y	Amount in the smallest currency unit (NAD cents).
`destination`	body	Y	Enumerated string.
`mode`	body	Y	One of: "now", "schedule".
`scheduledFor`	body	N	Text field (min 8, max 40).
`marisMsisdn`	body	N	Text field (min 8, max 20).
`idempotencyKey`	body	N	Text field (min 8, max 80).

Example body

{
  "amountMinor": 0,
  "destination": "\u2026",
  "mode": "\u2026",
  "scheduledFor": "\u2026",
  "marisMsisdn": "\u2026",
  "idempotencyKey": "\u2026"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

PATCH /api/merchants/me/pos-floor-status

Update selected fields on this resource.

Bearer token

Request

Parameter	In	Req.	Description
`status`	body	Y	Lifecycle status for the resource.

Example body

{
  "status": "\u2026"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/merchants/me/resume

Create a resource or run this action.

Bearer token

Request

Parameter	In	Req.	Description
`currentPassword`	body	Y	Text field (min 1).
`confirmation`	body	Y	Request field. See Zod schema in the route module for constraints.

Example body

{
  "currentPassword": "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022",
  "confirmation": "\u2026"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

Lock this page again

Merchants · 30 methods · October 2026

Resolve this before you come in.

Request

Example body

Example response

Response data

Request

Example body

Example response

Response data

Request

Example body

Example response

Response data

Request

Example body

Example response

Response data

Request

Example body

Example response

Response data

Request

Example response

Response data

Request

Example response

Response data

Request

Example response

Response data

Request

Example response

Response data

Request

Example response

Response data

Request

Example body

Example response

Response data

Request

Example response

Response data

Request

Example body

Example response

Response data

Request

Example body

Example response

Response data

Request

Example response

Response data

Request

Example response

Response data

Request

Example response

Response data

Request

Example response

Response data

Request

Example response

Response data

Request

Example response

Response data

Request

Example response

Response data

Request

Example body

Example response

Response data

Request

Example response

Response data

Request