Detokenizer v5

The Detokenizer API allows clients to retrieve the user’s credit card number from Concur Expense in a secure way. It returns the user’s credit card number encrypted with a symmetric key that the client provides in the request. The client will be able to decrypt the user’s credit card number using their symmetric key. The detokenizer V5 version is FIPS compliant so that customers with IBCP card programs can benefit with credit card detokenizer functionality in CCPS environment. This API ensures secure transmission of sensitive data (card number) to customers as part of the remittance file creation process running at caller applications like ICS and CWS, in which the full, unmasked credit card number is required for the correct application of payments.

Authentication

Authentication is done via company JWT with required scope creditcardaccount.read. The company JWT refers to the token belonging to the company whose data is being accessed. If a company is accessing data on behalf of another company, then the calling company should invoke the detokenizer API using the JWT of the company that owns the card data. For example, if a company XYZ wants to call the detokenizer API on behalf of another company ABC, then the company XYZ should access the API using ABC’s company JWT.

Overview

The detokenizer v5 API exposes the following resources and these have to be called sequentially:

Resource Description
RSAPublicKey Retrieve RSA public Key via publickey API.
Credit Card Account Details Retrieve credit card number via Detokenizer API.

Limitations

This API is only for public use to support various SAP integration features or to the SAP Concur customer that has established corporate credit card accounts involved in the data (the “Customer Corporate Card Holder”). Such use must be in compliance with regulations and other industry standards, including but not limited to Payment Card Industry Data Security Standards (PCI DSS). Access to this documentation does not provide access to the API.

These APIs are available in US2, EU2, APJ1 and CCPS environments.

Process Flow

DetokenizerV5ProcessFlow

Products and Editions

  • Concur Expense Professional Edition
  • Concur Expense Standard Edition

Scope Usage

Name Description Endpoint
creditcardaccount.read Reads credit card data from Concur Expense. POST

Dependencies

SAP Concur clients must purchase Concur Expense in order to use this API.

Access Token Usage

This API supports company level access tokens. A Company access token (JWT) is required for these endpoints like mentioned in Authentication.

Get RSA Public Key Detail

Endpoint to retrieve RSA public Key. Returns RSA Public key for caller to consume the other V5 API i.e. Get Credit Card Account Details. This key would be used by caller to wrap their own symmetric key which would be passed to Get Credit Card Account Details API.

Scopes

creditcardaccount.read - Refer to Scope Usage for full details.

Request

GET https://{region}.api.concursolutions.com/detokenizer/v5/publickey

Parameters

  • None

Headers

Payload

  • None.

Response

Status Codes

In case of success, HTTP status code 200 (OK) - RSA Public Key is returned.

Headers

Payload

Example

Request

GET https://usg.api.concursolutions.com/detokenizer/v5/publickey
concur-correlationid: 87de8598-dbd5-4aea-af9d-988efb61c468
Authorization: Bearer JWT_TOKEN
Accept: application/json

Success Response

HTTP/1.1 200 OK
concur-correlationid: 87de8598-dbd5-4aea-af9d-988efb61c468
Content-Type: application/json
Content-Length: 1270

{
  "pubKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuPXJGJKBYiqRsPUrrxs7726KUQa+xiyaZ38CfvgPCUo6KV4WQRSAdudoY7Ut1VKA7tqjcFAV/OWVdqKYG32I4oyfGYGfacCXSSF+HQY6D8WrZg87mtNiZq0SrzQNESfd80ZpbKMEKSN23q7Pjub35YKfHWLn6JZXo+Y+YXW040ghCqNULFvG0EyY6WPalYCfQqV9231kJkyu5L0RLzjfqOLCfu4m+YHgo3FAEhFUrhYTDLMm7nnoGwQQA5Mf+Hcd84FMKIow0t7iv8fPox5uZS7o/RTCZfbGpCkyka5pF0NnkGXvLI5J8JCobO/IAm9DoElSClJznHZwZOtHcQb/gwIDAQAB",
  "version": 5
}

Error Response

401 Unauthorized
Content-Type: application/json

{
    "timestamp": "2025-05-12T13:24:18.149+00:00",
    "httpStatus": "401 - Unauthorized",
    "errorMessage": "",
    "errorId": "UNAUTHORIZED",
    "path": "/detokenizer/v5/publickey"
}

Get Credit Card Account Details

Returns the credit card number associated with the credit card token by adhering to FIPS standards, with the credit card number encrypted with caller’s symmetric key. Caller has to decrypt this Encrypted Credit Card Number using their symmetric key.

Prerequisite

  • Publickey endpoint needs to be called and symmetricKey needs to be wrapped using same before making request to this API.

Scopes

creditcardaccount.read - Refer to Scope Usage for full details.

Request

POST https://{region}.api.concursolutions.com/detokenizer/v5/creditcards/{creditCardGuid}

Parameters

Name|Type|Format|Description —|—|—|— creditCardGuid|string|-|Credit card GUID - It’s a token which represents a credit card number in Concur Expense. This creditCardGuid can be obtained from the cardAccountID field available in the Financial Integration Service (FIS) data.

Headers

Payload

Response

Status Codes

In case of success, HTTP status code 200 (OK) - Encrypted Credit Card Data is returned.

Headers

Payload

Example

Request

POST https://usg.api.concursolutions.com/detokenizer/v5/creditcards/9D118EDC278B844DB7814072110AC4D9
concur-correlationid: 87de8598-dbd5-4aea-af9d-988efb61c468
Authorization: Bearer JWT_TOKEN
Accept: application/json
Content-Type: application/json

{
  "symmetricKey": "R7zgrcT6rpJjtGPXIBSODGDblzPnhQgQ+CKCcwyn7rE8j7FImmNhtETqihB0WQhm1+6v70tKzJsaAMLeucVBEEDcz2sOXgED9WmG6BzhiKgiIJgGcSRTR0QZvdY5LgyI67mhLUT87xsGtUv2ZNkKTR9xkWn3cPrD3tB4bDE296gIRXDLpSadcQAK8gNUfLsuv5c3dfRUdc+B4QdWw8E+hxXR682DIfnpJFSWwoGp9uIao7nJeunXuvkvKfGz0SU1DDu8T4FVlpHJpwuf4a/Kgi+rI/JY0UBOYaW7B5Ne+F7ohcu3Np7SOr2FsSzTAX1X4GH63EstBPtPQr1sTd2yYA==",
  "keyVersion": 5
}

Response

HTTP/1.1 200 OK
concur-correlationid: 87de8598-dbd5-4aea-af9d-988efb61c468
Content-Type: application/json
Content-Length: 1270

{
  "accountNumber": "dPp0l3xtLvucH+md:EUjJp2eIWgIpjdHjTg0EhJjawdEek5M8gSrJBKHCOtY="
}

Error Response

400 Bad Request
Content-Type: application/json

{
    "timestamp": "2025-05-12T13:24:18.149+00:00",
    "httpStatus": "400 - Bad Request",
    "errorMessage": "Bad request [keyVersion] received.",
    "errorId": "BAD_REQUEST",
    "path": "/detokenizer/v5/creditcards/059fee21-a340-5043-8b72-583f5c2d10b0"
}

Schemas

RSA Public Key Response

Name Type Format Description
pubKey string - Base64 Encoded RSA public key of 2048 bits length.
version long - Version of RSA public key.

Credit Card Detokenizer Request

Name Type Format Description
symmetricKey string - AES Symmetric Key (256 length with transformation: AES/GCM/NoPadding) which is wrapped with RSA public key (transformation: RSA/ECB/OAEPWithSHA-256AndMGF1Padding). Note: Symmetric key has to be refreshed frequently in the caller side.
keyVersion long - Version of RSA public key used for wrapping symmetric key.

Credit Card Number Response

Name Type Format Description
accountNumber string - This field would consists of 2 parts with colon as delimiter. First Part is Base64 Encoded IV value and Second Part is Based64 Encoded Encrypted credit card number.

Error Response

Name Type Format Description Example
timestamp string - The time when the error was captured. -
httpStatus string - The http response code and phrase for the response. 400 - Bad Request; 401 - Unauthorized; 403 - Forbidden; 404 - Not Found; 500 - Internal Server Error
errorMessage string - The detailed error message. Bad request [creditCardGUID] received, Bad request [keyVersion] received, Bad request [symmetricKey] received; Unauthorized request; Forbidden request; Not Found; Internal server error. Please contact system administrator.
errorId string - The unique identifier of the error associated with the response. BAD_REQUEST; UNAUTHORIZED; FORBIDDEN; NOT_FOUND; INTERNAL_SERVER_ERROR
path string - The URI of the attempted request. -

On this page