Paystone DataCandy API

openapi: 3.1.0
info:
  title: DataCandy API
  description: 'REST API for the DataCandy platform. Provides endpoints for managing merchants,

    clients, contacts, account types, transactions, webhooks, and portal configuration.


    All endpoints require a JWT bearer token unless stated otherwise.'
  version: 26.7.1.0-d9107e6
servers:
- url: /
  description: ''
paths:
  /v1/clients/{accessKey}/portals/balance:
    get:
      operationId: api_v1clients_accessKeyportalsbalance_get_collection
      tags:
      - Balance Portal
      responses:
        200:
          description: List of balance portal configurations.
          content:
            application/ld+json:
              schema:
                type: object
                description: BalancePortal.jsonld-balance_portal.read collection.
                allOf:
                - $ref: '#/components/schemas/HydraCollectionBaseSchema'
                - type: object
                  required:
                  - hydra:member
                  properties:
                    hydra:member:
                      type: array
                      items:
                        $ref: '#/components/schemas/BalancePortal.jsonld-balance_portal.read'
        403:
          description: Forbidden — token does not have the required role.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: Access Denied.
        401:
          description: Unauthorized — missing or invalid JWT token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: JWT Token not found
      summary: Retrieve balance portal configurations for a client.
      description: Retrieves the collection of BalancePortal resources.
      parameters:
      - name: accessKey
        in: path
        description: Unique access key identifying the client.
        required: true
        deprecated: false
        schema:
          type: string
        style: simple
        explode: false
        example: abc123def456
      security:
      - JWT: {}
  /v1/clients:
    get:
      operationId: api_v1clients_get_collection
      tags:
      - Client Management
      responses:
        200:
          description: List of clients.
          content:
            application/ld+json:
              schema:
                type: object
                description: Client.jsonld-client.read collection.
                allOf:
                - $ref: '#/components/schemas/HydraCollectionBaseSchema'
                - type: object
                  required:
                  - hydra:member
                  properties:
                    hydra:member:
                      type: array
                      items:
                        $ref: '#/components/schemas/Client.jsonld-client.read'
        403:
          description: Forbidden — token does not have the required role.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: Access Denied.
        401:
          description: Unauthorized — missing or invalid JWT token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: JWT Token not found
      summary: Retrieve all clients in the portfolio.
      description: Retrieves the collection of Client resources.
      parameters:
      - name: page
        in: query
        description: The collection page number
        required: false
        deprecated: false
        schema:
          type: integer
          default: 1
        style: form
        explode: false
      - name: itemsPerPage
        in: query
        description: The number of items per page
        required: false
        deprecated: false
        schema:
          type: integer
          default: 30
          minimum: 0
          maximum: 30
        style: form
        explode: false
      security:
      - JWT: {}
    post:
      operationId: api_v1clients_post
      tags:
      - Client Management
      responses:
        201:
          description: Client created successfully.
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/Client.jsonld-client.read'
        400:
          description: Invalid input
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/Error.jsonld'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          links: null
        422:
          description: Validation error — see violations array for field-level details.
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/ConstraintViolation.jsonld'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConstraintViolation'
            application/json:
              schema:
                $ref: '#/components/schemas/ConstraintViolation'
        403:
          description: Forbidden — token does not have the required role.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: Access Denied.
        401:
          description: Unauthorized — missing or invalid JWT token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: JWT Token not found
      summary: Create a new client.
      description: "Creates a new client and provisions its database, account types, and product packages.\
        \  \n**Required fields:** `name`, `hostname`, `country`, `timeZone`, `currency`, `languages`,\
        \ `programs`, `companyInfo`  \n**For loyalty clients:** also requires `accumulationRatioNumerator`,\
        \ `accumulationRatioDenominator`, `debitRatioNumerator`, `debitRatioDenominator`  \n**For Moneris\
        \ portfolios:** also requires `configureEgift`, `configureEloyalty`, `configureMemberPortal`,\
        \ `giftCardsRestrictedWhereActivated`, `enableSboEmailAndSms`"
      parameters: {}
      requestBody:
        description: The new Client resource
        content:
          application/ld+json:
            schema:
              $ref: '#/components/schemas/Client-client.write'
        required: true
      security:
      - JWT: {}
  /v1/clients/{id}:
    get:
      operationId: api_v1clients_id_get
      tags:
      - Client Management
      responses:
        200:
          description: Client retrieved successfully.
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/Client.jsonld-client.read'
        403:
          description: Forbidden — token does not have the required role.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: Access Denied.
        404:
          description: Not found — the requested resource does not exist.
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/Error.jsonld'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        401:
          description: Unauthorized — missing or invalid JWT token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: JWT Token not found
      summary: Retrieve a client by ID.
      description: Retrieves a Client resource.
      parameters:
      - name: id
        in: path
        description: Numeric client ID.
        required: true
        deprecated: false
        schema:
          type: integer
        style: simple
        explode: false
        example: 42
      security:
      - JWT: {}
    patch:
      operationId: api_v1clients_id_patch
      tags:
      - Client Management
      responses:
        200:
          description: Client updated successfully.
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/Client.jsonld-client.read'
        400:
          description: Invalid input
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/Error.jsonld'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          links: null
        422:
          description: Validation error — see violations array for field-level details.
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/ConstraintViolation.jsonld'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConstraintViolation'
            application/json:
              schema:
                $ref: '#/components/schemas/ConstraintViolation'
        403:
          description: Forbidden — token does not have the required role.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: Access Denied.
        404:
          description: Not found — the requested resource does not exist.
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/Error.jsonld'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        401:
          description: Unauthorized — missing or invalid JWT token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: JWT Token not found
      summary: Update an existing client.
      description: Updates the Client resource.
      parameters:
      - name: id
        in: path
        description: Numeric client ID.
        required: true
        deprecated: false
        schema:
          type: integer
        style: simple
        explode: false
        example: 42
      requestBody:
        description: The updated Client resource
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/Client-client.patch.jsonMergePatch'
        required: true
      security:
      - JWT: {}
  /v1/clients/{id}/complete:
    post:
      operationId: api_v1clients_idcomplete_post
      tags:
      - Client Management
      responses:
        201:
          description: Client resource created
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/Client.jsonld-client.complete.read'
          links: null
        400:
          description: Invalid input
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/Error.jsonld'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          links: null
        422:
          description: Validation error — see violations array for field-level details.
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/ConstraintViolation.jsonld'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConstraintViolation'
            application/json:
              schema:
                $ref: '#/components/schemas/ConstraintViolation'
        403:
          description: Forbidden — token does not have the required role.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: Access Denied.
        200:
          description: Client onboarding completed.
        401:
          description: Unauthorized — missing or invalid JWT token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: JWT Token not found
        404:
          description: Not found — the requested resource does not exist.
      summary: Complete client onboarding.
      description: 'Marks onboarding as complete and records the `completedOn` timestamp.

        After this call the client is active and ready to process transactions.'
      parameters:
      - name: id
        in: path
        description: Numeric client ID.
        required: true
        deprecated: false
        schema:
          type: integer
        style: simple
        explode: false
        example: 42
      requestBody:
        description: The new Client resource
        content:
          application/ld+json:
            schema:
              $ref: '#/components/schemas/Client-client.complete'
        required: true
      security:
      - JWT: {}
  /contacts:
    get:
      operationId: api_contacts_get_collection
      tags:
      - Contact
      responses:
        200:
          description: List of contacts.
          content:
            application/ld+json:
              schema:
                type: object
                description: Contact.jsonld-contact.read collection.
                allOf:
                - $ref: '#/components/schemas/HydraCollectionBaseSchema'
                - type: object
                  required:
                  - hydra:member
                  properties:
                    hydra:member:
                      type: array
                      items:
                        $ref: '#/components/schemas/Contact.jsonld-contact.read'
        403:
          description: Forbidden — token does not have the required role.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: Access Denied.
        401:
          description: Unauthorized — missing or invalid JWT token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: JWT Token not found
      summary: Retrieve all contacts.
      description: Retrieves the collection of Contact resources.
      parameters:
      - name: page
        in: query
        description: The collection page number
        required: false
        deprecated: false
        schema:
          type: integer
          default: 1
        style: form
        explode: false
      - name: itemsPerPage
        in: query
        description: The number of items per page
        required: false
        deprecated: false
        schema:
          type: integer
          default: 30
          minimum: 0
          maximum: 30
        style: form
        explode: false
      - name: isActive
        in: query
        description: Contact isActive
        required: false
        deprecated: false
        schema:
          type: string
        style: form
        explode: false
      security:
      - JWT: {}
  /contacts/{id}:
    get:
      operationId: api_contacts_id_get
      tags:
      - Contact
      responses:
        200:
          description: Contact retrieved successfully.
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/Contact.jsonld-contact.read'
        403:
          description: Forbidden — token does not have the required role.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: Access Denied.
        404:
          description: Not found — the requested resource does not exist.
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/Error.jsonld'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        401:
          description: Unauthorized — missing or invalid JWT token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: JWT Token not found
      summary: Retrieve a contact by ID.
      description: Retrieves a Contact resource.
      parameters:
      - name: id
        in: path
        description: Numeric contact ID.
        required: true
        deprecated: false
        schema:
          type: integer
        style: simple
        explode: false
        example: 1
      security:
      - JWT: {}
  /v1/clients/{accessKey}/account-types/gift:
    get:
      operationId: api_v1clients_accessKeyaccount-typesgift_get_collection
      tags:
      - Gift Account Type
      responses:
        200:
          description: List of gift account types.
          content:
            application/ld+json:
              schema:
                type: object
                description: GiftAccountType.jsonld-account-type.read collection.
                allOf:
                - $ref: '#/components/schemas/HydraCollectionBaseSchema'
                - type: object
                  required:
                  - hydra:member
                  properties:
                    hydra:member:
                      type: array
                      items:
                        $ref: '#/components/schemas/GiftAccountType.jsonld-account-type.read'
        403:
          description: Forbidden — token does not have the required role.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: Access Denied.
        401:
          description: Unauthorized — missing or invalid JWT token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: JWT Token not found
      summary: Retrieve all gift account types for a client.
      description: Retrieves the collection of GiftAccountType resources.
      parameters:
      - name: accessKey
        in: path
        description: Unique access key identifying the client.
        required: true
        deprecated: false
        schema:
          type: string
        style: simple
        explode: false
        example: abc123def456
      security:
      - JWT: {}
  /v1/clients/{accessKey}/account-types/gift/{id}:
    get:
      operationId: api_v1clients_accessKeyaccount-typesgift_id_get
      tags:
      - Gift Account Type
      responses:
        200:
          description: Gift account type retrieved successfully.
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/GiftAccountType.jsonld-account-type.read'
        403:
          description: Forbidden — token does not have the required role.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: Access Denied.
        404:
          description: Not found — the requested resource does not exist.
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/Error.jsonld'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        401:
          description: Unauthorized — missing or invalid JWT token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: JWT Token not found
      summary: Retrieve a gift account type by ID.
      description: Retrieves a GiftAccountType resource.
      parameters:
      - name: accessKey
        in: path
        description: Unique access key identifying the client.
        required: true
        deprecated: false
        schema:
          type: string
        style: simple
        explode: false
        example: abc123def456
      - name: id
        in: path
        description: Numeric account type ID.
        required: true
        deprecated: false
        schema:
          type: integer
        style: simple
        explode: false
        example: 1
      security:
      - JWT: {}
  /items/{id}:
    get:
      operationId: api_items_id_get
      tags:
      - Item
      responses:
        200:
          description: Item retrieved successfully.
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/Item.jsonld'
        403:
          description: Forbidden — token does not have the required role.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: Access Denied.
        404:
          description: Not found — the requested resource does not exist.
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/Error.jsonld'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        401:
          description: Unauthorized — missing or invalid JWT token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: JWT Token not found
      summary: Retrieve an item by ID.
      description: Retrieves a Item resource.
      parameters:
      - name: id
        in: path
        description: Numeric item ID.
        required: true
        deprecated: false
        schema:
          type: integer
        style: simple
        explode: false
        example: 1
      security:
      - JWT: {}
  /v1/clients/{accessKey}/account-types/loyalty:
    get:
      operationId: api_v1clients_accessKeyaccount-typesloyalty_get_collection
      tags:
      - Loyalty Account Type
      responses:
        200:
          description: List of loyalty account types.
          content:
            application/ld+json:
              schema:
                type: object
                description: LoyaltyAccountType.jsonld-account-type.read collection.
                allOf:
                - $ref: '#/components/schemas/HydraCollectionBaseSchema'
                - type: object
                  required:
                  - hydra:member
                  properties:
                    hydra:member:
                      type: array
                      items:
                        $ref: '#/components/schemas/LoyaltyAccountType.jsonld-account-type.read'
        403:
          description: Forbidden — token does not have the required role.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: Access Denied.
        401:
          description: Unauthorized — missing or invalid JWT token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: JWT Token not found
      summary: Retrieve all loyalty account types for a client.
      description: Retrieves the collection of LoyaltyAccountType resources.
      parameters:
      - name: accessKey
        in: path
        description: Unique access key identifying the client.
        required: true
        deprecated: false
        schema:
          type: string
        style: simple
        explode: false
        example: abc123def456
      security:
      - JWT: {}
  /v1/clients/{accessKey}/account-types/loyalty/{id}:
    get:
      operationId: api_v1clients_accessKeyaccount-typesloyalty_id_get
      tags:
      - Loyalty Account Type
      responses:
        200:
          description: Loyalty account type retrieved successfully.
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/LoyaltyAccountType.jsonld-account-type.read'
        403:
          description: Forbidden — token does not have the required role.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: Access Denied.
        404:
          description: Not found — the requested resource does not exist.
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/Error.jsonld'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        401:
          description: Unauthorized — missing or invalid JWT token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: JWT Token not found
      summary: Retrieve a loyalty account type by ID.
      description: Retrieves a LoyaltyAccountType resource.
      parameters:
      - name: accessKey
        in: path
        description: Unique access key identifying the client.
        required: true
        deprecated: false
        schema:
          type: string
        style: simple
        explode: false
        example: abc123def456
      - name: id
        in: path
        description: Numeric account type ID.
        required: true
        deprecated: false
        schema:
          type: integer
        style: simple
        explode: false
        example: 1
      security:
      - JWT: {}
  /loyalty-transactions:
    get:
      operationId: api_loyalty-transactions_get_collection
      tags:
      - Loyalty Transaction
      responses:
        200:
          description: List of loyalty transactions.
          content:
            application/ld+json:
              schema:
                type: object
                description: LoyaltyTransaction.jsonld-transaction.read collection.
                allOf:
                - $ref: '#/components/schemas/HydraCollectionBaseSchema'
                - type: object
                  required:
                  - hydra:member
                  properties:
                    hydra:member:
                      type: array
                      items:
                        $ref: '#/components/schemas/LoyaltyTransaction.jsonld-transaction.read'
        403:
          description: Forbidden — token does not have the required role.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: Access Denied.
        401:
          description: Unauthorized — missing or invalid JWT token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: JWT Token not found
      summary: Retrieve all loyalty transactions.
      description: Retrieves the collection of 

# --- truncated at 32 KB (208 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paystone/refs/heads/main/openapi/paystone-datacandy-openapi.yml