Skip to content

ARCH-2577 Public GET v4 Card Transactions API #1650

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 6 commits into
base: main
Choose a base branch
from
Draft

ARCH-2577 Public GET v4 Card Transactions API #1650

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a69cb97
Add read API
rrillig Nov 17, 2025
7f465e7
Document get transactions for user endpoint
rrillig Nov 17, 2025
7d86244
Update process flow diagram
rrillig Nov 17, 2025
d3f0bad
Revise resource descriptions
rrillig Nov 17, 2025
8f8ed22
Clarify access token requirements for transactions
rrillig Nov 17, 2025
efafc38
Add GET transaction schema
rrillig Nov 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 89 additions & 5 deletions src/api-reference/cards/v4.cards-endpoints.schemas.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ Name|Type|Format|Description

Name|Type|Format|Description
---|---|---|---
`account`|`object`|[`Transaction Account Reference`](#schema-transaction-accountreference)|**Required** Reference to the card account this transaction belongs to.
`account`|`object`|[`Transaction Account Reference`](#schema-create-transaction-accountreference)|**Required** Reference to the card account this transaction belongs to.
`acquirerReferenceNumber`|`string`|-|Acquirer reference number.
`authorizationExternalId`|`string`|-|External ID of the referenced (pre-)authorization.
`billedAmount`|`object`|[`Amount`](#schema-amount)|Billed amount.
Expand Down Expand Up @@ -103,12 +103,85 @@ Name|Type|Format|Description
`travel`|`object`|[`Travel`](#schema-travel)|Travel addendum data.
`type`|`enum`|-|**Required** Type of the transaction. Supported values: `ANF - Annual Fees`, `CAV - Cash Advance`, `CCF - Cash and Check Fees`, `RPE - Regular Transaction`, `FNC - Finance Charges`, `NSF - Insufficient Funds Check Fees`, `LAF - Late Fees`, `CHG - Other Bank Charges and Fees`, `PAY - Payment`

## <a name="schema-transaction-accountreference"></a>Transaction Account Reference
## <a name="schema-transaction-list-response"></a>Transaction List Response

Name|Type|Format|Description
---|---|---|---
`transactions`|`array`|[`Transaction`](#schema-transaction)|**Required** Array of transactions. (Maximum number of items: 100)
`paging`|`object`|[`Paging`](#schema-paging)|**Required** Paging details

## <a name="schema-transaction"></a>Transaction

Name|Type|Format|Description
---|---|---|---
`account`|`object`|[`Transaction Account Reference`](#schema-transaction-accountreference)|**Required** Reference to the card account this transaction belongs to.
`accountCodes`|`array`|[`Transaction Account Code`](#schema-transaction-accountcode)|Account codes of the transaction (accountCode1 - accountCode10).
`acquirerReferenceNumber`|`string`|-|Acquirer reference number.
`administrativeData`|`object`|[`Transaction Administrative Data`](#schema-transaction-administrativedata)|Administrative (internal) data
`authorizationReferenceNumber`|`string`|-|Authorization Reference Number
`billedAmount`|`object`|[`Amount`](#schema-amount)|Billed amount.
`billingAccount`|`object`|[`Transaction Account Reference`](#schema-transaction-accountreference)|Account to which the transaction is billed to, relevant for example in case of Lodge scenarios.
`carRental`|`object`|[`Car Rental`](#schema-carrental)|Car rental addendum data.
`companyId`|`string`|-|**Required** SAP Concur company ID.
`customerVatNumber`|`string`|-|Customer VAT number.
`description`|`string`|-|Description of the transaction.
`description2`|`string`|-|Description2 of the transaction.
`description3`|`string`|-|Description3 of the transaction.
`description4`|`string`|-|Description4 of the transaction.
`description5`|`string`|-|Description5 of the transaction.
`fleet`|`object`|[`Fleet`](#schema-fleet)|Fleet addendum data.
`id`|`string`|-|**Required** Concur internal transaction ID. Unique identifier for the card transaction as defined by SAP Concur.
`lodging`|`object`|[`Lodging`](#schema-lodging)|Lodging addendum data.
`merchant`|`object`|[`Merchant`](#schema-merchant)|**Required** Merchant details.
`merchantReferenceNumber`|`string`|-|Merchant reference number.
`postedAmount`|`object`|[`Amount`](#schema-amount)|**Required** Posted amount.
`postedDate`|`date`|ISO 8601 `YYYY-MM-DD`|**Required** Posted date.
`processorReferenceNumber`|`string`|-|Processor reference number.
`purchase`|`object`|[`Purchase`](#schema-purchase)|Purchase addendum data.
`referenceNumber`|`string`|-|Transaction reference number for display purposes.
`statement`|`object`|[`Statement`](#schema-statement)|Statement this transactions belongs to.
`taxes`|`array`|[`Transaction Tax`](#schema-transaction-tax)|Taxes incurred for the transaction.
`totalTaxAmount`|`object`|[`Amount`](#schema-amount)|Total tax amount.
`transactionAmount`|`object`|[`Amount`](#schema-amount)|**Required** Transaction amount.
`transactionDate`|`date`|ISO 8601 `YYYY-MM-DD`|**Required** Transaction date.
`transactionDateTime`|`timestamp`|RFC 3339 `YYYY-MM-DDThh:mm:ss.nnn`|Timestamp when the transaction happened.
`travel`|`object`|[`Travel`](#schema-travel)|Travel addendum data.
`type`|`enum`|-|**Required** Type of the transaction. Supported values: `ANF - Annual Fees`, `CAV - Cash Advance`, `CCF - Cash and Check Fees`, `RPE - Regular Transaction`, `FNC - Finance Charges`, `NSF - Insufficient Funds Check Fees`, `LAF - Late Fees`, `CHG - Other Bank Charges and Fees`, `PAY - Payment`

## <a name="schema-create-transaction-accountreference"></a>Create Transaction Account Reference

Name|Type|Format|Description
---|---|---|---
`externalId`|`string`|-|**Required** Unique identifier (token) of the referenced billing account as defined by an external system (outside the SAP Concur platform). Must not contain primary account number (PAN).

## <a name="schema-transaction-accountreference"></a>Transaction Account Reference

Name|Type|Format|Description
---|---|---|---
`cardProductType`|`string`|-|**Required** Card product type. Supported values: `CORP - Corporate Card`, `BUSN - Business Card`
`id`|`string`|-|**Required** Concur internal account ID. Unique identifier (token) for the card account as defined by SAP Concur. Does not contain primary account number (PAN).
`lastSegment`|`string`|-|Last four digits of the card account.
`paymentType`|`object`|[`Payment Type Reference`](#schema-paymenttypereference)|Payment Type of the card account.

## <a name="schema-paymenttypereference"></a>Payment Type Reference

Name|Type|Format|Description
---|---|---|---
`id`|`string`|-|**Required** Concur internal payment type ID.

## <a name="schema-transaction-administrativedata"></a>Transaction Administrative Data

Name|Type|Format|Description
---|---|---|---
`addendumType`|`string`|-|In case the transaction has addendum data, specifies which kind of addendum data are available. Supported values: `TRVL - Travel`, `LODG - Lodging`, `FLET - Fleet`, `CAR - Car Rental`, `PRCH - Purchase`
`hasRichData`|`boolean`|-|**Required** Indicates whether the transaction enough (addendum) data for being classified as "rich".
`integrationPartner`|`string`|-|**Required** Integration partner through which this transaction was imported. Supported values: `BATCH - File-based integration`, `AMEX_OPEN - American Express Business Card integration`, `API - API-based integration`
`isDeletable`|`boolean`|-|**Required** Indicates whether the transaction can be deleted/hidden by the end user.
`lastModified`|`timestamp`|RFC 3339 `YYYY-MM-DDThh:mm:ss.nnnZ`|**Required** Last Modified timestamp
`processType`|`string`|-|**Required** Process type. Supported values: `CBS - Company Bill Statements`, `CR - Central Reconciliation`, `REG - Regular Expense Processing`
`receiptImageId`|`string`|-|ID of the receipt image
`status`|`string`|-|Transaction Status. Supported values: `UN - Unassigned`, `AS - Assigned to Report`

## <a name="schema-carrental"></a>Car Rental

Name|Type|Format|Description
Expand Down Expand Up @@ -151,12 +224,12 @@ Name|Type|Format|Description
---|---|---|---
`discountAmount`|`object`|[`Amount`](#schema-amount)|Discount Amount.
`driverId`|`string`|-|Driver ID.
`fuelType`|`enum`|-|**Required** Fuel type. Supported values: `ALCOHOL - Alcohol-based Fuel`, `AUTOGAS - Autogas (LPG)`, `AVIATION - Aviation/Jet Fuel`, `BIOBLEND - Biodiesel-blended Fuel`, `BIOFUEL - Biodiesel Fuel`, `CLNDIESEL - Clean Diesel`, `DIESEL - Diesel Fuel`, `GASOLINE - Gasoline`, `MARINE - Marine Fuel`, `NATURAL - Natural Gas`, `OTHER - Other Fuel`, `UNDEF - Undefined Fuel Type`
`fuelType`|`enum`|-|Fuel type. Only **Required** for *create* scenario. Supported values (validated for *create* case only): `ALCOHOL - Alcohol-based Fuel`, `AUTOGAS - Autogas (LPG)`, `AVIATION - Aviation/Jet Fuel`, `BIOBLEND - Biodiesel-blended Fuel`, `BIOFUEL - Biodiesel Fuel`, `CLNDIESEL - Clean Diesel`, `DIESEL - Diesel Fuel`, `GASOLINE - Gasoline`, `MARINE - Marine Fuel`, `NATURAL - Natural Gas`, `OTHER - Other Fuel`, `UNDEF - Undefined Fuel Type`
`items`|`array`|[`Fleet Detail`](#schema-fleet-detail)|Fleet items.
`odometer`|`string`|-|Odometer reading.
`productType`|`enum`|-|**Required** Product type. Supported values: `CARACC - Automotive Accessories`, `GLASS - Automotive Glass`, `AVIACC - Aviation Accessories`, `AVIFOOD - Aviation Food/Beverage`, `AVIMAINT - Aviation Maintenance`, `BATTERIES - Batteries`, `BEVERAGE - Beverage`, `BRAKE - Brakes and Brake Services`, `WASH - Car Wash`, `SMOKE - Cigarettes/Tobacco`, `FEE - Fees`, `FOOD - Food`, `AVIATION - General Aviation`, `HEALTH - Health/Beauty`, `LABOR - Labor`, `MISC - Miscellaneous Product`, `OIL - Motor Oil`, `PARTS - Parts`, `REPAIR - Repair`, `SERVICE - Services`, `TIRES - Tires`, `TBA - Tires Batteries Accessories`, `TOW - Towing`, `UNDEF - Undefined Product Type`
`productType`|`enum`|-|Product type. . Only **Required** for *create* scenario. Supported values (validated for *create* case only): `CARACC - Automotive Accessories`, `GLASS - Automotive Glass`, `AVIACC - Aviation Accessories`, `AVIFOOD - Aviation Food/Beverage`, `AVIMAINT - Aviation Maintenance`, `BATTERIES - Batteries`, `BEVERAGE - Beverage`, `BRAKE - Brakes and Brake Services`, `WASH - Car Wash`, `SMOKE - Cigarettes/Tobacco`, `FEE - Fees`, `FOOD - Food`, `AVIATION - General Aviation`, `HEALTH - Health/Beauty`, `LABOR - Labor`, `MISC - Miscellaneous Product`, `OIL - Motor Oil`, `PARTS - Parts`, `REPAIR - Repair`, `SERVICE - Services`, `TIRES - Tires`, `TBA - Tires Batteries Accessories`, `TOW - Towing`, `UNDEF - Undefined Product Type`
`quantity`|`object`|[`Fleet Quantity`](#schema-fleet-quantity)|Quantity.
`serviceType`|`enum`|-|**Required** Service type. Supported values: `FULL - Full-service`, `NFUEL - Only non-fuel products purchased`, `SELF - Self-service`, `UNDEF - Undefined Service Type`
`serviceType`|`enum`|-|Service type. . Only **Required** for *create* scenario. Supported values (validated for *create* case only): `FULL - Full-service`, `NFUEL - Only non-fuel products purchased`, `SELF - Self-service`, `UNDEF - Undefined Service Type`
`totalAmount`|`object`|[`Amount`](#schema-amount)|Total amount.
`unitAmount`|`object`|[`Amount`](#schema-amount)|Price per unit of measure.
`vehicleNumber`|`string`|-|Vehicle Number.
Expand Down Expand Up @@ -248,6 +321,7 @@ Name|Type|Format|Description
`doingBusinessAs`|`string`|-|Name of the business the merchant is doing (preferred for display purposes over merchant name).
`id`|`string`|-|Merchant identifier.
`name`|`string`|-|**Required** Merchant name.
`standardCategoryCode`|`string`|-|Standardized Merchant Category Code. Relevant for *read* scenario only.
`vatNumber`|`string`|-|Merchant's VAT number.

## <a name="schema-purchase"></a>Purchase
Expand Down Expand Up @@ -371,6 +445,16 @@ Name|Type|Format|Description
`serviceClass`|`string`|-|Class of Service Code. Preferred values: `A = First Discount`, `B = Coach Discount`, `C = Business Class`, `D = Bus Discounted`, `E = Shuttle`, `F = First Class`, `H = Coach Discount`, `J = Bus Premium`, `K = Thrift`, `L = Thrift Discount`, `M = Coach Discount`, `P = First Premium`, `Q = Coach Discount`, `R = Supersonic`, `S = Standard Class`, `T = Coach Discount`, `U = Shuttle`, `V = Thrift Discount`, `W = Coach Premium`, `Y = Coach`
`travelLegNumber`|`integer`|-|Order in which the leg is to be traveled.

## <a name="schema-paging"></a>Paging

Name|Type|Format|Description
---|---|---|---
`nextPageToken`|`string`|-|Page token as returned in a previous request.
`page`|`integer`|-|Current page (starting with 1).
`pageSize`|`integer`|-|Page size.
`totalElements`|`integer`|-|Number of total elements across all pages.
`totalPages`|`integer`|-|Total number of pages.

# <a name="schemas-bulkrequest"></a>Bulk Request Schemas

## <a name="schema-bulkrequest"></a>Bulk Request
Expand Down
148 changes: 148 additions & 0 deletions src/api-reference/cards/v4.cards-endpoints.transaction.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -226,3 +226,151 @@ Content-Type: application/json
}
]
```

## <a name="get-transactions-for-user"></a>Retrieve Card Transactions by User

Endpoint to retrieve credit card transactions of a user. This includes corporate and business cards only. Personal card data is not exposed.

By default only basic transaction data is returned. It is recommended to only request required options for optimal performance. It is possible to request multiple options in one call.

This endpoint supports user level access tokens only.

### Scopes

`cards.transaction.read` - Refer to [Scope Usage](./v4.cards-get-started.html#scope-usage) for full details.

### URI

```shell
GET https://{datacenterURI}/cards/v4/users/{userId}/transactions
```

### Parameters

Name|Type|Format|Description
---|---|---|---
`userId`|`string`|-|**Required** The unique identifier of the SAP Concur user.
`status`|`array `|`string`|Filter transactions by status. Allowed values: `UN - Unassigned from Report`, `AS - Assigned to Report`
`transactionDateFrom`|`date`|ISO 8601 YYYY-MM-DD|Filter transactions from this transaction date (inclusive). Defaults to 24 months ago; cannot be earlier than 24 months in the past.
`transactionDateTo`|`date`|ISO 8601 YYYY-MM-DD|Filter transactions up to this transaction date (inclusive).
`pageSize`|`integer`|-|Page size (max limit: 100); default: 100
`pageToken`|`string`|-|Next page token as returned in a previous request.
`sort`|`string`|-|Sort criteria. Allowed values: `transactionDate`, `lastModified`; default: `transactionDate`
`order`|`string`|-|Sort order (`ASC - Ascending` or `DESC - Descending`); default: `DESC`
`includeAddendumFor`|`array `|`string`| Option to additionally fetch addendum data. Allowed values: `*` / `all`, `carRental`, `fleet`, `lodging`, `purchase`, `travel`; default behavior: no addendum data is returned.
`includeAddendumDetailsFor`|`array `|`string`| Option to additionally fetch addendum detail data. Allowed values: `*` / `all`, `fleet`, `lodging`, `purchase`, `travel`; default behavior: no addendum detail data is returned.


### Payload

* Request: none
* Response: [Transaction List Response](./v4.cards-endpoints.schemas.html#schema-transaction-list-response)

### Headers

* `concur-correlationid` is a specific custom header used for technical support in the form of a [RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace](https://tools.ietf.org/html/rfc4122).

### HTTP Status Codes

* 200 OK
* 400 Bad Request
* 401 Unauthorized
* 403 Forbidden
* 404 Not Found
* 500 Internal Server Error
* 503 Service Unavailable

To learn more about response HTTP status codes for this API see [HTTP Status Codes](./v4.cards-endpoints.schemas.html#http-status-codes).

### Examples

#### Request

```shell
GET https://us.api.concursolutions.com/cards/v4/users/e48fda91-15c8-4670-afe5-6c76501813c9/transactions
Accept: application/json
Authorization: Bearer {token}
Concur-CorrelationId: 90f23ece-cb6c-476f-818d-1412bdb23749
```

#### Response

```json
{
"transactions": [
{
"type": "RPE",
"transactionAmount": {
"currencyCode": "USD",
"value": 405.1
},
"postedAmount": {
"currencyCode": "USD",
"value": 405.1
},
"transactionDate": "2018-08-17",
"postedDate": "2018-08-19",
"billedAmount": {
"currencyCode": "USD",
"value": 405.1
},
"description": "ACME Hotels,123-456-7890,Seattle",
"description2": null,
"description3": null,
"description4": null,
"description5": null,
"referenceNumber": "gWp859SqAX97DsIVt5aoZmSNh4y8iH6qc",
"processorReferenceNumber": null,
"acquirerReferenceNumber": null,
"merchantReferenceNumber": null,
"customerVatNumber": "",
"totalTaxAmount": null,
"taxes": [],
"statement": {
"referenceNumber": null,
"billingDate": null
},
"id": "d1c555dc",
"companyId": "5c381619-4980-4eac-bf63-d229ce0be23b",
"account": {
"id": "C2593B6F67E44F4587A812CDD4105FF7",
"lastSegment": "4801",
"paymentType": {
"id": "1024"
},
"cardProductType": "CORP"
},
"billingAccount": null,
"administrativeData": {
"status": "UN",
"processType": "REG",
"receiptImageId": null,
"integrationPartner": "BATCH",
"addendumType": null,
"lastModified": "2025-08-15T18:23:34.487+00:00",
"hasRichData": false,
"isDeletable": false
},
"merchant": {
"name": "ACME Corporation",
"categoryCode": "7011",
"vatNumber": "",
"address": {
"city": "Seattle",
"countryCode": "US",
"state": "WA",
"streetAddress": "1 Hotel Way",
"zip": "90001"
}
}
}
],
"paging": {
"totalElements": 1,
"nextPageToken": null,
"page": 1,
"pageSize": 1,
"totalPages": 1
}
}
```
Binary file modified src/api-reference/cards/v4.cards-get-started-process-flow.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading