Giftcards API (B2B)

Retrieve and manage giftcards via the API.
All endpoints are protected using Laravel Sanctum.

---

Authentication

All requests must be authenticated using a Bearer token.

Required headers

Authorization: Bearer <SANCTUM_TOKEN> Accept: application/json Content-Type: application/json

If authentication fails, the API returns 401 Unauthorized.

---

Base URL

All giftcard endpoints are available under:

/api/giftcards

---

Available Endpoints

Method	Endpoint	Description
POST	/api/giftcards/retrieve	Retrieve full giftcard information
POST	/api/giftcards/balance	Retrieve the current giftcard balance
POST	/api/giftcards/activate	Activate a giftcard with a given amount
POST	/api/giftcards/reload	Reload an existing giftcard
POST	/api/giftcards/redeem	Redeem an amount from the giftcard
POST	/api/giftcards/block	Block a giftcard
POST	/api/giftcards/unblock	Unblock a giftcard

---

Retrieve Giftcard

Retrieve full information for a giftcard by its code.

Endpoint

POST /api/giftcards/retrieve

Request Body

Field	Type	Required	Description
giftcard_code	string	Yes	The unique giftcard code

Example Request

{
  "giftcard_code": "6064362450282800076"
}

Responses

200 OK

{
  "message": "Giftcard retrieved successfully",
  "giftcard": {
    "code": "6064362450282800076",
    "status": "Normal",
    "brand_name": "Example Brand",
    "ean": "1234567890123",
    "currency": "EUR",
    "balance": 50,
    "balance_factor": 100,
    "activated": true,
    "blocked": false,
    "handled": true
  }
}

404 Not Found

{
  "message": "Giftcard not found",
  "giftcard": {
    "code": "6064362450282800076",
    "handled": false,
    "activated": false,
    "blocked": false,
    "status": null
  }
}

Balance

Retrieve the current balance for a giftcard.

Endpoint

POST /api/giftcards/balance

Request Body

Field	Type	Required	Description
giftcard_code	string	Yes	The unique giftcard code

Example Request

{
  "giftcard_code": "6064362450282800076"
}

Responses

200 OK

{
  "message": "Balance retrieved successfully",
  "giftcard": {
    "code": "6064362450282800076",
    "status": "Normal",
    "brand_name": "Example Brand",
    "ean": "1234567890123",
    "currency": "EUR",
    "balance": 50,
    "balance_factor": 100,
    "activated": true,
    "blocked": false,
    "handled": true
  },
  "balance": {
    "amount": 50,
    "currency": "EUR"
  }
}

404 Not Found

{
  "message": "Giftcard not found"
}

Activate Giftcard

Activate a giftcard with a given amount.

Endpoint

POST /api/giftcards/activate

Request Body

Field	Type	Required	Description
giftcard_code	string	Yes	The unique giftcard code
amount	numeric	Yes	Amount to activate on the giftcard

Example Request

{
  "giftcard_code": "6064362450282800076",
  "amount": 50
}

Responses

200 OK

{
  "message": "Giftcard activated successfully",
  "giftcard": {
    "code": "6064362450282800076",
    "status": "Normal",
    "brand_name": "Example Brand",
    "ean": "1234567890123",
    "currency": "EUR",
    "balance": 50,
    "balance_factor": 100,
    "activated": true,
    "blocked": false,
    "handled": true
  }
}

422 Validation Error

{
  "message": "The given data was invalid.",
  "errors": {
    "amount": [
      "The amount field is required."
    ]
  }
}

422 Action Failed

{
  "message": "Activating giftcard failed"
}

Reload Giftcard

Reload an existing giftcard with an additional amount.

Endpoint

POST /api/giftcards/reload

Request Body

Field	Type	Required	Description
giftcard_code	string	Yes	The unique giftcard code
amount	numeric	Yes	Amount to add to the giftcard

Example Request

{
  "giftcard_code": "6064362450282800076",
  "amount": 25
}

Responses

200 OK

{
  "message": "Giftcard reloaded successfully",
  "giftcard": {
    "code": "6064362450282800076",
    "status": "Normal",
    "brand_name": "Example Brand",
    "ean": "1234567890123",
    "currency": "EUR",
    "balance": 75,
    "balance_factor": 100,
    "activated": true,
    "blocked": false,
    "handled": true
  }
}

422 Action Failed

{
  "message": "Reloading giftcard failed"
}

Redeem Giftcard

Redeem an amount from a giftcard.

Endpoint

POST /api/giftcards/redeem

Request Body

Field	Type	Required	Description
giftcard_code	string	Yes	The unique giftcard code
amount	numeric	Yes	Amount to redeem from the giftcard

Example Request

{
  "giftcard_code": "6064362450282800076",
  "amount": 10
}

Responses

200 OK

{
  "message": "Giftcard redeemed successfully",
  "giftcard": {
    "code": "6064362450282800076",
    "status": "Normal",
    "brand_name": "Example Brand",
    "ean": "1234567890123",
    "currency": "EUR",
    "balance": 40,
    "balance_factor": 100,
    "activated": true,
    "blocked": false,
    "handled": true
  }
}

422 Insufficient Balance

{
  "message": "Insufficient balance",
  "balance": {
    "amount": 5,
    "currency": "EUR"
  }
}

422 Action Failed

{
  "message": "Redeeming giftcard failed"
}

404 Not Found

{
  "message": "Giftcard not found"
}

Block Giftcard

Block a giftcard.

A reason can optionally be provided.

Endpoint

POST /api/giftcards/block

Request Body

Field	Type	Required	Description
giftcard_code	string	Yes	The unique giftcard code
reason	string	No	Optional reason for blocking the giftcard

Example Request

{
  "giftcard_code": "6064362450282800076",
  "reason": "Fraud suspicion"
}

Responses

200 OK

{
  "message": "Giftcard blocked successfully"
}

422 Action Failed

{
  "message": "Blocking giftcard failed"
}

Unblock Giftcard

Unblock a previously blocked giftcard.

Endpoint

POST /api/giftcards/unblock

Request Body

Field	Type	Required	Description
giftcard_code	string	Yes	The unique giftcard code
reason	string	No	Optional reason for unblocking the giftcard

Example Request

{
  "giftcard_code": "6064362450282800076",
  "reason": "Issue resolved"
}

Responses

200 OK

{
  "message": "Giftcard unblocked successfully"
}

422 Action Failed

{
  "message": "Unblocking giftcard failed"
}

Error Responses

401 Unauthorized

Returned when:

• No token is provided
• Token is invalid
• Token is expired

422 Validation Error

{
  "message": "The given data was invalid.",
  "errors": {
    "giftcard_code": [
      "The giftcard_code field is required."
    ]
  }
}

500 Server Error

{
"message": "Server error"
}