Viacash

Introduction

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 (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 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, 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.

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:

Diagram: Pay-out/pay-in user flow

1. The customer requests a cash operation (pay-out/pay-in) in your solution.
2. Your solution calls the POST Request cash operation barcode 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.
   • 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. The customer receives a 2FA challenge 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 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 response.
8. Your solution calls the GET Retrieve a cash operation method using the id from the response.
9. Your solution generates an EAN-13 barcode 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

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:

{
  "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

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 with an expiration date and a status. See the payload example below for more information.

Request attributes

Example request

// 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

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

Payload after change request confirmation

{
    "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.

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

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

Example response

// 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.

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

GET /v1/accounts/{account_id}/cash_operations

Example response

// 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.

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

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

Example response

HTTP/1.1 204 Deleted

Click here to view the full API reference.

(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

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

Example response

HTTP/1.1 204 No Content

Click here to view the full API reference.