---
title: "Create Incoming Transactions"
method: POST
path: "/v2/issuers/{organizationId}/transactions"
tags: ["transactions"]
---

# Create Incoming Transactions

`POST /v2/issuers/{organizationId}/transactions`

## Request

- Base URL: `https://rewards-api.getkard.com`
- URL: `https://rewards-api.getkard.com/v2/issuers/{organizationId}/transactions`
- Auth: HTTP bearer

Call this endpoint to send all transactions made by all your enrolled users in your rewards program. The request body will depend on the transaction type.<br/>
Please use the correct type when calling the endpoint:
- `transaction`: These incoming transactions will be processed and matched by the Kard system. Learn more about the [Transaction CLO Matching](https://github.com/kard-financial/kard-postman#c-transaction-clo-matching) flow here.
- `coreTransaction`: For transactions from core banking systems with limited card-level data.<br/>

<b>Required scopes:</b> `transaction:write`<br/>
<b>Note:</b> `Maximum of 500 transactions can be created per request`.

## Path parameters

- `organizationId` string, required: Your issuer organization ID, provided by Kard

## Request body

- TransactionsTransactionsRequestBody
  - `data` TransactionsTransactions[], required: Discriminated union representing the request body for submitting a transaction. Use `type` to distinguish between the two: - `transaction`: For transactions requiring processing and matching by the Kard system. - `coreTransaction`: For transactions from core banking systems with limited card-level data.
    - union
      - object
        - `type` 'transaction', required: Discriminator value: transaction
        - `id` string, required: Unique identifier for the transaction event. This <b>must</b> be unique for each distinct event sent to the API.
        - `attributes` TransactionsTransactionsAttributes, required
          - `userId` string, required: The ID of the user as defined on the issuers system
          - `amount` integer, required: Transaction amount in cents
          - `subtotal` integer: The base amount in cents excluding additional charges (such as tips, taxes, and other fees).
          - `status` 'APPROVED' | 'SETTLED' | 'REVERSED' | 'RETURNED' | 'DECLINED', required
          - `currency` string, required: Currency of transaction
          - `description` string, required: Description of transaction - usually includes merchant and other key details on transaction
          - `description2` string: Description2 of transaction — usually includes other merchant identifying information
          - `mcc` string: 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` string: Name of processor associated with transaction
          - `transactionDate` string, date-time: 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` string, date-time: 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` string, date-time: 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` TransactionsMerchant
            - `id` string: 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` string, required: Merchant name associated with transaction
            - `addrStreet` string: Merchant street address associated with transaction.
            - `addrCity` string: Merchant address city associated with transaction.
            - `addrState` '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'
            - `addrZipcode` string: Merchant address zip code associated with transaction.
            - `addrCountry` string: Merchant address country associated with transaction.
            - `latitude` string: Merchant latitude geocoordinate associated with transaction.
            - `longitude` string: Merchant longitude geocoordinate associated with transaction.
            - `storeId` string: Merchant store ID where transaction originated from
          - `cardPresence` string: Whether card was present at time of transaction
          - `panEntryMode` string: PAN entry mode
          - `cardBIN` string, required: Bank identification number (BIN). Must be a valid BIN of 6 digits. If over 6 digits, please send first 6.
          - `cardLastFour` string, required: Card last four digits.
          - `authorizationCode` string: Transaction approval code
          - `retrievalReferenceNumber` string: Retrieval Reference Number
          - `systemTraceAuditNumber` string: System Trace Audit Number
          - `acquirerReferenceNumber` string: Acquirer Reference Number
          - `direction` 'DEBIT' | 'CREDIT', required
          - `paymentType` 'CARD', required
          - `cardNetwork` 'VISA' | 'MASTERCARD' | 'AMERICANEXPRESS' | 'DISCOVER': Supported card networks
          - `transactionId` string, required: The transaction ID
          - `cardProductId` string: The card product ID associated with the transaction
          - `userZipCode` string: The zip code of the user who made the transaction
          - `processorMids` TransactionsProcessorMid
            - `processor` 'VISA', required: Discriminator value: VISA
            - `mids` TransactionsVisaMidDetails, required
              - …
          - `accountId` string: An account identifier associated to transaction
      - object
        - `type` 'coreTransaction', required: Discriminator value: coreTransaction
        - `id` string, required: Unique identifier for the transaction event. This <b>must</b> be unique for each distinct event sent to the API.
        - `attributes` TransactionsCoreTransactionAttributes, required
          - `userId` string, required: The ID of the user as defined on the issuers system
          - `transactionId` string, required: The transaction ID from the core banking system
          - `amount` integer, required: Transaction amount in cents
          - `currency` string, required: Currency of transaction in ISO 4217 alpha-3 format
          - `description` string, required: Description of transaction - usually includes merchant and other key details on transaction
          - `direction` 'DEBIT' | 'CREDIT', required
          - `status` 'SETTLED', required: Transaction status (always SETTLED for core transactions)
          - `settledDate` string, date-time, required: Timestamp when transaction was settled. 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` string, date-time, required: Timestamp for transaction authorization. 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
          - `financialInstitutionName` string: Deprecated. Use `financialInstitutionId` instead. Name of the financial institution.
          - `financialInstitutionId` string: Unique identifier of the financial institution
          - `cardLastFours` string[]: Last four digits of the card(s) that may have been used for the transaction. When the issuer cannot determine which specific card was used, multiple values are provided as candidates.

## Response `202`

Response with status 202

- TransactionsTransactionsResponse
  - `data` TransactionsTransactionsResponseData, required
    - `type` string, required: Type of document returned
    - `id` string, required: The request id of the pending job
    - `attributes` CommonsJob, required
      - `status` 'queued', required: Status of the job
      - `message` string, required: Message regarding the status of the job request

## Other responses

- `207`: Error response with status 207
- `400`: Error response with status 400
- `401`: Error response with status 401
- `409`: Error response with status 409
- `429`: The issuer's traffic grew faster than its allowed rate, or the endpoint's own limit was reached. If the response includes a `Retry-After` header, wait that many seconds before retrying. See [Rate Limits](/2024-10-01/api/integration-guides/rate-limits).
- `500`: Error response with status 500

## Changes

- **2026-10-22** `4e87fc8b018b`: 1 info
  - added the non-success response with the status `429`

[Operation history](https://skmtc.dev/getkard/apis/getkard-2/changes/v2/issuers/:organizationId/transactions/post.md)

---

[API](https://skmtc.dev/getkard/apis/getkard-2.md) - [All operations](https://skmtc.dev/getkard/apis/getkard-2/llms.txt) - [OpenAPI document](https://skmtc.dev/getkard/apis/getkard-2/revisions/bd47764afa21?raw)