{"info":{"_postman_id":"21ea5d37-e298-483c-ba3f-0a4d83af4d86","name":"SuperPOS as Service","description":"

SuperPOS as Service Integration

Overview

This API enables third-party systems to integrate with PVS SuperPOS devices, using them as payment channels for collection orders created by client systems.

Authentication

All requests require JWT authentication via Keycloak. Include the token in the Authorization header:

Authorization: Bearer {jwt_token}\n\n

Payment Flow

Authenticate - Obtain JWT token from Keycloak
\n
Create Payment Order - Submit order with device ID, amount, and payment channels
\n
Process Payment - Operator selects and processes order on SuperPOS device
\n
Receive Callback - System notifies via callback URL (retries at 30s, 3min, 5min)
\n
Query Status - Check transaction status via API
\n
Manage Orders - Cancel orders or request refunds as needed
\n

Base URL

https://api.superpos.pvs.com/v1\n\n

Support

For technical support, contact: api-support@pvs.com

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"SuperPOS as Service Integration","slug":"superpos-as-service-integration"}],"owner":"40824655","collectionId":"21ea5d37-e298-483c-ba3f-0a4d83af4d86","publishedId":"2sBXVfkBjp","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-01-12T19:11:25.000Z"},"item":[{"name":"Authentication","item":[{"name":"Obtain JWT Token","event":[{"listen":"test","script":{"exec":["if (pm.response.code === 200) {"," var jsonData = pm.response.json();"," pm.collectionVariables.set('jwt_token', jsonData.access_token);"," console.log('JWT Token saved to collection variable');","}"],"type":"text/javascript","id":"fd2b2d1e-c23e-441a-925c-39970615f517"}}],"id":"d7e07d9a-900a-4fcf-99ed-ceb0bff242b6","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/x-www-form-urlencoded"}],"body":{"mode":"urlencoded","urlencoded":[{"key":"grant_type","value":"client_credentials","description":"

OAuth2 grant type

\n"},{"key":"client_id","value":"your_client_id","description":"

Your client ID provided by PVS

\n"},{"key":"client_secret","value":"your_client_secret","description":"

Your client secret provided by PVS

\n"}]},"url":"https://auth.superpos.pvs.com/realms/superpos/protocol/openid-connect/token","description":"

Authenticate with Keycloak

Obtains a JWT access token required for all subsequent API requests.

Request Parameters

grant_type: Must be \"client_credentials\"
client_id: Your unique client identifier
client_secret: Your confidential client secret

Response

{\n  \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\",\n  \"expires_in\": 3600,\n  \"token_type\": \"Bearer\"\n}\n

Notes

Token expires after 3600 seconds (1 hour)
The test script automatically saves the token to collection variables
All other endpoints require this token in the Authorization header

\n","urlObject":{"path":["realms","superpos","protocol","openid-connect","token"],"host":["https://auth.superpos.pvs.com"],"query":[],"variable":[]}},"response":[{"id":"9b9ca93d-99c5-488f-89f9-f16e9893359a","name":"Success Response","originalRequest":{"method":"POST","header":[],"body":{"mode":"urlencoded","urlencoded":[{"key":"grant_type","value":"client_credentials"},{"key":"client_id","value":"demo_client"},{"key":"client_secret","value":"demo_secret"}]},"url":"https://auth.superpos.pvs.com/realms/superpos/protocol/openid-connect/token"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxNVNGY...\",\n \"expires_in\": 3600,\n \"refresh_expires_in\": 0,\n \"token_type\": \"Bearer\",\n \"not-before-policy\": 0,\n \"scope\": \"profile email\"\n}"}],"_postman_id":"d7e07d9a-900a-4fcf-99ed-ceb0bff242b6"}],"id":"27bac853-a10f-4c88-98d0-9f31b91c1945","description":"

Authentication endpoints for obtaining JWT tokens from Keycloak.

\n","_postman_id":"27bac853-a10f-4c88-98d0-9f31b91c1945","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"21ea5d37-e298-483c-ba3f-0a4d83af4d86","id":"21ea5d37-e298-483c-ba3f-0a4d83af4d86","name":"SuperPOS as Service","type":"collection"}}},{"name":"Payment Orders","item":[{"name":"Create Payment Order","id":"45b0cd0c-5cf9-4edd-a12a-0d9ea4b091ef","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"device_id\": \"SPOS-12345\",\n \"transaction_id\": \"TXN-2025-001234\",\n \"currency\": \"ARS\",\n \"amount\": 15000.50,\n \"description\": \"Coffee shop order #1234\",\n \"callback_url\": \"https://your-system.com/api/payment-callback\",\n \"accepted_payment_channels\": [\n \"QR_ARG\",\n \"TD\",\n \"TC\"\n ],\n \"max_installments\": 6,\n \"metadata\": {\n \"order_id\": \"ORD-2025-5678\",\n \"customer_id\": \"CUST-9012\",\n \"store_location\": \"Downtown Branch\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.superpos.pvs.com/v1/payment-orders","description":"

Create Payment Order

Creates a new payment order that will be displayed on the specified SuperPOS device for processing.

Request Body

Required Fields

device_id (string): SuperPOS device identifier
\n
transaction_id (string): Unique transaction ID in your system
\n
currency (string): ISO 4217 currency code (e.g., ARS, USD, PEN)
\n
amount (number): Payment amount with up to 2 decimal places
\n
description (string): Payment description/concept (max 255 characters)
\n
callback_url (string): HTTPS URL for payment result notifications
\n

Optional Fields

accepted_payment_channels (array): List of allowed payment methods
\n
- If omitted, all channels are accepted
  \n
- Valid values: QR_ARG, CREDIT_CARD, DEBIT_CARD, QR_ALIPAY, QR_PER, CASH, TRANSFER, QR_PIX
  \n
\n
max_installments (integer): Maximum number of installments for credit card payments
\n
- Only applicable when CREDIT_CARD is in accepted channels
  \n
- Valid range: 1-12
  \n
\n
metadata (object): Additional custom data for your reference
\n

Response

{\n  \"order_id\": \"ORD-SPOS-789456\",\n  \"transaction_id\": \"TXN-2025-001234\",\n  \"status\": \"pending\",\n  \"created_at\": \"2025-01-12T10:30:00Z\",\n  \"expires_at\": \"2025-01-12T18:30:00Z\"\n}\n\n

Status Codes

201: Order created successfully
\n
400: Invalid request (missing required fields or invalid data)
\n
401: Unauthorized (invalid or expired JWT token)
\n
404: Device not found or not enabled
\n
409: Duplicate transaction_id
\n

Callback Notifications

The system will send POST requests to your callback_url with payment results:

Immediate notification upon payment completion
\n
Retry schedule on failure: 30 seconds, 3 minutes, 5 minutes
\n

Query Payment Order Status

Retrieves the current status and details of a payment order using your transaction ID.

Path Parameters

transaction_id (string): Your unique transaction identifier

Response

{\n  \"order_id\": \"ORD-SPOS-789456\",\n  \"transaction_id\": \"TXN-2025-001234\",\n  \"device_id\": \"SPOS-12345\",\n  \"status\": \"completed\",\n  \"currency\": \"ARS\",\n  \"amount\": 15000.50,\n  \"description\": \"Coffee shop order #1234\",\n  \"payment_method\": \"TC\",\n  \"installments\": 3,\n  \"created_at\": \"2025-01-12T10:30:00Z\",\n  \"processed_at\": \"2025-01-12T10:35:22Z\",\n  \"payment_details\": {\n    \"card_brand\": \"VISA\",\n    \"last_four_digits\": \"4532\",\n    \"authorization_code\": \"AUTH123456\",\n    \"receipt_number\": \"REC-789012\"\n  }\n}\n

Status Values

pending: Order created, awaiting payment
processing: Payment in progress
completed: Payment successful
failed: Payment failed
cancelled: Order cancelled
refunded: Payment refunded
partial_refund: Partial refund applied

Status Codes

200: Request successful
401: Unauthorized
404: Transaction not found

Your system's transaction ID

\n","type":"text/plain"},"type":"any","value":"TXN-2025-001234","key":"transaction_id"}]}},"response":[{"id":"c9ef005f-bacc-40b7-88a2-7f8dc31e4d30","name":"Completed Payment","originalRequest":{"method":"GET","header":[],"url":"https://api.superpos.pvs.com/v1/payment-orders/TXN-2025-001234"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"order_id\": \"ORD-SPOS-789456\",\n \"transaction_id\": \"TXN-2025-001234\",\n \"device_id\": \"SPOS-12345\",\n \"status\": \"completed\",\n \"currency\": \"ARS\",\n \"amount\": 15000.50,\n \"description\": \"Coffee shop order #1234\",\n \"payment_method\": \"TC\",\n \"installments\": 3,\n \"created_at\": \"2025-01-12T10:30:00Z\",\n \"processed_at\": \"2025-01-12T10:35:22Z\",\n \"payment_details\": {\n \"card_brand\": \"VISA\",\n \"last_four_digits\": \"4532\",\n \"authorization_code\": \"AUTH123456\",\n \"receipt_number\": \"REC-789012\"\n },\n \"metadata\": {\n \"order_id\": \"ORD-2025-5678\",\n \"customer_id\": \"CUST-9012\"\n }\n}"}],"_postman_id":"5607ef8e-9655-4390-919b-012a704132fd"},{"name":"Cancel Payment Order","id":"7112f5cd-f4c7-4f88-b587-e826f5733705","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"reason\": \"Customer requested cancellation\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.superpos.pvs.com/v1/payment-orders/:transaction_id/cancel","description":"

Cancel Payment Order

Cancels a pending payment order. Only orders with status \"pending\" can be cancelled.

Path Parameters

transaction_id (string): Your unique transaction identifier

Request Body

reason (string, optional): Cancellation reason for audit purposes

Response

{\n  \"order_id\": \"ORD-SPOS-789456\",\n  \"transaction_id\": \"TXN-2025-001234\",\n  \"status\": \"cancelled\",\n  \"cancelled_at\": \"2025-01-12T11:00:00Z\",\n  \"reason\": \"Customer requested cancellation\"\n}\n

Status Codes

200: Order cancelled successfully
400: Order cannot be cancelled (already processed/completed)
401: Unauthorized
404: Transaction not found

Notes

Completed or processing orders cannot be cancelled
Use the refund endpoint for completed payments
The order will be immediately removed from the device's pending orders list

Your system's transaction ID

\n","type":"text/plain"},"type":"any","value":"TXN-2025-001234","key":"transaction_id"}]}},"response":[{"id":"51d4f6d0-a34a-410f-a77d-3c2bd28d4415","name":"Success - Order Cancelled","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"reason\": \"Customer requested cancellation\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.superpos.pvs.com/v1/payment-orders/TXN-2025-001234/cancel"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"order_id\": \"ORD-SPOS-789456\",\n \"transaction_id\": \"TXN-2025-001234\",\n \"status\": \"cancelled\",\n \"cancelled_at\": \"2025-01-12T11:00:00Z\",\n \"reason\": \"Customer requested cancellation\"\n}"}],"_postman_id":"7112f5cd-f4c7-4f88-b587-e826f5733705"},{"name":"Request Refund","id":"d38b1acd-ce63-42fa-948b-9dd820bedb1f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"amount\": 15000.50,\n \"reason\": \"Product defect - full refund\",\n \"metadata\": {\n \"support_ticket\": \"TICKET-12345\",\n \"approved_by\": \"manager@company.com\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.superpos.pvs.com/v1/payment-orders/:transaction_id/refund","description":"

Request Payment Refund

Initiates a refund for a completed payment. Supports both full and partial refunds.

Path Parameters

transaction_id (string): Your unique transaction identifier

Request Body

amount (number): Refund amount (must not exceed original payment amount)
reason (string): Refund reason for audit purposes
metadata (object, optional): Additional refund information

Response

{\n  \"refund_id\": \"REF-SPOS-456789\",\n  \"order_id\": \"ORD-SPOS-789456\",\n  \"transaction_id\": \"TXN-2025-001234\",\n  \"status\": \"pending_card\",\n  \"amount\": 15000.50,\n  \"reason\": \"Product defect - full refund\",\n  \"created_at\": \"2025-01-12T14:20:00Z\"\n}\n

Refund Status Values

pending_card: Refund requires customer card presentation at device
processing: Refund in progress
completed: Refund successful
failed: Refund failed

Status Codes

201: Refund request created successfully
400: Invalid amount or order not refundable
401: Unauthorized
404: Transaction not found

Card-Present Refunds

If the refund requires the customer's card:

The refund order will appear in the device's \"Collection Orders\" section
Status will be pending_card
Operator must process the refund when customer presents their card
System will notify via callback upon completion

Partial Refunds

Multiple partial refunds can be processed
Total refunds cannot exceed the original payment amount
Each partial refund generates a unique refund_id

Your system's transaction ID

\n","type":"text/plain"},"type":"any","value":"TXN-2025-001234","key":"transaction_id"}]}},"response":[{"id":"884cbb88-8846-4265-8ddf-8bd4545cf9ba","name":"Refund Request Created","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"amount\": 15000.50,\n \"reason\": \"Product defect - full refund\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.superpos.pvs.com/v1/payment-orders/TXN-2025-001234/refund"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"refund_id\": \"REF-SPOS-456789\",\n \"order_id\": \"ORD-SPOS-789456\",\n \"transaction_id\": \"TXN-2025-001234\",\n \"status\": \"pending_card\",\n \"original_amount\": 15000.50,\n \"refund_amount\": 15000.50,\n \"reason\": \"Product defect - full refund\",\n \"created_at\": \"2025-01-12T14:20:00Z\",\n \"message\": \"Refund requires customer card. Order sent to device SPOS-12345.\"\n}"}],"_postman_id":"d38b1acd-ce63-42fa-948b-9dd820bedb1f"},{"name":"List Transactions","id":"3b97b00c-ccfc-4704-a285-96f4f825b702","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.superpos.pvs.com/v1/payment-orders?start_date=2025-01-12T00:00:00Z&end_date=2025-01-12T23:59:59Z&page=1&page_size=50","description":"

List Payment Transactions

Retrieves a paginated list of payment orders within a specified date-time range.

Query Parameters

Required

start_date (string): Start of date-time range (ISO 8601 format)
end_date (string): End of date-time range (ISO 8601 format)

Optional

status (string): Filter by order status
- Values: pending, processing, completed, failed, cancelled, refunded
\n
device_id (string): Filter by specific device
payment_method (string): Filter by payment channel
- Values: QR_ARG, TD, TC, QR_ALIPAY, QR_PER, CASH, TRANSFER
\n
page (integer): Page number (default: 1)
page_size (integer): Results per page (default: 50, max: 100)

Response

{\n  \"data\": [\n    {\n      \"order_id\": \"ORD-SPOS-789456\",\n      \"transaction_id\": \"TXN-2025-001234\",\n      \"device_id\": \"SPOS-12345\",\n      \"status\": \"completed\",\n      \"currency\": \"ARS\",\n      \"amount\": 15000.50,\n      \"payment_method\": \"TC\",\n      \"created_at\": \"2025-01-12T10:30:00Z\",\n      \"processed_at\": \"2025-01-12T10:35:22Z\"\n    }\n  ],\n  \"pagination\": {\n    \"page\": 1,\n    \"page_size\": 50,\n    \"total_records\": 245,\n    \"total_pages\": 5\n  },\n  \"summary\": {\n    \"total_amount\": 1250000.00,\n    \"count_by_status\": {\n      \"completed\": 200,\n      \"pending\": 30,\n      \"failed\": 15\n    }\n  }\n}\n

Status Codes

200: Request successful
400: Invalid date range or parameters
401: Unauthorized

Notes

Maximum date range: 31 days
Results are ordered by creation date (newest first)
Large exports should use multiple paginated requests

Start of date-time range (ISO 8601 format)

\n","type":"text/plain"},"key":"start_date","value":"2025-01-12T00:00:00Z"},{"description":{"content":"

End of date-time range (ISO 8601 format)

\n","type":"text/plain"},"key":"end_date","value":"2025-01-12T23:59:59Z"},{"disabled":true,"description":{"content":"

Filter by status (optional)

\n","type":"text/plain"},"key":"status","value":"completed"},{"disabled":true,"description":{"content":"

Filter by device (optional)

\n","type":"text/plain"},"key":"device_id","value":"SPOS-12345"},{"description":{"content":"

Page number (default: 1)

\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"

Results per page (default: 50, max: 100)

\n","type":"text/plain"},"key":"page_size","value":"50"}],"variable":[]}},"response":[{"id":"23a67817-6d2c-480f-ab72-0fb5744e7ddf","name":"Success - Transaction List","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.superpos.pvs.com/v1/payment-orders?start_date=2025-01-12T00:00:00Z&end_date=2025-01-12T23:59:59Z&page=1&page_size=50","host":["https://api.superpos.pvs.com/v1"],"path":["payment-orders"],"query":[{"key":"start_date","value":"2025-01-12T00:00:00Z"},{"key":"end_date","value":"2025-01-12T23:59:59Z"},{"key":"page","value":"1"},{"key":"page_size","value":"50"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": [\n {\n \"order_id\": \"ORD-SPOS-789456\",\n \"transaction_id\": \"TXN-2025-001234\",\n \"device_id\": \"SPOS-12345\",\n \"status\": \"completed\",\n \"currency\": \"ARS\",\n \"amount\": 15000.50,\n \"description\": \"Coffee shop order #1234\",\n \"payment_method\": \"TC\",\n \"installments\": 3,\n \"created_at\": \"2025-01-12T10:30:00Z\",\n \"processed_at\": \"2025-01-12T10:35:22Z\"\n },\n {\n \"order_id\": \"ORD-SPOS-789457\",\n \"transaction_id\": \"TXN-2025-001235\",\n \"device_id\": \"SPOS-12345\",\n \"status\": \"completed\",\n \"currency\": \"ARS\",\n \"amount\": 8500.00,\n \"description\": \"Retail purchase\",\n \"payment_method\": \"QR_ARG\",\n \"created_at\": \"2025-01-12T11:15:00Z\",\n \"processed_at\": \"2025-01-12T11:16:05Z\"\n }\n ],\n \"pagination\": {\n \"page\": 1,\n \"page_size\": 50,\n \"total_records\": 2,\n \"total_pages\": 1\n },\n \"summary\": {\n \"total_amount\": 23500.50,\n \"count_by_status\": {\n \"completed\": 2\n },\n \"count_by_method\": {\n \"TC\": 1,\n \"QR_ARG\": 1\n }\n }\n}"}],"_postman_id":"3b97b00c-ccfc-4704-a285-96f4f825b702"}],"id":"0adf07f4-d515-470d-980f-5ccbc88587a9","description":"

Endpoints for creating, querying, and managing payment orders.

\n","_postman_id":"0adf07f4-d515-470d-980f-5ccbc88587a9","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"21ea5d37-e298-483c-ba3f-0a4d83af4d86","id":"21ea5d37-e298-483c-ba3f-0a4d83af4d86","name":"SuperPOS as Service","type":"collection"}}},{"name":"Device Management","item":[{"name":"List Available Devices","id":"8d96a220-1547-42f1-a597-41c3df7f2d67","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.superpos.pvs.com/v1/devices?status=enabled&page=1&page_size=50","description":"

List SuperPOS Devices

Retrieves a list of SuperPOS devices available for sending payment orders.

Query Parameters

status (string, optional): Filter devices by status
- enabled: Only active devices (default)
- disabled: Only inactive devices
- all: All devices regardless of status
\n
page (integer): Page number (default: 1)
page_size (integer): Results per page (default: 50, max: 100)

Response

{\n  \"data\": [\n    {\n      \"device_id\": \"SPOS-12345\",\n      \"device_name\": \"Downtown Store - POS 1\",\n      \"status\": \"enabled\",\n      \"location\": \"Downtown Branch\",\n      \"supported_channels\": [\n        \"QR_ARG\",\n        \"TD\",\n        \"TC\",\n        \"CASH\"\n      ],\n      \"last_online\": \"2025-01-12T14:30:00Z\",\n      \"firmware_version\": \"2.5.1\"\n    }\n  ],\n  \"pagination\": {\n    \"page\": 1,\n    \"page_size\": 50,\n    \"total_records\": 15,\n    \"total_pages\": 1\n  }\n}\n

Device Status

enabled: Device is active and can receive payment orders
disabled: Device is inactive and cannot receive orders
online: Device is currently connected
offline: Device is not connected (orders will queue)

Status Codes

200: Request successful
401: Unauthorized

Filter by device status (enabled/disabled/all)

\n","type":"text/plain"},"key":"status","value":"enabled"},{"description":{"content":"

Page number

\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"

Results per page (max: 100)

\n","type":"text/plain"},"key":"page_size","value":"50"}],"variable":[]}},"response":[{"id":"662a2595-bb16-42b2-a801-08ebc6fabf64","name":"Success - Device List","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.superpos.pvs.com/v1/devices?status=enabled","host":["https://api.superpos.pvs.com/v1"],"path":["devices"],"query":[{"key":"status","value":"enabled"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": [\n {\n \"device_id\": \"SPOS-12345\",\n \"device_name\": \"Downtown Store - POS 1\",\n \"status\": \"enabled\",\n \"location\": \"Downtown Branch\",\n \"supported_channels\": [\"QR_ARG\", \"TD\", \"TC\", \"QR_ALIPAY\", \"CASH\"],\n \"last_online\": \"2025-01-12T14:30:00Z\",\n \"firmware_version\": \"2.5.1\",\n \"timezone\": \"America/Argentina/Buenos_Aires\"\n },\n {\n \"device_id\": \"SPOS-12346\",\n \"device_name\": \"Airport Branch - POS 2\",\n \"status\": \"enabled\",\n \"location\": \"International Airport\",\n \"supported_channels\": [\"TD\", \"TC\", \"QR_ALIPAY\", \"QR_PER\"],\n \"last_online\": \"2025-01-12T14:28:15Z\",\n \"firmware_version\": \"2.5.1\",\n \"timezone\": \"America/Argentina/Buenos_Aires\"\n }\n ],\n \"pagination\": {\n \"page\": 1,\n \"page_size\": 50,\n \"total_records\": 2,\n \"total_pages\": 1\n }\n}"}],"_postman_id":"8d96a220-1547-42f1-a597-41c3df7f2d67"},{"name":"Get Device Details","id":"5ebe7910-3d0c-43a4-8463-cafc6621b76d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.superpos.pvs.com/v1/devices/:device_id","description":"

Get Device Details

Retrieves detailed information about a specific SuperPOS device.

Path Parameters

device_id (string): SuperPOS device identifier

Response

{\n  \"device_id\": \"SPOS-12345\",\n  \"device_name\": \"Downtown Store - POS 1\",\n  \"status\": \"enabled\",\n  \"connection_status\": \"online\",\n  \"location\": \"Downtown Branch\",\n  \"address\": \"123 Main St, Buenos Aires\",\n  \"supported_channels\": [\n    \"QR_ARG\",\n    \"TD\",\n    \"TC\",\n    \"CASH\"\n  ],\n  \"max_installments\": 12,\n  \"last_online\": \"2025-01-12T14:30:00Z\",\n  \"firmware_version\": \"2.5.1\",\n  \"timezone\": \"America/Argentina/Buenos_Aires\",\n  \"pending_orders_count\": 3,\n  \"daily_transactions\": {\n    \"count\": 45,\n    \"total_amount\": 675000.50\n  }\n}\n

Status Codes

200: Request successful
401: Unauthorized
404: Device not found

SuperPOS device identifier

\n","type":"text/plain"},"type":"any","value":"SPOS-12345","key":"device_id"}]}},"response":[{"id":"49eda69b-91ca-4c47-802c-e395315abb2c","name":"Success - Device Details","originalRequest":{"method":"GET","header":[],"url":"https://api.superpos.pvs.com/v1/devices/SPOS-12345"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"device_id\": \"SPOS-12345\",\n \"device_name\": \"Downtown Store - POS 1\",\n \"status\": \"enabled\",\n \"connection_status\": \"online\",\n \"location\": \"Downtown Branch\",\n \"address\": \"123 Main St, Buenos Aires, Argentina\",\n \"supported_channels\": [\"QR_ARG\", \"TD\", \"TC\", \"QR_ALIPAY\", \"CASH\"],\n \"max_installments\": 12,\n \"last_online\": \"2025-01-12T14:30:00Z\",\n \"firmware_version\": \"2.5.1\",\n \"hardware_model\": \"SuperPOS Pro X1\",\n \"serial_number\": \"SN-2024-12345\",\n \"timezone\": \"America/Argentina/Buenos_Aires\",\n \"pending_orders_count\": 3,\n \"daily_transactions\": {\n \"date\": \"2025-01-12\",\n \"count\": 45,\n \"total_amount\": 675000.50,\n \"currency\": \"ARS\"\n }\n}"}],"_postman_id":"5ebe7910-3d0c-43a4-8463-cafc6621b76d"}],"id":"29452baa-a13d-4aad-b32b-521f69cabb99","description":"

Endpoints for managing and querying SuperPOS devices.

\n","_postman_id":"29452baa-a13d-4aad-b32b-521f69cabb99","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"21ea5d37-e298-483c-ba3f-0a4d83af4d86","id":"21ea5d37-e298-483c-ba3f-0a4d83af4d86","name":"SuperPOS as Service","type":"collection"}}},{"name":"Configuration","item":[{"name":"List Payment Channels","id":"e4b303c3-71b8-40b6-9ea6-43b1c193d6a4","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.superpos.pvs.com/v1/payment-channels","description":"

List Payment Channels

Retrieves all available payment channels/methods supported by the SuperPOS system.

Response

{\n  \"data\": [\n    {\n      \"code\": \"QR_ARG\",\n      \"name\": \"QR Code Argentina\",\n      \"description\": \"Argentine QR code payments (Modo, Mercado Pago)\",\n      \"supports_installments\": false,\n      \"currencies\": [\"ARS\"],\n      \"icon_url\": \"https://cdn.superpos.pvs.com/icons/qr_arg.png\"\n    },\n    {\n      \"code\": \"TC\",\n      \"name\": \"Credit Card\",\n      \"description\": \"Credit card payments with installment options\",\n      \"supports_installments\": true,\n      \"max_installments\": 12,\n      \"currencies\": [\"ARS\", \"USD\"],\n      \"icon_url\": \"https://cdn.superpos.pvs.com/icons/credit_card.png\"\n    }\n  ]\n}\n\n

Payment Channel Codes

QR_ARG: QR Code Argentina (Modo, Mercado Pago, etc.)
\n
DEBIT_CARD: Debit Card
\n
CREDIT_CARD: Credit Card (supports installments)
\n
QR_ALIPAY: Alipay QR Code
\n
QR_PER: QR Code Peru (Yape)
\n
CASH: Cash Payment
\n
TRANSFER: Bank Transfer
\n

Status Codes

200: Request successful
\n
401: Unauthorized
\n

Notes

Available channels may vary by device
\n
Check device details for specific channel support
\n
Some channels may have country or currency restrictions
\n

\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"21ea5d37-e298-483c-ba3f-0a4d83af4d86","id":"21ea5d37-e298-483c-ba3f-0a4d83af4d86","name":"SuperPOS as Service","type":"collection"}},"urlObject":{"path":["payment-channels"],"host":["https://api.superpos.pvs.com/v1"],"query":[],"variable":[]}},"response":[{"id":"feb8abfd-c331-432e-bb0c-dd1b12e81fcc","name":"Success - Payment Channels","originalRequest":{"method":"GET","header":[],"url":"https://api.superpos.pvs.com/v1/payment-channels"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": [\n {\n \"code\": \"QR_ARG\",\n \"name\": \"QR Code Argentina\",\n \"description\": \"Argentine QR code payments (Modo, Mercado Pago, BNA+)\",\n \"supports_installments\": false,\n \"currencies\": [\"ARS\"],\n \"processing_time\": \"instant\",\n \"icon_url\": \"https://cdn.superpos.pvs.com/icons/qr_arg.png\"\n },\n {\n \"code\": \"TD\",\n \"name\": \"Debit Card\",\n \"description\": \"Debit card payments (Visa Debit, Mastercard Debit)\",\n \"supports_installments\": false,\n \"currencies\": [\"ARS\", \"USD\"],\n \"processing_time\": \"instant\",\n \"icon_url\": \"https://cdn.superpos.pvs.com/icons/debit_card.png\"\n },\n {\n \"code\": \"TC\",\n \"name\": \"Credit Card\",\n \"description\": \"Credit card payments with installment options\",\n \"supports_installments\": true,\n \"max_installments\": 12,\n \"currencies\": [\"ARS\", \"USD\"],\n \"processing_time\": \"instant\",\n \"icon_url\": \"https://cdn.superpos.pvs.com/icons/credit_card.png\"\n },\n {\n \"code\": \"QR_ALIPAY\",\n \"name\": \"Alipay\",\n \"description\": \"Alipay QR code payments\",\n \"supports_installments\": false,\n \"currencies\": [\"CNY\", \"USD\", \"ARS\"],\n \"processing_time\": \"instant\",\n \"icon_url\": \"https://cdn.superpos.pvs.com/icons/alipay.png\"\n },\n {\n \"code\": \"QR_PER\",\n \"name\": \"QR Code Peru\",\n \"description\": \"Peruvian QR code payments (Yape, Plin)\",\n \"supports_installments\": false,\n \"currencies\": [\"PEN\"],\n \"processing_time\": \"instant\",\n \"icon_url\": \"https://cdn.superpos.pvs.com/icons/qr_per.png\"\n },\n {\n \"code\": \"CASH\",\n \"name\": \"Cash\",\n \"description\": \"Cash payment\",\n \"supports_installments\": false,\n \"currencies\": [\"ARS\", \"USD\", \"PEN\"],\n \"processing_time\": \"instant\",\n \"icon_url\": \"https://cdn.superpos.pvs.com/icons/cash.png\"\n },\n {\n \"code\": \"TRANSFER\",\n \"name\": \"Bank Transfer\",\n \"description\": \"Direct bank transfer\",\n \"supports_installments\": false,\n \"currencies\": [\"ARS\", \"USD\"],\n \"processing_time\": \"24-48 hours\",\n \"icon_url\": \"https://cdn.superpos.pvs.com/icons/transfer.png\"\n }\n ]\n}"}],"_postman_id":"e4b303c3-71b8-40b6-9ea6-43b1c193d6a4"},{"name":"List Available Installments","id":"7eaffc9a-d703-433a-a568-879b31eb2a7d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.superpos.pvs.com/v1/installments?currency=ARS","description":"

List Available Installments

Retrieves available installment options for credit card payments.

Query Parameters

currency (string, optional): Filter by currency code (e.g., ARS, USD)

Response

{\n  \"data\": [\n    {\n      \"installments\": 1,\n      \"description\": \"Single payment\",\n      \"interest_rate\": 0,\n      \"currencies\": [\"ARS\", \"USD\"]\n    },\n    {\n      \"installments\": 3,\n      \"description\": \"3 monthly installments\",\n      \"interest_rate\": 0,\n      \"currencies\": [\"ARS\"]\n    },\n    {\n      \"installments\": 6,\n      \"description\": \"6 monthly installments\",\n      \"interest_rate\": 15.5,\n      \"currencies\": [\"ARS\"]\n    },\n    {\n      \"installments\": 12,\n      \"description\": \"12 monthly installments\",\n      \"interest_rate\": 28.0,\n      \"currencies\": [\"ARS\"]\n    }\n  ]\n}\n

Response Fields

installments: Number of installment payments
description: Human-readable description
interest_rate: Annual interest rate percentage (0 for interest-free)
currencies: Supported currencies for this installment option

Status Codes

200: Request successful
401: Unauthorized

Notes

Installment availability may vary by card issuer and bank
Interest rates are subject to change
Some promotions may offer interest-free installments
Maximum installments can be restricted per transaction using max_installments parameter when creating an order

Currency code (optional)

\n","type":"text/plain"},"key":"currency","value":"ARS"}],"variable":[]}},"response":[{"id":"d2606b85-99bb-4ebd-abac-cd3bb81f355b","name":"Success - Installments List","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.superpos.pvs.com/v1/installments?currency=ARS","host":["https://api.superpos.pvs.com/v1"],"path":["installments"],"query":[{"key":"currency","value":"ARS"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": [\n {\n \"installments\": 1,\n \"description\": \"Single payment\",\n \"interest_rate\": 0,\n \"total_rate\": 1.0,\n \"currencies\": [\"ARS\", \"USD\"],\n \"card_brands\": [\"VISA\", \"MASTERCARD\", \"AMEX\", \"CABAL\"]\n },\n {\n \"installments\": 3,\n \"description\": \"3 monthly installments\",\n \"interest_rate\": 0,\n \"total_rate\": 1.0,\n \"currencies\": [\"ARS\"],\n \"card_brands\": [\"VISA\", \"MASTERCARD\", \"CABAL\"],\n \"promotion\": \"Interest-free promotion\"\n },\n {\n \"installments\": 6,\n \"description\": \"6 monthly installments\",\n \"interest_rate\": 15.5,\n \"total_rate\": 1.155,\n \"currencies\": [\"ARS\"],\n \"card_brands\": [\"VISA\", \"MASTERCARD\", \"AMEX\", \"CABAL\"]\n },\n {\n \"installments\": 9,\n \"description\": \"9 monthly installments\",\n \"interest_rate\": 22.0,\n \"total_rate\": 1.22,\n \"currencies\": [\"ARS\"],\n \"card_brands\": [\"VISA\", \"MASTERCARD\", \"CABAL\"]\n },\n {\n \"installments\": 12,\n \"description\": \"12 monthly installments\",\n \"interest_rate\": 28.0,\n \"total_rate\": 1.28,\n \"currencies\": [\"ARS\"],\n \"card_brands\": [\"VISA\", \"MASTERCARD\", \"AMEX\", \"CABAL\"]\n }\n ],\n \"last_updated\": \"2025-01-12T00:00:00Z\",\n \"notes\": \"Interest rates may vary by card issuer. Some banks offer additional promotions.\"\n}"}],"_postman_id":"7eaffc9a-d703-433a-a568-879b31eb2a7d"}],"id":"5ccbbec8-8970-4649-beb4-b7339bcd86d4","description":"

Configuration and reference data endpoints.

\n","_postman_id":"5ccbbec8-8970-4649-beb4-b7339bcd86d4","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"21ea5d37-e298-483c-ba3f-0a4d83af4d86","id":"21ea5d37-e298-483c-ba3f-0a4d83af4d86","name":"SuperPOS as Service","type":"collection"}}},{"name":"Webhooks","item":[{"name":"Payment Callback (Example)","id":"5b4432b6-1505-4691-8a44-7203afba212f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-SuperPOS-Signature","value":"sha256=abc123...","description":"

HMAC signature for webhook verification

\n"}],"body":{"mode":"raw","raw":"{\n \"event_type\": \"payment.completed\",\n \"event_id\": \"EVT-2025-123456\",\n \"timestamp\": \"2025-01-12T10:35:22Z\",\n \"data\": {\n \"order_id\": \"ORD-SPOS-789456\",\n \"transaction_id\": \"TXN-2025-001234\",\n \"device_id\": \"SPOS-12345\",\n \"status\": \"completed\",\n \"currency\": \"ARS\",\n \"amount\": 15000.50,\n \"payment_method\": \"TC\",\n \"installments\": 3,\n \"processed_at\": \"2025-01-12T10:35:22Z\",\n \"payment_details\": {\n \"card_brand\": \"VISA\",\n \"last_four_digits\": \"4532\",\n \"authorization_code\": \"AUTH123456\",\n \"receipt_number\": \"REC-789012\",\n \"merchant_id\": \"MERCH-456\"\n },\n \"metadata\": {\n \"order_id\": \"ORD-2025-5678\",\n \"customer_id\": \"CUST-9012\"\n }\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://your-system.com/api/payment-callback","description":"

Payment Callback Webhook

This is an EXAMPLE of the callback request that SuperPOS will send to your system when a payment is processed.

IMPORTANT: You must implement this endpoint in YOUR system to receive payment notifications.

Request Headers

Content-Type: application/json
\n
X-SuperPOS-Signature: HMAC-SHA256 signature for verification
\n

Event Types

payment.completed: Payment successfully processed
\n
payment.failed: Payment processing failed
\n
payment.cancelled: Payment was cancelled
\n
refund.completed: Refund successfully processed
\n
refund.failed: Refund processing failed
\n

Request Body

{\n  \"event_type\": \"payment.completed\",\n  \"event_id\": \"EVT-2025-123456\",\n  \"timestamp\": \"2025-01-12T10:35:22Z\",\n  \"data\": {\n    \"order_id\": \"ORD-SPOS-789456\",\n    \"transaction_id\": \"TXN-2025-001234\",\n    \"status\": \"completed\",\n    \"payment_details\": {...}\n  }\n}\n\n

Your Implementation Requirements

Endpoint Security
\n
- Must use HTTPS
  \n
- Verify the X-SuperPOS-Signature header
  \n
- Use the webhook secret provided during onboarding
  \n
\n
Response Requirements
\n
- Return HTTP 200 for successful receipt
  \n
- Respond within 5 seconds
  \n
- Non-200 responses trigger retry logic
  \n
\n
Idempotency
\n
- Use event_id to prevent duplicate processing
  \n
- Store processed event IDs
  \n
\n
Retry Schedule
\n
- First retry: 30 seconds after failure
  \n
- Second retry: 3 minutes after failure
  \n
- Third retry: 5 minutes after failure
  \n
- After 3 failures, manual intervention required
  \n
\n

Signature Verification (Python Example)

import hmac\nimport hashlib\ndef verify_webhook(payload, signature, secret):\n    computed = hmac.new(\n        secret.encode(),\n        payload.encode(),\n        hashlib.sha256\n    ).hexdigest()\n    expected = f\"sha256={computed}\"\n    return hmac.compare_digest(expected, signature)\n\n

Example Implementation

@app.route('/api/payment-callback', methods=['POST'])\ndef payment_callback():\n    signature = request.headers.get('X-SuperPOS-Signature')\n    payload = request.get_data(as_text=True)\n    if not verify_webhook(payload, signature, WEBHOOK_SECRET):\n        return jsonify({'error': 'Invalid signature'}), 401\n    data = request.json\n    event_id = data['event_id']\n    # Check for duplicate\n    if is_processed(event_id):\n        return jsonify({'status': 'already_processed'}), 200\n    # Process the payment\n    process_payment(data)\n    mark_processed(event_id)\n    return jsonify({'status': 'received'}), 200\n\n

Example webhook callbacks that YOUR system must implement to receive payment notifications from SuperPOS.

\n","_postman_id":"2a37f687-0df3-403e-8cea-516cb9716a93","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"21ea5d37-e298-483c-ba3f-0a4d83af4d86","id":"21ea5d37-e298-483c-ba3f-0a4d83af4d86","name":"SuperPOS as Service","type":"collection"}}}],"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]}},"event":[{"listen":"prerequest","script":{"id":"5d5c520a-5873-4795-89f6-988f96d5b199","type":"text/javascript","requests":{},"exec":["// Check if JWT token exists and is not expired","// This runs before each request in the collection"]}},{"listen":"test","script":{"id":"7c5dd837-e5f8-4fde-9842-10ddc2bcd074","type":"text/javascript","packages":{},"requests":{},"exec":[""]}}],"variable":[{"key":"base_url","value":"https://api.superpos.pvs.com/v1"},{"key":"keycloak_url","value":"https://auth.superpos.pvs.com"},{"key":"jwt_token","value":""},{"key":"client_id","value":"your_client_id"},{"key":"client_secret","value":"your_client_secret"}]}

SuperPOS as Service Integration

Overview

Authentication

Payment Flow

Supported Payment Channels

Base URL

Support

Authenticate with Keycloak

Request Parameters

Response

Notes

Create Payment Order

Request Body

Required Fields

Optional Fields

Response

Status Codes

Callback Notifications

Query Payment Order Status

Path Parameters

Response

Status Values

Status Codes

Cancel Payment Order

Path Parameters

Request Body

Response

Status Codes

Notes

Request Payment Refund

Path Parameters

Request Body

Response

Refund Status Values

Status Codes

Card-Present Refunds

Partial Refunds

List Payment Transactions

Query Parameters

Required

Optional

Response

Status Codes

Notes

List SuperPOS Devices

Query Parameters

Response

Device Status

Status Codes

Get Device Details

Path Parameters

Response

Status Codes

List Payment Channels

Response

Payment Channel Codes

Status Codes

Notes

List Available Installments

Query Parameters

Response

Response Fields

Status Codes

Notes

Payment Callback Webhook

Request Headers

Event Types

Request Body

Your Implementation Requirements

Signature Verification (Python Example)

Example Implementation