Voucher REST-API

The 4Netplayers Voucher System REST API allows partners to generate and retrieve voucher codes. This API is designed for ease of use and flexibility, with methods to manage voucher codes efficiently.

Base URL#

https://secure.4players.de/public/api/v1/vouchers/{VOUCHER-ID}

• {VOUCHER-ID}: Replace with the Voucher-ID provided to you by 4Netplayers.

Authentication#

All API requests require an Authorization header with your API-Key:

Authorization: your-api-key

Endpoints#

Retrieve Voucher Codes#

• Method: GET
• URL: https://secure.4players.de/public/api/v1/vouchers/{VOUCHER-ID}[?externalId=EXTERNAL-ID]
• Description: Retrieves a list of all voucher codes generated under the specified Voucher-ID and optionally filtered by an external ID.
• Response Format:

[
	{
		"id": "bjBucDdab3pDc0dITkFWNTVjWLlEZz09",
		"code": "POE-A5E-F9F-641-NIX",
		"amount": 1500,
		"created": "2024-08-23 10:50:16",
		"externalId": "12385",
        "isUsed": false
	},
	{
		"id": "ajBucDaab3pCc0dIHkFWNTHjWTlEZz09",
		"code": "POE-3B6-1BD-A04-NIX",
		"amount": 500,
		"created": "2024-08-23 10:50:57",
		"externalId": "12384",
        "isUsed": true
	}
]

• Request Parameters:

  • VOUCHER-ID: The unique identifier assigned to the partner for managing voucher codes.
  • EXTERNAL-ID: (Optional) Filter the vouchers by an external identifier provided by the partner.

• Response Details:

  • id: The unique identifier for the voucher.
  • code: The actual voucher code that users can enter during the rental service order process.
  • amount: The value of the voucher in Eurocents (e.g., 1500 represents 15.00€).
  • created: The date and time when the voucher was created.
  • externalId: An optional identifier provided by the partner to link the voucher to their internal systems (e.g., user IDs).
  • isUsed: Indicates whether the voucher has been redeemed.

Create a Voucher#

• Method: POST
• URL: https://secure.4players.de/public/api/v1/vouchers/{VOUCHER-ID}
• Description: Creates a new voucher code under the specified Voucher-ID.
• Request Payload:

{
	"prefix": "MYGAME",
	"suffix": "2024",
	"amount": 500,
	"externalId": "12384"
}

• Request Details:

  • prefix: (Optional) A prefix to be added to the generated voucher code.
  • suffix: (Optional) A suffix to be added to the generated voucher code.
  • amount: The value of the voucher in Eurocents. Must be a positive integer, with a maximum of 25000 (i.e., 250.00€).
  • externalId: (Optional) A string that partners can use to associate the voucher with their internal user IDs or other identifiers.

• Response:

  • On success, the API will return the newly created voucher code in a format similar to the GET response.

Error Handling#

• 401 Unauthorized: If the API-Key is missing or invalid.
• 400 Bad Request: If required parameters are missing or invalid (e.g., amount exceeds the maximum allowed value).
• 404 Not Found: If the Voucher-ID does not exist.

Example Use Cases#

• Retrieve all vouchers for a game:

  curl -H "Authorization: your-api-key" https://secure.4players.de/public/api/v1/vouchers/ajBucDdab3pDc0dITkFWN
  

• Create a new voucher:

  curl -X POST -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"prefix":"MYGAME", "amount":1500, "externalId":"user123"}' \
  https://secure.4players.de/public/api/v1/vouchers/ajBucDdab3pDc0dITkFWN
  

Conclusion#

This REST API documentation provides the necessary details to integrate the 4Netplayers voucher system into your applications. It offers a straightforward method for managing voucher codes, enabling you to enhance your game or application with voucher-based server rentals.