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.

FieldDescriptionType
card_holder->reference_idThe reference of the card holder defined by the EMS.String
organization->reference_idThe 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.

FieldDescriptionType
idA unique id of the transactionString
stateThe state of the transaction. Can be authorized, deleted, cleared or invoiced.String
receiptableInformation if you can expect a a receipt for this transaction.Boolean
card_issuerThe issuer of the transaction. Can be nordea.String
card_issuer_referenceA reference from the card_issuer for the transaction state (not the transaction). May not be unique within a transaction.String
typeType of transaction. Can only be card.String
invoice_numberThe invoice number of the transaction. Can be null if the transaction has not been invoiced.String
original_amountThe amount paid at the purchase place.Float
original_currencyThe currency of the amount paid at the purchase place following ISO 4217.String
vat_rateThe vat rate reported by the purchase place. Can be null.Integer
vat_amountThe vat amount reported by the purchase place. Can be null.Float
vat_currencyThe vat currency reported by the purchase place following ISO 4217. Can be null.String
accounting_amountThe amount converted to the customers domestic currency.Float
accounting_currencyThe customers domestic currency following ISO 4217.String
purchase_merchantThe name of the purchase merchant.String
purchase_merchant_commonThe common name of the purchase merchant.String
purchase_dateThe date of the purchase on format YYYY-MM-DD.String
purchase_timeThe time of the purchase on format HH:MM:SS including time zone. Can be null.String
purchase_timezoneThe timezone of the purchase. Can be null.String
purchase_countryThe country of the purchase following ISO 3166-1 alpha-3.String
purchase_cityThe city of the purchase.String
card_idUnique ID of the card.Integer
card_productName of the card productString
card_typeType of card used in the purchase. Can be private, corporate or corporate_with_private_invoice.String
card_last_fourThe last four of the card used in the purchase.String
mcc_codeThe MCC code of the purchase.String
mcc_textThe MCC text of the purchase. Can be null.String
mcc_top_levelThe MCC top level text.String
branch_codeThe branch code of the purchase. Can be null.String
branch_textThe branch text of the purchase. Can be null.String
category_textThe category text of the purchase.String
card_holder->reference_idThe reference of the card holder defined by the EMS.String
organization->reference_idThe 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"
  }
}