Webhooks

As part of operating Conferma issued virtual cards, there are a number of life-cycle events that may require a customer to be notified.

Conferma provide an event webhook capability that enables a third-party system to be notified of activity surrounding a virtual card.

Event Types

The following event types are managed by Conferma:

Event ID	Name	Description
98	Card Authorisation Activity	A card issuer has notified Conferma of authorisation activity on a virtual card. This event is triggered in near real-time following a virtual card being presented to a merchant point of sale.

Handling Webhook Events

In order to receive notifications issued via the Conferma system, a webhook listener must be installed on the integrated third-party server.

All Conferma notifications are issued in a standard format to a single configured endpoint. This endpoint must conform to the message format specification outlined by Conferma.

The webhook listener URL should be provided to the Conferma Implementations team.

Webhook Security

All notifications issued by Conferma must be processed over a secure HTTPS connection with TLS 1.2 or above.

Webhook Payload Format

Each payload follows a standard format.

Property	Data Type	Description	Example
version	integer	A version property will be provided to allow for future expansion of the event message payload.	1
notificationMessageID	integer	Unique identifier for the notification message instance.	123456
notificationCreationTime	DateTime	The date and time the notification was generated.	2022-04-03 10:15:87
notificationEventType	object
notificationEventType.id	integer	Unique ID for the Event Type of the notification.	98
notificationEventType.name	string	Name of the notification event.	Card Authorisation Activity
Content	object	Specific content for the event notification.	-

Sample Request Payload

JSON

{
    "version": 1, 
    "notificationMessageID": 123456, 
    "notificationCreationTime": "2020-04-03 10:15:87",
    "notificationEventType": {
        "id":98,
        "name": "Card Authorisation Activity"
    },
    "content":  {
    ...
    } 
}

Request Acknowledgement
The integrating partner should acknowledge that they have received the webhook payload by returning an HTTP status code of 200.

JSON

{
    "result": "SUCCESS"
}

Event Subscription

A Conferma partner system can be notified of any of the supported Event Types following an event type subscription, opt-in set-up is managed ad-hoc by the Conferma Implementations Team.

Card Authorisation Activity Event

🚧

Requires Card Issuer Support

This event requires that Conferma are receiving real-time card authorisation activity data from the card issuer platform.

Contact the Conferma Implementations Team to check support before coding to this webhook.

The notification content parameter for the Card Authorisation Activity Event Type is defined as follows:

Property	Data Type	Description	Example
deployment	object	Deployment details.
deployment.deploymentID	integer	Unique identifier for the Conferma Card Deployment.	1234567890
deployment.cardPoolID	integer	Unique identifier for the Conferma Card Pool.	1234
deployment.clientID	integer	Unique identifier for the Conferma Client.	4321
deployment.consumerID	integer	Unique identifier for the Conferma Consumer.	5432
deployment.supplierReference	string	Supplier booking or confirmation reference held for the Deployment.	REF1234
deployment.supplierName	string	Name of the Supplier or Merchant on the Deployment.	My Supplier
deployment.amount	decimal	Deployment amount.	200.00
deployment.amountCurrency	string	3-Letter ISO currency code for Deployment amount.	GBP
authorisation	object	Authorisation details.
authorisation.authorisationid	integer	Unique identifier for the authorisation.	4321
authorisation.transactionType	string	Enumeration of possible card activity transaction types identified by Conferma. Possible values: Authorisation, PreAuthorisation, AuthReversal.	Authorisation
authorisation.transactionDateTime	dateTime	Date & time the transaction occurred. Values are provided to Conferma by the relevant card issuing platform. Authorisation data and timestamps are set outside of the Conferma system.	"2022-03-02 15:32:14"
authorisation.merchantNarrative	string	The name or narrative provided by the merchant.	Supplier Inc.
authorisation.merchantCountry	string	2-Letter ISO country code.	GB
authorisation.merchantCategoryCode	string	Merchant Category Code.	1234
authorisation.originalAmount	decimal	Original amount charged by the merchant.	300.00
authorisation.originalCurrency	string	3-Letter ISO currency code for the originalAmount.	GBP
authorisation.billingAmount	decimal	Transaction amount in the billing currency of the card.	300.00
authorisation.billingCurrency	string	3-Letter ISO currency code for the billingAmount.	GBP
authorisation.authorisationCode	string	Authorisation code provided for the processing platform.	123456
authorisation.authorisationStatus	string	Enumeration of authorisation status. Possible values: PROCESSED, DECLINED.	DECLINED
authorisation.declineReason	string	Decline reason provided when the AuthorisationStatus is DECLINED.	Insufficient Funds

Sample Content Payload

JSON

{
   "Deployment":{
      "DeploymentID":789066233,
      "CardPoolID":"56432",
      "ClientID":1234,
      "ConsumerID":12,
      "SupplierReference":"REF1234A",
      "SupplierName":"My Supplier",
      "Amount":200.00,
      "AmountCurrency":"GBP"
   },
   "Authorisation":{
      "AuthorisationID":4321,
      "TransactionType":"Authorisation",
      "TransactionDateTime":"2020-03-02 15:32:14",
      "MerchantNarrative":"Supplier Inc.",
      "MerchantCountry":"GB",
      "MerchantCategoryCode":1234,
      "OriginalAmount":"200.00",
      "OriginalAmountCurrency":"GBP",
      "BillingAmount":"200.00",
      "BillingAmountCurrency":"GBP",
      "AuthorisationCode":"1235",
      "AuthorisationStatus":"PROCESSED",
      "DeclineReason":""
   }
}