API guideline for developers
As a minimum requirement, APIs provided by Societe Generale are compliant with REST architecture standards and adopt the 2-level Richardson model (included the HAL convention).
Interface contract: Swagger v2.0
Developments: HTTP 1.1, REST Richardson L2, HAL, JSON format and UTF-8 encoding
Security: TLS 1.2, OpenID Connect
English is the common language for API publications. In particular for contract descriptions and API urls (path + parameters).
The API structure
Only one resource type (and its sub-resources) is exposed by each API provided by Societe Generale.
The API documentation
Each API, resource and operation provides a functional rendering overview. Filters, paging, sorting, and counting elements can also be referred.
API description contains a history table of all supported versions. As well as contact details of a technical manager. API specifications are available in Swagger modeling file, which can be downloaded from the API description.
HTTP methods configuration
No other HTTP methods than those described below will be available for APIs provided by Societe Generale:
POST: used to create a new resource. This method can also be used for operations that do not correspond to any other method (eg. functions, calculation...)
GET: used to retrieve one or more resources
PUT: used to update one or more resources (potentially with replacement)
PATCH: used instead of PUT method to make changes on a resource (without replacement)
DELETE: used to remove a unique resource
All the APIs provided by Societe Generale are stateless.
Idempotency is also guaranteed on the APIs. Regardless of the number of identical API calls on a resource, the result will always be the same on server side (the answer could be different).
Framework for API request
Authentication and security
"SG SIGNIN" module allows you to authenticate to the "SOCIETE GENERALE | SG OPEN API" platform using your developer account credentials (login and password).
API access is done by the transfer of an access Token (to be included on your request "Authorization" header). The recovery mode of this access Token could be different depending on APIs you want to use. Moreover for some APIs you may be required to import a certificate when registering your application.
Versions relate to APIs provided by Societe Generale, not for resources. There are two release levels for these APIs: 'major' and 'minor'. Only the major version has to be indicated on the API path.
Only the latest two major API releases are supported and available. These major releases may not be backward compatible (minor releases are backward compatible).
HTTP Headers are only used for metadata.
Path and query parameters use the 'camelCase' convention for all APIs provided by Societe Generale.
Path parameters are used for resources which include identity elements.
All others have to be used as query parameters.
Framework for API response
Paging will be enabled in most cases for a query returning a collection. 'offset' and 'limit' parameters are then included on the HTTP response header.
Available HTTP response codes
Only codes below will be available to the HTTP response:
200: Request succeeded for a GET, POST, DELETE, or PATCH call that completed synchronously, or a PUT call that synchronously updated an existing resource
201: Request succeeded for a POST, or PUT call that synchronously created a new resource
202: Request accepted for a POST, PUT, DELETE, or PATCH call that will be processed asynchronously
204: The server successfully processed the request and is not returning any content
206: Request succeeded on GET, but only a partial response returned
40x: Client error
400: General error for any request (if it doesn’t fit in any other)
401: Unauthorized - Request failed because user/client app is not authenticated
403: Forbidden - Request failed because user does not have authorization to access a specific resource
404: Not found - The resource you’re requesting doesn’t exist
422: Unprocessable Entity - Your request was understood, but contained invalid parameters
429: Too many requests
50x: Server error
500: Internal server error - Something went wrong on the server, check status site and/or report the issue
Our APIs are secured through SG Signin OAuth 2 & OIDC server. Full documentation may be found here : https://sg-signin.societegenerale.fr/apidoc/oauth2
Strong Customer Authentication using APIs
Retail Market: PSD2-SCA API RETAIL v20190614.pdf
Corporate Market: PSD2-SCA API CORP v20190614.pdf
Professional Market: PSD2-SCA API PRO v20190614.pdf
In case of dedicated interface (DSP2 APIs) malfunction, SOCIETE GENERALE will make use a contingency mechanism referred to in Article 32 from COMMISSION DELEGATED REGULATION (EU) 2018/389.
Therefore, SOCIETE GENERALE will provide as contingency mechanism to authorized service providers, a secured access to the interfaces made available to the payment service users for the authentication and communication with their account servicing payment service provider, until the dedicated interface is restored to the level of availability and performance provided for in Article 32.
This contingency mechanism, available trough website links provided hereafter, will be secured by TLS protocol with mutual authentication and will need from service providers the use of eIDAS DSP2 QWAC (Qualified Website Authentication Certificate).
URL for contingency mechanism (coming soon):
- Retail market: https://particuliers.wss.societegenerale.fr
- Corporate market : https://entreprises.wss.societegenerale.fr
- Professional market : https://professionnels.wss.societegenerale.fr