Webhooks

You can configure webhook endpoints via the API to be notified about events that happen in your OpenCard account, so that your integration can automatically trigger reactions.

📘
Check out the "Setting up your Webhook Endpoint" page
The Setting up your Webhook Endpoint will show you step-by-step how to start using webhooks with your OpenCard integration.

Each event is defined by the request header X-Event. The different values of the header is explained below.

Choose the relevant webhooks for your service:

Tpa

tpa.signed

Invoice (coming soon)

invoice.created

Cardholder

card holder payload
card_holder.created
card_holder.identified
card_holder.signed.pdpc
card_holder.deleted
card_holder.email.failed
card_holder.email.delivered

Card Transactions

card transaction payload
card.transaction.authorized
card.transaction.deleted
card.transaction.cleared
card.transaction.invoiced

Additional Transaction Information

receipt.fetched
transaction.true.vat
transaction.line.items

Environmental Impact

environmental_impact.aland_index
environmental_impact.deedster

📘
ADD AUTHENTICATION
Select "use authentication" when configuring your webhooks. This allows you to add a key and value, which our client will include as a HTTP header in posted requests to you. See security guide for more info.

tpa.signed

Occurs when a tpa has been signed. back to top

{
  "id": "1",
  "name": "Test Inc.",
  "organization_number": "1234567890",
  "url": "https://sandbox-api.opencard.io/files/tpas/abc123",
  "organization": {
    "reference_id": "123ABC"
  }
}

invoice.created

Occurs when an invoice has been created. back to top

{
  "id": "1",
  "organization_number": "1234567890",
  "invoice_number": "12345678",
  "no_of_transactions": 11,
  "invoice_amount": 120.12,
  "invoice_currency": "USD",
  "invoice_date": "2023-01-01",
  "due_date": "2023-01-31"
}

card holder payload

Every card_holder.* event has the same payload. Below follows a field description of the payload.

Field	Description	Type
card_holder->reference_id	The reference of the card holder defined by the EMS.	String
organization->reference_id	The reference of the organization defined by the EMS.	String

card_holder.created

Occurs when a card holder has been created. back to top

{
  "card_holder": {
    "reference_id": "ABC123"
  },
  "organization": {
    "reference_id": "123ABC"
  }
}

card_holder.identified

Occurs when a card holder has been identified. back to top

{
  "card_holder": {
    "reference_id": "ABC123"
  },
  "organization": {
    "reference_id": "123ABC"
  }
}

card_holder.signed.pdpc

Occurs when a card holder has signed the Personal Data Processing Consent to release transactions for a certain TPA. back to top

{
  "card_holder": {
    "reference_id": "ABC123"
  },
  "organization": {
    "reference_id": "123ABC"
  }
}

card_holder.deleted

Occurs when a card holder has been deleted. back to top

{
  "card_holder": {
    "reference_id": "ABC123"
  },
  "organization": {
    "reference_id": "123ABC"
  }
}

card_holder.email.failed

Occurs when a card holders email couldn't be delivered. back to top

{
  "card_holder": {
    "reference_id": "ABC123"
  },
  "organization": {
    "reference_id": "123ABC"
  }
}

card_holder.email.delivered

Occurs when a card holders email is delivered. back to top

{
  "card_holder": {
    "reference_id": "ABC123"
  },
  "organization": {
    "reference_id": "123ABC"
  }
}

card transaction payload

Every card.transaction.* event has the same payload. Below follows a field description of the payload.

Field	Description	Type
id	A unique id of the transaction	String
state	The state of the transaction. Can be authorized, deleted, cleared or invoiced.	String
receiptable	Information if you can expect a a receipt for this transaction.	Boolean
card_issuer	The issuer of the transaction. Can be nordea.	String
card_issuer_reference	A reference from the card_issuer for the transaction state (not the transaction). May not be unique within a transaction.	String
type	Type of transaction. Can only be card.	String
invoice_number	The invoice number of the transaction. Can be null if the transaction has not been invoiced.	String
original_amount	The amount paid at the purchase place.	Float
original_currency	The currency of the amount paid at the purchase place following ISO 4217.	String
vat_rate	The vat rate reported by the purchase place. Can be null.	Integer
vat_amount	The vat amount reported by the purchase place. Can be null.	Float
vat_currency	The vat currency reported by the purchase place following ISO 4217. Can be null.	String
accounting_amount	The amount converted to the customers domestic currency.	Float
accounting_currency	The customers domestic currency following ISO 4217.	String
purchase_merchant	The name of the purchase merchant.	String
purchase_merchant_common	The common name of the purchase merchant.	String
purchase_date	The date of the purchase on format YYYY-MM-DD.	String
purchase_time	The time of the purchase on format HH:MM:SS including time zone. Can be null.	String
purchase_timezone	The timezone of the purchase. Can be null.	String
purchase_country	The country of the purchase following ISO 3166-1 alpha-3.	String
purchase_city	The city of the purchase.	String
card_id	Unique ID of the card.	Integer
card_product	Name of the card product	String
card_type	Type of card used in the purchase. Can be private, corporate or corporate_with_private_invoice.	String
card_last_four	The last four of the card used in the purchase.	String
mcc_code	The MCC code of the purchase.	String
mcc_text	The MCC text of the purchase. Can be null.	String
mcc_top_level	The MCC top level text.	String
branch_code	The branch code of the purchase. Can be null.	String
branch_text	The branch text of the purchase. Can be null.	String
category_text	The category text of the purchase.	String
card_holder->reference_id	The reference of the card holder defined by the EMS.	String
organization->reference_id	The reference of the organization defined by the EMS.	String

card.transaction.authorized

Occurs when a transaction is authorized. back to top

📘
Usage of card.transaction.authorized
It is highly recommended to use card.transaction.authorized in combination with card.transaction.cleared and card.transaction.deleted. An authorized transaction may be updated when cleared or deleted before it is cleared. A simplified view of the different transaction states for a transaction is:

card.transaction.authorized creates a new transaction

card.transaction.cleared updates an existing transaction

card.transaction.deleted deletes a transaction

{
  "id": "10",
  "state": "authorized",
  "receiptable": true,
  "card_issuer": "nordea",
  "card_issuer_reference": "654321",
  "type": "card",
  "invoice_number": null,
  "original_amount": 109.38,
  "original_currency": "SEK",
  "vat_rate": 0,
  "vat_amount": 0,
  "vat_currency": "SEK",
  "accounting_amount": 109.38,
  "accounting_currency": "SEK",
  "purchase_merchant": "Coop Vasagatan",
  "purchase_merchant_common": "Coop",
  "purchase_date": "2022-09-02",
  "purchase_time": "11:12:14",
  "purchase_country": "SE",
  "purchase_city": "STOCKHOLM",
  "card_id": 1,
  "card_product": "first_card",
  "card_type": "private",
  "card_last_four": "1234",
  "mcc_code": "5411",
  "mcc_text": null,
  "mcc_top_level": "Miscellaneous Stores",
  "category_text": "Card purchase",
  "card_holder": {
    "reference_id": "ABC123"
  },
  "organization": {
    "reference_id": "123ABC"
  }
}

card.transaction.deleted

📘
Usage of card.transaction.deleted
It is only relevant to use card.transaction.deleted when using card.transaction.authorized. A cleared transaction can not be deleted.

Occurs when a transaction is deleted. No more events will be sent after this event. back to top

{
  "id": "10",
  "state": "deleted",
  "receiptable": true,
  "card_issuer": "nordea",
  "card_issuer_reference": "654321",
  "type": "card",
  "invoice_number": null,
  "original_amount": 109.38,
  "original_currency": "SEK",
  "vat_rate": 0,
  "vat_amount": 0,
  "vat_currency": "SEK",
  "accounting_amount": 109.38,
  "accounting_currency": "SEK",
  "purchase_merchant": "Coop Vasagatan",
  "purchase_merchant_common": "Coop",
  "purchase_date": "2022-09-02",
  "purchase_time": "11:12:14",
  "purchase_country": "SE",
  "purchase_city": "STOCKHOLM",
  "card_id": 1,
  "card_product": "first_card",
  "card_type": "private",
  "card_last_four": "1234",
  "mcc_code": "5411",
  "mcc_text": null,
  "mcc_top_level": "Miscellaneous Stores",
  "category_text": "Card purchase",
  "card_holder": {
    "reference_id": "ABC123"
  },
  "organization": {
    "reference_id": "123ABC"
  }
}

card.transaction.cleared

Occurs when a transaction is cleared (follows within a few days after the card.transaction.authorized). back to top

{
  "id": "10",
  "state": "cleared",
  "receiptable": true,
  "card_issuer": "nordea",
  "card_issuer_reference": "123456",
  "type": "card",
  "invoice_number": null,
  "original_amount": 109.38,
  "original_currency": "SEK",
  "vat_rate": 18.53,
  "vat_amount": 17.1,
  "vat_currency": "SEK",
  "accounting_amount": 109.38,
  "accounting_currency": "SEK",
  "purchase_merchant": "Coop Vasagatan",
  "purchase_merchant_common": "Coop",
  "purchase_date": "2022-09-02",
  "purchase_time": null,
  "purchase_country": "SE",
  "purchase_city": "STOCKHOLM",
  "card_id": 1,
  "card_product": "first_card",
  "card_type": "private",
  "card_last_four": "1234",
  "mcc_code": "5411",
  "mcc_text": "GROCERY STORES, SUPERMARKETS",
  "mcc_top_level": "Miscellaneous Stores",
  "category_text": "Card purchase",
  "card_holder": {
    "reference_id": "ABC123"
  },
  "organization": {
    "reference_id": "123ABC"
  }
}

card.transaction.invoiced

Occurs when a transaction is updated with an invoice number. back to top

{
  "id": "10",
  "state": "invoiced",
  "receiptable": true,
  "card_issuer": "nordea",
  "card_issuer_reference": "123456",
  "type": "card",
  "invoice_number": "1234567890",
  "original_amount": 109.38,
  "original_currency": "SEK",
  "vat_rate": 18.53,
  "vat_amount": 17.1,
  "vat_currency": "SEK",
  "accounting_amount": 109.38,
  "accounting_currency": "SEK",
  "purchase_merchant": "Coop Vasagatan",
  "purchase_merchant_common": "Coop",
  "purchase_date": "2022-09-02",
  "purchase_time": null,
  "purchase_country": "SE",
  "purchase_city": "STOCKHOLM",
  "card_id": 1,
  "card_product": "first_card",
  "card_type": "private",
  "card_last_four": "1234",
  "mcc_code": "5411",
  "mcc_text": "GROCERY STORES, SUPERMARKETS",
  "mcc_top_level": "Miscellaneous Stores",
  "category_text": "Card purchase",
  "card_holder": {
    "reference_id": "ABC123"
  },
  "organization": {
    "reference_id": "123ABC"
  }
}

receipt.fetched

Occurs when a purchase place publish a receipt. back to top

{
  "url": "https://sandbox-api.opencard.io/files/receipts/abc123",
  "content_type": "application/pdf",
  "expiration_time": "2022-10-19 13:23:08",
  "purchase_merchant": "Store X",
  "original_amount": 109.38,
  "original_currency": "SEK",
  "purchase_date": "2022-09-02",
  "purchase_time": "11:12:14",
  "transaction": {
    "id": "10",
    "card_issuer": "nordea"
  },
  "card_holder": {
    "reference_id": "ABC123"
  },
  "organization": {
    "reference_id": "123ABC"
  }
}

transaction.true.vat

Card as well as travel accounts transactions contains incorrect vat. You can get the correct VAT from connected merchants by subscribing on the true vat webhook. back to top

{
  "transaction": {
    "id": "10",
    "card_issuer": "nordea"
  },
  "organization": {
    "reference_id": "123ABC"
  },
  "card_holder": {
    "reference_id": "ABC123"
  },
  "purchase_country": "SE",
  "vat_rates": [
    {
      "vat_amount": 5.52,
      "taxable_amount": 45.96,
      "total_amount": 51.48,
      "percentage": 12,
      "currency": "SEK"
    },
    {
      "vat_amount": 11.58,
      "taxable_amount": 46.32,
      "total_amount": 57.90,
      "percentage": 25,
      "currency": "SEK"
    }
  ],
  "totals": [
    {
      "vat_amount": 17.1,
      "taxable_amount": 92.29,
      "total_amount": 109.38,
      "currency": "SEK"
    }
  ]
}

transaction.line.items

When a purchase merchant publishes a receipt, the line items of that purchase can be sent if you subscribe on the transaction.line.items event. back to top

{
  "transaction": {
    "id": "10",
    "card_issuer": "nordea"
  },
  "organization": {
    "reference_id": "123ABC"
  },
  "card_holder": {
    "reference_id": "ABC123"
  },
  "line_items": [
    {
      "description": "Coffee",
      "amount": 5,
      "total_amount": 10,
      "quantity": 2,
      "currency": "USD"
    }
  ]
}

environmental.impact.aland_index

Occurs when a transaction calculates the environmental impact using Åland Index. back to top

For more info about the Åland climate impact index, see external link.

{
  "carbon_emission_in_grams": 0.66,
  "carbon_social_cost_amount": 2.1,
  "carbon_social_cost_currency": "SEK",
  "transaction": {
    "id": "10",
    "card_issuer": "nordea"
  },
  "organization": {
    "reference_id": "123ABC"
  },
  "card_holder": {
    "reference_id": "ABC123"
  }
}

environmental.impact.deedster

Occurs when a transaction calculates the environmental impact using Deedster. back to top

For more info about the Deedster climate impact, see external link.

{
  "carbon_emission_in_grams": 0.66,
  "carbon_social_cost_amount": 2.1,
  "carbon_social_cost_currency": "SEK",
  "transaction": {
    "id": "10",
    "card_issuer": "nordea"
  },
  "organization": {
    "reference_id": "123ABC"
  },
  "card_holder": {
    "reference_id": "ABC123"
  }
}

Webhooks

📘
Check out the "Setting up your Webhook Endpoint" page

Tpa

Invoice (coming soon)

Cardholder

Card Transactions

Additional Transaction Information

Environmental Impact

📘
ADD AUTHENTICATION

tpa.signed

invoice.created

card holder payload

card_holder.created

card_holder.identified

card_holder.signed.pdpc

card_holder.deleted

card_holder.email.failed

card_holder.email.delivered

card transaction payload

card.transaction.authorized

📘
Usage of card.transaction.authorized

card.transaction.deleted

📘
Usage of card.transaction.deleted

card.transaction.cleared

card.transaction.invoiced

receipt.fetched

transaction.true.vat

transaction.line.items

environmental.impact.aland_index

environmental.impact.deedster

📘Check out the "Setting up your Webhook Endpoint" page

Tpa

Invoice (coming soon)

Cardholder

Card Transactions

Additional Transaction Information

Environmental Impact

📘ADD AUTHENTICATION

tpa.signed

invoice.created

card holder payload

card_holder.created

card_holder.identified

card_holder.signed.pdpc

card_holder.deleted

card_holder.email.failed

card_holder.email.delivered

card transaction payload

card.transaction.authorized

📘Usage of card.transaction.authorized

card.transaction.deleted

📘Usage of card.transaction.deleted

card.transaction.cleared

card.transaction.invoiced

receipt.fetched

transaction.true.vat

transaction.line.items

environmental.impact.aland_index

environmental.impact.deedster

📘
Check out the "Setting up your Webhook Endpoint" page

📘
ADD AUTHENTICATION

📘
Usage of card.transaction.authorized

📘
Usage of card.transaction.deleted