Welcome to the reference for the Transaction Connect REST API, aka TC4Hubs API! Want to share your opinion on how our API works for you? Tell us how you feelabout using our API and what we can do to make it better: tech@transactionconnect.com

You can access the TC4Hubs REST API via one of the following endpoints:

On Shopping Hubs API, some requests need to be signed by providing Signature headers (see section below). To be able to sign requests, you should provide a dedicated public keys for both staging and live environment of the API (see “RSA keys generation instruction” section). Those keys should be emailed to tech@transactionconnect.com. The private key should be securely stored on your server. In case of possible security breach, the private key should be regenerated and the public key should be emailed again.

Signature headers

The following headers are required for the request to be considered signed:

• Expires-at - request expiration time as a UNIX timestamp in UTC timezone. We suggest to use +1 minute from the current time. The maximum value is 1 hour from now in UTC, otherwise a ForbiddenRequest with invalidExpiresAtHeader code error will be raised;
• Signature - base64 encoded SHA256 signature of the string represented in the form Expires-at|request_method|original_url|post_body| - 4 parameters concatenated with a vertical bar |, signed with the client’s private key. The pseudocode to generate the signature looks like this: base64(sha256_signature(private_key, "Expires-at|request_method|original_url|post_body|"))) The fields request_method, original_url, and post_body from the Signature header represent:
• request_method - uppercase method of the HTTP request. Example: GET, POST, PATCH, PUT, DELETE, etc.;
• original_url - the full requested URL, with all its complementary parameters;
• post_body - the request post body. Should be left empty if it is a GET request, or the body is empty;

An example of the string that is to be used to generate the signature looks as follows:

GET string example: 1522249849|GET|https://api.transactionconnect.com/myResource?customerId=123||;

POST string example: 1522249849|POST|https://api.transactionconnect.com/myResource|{"customerId":"123"};

Headers example: Expires-at: 1413466421 Signature: 0o6LgMnlG7FX5tWLoKd6V5jlktodP8I/3vWqh1pOZvPgMn/WPq5YqZWPc0teey135RO2muFThcvuZJtcbaUje1UWFHyWhTh89guHJ47pgBB7w0LMkRw3XskEsafEUZketeTY/NtyeU7ETHHm2Tlw8IJho+gk51Rtp7JJPanw2OZG/6BElFcL0qGs4ohTmJUKKsdI1eo5jseFqF+sX0T4dRYqL7ebhDCD8YsYdsZ9zxlX88+YtUQnEqGbswOH4saGaQNH9NjxST2NS8MFtCU7uwZGybBk4i0l1wtbTJwfgaa+yb2L7l0ltIgxZFJzQOShpVOgI+o8fUg31lOblmMVkpyvXJ/n5Ed2u0nA1yMWkQUPpu03Xkh2RG7qbBOEq6+A374OnhUDwi5TUqYrY89paPwq/A7z2lc56Q84T+NrSLdi0x0aejpp6Cn90Yqpbs04dIio579+KyLm/8XoZ4p9k7vz6vTpDITyTAc93/KHnqeT1hTp7AWMaxuGfEI361fyZLDzkSvnHq4QzMkJOKhPELxSji99dm0LCSZpUiUhTTU3G09LvLBCEFLvbGJzxlO7NgqOGVPMlEc4fJqzU/jrTfkodn4DtzaOJghlXynithKIUBAkpNY9QGPOQIMvcbOZfhilm+bjWuYeNpeALvbqY3ONcibHLjc8ItAVMzORSFg=

RSA keys generation instruction

1. Install openssl package

Mac OS X Install via [Homebrew] (http://brew.sh/): brew install openssl

Windows [Windows complete package .exe installer] (https://www.openssl.org/community/binaries.html)

Ubuntu Linux apt-get install openssl

2. Create the RSA Key Pair for Mac OS X and Ubuntu Linux: type in the command line: openssl genrsa -out private.pem 2048 openssl rsa -pubout -in private.pem -out public.pem

for Windows: After the package has been installed, open a command prompt and navigate to the install path. Then you can generate RSA keys by typing: openssl genrsa -out private.pem 2048 openssl rsa -pubout -in private.pem -out public.pem

3. Send the public key The private key (private.pem) should be securely stored on your server. The public key (public.pem) should be emailed to tech@transactionconnect.com

For the integration with your website or up you can redirect your users to our website for different actions and pass a callback url to redirect the user to your site at the end of the action

The user can be redirected to different interfaces depending on the active features on the shopping hub(the url entry point doesn't change).*

if receipt scan is enabled + bank connection is activated, the user is redirected to a registration choice (manual(scan) / auto(account linking))*

if the scan is not activated, the user is directly redirected to the bank selection.*

Once the user is registered, he accesses a success page then is redirected to your own customer area using the callback url initially provided in the url query string (cb=your_callback_url)*

technical information(url access):

Link: https://your-loyalty-domain.com/cashback?mid=[your_mall_id]&cid=[your_customer_id]&cb=[your_callback_url]&lng=[language]

your_mall_id - your mall id as stored in our database as external

your_customer_id - your customer id as stored in our database as external

your_callback_url - the url to redirect the user at the end of the onboarding

language - the language to be shown in a two letters format (ex. 'fr') the language of your shopping hub or english are always available

When the user does not have a cashback method yet, he/she can add it using the /cashback url. Once the method has been registered, the user can visualize/update it on the Profile interface (see section below)

Link https://your-loyalty-domain.com/cashback?t=[the_jwt_token_for]&cb=[your_callback_url]&lng=[language]

cb - the url to redirect the user at the end of the onboarding

t - the token of the user

lng - the language to be shown in a two letters format (ex. 'fr') the language of your shopping hub or english are always available

When the user does not have a cashback method, we invite him to enter one of his own using our Profile interface. Once the method has been registered, the user can visualize/update his cashback method*

technical information(url access):

Link: https://your-loyalty-domain.com/profile?t=[the_jwt_token_for]&cb=[your_callback_url]&lng=[language]

your_callback_url - the url to redirect the user at the end of the onboarding

language - the language to be shown in a two letters format (ex. 'fr') the language of your shopping hub or english are always available

This area allows the user to visualize the main information relating to his customer account (purchases, claims, rewards and transactions (made in the shopping hub)).*

The user can also make a claim, add a scan(for scan users) and add a first connection (for scan users)*

technical information(url access):

Link: https://your-loyalty-domain.com/activities?t=[the_jwt_token_for]&cb=[your_callback_url]&lng=[language]

language - the language to be shown in a two letters format (ex. 'fr') the language of your shopping hub or english are always available

This area allows the user to visualize his bank connections linked to the shopping hub's loyalty program*

The user can also update his banking information, add new connections, delete a connection (you need at least 2 connections to be able to delete one)*

technical information(url access):

Link: https://your-loyalty-domain.com/connections?t=[the_jwt_token_for]&cb=[your_callback_url]&lng=[language]

language - the language to be shown in a two letters format (ex. 'fr') the language of your shopping hub or english are always available

When an event occurs, we send you a webhook notification to tell you what's happened so you can take action and keep your business running smoothly.

Webhooks provide a definitive confirmation of a status update and are used for a variety of purposes, such as notifying an onboarding, notifying some new transactions happened in the hub, notifyng a change in the status of a customer connection.

When the event you subscribed by creating a webhook occurs we will POST the data on the url you provided in the json format indicated here in the webhook events documentation.

To create a webhook use the POST /webhook api. You can then manage it with the PATCH and DELETE api.

This event is triggered when a customer subscription is updated

Parameters in the body:

event [String]: the name of the webhook event

customerExternalId [String]: the customer external id assigned by the client

credentialsPreviouslyUsed [Boolean]: bank credentials already used for this customer

customerId [String]: Transaction Connect's customer id

dataProviderType [String]: Provider type of subscription, possible values: 'bank', 'restaurant', 'scan' (not required)

registrationDate [String]: Customer's registration date (in ISO 8601 format)

status [String]: The status that has been updated, possible values: 'creation', 'deletion', 'update'

NB: this webhook only works for customers with an externalId. We need the field externalIdSynced to not notify hub several times for the same customer, but this field should be renamed and accessible to all customer even if they do not have externalId.

Example:

{
    "event": "customer_subscription",
    "customerExternalId: "43213424",
    "credentialsPreviouslyUsed": false,
    "customerId": "c84c33cf-62c6-4a44-8692-973cc0cc420c",
    "dataProviderType": "bank",
    "registrationDate": "2020-07-13T11:34:41+01:00",
    "status": "creation"
}

This event is triggered when new transactions are detected inside the program. This webhook pushes more transactions at the time in an array

Parameters in the array in the body:

event [String]: the name of the webhook event

transactions: [Array]

id [uuid]: the id of the transaction

amount [Float]: the amount of the transaction

currency [String]: the currency of the transaction in three letters format ex.'EUR'

purchaseDate [String]: the date of the transaction

dateBankingStatement [String]: the date of the banking statement

customerId [String]: Transaction Connect's customer id

customerExternalId [String]: The client's customer id

dataProviderType [String]: The cardType 'bank' or 'restaurant' or 'scan'

purchaseLocation: [Object]

id: The Transaction Connect's id of the purchase location

externalId: The external id of the purchase location

type: The purchase location type 'service' or 'store'

Example:

{
    "event": "customer_transactions",
    "transactions": [
        {
            "id": "c84c33cf-62c6-4a44-8692-973cc0cc420c",
            "amount": -10.53
            "currency": "EUR",
            "purchaseDate": "2018-03-29",
            "dateBankingStatement": "2018-04-01",
            "customerId": "8148b7f5-fcd4-4818-aefa-5450e7dd5dad",
            "customerExternalId": "87316292",
            "dataProviderType": "bank",
            "purchaseLocation": {
        "id": "6a6a578b-662b-4673-8885-e00902a34dd4",
        "externalId": "18289377",
                "type": "store"
            }
        }
    ]
}

This event is triggered when a receipt ticket is updated

Parameters in the body:

event [String]: the name of the webhook event

receiptId [Uuid]: the id of the receipt ticket

status [String]: the status that has been updated possible values: 'pending', 'validated', 'rejected'

Example:

{
    "event": "receipt_updated",
    "receiptId": "d7d4bad0-f7c0-4427-9305-fa5c9394e211",
    "status": "rejected",
    "customerId": "c84c33cf-62c6-4a44-8692-973cc0cc420c"
}

This event is triggered when a cashback method (ex. IBAN) is updated. When the customer iban is missing for example, we'll trigger this event with status 'missing' and later when the customer adds a valid IBAN we'll trigger this event with status 'retrieved'

Parameters in the body:

event [String]: the name of the webhook event

customerId [String]: Transaction Connect's customer id

customerExternalId [String]: The client's customer id

status [String]: the status that has been updated possible values: 'missing', 'retrieved'

Example:

{
    "event": "cashback_method_updated",
    "customerId": "c84c33cf-62c6-4a44-8692-973cc0cc420c"
    "customerExternalId": "87316292",
    "status": "missing",
}

This event is triggered when the data provider failed to fetch data from the bank account or when the provider connection is resolved

Parameters in the body:

event [String]: the name of the webhook event

customer: [Object]

id [String]: Transaction Connect's customer id

externalId [String]: The client's customer id

connectionsOn [Number]: The number of customer's active bank connections

connectionsOff [Number]: The number of customer's bank connections in error, described in connectionsInError

connectionsInError: [Array]

id [String]: the bank connection id

errorCode [String]: the error code from the data provider

errorMessage [String]: the error message from the data provider

bank [String]: the bank name of the bank connection

{
    "event": "bank_connections_update",
  "customer": {
    "id": "398f0b39-c205-4fb2-a225-70e042df3fdb",
    "externalId": "4564564564654",
    "connectionsOn": 0,
    "connectionsOff": 1
  },
  "connectionsInError": [
    {
      "id": "fea86a6e-48e4-4b20-b07a-3e957f012fb6",
      "errorCode": "invalidCredentials",
      "errorMessage": "Invalid User",
      "bank": "Boursorama"
    }
  ]
}

This event is triggered when a cashback request is updated. A cashback can have different statutes (two intermediate statuses and two final statuses):

Intermediate statuses:

'SUCCEDEED': the cashback request has been successfully accepted from the cashback provider partner

'FAILED': the cashback provider partner has refused the cashback request

Final statuses:

'RECEIVED': the customer has received the cashback

'REJECTED': the cashback request has been rejected

Parameters in the array in the body:

event [String]: the name of the webhook event

cashbacks: [Array]

transferId [String]: the transfer id of the cashback

status [String]: the status of the cashback. possible values: 'SUCCEDEED', 'FAILED', 'RECEIVED', 'REJECTED'

Example:

{
    "event": "cashback_updated",
    "cashbacks":
    [
        {
            "transferId": "8494514",
            "status": "RECEIVED"
        }
    ]
}

bank operations