{"components":{"parameters":{"IdempotencyKey":{"description":"Optional client-generated opaque identifier, unique per logical\noperation (e.g. \"{orderRef}:{lineId}:topup\"). Retrying with the same\nkey is a no-op: the server replays the original success (204) instead\nof applying the operation twice. Max 255 characters. Will become\nrequired in a future API version.\n","in":"header","name":"Idempotency-Key","schema":{"maxLength":255,"minLength":1,"type":"string"}},"IssueIdempotencyKey":{"description":"Strongly recommended. Client-generated opaque identifier, unique per\ncard to issue (e.g. \"{returnId}:refund\"). Scoped to the caller's\norganization. A retry with the same key and body returns the original\ncard (200); the same key with a different body returns 409\n`request/idempotency-conflict`. Without the key a retry issues a new\ncard. Max 255 characters.\n","in":"header","name":"Idempotency-Key","schema":{"maxLength":255,"minLength":1,"type":"string"}},"OptionalXBranchCode":{"description":"Optional branch code (matches branches.code within the caller's\norganization). When present, the issue is attributed to that branch;\nan unknown code returns 400 `request/branch-code-not-found`.\n","in":"header","name":"X-Branch-Code","schema":{"example":"1561254523","type":"string"}},"XBranchCode":{"description":"Branch code (matches branches.code within the caller's organization).\nRequired on sell, top-up, and redeem operations to attribute the\ntransaction to a specific branch. Qboon provides this code per merchant\norganization during onboarding.\n","in":"header","name":"X-Branch-Code","required":true,"schema":{"example":"1561254523","type":"string"}},"XPartnerSource":{"description":"Identifies the integration source (e.g., odoo, shopify-pos, wordpress)","in":"header","name":"X-Partner-Source","required":true,"schema":{"example":"odoo","type":"string"}},"XTeamId":{"description":"Your organization's team ID. A card of another organization returns 404.","in":"header","name":"X-Team-Id","required":true,"schema":{"type":"string"}}},"responses":{"DefaultError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"schemas":{"BasicBranchResponse":{"properties":{"address":{"type":"string"},"code":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"id":{"type":"string"},"name":{"type":"string"},"organizationId":{"type":"string"},"organizationName":{"type":"string"},"phoneNumber":{"type":"string"},"status":{"$ref":"#/components/schemas/api_common-schemas_BranchStatus"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","name","code","address","phoneNumber","organizationId","status","createdAt","updatedAt"],"type":"object"},"BasicReceiptResponse":{"properties":{"id":{"type":"string"},"serialNumber":{"type":"string"}},"required":["id","serialNumber"],"type":"object"},"BatchResponse":{"properties":{"averageBalance":{"format":"int64","type":"integer"},"averageDiscountFactor":{"format":"double","type":"number"},"cardType":{"$ref":"#/components/schemas/api_common-schemas_CardType"},"cardsCount":{"type":"integer"},"createdAt":{"format":"date-time","type":"string"},"createdBy":{"$ref":"#/components/schemas/api_common-schemas_UserResponse"},"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"totalBalance":{"type":"integer"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","key","name","cardsCount","totalBalance","cardType","averageBalance","averageDiscountFactor","createdAt","updatedAt"],"type":"object"},"BranchStatus":{"enum":["ACTIVE","INACTIVE"],"type":"string"},"CardCategoryResponse":{"properties":{"amount":{"format":"int64","type":"integer"},"cardType":{"$ref":"#/components/schemas/api_common-schemas_CardType"},"description":{"type":"string"},"discountFactor":{"format":"double","type":"number"},"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"}},"required":["id","cardType","key","name"],"type":"object"},"CardHolderResponse":{"properties":{"createdAt":{"format":"date-time","type":"string"},"id":{"type":"string"},"identifier":{"type":"string"},"metadata":{"additionalProperties":true,"type":"object"},"mobile":{"type":"string"},"name":{"type":"string"},"organizationId":{"type":"string"},"organizationUnitId":{"type":"string"},"organizationUnitName":{"type":"string"},"status":{"$ref":"#/components/schemas/api_common-schemas_CardHolderStatus"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","name","organizationId","status","createdAt","updatedAt"],"type":"object"},"CardHolderStatus":{"enum":["ACTIVE","INACTIVE"],"type":"string"},"CardOrganizationResponse":{"properties":{"id":{"type":"string"},"isPrimary":{"description":"Indicates if this is the primary organization that owns the card","type":"boolean"},"name":{"type":"string"}},"required":["id","name","isPrimary"],"type":"object"},"CardResponse":{"properties":{"activatedAt":{"format":"date-time","type":"string"},"activatedBy":{"$ref":"#/components/schemas/api_common-schemas_UserResponse"},"balance":{"format":"int64","type":"integer"},"batch":{"$ref":"#/components/schemas/api_common-schemas_BatchResponse"},"cardCategory":{"$ref":"#/components/schemas/api_common-schemas_CardCategoryResponse"},"cardHolders":{"description":"Card holders assigned to this card","items":{"$ref":"#/components/schemas/api_common-schemas_CardHolderResponse"},"type":"array"},"cardType":{"$ref":"#/components/schemas/api_common-schemas_CardType"},"createdAt":{"format":"date-time","type":"string"},"createdBy":{"$ref":"#/components/schemas/api_common-schemas_UserResponse"},"currency":{"description":"Currency of the card balance (ISO 4217). Present on operation and card detail responses.","type":"string"},"discountFactor":{"format":"double","type":"number"},"expiryDate":{"format":"date-time","type":"string"},"faceValue":{"format":"int64","type":"integer"},"id":{"type":"string"},"invoiceNumber":{"description":"Number of the invoice if the card is sold with an invoice","nullable":true,"type":"string"},"last5Digits":{"description":"Last 5 digits of the card multicode","type":"string"},"maxRedemptions":{"type":"integer"},"multicode":{"type":"string"},"notes":{"type":"string"},"organizationId":{"type":"string"},"organizations":{"description":"All organizations where this card can be used","items":{"$ref":"#/components/schemas/api_common-schemas_CardOrganizationResponse"},"type":"array"},"pin":{"description":"PIN of the card","type":"string"},"projectId":{"type":"string"},"projectName":{"description":"Name of the project","nullable":true,"type":"string"},"purchasedAt":{"format":"date-time","type":"string"},"redemptionCount":{"format":"int64","type":"integer"},"reloadable":{"type":"boolean"},"sellingBranchId":{"description":"ID of the branch where the card is sold","nullable":true,"type":"string"},"startDate":{"format":"date-time","type":"string"},"status":{"$ref":"#/components/schemas/api_common-schemas_CardStatus"},"transactions":{"description":"Transactions linked to the card","items":{"$ref":"#/components/schemas/api_common-schemas_TransactionResponse"},"type":"array"},"updatedAt":{"format":"date-time","type":"string"},"validityDays":{"type":"integer"}},"required":["id","multicode","pin","last5Digits","organizationId","status","balance","createdAt","updatedAt","cardType"],"type":"object"},"CardStatus":{"enum":["PENDING","PRINTING_IN_PROGRESS","READY_TO_DISPATCH","DISPATCH_IN_PROGRESS","READY","ACTIVE","REDEEMED","PARTIALLY_REDEEMED","DISABLED","EXPIRED","VOIDED","CANCELLED"],"type":"string"},"CardType":{"enum":["GIFT_VOUCHER","DISCOUNT_CARD","TOPUP_CARD","COUPON_CARD","MARKETPLACE_CARD"],"type":"string"},"Currency":{"description":"ISO 4217 code. Core supports EGP only; other request values are rejected with 400 `request/invalid-fields`.","enum":["EGP"],"type":"string"},"CustomerResponse":{"properties":{"address":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"createdBy":{"$ref":"#/components/schemas/api_common-schemas_UserResponse"},"email":{"type":"string"},"fullName":{"type":"string"},"id":{"type":"string"},"organizationId":{"type":"string"},"phoneNumber":{"type":"string"},"status":{"$ref":"#/components/schemas/api_common-schemas_CustomerStatus"},"totalRedeemCount":{"format":"int64","type":"integer"},"totalSellingCount":{"format":"int64","type":"integer"},"type":{"$ref":"#/components/schemas/api_common-schemas_CustomerType"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","fullName","organizationId","createdAt","updatedAt","status"],"type":"object"},"CustomerStatus":{"enum":["ACTIVE","INACTIVE","BLOCKED"],"type":"string"},"CustomerType":{"enum":["ODOO"],"type":"string"},"Error":{"properties":{"code":{"type":"string"},"errors":{"type":"string"}},"required":["code","errors"],"type":"object"},"IssueCardRequest":{"additionalProperties":false,"description":"Unknown fields (for example the removed `cardCategoryId`) return 400 `request/invalid-fields` naming the field.","properties":{"amount":{"description":"Amount to load in piasters (EGP 50 – 50,000). Out-of-range values return 400 `request/invalid-fields`.","format":"int64","maximum":5000000,"minimum":5000,"type":"integer"},"cardType":{"$ref":"#/components/schemas/IssueCardType"},"currency":{"$ref":"#/components/schemas/Currency"},"reference":{"description":"Optional external reference (e.g. a return or order ID), stored on the card and its load transaction and echoed in the response.","maxLength":100,"type":"string"}},"required":["amount","currency"],"type":"object"},"IssueCardResponse":{"properties":{"balance":{"description":"Current balance in piasters. Equals `amount` on first issue.","format":"int64","type":"integer"},"barcode":{"description":"12-digit CODE128 barcode value for in-store scanning.","type":"string"},"cardType":{"$ref":"#/components/schemas/CardType"},"code":{"description":"16-digit card number. Shown to the cardholder and entered with the PIN to redeem.","type":"string"},"currency":{"$ref":"#/components/schemas/Currency"},"expiresAt":{"description":"Expiry time, 365 days after issue.","format":"date-time","type":"string"},"id":{"description":"Card ID.","type":"string"},"pin":{"description":"4-digit PIN.","type":"string"},"reference":{"description":"The `reference` sent on issue, if any.","type":"string"},"status":{"$ref":"#/components/schemas/CardStatus"}},"required":["id","code","pin","barcode","balance","currency","cardType","status","expiresAt"],"type":"object"},"IssueCardType":{"default":"TOPUP_CARD","description":"Kind of card to issue. TOPUP_CARD can be redeemed in parts; GIFT_VOUCHER must be redeemed in full. Omitted or null means TOPUP_CARD. Other values return 400 `request/invalid-fields`.","enum":["TOPUP_CARD","GIFT_VOUCHER"],"nullable":true,"type":"string"},"OperationValidation":{"properties":{"enabled":{"description":"Whether the operation can proceed","type":"boolean"},"errorMessage":{"description":"Error message if operation is not enabled","type":"string"},"errorType":{"description":"- destructive: Operation cannot proceed (red error, disable button)\n- warning: Operation can proceed but with warning (yellow warning, enable button)\n","enum":["destructive","warning"],"type":"string"},"nextStatus":{"$ref":"#/components/schemas/api_common-schemas_CardStatus"}},"required":["enabled"],"type":"object"},"PartnerCustomerDetails":{"description":"Optional customer details forwarded from the partner integration\n(e.g. the POS terminal's identified customer). All fields are\noptional. The backend matches an existing customer by email, then\nphone; otherwise it creates one (the name may be blank) and attaches\nit to the operation. If omitted or empty, the backend falls back to the\norganization's default ODOO-typed customer, or runs the operation\nanonymously when no default exists.\n","properties":{"email":{"description":"Malformed values are ignored.","type":"string"},"fullName":{"type":"string"},"phoneNumber":{"type":"string"}},"type":"object"},"PartnerPermission":{"description":"Partner-specific permissions for card operations. These permissions are used in the security definitions of partner API endpoints.","enum":["card.sell","card.topup","card.redeem","card.verify","card.issue","card.void"],"type":"string"},"RedeemAmountRequest":{"properties":{"amount":{"description":"Amount to redeem in piasters. Gift vouchers (GIFT_VOUCHER) must redeem the full current balance; partial amounts are rejected.","format":"int64","type":"integer"},"currency":{"$ref":"#/components/schemas/Currency"},"customerDetails":{"$ref":"#/components/schemas/PartnerCustomerDetails"},"retailInvoiceNumber":{"type":"string"}},"required":["amount","retailInvoiceNumber"],"type":"object"},"RedeemDiscountRequest":{"properties":{"retailInvoiceAmountAfterDiscount":{"format":"int64","type":"integer"},"retailInvoiceAmountBeforeDiscount":{"format":"int64","type":"integer"},"retailInvoiceNumber":{"type":"string"}},"required":["retailInvoiceNumber"],"type":"object"},"SellCardRequest":{"properties":{"customerDetails":{"$ref":"#/components/schemas/PartnerCustomerDetails"},"retailInvoiceNumber":{"type":"string"}},"required":["retailInvoiceNumber"],"type":"object"},"TopUpCardRequest":{"properties":{"amount":{"format":"int64","type":"integer"},"currency":{"$ref":"#/components/schemas/Currency"},"customerDetails":{"$ref":"#/components/schemas/PartnerCustomerDetails"},"retailInvoiceNumber":{"type":"string"}},"required":["amount","retailInvoiceNumber"],"type":"object"},"TransactionResponse":{"properties":{"amount":{"format":"int64","type":"integer"},"branch":{"$ref":"#/components/schemas/api_common-schemas_BasicBranchResponse"},"card":{"$ref":"#/components/schemas/api_common-schemas_CardResponse"},"cardId":{"type":"string"},"currency":{"$ref":"#/components/schemas/api_common-schemas_Currency"},"customer":{"$ref":"#/components/schemas/api_common-schemas_CustomerResponse"},"customerId":{"type":"string"},"id":{"type":"string"},"receipts":{"items":{"$ref":"#/components/schemas/api_common-schemas_BasicReceiptResponse"},"type":"array"},"retailInvoiceNumber":{"description":"Number of the invoice if the transaction is linked to an invoice","type":"string"},"timestamp":{"format":"date-time","type":"string"},"transactionType":{"$ref":"#/components/schemas/api_common-schemas_TransactionType"},"user":{"$ref":"#/components/schemas/api_common-schemas_UserResponse"},"userId":{"type":"string"}},"required":["id","cardId","amount","timestamp","userId","transactionType","currency","customerId"],"type":"object"},"TransactionType":{"enum":["LOAD","REDEEM","REFUND","CANCEL","UNLOAD","ISSUE"],"type":"string"},"UserResponse":{"properties":{"createdAt":{"format":"date-time","type":"string"},"email":{"type":"string"},"fullName":{"type":"string"},"id":{"type":"string"},"lastLogin":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","email","fullName","createdAt","updatedAt"],"type":"object"},"VerifyCardRequest":{"properties":{"multicode":{"type":"string"},"pin":{"type":"string"},"sourceOperation":{"$ref":"#/components/schemas/WizardOperationType"}},"required":["multicode","pin","sourceOperation"],"type":"object"},"VerifyCardResponse":{"properties":{"card":{"$ref":"#/components/schemas/api_common-schemas_CardResponse"},"operationValidation":{"$ref":"#/components/schemas/api_common-schemas_OperationValidation"},"valid":{"description":"Whether card exists and PIN is correct","type":"boolean"}},"required":["valid"],"type":"object"},"VoidCardRequest":{"additionalProperties":false,"description":"Unknown fields return 400 `request/invalid-fields` naming the field.","properties":{"reason":{"description":"Optional reason (e.g. a return ID), stored on the CANCEL transaction.","maxLength":255,"type":"string"}},"type":"object"},"VoidCardResponse":{"properties":{"balance":{"description":"Balance after the void in piasters (0).","format":"int64","type":"integer"},"id":{"description":"Card ID.","type":"string"},"status":{"$ref":"#/components/schemas/CardStatus"},"voidedAmount":{"description":"Balance this call reversed, in piasters. 0 when the card was already void.","format":"int64","type":"integer"}},"required":["id","status","balance","voidedAmount"],"type":"object"},"WizardOperationType":{"enum":["SELL_CARD","REDEEM_CARD","TOPUP_CARD","VIEW_CARD_BALANCE"],"type":"string"},"api_common-schemas_BasicBranchResponse":{"properties":{"address":{"type":"string"},"code":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"id":{"type":"string"},"name":{"type":"string"},"organizationId":{"type":"string"},"organizationName":{"type":"string"},"phoneNumber":{"type":"string"},"status":{"$ref":"#/components/schemas/api_common-schemas_BranchStatus"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","name","code","address","phoneNumber","organizationId","status","createdAt","updatedAt"],"type":"object"},"api_common-schemas_BasicReceiptResponse":{"properties":{"id":{"type":"string"},"serialNumber":{"type":"string"}},"required":["id","serialNumber"],"type":"object"},"api_common-schemas_BatchResponse":{"properties":{"averageBalance":{"format":"int64","type":"integer"},"averageDiscountFactor":{"format":"double","type":"number"},"cardType":{"$ref":"#/components/schemas/api_common-schemas_CardType"},"cardsCount":{"type":"integer"},"createdAt":{"format":"date-time","type":"string"},"createdBy":{"$ref":"#/components/schemas/api_common-schemas_UserResponse"},"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"totalBalance":{"type":"integer"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","key","name","cardsCount","totalBalance","cardType","averageBalance","averageDiscountFactor","createdAt","updatedAt"],"type":"object"},"api_common-schemas_BranchStatus":{"enum":["ACTIVE","INACTIVE"],"type":"string"},"api_common-schemas_CardCategoryResponse":{"properties":{"amount":{"format":"int64","type":"integer"},"cardType":{"$ref":"#/components/schemas/api_common-schemas_CardType"},"description":{"type":"string"},"discountFactor":{"format":"double","type":"number"},"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"}},"required":["id","cardType","key","name"],"type":"object"},"api_common-schemas_CardHolderResponse":{"properties":{"createdAt":{"format":"date-time","type":"string"},"id":{"type":"string"},"identifier":{"type":"string"},"metadata":{"additionalProperties":true,"type":"object"},"mobile":{"type":"string"},"name":{"type":"string"},"organizationId":{"type":"string"},"organizationUnitId":{"type":"string"},"organizationUnitName":{"type":"string"},"status":{"$ref":"#/components/schemas/api_common-schemas_CardHolderStatus"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","name","organizationId","status","createdAt","updatedAt"],"type":"object"},"api_common-schemas_CardHolderStatus":{"enum":["ACTIVE","INACTIVE"],"type":"string"},"api_common-schemas_CardOrganizationResponse":{"properties":{"id":{"type":"string"},"isPrimary":{"description":"Indicates if this is the primary organization that owns the card","type":"boolean"},"name":{"type":"string"}},"required":["id","name","isPrimary"],"type":"object"},"api_common-schemas_CardResponse":{"properties":{"activatedAt":{"format":"date-time","type":"string"},"activatedBy":{"$ref":"#/components/schemas/api_common-schemas_UserResponse"},"balance":{"format":"int64","type":"integer"},"batch":{"$ref":"#/components/schemas/api_common-schemas_BatchResponse"},"cardCategory":{"$ref":"#/components/schemas/api_common-schemas_CardCategoryResponse"},"cardHolders":{"description":"Card holders assigned to this card","items":{"$ref":"#/components/schemas/api_common-schemas_CardHolderResponse"},"type":"array"},"cardType":{"$ref":"#/components/schemas/api_common-schemas_CardType"},"createdAt":{"format":"date-time","type":"string"},"createdBy":{"$ref":"#/components/schemas/api_common-schemas_UserResponse"},"currency":{"description":"Currency of the card balance (ISO 4217). Present on operation and card detail responses.","type":"string"},"discountFactor":{"format":"double","type":"number"},"expiryDate":{"format":"date-time","type":"string"},"faceValue":{"format":"int64","type":"integer"},"id":{"type":"string"},"invoiceNumber":{"description":"Number of the invoice if the card is sold with an invoice","nullable":true,"type":"string"},"last5Digits":{"description":"Last 5 digits of the card multicode","type":"string"},"maxRedemptions":{"type":"integer"},"multicode":{"type":"string"},"notes":{"type":"string"},"organizationId":{"type":"string"},"organizations":{"description":"All organizations where this card can be used","items":{"$ref":"#/components/schemas/api_common-schemas_CardOrganizationResponse"},"type":"array"},"pin":{"description":"PIN of the card","type":"string"},"projectId":{"type":"string"},"projectName":{"description":"Name of the project","nullable":true,"type":"string"},"purchasedAt":{"format":"date-time","type":"string"},"redemptionCount":{"format":"int64","type":"integer"},"reloadable":{"type":"boolean"},"sellingBranchId":{"description":"ID of the branch where the card is sold","nullable":true,"type":"string"},"startDate":{"format":"date-time","type":"string"},"status":{"$ref":"#/components/schemas/api_common-schemas_CardStatus"},"transactions":{"description":"Transactions linked to the card","items":{"$ref":"#/components/schemas/api_common-schemas_TransactionResponse"},"type":"array"},"updatedAt":{"format":"date-time","type":"string"},"validityDays":{"type":"integer"}},"required":["id","multicode","pin","last5Digits","organizationId","status","balance","createdAt","updatedAt","cardType"],"type":"object"},"api_common-schemas_CardStatus":{"enum":["PENDING","PRINTING_IN_PROGRESS","READY_TO_DISPATCH","DISPATCH_IN_PROGRESS","READY","ACTIVE","REDEEMED","PARTIALLY_REDEEMED","DISABLED","EXPIRED","VOIDED","CANCELLED"],"type":"string"},"api_common-schemas_CardType":{"enum":["GIFT_VOUCHER","DISCOUNT_CARD","TOPUP_CARD","COUPON_CARD","MARKETPLACE_CARD"],"type":"string"},"api_common-schemas_Currency":{"description":"ISO 4217 code. Core supports EGP only; other request values are rejected with 400 `request/invalid-fields`.","enum":["EGP"],"type":"string"},"api_common-schemas_CustomerResponse":{"properties":{"address":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"createdBy":{"$ref":"#/components/schemas/api_common-schemas_UserResponse"},"email":{"type":"string"},"fullName":{"type":"string"},"id":{"type":"string"},"organizationId":{"type":"string"},"phoneNumber":{"type":"string"},"status":{"$ref":"#/components/schemas/api_common-schemas_CustomerStatus"},"totalRedeemCount":{"format":"int64","type":"integer"},"totalSellingCount":{"format":"int64","type":"integer"},"type":{"$ref":"#/components/schemas/api_common-schemas_CustomerType"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","fullName","organizationId","createdAt","updatedAt","status"],"type":"object"},"api_common-schemas_CustomerStatus":{"enum":["ACTIVE","INACTIVE","BLOCKED"],"type":"string"},"api_common-schemas_CustomerType":{"enum":["ODOO"],"type":"string"},"api_common-schemas_OperationValidation":{"properties":{"enabled":{"description":"Whether the operation can proceed","type":"boolean"},"errorMessage":{"description":"Error message if operation is not enabled","type":"string"},"errorType":{"description":"- destructive: Operation cannot proceed (red error, disable button)\n- warning: Operation can proceed but with warning (yellow warning, enable button)\n","enum":["destructive","warning"],"type":"string"},"nextStatus":{"$ref":"#/components/schemas/api_common-schemas_CardStatus"}},"required":["enabled"],"type":"object"},"api_common-schemas_TransactionResponse":{"properties":{"amount":{"format":"int64","type":"integer"},"branch":{"$ref":"#/components/schemas/api_common-schemas_BasicBranchResponse"},"card":{"$ref":"#/components/schemas/api_common-schemas_CardResponse"},"cardId":{"type":"string"},"currency":{"$ref":"#/components/schemas/api_common-schemas_Currency"},"customer":{"$ref":"#/components/schemas/api_common-schemas_CustomerResponse"},"customerId":{"type":"string"},"id":{"type":"string"},"receipts":{"items":{"$ref":"#/components/schemas/api_common-schemas_BasicReceiptResponse"},"type":"array"},"retailInvoiceNumber":{"description":"Number of the invoice if the transaction is linked to an invoice","type":"string"},"timestamp":{"format":"date-time","type":"string"},"transactionType":{"$ref":"#/components/schemas/api_common-schemas_TransactionType"},"user":{"$ref":"#/components/schemas/api_common-schemas_UserResponse"},"userId":{"type":"string"}},"required":["id","cardId","amount","timestamp","userId","transactionType","currency","customerId"],"type":"object"},"api_common-schemas_TransactionType":{"enum":["LOAD","REDEEM","REFUND","CANCEL","UNLOAD","ISSUE"],"type":"string"},"api_common-schemas_UserResponse":{"properties":{"createdAt":{"format":"date-time","type":"string"},"email":{"type":"string"},"fullName":{"type":"string"},"id":{"type":"string"},"lastLogin":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","email","fullName","createdAt","updatedAt"],"type":"object"},"api_common-schemas_VerifyCardResponse":{"properties":{"card":{"$ref":"#/components/schemas/api_common-schemas_CardResponse"},"operationValidation":{"$ref":"#/components/schemas/api_common-schemas_OperationValidation"},"valid":{"description":"Whether card exists and PIN is correct","type":"boolean"}},"required":["valid"],"type":"object"}},"securitySchemes":{"apiKey":{"description":"API key for authentication","in":"header","name":"X-Api-Key","type":"apiKey"}}},"info":{"contact":{"email":"info@qboon.net","name":"Qboon","url":"https://qboon.net/"},"description":"The GCC Core Partner API for external integrations (e.g., Odoo, Shopify) to issue, sell and redeem cards.\n\n**Required headers (canonical names):** `X-Api-Key`, `X-Team-Id`, `X-Partner-Source`, and `X-Branch-Code` on sell/top-up/redeem. HTTP header names are case-insensitive (RFC 7230); any casing is accepted by the server.\n","title":"Qboon GCC Core Partner API","version":"1.0"},"openapi":"3.0.2","paths":{"/cards/issue":{"post":{"description":"Issues a new ACTIVE gift card in the caller's organization (the\n`X-Team-Id` organization) and loads it with `amount`. The response\ncarries the card's code, PIN and barcode; deliver them to the\ncardholder. The card expires 365 days after issue and can be redeemed\nonline and at any branch of the organization.\n\n`cardType` picks the kind of card: TOPUP_CARD (the default) allows\npartial redemption; GIFT_VOUCHER must be redeemed in full. The card is\nissued under the organization's open-amount category of that type;\nwhen none is set up the call returns 422 `cards/no-issue-category`.\n\nSend an `Idempotency-Key` on every call. A retry with the same key and\nthe same body returns the original card with 200 instead of issuing a\nsecond card. The same key with a different body returns 409\n`request/idempotency-conflict`.\n","operationId":"IssueCard","parameters":[{"$ref":"#/components/parameters/XTeamId"},{"$ref":"#/components/parameters/XPartnerSource"},{"$ref":"#/components/parameters/OptionalXBranchCode"},{"$ref":"#/components/parameters/IssueIdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueCardRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueCardResponse"}}},"description":"Idempotent replay. The card first issued for this Idempotency-Key, in its current state."},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueCardResponse"}}},"description":"Card issued."},"default":{"$ref":"#/components/responses/DefaultError"}},"security":[{"apiKey":["card.issue"]}],"summary":"Issue a gift card","tags":["card"]}},"/cards/verify":{"post":{"description":"Verify a card","operationId":"VerifyCard","parameters":[{"$ref":"#/components/parameters/XTeamId"},{"$ref":"#/components/parameters/XPartnerSource"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyCardRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyCardResponse"}}},"description":"OK"},"default":{"$ref":"#/components/responses/DefaultError"}},"security":[{"apiKey":["card.verify"]}],"tags":["card"]}},"/cards/{cardId}/redeem-amount":{"put":{"description":"Redeem an amount from a card","operationId":"RedeemAmount","parameters":[{"in":"path","name":"cardId","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XTeamId"},{"$ref":"#/components/parameters/XPartnerSource"},{"$ref":"#/components/parameters/XBranchCode"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedeemAmountRequest"}}},"description":"Object containing redeem amount parameters."},"responses":{"204":{"description":"No content"},"default":{"$ref":"#/components/responses/DefaultError"}},"security":[{"apiKey":["card.redeem"]}],"tags":["card"]}},"/cards/{cardId}/redeem-discount":{"post":{"description":"Redeem a discount from a card","operationId":"RedeemDiscount","parameters":[{"in":"path","name":"cardId","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XTeamId"},{"$ref":"#/components/parameters/XPartnerSource"},{"$ref":"#/components/parameters/XBranchCode"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedeemDiscountRequest"}}},"description":"Object containing redeem discount parameters."},"responses":{"204":{"description":"No content"},"default":{"$ref":"#/components/responses/DefaultError"}},"security":[{"apiKey":["card.redeem"]}],"tags":["card"]}},"/cards/{cardId}/sell":{"put":{"description":"Sell a card","operationId":"SellCard","parameters":[{"in":"path","name":"cardId","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XTeamId"},{"$ref":"#/components/parameters/XPartnerSource"},{"$ref":"#/components/parameters/XBranchCode"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellCardRequest"}}},"description":"Object containing sell parameters."},"responses":{"204":{"description":"No content"},"default":{"$ref":"#/components/responses/DefaultError"}},"security":[{"apiKey":["card.sell"]}],"tags":["card"]}},"/cards/{cardId}/top-up":{"put":{"description":"Top up a card","operationId":"TopUpCard","parameters":[{"in":"path","name":"cardId","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XTeamId"},{"$ref":"#/components/parameters/XPartnerSource"},{"$ref":"#/components/parameters/XBranchCode"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopUpCardRequest"}}},"description":"Object containing top up parameters."},"responses":{"204":{"description":"No content"},"default":{"$ref":"#/components/responses/DefaultError"}},"security":[{"apiKey":["card.topup"]}],"tags":["card"]}},"/cards/{cardId}/void":{"post":{"description":"Voids a card in the caller's organization (the `X-Team-Id`\norganization): the card moves to VOIDED and its remaining balance is\nreversed to 0 with one CANCEL transaction. A card of another\norganization, or an unknown card, returns 404 `server/not-found`.\n\nVoiding is idempotent: voiding a card that is already VOIDED (or\nCANCELLED) returns 200 with the card unchanged and `voidedAmount` 0.\nCards that are fully redeemed or expired cannot be voided (409 `cards/invalid-transition`).\n","operationId":"VoidCard","parameters":[{"in":"path","name":"cardId","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XTeamId"},{"$ref":"#/components/parameters/XPartnerSource"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoidCardRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoidCardResponse"}}},"description":"Card voided, or already void."},"default":{"$ref":"#/components/responses/DefaultError"}},"security":[{"apiKey":["card.void"]}],"summary":"Void a card","tags":["card"]}}},"servers":[{"description":"Partner API v1 endpoints","url":"/api/partner/v1"}],"tags":[{"description":"Endpoints for card operations","name":"card"}]}
