Spaycial REST API (3.2.0)

Download OpenAPI specification:Download

Introduction

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

Access to the API

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

Signature

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

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

Creating a validation end-point to verify your user's external access token

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

Sequence Diagrams

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.

User Subscription Flow

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

This browser does not support PDFs. Please download the PDF to view it: Download User Subscription Flow PDF.

Authenticated Action 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)

This browser does not support PDFs. Please download the PDF to view it: Download Authenticated Action Flow PDF.

Webhooks lifecycle

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

This browser does not support PDFs. Please download the PDF to view it: Download Webhooks lifecycle PDF.

Cashback Flow

Here is an example of the lifecycle of a cashback.

This browser does not support PDFs. Please download the PDF to view it: Download Cashback Flow PDF.

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

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

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

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

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) in the past to allow eligible transactions before the system registration date

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)

https://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

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*

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

https://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

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

https://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]

Make the user add a claim

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.

https://cdn.transactionconnect.com/img/doc/claim_img.png

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

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

https://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]

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

customer_creation

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

customer_subscription

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

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

purchaseDate [String]: the date of the transaction

dateBankingStatement [String]: the date of the banking statement, null for non bank transactions or if not provided by the bank

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 origin of the transaction: 'bank' for an open banking transaction, 'restaurant' for restaurant card providers, 'scan' for receipt scan, 'support'

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

receipt_updated

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

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

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

bank_connections_update_v2

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

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

bank_association_notification

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

bank_status_update

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

claim_update

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

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:

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

store_list_updated

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

offer_updated

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

reward_updated

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

bank operations

getBanks

get bank list

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

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

Responses

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

getBankById

get info about a bank, based on its id

Authorizations:
apiKey
path Parameters
bankId
required
string

bank identifier (found in GET /banks)

header Parameters
locale
string

for some banks, a locale can be provided to define the bank portal language

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

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

auth

authentication operations

getOptins

get optins list

Authorizations:
apiKey
query Parameters
lng
string

country code (2 letters) used to filter bank list by country

registrationType
string
Enum: "restaurant" "receipt" "CLO" "PSD2" "SCR" "COM"

type of customer registration, default 'SCR' (optins depend on registation type)

Responses

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

postRegistration

register to Spaycial using an identifier (mobile phone, email, external id, ...)

Authorizations:
apiKey
Request Body schema: application/json

body containing registration info

phoneNumber
string

phone number, without any prefix

countryCode
integer

phone country code (i.e. 33 for France)

captcha
string

google recaptcha code to avoid bot registration

origin
string
Enum: "email" "iOS-app" "Android-app" "website" "desk"

customer origin

referer
string

customer referer, a string identifying previous page visited before registering

customerExternalId
string

customer identifier in shopping hub repository

firstName
string

customer's first name

lastName
string

customer's last name

familyStatus
string
Enum: "singleWithoutChildren" "singleWithChildren" "marriedWithoutChildren" "marriedWithChildren"

Family situation of the customer

  • singleWithoutChildren - single customer without children
  • singleWithChildren - single customer with children
  • marriedWithoutChildren - married customer without children
  • marriedWithChildren - married customer without children
postalCode
string

The postal code of the address - can be alphanumeric, dashes or spaces

email
string

email of the customer

Array of objects (Array)
outsideOptIn
boolean

true if customer accepts its out of mall transactions to be analyzed, false otherwhise

object (ReferralInfo)

referral information to get referral offer

preferredLanguage
string

customer preferred language for communication (email, sms...) - ISO 639-1 format is expected (i.e. fr-FR or en)

transactionsEligibleFromDate
number

Unix Timestamp (in seconds) representing the start date from where the customer's transactions will be pushed. If not provided, it will default to the customer's registrationDate

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string",
  • "countryCode": 0,
  • "captcha": "string",
  • "origin": "email",
  • "referer": "string",
  • "customerExternalId": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "familyStatus": "singleWithoutChildren",
  • "postalCode": "string",
  • "email": "string",
  • "optins": [
    ],
  • "outsideOptIn": true,
  • "referralInfo": {
    },
  • "preferredLanguage": "string",
  • "transactionsEligibleFromDate": 0
}

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

postFirstReceipt

Allows a customer to register by uploading a receipt

Authorizations:
registrationJWT
Request Body schema: multipart/form-data
image
string <binary>

Image of the receipt to upload

customerId
required
string

Customer identifier

optins
required
string

Stringified optins JSON object which contains array of optins objects with string code and boolean value

Responses

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

postBankConnectionCallback

Add a first bank connection to customer by providing bank website callback code

Authorizations:
(apiKeyregistrationJWT)
Request Body schema: application/json

body containing connection info

customerId
required
string

customer identifier get from /auth/register response

bankId
string or null

identifier of the bank to connect with (found in GET /banks)

dataProviderConnectionId
string or null

identifier of the bank connection in data provider repository (found in GET /banks)

queryString
object

object containing the temp code retrieved from psd2 callback login and the customer_id

redirectUri
string

the URI where to redirect to

Responses

Request samples

Content type
application/json
{
  • "customerId": "string",
  • "bankId": "string",
  • "dataProviderConnectionId": "string",
  • "queryString": { },
  • "redirectUri": "string"
}

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

getAccessToken

Get an access token for the given customerId or customerExternalId.

Please note that before generating the access token, we need to verify your customer's external token (see here for detailed information on how we proceed)

Authorizations:
(apiKeysignature)
header Parameters
customerId
string

customer identifier get from /auth/register response

customerExternalId
string

the customer external id

x-access-token
required
string

the customer access token in mall repository

Expires-at
integer

request expiration time as a UNIX timestamp in UTC timezone. We suggest to use +1 minute from the current time.

Responses

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

postLogin

login to Spaycial using mobile phone and password

Authorizations:
apiKey
Request Body schema: application/json

the body containing login info

phoneNumber
string

phone number, without any prefix

countryCode
integer

phone country code (i.e. 33 for France)

email
string

customer's email

password
required
string

customer's area password

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string",
  • "countryCode": 0,
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

getPasswordEmailConfirmation

get an email containing a URL to confirm the password creation request

Authorizations:
apiKey
header Parameters
email
required
string

customer's email

Responses

Response samples

Content type
application/json
{
  • "code": "emailNotFound",
  • "message": "string"
}

getTemporaryCode

get an SMS temporary code to confirm customer identity

Authorizations:
apiKey
header Parameters
phoneNumber
required
string

phone number, without any prefix

countryCode
required
integer

phone country code (i.e. 33 for France)

Responses

Response samples

Content type
application/json
{
  • "code": "unknownPhone",
  • "message": "string"
}

postTemporaryCode

post the temporary code received via SMS to confirm identity

Authorizations:
apiKey
Request Body schema: application/json

the body containing code information

phoneNumber
required
string

phone number, without any prefix

countryCode
required
integer

phone country code (i.e. 33 for France)

temporaryCode
required
string

temporary code, received by SMS

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string",
  • "countryCode": 0,
  • "temporaryCode": "string"
}

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

verifyDecoupledConnection

verify the status of a decoupledConnection and retrieve the oauthcallback uri

Authorizations:
apiKey
Request Body schema: application/json

body containing decouple connection info

required
object

object containing the decoupledDetails sent from the server to be used for the polling (the specified properties differ depending on the data provider)

Responses

Request samples

Content type
application/json
{
  • "decoupledDetails": {
    }
}

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

customer

customer related services

postFirstReceipt

Allows a customer to register by uploading a receipt

Authorizations:
registrationJWT
Request Body schema: multipart/form-data
image
string <binary>

Image of the receipt to upload

customerId
required
string

Customer identifier

optins
required
string

Stringified optins JSON object which contains array of optins objects with string code and boolean value

Responses

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

getCustomer

Get current customer information (deduced from header token)

Authorizations:
JWT

Responses

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

patchCustomer

update current customer

Authorizations:
(apiKeyJWT)
Request Body schema: application/json
firstName
string

customer's first name

lastName
string

customer's last name

email
string

customer's email

phoneNumber
string

phone number, without any prefix

countryCode
integer

phone country code (i.e. 33 for France)

password
string

customer's password

outsideOptIn
boolean

true if customer accepts its out of mall transactions to be analyzed, false otherwhise

preferredLanguage
string

customer preferred language for communication (email, sms...) - ISO 639-1 format is expected (i.e. fr-FR or en)

postalCode
string

The postal code of the customer

familyStatus
string
Enum: "singleWithoutChildren" "singleWithChildren" "marriedWithoutChildren" "marriedWithChildren"

Family situation of the customer

  • singleWithoutChildren - single customer without children
  • singleWithChildren - single customer with children
  • marriedWithoutChildren - married customer without children
  • marriedWithChildren - married customer without children

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "phoneNumber": "string",
  • "countryCode": 0,
  • "password": "string",
  • "outsideOptIn": true,
  • "preferredLanguage": "string",
  • "postalCode": "string",
  • "familyStatus": "singleWithoutChildren"
}

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

deleteCustomer

Delete current customer in the Spaycial repository (deduced from header token)

Authorizations:
(apiKeyJWT)

Responses

Response samples

Content type
application/json
{
  • "code": "expiredToken",
  • "message": "string"
}

changeCustomerPassword

update current customer password

Authorizations:
(apiKeyJWT)
Request Body schema: application/json

The user data.

currentPassword
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "currentPassword": "string",
  • "password": "string"
}

getCloConnections

Returns customer's CLO connections list

Authorizations:
(apiKeyJWT)

Responses

Response samples

Content type
application/json
{
  • "customerId": "string",
  • "connections": [
    ]
}

addCreditCardConnection

add a credit card connection providing checkout credit card token

Authorizations:
(apiKeyJWT)
Request Body schema: application/json

body containing connection info

creditCardToken
required
string

credit card token (issued by Checkout tokenization)

Responses

Request samples

Content type
application/json
{
  • "creditCardToken": "string"
}

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

deleteConnection

delete a connection of any type

Authorizations:
(apiKeyJWT)
path Parameters
connectionId
required
string

the connection id (either a bank connection id or a credit card id)

Responses

Response samples

Content type
application/json
{
  • "code": "invalidConnectionId",
  • "message": "string"
}

getAllCustomerConnections

Returns customer's bank

Authorizations:
(apiKeyJWT)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getBankConnections

Returns customer's bank connections list

Authorizations:
(apiKeyJWT)

Responses

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

addBankConnectionCallback

add a bank connection to customer by providing bank website callback code

Authorizations:
(apiKeyJWT)
Request Body schema: application/json

body containing connection info

bankId
string or null

identifier of the bank to connect with (found in GET /banks)

queryString
required
object

object containing the temp code retrieved from psd2 callback login and the customer_id

redirectUri
string

the URI where to redirect to

Responses

Request samples

Content type
application/json
{
  • "bankId": "string",
  • "queryString": { },
  • "redirectUri": "string"
}

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

updateBankConnection

update a bank connection by providing bank website credentials

Authorizations:
(apiKeyJWT)
path Parameters
connectionId
required
string

the connection id

Request Body schema: application/json

body containing connection info

credentials
object

object containing bank credentials

redirectUri
string

the URI where to redirect to

locale
string

for some banks, a locale can be provided to define the bank portal language

psuId
string

psuId which is the identification number of the user

chosenAuthModel
string

the chosen authentication model which is redirect or decoupled

Responses

Request samples

Content type
application/json
{
  • "credentials": { },
  • "redirectUri": "string",
  • "locale": "string",
  • "psuId": "string",
  • "chosenAuthModel": "string"
}

Response samples

Content type
application/json
{
  • "code": "invalidConnectionId",
  • "message": "string"
}

deleteBankConnection

delete a bank connection

Authorizations:
(apiKeyJWT)
path Parameters
connectionId
required
string

the connection id

Responses

Response samples

Content type
application/json
{
  • "code": "invalidConnectionId",
  • "message": "string"
}

updateBankConnectionCallback

update bank connection callback

Authorizations:
(apiKeyJWT)
path Parameters
connectionId
required
string

the connection id

Request Body schema: application/json

body containing connection info

queryString
object

object containing the query string from interactive callback

Responses

Request samples

Content type
application/json
{
  • "queryString": { }
}

Response samples

Content type
application/json
{
  • "code": "invalidConnectionId",
  • "message": "string"
}

trackCustomer

Track an action made by a Customer

Authorizations:
apiKey
query Parameters
customerId
required
string

the customer identifier

eventName
required
string

the event name

value
required
string

the event value

Responses

Response samples

Content type
application/json
{
  • "code": "customerNotFound",
  • "message": "string"
}

existsCustomer

Test if a given external identifier match a customer in the Spaycial repository

Authorizations:
apiKey
path Parameters
externalId
required
string

the customer identifier in mall repository

Responses

Response samples

Content type
application/json
{
  • "code": "missingAuthorizationHeader",
  • "message": "string"
}

isRegistered

Test if a given Spaycial identifier matches a registered customer in the Spaycial repository

Authorizations:
apiKey
path Parameters
customerId
required
string

the customer identifier in the Spaycial repository

query Parameters
eventType
required
string
Enum: "exclusive_event" "purchase_discount" "store_opening" "toilets_access"

the event at the origin a call to this endpoint

  • exclusive_event - Check member registration to access to an exclusive event
  • purchase_discount - Check member registration to apply a purchase discount
  • store_opening - Check member registration to access to a new store opening
  • toilets_access - Check member registration to access to the toilets

Responses

Response samples

Content type
application/json
{
  • "code": "missingAuthorizationHeader",
  • "message": "string"
}

referralExists

Test if the given customer info matches a referral customer in the Spaycial database

Authorizations:
apiKey
Request Body schema: application/json

the body containing referral information

referralCode
string

the customer referral code

phoneNumber
string

phone number, without any prefix

countryCode
integer

phone country code (i.e. 33 for France)

Responses

Request samples

Content type
application/json
{
  • "referralCode": "string",
  • "phoneNumber": "string",
  • "countryCode": 0
}

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

postFavoriteAccount

set customer's favorite account used for refunds

Authorizations:
(apiKeyJWT)
Request Body schema: application/json
iban
string

customer favorite bank account to receive refunds (in IBAN format)

sortCode
string

bank account sort code (specific to the UK bank accounts, instead of the IBAN)

accountNumber
string

bank account number (specific to the UK bank accounts, instead of the IBAN)

Responses

Request samples

Content type
application/json
{
  • "iban": "string",
  • "sortCode": "string",
  • "accountNumber": "string"
}

Response samples

Content type
application/json
{
  • "code": "invalidIban",
  • "message": "string"
}

getCustomerFavoriteAccount

set customer's favorite account used for refunds

Authorizations:
(apiKeyJWT)

Responses

Response samples

Content type
application/json
{
  • "IBAN": {
    },
  • "creditCard": {
    },
  • "cashbackFallbackNeeded": true
}

getRewards

Returns customer rewards

Authorizations:
(apiKeyJWT)

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

getStores

Returns all stores where the user did (or did not, depending on parameter) make a transaction

Authorizations:
(apiKeyJWT)
query Parameters
transaction
boolean

a boolean set to true if we need stores where user did make a transaction, or false if we need stores where user have not make a transaction yet

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

getStoresTransactions

Returns all customer transactions related to shopping hub stores

Authorizations:
(apiKeyJWT)
header Parameters
limit
number [ 0 .. 1000 ]
Default: 1000

the maximum number of results to retrieve (default 1000)

offset
number >= 0
Default: 0

the results offset (default 0), used to paginate results

from
string <date>

period start date, in date format of ISO8061

to
string <date>

period end date, in date format of ISO8061, not possible to add a to without from

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getPointsHistory

Returns all customer points history

Authorizations:
(apiKeyJWT)
header Parameters
limit
number [ 0 .. 1000 ]
Default: 1000

the maximum number of results to retrieve (default 1000)

offset
number >= 0
Default: 0

the results offset (default 0), used to paginate results

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getStoreTransactions

Returns all transactions that the user did in the given store

Authorizations:
(apiKeyJWT)
path Parameters
storeId
required
string

the store identifier in mall repository

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

getServicesTransactions

Returns all customer transactions related to shopping hub services

Authorizations:
(apiKeyJWT)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

getServiceTransactions

Returns all transactions that the user did for the given service

Authorizations:
(apiKeyJWT)
path Parameters
serviceId
required
string

the service identifier in mall repository

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

getCustomerComplaints

Returns all customer transactions complaints

Authorizations:
(apiKeyJWT)

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

postTransactionAssignmentComplaint

allows to send a complaint about a transaction assignment issue

Request Body schema: application/json

body containing transaction assignement issue info

storeId
required
string

store identifier

externalId
string

customer external id

amount
required
number <float>

transaction amount

transactionDate
required
string <date>

transaction date of the transaction assignment request

additionalFeedback
string <= 255 characters

additional feeback made by the customer

attachment
string

Attachment file (base64)

Responses

Request samples

Content type
application/json
{
  • "storeId": "string",
  • "externalId": "string",
  • "amount": 0,
  • "transactionDate": "2019-08-24",
  • "additionalFeedback": "string",
  • "attachment": "string"
}

Response samples

Content type
application/json
{
  • "code": "storeNotFound",
  • "message": "string"
}

getCustomerReceipts

get receipts updated by a customer

Authorizations:
(apiKeyJWT)

Responses

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

postReceipt

Allows customer to add a receipt

Authorizations:
(apiKeyJWT)
Request Body schema: multipart/form-data
image
string <binary>

Image of the receipt to upload

Responses

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

updateReceipt

Allows customer to update a receipt

Authorizations:
(apiKeyJWT)
Request Body schema: application/json

body containing receipt id and store id

storeId
required
string

id of the store

receiptId
required
string

id of the receipt

Responses

Request samples

Content type
application/json
{
  • "storeId": "string",
  • "receiptId": "string"
}

Response samples

Content type
application/json
{
  • "code": "invalidStoreId",
  • "message": "string"
}

getCustomerOptins

get optins list validated by the customer

Authorizations:
(apiKeyJWT)
query Parameters
lng
string

country code (2 letters) used to filter bank list by country

Responses

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

updateOptins

update optins value for current customer

Authorizations:
(apiKeyJWT)
Request Body schema: application/json

body containing new optin values

registrationType
string
Default: "SCR"

type of optin's registration (default 'SCR': web scrapping)

required
Array of objects (Optin)

Responses

Request samples

Content type
application/json
{
  • "registrationType": "SCR",
  • "optins": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

patchBankConnection

update a bank connection

Authorizations:
(signatureapiKey)
path Parameters
connectionId
required
string

the connection id to update

Request Body schema: application/json

body containing connection info

simulateInvalidCredentials
boolean

true to simulate an invalidCredentials error on this bank connection, false to do nothing

Responses

Request samples

Content type
application/json
{
  • "simulateInvalidCredentials": true
}

Response samples

Content type
application/json
{
  • "code": "invalidConnectionId",
  • "message": "string"
}

country

operations related to countries

getPhoneCountries

get a list of countries covered by phone communication

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

cashback

operations related to cashback

postCashback

generate a cashback refund for a given customer

Authorizations:
(apiKeysignature)
header Parameters
Expires-at
integer

request expiration time as a UNIX timestamp in UTC timezone. We suggest to use +1 minute from the current time.

Request Body schema: application/json

body containing cahsback info

customerId
string

customer identifier in the Spaycial database

customerExternalId
string

the customer external id

externalId
string

the cashback external id (an optional reference of the cashback in your system)

required
object

information about bank account owner

required
object

information about the transfer to create

Responses

Request samples

Content type
application/json
{
  • "customerId": "string",
  • "customerExternalId": "string",
  • "externalId": "string",
  • "ownerInfo": {
    },
  • "transferInfo": {
    }
}

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

postCashbackList

generate a list of cashback refund

Authorizations:
(apiKeysignature)
header Parameters
Expires-at
integer

request expiration time as a UNIX timestamp in UTC timezone. We suggest to use +1 minute from the current time.

Request Body schema: application/json

body containing an array of cahsbacks info

Array ([ 1 .. 200 ] items)
customerId
string

customer identifier in the Spaycial database

customerExternalId
string

the customer external id

externalId
string

the cashback external id (an optional reference of the cashback in your system)

required
object

information about bank account owner

required
object

information about the transfer to create

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

getPushedCashbacks

Return a list of cashbacks that have been pushed to hub in a given period (30 days max)

Authorizations:
(signatureapiKey)
header Parameters
startDate
required
string <date>

period start date, in full-date format of RFC3339

endDate
required
string <date>

period end date, in full-date format of RFC3339

limit
number

the maximum number of results to retrieve (default 1000)

offset
number

the results offset (default 0), used to paginate results

Responses

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

shoppingHub

shopping hub operations

getShoppingHub

Retrieve a shopping hub based on its external id, customer external id or host (priority is given to customerExternalId)

query Parameters
host
string

Retrieve the shopping hub with the given host.

customerExternalId
string

Retrieve the shopping hub with the given customer external id

externalId
string

Retrieve the shopping hub with the given external id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "shortcut": "string",
  • "hubType": "string",
  • "city": "string",
  • "formattedAddress": "string",
  • "apiKey": "string",
  • "country": "string",
  • "host": "string",
  • "contactEmail": "string",
  • "supportContactEmail": "string",
  • "programName": "string",
  • "mainLanguage": "string",
  • "phoneRequired": true,
  • "emailRequired": true,
  • "customerExternalIdRequired": true,
  • "scanEnable": true,
  • "cardRestaurantEnable": true,
  • "externalId": "string",
  • "recaptchaSiteKey": "string",
  • "googleAnalyticsId": "string",
  • "hotjarId": "string",
  • "zendeskId": "string",
  • "fidelProgramId": "string",
  • "currency": "str",
  • "hasExternalFront": true,
  • "propertyManager": "string",
  • "cookieId": "string",
  • "cookieVersion": "string",
  • "shoppingHubOwner": {
    },
  • "hasWestfield": true,
  • "interface": {
    },
  • "cashbackProvider": "string",
  • "checkoutPublicKey": "string",
  • "programOffer": "string",
  • "scanConditions": "string",
  • "claimMinimumAmount": "string",
  • "rewardType": "CASHBACK",
  • "languages": [
    ],
  • "features": [
    ]
}

getWebhooks

get all the subscribed webhooks

Authorizations:
(apiKeysignature)

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

postWebhook

add a webhook too be posted events onto

Authorizations:
(apiKeysignature)
Request Body schema: application/json

body containing connection info

name
string

an optional webhook name to let the client identify the webhooks

url
required
string

the webhook endpoint to post events

events
required
Array of strings non-empty
Items Enum: "bank_connections_update" "claim_update" "bank_status_update" "bank_association_notification" "bank_connections_update_v2" "customer_creation" "customer_subscription" "customer_transactions" "receipt_updated" "cashback_method_updated" "cashbacks_updated" "store_list_updated" "offer_updated" "reward_updated"
active
boolean
Default: true

weather the webhook is active

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "url": "string",
  • "events": [
    ],
  • "active": true
}

Response samples

Content type
application/json
{
  • "webhookId": "string"
}

patchWebhook

patch an existing webhook

Authorizations:
(apiKeysignature)
Request Body schema: application/json

body containing connection info

webhookId
required
string

the webhookId to patch

name
string

an optional webhook name to let the client identify the webhooks

url
string

the webhook endpoint to post events

events
Array of strings non-empty
Items Enum: "bank_connections_update" "bank_status_update" "bank_association_notification" "bank_connections_update_v2" "customer_creation" "customer_subscription" "customer_transactions" "receipt_updated" "cashback_method_updated" "cashbacks_updated" "store_list_updated" "offer_updated" "reward_updated"
active
boolean
Default: true

weather the webhook is active

Responses

Request samples

Content type
application/json
{
  • "webhookId": "string",
  • "name": "string",
  • "url": "string",
  • "events": [
    ],
  • "active": true
}

Response samples

Content type
application/json
{
  • "webhookId": "string"
}

deleteWebhook

delete a webhook and its associated events

Authorizations:
(apiKeysignature)
path Parameters
webhookId
required
string

the webhookId

Responses

Response samples

Content type
application/json
{
  • "code": "expiredToken",
  • "message": "string"
}

challenges

operations related to challenges

Returns a list of challenges. The challenges are returned in sorted order, with the most recently created challenge appearing first.

Authorizations:
apiKey
query Parameters
current
boolean

If true, only return challenges that are active, if missing, all challenges will be returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieves the details of an existing challenge.

Authorizations:
apiKey
path Parameters
id
required
string

id of the challenge

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "startDate": "2019-08-24T14:15:22Z",
  • "endDate": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "teaser": "string",
  • "rewardType": "string",
  • "rewardLabel": "string",
  • "rewardValue": "string",
  • "conditionLabel": "string",
  • "legalConditionText": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z"
}

transaction

operations related to transactions

getPushedTransactions

Return a list of transactions that have been pushed to hub in a given period (30 days max)

Authorizations:
(signatureapiKey)
header Parameters
startDate
required
string <date>

period start date, in full-date format of RFC3339

endDate
required
string <date>

period end date, in full-date format of RFC3339

limit
number

the maximum number of results to retrieve (default 1000)

offset
number

the results offset (default 0), used to paginate results

Responses

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

admin

storesRecommendation

get store recommendations for a list of customers

Authorizations:
(apiKeysignature)
Request Body schema: application/json
customerList
Array of strings

list of customer ids

Responses

Request samples

Content type
application/json
{
  • "customerList": [
    ]
}

getStoresList

get all stores with for a given shoppingHub

Authorizations:
(apiKeysignature)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

postStoresList

DEPRECATED - Post the store referential of a shoppingHub (you need to provide the full store list as our system is currenlty not able to handle diff updates) (deprecated, please use POST /admin/stores/v2 for a smoother and faster store sync)

Authorizations:
(apiKeysignature)
Request Body schema: application/json

the body containing the stores information

Array of objects [ 1 .. 500 ] items

Responses

Request samples

Content type
application/json
{
  • "stores": [
    ]
}

Response samples

Content type
application/json
{
  • "requestId": "string"
}

postStoresListV2

Synchronize the program's store list with the Spaycial repository (for the updates, you don't have to provide the full store list as our system is able to handle incremental updates)

Authorizations:
(apiKeysignature)
Request Body schema: application/json

the body containing the stores information

Array of objects [ 1 .. 500 ] items

Responses

Request samples

Content type
application/json
{
  • "stores": [
    ]
}

Response samples

Content type
application/json
{ }

getCustomers

Return a list of customers that have registered in a given period

Authorizations:
(signatureapiKey)
header Parameters
startDate
required
string <date>

period start date, in full-date format of RFC3339

endDate
required
string <date>

period end date, in full-date format of RFC3339

limit
number

the maximum number of results to retrieve (default 1000)

offset
number

the results offset (default 0), used to paginate results

Responses

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}

deleteCustomerAdmin

Delete a customer in the Spaycial repository (based on customerId)

Authorizations:
(signatureapiKey)
header Parameters
customerId
required
string

identifier of the customer to delete

Responses

Response samples

Content type
application/json
{
  • "code": "expiredToken",
  • "message": "string"
}

getCustomerRecommendations

Retrieve recommendation for customers - 3 retailers ID for each customers based on previous customers transactions. It's a list of retailers where user haven't spent anything yet but it's likely he will. If there are no personal recommendations for a customer (no transactions made by the customer yet) 3 general recommendations would be provided

Authorizations:
(signatureapiKey)
Request Body schema: application/json

body containing customers filters

customers
Array of strings

a list of customers external ids

dataRetrievalMethod
string
Enum: "paymentCard" "scan"

filter users based on the way we collect their data. Codes:

  • paymentCard - filter users who joined the program by linking their payment card
  • scan - filter users who manually scan of their purchase receipt as part of the program
status
string
Enum: "synchronized" "desynchronized"

whether users bank connections are synchronized or desynchronized. If a user has multiple bank connections, he will be counted as desynchronised if one of his bank connections is desynchronised

registered
boolean

true for users who has finished registration in the system, false for those who are not yet finished the registration process.

Responses

Request samples

Content type
application/json
{
  • "customers": [
    ],
  • "dataRetrievalMethod": "paymentCard",
  • "status": "synchronized",
  • "registered": true
}

Response samples

Content type
application/json
[
  • {
    }
]

sendCustomerTransactionsWebhook

trigger a customer_transactions webhook on a shopping hub

Authorizations:
apiKey
Request Body schema: application/json

The data describing the customer_transactions webhook requested

minTransactions
integer >= 1
Default: 3

Minimum number of generated transactions (inclusive)

maxTransactions
integer >= 1
Default: 3

Maximum number of generated transactions (inclusive)

customersExternalIds
required
Array of strings non-empty

List of external customer identifiers used randomly in generated transactions

purchaseLocationsExternalIds
required
Array of strings non-empty

List of purchase locations external identifiers used randomly in generated transactions

currency
string = 3 characters
Default: "EUR"

Transactions currency in ISO_4217 format

Responses

Request samples

Content type
application/json
{
  • "minTransactions": 3,
  • "maxTransactions": 3,
  • "customersExternalIds": [
    ],
  • "purchaseLocationsExternalIds": [
    ],
  • "currency": "EUR"
}

Response samples

Content type
application/json
{
  • "configuredEndpoints": 0,
  • "successCalls": 0,
  • "failedCalls": 0
}

sendBankConnectionsUpdateV2Webhook

trigger a bank_connections_update_v2 webhook on a shopping hub

Authorizations:
apiKey
Request Body schema: application/json

The data describing the bank_connections_update_v2 webhook requested

eventType
required
string
Enum: "create" "update" "delete"

Type of event between create, update or delete

customerExternalId
required
string

The client's customer id

connectionId
string

The Spaycial's bank connection id, generated if not specified

errorCode
string
Enum: "psd2ConnectionInvalid" "psd2ConnectionExpired" "invalidCredentials"

The error code from the data provider

bank
string
Default: "Boursorama"

The bank name of the bank connection

Responses

Request samples

Content type
application/json
{
  • "eventType": "create",
  • "customerExternalId": "string",
  • "connectionId": "string",
  • "errorCode": "psd2ConnectionInvalid",
  • "bank": "Boursorama"
}

Response samples

Content type
application/json
{
  • "configuredEndpoints": 0,
  • "successCalls": 0,
  • "failedCalls": 0
}

testimonies

getRandomTestimonies

get three random testimonies, one of each categories

Authorizations:
apiKey
query Parameters
lng
required
string = 2 characters

country code (2 letters) used to filter testimonies

Responses

Response samples

Content type
application/json
{
  • "application/json": [
    ]
}