ProCinema Voucher API

Integrate cinema voucher validation and redemption into your application

View API Reference →

Overview

The ProCinema Voucher API allows you to validate and redeem cinema vouchers without purchasing real vouchers during development. Use our sandbox environment with pre-defined test codes to develop and test your integration quickly and cost-effectively.

Quick Start

Base URL (Sandbox)

https://api.procinemadev.com/v1
(Production URL will be announced soon)

Endpoints

  • POST /check - Validate a voucher code
  • POST /redeem - Redeem a voucher
  • POST /unredeem - Unredeem a voucher

Authentication

All API requests require a valid API key passed in the X-API-KEY header.

curl -X POST https://api.procinemadev.com/v1/check \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key-here" \
  -d '{"code": "SANDBOX867C42F3"}'

The API key is unique to your cinema organisation. You can manage the API key from the ProCinema Portal. To get access to the Cinema Portal, you need to get in touch with ProCinema.

API Examples

Validate a Voucher Code

Use the /check endpoint to validate a voucher code before redemption.

Request:

curl -X POST https://api.procinemadev.com/v1/check \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key-here" \
  -d '{"code": "SANDBOX867C42F3"}'

Response (200 OK):

{"valid": true}

Error Response (400 Bad Request):

{"valid": false, "error": "Invalid voucher code"}

Redeem a Voucher

Use the /redeem endpoint to redeem a validated voucher. The amount must be between 1 and 100 (in CHF).

Request:

curl -X POST https://api.procinemadev.com/v1/redeem \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key-here" \
  -d '{
    "code": "SANDBOX867C42F3",
    "amount": 25.00,
    "suisanr": "123456",
    "cinema_site_id": "1147630"
  }'

Request Body Fields:

  • code (required): Voucher code to redeem (string: XXXXXXXXXXXXXXX)
  • amount (required): Amount in CHF (decimal: 1.00-100.00)
  • suisanr (optional): Movie identifier (string: 1006682)
  • cinema_site_id (optional): Cinema Site Identifier. Your Cinema Site(s) IDs can be found in the Portal, as External ID. This is the same ID used by the current database of ProCinema. Providing the Cinema Site ID helps with more granular tracking of redemptions, and enables better reporting.

Response (200 OK):

{
  "success": true,
  "redemption_id": "166d00b1-2ed6-4b35-b5a2-36968a325e1a"
}

Error Response (400 Bad Request):

{
  "error": "Voucher code is invalid"
}

Unredeem a Voucher

Use the /unredeem endpoint to reverse a voucher redemption. This allows you to cancel a redemption transaction.

Request:

curl -X POST https://api.procinemadev.com/v1/unredeem \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key-here" \
  -d '{
    "code": "SANDBOX867C42F3"
  }'

Request Body Fields:

  • code (required): Voucher code to unredeem

Response (200 OK):

{
  "success": true
}

Error Response (400 Bad Request):

{
  "error": "Voucher has not been redeemed"
}

Sandbox Test Code

Valid Test Code

SANDBOX867C42F3
  • Always passes /check validation
  • Always succeeds on /redeem
  • Respects all validation rules
  • Simulates realistic latency (100-300ms for check, 200-500ms for redeem)

Real Test Codes from Database

Loading test codes...

Getting Started

  1. Get Your API Key: Contact ProCinema to get access to the Admin Portal from which you can manage and get an API Key.
  2. Get Your Cinema Site ID: Contact ProCinema to get access to the Admin Portal from which you can get your Cinema Site IDs.
  3. Test with Fixed Test Codes: Use the pre-defined test codes to develop your integration without real vouchers.
  4. Test with Sandbox Codes: Use sandbox-bound voucher codes to test redemptions and un-redemptions.
  5. Review the API Reference: Explore the complete API documentation in our interactive Swagger interface.