V 1.0.6 - Merchant Webhooks API

Version 1.0.6 (latest)

Description

The common services is offered by the BAAS platform. One of the main services is the merchant webhook service. The Webhook Merchant API allows merchants to subscribe to various transaction status events and receive notifications through configured callback APIs or by polling for these events.

Webhooks

Configure a webhook (for a given event type) for a merchant

put

Configure a webhook (for a given event type) for a merchant. The event type must match the family code of the merchant's subscription product.

Authorizations

Body

Data to configure webhooks for a merchant

eventTypeCodestringRequired

Event type code for which we want to configure the webhook. Can be ANY, SC_SUBSCRIPTION, SC_CANCEL_REQUEST, CI_SUBSCRIPTION, HELLO_WORLD.

Example: SC_SUBSCRIPTION

activebooleanOptional

Is this webhook active ? Default is false.

Example: true

urlstring · urlOptional

Url to use for this webhook. Default is null.

Example: https://www.acme.com/webhooks/events/credit

authMethodstring · enumOptional

Authentication method to use for this webhook. Default is null.

Example: BASIC_AUTHPossible values:

authLoginstringOptional

Authentication login to use for this webhook if authentication method is BASIC_AUTH. Default is null.

Example: mySuperLogin

authPasswordstringOptional

Authentication password to use for this webhook if authentication method is BASIC_AUTH. Default is null.

Example: mySuperPassword

authScopestringOptional

Authentication scope to use for this webhook. Not used so far (OAUTH2 is not yet supported). Default is null.

Example: mySuperScope

keyForSignaturestringOptional

Key to use to sign the events for this webhook (using HMAC-SHA256). When the webhook endpoint will be called (during event delivery), the header X-BAAS-SIGNATURE will contain the signature of the event. Default is null.

Example: e5399af3ebcde0f3ead45086e13e932f36b1e5a1db002c8bb6a2870a1d22a7b6

secretstringOptional

Secret (or ApiKey if authentication method is API_KEY) to send alongside with the events for this webhook. When the webhook endpoint will be called (during event delivery), the header X-BAAS-SECRET will contain the secret. If the authentication method is API_KEY, the header Authorization will contain the secret. Default is null.

Example: mySuperSecretOrMyAPIKey

emailForAlertsstringOptional

Email to use to notify alerts (typically used if too many errors are encountered on a webhook)

Example: [e-mail]

activeEventCodesstring[]Optional

List of active event codes for the given event type. If this field is not specified, all event codes that belong to the given eventTypeCode will be activated (current and future).

Example: ["SC_SUBSCRIPTION_ACCEPTED","SC_SUBSCRIPTION_REJECTED"]

Responses

put

HTTPcURLJavaScriptPython

PUT /baas/prod/merchant-webhooks/api/v1/webhooks HTTP/1.1
Host: api.scalexpert.societegenerale.com
Content-Type: application/json
Accept: */*
Content-Length: 445

{
  "eventTypeCode": "SC_SUBSCRIPTION",
  "active": true,
  "url": "https://www.acme.com/webhooks/events/credit",
  "authMethod": "BASIC_AUTH",
  "authLogin": "mySuperLogin",
  "authPassword": "mySuperPassword",
  "authScope": "mySuperScope",
  "keyForSignature": "e5399af3ebcde0f3ead45086e13e932f36b1e5a1db002c8bb6a2870a1d22a7b6",
  "secret": "mySuperSecretOrMyAPIKey",
  "emailForAlerts": "[e-mail]",
  "activeEventCodes": [
    "SC_SUBSCRIPTION_ACCEPTED",
    "SC_SUBSCRIPTION_REJECTED"
  ]
}

No content

Retrieve a webhook configuration (for a given event type code) for a merchant

get

Retrieve a webhook configuration (for a given event type code) for a merchant

Authorizations

Query parameters

eventTypeCodestringRequired

eventTypeCode for which the webhook configuration must be retrieved.
Can be SC_SUBSCRIPTION, CI_SUBSCRIPTION, HELLO_WORLD...etc.

• HELLO_WORLD: This Key word could be used for retrieving the webhooks config already created for test.

Example: SC_SUBSCRIPTION

Responses

get

HTTPcURLJavaScriptPython

GET /baas/prod/merchant-webhooks/api/v1/webhooks HTTP/1.1
Host: api.scalexpert.societegenerale.com
Accept: */*

{
  "eventTypeCode": "SC_SUBSCRIPTION",
  "active": true,
  "url": "https://www.acme.com/webhooks/events/credit",
  "authMethod": "BASIC_AUTH",
  "authLogin": "mySuperLogin",
  "authPassword": "mySuperPassword",
  "authScope": "mySuperScope",
  "keyForSignature": "e5399af3ebcde0f3ead45086e13e932f36b1e5a1db002c8bb6a2870a1d22a7b6",
  "secret": "mySuperSecretOrMyAPIKey",
  "emailForAlerts": "[e-mail]",
  "activeEventCodes": [
    "SC_SUBSCRIPTION_ACCEPTED",
    "SC_SUBSCRIPTION_REJECTED"
  ]
}

Events

Trigger an event of type HELLO_WORLD to a merchant.

post

Trigger an event of type HELLO_WORLD to a merchant in order to test its endpoint of webhooks callback.

Authorizations

Responses

post

HTTPcURLJavaScriptPython

POST /baas/prod/merchant-webhooks/api/v1/events/tests/_trigger HTTP/1.1
Host: api.scalexpert.societegenerale.com
Accept: */*

{
  "eventId": "44f5060e-a89c-11ed-afa1-0242ac120002"
}

Retrieve webhook events with a given delivery status

get

Retrieve webhook events with a given delivery status (OK, ERROR, INACTIVE...)

Authorizations

Query parameters

statusstring · enumOptional

Delivery status of the events to retrieve

Possible values:

eventTypeCodestringOptional

eventTypeCode for which the webhook configuration must be retrieved. Can be ANY, SC_SUBSCRIPTION, CI_SUBSCRIPTION, TEST...

Example: SC_SUBSCRIPTION

eventCodestringOptional

event code for the event type

Example: ["SC_SUBSCRIPTION_INITIALIZED","SC_SUBSCRIPTION_PRE_ACCEPTED"]

fromTimestampstring · date-timeOptional

Event to retrieve must have a timestamp greater that fromTimestamp

Example: 2023-06-27T15:20:30.456Z

toTimestampstring · date-timeOptional

Event to retrieve must have a timestamp lower that toTimestamp

Example: 2023-09-27T15:20:30.456Z

pageintegerOptional

Page, starting from 1. Default is 1.

pageSizeintegerOptional

Page size. Default is 20.

sortstringOptional

Sort. Default is -timestamp.

Responses

get

HTTPcURLJavaScriptPython

GET /baas/prod/merchant-webhooks/api/v1/events HTTP/1.1
Host: api.scalexpert.societegenerale.com
Accept: */*

{
  "totalEventCount": 158,
  "events": [
    {
      "timestamp": "2023-06-27T13:20:30.456Z",
      "id": "44f5060e-a89c-11ed-afa1-0242ac120002",
      "correlationId": "7d9670fe-a0cf-4073-afde-bdc61ca49f75",
      "eventTypeCode": "CREDIT",
      "eventCode": "CANCELLED",
      "data": {
        "eventTypeCode": "text",
        "eventCode": "text",
        "merchantGlobalOrderId": "text",
        "insuranceSubscriptionId": "text",
        "consolidatedStatus": "INITIALIZED"
      },
      "replayCount": 1,
      "status": "ERROR",
      "timestampOfLastDeliveryAttempt": "2023-06-27T13:20:30.456Z",
      "httpStatusCodeOfLastDeliveryAttempt": 500
    }
  ]
}

Retrieve a webhook event

get

Retrieve a webhook event using its id

Authorizations

Path parameters

eventIdstring · uuidRequired

Id of the event to retrieve

Responses

get

HTTPcURLJavaScriptPython

GET /baas/prod/merchant-webhooks/api/v1/events/{eventId} HTTP/1.1
Host: api.scalexpert.societegenerale.com
Accept: */*

{
  "timestamp": "2023-06-27T13:20:30.456Z",
  "id": "44f5060e-a89c-11ed-afa1-0242ac120002",
  "correlationId": "7d9670fe-a0cf-4073-afde-bdc61ca49f75",
  "eventTypeCode": "CREDIT",
  "eventCode": "CANCELLED",
  "data": {
    "eventTypeCode": "text",
    "eventCode": "text",
    "merchantGlobalOrderId": "text",
    "insuranceSubscriptionId": "text",
    "consolidatedStatus": "INITIALIZED"
  },
  "replayCount": 1,
  "status": "ERROR",
  "timestampOfLastDeliveryAttempt": "2023-06-27T13:20:30.456Z",
  "httpStatusCodeOfLastDeliveryAttempt": 500
}

Event Types

Retrieve available event type codes and associated event codes for a merchant.

get

• Retrieve available event type codes and associated event codes.
• Return an empty list of eventTypes if the merchant is not eligible for any event-type.

Authorizations

Responses

get

HTTPcURLJavaScriptPython

GET /baas/prod/merchant-webhooks/api/v1/event-types HTTP/1.1
Host: api.scalexpert.societegenerale.com
Accept: */*

{
  "eventTypes": [
    {
      "eventTypeCode": "text",
      "description": "text",
      "eventCodes": [
        {
          "eventCode": "text",
          "description": "text"
        }
      ]
    }
  ]
}

Download OpenAPI specs:

27KB

swagger_merchant-webhooks_1.0.6.yaml