> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.getkard.com/legacy/api/transactions/create-incoming-transaction/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getkard.com/_mcp/server. # Create Incoming Transaction POST https://rewards-api.getkard.com/transactions/incoming Content-Type: application/json Call this endpoint to send all incoming transactions made by all enrolled users in your rewards program. 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. Required scopes: `transaction:write` Reference: https://docs.getkard.com/legacy/api/transactions/create-incoming-transaction ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Servers - `https://rewards-api.getkard.com` (Production, default) - `https://test-rewards-api.getkard.com` (Sandbox) ## Request ### Body (application/json) This endpoint expects a list of IncomingTransactionRequest. - `list of IncomingTransactionRequest` ## Response ### 201 - `string` ## Errors ### 401 Unauthorized Error - `message` (string, required) ### 500 Internal Server Error - `string` ### 400 Invalid Request - `InvalidRequestUnion` ## Types ### IncomingTransactionRequest - `transactionId` (string, required) — Transaction ID in issuer's system - `referringPartnerUserId` (string, required) — Referring partner user ID from issuer associated with transaction - `amount` (integer, required) — Transaction amount in cents - `status` (enum, required) — Transaction status - Allowed values: `APPROVED`, `SETTLED`, `REVERSED`, `RETURNED`, `DECLINED` - `currency` (string, required) — Currency of transaction - `description` (string, required) — Description of transaction - usually includes merchant and other key details on transaction - `description2` (string, optional) — Description2 of transaction — usually includes other merchant identifying information - `mcc` (string, optional) — Merchant Category Code (usually a 4-digit numerical number). Note, this field is REQUIRED for SOME national offers. We HIGHLY RECOMMEND sending this field as it will be required in the near future. - `coreProviderId` (string, optional) — Name of processor associated with transaction - `transactionDate` (datetime, optional) — Timestamp for REVERSED, RETURNED, DECLINED transaction events; REQUIRED for transactions with REVERSED, RETURNED, DECLINED status. Date string should be in ISO 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` (datetime, optional) — Timestamp for APPROVED transaction event; REQUIRED for transactions with APPROVED status, and HIGHLY RECOMMENDED to include for transactions with a SETTLED status. Date string should be in ISO 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` (datetime, optional) — Timestamp for SETTLED transaction event, REQUIRED for transactions with SETTLED status. Date string should be in ISO 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` - `merchantId` (string, optional) — Acquirer Merchant Identification Number (MID) — usually a 15 digit numerical identifier code. Note, this field is REQUIRED for local offers. We HIGHLY RECOMMEND sending this field as it will be required in the near future. - `merchantStoreId` (string, optional) — Merchant store ID where transaction originated from - `cardPresence` (string, optional) — Whether card was present at time of transaction - `merchantName` (string, optional) — Merchant name associated with transaction - `merchantAddrCity` (string, optional) — Merchant address city associated with transaction. We HIGHLY RECOMMEND sending this field as it may be required in the near future. - `merchantAddrState` (enum, optional) — Merchant address state associated with transaction. We HIGHLY RECOMMEND sending this field as it may be required in the near future. - Allowed values: `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` - `merchantAddrZipcode` (string, optional) — Merchant address zip code associated with transaction. We HIGHLY RECOMMEND sending this field as it may be required in the near future. - `merchantAddrCountry` (string, optional) — Merchant address country associated with transaction. We HIGHLY RECOMMEND sending this field as it may be required in the near future. - `merchantAddrStreet` (string, optional) — Merchant street address associated with transaction. We HIGHLY RECOMMEND sending this field as it may be required in the near future. - `merchantLat` (string, optional) — Merchant latitude geocoordinate associated with transaction. We HIGHLY RECOMMEND sending this field as it may be required in the near future. - `merchantLong` (string, optional) — Merchant longitude geocoordinate associated with transaction. We HIGHLY RECOMMEND sending this field as it may be required in the near future. - `panEntryMode` (string, optional) — PAN entry mode (usually a 2 digit numeric code) - `cardBIN` (string, optional) — Bank identification number (BIN). Must be a valid BIN of 6 digits. If over 6 digits, please send first 6. Note, this field is REQUIRED for matching purposes. - `cardLastFour` (string, optional) — Card last four digits. Note, this field is REQUIRED for matching purposes. - `authorizationCode` (string, optional) — Transaction approval code - `retrievalReferenceNumber` (string, optional) — Retrieval Reference Number - `systemTraceAuditNumber` (string, optional) — System Trace Audit Number - `acquirerReferenceNumber` (string, optional) — Acquirer Reference Number - `isDeposit` (boolean, optional) — Transaction is a deposit - `googleId` (string, optional, deprecated) — Google Id ### RequestValidationErrorResponse - `errors` (list of string, required) ## Examples **Request** ```json [ { "transactionId": "asdlkfjalksdf0t-dsfdfsdfsdkajsldkf", "referringPartnerUserId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69", "amount": 1000, "status": "APPROVED", "currency": "USD", "description": "ADVANCEAUTO", "description2": "ADVANCEAUTO", "mcc": "1234", "authorizationDate": "2021-07-02T17:47:06Z", "merchantId": "123456789101213", "merchantName": "ADVANCEAUTO", "merchantAddrCity": "Philadephia", "merchantAddrState": "PA", "merchantAddrZipcode": "19147", "merchantAddrCountry": "United States", "merchantAddrStreet": "125 Main St", "merchantLat": "37.9419429", "merchantLong": "-73.1446869", "cardBIN": "123456", "cardLastFour": "4321", "authorizationCode": "123456", "retrievalReferenceNumber": "100804333919", "systemTraceAuditNumber": "333828", "acquirerReferenceNumber": "1234567890123456789012345678", "isDeposit": false } ] ``` **Response** ```json "Incoming Transaction event successfully queued for processing" ``` **SDK Code** ```python import requests url = "https://rewards-api.getkard.com/transactions/incoming" payload = [ { "transactionId": "asdlkfjalksdf0t-dsfdfsdfsdkajsldkf", "referringPartnerUserId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69", "amount": 1000, "status": "APPROVED", "currency": "USD", "description": "ADVANCEAUTO", "description2": "ADVANCEAUTO", "mcc": "1234", "authorizationDate": "2021-07-02T17:47:06Z", "merchantId": "123456789101213", "merchantName": "ADVANCEAUTO", "merchantAddrCity": "Philadephia", "merchantAddrState": "PA", "merchantAddrZipcode": "19147", "merchantAddrCountry": "United States", "merchantAddrStreet": "125 Main St", "merchantLat": "37.9419429", "merchantLong": "-73.1446869", "cardBIN": "123456", "cardLastFour": "4321", "authorizationCode": "123456", "retrievalReferenceNumber": "100804333919", "systemTraceAuditNumber": "333828", "acquirerReferenceNumber": "1234567890123456789012345678", "isDeposit": False } ] headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://rewards-api.getkard.com/transactions/incoming'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '[{"transactionId":"asdlkfjalksdf0t-dsfdfsdfsdkajsldkf","referringPartnerUserId":"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69","amount":1000,"status":"APPROVED","currency":"USD","description":"ADVANCEAUTO","description2":"ADVANCEAUTO","mcc":"1234","authorizationDate":"2021-07-02T17:47:06Z","merchantId":"123456789101213","merchantName":"ADVANCEAUTO","merchantAddrCity":"Philadephia","merchantAddrState":"PA","merchantAddrZipcode":"19147","merchantAddrCountry":"United States","merchantAddrStreet":"125 Main St","merchantLat":"37.9419429","merchantLong":"-73.1446869","cardBIN":"123456","cardLastFour":"4321","authorizationCode":"123456","retrievalReferenceNumber":"100804333919","systemTraceAuditNumber":"333828","acquirerReferenceNumber":"1234567890123456789012345678","isDeposit":false}]' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://rewards-api.getkard.com/transactions/incoming" payload := strings.NewReader("[\n {\n \"transactionId\": \"asdlkfjalksdf0t-dsfdfsdfsdkajsldkf\",\n \"referringPartnerUserId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 1000,\n \"status\": \"APPROVED\",\n \"currency\": \"USD\",\n \"description\": \"ADVANCEAUTO\",\n \"description2\": \"ADVANCEAUTO\",\n \"mcc\": \"1234\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"merchantId\": \"123456789101213\",\n \"merchantName\": \"ADVANCEAUTO\",\n \"merchantAddrCity\": \"Philadephia\",\n \"merchantAddrState\": \"PA\",\n \"merchantAddrZipcode\": \"19147\",\n \"merchantAddrCountry\": \"United States\",\n \"merchantAddrStreet\": \"125 Main St\",\n \"merchantLat\": \"37.9419429\",\n \"merchantLong\": \"-73.1446869\",\n \"cardBIN\": \"123456\",\n \"cardLastFour\": \"4321\",\n \"authorizationCode\": \"123456\",\n \"retrievalReferenceNumber\": \"100804333919\",\n \"systemTraceAuditNumber\": \"333828\",\n \"acquirerReferenceNumber\": \"1234567890123456789012345678\",\n \"isDeposit\": false\n }\n]") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://rewards-api.getkard.com/transactions/incoming") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "[\n {\n \"transactionId\": \"asdlkfjalksdf0t-dsfdfsdfsdkajsldkf\",\n \"referringPartnerUserId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 1000,\n \"status\": \"APPROVED\",\n \"currency\": \"USD\",\n \"description\": \"ADVANCEAUTO\",\n \"description2\": \"ADVANCEAUTO\",\n \"mcc\": \"1234\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"merchantId\": \"123456789101213\",\n \"merchantName\": \"ADVANCEAUTO\",\n \"merchantAddrCity\": \"Philadephia\",\n \"merchantAddrState\": \"PA\",\n \"merchantAddrZipcode\": \"19147\",\n \"merchantAddrCountry\": \"United States\",\n \"merchantAddrStreet\": \"125 Main St\",\n \"merchantLat\": \"37.9419429\",\n \"merchantLong\": \"-73.1446869\",\n \"cardBIN\": \"123456\",\n \"cardLastFour\": \"4321\",\n \"authorizationCode\": \"123456\",\n \"retrievalReferenceNumber\": \"100804333919\",\n \"systemTraceAuditNumber\": \"333828\",\n \"acquirerReferenceNumber\": \"1234567890123456789012345678\",\n \"isDeposit\": false\n }\n]" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://rewards-api.getkard.com/transactions/incoming") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("[\n {\n \"transactionId\": \"asdlkfjalksdf0t-dsfdfsdfsdkajsldkf\",\n \"referringPartnerUserId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 1000,\n \"status\": \"APPROVED\",\n \"currency\": \"USD\",\n \"description\": \"ADVANCEAUTO\",\n \"description2\": \"ADVANCEAUTO\",\n \"mcc\": \"1234\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"merchantId\": \"123456789101213\",\n \"merchantName\": \"ADVANCEAUTO\",\n \"merchantAddrCity\": \"Philadephia\",\n \"merchantAddrState\": \"PA\",\n \"merchantAddrZipcode\": \"19147\",\n \"merchantAddrCountry\": \"United States\",\n \"merchantAddrStreet\": \"125 Main St\",\n \"merchantLat\": \"37.9419429\",\n \"merchantLong\": \"-73.1446869\",\n \"cardBIN\": \"123456\",\n \"cardLastFour\": \"4321\",\n \"authorizationCode\": \"123456\",\n \"retrievalReferenceNumber\": \"100804333919\",\n \"systemTraceAuditNumber\": \"333828\",\n \"acquirerReferenceNumber\": \"1234567890123456789012345678\",\n \"isDeposit\": false\n }\n]") .asString(); ``` ```php request('POST', 'https://rewards-api.getkard.com/transactions/incoming', [ 'body' => '[ { "transactionId": "asdlkfjalksdf0t-dsfdfsdfsdkajsldkf", "referringPartnerUserId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69", "amount": 1000, "status": "APPROVED", "currency": "USD", "description": "ADVANCEAUTO", "description2": "ADVANCEAUTO", "mcc": "1234", "authorizationDate": "2021-07-02T17:47:06Z", "merchantId": "123456789101213", "merchantName": "ADVANCEAUTO", "merchantAddrCity": "Philadephia", "merchantAddrState": "PA", "merchantAddrZipcode": "19147", "merchantAddrCountry": "United States", "merchantAddrStreet": "125 Main St", "merchantLat": "37.9419429", "merchantLong": "-73.1446869", "cardBIN": "123456", "cardLastFour": "4321", "authorizationCode": "123456", "retrievalReferenceNumber": "100804333919", "systemTraceAuditNumber": "333828", "acquirerReferenceNumber": "1234567890123456789012345678", "isDeposit": false } ]', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://rewards-api.getkard.com/transactions/incoming"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "[\n {\n \"transactionId\": \"asdlkfjalksdf0t-dsfdfsdfsdkajsldkf\",\n \"referringPartnerUserId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 1000,\n \"status\": \"APPROVED\",\n \"currency\": \"USD\",\n \"description\": \"ADVANCEAUTO\",\n \"description2\": \"ADVANCEAUTO\",\n \"mcc\": \"1234\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"merchantId\": \"123456789101213\",\n \"merchantName\": \"ADVANCEAUTO\",\n \"merchantAddrCity\": \"Philadephia\",\n \"merchantAddrState\": \"PA\",\n \"merchantAddrZipcode\": \"19147\",\n \"merchantAddrCountry\": \"United States\",\n \"merchantAddrStreet\": \"125 Main St\",\n \"merchantLat\": \"37.9419429\",\n \"merchantLong\": \"-73.1446869\",\n \"cardBIN\": \"123456\",\n \"cardLastFour\": \"4321\",\n \"authorizationCode\": \"123456\",\n \"retrievalReferenceNumber\": \"100804333919\",\n \"systemTraceAuditNumber\": \"333828\",\n \"acquirerReferenceNumber\": \"1234567890123456789012345678\",\n \"isDeposit\": false\n }\n]", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ [ "transactionId": "asdlkfjalksdf0t-dsfdfsdfsdkajsldkf", "referringPartnerUserId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69", "amount": 1000, "status": "APPROVED", "currency": "USD", "description": "ADVANCEAUTO", "description2": "ADVANCEAUTO", "mcc": "1234", "authorizationDate": "2021-07-02T17:47:06Z", "merchantId": "123456789101213", "merchantName": "ADVANCEAUTO", "merchantAddrCity": "Philadephia", "merchantAddrState": "PA", "merchantAddrZipcode": "19147", "merchantAddrCountry": "United States", "merchantAddrStreet": "125 Main St", "merchantLat": "37.9419429", "merchantLong": "-73.1446869", "cardBIN": "123456", "cardLastFour": "4321", "authorizationCode": "123456", "retrievalReferenceNumber": "100804333919", "systemTraceAuditNumber": "333828", "acquirerReferenceNumber": "1234567890123456789012345678", "isDeposit": false ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/transactions/incoming")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```