diff --git a/src/api-reference/cards/v4.cards-endpoints.schemas-new.markdown b/src/api-reference/cards/v4.cards-endpoints.schemas-new.markdown new file mode 100644 index 000000000..bfa354d98 --- /dev/null +++ b/src/api-reference/cards/v4.cards-endpoints.schemas-new.markdown @@ -0,0 +1,571 @@ +--- +title: Cards v4 - Schemas +layout: reference +--- + +# Cards v4 Schemas + +# Account Schemas + +## Create Account List + +Name|Type|Format|Description +---|---|---|--- +`accounts`|`array`|[`Create Account`](#schema-create-account)|An array of Accounts to be created. (Maximum number of accounts per call: 1000) + +## Create Account + +Name|Type|Format|Description +---|---|---|--- +`accountType`|`enum`|-|**Required** Type of the credit card account. Supported values: `I - Individual`, `M - Managing (the master account of virtual cards)`, `V - Virtual card` +`billedCurrency`|`string`|3-letter ISO 4217 currency code|Billed currency of the card account. +`billingAccount`|`object`|[`Billing Account Reference`](#schema-billingaccountreference)|Reference to the billing account, e.g. in case of virtual card this references the managing/master account. +`cardBrand`|`enum`|-|Brand of the card. Supported values: `AX - American Express`, `CA - MasterCard`, `CB - Carte Blanche`, `DC - Diners Club`, `DS - Discover`, `EC - EuroCard`, `ER - ENROUTE`, `JC - JCB International`, `OT - Other`, `TP - UATP Card`, `UP - China Union Pay`, `VI - VISA` +`cardProductDescription`|`string`|-|**Required** Branded name of the credit card; might be used for display purposes. +`cardProductType`|`enum`|-|**Required** Card product type. Supported values: `CORP - Corporate Card`, `BUSN - Business Card` +`cardholder`|`object`|[`Cardholder`](#schema-cardholder)|Cardholder owning this card account. +`externalId`|`string`|-|**Required** Unique identifier (token) for a card account as defined by an external system (outside SAP Concur). Must not contain primary account number (PAN). +`lastSegment`|`string`|-|**Required** Last four digits of the credit card number. +`liabilityType`|`enum`|-|**Required** Liability type (payment method). Supported values: `IBIP - Individually Billed, Individually Paid`, `IBCP - Individually Billed, Company Paid`, `CBCP - Company Billed Company Paid` +`nameOnCard`|`string`|-|**Required** Embossed name on the card. +`provider`|`object`|[`Provider`](#schema-provider)|**Required** Credit card provider/issuer. +`status`|`enum`|-|Lifecycle status (default: Active). Supported values: `A - Active`, `C - Canceled` +`travelRequest`|`object`|[`Travel Request Reference`](#schema-travelrequestreference)|Reference to an SAP Concur Travel Request which is related to this card account. + +## Billing 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). + +## Cardholder + +Name|Type|Format|Description +---|---|---|--- +`email`|`string`|-|Email address of the card holder. This is an alternative way for identifying a user. +`employeeId`|`string`|-|Concur specific employeeId. This is an alternative way for identifying a user. The employeeId is a client facing ID. +`firstName`|`string`|-|First name of the card holder. +`lastName`|`string`|-|Last name of the card holder. +`userId`|`string`|-|The unique identifier of the user (refer to [Identity v4 API](/api-reference/profile/v4.identity.html)). This is the preferred way for identifying a user. The `userId` is a technical non-client facing ID. + +## Provider + +Name|Type|Format|Description +---|---|---|--- +`countryCode`|`string`|ISO 3166-1 Alpha-2 code|**Required** Country where card is issued. + +## Travel Request Reference + +Name|Type|Format|Description +---|---|---|--- +`id`|`string`|-|**Required** Unique identifier for an SAP Concur travel request (refer to [Travel Request v4 API](/api-reference/request/v4.endpoints.request-resources.html)). + +# Transaction Schemas + +## Create Transaction List + +Name|Type|Format|Description +---|---|---|--- +`transactions`|`array`|[`Create Transaction`](#schema-create-transaction)|**Required** An array of transactions to be created. (Maximum number of transactions per call: 1000) + +## Create Transaction + +Name|Type|Format|Description +---|---|---|--- +`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. +`carRental`|`object`|[`Car Rental`](#schema-carrental)|Car rental addendum data. +`customData`|`array`|[`Custom Data`](#schema-customdata)|Custom data. +`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. +`externalId`|`string`|-|**Required** Unique identifier for a card transaction as defined by an external system (outside the SAP Concur platform). +`fleet`|`object`|[`Fleet`](#schema-fleet)|Fleet addendum data. +`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` + +## 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 + +## 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` + +## 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). + +## 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. + +## Payment Type Reference + +Name|Type|Format|Description +---|---|---|--- +`id`|`string`|-|**Required** Concur internal payment type ID. + +## 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` + +## Car Rental + +Name|Type|Format|Description +---|---|---|--- +`adjustmentAmount`|`object`|[`Amount`](#schema-amount)|Adjustment amount. +`charges`|`array`|[`Car Rental Charge`](#schema-carrental-charge)|Car rental charges. +`classificationCode`|`string`|-|Classification of the rented vehicle. +`commodityCode`|`string`|-|Commodity code. +`customData`|`array`|[`Custom Data`](#schema-customdata)|Custom data. +`dailyRate`|`object`|[`Amount`](#schema-amount)|Daily rental fee. +`extraChargeAmount`|`object`|[`Amount`](#schema-amount)|Total amount of extra charges applied. +`extraChargeCode`|`string`|-|Code describing the cause of extra charges applied. +`extraDistanceRate`|`object`|[`Amount`](#schema-amount)|Additional rate per distance unit applied to the vehicle. +`maximumFreeDistance`|`object`|[`Distance`](#schema-distance)|Maximum travel distance allowed to the customer before additional charges apply. +`mileageRate`|`object`|[`Amount`](#schema-amount)|Rate applied per unit of distance traveled in vehicle. +`numberOfVehicles`|`integer`|-|Number of vehicles rented. +`pickupAddress`|`object`|[`Address`](#schema-address)|Address where the vehicle was rented. +`pickupDate`|`date`|ISO 8601 `YYYY-MM-DD`|Date on which the vehicle was rented. +`pickupPropertyId`|`string`|-|Property ID where the vehicle was rented. +`rentalAgreementNumber`|`string`|-|Number entered at the point of sale. +`rentalDays`|`integer`|-|Number of days the vehicle was rented. +`renterName`|`string`|-|Name of the individual that made the rental agreement. +`renterNotShown`|`boolean`|-|Renter not shown flag. +`returnAddress`|`object`|[`Address`](#schema-address)|True if renter did not pick up vehicle; no show charges may apply. +`returnDate`|`date`|ISO 8601 `YYYY-MM-DD`|Date the customer returned the vehicle. +`returnPropertyId`|`string`|-|Property ID where the vehicle was returned. +`totalDistance`|`object`|[`Distance`](#schema-distance)|Total distance traveled during the rental period. +`weeklyRate`|`object`|[`Amount`](#schema-amount)|Weekly rental fee. + +## Car Rental Charge + +Name|Type|Format|Description +---|---|---|--- +`amount`|`object`|[`Amount`](#schema-amount)|Amount. +`name`|`enum`|-|Name/type of the charge. Supported values: `REGULAR - Regular charges`, `ONEWAY - One-way drop charges`, `LATE - Late charges`, `FUEL - Fuel charges`, `INSURANCE - Insurance charges`, `EXTRA - Extra charges`, `OTHER - Other charges` + +## Fleet + +Name|Type|Format|Description +---|---|---|--- +`discountAmount`|`object`|[`Amount`](#schema-amount)|Discount Amount. +`driverId`|`string`|-|Driver ID. +`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`|-|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`|-|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. + +## Fleet Detail + +Name|Type|Format|Description +---|---|---|--- +`commodityCode`|`string`|-|Standard coding structure for the description of goods and services. +`description`|`string`|-|Description. +`discountAmount`|`object`|[`Amount`](#schema-amount)|Discount amount. +`discountApplied`|`boolean`|-|Indicating whether a discount is granted. +`extendedAmount`|`object`|[`Amount`](#schema-amount)|Extended amount. +`quantity`|`object`|[`Fleet Quantity`](#schema-fleet-quantity)|Quantity. +`sequenceNumber`|`integer`|-|Sequence Number. +`totalAmount`|`object`|[`Amount`](#schema-amount)|Total amount. +`unitAmount`|`object`|[`Amount`](#schema-amount)|Price per unit of measure. + + +## Fleet Quantity + +Name|Type|Format|Description +---|---|---|--- +`unit`|`string`|-|Fuel unit of measure. Preferred values: `LTR - liter`, `GLI - gallon (UK)`, `GLL - gallon (US)`, `KGM - kilogram`, `LBR - pound`, `KWH - kilowatt hour` +`value`|`number`|-|**Required** Quantity value. + +## Lodging + +Name|Type|Format|Description +---|---|---|--- +`adjustmentAmount`|`object`|[`Amount`](#schema-amount)|Adjustment amount. +`charges`|`array`|[`Lodging Charge`](#schema-lodging-charge)|Charges incurred for the lodging transaction aggregated per charge type. Note that each charge type can only be listed once. +`chargesDescription`|`string`|-|Charges description. +`checkInDate`|`date`|-|Date the customer checked in to the lodging location. +`checkOutDate`|`date`|-|Date the customer checked out of the lodging location. +`commodityCode`|`string`|-|Standard coding structure for the description of goods and services. +`customData`|`array`|[`Custom Data`](#schema-customdata)|Custom data. +`dailyRoomRate`|`object`|[`Amount`](#schema-amount)|Daily room rate. +`dailyRoomTax`|`object`|[`Amount`](#schema-amount)|Daily room tax amount. +`folioLineItems`|`array`|[`Lodging Detail`](schema-lodging-detail)|Folio line items. +`folioNumber`|`string`|-|Folio number. +`guestName`|`string`|-|Name of registered guest. +`lodgingAddress`|`object`|[`Address`](#schema-address)|Lodging address. +`merchantOrderNumber`|`string`|-|Merchant order number. +`numberInParty`|`integer`|-|Number of guests staying in the room. +`numberOfRoomNights`|`integer`|-|Total number of rooms times number of nights. +`numberOfRooms`|`integer`|-|Number of rooms reserved. +`otherServicesCode`|`string`|-|A code to explain other miscellaneous charges. +`prepaidAmount`|`object`|[`Amount`](#schema-amount)|Prepaid amount. +`programCode`|`string`|-|Code used to identify special circumstances. +`propertyId`|`string`|-|Property Id. +`propertyPhoneNumber`|`string`|-|Phone number of the property. +`roomType`|`string`|-|Room Type. +`taxes`|`array`|[`Lodging Tax`](#schema-lodging-tax)|Taxes incurred for the lodging transaction. +`totalLodgingAmount`|`object`|[`Amount`](#schema-amount)|Total lodging amount. +`totalNonRoomChargeAmount`|`object`|[`Amount`](#schema-amount)|Total non-room charge amount. +`totalTaxAmount`|`object`|[`Amount`](#schema-amount)|Total tax amount. + +## Lodging Charge + +Name|Type|Format|Description +---|---|---|--- +`amount`|`object`|[`Amount`](#schema-amount)|Amount. +`name`|`enum`|-|Name/type of the charge. Supported values: `BZCNT - Business center charges (copies, faxes, etc.)`, `CAADV - Cash advances charged against the folio`, `CONFR - Conference charges`, `FOODX - Food charges (excludes mini-bar)`, `GIFTX - Gift shop charges`, `HELTH - Health club, pool, court, golf charges`, `INTNT - Internet charges, online fees`, `LNDRY - Laundry charges`, `MNBAR - In room mini-bar charges`, `MOVIE - Movie/in room entertainment`, `OTHER - Other miscellaneous charges`, `PRKNG - Parking/Valet charges`, `TIPSX - Charges for Gratuities and Tips`, `TLPHN - Telephone charges` + +## Lodging Detail + +Name|Type|Format|Description +---|---|---|--- +`description`|`string`|-|Line item description. +`folioLineItemType`|`enum`|-|**Required** Name/type of the line item. Supported values: `BZCNT - Business center charges (copies, faxes, etc.)`, `CAADV - Cash advances charged against the `, `CONFR - Conference charges`, `CTTAX - County Room Tax`, `FDTAX - Federal Room Tax`, `FOODX - Food charges (excludes mini-bar)`, `GIFTX - Gift shop charges`, `GNTAX - General Taxes`, `HELTH - Health club, pool, court, golf charges`, `INTNT - Internet charges, online fees`, `LNDRY - Laundry charges`, `MNBAR - In room mini-bar charges`, `MNTAX - Municipal Room Tax`, `MOVIE - Movie/in room entertainment`, `OTHER - Other miscellaneous charges`, `PRKNG - Parking/Valet charges`, `PSTAX - Provincial Room Tax`, `PYMNT - Payments/Discounts received`, `RMRAT - Room Rate`, `RMTAX - Room Tax`, `TIPSX - Charges for Gratuities and Tips`, `TLPHN - Telephone charges` +`sequenceNumber`|`integer`|-|Sequence number. +`transactionAmount`|`object`|[`Amount`](#schema-amount)|Line item amount. +`transactionDate`|`date`|ISO 8601 `YYYY-MM-DD`|Transaction date of the line item. + +## Lodging Tax + +Name|Type|Format|Description +---|---|---|--- +`amount`|`object`|[`Amount`](#schema-amount)|Tax amount. +`type`|`enum`|-|Tax type. Supported values: `ROOMTAX - Room tax` + +## Merchant + +Name|Type|Format|Description +---|---|---|--- +`address`|`object`|[`Address`](#schema-address)|Merchant address. +`categoryCode`|`string`|-|Merchant category code (VISA merchant category classification). +`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. + +## Purchase + +Name|Type|Format|Description +---|---|---|--- +`commodityCode`|`string`|-|Commodity code. +`customData`|`array`|[`Custom Data`](#schema-customdata)|Custom data. +`description`|`string`|-|Purchase description. +`discountAmount`|`object`|[`Amount`](#schema-amount)|Discount amount. +`dutyAmount`|`object`|[`Amount`](#schema-amount)|Duty amount. +`invoiceNumber`|`string`|-|Invoice Number. +`items`|`array`|[`Purchase Detail`](#schema-purchase-detail)|Purchase items. +`merchantOrderNumber`|`string`|-|Order number assigned by the merchant. +`numberOfLineItems`|`integer`|-|Number of line items that belong to the purchase. +`orderDate`|`date`|ISO 8601 `YYYY-MM-DD`|Date the order was placed. +`purchaseDate`|`date`|ISO 8601 `YYYY-MM-DD`|Effective/transaction date of the order. +`shipFromAddress`|`object`|[`Address`](#schema-address)|Ship from address. +`shipToAddress`|`object`|[`Address`](#schema-address)|Ship to address. +`shippingAmount`|`object`|[`Amount`](#schema-amount)|Shipping amount. +`supplierAddress`|`object`|[`Address`](#schema-address)|Supplier address. +`taxes`|`array`|[`Purchase Tax`](#schema-purchase-tax)|Taxes incurred for the purchase. + +## Purchase Detail + +Name|Type|Format|Description +---|---|---|--- +`commodityCode`|`string`|-|Commodity code. +`customData`|`array`|[`Custom Data`](#schema-customdata)|Custom data. +`description`|`string`|-|Purchase item description. +`discountAmount`|`object`|[`Amount`](#schema-amount)|Discount amount. +`discountApplied`|`boolean`||Indicating whether a discount is granted. +`extendedAmount`|`object`|[`Amount`](#schema-amount)|Extended amount. +`itemId`|`string`|-|Identifier of the item. +`quantity`|`object`|[`Purchase Quantity`](#schema-purchase-quantity)|Quantity. +`sequenceNumber`|`integer`|-|Sequence Number. +`taxIncluded`|`boolean`|-|Indicating whether tax is included in the amount. +`totalAmount`|`object`|[`Amount`](#schema-amount)|Total amount. +`unitAmount`|`object`|[`Amount`](#schema-amount)|Price per unit of measure. + +## Purchase Tax + +Name|Type|Format|Description +---|---|---|--- +`amount`|`object`|[`Amount`](#schema-amount)|Tax amount. +`type`|`enum`|-|Tax type. Supported values: `SHIPPINGVAT - Shipping Value-added Tax (VAT)` + +## Purchase Quantity + +Name|Type|Format|Description +---|---|---|--- +`unit`|`string`|-|Unit of measure (preferably use codes from [https://www.unece.org/cefact/codesfortrade/codes_index.html](https://www.unece.org/cefact/codesfortrade/codes_index.html), for example `EA - each`, `KGM - kilogram`, `LTR - liter`). +`value`|`number`|-|Quantity value. + +## Statement + +Name|Type|Format|Description +---|---|---|--- +`billingDate`|`date`|ISO 8601 `YYYY-MM-DD`|Billing (end) date of the statement. +`referenceNumber`|`string`|-|Reference number of the statement. + +## Transaction Tax + +Name|Type|Format|Description +---|---|---|--- +`amount`|`object`|[`Amount`](#schema-amount)|Tax amount. +`type`|`enum`|-|Tax type. Supported values: `LOCAL - Local tax`, `VAT_OR_GST - Value-added Tax (VAT) or Goods and Services Tax (GST)`, `SALES - Sales Tax`, `PST_OR_QST - Provincial Sales Tax (PST) or Quebec Sales Tax (QST)`, `OTHER - Other taxes` + +## Travel + +Name|Type|Format|Description +---|---|---|--- +`baseFare`|`object`|[`Amount`](#schema-amount)|Amount of the ticket, excluding fees and taxes. +`commodityCode`|`string`|-|National standard coding Structure for the description of goods and services. +`conjunctionId`|`string`|-|ID for a ticket that contains an itinerary that is more than four segments. +`customData`|`array`|[`Custom Data`](#schema-customdata)|Custom data. +`customerData`|`string`|-|Customer defined data entered at the point of sale. +`departureDate`|`date`|ISO 8601 `YYYY-MM-DD`|Date of departure for the first leg of travel. +`domestic`|`boolean`|-|Indicates whether the the travel is domestic. +`electronicTicket`|`boolean`|-|Indicates whether the ticket is an e-ticket. +`endorsements`|`string`|-|Describes the fare issued by the airline. +`exchangedTicketAmount`|`object`|[`Amount`](#schema-amount)|Total amount of the ticket for which the original was exchanged. +`exchangedTicketNumber`|`string`|-|Number of the new ticket which replaces the original ticket. +`issueDate`|`date`|ISO 8601 `YYYY-MM-DD`|Date when the ticket was issued to the ticket holder. +`issuingCarrier`|`string`|-|Airline or railway carrier. +`numberOfLegs`|`integer`|-|Number of city pairs included on the ticket +`passengerName`|`string`|-|Name of the person to whom the ticked was issued. +`refundTicketNumber`|`string`|-|Refund ticket number. +`restrictionsApply`|`boolean`|-|Identifier noting ticket purchased has some restriction associated with its use. +`segments`|`array`|[`Travel Detail`](#schema-travel-detail)|Travel segments. +`ticketNumber`|`string`|-|Ticket Number. +`totalFare`|`object`|[`Amount`](#schema-amount)|Total amount of the ticket. +`totalFee`|`object`|[`Amount`](#schema-amount)|Total amount of fees associated with the ticket. +`totalTaxAmount`|`object`|[`Amount`](#schema-amount)|Total amount of taxes associated with the ticket. +`travelAgencyCode`|`string`|-|Code assigned to the travel agency that booked the ticket. +`travelAgencyInvoiceNumber`|`string`|-|Invoice number assigned by the travel agency that booked the ticket. +`travelAgencyName`|`string`|-|Name of the travel agency that booked the ticket. + +## Travel Detail + +Name|Type|Format|Description +---|---|---|--- +`arrivalCountry`|`string`|-|Arrival Country. +`arrivalDate`|`date`|ISO 8601 `YYYY-MM-DD`|Date of arrival. +`arrivalLocation`|`string`|-|Arrival location/code. +`carrierCode`|`string`|-|Air or Rail carrier name abbreviation. +`conjunctionTicketNumber`|`string`|-|ID for a ticket that contains an itinerary that is more than four segments. +`customData`|`array`|[`Custom Data`](#schema-customdata)|Custom data. +`departureCountry`|`string`|-|Departure Country. +`departureDate`|`date`|ISO 8601 `YYYY-MM-DD`|Date of departure. +`departureLocation`|`string`|-|Departure location/code. +`endorsements`|`string`|-|Describes the fare issued by the airline. +`exchangeTicketNumber`|`string`|-|Exchange ticket number. +`fare`|`object`|[`Amount`](#schema-amount)|Amount of the ticket for this leg of travel. +`fee`|`object`|[`Amount`](#schema-amount)|Amount of fees associated with this leg of travel. +`flightNumber`|`string`|-|Flight number assigned by the airline carrier. +`foreignArrival`|`boolean`|-|Indicates if the travel is from a foreign country. +`foreignDeparture`|`boolean`|-|Indicates if the travel is to a foreign country. +`isDestination`|`boolean`|-|Indicates if this is the final leg of travel on the ticket. +`isOrigin`|`boolean`|-|Indicates if this is the first leg of travel on the ticket. +`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. + +## 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. + +# Bulk Request Schemas + +## Bulk Request + +Name|Type|Format|Description +---|---|---|--- +`completedAt`|`timestamp`|RFC 3339 `YYYY-MM-DDThh:mm:ss.nnnZ`|Timestamp when processing of the bulk request was completed. +`receivedAt`|`timestamp`|RFC 3339 `YYYY-MM-DDThh:mm:ss.nnnZ`|**Required** Timestamp when the bulk request was received. +`requestId`|`string`|-|**Required** Unique identifier of the API request. +`status`|`enum`|-|**Required** The processing status. Supported values: `IN_PROGRESS - In progress`, `COMPLETED_SUCCESSFULLY - Completed successfully`, `COMPLETED_WITH_WARNINGS - Completed with warnings`, `COMPLETED_WITH_ERRORS - Completed with errors`, `PROCESSED_PARTIALLY_PENDING_RETRY - Processed partially, pending retry` +`totalElements`|`integer`|-|**Required** Number of elements in this bulk request. +`type`|`string`|-|**Required** Type of the API request. Supported values: `POST_ACCOUNT - Account creation`, `POST_TRANSACTION - Transaction creation`, `PATCH_ACCOUNT - Account update`, `PATCH_TRANSACTION - Transaction update` + +# Common Schemas + +## Bulk API Response + +Name|Type|Format|Description +---|---|---|--- +`requestId`|`string`|-|**Required** Unique identifier of the bulk API request. +`links`|`array`|[`Link`](#schema-link)|An array of links. + +## Link + +Name|Type|Format|Description +---|---|---|--- +`href`|`string`|-|**Required** Hyperlink to the resource. +`rel`|`string`|-|**Required** Relation type as defined by the server. + +## Error Response + +Name|Type|Format|Description +---|---|---|--- +`errorCode`|`string`|-|**Required** Machine readable code associated with the error which is static and never localized. Possible error codes: `invalidRequest - The request contains errors (usually contains a detailed error list)`, `invalidJson - The request body is not a valid JSON` +`errorMessage`|`string`|-|**Required** Message associated with the error. +`dataPath`|`string`|-|Relative data path. +`errors`|`array`|[`Error`](#schema-error)|An array of detailed/nested errors. + +## Error + +Name|Type|Format|Description +---|---|---|--- +`errorCode`|`string`|-|**Required** Machine readable code associated with the error which is static and never localized. Possible error codes see [Detailed Error Codes](#detailed-error-codes) +`errorMessage`|`string`|-|**Required** Message associated with the error. +`dataPath`|`string`|-|Relative data path. + +## Address + +Name|Type|Format|Description +---|---|---|--- +`city`|`string`|-|City. +`countryCode`|`string`|ISO 3166-1 Alpha-2 code|Country code. +`state`|`string`|-|State / province / region. +`streetAddress`|`string`|-|Street address lines. +`zip`|`string`|-|Zip / postal code. + + +## Amount + +Name|Type|Format|Description +---|---|---|--- +`currencyCode`|`string`|3-letter ISO 4217 currency code|**Required** Currency of the amount. +`value`|`number`|-|**Required** Amount value. + +## Custom Data + +Name|Type|Format|Description +---|---|---|--- +`id`|`string`|-|**Required** Id of the custom field. +`value`|`string`|-|Value of the custom field. + +## Distance + +Name|Type|Format|Description +---|---|---|--- +`unit`|`enum`|-|Distance unit. Supported values: `KM - Kilometer`, `MILE - Mile` +`value`|`integer`|-|**Required** Distance value (without decimal places). + +## HTTP Status Codes + +HTTP Status Code|Description +---|--- +200 OK|The request succeeded. +202 Accepted|The request has been accepted and will be processed asynchronously. +400 Bad Request|The request was rejected due to client-side errors. Possible error codes: `invalidRequest`, `invalidJson`. In case of `invalidRequest` the error response usually contains a detailed error list, refer to Detailed Error Codes. +401 Unauthorized|The request is not authenticated. Missing or invalid authorization header. +403 Forbidden|The request is not authorized to access this resource. +404 Not Found|The requested resource does not exist. +500 Internal Server Error|Unexpected error on server side. +503 Service Unavailable|The server is temporarily unavailable. + +## Detailed Error Codes + +Error Code|Description +---|--- +`tooManyItems`|The collection contains more than the allowed number of items. +`missingRequiredField`|Missing required field. +`illegalCardNumberValue`|The value contains a credit card number which is not allowed due to PCI. +`invalidFieldSize`|Size must be between {min} and {max}. +`invalidEnum`|Value is not one of the allowed values. +`invalidCountryCode`|Value is not a valid ISO 3166-1 Alpha-2 country code. +`invalidCurrencyCode`|Value is not a valid 3-letter ISO 4217 currency code. +`invalidUUID`|Value is not a valid UUID. +`invalidEmailAddress`|Value is not a valid email address. +`invalidCharsExternalId`|Only alphanumeric characters, hyphen -, and underscores _ are allowed. +`invalidAppId`|The appId of the access token is unknown to the system. +`duplicateExternalId`|The externalId in this request must be unique. +`duplicateTaxType`|The tax type must be unique within each taxes list. +`duplicateChargeName`|The charge name must be unique within each charges list. +`duplicateCustomDataID`|The custom data id must be unique within each `customData` list. +`ambiguousAddendumType`|The transaction contains data for multiple addendum types at the same time. +`currencyInconsistency`|The transaction contains inconsistencies between the transaction currency and other currency fields. +`illegalBillingAccount`|Billing account reference must not be present for the given account type. +`missingBillingAccount`|Billing account reference must be present for the given account type. diff --git a/src/api-reference/cards/v4.cards-endpoints.transaction-new.markdown b/src/api-reference/cards/v4.cards-endpoints.transaction-new.markdown new file mode 100644 index 000000000..5a7734ac7 --- /dev/null +++ b/src/api-reference/cards/v4.cards-endpoints.transaction-new.markdown @@ -0,0 +1,376 @@ +--- +title: Cards v4 - Credit Card Transaction +layout: reference +--- + +# Cards v4 - Credit Card Transaction + +## Create Card Transactions (Bulk) + +Endpoint to create credit card transactions as bulk operation. Assuming that the request is properly authorized and the schema validation passes, the API immediately returns `202 (Request Accepted)` and performs the actual processing asynchronously. + +### Scopes + +`cards.transaction.writeonly` - Refer to [Scope Usage](./v4.cards-get-started.html#scope-usage) for full details. + +### URI + +```shell +POST https://{datacenterURI}/cards/v4/companies/{companyId}/transactions/bulk +``` + +### Parameters + +Name|Type|Format|Description +---|---|---|--- +`companyId`|`string`|-|**Required** The unique identifier of the SAP Concur company. + +### Payloads + +* Request: [Create Transaction List](./v4.cards-endpoints.schemas.html#schema-create-transaction-list) +* Response: [Bulk API Response](./v4.cards-endpoints.schemas.html#schema-bulkapi-response) + +Notes: +* This API can only be used for creating new transactions. If the same `externalId` is sent a second time, it will be ignored with an error during processing. +* The `externalId` is a unique identifier for a card transaction as defined by an external system (outside the SAP Concur platform). It must not contain the primary account number (PAN). It may contain the same value as `referenceNumber` as long as it is unique. +* A transaction contains a reference to an account using the account `externalId`. Referenced accounts need to be created via Card Accounts (Bulk) API. +* The `authorizationExternalId` can be used to reference a posted transaction to a preceding authorization. In this case the authorization will be overwritten by the posted transaction. +* A transaction can only contain one type of addendum data (car rental, fleet, lodging, purchase, or travel) at the same time. + +### 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 + +In case of success, HTTP status code `202 (Request Accepted)` is returned. +In case of a bad request, HTTP status code `400 (Bad Request)` is returned along with an error code describing the cause. Possible error codes are: `invalidRequest`, `invalidJson`. For `invalidRequest` the error response usually contains a detailed error list. + +To learn more about response HTTP status codes for this API see [HTTP Status Codes](./v4.cards-endpoints.schemas.html#http-status-codes). + +### Examples + +#### Valid Request + +```shell +POST https://us.api.concursolutions.com/cards/v4/companies/1700f4bc-4166-4516-bffe-91d7ae423189/transactions/bulk +Content-Type: application/json +Accept: application/json +Authorization: Bearer {token} +Concur-CorrelationId: 90f23ece-cb6c-476f-818d-1412bdb23749 +``` + +```json +{ + "transactions": [{ + "account": { + "externalId": "59edf00e-6e0a-46c4-bf59-c233000c5b98" + }, + "billedAmount": { + "currencyCode": "USD", + "value": 405.10 + }, + "description": "ACME Hotels,123-456-7890,Seattle", + "externalId": "1047ecc3-bc47-4b2f-bcf5-6c8e13291338", + "lodging": { + "charges": [{ + "amount": { + "currencyCode": "USD", + "value": 19.90 + }, + "name": "INTNT" + } + ], + "checkInDate": "2022-08-14", + "checkOutDate": "2022-08-17", + "dailyRoomRate": { + "currencyCode": "USD", + "value": 120 + }, + "folioNumber": "F344145-51VD", + "guestName": "DOE,JOHN", + "lodgingAddress": { + "city": "Vancouver", + "countryCode": "CA", + "state": "BC", + "streetAddress": "433 Hotel Street", + "zip": "v6b 6l9" + }, + "numberOfRoomNights": 3, + "numberOfRooms": 1, + "totalLodgingAmount": { + "currencyCode": "USD", + "value": 360 + }, + "totalNonRoomChargeAmount": { + "currencyCode": "USD", + "value": 19.90 + }, + "totalTaxAmount": { + "currencyCode": "USD", + "value": 25.2 + } + }, + "merchant": { + "address": { + "city": "Seattle", + "countryCode": "US", + "state": "WA", + "streetAddress": "1 Hotel Way", + "zip": "90001" + }, + "categoryCode": "7011", + "doingBusinessAs": "ACME Hotels", + "id": "ACME34393", + "name": "ACME Corporation" + }, + "postedAmount": { + "currencyCode": "USD", + "value": 405.10 + }, + "postedDate": "2018-08-19", + "referenceNumber": "gWp859SqAX97DsIVt5aoZmSNh4y8iH6qc", + "transactionAmount": { + "currencyCode": "USD", + "value": 405.10 + }, + "transactionDate": "2018-08-17", + "transactionDateTime": "2018-08-17T09:15:23.000", + "type": "RPE" + } + ] +} +``` + +#### Success Response + +```shell +202 Accepted +Content-Type: application/json +``` + +```json +{ + "links": [ + { + "href": "https://us.api.concursolutions.com/cards/v4/companies/1700f4bc-4166-4516-bffe-91d7ae423189/bulkrequests/55e45023-813f-46a2-b83c-1a0b0b7bdda6", + "rel": "self" + } + ], + "requestId": "55e45023-813f-46a2-b83c-1a0b0b7bdda6" +} +``` + +#### Invalid Request + +```shell +POST https://us.api.concursolutions.com/cards/v4/companies/1700f4bc-4166-4516-bffe-91d7ae423189/transactions/bulk +Content-Type: application/json +Accept: application/json +Authorization: Bearer {token} +Concur-CorrelationId: 90f23ece-cb6c-476f-818d-1412bdb23749 +``` + +```json +{ + "transactions": [{ + "account": { + "externalId": "59edf00e-6e0a-46c4-bf59-c233000c5b98" + }, + "externalId": "1047ecc3-bc47-4b2f-bcf5-6c8e13291338-this-is-too-long-must-only-be-50-chars-max", + "merchant": { + "name": "ACME Corporation" + }, + "postedDate": "2018-08-19", + "transactionAmount": { + "currencyCode": "USD", + "value": 405.10 + }, + "transactionDate": "2018-08-17", + "type": "XXX" + } + ] +} +``` + +#### Error Response + +```shell +400 Bad Request +Content-Type: application/json +``` + +```json +[ + { + "errorCode": "invalidRequest", + "errorMessage": "The request contains errors", + "dataPath": "/v4/companies/1700f4bc-4166-4516-bffe-91d7ae423189/transactions/bulk", + "errors": [ + { + "errorCode": "invalidEnum", + "errorMessage": "Value is not one of the allowed values", + "dataPath": "transactions[0].type" + }, + { + "errorCode": "missingRequiredField", + "errorMessage": "Missing required field", + "dataPath": "transactions[0].postedAmount" + }, + { + "errorCode": "invalidFieldSize", + "errorMessage": "size must be between 1 and 50", + "dataPath": "transactions[0].externalId" + } + ] + } +] +``` + +## Retrieve Card Transactions by User + +Endpoint to retrieve credit card transactions of a user. Only cleared card transactions received via file feed, or bespoke API integration are supported; Card transactions received via the Yodlee integration (including personal card transactions) are 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 + } +} +``` diff --git a/src/api-reference/cards/v4.cards-get-started-new.markdown b/src/api-reference/cards/v4.cards-get-started-new.markdown new file mode 100644 index 000000000..0c1da9574 --- /dev/null +++ b/src/api-reference/cards/v4.cards-get-started-new.markdown @@ -0,0 +1,59 @@ +--- +title: Cards v4 - Getting Started +layout: reference +--- + +# Cards v4 - Getting Started + +Cards v4 **write** APIs provide certified partner financial networks, issuing banks, and fin-tech partners with an automated path for mutual clients to make self-service connections between the partner and Concur Expense. This path enables the partner to subsequently submit Credit Card Account and Transaction data to Concur Expense in near real time. The write APIs are only available to **partners** who have been granted access and are creating a certified application. Those are not intended to be accessed by clients directly. + +The Cards v4 **read** APIs can be used to read card transactions for a given user. + +## Overview + +The Cards v4 API exposes the following resources: + +Resource|Description +---|--- +Account|Partners can create Accounts via bulk API. +Transaction|Partners can create Transactions via bulk API. Users can retrieve Transactions. +Bulk Request|Partners can retrieve the details of a Bulk Request. + +## Limitations + +Access to this documentation does not provide access to the API. + +Write API limitations: + +- Cards v4 write APIs are available in all data centers exceptand only to partners who have been granted access. +- Maximum number of accounts / transactions per call is 1000. +- Notification of bulk request completion via [Event Subscription Service](/api-reference/ess/v4.event-subscription.html) is already depicted in the process flow diagram but not yet available. + +## Process Flow + +![CardsV4ProcessFlow](./v4.cards-get-started-process-flow-new.png) + +## Products and Editions + +* Concur Expense Professional Edition +* Concur Expense Standard Edition + +## Scope Usage + +Name|Description|Endpoint|Supported Authentication +---|---|---|--- +`cards.account.writeonly`|Write Credit Card Account|POST|Company JWT for certified partners +`cards.transaction.writeonly`|Write Credit Card Transaction|POST|Company JWT for certified partners +`cards.transaction.read`|Read Credit Card Transaction|GET|User JWT +`cards.bulkrequest.read`|Read Bulk Request details|GET|Company JWT for certified partners + +## Dependencies + +SAP Concur clients must purchase Concur Expense in order to use this API. Please contact your SAP Concur representative for more information. + +The Identity v4 API can be used to retrieve the `userId` and `companyId`. + +## Access Token Usage + +The write APIs support company level access tokens. +The read API for card transactions supports user level access tokens. diff --git a/src/api-reference/cards/v4.cards-get-started-process-flow-new.png b/src/api-reference/cards/v4.cards-get-started-process-flow-new.png new file mode 100644 index 000000000..a8efb7cec Binary files /dev/null and b/src/api-reference/cards/v4.cards-get-started-process-flow-new.png differ diff --git a/src/api-reference/cards/v4.cards-get-started.markdown b/src/api-reference/cards/v4.cards-get-started.markdown index 96ed86959..c2c336ae9 100644 --- a/src/api-reference/cards/v4.cards-get-started.markdown +++ b/src/api-reference/cards/v4.cards-get-started.markdown @@ -53,4 +53,3 @@ The Identity v4 API can be used to retrieve the `userId` and `companyId`. ## Access Token Usage This API supports company level access tokens. -