Shopping Hubs API (3.0)

Download OpenAPI specification:Download

Introduction

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

Access to the API

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

Environment Base URL for REST Endpoints
Production https://api.transactionconnect.com
Sandbox https://api-test.transactionconnect.com

Signature

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

  1. 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

  1. 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

Web UI integration

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

Onboarding your user to the program

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)*

http://cdn.transactionconnect.com/img/doc/select-type.png

http://cdn.transactionconnect.com/img/doc/select-bank.png

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

Make the user add a cashback method

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)

http://cdn.transactionconnect.com/img/doc/cashback.png

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

Make the user visualize/update his cashback method

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*

http://cdn.transactionconnect.com/img/doc/profil.png

http://cdn.transactionconnect.com/img/doc/addIban.png

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

User activities page (transactions, rewards, scan, claims)

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)*

http://cdn.transactionconnect.com/img/doc/activities.png

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

User connections management page

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)*

http://cdn.transactionconnect.com/img/doc/connections.png

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

Webhooks

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.

customer_subscription

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"
}

customer_transactions

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"
            }
        }
    ]
}

receipt_updated

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"
}

cashback_method_updated

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",
}

bank_connections_update

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"
    }
  ]
}

cashbacks_updated

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"
        }
    ]
}

Authentication

apiKey

Api key to use TC API (provided to you by email)

Security Scheme Type API Key
Header parameter name: Api-Key

JWT

Access token required to access API, except for registration (value: Bearer XXX where XXX=token value)

Security Scheme Type API Key
Header parameter name: Authorization

signature

Signature header to authenticate through API as a service (see Introduction)

Security Scheme Type API Key
Header parameter name: Signature

bank

bank operations

getBanks

get bank list

Authorizations:
query Parameters
cardType
string
Enum: "bank" "restaurant"

type of card associated to this bank (bank vs restaurant )

Responses

200

Success

400

Bad request

403

Forbidden access

500

Server error

get/banks
https://api-test.transactionconnect.com/banks

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "application/json":
    [
    ]
}

getTestAccountsByProviderCode

get the test accounts

Authorizations:
path Parameters
code
required
string

the provider code

Responses

200

Success

400

Bad request

403

Forbidden access

500

Server error

get/getTestAccountsByProviderCode/{code}
https://api-test.transactionconnect.com/getTestAccountsByProviderCode/{code}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{ }

getBankById

get info about a bank, based on its id

Authorizations:
path Parameters
bankId
required
string

bank identifier (found in GET /banks)

header Parameters
redirectURI
string

the URI where to redirect to when bank is of type 'PSD2'

customerId
string

id of the customer (will be used to create a customer in the provider )

psuId
string

psuId which is the identification number of the user

chosenAuthModel
string

the chosen authentication model which is redirect or decoupled

Responses

200

Success

400

Bad request

403

Forbidden access

500

Server error

get/banks/{bankId}
https://api-test.transactionconnect.com/banks/{bankId}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "application/json":
    [