last_4_digits" => "6789",
    "email" => "<EMAIL>",
    "language" => "de-DE"
  },
  "metadata" => {
    "order_id" => "1234",
    "invoice_no" => "A123"
  },
  "transactions" => [
    {
      "id" => "4729294329",
      "currency" => "EUR",
      "amount" => "123.34",
      "state" => "pending"
    }
  ]
}
```

Content can be looked up [here][api_documentation_update].

### Resend Slip Email

Resending a slip email is done as following:

```ruby
Barzahlen.resend_email(slip_id)
```

For further information please refer to the [viafintech API v2 resend documentation][api_documentation_resend].

### Resend Slip Text Message

Resending a slip text message is done as following:

```ruby
Barzahlen.resend_text_message(slip_id)
```

For further information please refer to the [viafintech API v2 resend documentation][api_documentation_resend].

### Invalidate Slip

Invalidating a slip is done as following:

```ruby
Barzahlen.invalidate_slip(slip_id)
```

As a response you can get:

```ruby
{
  "id" => "slp-d90ab05c-69f2-4e87-9972-97b3275a0ccd",
  "slip_type" => "payment",
  "division_id" => "1234",
  "reference_key" => "O64737X",
  "hook_url" => "https://psp.example.com/hook",
  "expires_at" => "2016-01-10T12:34:56Z",
  "customer" => {
    "key" => "<KEY>",
    "cell_phone_last_4_digits" => "6789",
    "email" => "<EMAIL>",
    "language" => "de-DE"
  },
  "metadata" => {
    "order_id" => "1234",
    "invoice_no" => "A123"
  },
  "transactions" => [
    {
      "id" => "4729294329",
      "currency" => "EUR",
      "amount" => "123.34",
      "state" => "pending"
    }
  ]
}
```

For a full list of all response variables please refer to the [viafintech API v2 invalidate slip documentation][api_documentation_invalidate].

### Webhook Handling

When a slip is paid or expires, a webhook request is issued to the url you provided individually in the slip or in the [viafintech Control Center App][control_center_app].

In sandbox mode you can manually trigger a `paid` or `expired` webhook request in the [Control Center App][control_center_app].

The webhook request is also signed as normal requests to the API with the aforementioned `payment_key`. But don't worry about the signature check because this library will take care of it.

If the signature check is failing a **Barzahlen::Error::SignatureError** is raised.

For further documentation please refer to the [webhooks viafintech API v2 documentation][api_documentation_webhooks].

The notification handling is expecting an Object in the following structure:

```ruby
request = {
  "Bz-Hook-Format" => "v2",
  "Host" => "callback.example.com",
  "Path" => "/barzahlen/callback",
  "Port" => "443",
  "Date" => "Fri, 01 Apr 2016 09:20:06 GMT",
  "Method" => "POST",
  "Bz-Signature" => "BZ1-HMAC-SHA256 eb22cda264a5cf5a138e8ac13f0aa8da2daf28c687d9db46872cf777f0decc04",
  "Body" => '{
    "event": "paid",
    "event_occurred_at": "2016-01-06T12:34:56Z",
    "affected_transaction_id": "4729294329",
    "slip": {
        "id": "slp-d90ab05c-69f2-4e87-9972-97b3275a0ccd",
        "slip_type": "payment",
        "division_id": "1234",
        "reference_key": "O64737X",
        "expires_at": "2016-01-10T12:34:56Z",
        "customer": {
            "key": "<KEY>",
            "cell_phone_last_4_digits": "6789",
            "email": "<EMAIL>",
            "language": "de-DE"
        },
        "metadata": {
          "order_id": 1234,
          "invoice_no": "A123"
        },
        "transactions": [
          {
            "id": "4729294329",
            "currency": "EUR",
            "amount": "123.34",
            "state": "paid"
          }
        ]
    }
}'
}
```

Method (default `POST`) and port (default `443`) are optional. (If you want to try out this request, the `payment_key` is `<KEY>`)

A request of this type can then be passed to the webhook request method:
```ruby
request_hash = Barzahlen.webhook_request(request)
```

The following can happen:

* If the request is an API v1 webhook request: nil is returned.
* If the signature check is not successful: a `SignatureError` is raised.
* If the everything works fine: a hash with the content is returned.

Example hash response:

```ruby
{
  "event" => "paid",
  "event_occurred_at" => "2016-01-06T12:34:56Z",
  "affected_transaction_id" => "4729294329",
  "slip" => {
    "id" => "slp-d90ab05c-69f2-4e87-9972-97b3275a0ccd",
    "slip_type" => "payment",
    "division_id" => "1234",
    "reference_key" => "O64737X",
    "expires_at" => "2016-01-10T12:34:56Z",
    "customer" => {
      "key" => "<KEY>",
      "cell_phone_last_4_digits" => "6789",
      "email" => "<EMAIL>",
      "language" => "de-DE"
    },
    "metadata" => {
      "order_id" => 1234,
      "invoice_no" => "A123"
    },
    "transactions" => [
      {
        "id" => "4729294329",
        "currency" => "EUR",
        "amount" => "123.34",
        "state" => "paid"
      }
    ]
  }
}
```

For further documentation about webhooks please refer to [webhook documentation][api_documentation_webhooks].

## Interprete API Error and Return

### API Client Errors

Errors will be generated and raised based on the [viafintech API v2 error response][api_documentation_error] information.

The `error_class`, which is explained on [viafintech API v2 Documentation][api_documentation_error] is used as the error name:

* Barzahlen::Error::AuthError
* Barzahlen::Error::TransportError
* Barzahlen::Error::IdempotencyError
* Barzahlen::Error::RateLimitError
* Barzahlen::Error::InvalidFormatError
* Barzahlen::Error::InvalidStateError
* Barzahlen::Error::InvalidParameterError
* Barzahlen::Error::NotAllowedError
* Barzahlen::Error::ServerError
* Barzahlen::Error::UnexpectedError -> Is raised when no interpretation of the error response was possible.

All these Errors are of type `Barzahlen::Error::ApiError`.

If the interpretation was successful you will get an error where you can access the information the following:

```ruby
error.error_class # The error_