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
Invoice (coming soon)
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": "Business 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": "Business 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": "Business 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": "Business 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"
}
}