Kard users > uploads API

openapi: 3.2.0
info:
  title: Reference users > uploads API
  version: 1.0.0
servers:
- url: https://rewards-api.getkard.com
  description: Production
- url: https://test-rewards-api.getkard.com
  description: Sandbox
tags:
- name: users > uploads
paths:
  /v2/issuers/{organizationId}/users/{userId}/uploads:
    post:
      operationId: create
      summary: Create Upload
      description: '<b>Deprecated.</b> This endpoint is deprecated in favor of the [Create Bulk Transactions Upload URL](/2024-10-01/api/transactions/create-bulk-transactions-upload-url) endpoint. New integrations should use the bulk flow outlined in the [Historical Transaction Uploads](/2024-10-01/api/integration-guides/historical-transaction-uploads) integration guide.


        Call this endpoint to create an upload session and retrieve an upload ID. Using the upload ID in the [Add Upload Part](/2024-10-01/api/transactions/uploads/create-part) endpoint, historical transactions can be sent in batches for further processing.

        <b>Required scopes:</b> `transaction:write`'
      tags:
      - users > uploads
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_OrganizationId'
      - name: userId
        in: path
        description: The ID of the user as defined on the issuers system
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_users_uploads_CreateUploadResponseObject'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_ErrorResponse'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_ErrorResponse'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_users_uploads_CreateUploadRequestObject'
  /v2/issuers/{organizationId}/users/{userId}/uploads/{uploadId}/parts:
    put:
      operationId: create-part
      summary: Add Upload Part
      description: '<b>Deprecated.</b> This endpoint is deprecated in favor of the [Create Bulk Transactions Upload URL](/2024-10-01/api/transactions/create-bulk-transactions-upload-url) endpoint. New integrations should use the bulk flow outlined in the [Historical Transaction Uploads](/2024-10-01/api/integration-guides/historical-transaction-uploads) integration guide.


        Call this endpoint using the upload ID provided in the [Create Upload](/2024-10-01/api/transactions/uploads/create) endpoint to add parts to your upload. Currently, this endpoint supports adding historical transactions.

        <b>Required scopes:</b> `transaction:write`

        <b>Note:</b> `Maximum of 500 transactions can be uploaded per request`.'
      tags:
      - users > uploads
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_OrganizationId'
      - name: userId
        in: path
        description: The ID of the user as defined on the issuers system
        required: true
        schema:
          type: string
      - name: uploadId
        in: path
        description: The upload ID identifying the upload session to add parts
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_users_uploads_CreateUploadPartResponseObject'
        '207':
          description: Error response with status 207
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_users_uploads_CreateUploadPartMultiStatusResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_ErrorResponse'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_ErrorResponse'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_users_uploads_CreateUploadPartRequestObject'
  /v2/issuers/{organizationId}/users/{userId}/uploads/{uploadId}:
    put:
      operationId: update
      summary: Update Upload
      description: '<b>Deprecated.</b> This endpoint is deprecated in favor of the [Create Bulk Transactions Upload URL](/2024-10-01/api/transactions/create-bulk-transactions-upload-url) endpoint. New integrations should use the bulk flow outlined in the [Historical Transaction Uploads](/2024-10-01/api/integration-guides/historical-transaction-uploads) integration guide.


        Call this endpoint to update your upload session. Currently, you can signal completing a historical transactions upload.

        <b>Required scopes:</b> `transaction:write`'
      tags:
      - users > uploads
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_OrganizationId'
      - name: userId
        in: path
        description: The ID of the user as defined on the issuers system
        required: true
        schema:
          type: string
      - name: uploadId
        in: path
        description: The upload ID identifying the upload session to update
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_users_uploads_UpdateUploadResponseObject'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_ErrorResponse'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_ErrorResponse'
        '409':
          description: Error response with status 409
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_ErrorResponse'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_users_uploads_UpdateUploadRequestObject'
components:
  schemas:
    type_users_uploads_CreateUploadPartResponseDataUnion:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - historicalTransaction
            description: 'Discriminator value: historicalTransaction'
          id:
            type: string
            description: Id of the upload to add parts
          attributes:
            $ref: '#/components/schemas/type_commons_EmptyObject'
        required:
        - type
        - id
        - attributes
      discriminator:
        propertyName: type
      title: CreateUploadPartResponseDataUnion
    type_transactions_TransactionsAttributes:
      type: object
      properties:
        userId:
          type: string
          description: The ID of the user as defined on the issuers system
        amount:
          type: integer
          description: Transaction amount in cents
        subtotal:
          type: integer
          description: The base amount in cents excluding additional charges (such as tips, taxes, and other fees).
        status:
          $ref: '#/components/schemas/type_transactions_TransactionStatus'
          description: Transaction status
        currency:
          type: string
          description: Currency of transaction
        description:
          type: string
          description: Description of transaction - usually includes merchant and other key details on transaction
        description2:
          type: string
          description: Description2 of transaction — usually includes other merchant identifying information
        mcc:
          type: string
          description: Merchant Category Code (usually a 4-digit numerical number). <b>Note, this field is REQUIRED for SOME national offers. We HIGHLY RECOMMEND sending this field as it will be required in the near future.</b>
        coreProviderId:
          type: string
          description: Name of processor associated with transaction
        transactionDate:
          type: string
          format: date-time
          description: Timestamp for <b>REVERSED, RETURNED, DECLINED</b> transaction events; <b>REQUIRED</b> for transactions with <b>REVERSED, RETURNED, DECLINED</b> status. Date string should be in ISO 8601 format i.e.`'YYYY-MM-DDThh:mm:ss.sTZD'` where TZD = time zone designator (Z or +hh:mm or -hh:mm) i.e. `1994-11-05T08:15:30-05:00` OR `1994-11-05T08:15:30Z`
        authorizationDate:
          type: string
          format: date-time
          description: Timestamp for <b>APPROVED</b> transaction event; <b>REQUIRED</b> for transactions with <b>APPROVED</b> status, and <b>HIGHLY RECOMMENDED</b> to include for transactions with a <b>SETTLED</b> status. Date string should be in ISO 8601 format i.e.`'YYYY-MM-DDThh:mm:ss.sTZD'` where TZD = time zone designator (Z or +hh:mm or -hh:mm) i.e. `1994-11-05T08:15:30-05:00 OR 1994-11-05T08:15:30Z`
        settledDate:
          type: string
          format: date-time
          description: Timestamp for <b>SETTLED</b> transaction event, <b>REQUIRED</b> for transactions with <b>SETTLED</b> status. Date string should be in ISO 8601 format i.e.`'YYYY-MM-DDThh:mm:ss.sTZD'` where TZD = time zone designator (Z or +hh:mm or -hh:mm) i.e. `1994-11-05T08:15:30-05:00` OR `1994-11-05T08:15:30Z`
        merchant:
          $ref: '#/components/schemas/type_transactions_Merchant'
          description: Merchant details
        cardPresence:
          type: string
          description: Whether card was present at time of transaction
        panEntryMode:
          type: string
          description: PAN entry mode
        cardBIN:
          type: string
          description: Bank identification number (BIN). Must be a valid BIN of 6 digits. If over 6 digits, please send first 6.
        cardLastFour:
          type: string
          description: Card last four digits.
        authorizationCode:
          type: string
          description: Transaction approval code
        retrievalReferenceNumber:
          type: string
          description: Retrieval Reference Number
        systemTraceAuditNumber:
          type: string
          description: System Trace Audit Number
        acquirerReferenceNumber:
          type: string
          description: Acquirer Reference Number
        direction:
          $ref: '#/components/schemas/type_transactions_DirectionType'
          description: The direction in which the funds flow - DEBIT or CREDIT
        paymentType:
          $ref: '#/components/schemas/type_transactions_TransactionPaymentType'
          description: The type of payment involved in the transaction.
        cardNetwork:
          $ref: '#/components/schemas/type_commons_CardNetwork'
          description: The card network associated with the transaction
        transactionId:
          type: string
          description: The transaction ID
        cardProductId:
          type: string
          description: The card product ID associated with the transaction
        userZipCode:
          type: string
          description: The zip code of the user who made the transaction
        processorMids:
          $ref: '#/components/schemas/type_transactions_ProcessorMid'
          description: Network specific merchant IDs (MIDs) associated with the transaction
        accountId:
          type: string
          description: An account identifier associated to transaction
      required:
      - userId
      - amount
      - status
      - currency
      - description
      - cardBIN
      - cardLastFour
      - direction
      - paymentType
      - transactionId
      title: TransactionsAttributes
    type_users_uploads_CreateUploadRequestDataUnion:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - historicalTransactionStart
            description: 'Discriminator value: historicalTransactionStart'
          attributes:
            $ref: '#/components/schemas/type_commons_EmptyObject'
        required:
        - type
        - attributes
      discriminator:
        propertyName: type
      title: CreateUploadRequestDataUnion
    type_users_uploads_CreateUploadRequestObject:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/type_users_uploads_CreateUploadRequestDataUnion'
      required:
      - data
      title: CreateUploadRequestObject
    type_commons_EmptyObject:
      type: object
      properties: {}
      title: EmptyObject
    type_users_uploads_UpdateUploadRequestDataUnion:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - historicalTransactionComplete
            description: 'Discriminator value: historicalTransactionComplete'
          id:
            type: string
            description: Upload id the issuer can use in reference to the upload session
          attributes:
            $ref: '#/components/schemas/type_commons_EmptyObject'
        required:
        - type
        - id
        - attributes
      discriminator:
        propertyName: type
      title: UpdateUploadRequestDataUnion
    type_commons_ErrorObject:
      type: object
      properties:
        status:
          type: string
          description: Status code returned from the request
        title:
          type: string
          description: Name of error
        detail:
          type: string
          description: Description of the specific occurance of the error
        source:
          $ref: '#/components/schemas/type_commons_ErrorSource'
          description: An object containing a reference to the primary source of the error
        id:
          type: string
          description: The id of the resource which caused the error. Always returned for multi-status errors.
      required:
      - status
      - title
      - detail
      title: ErrorObject
    type_transactions_TransactionStatus:
      type: string
      enum:
      - APPROVED
      - SETTLED
      - REVERSED
      - RETURNED
      - DECLINED
      title: TransactionStatus
    type_users_uploads_CreateUploadPartRequestObject:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/type_users_uploads_CreateUploadPartDataUnion'
      required:
      - data
      title: CreateUploadPartRequestObject
    type_transactions_VisaMidDetails:
      type: object
      properties:
        vmid:
          type: string
          description: Visa Merchant ID (VMID) associated with the transaction
        vsid:
          type: string
          description: Visa Store ID (VSID) associated with the transaction
      required:
      - vmid
      - vsid
      title: VisaMidDetails
    type_users_uploads_CreateUploadResponseDataUnion:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - historicalTransactionStart
            description: 'Discriminator value: historicalTransactionStart'
          id:
            type: string
            description: Upload id to reference in subsequent upload request
          attributes:
            $ref: '#/components/schemas/type_commons_EmptyObject'
        required:
        - type
        - id
        - attributes
      discriminator:
        propertyName: type
      title: CreateUploadResponseDataUnion
    type_transactions_Merchant:
      type: object
      properties:
        id:
          type: string
          description: Acquirer Merchant Identification Number (MID) — usually a 15 digit numerical identifier code. <b>Note, this field is REQUIRED for local offers. We HIGHLY RECOMMEND sending this field as it will be required in the near future.</b>
        name:
          type: string
          description: Merchant name associated with transaction
        addrStreet:
          type: string
          description: Merchant street address associated with transaction.
        addrCity:
          type: string
          description: Merchant address city associated with transaction.
        addrState:
          $ref: '#/components/schemas/type_transactions_States'
          description: Merchant address state associated with transaction.
        addrZipcode:
          type: string
          description: Merchant address zip code associated with transaction.
        addrCountry:
          type: string
          description: Merchant address country associated with transaction.
        latitude:
          type: string
          description: Merchant latitude geocoordinate associated with transaction.
        longitude:
          type: string
          description: Merchant longitude geocoordinate associated with transaction.
        storeId:
          type: string
          description: Merchant store ID where transaction originated from
      required:
      - name
      title: Merchant
    type_users_uploads_UpdateUploadResponseDataUnion:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - historicalTransactionComplete
            description: 'Discriminator value: historicalTransactionComplete'
          id:
            type: string
            description: Upload id to reference in subsequent upload request
          attributes:
            $ref: '#/components/schemas/type_commons_EmptyObject'
        required:
        - type
        - id
        - attributes
      discriminator:
        propertyName: type
      title: UpdateUploadResponseDataUnion
    type_transactions_DirectionType:
      type: string
      enum:
      - DEBIT
      - CREDIT
      title: DirectionType
    type_commons_ErrorSource:
      type: object
      properties:
        pointer:
          type: string
          description: A JSON pointer to the value in the request document that caused the error
        parameter:
          type: string
          description: A string indicating which URI query parameter caused the error
        header:
          type: string
          description: A string indicating the name of a single request header which caused the error
      title: ErrorSource
    type_users_uploads_UpdateUploadRequestObject:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/type_users_uploads_UpdateUploadRequestDataUnion'
      required:
      - data
      title: UpdateUploadRequestObject
    type_users_uploads_CreateUploadPartDataUnion:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - historicalTransaction
            description: 'Discriminator value: historicalTransaction'
          id:
            type: string
            description: Unique identifier for the transaction event. This <b>must</b> be unique for each distinct event sent to the API.
          attributes:
            $ref: '#/components/schemas/type_transactions_TransactionsAttributes'
        required:
        - type
        - id
        - attributes
      discriminator:
        propertyName: type
      title: CreateUploadPartDataUnion
    type_users_uploads_CreateUploadPartMultiStatusResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/type_commons_ErrorObject'
        data:
          type: array
          items:
            $ref: '#/components/schemas/type_users_uploads_CreateUploadPartResponseDataUnion'
      required:
      - errors
      title: CreateUploadPartMultiStatusResponse
    type_transactions_States:
      type: string
      enum:
      - AL
      - AK
      - AS
      - AZ
      - AR
      - CA
      - CO
      - CT
      - DE
      - DC
      - FM
      - FL
      - GA
      - GU
      - HI
      - ID
      - IL
      - IN
      - IA
      - KS
      - KY
      - LA
      - ME
      - MH
      - MD
      - MA
      - MI
      - MN
      - MS
      - MO
      - MT
      - NE
      - NV
      - NH
      - NJ
      - NM
      - NY
      - NC
      - ND
      - MP
      - OH
      - OK
      - OR
      - PW
      - PA
      - PR
      - RI
      - SC
      - SD
      - TN
      - TX
      - UT
      - VT
      - VI
      - VA
      - WA
      - WV
      - WI
      - WY
      title: States
    type_users_uploads_CreateUploadPartResponseObject:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/type_users_uploads_CreateUploadPartResponseDataUnion'
      required:
      - data
      title: CreateUploadPartResponseObject
    type_commons_ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/type_commons_ErrorObject'
      required:
      - errors
      title: ErrorResponse
    type_transactions_TransactionPaymentType:
      type: string
      enum:
      - CARD
      title: TransactionPaymentType
    type_commons_OrganizationId:
      type: string
      description: Your issuer organization ID, provided by Kard
      title: OrganizationId
    type_users_uploads_UpdateUploadResponseObject:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/type_users_uploads_UpdateUploadResponseDataUnion'
      required:
      - data
      title: UpdateUploadResponseObject
    type_users_uploads_CreateUploadResponseObject:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/type_users_uploads_CreateUploadResponseDataUnion'
      required:
      - data
      title: CreateUploadResponseObject
    type_commons_CardNetwork:
      type: string
      enum:
      - VISA
      - MASTERCARD
      - AMERICANEXPRESS
      - DISCOVER
      description: Supported card networks
      title: CardNetwork
    type_transactions_ProcessorMid:
      oneOf:
      - type: object
        properties:
          processor:
            type: string
            enum:
            - VISA
            description: 'Discriminator value: VISA'
          mids:
            $ref: '#/components/schemas/type_transactions_VisaMidDetails'
            description: Merchant ID (MID) associated with the processor
        required:
        - processor
        - mids
      discriminator:
        propertyName: processor
      title: ProcessorMid
  securitySchemes:
    OAuthScheme:
      type: http
      scheme: bearer