Payment webhook

POST

Receive signed payment event notifications.

Parameters

Header Parameters

webhook-id

required

string format: uuid

Example

3f62fc97-907a-4212-af02-8c30f1ea1927

Unique identifier for this webhook delivery

webhook-timestamp

required

integer format: int64

Example

1674087231

Unix timestamp when the webhook was sent

webhook-signature

required

string

Example

v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= v1a,hnO3f9T8Ytu9HwrXslvumlUpqtNVqkhqw/enGzPCXe5BdqzCInXqYXFymVJaA7AZdpXwVLPo3mNl8EM+m7TBAg==

Signatures used to verify the webhook

Request Body^required

Media typeapplication/json

object

id

required

Unique identifier for the webhook event

string format: uuid

Example

3f62fc97-907a-4212-af02-8c30f1ea1927

timestamp

required

Timestamp when the webhook was generated

string format: date-time

Example

2025-04-24T13:45:10Z

type

required

Type of notification - original webhook or a retry

string

Allowed values: payment_callback invoice_declined payment_callback_retry (deprecated, use the same type as for the original webhook with the knowledge that it can be a retry)

data

required

One of:

payment_callback

payment_callback

The data sent when the payload type field has the value payment_callback or payment_callback_retry.

object

content_key

required

Key of the content associated with this payment

string

Example

1691677075a9813e08f783496382b0bff743ec34ae

due_date

Date when the payment was due

string format: date

Example

2025-05-01

pay_date

Date when the payment was made

string format: date

Example

2025-04-24

destination_account_type

Type of destination account

string

Allowed values: bankgiro plusgiro

destination_account

Destination account number

string

Example

12345-6789

remittance_type

Type of remittance information

string

Allowed values: SE_OCR TENANT_REF

remittance_string

Reference string used for the payment

string

Example

426523791

option_title

Title of the payment option if multiple options were available

string

Example

Full payment

option_id

Identifier of the selected payment option

string

Example

option_1

payment_type

required

Type of payment method used

string

Allowed values: instant bank autogiro

payment_event

required

The payment event that triggered this webhook

string

Allowed values: settled scheduled failed

event_time

required

Time when the payment event occurred

string format: date-time

Example

2025-04-24T13:44:58Z

swish_alias

Swish alias used for the payment, if applicable

string

Example

1234567890

swish_payment_reference

Swish payment reference, if applicable

string

Example

652ED6A2BCDE4BA8AD11D7334E9567B7

amount

required

Payment amount as a string

string

Example

123.50

currency

required

Currency code for the payment

string

Example

SEK

invoice_declined

invoice_declined

The data sent when the payload type field has the value invoice_declined or invoice_declined_retry. In all cases below where some information is specified as coming from the invoice, it more precisely comes from the first fixed option of the invoice.

object

content_key

required

The Kivra key for the invoice that was declined.

string

Example

1708693835ca2a6459d02d4c7fb50b19acaffcb624

due_date

required

Due date from the invoice.

string format: date

Example

2025-05-01

remittance_type

required

Type of remittance information.

string

Allowed values: SE_OCR TENANT_REF

remittance_string

required

Reference string from the invoice.

string

Example

426523791

event_time

required

Time when the declining event occurred.

string format: date-time

Example

2025-04-24T13:44:58Z

content_type

required

The type of the content that was declined.

string

Allowed values: invoice.renewal invoice.donation

Responses

200

Return a 200 status to acknowledge receipt of the webhook. Any other response will cause Kivra to retry the delivery, which will happen up to 10 times with increasing intervals.