# Viacash

## Introduction

Note
In order to use this feature, you must have [device signing](/guides/authentication/strong-customer-authentication/#implement-device-signing) implemented in your solution.

The **viacash** feature allows customers to make cash deposits and withdrawals
to and from their Solaris accounts.

Once you implement this feature, customers will be able to use your solution to
request a barcode to display at the point-of-sale (POS) at a [participating
retailer](https://www.viacash.com/) (i.e., the cash register). The merchant will
verify the barcode, and the customer will either give or receive cash at the
cash register. Solaris and [Viafintech](https://www.viafintech.com) verify
these transactions in their systems. Customers do not have to make in-store
purchases in order to use the Viacash feature.

Viafintech acts as the technical service provider of the cash payment
infrastructure for this feature via [Grenke Bank AG](https://www.grenke.de),
Solaris' partner bank.

This guide explains how this process works from a technical standpoint and how
to implement this feature in your solution.

### Terminology

In the Solaris API, cash withdrawals and deposits together constitute **cash
operations.** They are managed by the Cash Operations API. The API refers to
withdrawals as **pay-outs** and deposits as **pay-ins.**

### Participating retailers

You can find a list of retailers where customers can use this feature on the
[viacash website](https://www.viacash.com/).

### Limits

For risk-related reasons, Solaris and Viafintech have imposed a limit of
**999.99 EUR** in combined pay-ins and pay-outs per person per 24 hours
(rolling).

At request, Solaris can impose additional limits on pay-ins and pay-outs.
See the table below for a full list of possible dimensions to limit:

| Dimension | Transaction type | Time period |
|  --- | --- | --- |
| Person | Pay-out | Per 24h (rolling) |
| Person | Pay-out | Per operation |
| Person | Pay-in | Per 24h (rolling) |
| Person | Pay-in | Per operation |
| Person | Combined | Per 24h (rolling) |
| Account | Combined | Per 24h (rolling) |


## Diagram: Pay-out/pay-in user flow

![Diagram: Pay-out/pay-in user flow](/assets/cash-operations.494557a290803ebcbd47f6be565cb1a37c367ad51375577fd44f57e020e2e8f5.8793f243.png)

1. The customer requests a cash operation (pay-out/pay-in) in your solution.
2. Your solution calls the [POST Request cash operation
barcode](#post-request-cash-operation) method, specifying in the request body
whether it is a `payout` or `payin`.
3. Solaris runs a series of verification checks on the cash operation:
  - The account must be active.
  - The account must not be blocked/debit blocked.
  - The person requesting the operation must be authorized to act on the account.
  - (For payouts) The amount must be less than or equal to the available balance.
  - The cash operation does not exceed any of the [limits](#limits).
  - The person may not have more than one open cash operation request of each type.
  - The account must not be in close monitoring (compliance).
4. If the checks pass, then Solaris initiates the [change request process](/guides/authentication/strong-customer-authentication/#change-request).
The customer receives a [2FA challenge](/guides/authentication/strong-customer-authentication)
to confirm the transaction.
  - Solaris creates a cash operation resource with a `status` of `PENDING`.
  - Solaris also blocks the withdrawal/deposit amount on the customer's
account by creating a reservation. The reservation has the type
`CashWithdrawalRetail` for pay-outs, `CashDepositRetail` for pay-ins.
5. The customer confirms the change request, and your solution passes this
confirmation to the [POST Confirm change request](/api-reference/onboarding/device-management/#tag/Change-requests/paths/~1v1~1change_requests~1%7Bchange_request_id%7D~1confirm/post) endpoint.
6. Viafintech generates the barcode and sends it to Solaris.
7. Solaris returns the `id` of the cash operation resource in the `request_body` attribute of the [POST Confirm change request](/api-reference/onboarding/device-management/#tag/Change-requests/paths/~1v1~1change_requests~1%7Bchange_request_id%7D~1confirm/post) response.
8. Your solution calls the [GET Retrieve a cash operation](#get-retrieve-a-cash-operation) method using the `id` from the response.
9. Your solution generates an [EAN-13 barcode](https://www.cognex.com/resources/symbologies/1-d-linear-barcodes/ean-13-barcodes) based on the `barcode_ean_13` property of the cash operation and displays it to the customer.
10. The customer goes to a participating retailer and shows the barcode.
11. The merchant scans the barcode. The customer then either receives cash from
the merchant or hands cash to the merchant based on whether the cash
operation is a `payout` or `payin`.
12. Viafintech confirms the cash operation.
13. Solaris creates a booking, sends a notification via webhook, and
resolves the reservation.
  - The `type` of the booking is either `CashWithdrawalRetail` (for pay-outs)
or `CashDepositRetail` (for pay-ins).


## API documentation

### Webhooks

#### CASH_OPERATION_STATUS_CHANGED

Webhooks are intended only for informational purposes. In your solution, please
use the respective GET endpoints for interacting with cash operation resources
instead of acting directly on the data contained in the webhook.

Subscribe to the `CASH_OPERATION_STATUS_CHANGED` webhook to receive updates when
a customer acts on a cash operation or when it expires.

Possible status values:

- `PAID`
- `CANCELLED`
- `EXPIRED`


**Example payload:**


```json
{
  "id": "ffb18faf3c004f70a44c83b787488ceeslip",
  "barcode_ean13": "4053110826660",
  "expires_at": "2022-01-04T09:15:59.958864Z",
  "status": "PAID",
  "reference_id": "f92beb45-b46e-4733-be1a-80c085cbad0d",
  "person_id": "2231bdf43cf7b9041367d9ed5c6d4c7acper"
}
```

### POST Request cash operation

Note
This method requires confirmation via the [change request process.](/guides/authentication/strong-customer-authentication/#change-request) Your customer must confirm the change request using [device signing.](/guides/authentication/strong-customer-authentication/#implement-device-signing)

This method requests a barcode for the customer to present at the POS of a
participating Viacash retailer in order to complete a pay-in or pay-out.

Once the customer confirms the change request, Viafintech processes the request,
and then the Solaris API returns a payload containing an [EAN-13
barcode](https://www.cognex.com/resources/symbologies/1-d-linear-barcodes/ean-13-barcodes)
with an expiration date and a status. See the [payload example
below](#payload-after-change-request-confirmation) for more information.

- Each customer may only have one active pay-in request and one active pay-out
request at a time (i.e., requests with the status `CREATED` or `PENDING`).
- The maximum amount per cash operation is 300 EUR.


#### Request attributes

| Property | Type | Description |
|  --- | --- | --- |
| `idempotency_key` | string | Use a randomly-generated ID to ensure the uniqueness of the request to the Solaris API. |
| `reference` | string | End-to-end reference for the customer. |
| `provider` | string | Must contain the value `barzahlen`. |
| `type` | string(enum) | Defines the type of cash operation. Possible values are `PAYOUT` (for withdrawals) and `PAYIN` (for deposits). |
| `amount` | object | The amount of the cash operation, in Euro cents.currencyunitvalue |


#### Example request


```json
// POST /v1/persons/{person_id}/accounts/{account_id}/cash_operations
{
  "idempotency_key": "8695a767-2d7b-460b-9c4c-dceb82fb6566",
  "reference": "de430446-1da7-4adf-b440-be6005b5cf9f",
  "provider": "barzahlen",
  "type": "PAYIN",
  "amount": {
    "currency": "EUR",
    "unit": "cents",
    "value": 5000
  }
}
```

#### Example response


```json
// HTTP/1.1 201 Created
{
  "change_request_id": "de430446-1da7-4adf-b440-be6005b5cf9f",
  "id": "8695a767-2d7b-460b-9c4c-dceb82fb6566"
}
```

#### Payload after change request confirmation


```json
{
    "id": "de430446-1da7-4adf-b440-be6005b5cf9f",
    "status": "COMPLETED",
    "updated_at": "2021-09-29T14:20:25.000Z",
    "response_body": {
        "id": "ffb18faf3c004f70a44c83b787488ceeslip",
        "barcode_ean13": "4053110826660",
        "expires_at": "2021-09-29T15:20:12.424687Z",
        "status": "CREATED",
        "reference_id": "de430446-1da7-4adf-b440-be6005b5cf9f",
        "person_id": "5af2ea4271038d5c53e68ccbf4fe43b3cper"
    },
    "response_code": 200
}
```

[Click here to view the full API reference.](/api-reference/digital-banking/transactions/#operation/solaris_account_cash_service_cash_operations_create)

### GET Retrieve a cash operation

This method returns a single cash operation. Use the `id` of the cash operation in the request URL.

#### Example request


```shell
GET /v1/accounts/{account_id}/cash_operations/{cash_operation_id}
```

#### Example response


```json
// HTTP/1.1 200 OK
{
  "id": "b56c770a-4ed8-4542-9a51-c4b2c70c09ee",
  "barcode_ean_13": "4051234567890",
  "expires_at": "2021-10-21T14:36:58.207Z",
  "status": "PENDING",
  "reference_id": "34abaa5a-cd7a-4d1c-80e7-e3d48eb8efef",
  "person_id": "587d8a5d-20c0-4a2f-852c-361787ac2e28"
}
```

[Click here to view the full API reference.](/api-reference/digital-banking/transactions/#operation/solaris_account_cash_service_cash_operations_find)

### GET List all cash operations

This method returns a paginated list of all cash operations associated with a specific account.

#### Filters

You can filter the results in this request by appending the following string to the request URL:

`filter[status]`

#### Example request


```shell
GET /v1/accounts/{account_id}/cash_operations
```

#### Example response


```json
// HTTP/1.1 200 OK
[
  {
    "id": "b56c770a-4ed8-4542-9a51-c4b2c70c09ee",
    "barcode_ean_13": "4051234567890",
    "expires_at": "2021-10-21T14:36:58.207Z",
    "status": "PENDING",
    "reference_id": "34abaa5a-cd7a-4d1c-80e7-e3d48eb8efef",
    "person_id": "587d8a5d-20c0-4a2f-852c-361787ac2e28"
  },
  {
    "id": "1c641102-b50d-4565-9e31-fdef7246e9e8",
    "barcode_ean_13": "4051434567830",
    "expires_at": "2021-10-21T14:00:58.207Z",
    "status": "PAID",
    "reference_id": "70fa983c-6c22-49f3-b9ad-69af81668494",
    "person_id": "587d8a5d-20c0-4a2f-852c-361787ac2e28"
  }
]
```

[Click here to view the full API reference.](/api-reference/digital-banking/transactions/#operation/solaris_account_cash_service_cash_operations_all)

### DELETE Cancel cash operation

This method cancels the cash operation specified in the request URL. This will
trigger the `CASH_OPERATION_STATUS_CHANGED` webhook.

#### Example request


```shell
DELETE /v1/accounts/{account_id}/cash_operations/{cash_operation_id}
```

#### Example response


```shell
HTTP/1.1 204 Deleted
```

[Click here to view the full API reference.](/api-reference/digital-banking/transactions/#operation/solaris_account_cash_service_cash_operations_delete)

### (Sandbox only) PATCH Test cash operation process

This endpoint allows you to manually update the status of a cash operation. You may only use this endpoint on Sandbox.

This endpoint accepts the following values for updating the `status` of the cash operation:

- `PAID`
- `EXPIRED`
- `CANCELLED`


#### Example request


```json
// PATCH /v1/accounts/{account_id}/cash_operations/{cash_operation_id}
{
  "status": "PAID"
}
```

#### Example response


```shell
HTTP/1.1 204 No Content
```

[Click here to view the full API reference.](/api-reference/digital-banking/transactions/#operation/solaris_account_cash_service_cash_operations_emulate-events)