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

You can access the Spaycial 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

Sending data to Shopping Hubs API

On Shopping Hubs API, some requests need to be signed by providing Signature headers (see the section below).

To be able to sign requests, you should provide dedicated public keys for both the staging and live environment of the API (see "RSA keys generation instruction" section). Those keys should be emailed to tech@spaycial.com.

The private key should be securely stored on your server.

In case of a 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 using +1 minutes 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: brew install openssl

Windows Windows complete package .exe installer

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@spaycial.com

Receiving data from Shopping Hubs API

On Shopping Hubs API, Spaycial needs to push data to your system to inform you about different events (see the Webhooks section for the list of the events).

Request format

There are several common points about the request we send to the push URLs provided:

• The Content-Type header is application/json;
• There are signature headers that identify the request was signed by Shopping Hubs API (see next section);
• The request method is always POST;

Signature headers

The following headers are sent in the request to allow you to verify that the request is coming from Shopping Hubs API:

• Expires-at - request expiration time as a UNIX timestamp in UTC timezone. We suggest to use +1 minute from the current time.
• Signature - base64 encoded SHA256 signature of the string represented in the form Expires-at|push_url|post_body| - 3 parameters concatenated with a vertical bar |, signed with the Shopping Hubs APIS’s private key.

The pseudocode to generate the signature looks like this: base64(sha256_signature(private_key, "Expires-at|push_url|post_body|"))).

The fields push_url, and post_body from the Signature header represent:

• push_url - the full URL where data is pushed;
• post_body - the request post body.

You should use the following public key to verify the signature:

• in Sandbox:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwfc/T2Pv+ua5pUBqtVdK
+mtl7dphlPuI3jtYifTCEIhahNN8ZFtJwcYeuKwZxcFowO2zL/YQ4468Jj9jdKgb
A4JBOyWELHRawt9opTGuHEzyrl4VHG27bKrFYfOJwsyMEUjKSCxeRr173qkhIolr
MWnqgCtydBsnFZocghbWknoupl+aAEgesmLteHFNvfoQAeoJJLOvpA2ieQvLiTWE
h+oaSPuLN+ftRgUIY6DrAOOQFBtMtcVY2p6ZR27R1TgHr2YMWKxB/DUNVmaUsW/t
MVf+QOkmPLwKOrz/HjyZNLqh+vhmrsrc97dyImmnd1yjuciFtNzMwCmTO8lQ94uk
FwIDAQAB
-----END PUBLIC KEY-----

• in Production:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvXYksIu868s8b+KPwisC
UjEozQQTpQeQzaIqhDFB32htYPQJSjmZ8zoKHcInbmrunglRgtqxB5c0KxzjdUjZ
9U3hXk7MsJPKxcpFyWll8frDuMhvxK9Ly+OGqLdQSwQjjkf65fsKSyuKCUM5ww7S
V3mH4uili4p9+61ctGbtYQiqUJls8No/YAZBjSpgm7KZFK7ILYaFb03KeHxF4qv1
7Wdk002hH2UCZ62faLA9mX34safBNzC5fjAc7VXKRt+3TSzPcjLrHnbYnDzH3Diu
q5sHDtuiwVvGonzDe2wKWgAAnugSAGFyPHsfX36cGq1KwA4ivwVX2lDsl5uOLkkU
KwIDAQAB
-----END PUBLIC KEY-----

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

• POST string example: 1522249849|https://www.api.yourdomain.com/customer_subscription|"{"event": "customer_subscription", "customerExternalId: "123456", "status": "creation", "customerId": "c84c33cf-62c6-4a44-8692-973cc0cc420c", "credentialsPreviouslyUsed": false,"registrationDate": "2020-07-13T11:34:41+01:00", "dataProviderType": "bank","shoppingHubId": "f24b4d97-8d70-4133-b685-732c69b87884","shoppingHubExternalId": "3142"}"|

• Headers example:

{
    "Expires-at": "1522249849",
    "Signature": "0o7LgMnlG7FX5tWLoKd6V5jlktodP8I/3vWqh1pOZvPgMn/WPq5YqZWPc0teey135RO2muFThcvuZJtcbaUje1UWFHyWhTh89guHJ47pgBB7w0LMkRw3XskEsafEUZketeTY/NtyeU7ETHHm2Tlw8IJho+gk51Rtp7JJPanw2OZG/6BElFcL0qGs4ohTmJUKKsdI1eo5jseFqF+sX0T4dRYqL7ebhDCD8YsYdsZ9zxlX88+YtUQnEqGbswOH4saGaQNH9NjxST2NS8MFtCU7uwZGybBk4i0l1wtbTJwfgaa+yb2L7l0ltIgxZFJzQOShpVOgI+o8fUg31lOblmMVkpyvXJ/n5Ed2u0nA1yMWkQUPpu03Xkh2RG7qbBOEq6+A374OnhUDwi5TUqYrY89paPwq/A7z2lc56Q84T+NrSLdi0x0aejpp6Cn90Yqpbs04dIio579+KyLm/8XoZ4p9k7vz6vTpDITyTAc93/KHnqeT1hTp7AWMaxuGfEI361fyZLDzkSvnHq4QzMkJOKhPELxSji99dm0LCSZpUiUhTTU3G09LvLBCEFLvbGJzxlO7NgqOGVPMlEc4fJqzU/jrTfkodn4DtzaOJghlXynithKIUBAkpNY8QGPOQIMvcbOZfhilm+bjWuYeNpeALvbqY3ONcibHLjc8ItAVMzORSFg=",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

When you integrate our solution, we request that you create and communicate to us a new access token validation end-point.

The aim of this end-point is for us to be able to validate the access token of a given customer in your repository (external token), when you request us to generate a new access token for this customer (see the auth getAccessToken section).

We will send you the customer external token we have received in your request for you to check if it matches the one you would have sent us.

How does it work?

When you send a request to get an access token for a given customer id or customer external id (see the auth getAccessToken section), before generating the customer's access token, we need to validate the customer's external token.

In order to proceed with this verification, we will send a GET request to the end-point you provided with the following headers parameters:

• Expires-at - request expiration time as a UNIX timestamp in UTC timezone. We use +1 minute from the current time.
• Signature - base64 encoded SHA256 signature of the string represented in the form x-access-token|Api-Key|Expires-at| - 3 parameters concatenated with a vertical bar |, signed with the Spaycial’s private key.
• Content-Type - application/json.
• Accept - application/json.
• x-access-token - the customer access token in your repository.
• Api-Key - API key to use Spaycial API.
• customerExternalId - the customer external id.

If the customer's external token is validated (meaning we get a successful response from your end-point), we will generate a new access token for this customer. Otherwise, we will return an error.

Examples

Validation end-point to be provided to us

https://www.api.yourdomain.com/mymall/tc-endpoint

Headers to be received by your end-point

{
    ...
    “expires-at”: “1623406378",
    “signature”: “iv2MYg/u94gKX1qgSS2+m0KJwYGUNAiMh4kXs2KzrtczdrCiby4nj8+b/Lmk5VP/BKkU71VKE0vyiskjif6XFzlhgTun4IIPCHBmVMmfzWt4U19h01Zs18YVxqDX3fGMj6sdOLES7qarMMxdcD1fS8MilFOZTeBj/eoLpArHL3cAHQ/snu2yidGG+3A3JX77Rrp947ZR+joO5cDFn6qTkSeaxDof2oWNJLDR8dzM8OystbDOhSU2HIe4BokC5mBYreT2lKTH5KOpw9Nz4LP9yaHHwnyo/X0PA9l6u7ZyknnQtlTFh9wIQyOIgDJsPiuvW3z6xfvwj9JsWrOsMxcwWQ==“,
    “content-type”: “application/json”,
    “accept”: “application/json”,
    “x-access-token”: “123456789",
    “api-key”: “17fe12345cc783a16b2070b1eaa382dki”
}

Here are some sequence diagrams simplified for helping the implementation. Hyperlinks to the documentation of mentioned APIs are provided where possible, make sure to read the associated doc.

In this diagram you have a general overview of the user subscription flow.

Once a customer is subscribed he can access different views to visualize his data and perform some actions (you can take a look to the [Web Ui Integration] (#section/Web-UI-integration)). To do this you have to first fetch a valid Spaycial JWT token and have exposed the [validation endpoint]

(#section/Introduction/Creating-a-validation-end-point-to-verify-your-user's-external-access-token)

To receive data from our servers in real time you can use webhooks that you can set up autonomously via the webhook API

Here is an example of the lifecycle of a cashback.

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

technical information(url access), these fields are available on all following steps:

your-loyalty-domain - your domain url that we gave to you

lng - [optional] The language to be shown in a two letters format (ex. 'fr') the language of your shopping hub is always available, list of languages code https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes?oldid=133943906

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/?mid=[your_mall_id]&cid=[your_customer_id]&cb=[your_callback_url]&lng=[language]&ted=[transactions_eligible_from_date]

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

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

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

ted - [optional] A unix timestamp (in seconds) between today and past 90 days to allow eligible transactions before the system registration date

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

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

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]

If a transaction was not taken into account by our system, the user can make a claim by filling out a form within his/her customer area. This form contains information about the purchase, including an attachment to provide the receipt as proof of the purchase. The claim will then be studied by the Spaycial team. If the claim is relevant, it will be validated, you’ll get a “validated” notification via the claim_update webhook, and the purchase will be sent in the next customer_transactions webhook notification. If the claim is not relevant, it will be rejected, and you’ll get a “rejected” notification via the claim_update webhook.

technical information(url access)

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

your_callback_url - the url to redirect the user once the user made the claim

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]

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 definitive confirmation of a status update and are used for a variety of purposes, such as notifying an onboarding, notifying some new transactions that happened in the hub, and notifying a change in the status of a customer connection.

When the event you subscribed to 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.

You can authenticate Spaycial as the author of webhook events thanks to a signature system (see the Receiving data from Shopping Hubs API part of the Signature section).

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

When the system makes a POST call to your webhook subscription it will check the response and schedule a retry if the response has an error code. For example: if your server returns a 500 response status the post will be retried until the response is 200. The systems will try a maximum of 6 times including the first call and after that, it will retry following this schedule: 10 minutes, 1 hour, 24 hours, 48 hours, and 72 hours.

After the 6th attempt, the system will stop retrying and data will be lost.

The POST call from the webhook includes an HTTP header named "AttemptNumber" which starts from 0 and identifies the retries made before this call.

Lastly, you can test some of those webhooks using a POST call on /admin/webhook/[camelCaseWebhookName], see below for more information.

This event is triggered when a customer is created in the Spaycial system. It means the customer has started a registration process.

Parameters in the body:

event [String]: the name of the webhook event, here "customer_creation"

customerExternalId [String]: the customer external identifier (identifier of the customer in the client repository)

customerId [String]: Spaycial customer id

shoppingHubId [String]: Shopping Hub id

shoppingHubExternalId [String]: Shopping Hub External Id

Example:

{
    "event": "customer_creation",
    "customerExternalId: "4354213424",
    "customerId": "b84c33cf-62c6-4a44-8692-973cc0cc420c",
    "shoppingHubId": "f24b4d97-8d70-4133-b685-932c69b87114",
    "shoppingHubExternalId": "341451",
}

This event is triggered when a change occurs on a customer subscription.

Parameters in the body:

event [String]: the name of the webhook event

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

status [String]: The new status of the customer subscription. The possible values are: 'creation', 'deletion', 'update'. 'creation' means the customer has completed the registration process by linkin his/her payment method. 'deletion' means the customer has been deleted from our system. 'update' means the customer has linked a new payment method to our system.

customerId [String]: Spaycial customer id

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

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

transactionsEligibleFromDate [String]: Start date from where transactions will be pushed

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

shoppingHubId [String]: Shopping Hub id

shoppingHubExternalId [String]: Shopping Hub External Id

Example:

{
    "event": "customer_subscription",
    "customerExternalId: "43213424",
    "status": "creation"
    "customerId": "c84c33cf-62c6-4a44-8692-973cc0cc420c",
    "credentialsPreviouslyUsed": false,
    "registrationDate": "2020-07-13T11:34:41+01:00",
    "transactionsEligibleFromDate": "2020-07-13T11:34:41+01:00",
    "dataProviderType": "bank",
    "shoppingHubId": "f24b4d97-8d70-4133-b685-732c69b87884",
    "shoppingHubExternalId": "654564561",
}

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

purchaseDate [String]: the date of the transaction

dateBankingStatement [String]: the date of the banking statement

customerId [String]: Spaycial's customer id

customerExternalId [String]: The client's customer id

purchaseLocation: [Object]

id: The Spaycial's id of the purchase location

externalId: The external id of the purchase location

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

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

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

timeOfPurchase [String]: the date and time of the transaction (only provided when dataProviderType='scan', meaning for transactions coming from receipt's scan feature)

receiptId [String]: the receipt id linked to this transaction

shoppingHubId [String]: Shopping Hub id

shoppingHubExternalId [String]: Shopping Hub External Id

Example:

{
    "event": "customer_transactions",
    "transactions": [
        {
            "id": "c84c33cf-62c6-4a44-8692-973cc0cc420c",
            "amount": -10.53,
            "currency": "EUR",
            "purchaseDate": "2023-01-12",
            "dateBankingStatement": "2023-01-15",
            "customerId": "8148b7f5-fcd4-4818-aefa-5450e7dd5dad",
            "customerExternalId": "87316292",
            "purchaseLocation": {
                "id": "6a6a578b-662b-4673-8885-e00902a34dd4",
                "externalId": "18289377",
                "type": "store"
            },
            "dataProviderType": "bank",
            "receiptId": null,
            "timeOfPurchase": null
        },
        {
            "id": "e1f5316f-877a-4ea3-92ce-63b99c8a5aae",
            "amount": -24.17,
            "currency": "EUR",
            "purchaseDate": "2023-01-15",
            "dateBankingStatement": "2023-01-18",
            "customerId": "8148b7f5-fcd4-4818-aefa-5450e7dd5dad",
            "customerExternalId": "87316292",
            "purchaseLocation": {
                "id": "f4de5a19-5a36-4227-a2ac-a543a1902964",
                "externalId": "18289514",
                "type": "store"
            },
            "dataProviderType": "scan",
            "receiptId": "9bb59173-5510-4b11-a783-71c83c3b6564",
            "timeOfPurchase": "2023-01-15 13:09:00.000000 +00:00"
        }
    ],
  "shoppingHubId": "f24b4d97-8d70-4133-b685-732c69b87884",
  "shoppingHubExternalId": "654564561"
}

This event is triggered when a receipt status 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'

customerId [String]: Spaycial's customer id

customerExternalId [String]: the customer external identifier (identifier of the customer in the client repository)

shoppingHubId [String]: Shopping Hub id

shoppingHubExternalId [String]: Shopping Hub External Id

rejectionReason [String]: the rejection reason has possible values: 'beforeRegistration', 'duplicate', 'incomplete', 'notATicket', 'outOfMall', 'notInClientReferential', 'unknown', null

Example:

{
    "event": "receipt_updated",
    "receiptId": "d7d4bad0-f7c0-4427-9305-fa5c9394e211",
    "status": "rejected",
    "customerId": "c84c33cf-62c6-4a44-8692-973cc0cc420c",
    "customerExternalId": "87316292",
    "shoppingHubId": "f24b4d97-8d70-4133-b685-732c69b87884",
    "shoppingHubExternalId": "654564561",
    "rejectionReason": "incomplete"
}

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]: Spaycial's customer id

customerExternalId [String]: The client's customer id

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

shoppingHubId [String]: Shopping Hub id

shoppingHubExternalId [String]: Shopping Hub External Id

Example:

{
    "event": "cahsback_method_updated",
    "customerId": "c84c33cf-62c6-4a44-8692-973cc0cc420c",
    "customerExternalId": "87316292",
    "status": "missing",
    "shoppingHubId": "f24b4d97-8d70-4133-b685-732c69b87884",
    "shoppingHubExternalId": "654564561",
}

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]: Spaycial'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

shoppingHubId [String]: Shopping Hub id

shoppingHubExternalId [String]: Shopping Hub External Id

{
    "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"
    }
  ],
    "shoppingHubId": "f24b4d97-8d70-4133-b685-732c69b87884",
    "shoppingHubExternalId": "654564561",
}

The bank_connections_update_v2 event is triggered when the bank connection:

• is created
• is desynchronised
• is resynchronised
• is deleted or disabled

Parameters in the body:

event [String]: the name of the webhook event

eventType [String]: type of event between create, update or delete

customer: [Object]

• id [String]: Spaycial'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

• connections: [Array] The list of all connections of the customer

connection [Object] The connection triggering the event

shoppingHubId [String]: Shopping Hub id

shoppingHubExternalId [String]: Shopping Hub External Id

Connection object:

• 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

• transactionsEligibleFromDate [String]: start date for eligibility of transactions on this connection

• consentExpiresAt [String]: end of consent for this connection [optional]

{
  "event": "bank_connections_update_v2",
  "eventType": "update",
  "customer": {
    "id": "398f0b39-c205-4fb2-a225-70e042df3fdb",
    "externalId": "4564564564654",
    "connectionsOn": 1,
    "connectionsOff": 1,
    "connections": [
      {
        "id": "fea86a6e-48e4-4b20-b07a-3e957f012fb6",
        "errorCode": "invalidCredentials",
        "errorMessage": "Invalid User",
        "bank": "Boursorama",
        "transactionsEligibleFromDate": "2021-01-03",
        "consentExpiresAt": "2021-04-15 01:02:03.0004"
      },
      {
        "id": "7f41325e-dbe9-4ea6-8406-a2d45ac694ef",
        "errorCode": null,
        "errorMessage": null,
        "bank": "BNP",
        "transactionsEligibleFromDate": "2021-01-02",
        "consentExpiresAt": "2021-05-01 01:02:03.0004"
      }
    ],
  },
  "connection": {
    "id": "7f41325e-dbe9-4ea6-8406-a2d45ac694ef",
    "errorCode": null,
    "errorMessage": null,
    "bank": "BNP",
    "transactionsEligibleFromDate": "2021-01-02",
    "consentExpiresAt": "2021-05-01 01:02:03.0004"
  },
  "shoppingHubId": "f24b4d97-8d70-4133-b685-732c69b87884",
  "shoppingHubExternalId": "654564561"
}

The bank_association_notification is triggered when a bank has been removed or added to a program.

Parameters in the body

• event [String]: Name of the webhook event described (bank_status_update)
• eventType [String]: Type of the event can be INSERT or DELETE
• bank [Object]: The bank triggering the event

Bank object:

• id [String]: bank id stored in the Spaycial repository

• name [String]: name of the bank

• active [Boolean] Status active to true or false. True means that the end-user can register through this bank. False means that the bank will not be clickable by the end-user

• shoppingHubExternalId [String] Id used by the program

• shoppingHubId [String] ID of the program in the Spaycial repository

{
  "event": "bank_association_notification",
  "eventType": "DELETE",
  "shoppingHubExternalId": "3145",
  "shoppingHubId": "492f0b39-c205-4fb2-a225-70e042df3fdb",
  "bank": {
    "id": "398f0b39-c205-4fb2-a225-70e042df3fdb",
    "name": "Société Générale",
    "active": true,
  }
}

The bank_status_update event is triggered when a bank becomes active or inactive. An active bank means the bank is working properly and the user can connect to it. An inactive bank means that the bank is not working properly. It's still displayed in the bank list but it cannot be selected.

Parameters in the body:

• event [String]: Name of the webhook event described (bank_status_update)
• bank [Object]: The bank triggering the event

Bank object:

• id [String]: bank id stored in the Spaycial repository

• name [String]: name of the bank

• active [Boolean] Status active to true or false

• shoppingHubExternalId [String] Id used by the program

• shoppingHubId [String] ID of the program in the Spaycial repository

{
  "event": "bank_status_update",
  "shoppingHubExternalId": "3145",
  "shoppingHubId": "492f0b39-c205-4fb2-a225-70e042df3fdb",
  "bank": {
    "id": "398f0b39-c205-4fb2-a225-70e042df3fdb",
    "name": "Société Générale",
    "active": true
  }
}

The claim_update event is triggered when the status of a claim has changed. This means that the claim is either:

• rejected
• pending
• validated

Parameters in the body: event [String]: the name of the webhook event (claim_update)

eventType [String]: type of event between pending, validated or rejected

customer: [Object]

• id [String]: Spaycial's customer id

• externalId [String]: The client's customer id

claim: [Object]

• id [String]: the claim identifier

• amount [String]: Amount of the claim

• store [String]: Name of the store

• storeId [String]: ID of the store in the Spaycial repository

• storeExternalId [String]: ID of the store in client's repository

• date [String]: Date when the claim was posted (in ISO 8601 format)

• rejectionReason [String] Rejection reason of the claim if rejected.

• code [String] Code used to defined the rejection reason. Possible values: * TRANSACTION_ALREADY_ASSOCIATED * TRANSACTION_NOT_FOUND * AUTO_REJECTED * DUPLICATED * STORE_OUT_OF_PROGRAM * BEFORE_REGISTRATION * RECEIPT_INCOMPLETE

• status [String] Status of the claim (rejected|pending|validated)

• transactionDate [Date] Date of the transaction, declared by the user (YYYY/MM/DD)

• transactionId [String] ID of the transaction (provided only for validated claims)

{
  event: "claim_update",
  eventType: "rejected",
  customer: {
    id: "398f0b39-c205-4fb2-a225-70e042df3fdb",
    externalId: "4564564564654",
  },
  claim: {
    id: "b73dbe2b-b1d6-46f0-8e0c-3ff122de3c62",
    amount: "-12.00",
    store: "ARMAND THIERY",
    storeId: "85536c27-ba78-4c00-ab66-f7c4a7d04faf",
    storeExternalId: "29894111110",
    status: "rejected",
    rejectionReason: "The store is out of program",
    code: "STORE_OUT_OF_PROGRAM",
    date: "2021-10-08T06:50:40.479Z",
    transactionId: null,
    transactionDate: "2021-10-01",
  }
}

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:

'SUCCEEDED': 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]

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

transferId [String]: the transfer id of the cashback

externalId [String]: the cashback external id (an optional reference of the cashback in your system)

customerId [String]: the customer id in the Spaycial system

customerExternalId [String]: the customer id in your system

shoppingHubId [String]: Shopping Hub id

shoppingHubExternalId [String]: Shopping Hub External Id

Example:

{
    "event": "cashbacks_updated",
    "cashbacks":
    [
        {
            "status": "RECEIVED"
            "transferId": "8494514",
            "externalId": "AEF874113C",
        }
    ],
    "customerId": "c84c33cf-62c6-4a44-8692-973cc0cc420c",
    "customerExternalId": "87316292",
    "shoppingHubId": "f24b4d97-8d70-4133-b685-732c69b87884",
    "shoppingHubExternalId": "654564561"
}

This event is triggered after calling POST /shoppingHub/stores and notifies if the store integration was succeeded or failed.

NB: Currently, only one request could be treated at a time per program. If you post a new store list before having the notification of the previous integration, then the previous request will automatically be rejected

Parameters in the body:

event [String]: the name of the webhook event

requestId [String]: the identifier of the request received after calling POST /shoppingHub/stores

result [String]: result of the integration. possible values: 'success', 'failed'

resultDetail [String]: more information regarding the result of the integration.

shoppingHubId [String]: Shopping Hub id

shoppingHubExternalId [String]: Shopping Hub External Id

Examples:

{
    "event": "store_list_updated",
    "requestId": "wp302492039482039482",
    "result": "success",
    "shoppingHubId": "f24b4d97-8d70-4133-b685-732c69b87884",
    "shoppingHubExternalId": "654564561"
}

{
    "event": "store_list_updated",
    "requestId": "wp302492039482039482",
    "result": "failed",
    "resultDetail": "Only one request can be treated at a time, we'll integrate only the most recent"
    "shoppingHubId": "f24b4d97-8d70-4133-b685-732c69b87884",
    "shoppingHubExternalId": "654564561"
}

This event is triggered when an offer of the loyalty program is created or updated.

Parameters in the body: event [String]: the name of the webhook event (offer_updated)

shoppingHubId [String]: Shopping Hub identifier

shoppingHubExternalId [String]: Shopping Hub External identifier

offer: [Object]

• id [String]: the offer identifier

• status [String] status of the offer (created|updated)

• startDate [Date] challenge start date-time, in full-date format of RFC3339

• endDate [Date] challenge end date-time, in full-date format of RFC3339

• name [String] offer's name

• teaser [String] offer's teaser

• rewardType [String] offer's reward type, meaning what type of benefit you'll get when unlocking this offer (LTRY|RFND|GIFT_CARD) (Lottery, Refund in cashback, Gift card)

• offerType [String] offer's type, meaning what kind of purchase trigger is searched for the shoppers (welcome|frequency|referral|average)

• rewardLabel [String] offer's reward description

• rewardValue [String] offer's reward value

• conditionLabel [String] condition to complete the offer (label)

• conditionValue [String] condition to complete the offer (value)

• active [Boolean] true if the offer is active, false otherwise

{
  "event": "offer_updated",
  "shoppingHubExternalId": "90890289082",
  "shoppingHubId": "492f0b39-c205-4fb2-a225-70e042df3fdb",
  "offer": {
    "id": "4f284506-f8e8-486a-994a-2fa0f62838e5",
    "status": "created",
    "startDate": "2023-05-31T22:00:00.000Z",
    "endDate": "2023-06-30T22:00:00.000Z",
    "name": "June 2023 offer",
    "teaser": "Offre du mois de juin",
    "offerType": "frequency",
    "rewardType": "RFND",
    "rewardLabel": "10 €",
    "rewardValue": "10.00",
    "conditionLabel": "Recevez 10€ pour 80€ d'achats cumulés",
    "conditionValue": "80.00",
    "active": true
  }
}

This event is triggered when a member is doing progress on a loyalty program's offer, which will potentially lead to a reward. A reward can have different statuses:

• 'started': the member has made a first purchase eligible for a particular offer
• 'pending': the member has made another purchase eligible for a particular offer
• 'completed': the member has completed a particular offer
• 'refunded': a benefit has been emitted for this reward (most often a cashback)

Parameters in the body: event [String]: the name of the webhook event (reward_updated)

shoppingHubId [String]: Shopping Hub identifier

shoppingHubExternalId [String]: Shopping Hub External Identifier

customer: [Object]

• id [String]: Spaycial's member id

• externalId [String]: The client's member id

reward: [Object]

• id [String]: the reward identifier

• status [String] status of the reward (started|pending|completed|refunded)

• offerId [String] the identifier of the offer (aka challenge) associated to this reward

offer: [Object]

• id [String]: the offer identifier

• startDate [Date] challenge start date-time, in full-date format of RFC3339

• endDate [Date] challenge end date-time, in full-date format of RFC3339

• name [String] offer's name

• teaser [String] offer's teaser

• rewardType [String] offer's reward type, meaning what type of benefit you'll get when unlocking this offer (LTRY|RFND|GIFT_CARD) (Lottery, Refund in cashback, Gift card)

• offerType [String] offer's type, meaning what kind of purchase trigger is searched for the shoppers (welcome|frequency|referral|average)

• rewardLabel [String] offer's reward description

• rewardValue [String] offer's reward value

• conditionLabel [String] condition to complete the offer (label)

• conditionValue [String] condition to complete the offer (value)

{
  "event": "reward_updated",
  "shoppingHubExternalId": "90890289082",
  "shoppingHubId": "492f0b39-c205-4fb2-a225-70e042df3fdb",
  "customer": {
    "id": "41278549-d17e-49d2-be12-772bc5425892",
    "externalId": "0f3ff415-bfc7-423b-9d5a-1caea428c920"
  },
  "reward": {
    "id": "163284cd-af07-43ed-9178-257a44ae2474",
    "status": "pending",
    "offerId": "4f284506-f8e8-486a-994a-2fa0f62838e5"
  },
  "offer": {
      "id": "4f284506-f8e8-486a-994a-2fa0f62838e5",
      "status": "created",
      "startDate": "2023-05-31T22:00:00.000Z",
      "endDate": "2023-06-30T22:00:00.000Z",
      "name": "June 2023 offer",
      "teaser": "Offre du mois de juin",
      "offerType": "frequency",
      "rewardType": "RFND",
      "rewardLabel": "10 €",
      "rewardValue": "10.00",
      "conditionLabel": "Recevez 10€ pour 80€ d'achats cumulés",
      "conditionValue": "80.00",
    }
}

bank operations

authentication operations

customer related services