A valid request URL is required to generate request examples{
"id": "gc-2026-000142",
"code": "GC-4F2A-9B71",
"kind": "gift_card",
"currency": "EUR",
"initialBalanceCents": 5000,
"balanceCents": 5000,
"status": "active",
"expiresAt": "2028-01-31T23:59:59.000Z"
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123,
"fieldErrors": [
{
"field": "<string>",
"message": "<string>"
}
]
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}Issue a stored-value instrument (carte cadeau, avoir)
Mints ONE instrument at amountCents (integer cents, strictly positive) under a caller-chosen id and bearer code, both of which must be unused. kind picks the product: gift_card (prepaid bearer), credit_note (issued in lieu of a cash refund) or store_credit (a named account balance) — the latter two normally carry customerId. expiresAt is optional; omit it for an instrument that never expires. PUTS REAL VALUE INTO CIRCULATION, so confirm the amount before calling. Safe to retry: the caller-chosen id/code make it effectively idempotent — a retry after a timeout 409s rather than minting a second card. To mint many at once use the import operation.
A valid request URL is required to generate request examples{
"id": "gc-2026-000142",
"code": "GC-4F2A-9B71",
"kind": "gift_card",
"currency": "EUR",
"initialBalanceCents": 5000,
"balanceCents": 5000,
"status": "active",
"expiresAt": "2028-01-31T23:59:59.000Z"
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123,
"fieldErrors": [
{
"field": "<string>",
"message": "<string>"
}
]
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}Authorizations
Authorization: Bearer <token>. Accepts EITHER a Keycloak access token (scopes-in-token) OR an opaque POS session token; both resolve to the same pos.* scope vocabulary the route guards enforce.
Body
1gift_card, credit_note, store_credit 130 < x <= 90071992547409911^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$Response
The minted instrument, active at its full issuance value.
The minted instrument, active at its full issuance value.
1gift_card, credit_note, store_credit 130 <= x <= 90071992547409910 <= x <= 9007199254740991active, depleted, void 1^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$