Gift cards

Public booking API · https://api.conciar.com/public/v1

Selling the restaurant's gift cards online. Separate limits: 60 reads and 6 purchases per minute per restaurant and IP. Here the restaurant is matched on its exact guid or current handle, and an unknown restaurant or token is a plain 404 without a code.

INFO

La référence de l’API est en anglais.

Gift card settings

Whether gift cards are on sale (reason when not: NO_RESTAURANT, DISABLED or NO_ONLINE_PAYMENTS), the preset amounts, the custom amount range and how long cards stay valid.

GET/public/v1/restaurants/{organization_guid}/gift-cards

Sans clé

Limite de débit: 60/min per restaurant and IP

Paramètres de chemin

organization_guidstringobligatoire
The restaurant's guid or its current handle, matched exactly (no @, no former handles).

Paramètres de requête

langstring
en, nl, de, fr or es. Falls back to Accept-Language, then the restaurant's language, then en.

Codes de statut

404Unknown restaurant (plain {message}).

Bon à savoir

A restaurant that does not sell gift cards online still answers 200, with available: false, the reason and presets: [].

curl "https://api.conciar.com/public/v1/restaurants/bistro-example/gift-cards" \
  -H "Accept: application/json"

Exemple de réponse · 200

{
  "status": true,
  "available": true,
  "reason": null,
  "locale": "en",
  "locales": [
    "en",
    "nl",
    "de",
    "fr",
    "es"
  ],
  "restaurant": {
    "name": "Bistro Example",
    "guid": "00000000000000000",
    "handle": "bistro-example",
    "logo": null,
    "accent": "#1f6f5c",
    "email": "hello@example.com",
    "website": null
  },
  "page_url": "https://r.conciar.com/bistro-example/gift-card",
  "currency": "EUR",
  "presets": [
    {
      "amount": "25.00",
      "minor": 2500,
      "currency": "EUR"
    },
    {
      "amount": "50.00",
      "minor": 5000,
      "currency": "EUR"
    }
  ],
  "allow_custom_amount": true,
  "min_amount": {
    "amount": "10.00",
    "minor": 1000,
    "currency": "EUR"
  },
  "max_amount": {
    "amount": "500.00",
    "minor": 50000,
    "currency": "EUR"
  },
  "validity_months": 24,
  "validity_text": "…"
}

Buy a gift card

Returns the payment page. After paying, the buyer lands on status_url in the Conciar guest app; the card is emailed to the buyer or the recipient.

POST/public/v1/restaurants/{organization_guid}/gift-cards/purchase

Sans clé

Limite de débit: 6/min per restaurant and IP

Paramètres de chemin

organization_guidstringobligatoire
The restaurant's guid or its current handle, matched exactly (no @, no former handles).

Corps

request_idstringobligatoire
Your idempotency id, 8–64 letters, digits or dashes.
amountnumberobligatoire
1–100000; a preset, or within the custom range when allowed.
purchaser_namestringobligatoire
Max 160.
purchaser_emailstringobligatoire
Max 190.
deliver_tostringobligatoire
recipient or buyer.
recipient_namestring
Max 160.
recipient_emailstring
An email address, max 190. Required when deliver_to is recipient.
messagestring
Max 500.
marketing_opt_inboolean
Consent to marketing.
langstring
en, nl, de, fr or es.

Codes de statut

404UNAVAILABLE — unknown restaurant, or it does not sell gift cards online.
409UNAVAILABLE — online payments are not available.
422INVALID (with errors) or INVALID_AMOUNT.
502PAYMENT_FAILED.
503BUSY.

curl -X POST "https://api.conciar.com/public/v1/restaurants/bistro-example/gift-cards/purchase" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "3a9e5f20-0000-4000-8000-000000000000",
    "amount": 50,
    "purchaser_name": "Alex Example",
    "purchaser_email": "alex@example.com",
    "deliver_to": "buyer"
  }'

Exemple de réponse · 201

{
  "status": true,
  "replayed": false,
  "payment_url": "https://payment-provider.example/checkout/…",
  "token": "ExampleGiftCardToken0000000000000000000000000000",
  "status_url": "https://r.conciar.com/bistro-example/gift-card/order/ExampleGiftCardToken0000000000000000000000000000"
}

Purchase status

paid, pending or failed (a payment still pending after two hours counts as failed). card_url when paid, payment_url while pending.

GET/public/v1/restaurants/{organization_guid}/gift-cards/purchase/{token}

Sans clé

Limite de débit: 60/min per restaurant and IP

Paramètres de chemin

organization_guidstringobligatoire
The restaurant's guid or its current handle, matched exactly (no @, no former handles).
tokenstringobligatoire
The 48-character token from the purchase (32–64 accepted).

Codes de statut

404Unknown restaurant or token (plain {message}).

curl "https://api.conciar.com/public/v1/restaurants/bistro-example/gift-cards/purchase/ExampleGiftCardToken0000000000000000000000000000" \
  -H "Accept: application/json"

Exemple de réponse · 200

{
  "status": true,
  "state": "paid",
  "locale": "en",
  "restaurant": {
    "…": "…"
  },
  "amount": {
    "amount": "50.00",
    "minor": 5000,
    "currency": "EUR"
  },
  "to_recipient": false,
  "sent_to": "alex@example.com",
  "card_url": "https://r.conciar.com/bistro-example/gift-card/card/ExampleGiftCardToken0000000000000000000000000000?sig=…",
  "payment_url": null,
  "page_url": "https://r.conciar.com/bistro-example/gift-card"
}

Get the gift card

The paid card itself, for the printable card page: its code, amount, balance and expiry. Needs the signature from card_url. The answer contains the card's redeemable code.

GET/public/v1/restaurants/{organization_guid}/gift-cards/card/{token}

Sans clé

Limite de débit: 60/min per restaurant and IP

Paramètres de chemin

organization_guidstringobligatoire
The restaurant's guid or its current handle, matched exactly (no @, no former handles).
tokenstringobligatoire
The 48-character token from the purchase or card_url (32–64 accepted).

Paramètres de requête

sigstringobligatoire
The signature from card_url. It does not expire.
langstring
en, nl, de, fr or es: show the card in that language. Otherwise the card's own language.

Codes de statut

403INVALID_LINK — missing or wrong sig, or the card is not paid yet.
404Unknown restaurant or token (plain {message}).

Bon à savoir

gift_card.status is active, redeemed, expired or void.

curl "https://api.conciar.com/public/v1/restaurants/bistro-example/gift-cards/card/ExampleGiftCardToken0000000000000000000000000000?sig=signature_from_card_url" \
  -H "Accept: application/json"

Exemple de réponse · 200

{
  "status": true,
  "locale": "en",
  "restaurant": {
    "name": "Bistro Example",
    "guid": "00000000000000000",
    "handle": "bistro-example",
    "logo": null,
    "accent": "#1f6f5c",
    "email": "hello@example.com",
    "website": null
  },
  "gift_card": {
    "code": "…",
    "status": "active",
    "amount": {
      "amount": "50.00",
      "minor": 5000,
      "currency": "EUR"
    },
    "balance": {
      "amount": "50.00",
      "minor": 5000,
      "currency": "EUR"
    },
    "amount_text": "€50.00",
    "balance_text": "€50.00",
    "expires_at": "2028-10-28",
    "expires_text": "28 October 2028",
    "recipient_name": null,
    "purchaser_name": "Alex Example",
    "message": null
  },
  "t": {
    "…": "…"
  }
}

Gift cards ​

Gift card settings ​

Paramètres de chemin

Paramètres de requête

Codes de statut

Bon à savoir

Buy a gift card ​

Paramètres de chemin

Corps

Codes de statut

Purchase status ​

Paramètres de chemin

Codes de statut

Get the gift card ​

Paramètres de chemin

Paramètres de requête

Codes de statut

Bon à savoir

Gift cards

Gift card settings

Buy a gift card

Purchase status

Get the gift card