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 |
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.
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=
Mac OS X Install via Homebrew: brew install openssl
Windows Windows complete package .exe installer
Ubuntu Linux apt-get install openssl
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
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).
There are several common points about the request we send to the push URLs provided:
Content-Type
header is application/json
;POST
;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:
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwfc/T2Pv+ua5pUBqtVdK
+mtl7dphlPuI3jtYifTCEIhahNN8ZFtJwcYeuKwZxcFowO2zL/YQ4468Jj9jdKgb
A4JBOyWELHRawt9opTGuHEzyrl4VHG27bKrFYfOJwsyMEUjKSCxeRr173qkhIolr
MWnqgCtydBsnFZocghbWknoupl+aAEgesmLteHFNvfoQAeoJJLOvpA2ieQvLiTWE
h+oaSPuLN+ftRgUIY6DrAOOQFBtMtcVY2p6ZR27R1TgHr2YMWKxB/DUNVmaUsW/t
MVf+QOkmPLwKOrz/HjyZNLqh+vhmrsrc97dyImmnd1yjuciFtNzMwCmTO8lQ94uk
FwIDAQAB
-----END PUBLIC KEY-----
-----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.
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.
https://www.api.yourdomain.com/mymall/tc-endpoint
{
...
“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.
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
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):
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
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):
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):
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, 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"
}
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:
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"
}
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 DELETEbank
[Object]: The bank triggering the eventBank 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 eventBank 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:
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:
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",
}
}
get bank list
cardType | string Enum: "bank" "restaurant" type of card associated to this bank (bank vs restaurant ) |
{- "application/json": [
- [
- {
- "id": "d9a25c93-bda9-4253-a49b-45f2a0979847",
- "name": "A French Bank",
- "countryCode": "FR",
- "available": true,
- "cardType": "bank",
}, - {
- "id": "4adb3a28-81e3-4e76-9a7f-ec59870b4893",
- "name": "Rest DE",
- "countryCode": "DE",
- "available": false,
- "cardType": "rest",
}
]
]
}
get info about a bank, based on its id
bankId required | string bank identifier (found in GET /banks) |
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 |
{- "application/json": [
- {
- "id": "d9a25c93-bda9-4253-a49b-45f2a0979847",
- "name": "A French Bank",
- "countryCode": "FR",
- "cardType": "bank",
- "available": true,
- "fields": [
- {
- "regex": null,
- "type": "text",
- "name": "login",
- "label": "Identifiant",
- "required": true,
- "requiredForUpdate": false
}, - {
- "regex": null,
- "type": "password",
- "name": "password",
- "label": "Mot de passe",
- "required": true,
- "requiredForUpdate": true
}
]
}
]
}
get optins list
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) |
{- "application/json": [
- [
- {
- "code": "optin1",
- "label": "This optin is mandatory",
- "required": true
}, - {
- "code": "optin2",
- "label": "This optin is optional",
- "required": false
}
]
]
}
register to Spaycial using an identifier (mobile phone, email, external id, ...)
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
|
postalCode | string The postal code of the address - can be alphanumeric, dashes or spaces |
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 |
{- "phoneNumber": "string",
- "countryCode": 0,
- "captcha": "string",
- "origin": "email",
- "referer": "string",
- "customerExternalId": "string",
- "firstName": "string",
- "lastName": "string",
- "familyStatus": "singleWithoutChildren",
- "postalCode": "string",
- "email": "string",
- "optins": [
- {
- "code": "string",
- "value": true
}
], - "outsideOptIn": true,
- "referralInfo": {
- "code": "string",
- "phoneNumber": "string",
- "countryCode": 0
}, - "preferredLanguage": "string",
- "transactionsEligibleFromDate": 0
}
{- "application/json": [
- {
- "customerId": "91c2003e-3eb0-87c6-ac8d-4fcaad4cbd19",
- "bankAlreadyConnected": false
}
]
}
Allows a customer to register by uploading a receipt
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 |
{- "application/json": [
- {
- "isProperReceiptExtract": true
}
]
}
Add a first bank connection to customer by providing bank website callback code
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 |
{- "customerId": "string",
- "bankId": "string",
- "dataProviderConnectionId": "string",
- "queryString": { },
- "redirectUri": "string"
}
{- "application/json": [
- {
- "bankConnectionId": "c0b88330-ec05-49c3-99eb-e67b1a1e3fc9",
- "accessToken": "xxxxx.yyyyy.zzzzz"
}
]
}
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)
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. |
{- "application/json": [
- {
- "accessToken": "xxxxx.yyyyy.zzzzz"
}
]
}
login to Spaycial using mobile phone and password
the body containing login info
phoneNumber | string phone number, without any prefix |
countryCode | integer phone country code (i.e. 33 for France) |
string customer's email | |
password required | string customer's area password |
{- "phoneNumber": "string",
- "countryCode": 0,
- "email": "string",
- "password": "string"
}
{- "application/json": [
- {
- "accessToken": "xxxxx.yyyyy.zzzzz"
}
]
}
get an SMS temporary code to confirm customer identity
phoneNumber required | string phone number, without any prefix |
countryCode required | integer phone country code (i.e. 33 for France) |
{- "code": "unknownPhone",
- "message": "string"
}
post the temporary code received via SMS to confirm identity
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 |
{- "phoneNumber": "string",
- "countryCode": 0,
- "temporaryCode": "string"
}
{- "application/json": [
- {
- "accessToken": "xxxxx.yyyyy.zzzzz"
}
]
}
verify the status of a decoupledConnection and retrieve the oauthcallback uri
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) |
{- "decoupledDetails": {
- "dataProviderId": "string",
- "dataProviderShortcut": "string",
- "connectionExternalId": "string"
}
}
{- "application/json": [
- {
- "callbackUrl": "/oauthcallback?code=xxxx&customer_id=xxxxxx",
- "status": "completed"
}
]
}
Allows a customer to register by uploading a receipt
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 |
{- "application/json": [
- {
- "isProperReceiptExtract": true
}
]
}
Get current customer information (deduced from header token)
{- "application/json": [
- {
- "customerId": "c5562d40-be8b-43cf-88ca-96933e76629f",
- "firstName": "John",
- "bankAlreadyConnected": true,
- "email": "foo@bar.com",
- "phoneVerified": true,
- "registered": true,
- "createdAt": "2018-10-19T16:07:05.887Z"
}
]
}
update current customer
firstName | string customer's first name |
lastName | string customer's last name |
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
|
{- "firstName": "string",
- "lastName": "string",
- "email": "string",
- "phoneNumber": "string",
- "countryCode": 0,
- "password": "string",
- "outsideOptIn": true,
- "preferredLanguage": "string",
- "postalCode": "string",
- "familyStatus": "singleWithoutChildren"
}
{- "application/json": [
- {
- "customerId": "c5562d40-be8b-43cf-88ca-96933e76629f",
- "firstName": "John",
- "bankAlreadyConnected": true,
- "email": "foo@bar.com",
- "phoneVerified": true,
- "registered": true,
- "createdAt": "2018-10-19T16:07:05.887Z"
}
]
}
{- "customerId": "string",
- "connections": [
- {
- "created": "2019-10-08T12:30:44.487Z",
- "updated": "2019-10-08T12:30:44.487Z",
- "id": "a83b4b96-568a-49f9-8019-d6fdff41c4c8",
- "type": "visa",
- "scheme": "visa",
- "programId": "4c65afca-047b-4c3e-b079-761545a40e1d",
- "metadata": {
- "id": "032ad8f4-098a-4187-aed9-5b1c05424df6"
}, - "live": false,
- "lastNumbers": "4322",
- "firstNumbers": "444400",
- "expYear": 2020,
- "expMonth": 2,
- "expDate": "2020-02-29T23:59:59.999Z",
- "countryCode": "CAN",
- "accountId": "8e8aed10-19ae-4faf-8cd2-147b1d9d1b94"
}
]
}
add a credit card connection providing checkout credit card token
body containing connection info
creditCardToken required | string credit card token (issued by Checkout tokenization) |
{- "creditCardToken": "string"
}
{- "application/json": [
- {
- "creditCardId": "c0b88330-ec05-49c3-99eb-e67b1a1e3fc9"
}
]
}
delete a connection of any type
connectionId required | string the connection id (either a bank connection id or a credit card id) |
{- "code": "invalidConnectionId",
- "message": "string"
}
[- {
- "customerId": "ffc09cbd-e5b3-497a-a9d7-9d510810efcb",
- "connections": [
- {
- "id": "9d635cb0-07ec-4e90-88f7-2562d5624d05",
- "expDate": "2024-03-31",
- "scheme": "visa",
- "countryCode": "SE",
- "lastNumbers": "5453",
- "type": "CLO"
}, - {
- "id": "cecb2084-d005-4e04-9689-65af01affc47",
- "creationDate": "2020-03-27T18:15:52+01:00",
- "passwordError": false,
- "lastUpdate": "2020-03-27",
- "bankId": "connecteur_de_test_fr_b",
- "bankName": "Connecteur de test",
- "cardType": "bank",
- "type": "SCR"
}
]
}
]
{- "application/json": [
- {
- "customerId": "27b36da1-39f2-5ab5-8784-52a78779af58",
- "connections": [
- {
- "id": "b6255bf6-b293-424d-9363-d94700aca720",
- "bankId": "0ef0f298-47ab-41f6-ae89-f1f6dab94104",
- "bankName": "Some Bank",
- "creationDate": "2018-01-17"
}, - {
- "id": "e13c5c09-f71f-4139-869a-3b228109594a",
- "bankId": "63cbd7cc-d65e-4e36-817a-ef3774f2a5ce",
- "bankName": "Another Bank",
- "creationDate": "2018-01-22"
}
]
}
]
}
add a bank connection to customer by providing bank website callback code
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 |
{- "bankId": "string",
- "queryString": { },
- "redirectUri": "string"
}
{- "application/json": [
- {
- "bankConnectionId": "c0b88330-ec05-49c3-99eb-e67b1a1e3fc9"
}
]
}
update a bank connection by providing bank website credentials
connectionId required | string the connection id |
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 |
{- "credentials": { },
- "redirectUri": "string",
- "locale": "string",
- "psuId": "string",
- "chosenAuthModel": "string"
}
{- "code": "invalidConnectionId",
- "message": "string"
}
update bank connection callback
connectionId required | string the connection id |
body containing connection info
queryString | object object containing the query string from interactive callback |
{- "queryString": { }
}
{- "code": "invalidConnectionId",
- "message": "string"
}
Track an action made by a Customer
customerId required | string the customer identifier |
eventName required | string the event name |
value required | string the event value |
{- "code": "customerNotFound",
- "message": "string"
}
Test if a given external identifier match a customer in the Spaycial repository
externalId required | string the customer identifier in mall repository |
{- "code": "missingAuthorizationHeader",
- "message": "string"
}
Test if a given Spaycial identifier matches a registered customer in the Spaycial repository
customerId required | string the customer identifier in the Spaycial repository |
eventType required | string Enum: "exclusive_event" "purchase_discount" "store_opening" "toilets_access" the event at the origin a call to this endpoint
|
{- "code": "missingAuthorizationHeader",
- "message": "string"
}
Test if the given customer info matches a referral customer in the Spaycial database
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) |
{- "referralCode": "string",
- "phoneNumber": "string",
- "countryCode": 0
}
{- "application/json": [
- {
- "referralExists": true
}
]
}
set customer's favorite account used for refunds
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) |
{- "iban": "string",
- "sortCode": "string",
- "accountNumber": "string"
}
{- "code": "invalidIban",
- "message": "string"
}
get an SMS containing a link to allow customer to set its favorite account used for refunds
phoneNumber required | string phone number, without any prefix |
countryCode required | integer phone country code (i.e. 33 for France) |
{- "code": "no_account",
- "message": "string"
}
get an SMS containing a link to allow customer to update its bank credentials
phoneNumber required | string phone number, without any prefix |
countryCode required | integer phone country code (i.e. 33 for France) |
{- "code": "unknown_phone",
- "message": "string"
}
[- [
- {
- "id": "string",
- "rewardState": "TRAN",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z",
- "rewardValue": 0,
- "redeemed": true,
- "redeemDate": "2019-08-24T14:15:22Z",
- "cashbackId": 0,
- "cashbackStatus": 0,
- "challenge": {
- "id": "string",
- "name": "string",
- "teaser": "string",
- "startDate": "2019-08-24T14:15:22Z",
- "endDate": "2019-08-24T14:15:22Z",
- "conditionLabel": "string",
- "terms": "string",
- "rewardLabel": "string"
}
}
]
]
Returns all stores where the user did (or did not, depending on parameter) make a transaction
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 |
[- [
- {
- "id": "{08228F4D-3FA0-4F1D-AC53-1C13B5E24968}",
- "name": "HISTOIRE D'OR"
}, - {
- "id": "{78228F4D-4GA0-9C1D-CD53-3B13B5E24968}",
- "name": "ZARA"
}
]
]
Returns all customer transactions related to shopping hub stores
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 |
[- {
- "application/json": [
- {
- "date": "2016-12-07",
- "storeId": "{08228F4D-3FA0-4F1D-AC53-1C13B5E24968}",
- "amount": -15,
- "currency": "EUR"
}, - {
- "date": "2016-12-08",
- "storeId": "{18228F4D-4FA3-4F1D-9C55-DC13B5E24954}",
- "amount": -40.95,
- "currency": "EUR"
}
]
}
]
Returns all customer points history
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 |
[- {
- "id": "string",
- "operationDate": "2019-08-24T14:15:22Z",
- "value": 0,
- "type": "SPEND"
}
]
Returns all transactions that the user did in the given store
storeId required | string the store identifier in mall repository |
[- {
- "date": "2016-12-07",
- "amount": -15,
- "currency": "EUR"
}, - {
- "date": "2016-12-08",
- "amount": -40.95,
- "currency": "EUR"
}
]
Returns all customer transactions related to shopping hub services
[- {
- "date": "2016-12-07",
- "serviceId": "{28228F4D-3FA0-4F1D-AC53-1C13B5E24968}",
- "amount": -15,
- "currency": "EUR"
}, - {
- "date": "2016-12-08",
- "serviceId": "{38228F4D-4FA3-4F1D-9C55-DC13B5E24954}",
- "amount": -40.95,
- "currency": "EUR"
}
]
Returns all transactions that the user did for the given service
serviceId required | string the service identifier in mall repository |
[- {
- "date": "2016-12-07",
- "amount": -15,
- "currency": "EUR"
}, - {
- "date": "2016-12-08",
- "amount": -40.95,
- "currency": "EUR"
}
]
Returns all customer transactions complaints
[- [
- {
- "id": "string",
- "transactionDate": "2019-08-24",
- "attachmentUrl": "string",
- "amount": 0,
- "claimStatus": "validated",
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z",
- "store": {
- "id": "string",
- "name": "string"
}, - "rejectionReason": "string",
- "rejectionReasonTranslationKey": "string"
}
]
]
allows to send a complaint about a transaction assignment issue
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) |
{- "storeId": "string",
- "externalId": "string",
- "amount": 0,
- "transactionDate": "2019-08-24",
- "additionalFeedback": "string",
- "attachment": "string"
}
{- "code": "storeNotFound",
- "message": "string"
}
{- "application/json": [
- [
- {
- "id": "2a804a3a-8da2-4ff1-8077-da588ba53a7d",
- "status": "validated",
- "receiptImageUrl": "https://cdn.transactionconnect.com/claims/staging/88035a54-e6bb-48ae-b526-d6cba060490a",
- "rejectionReason": null,
- "createdAt": "2020-02-02T16:09:44.034Z",
- "transaction": {
- "id": "f89c9349-283e-4664-9214-cf8cb702e150",
- "transactionDate": "2020-02-01",
- "amount": "-56.00",
- "currency": "EUR",
- "createdAt": "2020-02-02T16:10:32.743Z",
- "store": {
- "id": "67322cca-03ad-4542-92b9-2dd20d73fb9f",
- "name": "BASIC FIT"
}
}
}, - {
- "id": "7adb2988-6b6e-4f84-8272-2b293af577a8",
- "status": "validated",
- "receiptImageUrl": "https://cdn.transactionconnect.com/claims/staging/88035a54-e6bb-48ae-b526-d6cba060490a",
- "rejectionReason": null,
- "createdAt": "2020-02-02T17:44:07.552Z",
- "transaction": {
- "id": "f1eb4c08-0075-4503-befc-3d74d78319a8",
- "transactionDate": "2020-02-01",
- "amount": "-56.00",
- "currency": "EUR",
- "createdAt": "2020-02-02T17:44:40.882Z",
- "store": {
- "id": "c35cd149-2f80-4f5c-b932-08044c1641c6",
- "name": "GIFI"
}
}
}
]
]
}
Allows customer to update a receipt
body containing receipt id and store id
storeId required | string id of the store |
receiptId required | string id of the receipt |
{- "storeId": "string",
- "receiptId": "string"
}
{- "code": "invalidStoreId",
- "message": "string"
}
get optins list validated by the customer
lng | string country code (2 letters) used to filter bank list by country |
{- "application/json": [
- [
- {
- "code": "optin1",
- "label": "This optin is opted in",
- "value": true,
- "registrationType": "SCR"
}, - {
- "code": "optin2",
- "label": "This optin is opted out",
- "value": false,
- "registrationType": "CLO"
}
]
]
}
update optins value for current customer
body containing new optin values
registrationType | string Default: "SCR" type of optin's registration (default 'SCR': web scrapping) |
required | Array of objects (Optin) |
{- "registrationType": "SCR",
- "optins": {
- "application/json": [
- [
- {
- "code": "optin1",
- "value": true
}, - {
- "code": "optin2",
- "value": false
}
]
]
}
}
[- {
- "code": "string",
- "value": true
}
]
update a bank connection
connectionId required | string the connection id to update |
body containing connection info
simulateInvalidCredentials | boolean true to simulate an invalidCredentials error on this bank connection, false to do nothing |
{- "simulateInvalidCredentials": true
}
{- "code": "invalidConnectionId",
- "message": "string"
}
generate a cashback refund for a given customer
Expires-at | integer request expiration time as a UNIX timestamp in UTC timezone. We suggest to use +1 minute from the current time. |
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 |
{- "customerId": "string",
- "customerExternalId": "string",
- "externalId": "string",
- "ownerInfo": {
- "firstName": "string",
- "lastName": "string",
- "birthDate": "2019-08-24",
- "email": "string",
- "nationality": "st",
- "address": {
- "addressLine1": "string",
- "addressLine2": "string",
- "city": "string",
- "region": "string",
- "postalCode": "string",
- "country": "st"
}
}, - "transferInfo": {
- "iban": "string",
- "amount": 0,
- "currency": "str",
- "bankReference": "string",
- "cashbackType": "standard"
}
}
{- "application/json": [
- {
- "transferId": "8494514"
}
]
}
generate a list of cashback refund
Expires-at | integer request expiration time as a UNIX timestamp in UTC timezone. We suggest to use +1 minute from the current time. |
body containing an array of cahsbacks 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 |
[- {
- "customerId": "string",
- "customerExternalId": "string",
- "externalId": "string",
- "ownerInfo": {
- "firstName": "string",
- "lastName": "string",
- "birthDate": "2019-08-24",
- "email": "string",
- "nationality": "st",
- "address": {
- "addressLine1": "string",
- "addressLine2": "string",
- "city": "string",
- "region": "string",
- "postalCode": "string",
- "country": "st"
}
}, - "transferInfo": {
- "iban": "string",
- "amount": 0,
- "currency": "str",
- "bankReference": "string",
- "cashbackType": "standard"
}
}
]
{- "application/json": [
- [
- {
- "transferId": "8494514"
}, - {
- "status": "ERROR",
- "code": "invalidCustomer",
- "message": "Invalid customer id",
- "statusCode": 400
}
]
]
}
Return a list of cashbacks that have been pushed to hub in a given period (30 days max)
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 |
{- "application/json": [
- [
- {
- "id": "234123",
- "intermediateStatus": "SUCCEEDED",
- "intermediateStatusDate": "2017-01-09",
- "finalStatus": "RECEIVED",
- "finalStatusDate": "2017-01-09"
}
]
]
}
Retrieve a shopping hub based on its external id, customer external id or host (priority is given to customerExternalId)
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 |
{- "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": {
- "id": "string",
- "name": "string",
- "shortcut": "string",
- "transactionActivitiesIsDisplayed": true
}, - "hasWestfield": true,
- "interface": {
- "baseline": "string",
- "colorPrimary": "string",
- "colorSecondary": "string",
- "css": "string",
- "logoProgramUrl": "string",
- "faviconCode": "string",
- "hasLandingPage": true
}, - "cashbackProvider": "string",
- "checkoutPublicKey": "string",
- "programOffer": "string",
- "scanConditions": "string",
- "claimMinimumAmount": "string",
- "rewardType": "CASHBACK",
- "languages": [
- {
- "country": "string",
- "favorite": true
}
], - "features": [
- {
- "name": "string",
- "configuration": { }
}
]
}
[- [
- {
- "webhookId": "055b00a5-bd3e-482e-897c-0bcca6054dcf",
- "name": "Webhook Spaycial",
- "events": [
- "cashbacks_updated",
- "cashback_method_updated",
- "bank_connections_update",
- "bank_connections_update_v2",
- "receipt_updated",
- "customer_transactions",
- "customer_creation",
- "customer_subscription",
- "claim_update"
], - "active": true
}
]
]
add a webhook too be posted events onto
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 |
{- "name": "string",
- "url": "string",
- "events": [
- "bank_connections_update"
], - "active": true
}
{- "webhookId": "string"
}
patch an existing webhook
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 |
{- "webhookId": "string",
- "name": "string",
- "url": "string",
- "events": [
- "bank_connections_update"
], - "active": true
}
{- "webhookId": "string"
}
current | boolean If true, only return challenges that are active, if missing, all challenges will be returned. |
[- {
- "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"
}
]
id required | string id of the challenge |
{- "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"
}
Return a list of transactions that have been pushed to hub in a given period (30 days max)
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 |
{- "application/json": [
- [
- {
- "id": "3275ffc5-f1dd-435e-8757-1d293ff1e832",
- "amount": "-40.17"
}
]
]
}
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)
the body containing the stores information
Array of objects [ 1 .. 500 ] items |
{- "stores": [
- {
- "storeExternalId": "string",
- "retailerName": "string",
- "address": "string",
- "locality": "string"
}
]
}
{- "requestId": "string"
}
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)
the body containing the stores information
Array of objects [ 1 .. 500 ] items |
{- "stores": [
- {
- "externalId": "string",
- "brandName": "string",
- "googlePlaceId": "string",
- "status": "open",
- "inProgram": true,
- "closingDate": "2019-08-24T14:15:22Z"
}
]
}
{ }
Return a list of customers that have registered in a given period
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 |
{- "application/json": [
- [
- {
- "customerId": "0e67d4d5-e11d-4766-966c-d3d15b2acfb6",
- "customerExternalId": "56591974",
- "registrationDate": "2019-04-30T06:09:35.309Z",
- "registrationType": "BANK"
}
]
]
}
Delete a customer in the Spaycial repository (based on customerId)
customerId required | string identifier of the customer to delete |
{- "code": "expiredToken",
- "message": "string"
}
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
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:
|
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. |
{- "customers": [
- "string"
], - "dataRetrievalMethod": "paymentCard",
- "status": "synchronized",
- "registered": true
}
[- {
- "customerId": "string",
- "retailers": [
- "string"
]
}
]
trigger a customer_transactions webhook on a shopping hub
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 |
{- "minTransactions": 3,
- "maxTransactions": 3,
- "customersExternalIds": [
- "string"
], - "purchaseLocationsExternalIds": [
- "string"
], - "currency": "EUR"
}
{- "configuredEndpoints": 0,
- "successCalls": 0,
- "failedCalls": 0
}
trigger a bank_connections_update_v2 webhook on a shopping hub
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 |
{- "eventType": "create",
- "customerExternalId": "string",
- "connectionId": "string",
- "errorCode": "psd2ConnectionInvalid",
- "bank": "Boursorama"
}
{- "configuredEndpoints": 0,
- "successCalls": 0,
- "failedCalls": 0
}
get three random testimonies, one of each categories
lng required | string = 2 characters country code (2 letters) used to filter testimonies |
{- "application/json": [
- [
- {
- "id": "41c65e84-e30b-4f79-8f2a-92fe42c034de",
- "birthDate": "1984-10-09",
- "category": "benefits",
- "description": "This is a benefits test testimony, it should be disabled and not display.",
- "firstName": "Transaction",
- "age": 35
}
]
]
}