Introduction

viafintech API v2 allows you to create payment, partial payment, payout, and refund slips customers can use in stores like supermarkets to pay or receive money. Slips are sent to users as an email with a PDF attachment or as a text message. When a store's point of sale system confirms the transaction, viafintech usually immediately calls a Webhook to notify your system about the payment. You can then use this confirmation e.g. to mark an invoice as paid or trigger shipping goods to the customer.

The name viafintech refers to the company viafintech GmbH. The names Barzahlen and viacash refer to the same product. For the remainder of the document we will refer to it as viacash.

The API is a JSON-based REST API.

We provide client libraries for the following programming languages:

• PHP: Barzahlen Package
• Ruby: Barzahlen Gem

Functionality

• Create slip: Create a payment, payout, or refund slip and send them to the customer via email or text message.
• Retrieve slip: Retrieve information, including transaction state (pending, paid, etc.)
• Update slip: Update certain fields, e.g. when a customer accidentally entered a wrong email address.
• Resend slip: Resend the mail or text message for a slip, useful e.g. when a customer accidentally deleted a message.
• Invalidate slip: Invalidate a slip, so a customer can no longer pay it or receive money for it.

Slip Types

• Payment: A slip a customer can pay and you will receive money for, used e.g. when a customer orders a product in an online shop.
• Partial Payments: A slip a customer can pay multiple times and you will receive money for each time, used e.g. when a customer pays their monthly electricity bill.
• Payout: A slip paying money out to a customer, used e.g. when a customer withdraws cash from their bank account.
• Refund: A slip returning money to a customer, related to a previous payment through viacash. Used e.g. when a customer returns a product to an online shop.

If you have any problems with your integration, regarding any of the slip types, please contact us.

Slip States

A slip is in one of four states, all except pending are final.

• pending: Slip is valid and can be used by the customer.
• locked: Slip has been scanned and cannot be invalidated or expired at the moment. This state is not returned by default and needs to be enabled by viafintech.
• paid: Slip has been paid (final state).
• expired: Slip was not paid before expiry date and can no longer be used (final state).
• invalidated: Slip was explicitly invalidated and can no longer be used (final state).
• declined: Slip was declined and can no longer be used (final state).

Identifying a customer

To reduce money laundering, we are required to store an identifier that is unique per customer. Depending on your contract with viafintech, this can be an email address or an internal customer identifier. You must provide the identifier in the customer key field. If you provide an email address as customer key, you must use the same email address in the email field.

Accessing the API

The API is accessible via HTTPS and uses JSON as format for requests and responses. As REST-API, it uses different HTTP methods to indicate the type of request and response codes for indicating the outcome of a request. For errors, it returns additional, more specific error classes, codes, and messages.

The API endpoints are:

• Production: https://api.viafintech.com/v2
• Sandbox: https://api-sandbox.viafintech.com/v2 (use this for development)

HTTPS/TLS Protocols and Certificates

We employ TLS protocols to ensure secure communications between our systems and our partners' systems. Our systems currently supports both TLS 1.2 and TLS 1.3, using a range of secure encryption ciphers. We expect our partners to implement support for these protocols in their systems as well, to guarantee secure data transmission.

Additionally, we require our partners to maintain an up-to-date list of trusted root certificates (CA Root certificates). This ensures that new HTTPS/TLS connections can be properly verified and trusted, mitigating the risk of man-in-the-middle attacks. We strongly recommend always verifying HTTPS server certificates against trusted root certificates. This includes validating the certificate chain and verifying the server name(s) against the certificate. Refer to your HTTP client’s documentation for details on performing these and other required checks.

To facilitate secure integration, we provide a curated bundle of root certificates (download below) from reputable Certificate Authorities (CAs) that we currently or may in the future use for obtaining certificates for this API. Feel free to integrate this list into your systems to establish secure and reliable connections to our API services or you can also rely on your already existing system trust store. By using either this tailored certificate bundle or your system trust store, you can ensure a seamless and secure experience while making the renewal of our certificates effortless on your end.

• viafintech CA Bundle 2024-12 (combined PEM)
• viafintech CA Bundle 2024-12 (ZIP / contains individual PEM files)

Sandbox

Sandbox mode allows working on slips that can not actually be paid in a store. Instead, you can use the viafintech App to simulate payment and expiry and receive webhooks for these events. Text messages are not sent in sandbox mode, but emails are.

In contrast to the production endpoint, the sandbox endpoint is available immediately after you sign up, so you can begin integrating viacash as soon as possible.

Optional Features

• Barcode Field: Certain API responses that contain payment, partial payment, payout, or refund slip data may include the EAN-13/Code-128 barcode number of the affected slip. This number represents the barcode the customer gives to a cashier in a store. The customer usually receives the barcode in an email and/or text message from viacash. Depending on your use case it might be a better solution to display the barcode number to your customers directly. Due to security reasons this setting is disabled by default and can only be enabled by viafintech. Please feel free to contact us if you are interested in using this feature. Depending on the region of processing the barcode_code128 or barcode_ean13 field might be applicable.

• PDF Slip Download: See Retrieve Slip PDF.

• paid_at_store Object: Certain API responses that contain payment, partial payment, payout, or refund slip data may include information about where a specific transaction of a slip is paid. For customer privacy reasons this information is usually not returned. In some cases however there is a legal requirement e.g. to prevent money laundering, or other abusive behaviours of the division's system. This results in the setting not being enabled by default. It can only be enabled by viafintech. When enabled, the paid_at_store Object will only be part of the information if the transaction is paid. In rare cases the detailed store information might not be available to viafintech, in which case it will also not be returned for paid transactions. Additionally when the transaction is in a different state than paid (e.g. expired) the paid_at_store Object will not be part of the information provided. Please fee free to contact us if you are interested in using this feature.

• Know your Customer Fields: Depending on the country where the slip is being processed and the regulations in place there, you might need to send the Know your Customer (KYC) fields when creating a slip. This setting is disabled by default and can only be enabled by viafintech. Please feel free to contact us if you are unsure if you need to provide this information for your use case. Know your Customer Fields are:

  • country
  • customer:address:city
  • customer:address:country
  • customer:address:street_and_no
  • customer:address:zipcode - Optional for addresses from Ireland (customer:address:country is IE)
  • customer:document:id_number
  • customer:document:issuing_authority
  • customer:document:type
  • customer:first_name
  • customer:last_name
  • customer:ip_address
  • customer:kyc_type
  • customer:place_of_birth
  • customer:tax_id - Required for Italy
  • customer:mcc - Mandatory and only allowed for KYB

• Slip Country Field: Depending on the configuration for your division it might be necessary to provide the country in which the transaction(s) of the slip should be processible. If not given, it will default to value setup for your division. Please feel free to contact us if you are unsure if you need to provide this information for your use case.

Authentication

For authentication, the API requires requests to be signed using your API key. You will never have to include your API key in plain text in a request, only as part of the signature. We use the same signature algorithm to sign webhook requests to your system.

For authentication and webhook signature verification, you will need your division id and your API key. You can find both in the viafintech App under Settings / Divisions.

See Accessing the API for information about HTTPS certificate verification.

API Requests

Authorization header format for API requests

Authorization: BZ1-HMAC-SHA256 DivisionId=ID, Signature=SIGNATURE

For requests, the API expects a standard HTTP Authorization header with a custom authentication scheme, BZ1-HMAC-SHA256.

Replace ID with your division's ID and SIGNATURE with a signature based on certain parts of the request. The algorithm for calculating the signature is described below.

Example Date header

Date: Tue, 15 Nov 1994 08:12:31 GMT

The signature includes the current time, which must be included in the request's Date header.

When the Authorization header is missing or invalid, the API returns HTTP status 401 with an WWW-Authenticate: BZ1-HMAC-SHA256 header and an error.

Webhook Requests

For webhooks, we provide the signature in a custom header, Bz-Signature.

Bz-Signature header format for webhook requests

Bz-Signature: BZ1-HMAC-SHA256 SIGNATURE

SIGNATURE will be replaced with a signature based on certain parts of the request. The algorithm for calculating the signature is described below. Webhook requests contain a Date header as used in API requests.

When receiving webhooks, always verify the signature.

Calculating the Signature

Calculating the signature means generating a string with certain parameters and then using your division's API key to sign the string with HMAC-SHA256. This section describes the signature process and the next section contains a signature generator you can use to verify and debug your implementation.

The string to sign contains parameters in the following order, separated by newlines (line feed characters only).

Example String to sign

api.viafintech.com:443
GET
/v2/slips/slp-d90ab05c-69f2-4e87-9972-97b3275a0ccd

Thu, 31 Mar 2016 10:50:31 GMT

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

• Host and port, separated by a colon, e.g. api.viafintech.com:443. The host must match the host in the request's Host-header.
• HTTP Method, e.g. POST
• Path, e.g. /v2/slips
• Query string without question mark, e.g. param1=true&param2=false (always empty for now, viafintech API v2 does not use query parameters at the moment)
• Date as specified in the Date header, e.g. Tue, 15 Nov 1994 08:12:31 GMT (make sure the date and your system's clock is correct, it must be within a small window around the current time)
• Idempotency key as specified in the Idempotency-Key header (see below, may be empty if the header is not used for a request)
• SHA-256 digest of the request body (SHA-256 of an empty string if the body is empty), e.g. e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

The newlines are always necessary, regardless whether a value is empty or not, so the number of lines in the string to sign is always the same. Do not add a newline after the body digest. Make sure to only use the line feed characters, and no carriage returns.

When a value is empty (e.g. an empty query string), you will still have to add the newline.

The last step is signing the string with your API key. Use the API key in the form we provide it (do not convert the data to binary, even if it is in hexidecimal form).

Example Key: 6b3fb3abef828c7d10b5a905a49c988105621395

Ruby Example showing HMAC-SHA256 signing

require 'openssl'
signature = OpenSSL::HMAC.hexdigest('sha256', payment_key, string_to_sign)

Use the the API key to sign the string using HMAC with SHA-256 as hash function and encode the resulting bytes in hexidecimal form.

With the example string and example key above, you can calculate the following signature:

Example Signature: 3ebd7a069c0c0f6aafd537866c2b3af6594878eb62db51e2350bfba396971745

Example Request

Example Request with signature in Authorization header

GET /v2/slips/slp-d90ab05c-69f2-4e87-9972-97b3275a0ccd HTTP/1.1
Authorization: BZ1-HMAC-SHA256 DivisionId=20065, Signature=3b1a28fffd1cd2bbc1ec24cfbca1e85d802159e78c08328d92d4337a4a33b61d
Date: Thu, 31 Mar 2016 10:50:31 GMT
Host: api.viafintech.com

The example shows an API request including all headers required for authentication.

You can find an example for webhooks in the Webhooks section.

Signature Generator

This signature generator allows you to verify and debug your implementation of API v2's signature algorithm.

Note:

• Make sure to not have extra whitespace in any of the fields.
• Make sure you don't accidentally change the newline characters when copying code between the browser and your text editor. E.g. Windows often adds carriage return characters in addition to line feed characters.

The bytes put into the signature must be the same sent with the actual request, so different kinds of newlines and whitespace can invalidate the signature.

Idempotency

Most methods on resources in viafintech API v2 can or even must be used in an idempotent way, so you can automatically retry requests without having unintended side effects.

Retrying requests makes your system more resilient when network failures happen, our system temporarily fails to process your request or your division exceeds the rate limit. We highly recommend implementing automated retries - they are necessary for reliable use of any network-based API.

Here is an overview of the idempotency properties of the different methods and resources:

• GET /ping: Is a status endpoint to check if our system is operating correctly without side-effects, so no need for idempotency.
• POST /slips: Requires an Idempotency-Key header to be set. When retrying the same request with the same key, the request will be ignored by the API. Instead of creating a new slip, it returns the slip's current state. Never reuse an idempotency key, we recommand using a randomly generated string, e.g. a UUID v4.
• GET /slips/{id}: Is a read-only request without side-effects, so no need for idempotency.
• GET /slips/{id}/media/pdf: Is a read-only request without side-effects, so no need for idempotency.
• PATCH /slips/{id}: When updating a slip with the same values multiple times, the slip does not change, so there is no need for explicit idempotency. We only resend emails and text messages when a value actually changes.
• POST /slips/{id}/invalidate: Invalidating a slip is final, so a slip can not be changed afterwards. Invalidating an already invalidated slip does nothing and returns the slip as if it hadn't been invalidated before.
• POST /slips/{id}/resend/{type}: Resending an email or text message has an external side effect, so we can not properly implement this in an idempotent way. When retrying this endpoint, a new message might be sent for each request.

Using the Idempotency-Key header in any endpoint other than POST /slips has no effect and will be ignored.

Rate Limiting

Request Limit

The API is rate limited per division to ensure that no single division can use too much server resources.

Example API response headers after a single request

HTTP/1.1 200 OK
Content-Length: 363
Content-Type: application/json;charset=utf-8
Date: Tue, 03 May 2016 10:54:54 GMT
Ratelimit-Limit: 31
Ratelimit-Remaining: 30
Ratelimit-Reset-After: 1
Request-Id: 2b48b13ec1994d1e9cc577058c7b3be1

If the limit is reached, additional requests are not processed and a rate_limit_exceeded error is returned with HTTP status code 429. Over time, requests will be allowed again (as indicated by the Retry-After header) and the request can be repeated.

The API uses a 'leaky bucket' algorithm for rate limiting. It allows a sustained rate of 1 request per second, i.e. the bucket 'leaks' one request per second. The bucket has a size of 31, so a divison can execute a burst of 31 requests at once (within one second) before the limit is reached, i.e. the bucket is full. The next request is available after a second, when one request has 'leaked' from the bucket. Each second, another request 'leaks' from the bucket until after 31 seconds without requests, the bucket is empty again.

If you expect to reach these limits, you should implement client-side rate limit to prevent getting rate_limit_exceeded errors. When getting such an error, do not immediately retry a request, but wait at least the time indicated by the Retry-After header.

The following rate limiting-related headers are returned:

• Ratelimit-Limit: Total number of requests generally allowed at once
• Ratelimit-Remaining: Number of requests remaining
• Ratelimit-Reset-After: Duration in seconds until the limit will be reset to the maximum if no additional requests are executed.
• Retry-After: Returned only with rate_limit_exceeded errors and contains the duration in seconds until the next request is allowed.

Transaction Limit

There is also a per-division transaction creation rate limit. It's set pretty high, so most divisions are unlikely to be affected by it. If you plan on creating more than 10000 slips per 24 hours, please contact us.

In contrast to the request rate limit, the API does not return additional information about the state of the transaction limit as we expect divisions to not reach the limit under normal circumstances. When a division hits the limit nevertheless, the API returns the transaction_creation_rate_limit_exceeded error. In that case, please contact us.

Webhooks

Example Webhook Request

POST /viacash/callback HTTP/1.1
Host: callback.example.com
Date: Fri, 01 Apr 2016 09:20:06 GMT
Bz-Hook-Format: v2
Bz-Signature: BZ1-HMAC-SHA256 6519d1b3f85a7879fe5d2915bab4d0392976ea63ce6ef50b9006c693a029d3e0
Content-Type: application/json;charset=utf-8
Content-Length: 414
User-Agent: viacash Notifier

{
    "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",
        "hook_url": null,
        "expires_at": "2016-01-10T12:34:56Z",
        "customer": {
            "key": "LDFKHSLFDHFL",
            "cell_phone_last_4_digits": "6789",
            "email": "john@example.com",
            "language": "de-DE"
        },
        "metadata": {
          "order_id": "1234",
          "invoice_no": "A123"
        },
        "transactions": [
            {
                "id": "4729294329",
                "currency": "EUR",
                "amount": "123.34",
                "state": "paid",
                "displayed_due_at": "2016-01-10T10:00:00Z"
            }
        ],
        "nearest_stores": []
    }
}

When a relevant event occurred for a slip or transaction, our system does an HTTPS-request on a URL you can specify. These relevant events occur when transactions expire, are canceled, declined, paid, or when the pay confirmation was received from the retailer or the retailer canceled the confirmation during the cooldown period. You can set the URL up in the viafintech App under Settings / Divisions / Notification URL. Alternatively, if you want to use different hook URLs for some of the transactions, you can specify a hook_url when creating a transaction.

A webhook request is done as POST request with a JSON body. The body contains the event that happened (paid, expired, canceled, declined, locked, unlocked, money_received, money_returned), a timestamp when the event occurred and the id of the transaction affected by the event. The body also contains a complete slip resource, so you can access a given reference_key or metadata. When executing webhooks, we do not follow redirects.

Webhook requests are signed in the same way as requests to the API. For hook requests, we provide the signature in the Bz-Signature header. The signature works as authentication, so always verify the signature to prevent unauthorized access. See Authentication for more information about the signature.

The example request is signed using the key 6b3fb3abef828c7d10b5a905a49c988105621395.

We verify the HTTPS server certificate when making webhook requests to your system, so make sure you have a server certificate accepted by common browsers.

The Bz-Hook-Format header contains a version identifier for the webhook format. For slips created via API v2, it always contains v2. For slips previously created using API v1, it contains v1. See Webhook transition for more information on how to migrate webhooks from API v1 to v2.

Download JSON schema

Events

Failed Requests

If a webhook request fails, we retry the request up to 11 times. The waiting time between retries increases exponentially. After at least 24 hours, we give up and send your viafintech App account's administrator an email. The failed webhook can also be viewed and a retry can be initiated in the viafintech App under Transactions / Notifications. For sandbox slips, we do not retry requests (and do not send an email), so they can be viewed immediately in the viafintech App.

We regard all HTTP status codes in the 2xx range as success and everything else as an error. This means redirect status codes like 307 are interpreted as error since we do not follow redirects.

Cooldown period

The cooldown period is a time limit in which our retailers are able to cancel the transaction after we received the pay signal from the retailer. This is in place to allow the retailers to rectify a mistake. For that reason, the paid webhook request is only sent after the cool-down period. The time limit varies depending on the retailer.

In case of using the Know your Customer feature, the cooldown period defaults to 5 minutes.

Errors

Example Error Response

{
  "error_class": "invalid_parameter",
  "error_code": "invalid_slip_type",
  "message": "slip_type: slip_type is required",
  "request_id": "1865359ad354441b9403c3771d811c53"
}

viafintech API v2 returns different HTTP error codes in the 4xx and 5xx ranges. When an error status is returned, the body contains JSON with more information about the error (except for some 5xx errors, which might contain non-JSON data).

Error responses contain an error class as well as an error code. Errors in the same class contain similar types of errors. Your API implementation should be prepared to handle new error codes in any of the existing classes. New error classes will not be added without a new API version. Never write code parsing error messages or use them for anything other than showing them to people. Error messages will change without announcement.

The following describes all error classes as well as all currently used error codes. You should implement automated retries for certain errors, but not for others. Retries are useful not only for certain errors returned by the API, but also for other error cases. See Idempotency for more information.

Download JSON schema

Error Classes

• auth: Authentication or authorization problem. Do not automatically retry the same request.
• transport: A general problem with the HTTP request. Do not automatically retry the same request.
• idempotency: A problem concerning the idempotency mechanism. Do not automatically retry the same request.
• rate_limit: Too many requests were sent per duration, retry the same request later (see Rate Limiting).
• invalid_format: The request body has an invalid format. Do not automatically retry the same request.
• invalid_state: The slip does not have the state necessary for the requested action. Do not automatically retry the same request unless you know the state has changed.
• invalid_parameter: One of the given parameters does not have the necessary format or is invalid for some other reason. Do not automatically retry the same request.
• not_allowed: Organizational or legal reasons prevent the requested action. Do not automatically retry.
• server_error: An internal error occurred on our systems. Automatically retry the same request with a limited number of attempts. If the error persists for several hours, please contact us.

General Errors

The message returned with an error code can contain additional information.

Other HTTP status codes in the 5xx range (e.g. 503) are possible and should be treated the same as a 500 error.

You can find endpoint-specific error codes with the documentation for each endpoint.

Request-Ids

Example Request-Id header

Request-Id: ea65be86bc594a198579c09f16c32681

If you need help with integrating the API and have questions related to a specific request you made, please let us know the Request-Id header in the response. Error responses also contain the request id in their JSON body.

API Stability

We will make backwards-compatible changes to viafintech API v2 without releasing a new version. This means we will not break existing code accessing the API, under the assumption that the existing code allows for the following changes to the API:

• Adding new resources.
• Adding new optional request body or query parameters.
• Adding new parameters to response bodies.
• Adding new body parameters to webhook requests.
• Changing the length or format of id or token parameters. Always store parameters we return as string as such, even if they only contain numbers. E.g. transaction ids are likely to change their format to a format similar to slip ids. The parameters will never exceed the maximum length specified in the JSON schema.
• Adding new slip types.
• Adding new error codes. We will not add new error classes, but your code must be able to handle an unknown error code for any error class.
• Changing error messages. Never write code parsing them or using them for anything else than showing them to people, see Errors.

If we need to make changes which likely break systems using the API in the future, we will release a new version of the API. Examples for such backwards-incompatible changes are:

• Removing resources.
• Removing properties from response bodies.
• No longer accepting properties in request bodies.
• Changing body property types or increasing their length beyond the length specified in the JSON schema.
• Removing slip types.

Changelog

2024-08-19

• Slip Creation now accepts the following new optional fields:
  • customer:coordinates:lat
  • customer:coordinates:lng
• Slip Creation now returns new error codes:
  • invalid_customer_coordinates
  • invalid_customer_coordinates_lat
  • invalid_customer_coordinates_lng

2024-05-16

• Added new possible webhook events locked and unlocked

2024-05-06

• The transactions/state field now supports the locked state. This state is not returned by default an must be enabled by viafintech in order not to break any existing integrations. This state is used after the transaction has been scanned at a retailer but has not been confirmed as paid by the retailer yet, to indicate that the transaction cannot be invalidated or expired at the moment until it may be unlocked.

2024-03-25

• The customer:kyc_type kyb is now supported for the Know your Customer case. The customer:mcc field is mandatory and only allowed when customer:kyc_type is set to kyb.
• Slip Creation now returns new error codes:
  • customer_mcc_not_allowed
  • invalid_customer_kyc_type
  • invalid_customer_mcc

2024-01-30

• The customer:address:zipcode field is now optional for the Know your Customer case for Irish addresses (customer:address:country is IE)

2024-01-21

• Added new possible webhook events money_received and money_returned

2024-01-02

• Some fields already had a pattern applied for ensuring valid values. This was not clearly shown in the documentation. This change updates the documentation to show the pattern and format that is applied for validation for the following fields:
  • customer:email
  • customer:first_name
  • customer:last_name
  • customer:place_of_birth
  • customer:address:street_and_no
  • customer:address:city

2023-08-11

• Added the cooldown period information to the 'Webhooks' section.

2023-05-25

• Slip Creation now returns new error codes:
  • suspected_risk_aml_transaction_declined instead of low_risk_transaction_declined
  • confirmed_risk_aml_transaction_declined instead of high_risk_transaction_declined

2023-05-08

• Added a new field for customer KYC identification

  • customer:document:kyc_type

• Slip Creation now returns new error codes:

  • When eKYCing customers and sending documents:
  • customer_document_not_allowed

2023-03-29

• Slips now can have state declined.
• Slip Update now returns new error codes:
  • slip_declined
• Slip Invalidate now returns new error codes:
  • slip_declined
• Slip Media PDF now returns new error codes:
  • slip_declined
• Slip Resent now returns new error codes:
  • slip_declined

2023-03-24

• Slip Creation now returns new error codes:
  • low_risk_transaction_declined
  • high_risk_transaction_declined
  • transaction_creation_declined_due_to_sanction_screening
  • customer_locked

2023-02-15

• Added additional new fields for customer identification for specific use cases where they are required
  • When the feature is enabled for your division, the following additional fields are mandatory when creating a new slip:
  • customer.ip_address
• Slip Creation now returns new error codes:
  • invalid_customer_ip_address
  • customer_ip_address_not_allowed

2022-12-19

• Added additional new fields for determining which country a slip's transactions should be processible in.
  • In certain cases it is recommended to pass the following field when creating a new slip:
  • country
• Slip Creation now returns new error codes:
  • invalid_country
  • country_not_allowed

2022-07-28

• Slip Creation now returns new error codes:
  • invalid_customer_cell_phone
  • invalid_customer_email
  • invalid_customer_first_name
  • invalid_customer_last_name
  • invalid_customer_date_of_birth
  • invalid_customer_address_street_and_no
  • invalid_customer_address_zipcode
  • invalid_customer_address_city
  • invalid_customer_address_country
• Slip Update now returns new error code:
  • transactions_not_changeable

2022-06-15

• Added additional new fields for customer identification for specific use cases where they are required
  • When the feature is enabled for your division, the following additional fields are mandatory when creating a new slip:
    • customer:document:type
    • customer:document:issuing_authority
    • customer:document:id_number
    • customer:document:date_of_issuance
    • customer:document:date_of_expiry
  • Depending on the country/region the following field may be required:
    • customer:tax_id
  • Slip Creation now returns new error codes:
    • invalid_customer_tax_id
    • invalid_customer_document
    • invalid_customer_document_type
    • invalid_customer_document_issuing_authority
    • invalid_customer_document_id_number
    • invalid_customer_document_date_of_issuance
    • invalid_customer_document_date_of_expiry
    • customer_tax_id_not_allowed
    • customer_document_type_not_allowed
    • customer_document_issuing_authority_not_allowed
    • customer_document_id_number_not_allowed
    • customer_document_date_of_issuance_not_allowed
    • customer_document_date_of_expiry_not_allowed

2021-01-12

• Added new fields for customer identification for specific use cases where they are required.
  • When the feature is enabled for your division, the following fields are mandatory when creating a new slip:
    • customer:first_name
    • customer:last_name
    • customer:date_of_birth
    • customer:place_of_birth
    • customer:address:street_and_no
    • customer:address:zipcode
    • customer:address:city
    • customer:address:country
  • Slip Creation now returns new error codes:
    • invalid_customer_first_name
    • invalid_customer_last_name
    • invalid_customer_date_of_birth
    • invalid_customer_place_of_birth
    • invalid_customer_address
    • invalid_customer_address_street_and_no
    • invalid_customer_address_zipcode
    • invalid_customer_address_city
    • invalid_customer_address_country
    • customer_first_name_not_allowed
    • customer_last_name_not_allowed
    • customer_date_of_birth_not_allowed
    • customer_place_of_birth_not_allowed
    • customer_address_street_and_no_not_allowed
    • customer_address_zipcode_not_allowed
    • customer_address_city_not_allowed
    • customer_address_country_not_allowed
• Added new barcode_code128 field to the slip object. This field is not returned by default.
• Added new paid_at_store object that is returned inside of the transaction object and sent in the webhook request for paid transactions. This object is not returned by default.
  • When this feature is enabled for your division and the information is available, the following attributes are sent inside the paid transaction object:
    • paid_at_store:title
    • paid_at_store:address:street_and_no
    • paid_at_store:address:zipcode
    • paid_at_store:address:city
    • paid_at_store:address:country
    • paid_at_store:coordinates:lat
    • paid_at_store:coordinates:lng

2020-12-03

• Updated checkout to be loaded from cdn.viafintech.com and references from bz-checkout to via-checkout

2020-07-13

• Added support for partial_payments
  • The displayed_due_at fields per transaction now allow setting the date on slip PDF for partial_payments, which differs from expires_at
  • Slip Creation now returns new error codes:
    • invalid_transactions_displayed_due_at
    • too_early_transactions_displayed_due_at
    • transactions_displayed_due_at_after_expires_at
    • too_late_transactions_displayed_due_at
    • transactions_displayed_due_at_not_settable
  • Slip Update now returns the new error code expires_at_not_settable

2017-04-28

• Added the PDF slip download endpoint

2017-04-21

• Added support for payouts
  • The new slip type payout allows paying out money unrelated to a previous payment.
  • Slip Creation returns a new error code: payout_amount_limit_exceeded

2017-02-09

• Added the transaction_creation_rate_limit_exceeded error code and the 'Transaction Limit' section.

2016-09-20

• Returning associated_slip_anonymized error code for refund creation if the payment slip was already anonymized.

2016-09-09

• Webhooks are no longer retried every five minutes, but with exponential waiting time.

2016-07-29

• Slip responses now contain the three nearest stores if an address was provided during slip creation.

Note: The shown dates do not necessarily correspond to the date the change was deployed.

Changes from API v1

Compared to API v1, viafintech API v2 supports several new features and technical improvements.

New Features

• Customer notifications
  • Cell phone numbers can be provided
  • Email and cell phone attributes can be updated
  • Emails and text messages can be resent
• Slip expiry date can be customized
• Slip expiry date can be updated (except partial payments)
• Displayed time on the PDF slip can be customized and be different from the expiry date (partial payments only)
• For payment slips, the amount can be updated
• Partial payments are possible
• For sandbox transactions, emails are sent and PDF slips include nearby stores
• Per-slip webhook URLs (useful especially for payment service providers)
• Webhooks (formerly push notifications) include more information, including the full slip object
• Idempotency allows recovering from network or system failures with predictable outcome

Technical Changes

JSON-based REST API

API v2 is a JSON-based REST API and no longer uses XML. This results in a new structure and different endpoints.

We provide JSON schema definitions for request and response bodies.

New slip identifiers

In API v2, slip ids mostly replace transaction ids. Slip ids are strings with a length of up to 50 bytes, while API v1 transaction ids were numeric ids.

A slip represents a token a customer can use to go into a store and pay money in or to get money paid out. A slip usually is a PDF to be printed or a number in a text message. A transaction represents a possible transfer of money. At the moment, a slip created via API v2 must have exactly one transaction.

We built API v2 in a way to make the transition from transaction ids to slip ids as seamless as possible for existing systems. Slips previously created using API v1 (then called transactions) will keep their numeric transaction id, so you can treat existing transactions the same as transactions created using API v2. You can e.g. fetch information about an API v1 slip using the same endpoint as an API v2 slip, GET /slips/12345, with 12345 being a API v1 transaction id. Slips keeping their identifiers also allows you to easily associate webhooks sent with the API v2 format with previously created transactions.

Transaction ids still exist, although, at the moment, they are only necessary to update attributes in a slip's transactions field.

Strings as identifiers

Not only API v2's slip ids are strings, but also transaction and division identifiers are now strings. Although some of the fields might still return only numbers in a string, make sure to treat them as strings with the lengths specified in this documentation. We will change some of the fields to contain non-numeric characters in the future.

Webhook transition

Webhooks in API v2 are always POST requests with a JSON payload.

The old v1 webhook format does not support various fields used in API v2, most importantly slip ids. We thus switch the webhook format to the API v2 format when you create the first slip via API v2.

For slips created via API v2, webhooks are sent in v2 format exclusively. So before using API v2 in production, make sure your production webhooks understand the v2 format.

To allow for a transition period (e.g. during testing), when v2 format is activated, we send webhooks twice for slips created via API v1: Once in v1 format and once in v2 format. This ensures that creating a slip via API v2 doesn't break webhooks for systems still using API v1 and only supporting v1 webhooks.

If you want to prevent your systems reporting errors due to requests they cannot understand, you can decide to ignore webhooks in a certain format by checking the Bz-Hook-Format header. This can be useful for ignoring v1 webhooks after switching to API v2, when there can still be pending transactions created via API v1 before the switch.

When making API v2 webhook requests, we no longer follow redirects. For transitional API v1 webhook requests, we still do.

Other changes

• There is a new signature algorithm that no longer requires response signature checks and relies only on TLS and proper server certificate verification.
• Rate limiting prevents a division from using too many server resources.

Customer Checkout

viacash provides a custom checkout overlay for each payment and payout slip that has been created using the viafintech API v2. You should display this checkout overlay to your customers immediately after they successfully finished their ordering process on your website.

The viacash checkout overlay allows your customers to:

• Get information about the payment or payout process in general and how to proceed
• Find the stores closest to their current location where they can pay their order
• Download the payment or payout slip as a PDF document (e.g. for printing it out)
• Specify a phone number to receive the payment slip via text message (only possible for payment slips and if you did not already specify the customer:cell_phone parameter in your request to POST /slips)

The checkout does not support partial payments, payout and refund slips.

Setup

Example HTML code to display the viacash checkout overlay

<!-- viacash Checkout -->
<script src="https://cdn.viafintech.com/js/v2/checkout.js"
        class="via-checkout"
        data-token="CHECKOUT_TOKEN">
</script>
<!-- End viacash Checkout -->

The checkout overlay is very easy to set up and can be displayed on desktop browsers as well as on mobile phones. All you have to do is the following:

1. Add the HTML tag <script src="https://cdn.viafintech.com/js/v2/checkout.js" class="via-checkout" data-token="CHECKOUT_TOKEN"> to your website's own checkout page. (This is the page you display to your customers after they have confirmed an order on your website and you received a success response from your request to POST /slips.) You should put the <script ...> tag at the very bottom of your website's HTML source code just before the closing </body> tag. Otherwise some older browsers might not be able to load it properly.
2. Place the content of the checkout_token that you received within the API response of your call to POST /slips into the data-token attribute of the <script ...> tag.

The <script ...> tag loads a JavaScript file from https://cdn.viafintech.com/js/v2/checkout.js which automatically displays the viacash checkout overlay within a modal on top of your website's own checkout page. The customer is able to close the modal with one click to return to your website.

Reopening the viacash checkout overlay

Allow customers to manually reopen the viacash checkout overlay using a predefined button

<button class="via-checkout-btn">
  Pay now with viacash
</button>

Reopen the viacash checkout overlay using a custom link

<a href="javascript:viaCheckout.display();">
  Pay now with viacash
</a>

As mentioned above, the viacash checkout overlay will open automatically in a modal on your website. Customers are able to close this overlay with a click on the close icon in the top right corner.

In case customers accidentally close the overlay, they might want to reopen it. To allow them to do this, we provide the following two possibilities:

1. Include the following code into the HTML of your own checkout page: <button class="via-checkout-btn">Pay now with viacash.de</button>. This will render a pre-styled button that, when clicked by the customer, reopens the viacash checkout overlay. (Make sure to include the <button ...> on the same page as the <script ...> tag, as it will not work otherwise.)
2. In case you want to be more flexible (e.g. you want to use your own styled button or a link tag instead) you can reopen the viacash checkout overlay using the JavaScript function viaCheckout.display().

Disable automatic display

Example HTML code to disable the automatic display of the viacash checkout overlay

<!-- viacash Checkout -->
<script src="https://cdn.viafintech.com/js/v2/checkout.js"
        class="via-checkout"
        data-token="CHECKOUT_TOKEN"
        data-auto-display="false">
</script>
<!-- End viacash Checkout -->

Under certain circumstances it might be useful to prevent the checkout overlay from appearing automatically. Add the optional attribute data-auto-display="false" to the <script ...> tag to achieve this result. Not specifying the data-auto-display attribute at all or setting it to "true" will automatically display the checkout overlay. We recommend to always display the checkout overlay automatically to make it as easy as possible for your customers to immediately see all relevant information related to their viacash payment or payout process.

If you decide to disable the automatic display, make sure to allow your customers to manually open the checkout overlay using a predefined button or custom link like explained above.

Sandbox

Example HTML code to display the viacash checkout overlay in sandbox mode

<!-- viacash Checkout Sandbox -->
<script src="https://cdn.viafintech.com/js/v2/checkout-sandbox.js"
        class="via-checkout"
        data-token="CHECKOUT_TOKEN">
</script>
<!-- End viacash Checkout Sandbox -->

To use the viacash checkout overlay in sandbox mode, you need to change the src parameter of the HTML tag to point to a different JavaScript file: <script src="https://cdn.viafintech.com/js/v2/checkout-sandbox.js" class="via-checkout" data-token="CHECKOUT_TOKEN">

/ping

Ping

GET /ping

The /ping endpoint allows verifying that the connection to viafintech and authentication work. Calling this endpoint does not change any server state and always returns an empty JSON object for a valid request.

Using this endpoint is optional, there is no need to call it before accessing other endpoints of the API.

Example Response Body for HTTP status 200 with Content-Type application/json

{}

Headers

Errors

General API Errors can also be returned by this resource. See also Errors.

/slips

Create Slip

POST /slips

Example Minimal Request Body for a payment slip

{
  "slip_type": "payment",
  "customer": {
    "key": "LDFKHSLFDHFL"
  },
  "transactions": [
    { "currency": "EUR", "amount": "123.34" }
  ]
}

Create a payment, partial payments, payout, or refund slip.

If you provide an email address, we send an email with a PDF attachment to the customer. If you provide a cell phone number for a payment or partial payments slip, we send a text message containing the barcode number and the amount. If specified in our contractual agreement, we also send text messages for payouts. We do not send text messages for refunds.

• Required fields for all slip types:
  • slip_type
  • transactions/currency, transactions/amount
• All payment, payout and refund slips must contain exactly one transaction.
• Partial payments must contain at least two and at most twelve transactions.
• If you know the customer's address, you can provide it in show_stores_near:address. We use the address to show the customer nearby viacash partner stores and to return the three nearest stores in API responses. If you provide an address, you must provide all four fields.

Note: The Idempotency-Key header is required for this endpoint. See below.

Payment Slips

Payment slips can be paid by a customer and result in money being transferred to your division. They are used e.g. when a customer orders a product in an online shop.

Payment slip specifics:

• customer:key must be provided. See Identifying a customer for more information.
• transactions/amount must be positive.

Partial Payment Slips

Example Minimal Request Body for a partial payments slip

{
  "slip_type": "partial_payments",
  "customer": {
    "key": "LDFKHSLFDHFL"
  },
  "transactions": [
    { "currency": "EUR", "amount": "123.34", "displayed_due_at": "2020-05-31T22:00:00Z" },
    { "currency": "EUR", "amount": "123.34", "displayed_due_at": "2020-06-30T22:00:00Z" }
  ]
}

Partial Payment slips can be paid by a customer and result in money being transferred to your division for each individual payment. They are used e.g. when a customer pays their monthly electricity bill.

Partial Payment slip specifics:

• customer:key must be provided. See Identifying a customer for more information.
• transactions/amount must be positive.
• transactions/displayed_due_at must be provided.
• At least two and at most twelve transactions may be provided.

Payout Slips

Example Minimal Request Body for a payout slip

{
  "slip_type": "payout",
  "customer": {
    "key": "LDFKHSLFDHFL"
  },
  "transactions": [
    { "currency": "EUR", "amount": "-123.34" }
  ]
}

Payout slips allow a customer to receive money and result in money being transferred from your division. They are used when paying out money that is not associated with a previous payment. When returning a portion or all of the money a customer has previously paid via viacash, use refund slips.

Payout slip specifics:

• customer:key must be provided. See Identifying a customer for more information.
• transactions/amount must be negative.

Refund Slips

Example Minimal Request Body for a refund slip

{
  "slip_type": "refund",
  "refund": {
    "for_slip_id": "slp-d90ab05c-69f2-4e87-9972-97b3275a0ccd"
  },
  "transactions": [
    { "currency": "EUR", "amount": "-23.99" }
  ]
}

Refund slips return money to a customer and must be associated with a payment slip the same customer previously paid. They are used e.g. when a customer has returned a product to an online shop. The sum of all refund slip's amounts associated with a single payment slip must be less than or equal to the payment slip's amount.

Refund slip specifics:

• transactions/amount must be negative.
• Both customer:key and customer:email must not be provided due to regulatory issues. Both will be copied from the original payment slip.
• Both reference_key and customer:cell_phone_number also must not be provided – both are copied from the original payment slip as well.
• A show_stores_near address can be provided. Currently this address will be ignored and the original payment's address will be used. This will change in the future and we will then show stores next to the address provided when creating the refund.

KYC Attributes

Example Request Body for a payment slip with KYC attributes

{
  "slip_type": "payment",
  "customer": {
    "key": "LDFKHSLFDHFL",
    "ip_address": "46.231.176.208",
    "cell_phone": "+49123456789",
    "email": "john@example.com",
    "language": "de-DE",
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-12-31",
    "place_of_birth": "Berlin",
    "address": {
      "street_and_no": "Budapester Str. 50",
      "zipcode": "10178",
      "city": "Berlin",
      "country": "DE"
    },
    "tax_id": "12 345 678 901",
    "document": {
      "type": "passport",
      "issuing_authority": "Buergeramt",
      "id_number": "T22000129",
      "date_of_issuance": "2020-01-01",
      "date_of_expiry": "2022-01-01"
    }
  },
  "country": "DE",
  "transactions": [
    { "currency": "EUR", "amount": "123.34" }
  ]
}

Further attributes need to be added to the customer if KYC information are required. key, cell_phone, email and language attributes are not considered as KYC attributes.

These fields are not accepted by default. See Optional Features for more information.

Example Request Body

{
  "slip_type": "payment",
  "reference_key": "O64737X",
  "hook_url": "https://psp.example.com/hook",
  "expires_at": "2016-01-10T12:34:56Z",
  "customer": {
    "key": "LDFKHSLFDHFL",
    "cell_phone": "+49123456789",
    "email": "john@example.com",
    "language": "de-DE",
  },
  "show_stores_near": {
    "address": {
      "street_and_no": "Budapester Str. 50",
      "zipcode": "10787",
      "city": "Berlin",
      "country": "DE"
    }
  },
  "metadata": {
    "order_id": "1234",
    "invoice_no": "A123"
  },
  "transactions": [
    {
      "currency": "EUR",
      "amount": "123.34",
      "displayed_due_at": "2016-01-10T12:34:56Z"
    }
  ]
}

Request Attributes

Download JSON schema

Example Response Body for HTTP status 201 with Content-Type application/json

{
  "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": "LDFKHSLFDHFL",
    "cell_phone_last_4_digits": "6789",
    "email": "john@example.com",
    "language": "de-DE"
  },
  "checkout_token": "djF8Y2hrdHxzbHAtMTM4ZWI3NzUtOWY5Yy00NzYwLWI4ZTAtYTNlZWNmYjQ5M2IxfElBSThZMnd6SFYwbjJpMm9aSUpvREpnYnhNS3c5Z2x3elJOanlLblZJeFk9",
  "metadata": {
    "order_id": "1234",
    "invoice_no": "A123"
  },
  "transactions": [
    {
      "id": "4729294329",
      "currency": "EUR",
      "amount": "123.34",
      "displayed_due_at": "2016-01-10T12:34:56Z",
      "state": "pending",
      "country": null
    }
  ],
  "nearest_stores": [
    {
      "title": "mobilcom-debitel",
      "logo": {
        "id": "17077"
      },
      "distance_m": 1160,
      "address": {
        "city": "Berlin",
        "country": "DE",
        "street_and_no": "Grunerstraße 20",
        "zipcode": "10179"
      },
      "opening_hours": {
        "days": [
          { "day": "sun", "open": [] },
          { "day": "mon", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "tue", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "wed", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "thu", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "fri", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "sat", "open": [{"begin": "10:00", "end": "21:00"}] }
        ]
      }
    },
    {
      "title": "dm-drogerie markt",
      "logo": {
        "id": "13045"
      },
      "distance_m": 1220,
      "address": {
        "city": "Berlin",
        "country": "DE",
        "street_and_no": "Alexanderplatz 1",
        "zipcode": "10178"
      },
      "opening_hours": {
        "days": [
          { "day": "sun", "open": [] },
          { "day": "mon", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "tue", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "wed", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "thu", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "fri", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "sat", "open": [{"begin": "09:00", "end": "22:00"}] }
        ]
      }
    },
    {
      "title": "dm-drogerie markt",
      "logo": {
        "id": "13045"
      },
      "distance_m": 1280,
      "address": {
        "city": "Berlin",
        "country": "DE",
        "street_and_no": "Henriette-Herz-Platz 4",
        "zipcode": "10178"
      },
      "opening_hours": {
        "days": [
          { "day": "sun", "open": [] },
          { "day": "mon", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "tue", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "wed", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "thu", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "fri", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "sat", "open": [{"begin": "09:00", "end": "21:00"}] }
        ]
      }
    }
  ]
}

Response Attributes

Download JSON schema

Headers

Errors

General API Errors can also be returned by this resource. See also Errors.

Retrieve Slip

GET /slips/{id}

Retrieve information about a slip.

Example Response Body for HTTP status 200 with Content-Type application/json

{
  "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": "LDFKHSLFDHFL",
    "cell_phone_last_4_digits": "6789",
    "email": "john@example.com",
    "language": "de-DE"
  },
  "metadata": {
    "order_id": "1234",
    "invoice_no": "A123"
  },
  "transactions": [
    {
      "id": "4729294329",
      "currency": "EUR",
      "amount": "123.34",
      "displayed_due_at": "2020-06-12T07:32:19Z",
      "state": "pending",
      "country": "DE"
    }
  ],
  "nearest_stores": [
    {
      "title": "mobilcom-debitel",
      "logo": {
        "id": "17077"
      },
      "distance_m": 1160,
      "address": {
        "city": "Berlin",
        "country": "DE",
        "street_and_no": "Grunerstraße 20",
        "zipcode": "10179"
      },
      "opening_hours": {
        "days": [
          { "day": "sun", "open": [] },
          { "day": "mon", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "tue", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "wed", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "thu", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "fri", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "sat", "open": [{"begin": "10:00", "end": "21:00"}] }
        ]
      }
    },
    {
      "title": "dm-drogerie markt",
      "logo": {
        "id": "13045"
      },
      "distance_m": 1220,
      "address": {
        "city": "Berlin",
        "country": "DE",
        "street_and_no": "Alexanderplatz 1",
        "zipcode": "10178"
      },
      "opening_hours": {
        "days": [
          { "day": "sun", "open": [] },
          { "day": "mon", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "tue", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "wed", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "thu", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "fri", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "sat", "open": [{"begin": "09:00", "end": "22:00"}] }
        ]
      }
    },
    {
      "title": "dm-drogerie markt",
      "logo": {
        "id": "13045"
      },
      "distance_m": 1280,
      "address": {
        "city": "Berlin",
        "country": "DE",
        "street_and_no": "Henriette-Herz-Platz 4",
        "zipcode": "10178"
      },
      "opening_hours": {
        "days": [
          { "day": "sun", "open": [] },
          { "day": "mon", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "tue", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "wed", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "thu", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "fri", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "sat", "open": [{"begin": "09:00", "end": "21:00"}] }
        ]
      }
    }
  ]
}

Response Attributes

Download JSON schema

Headers

URL Parameters

Errors

General API Errors can also be returned by this resource. See also Errors.

Update Slip

PATCH /slips/{id}

Change certain slip attributes. Only slips with a pending transaction can be updated. We notify the customer about certain changes.

When one of the following values is changed, we send an email to the customer:

• customer:email
• expires_at
• transactions/amount

When customer:cell_phone is changed for a payment or partial payment slip, we send a text message to the new recipient. We do not send text messages for payout and refund slips.

For payments, the following attributes can be changed:

• customer:cell_phone if the text message resend limit has not been exceeded, see Resend Email / Text Message
• customer:email
• expires_at
• reference_key if it is not yet set
• transactions/amount

For partial payments, the following attributes can be changed:

• customer:cell_phone if the text message resend limit has not been exceeded, see Resend Email / Text Message
• customer:email
• reference_key if it is not yet set
• transactions/amount

For payouts, the following attributes can be changed:

• expires_at
• reference_key if it is not yet set

For refunds, the following attribute can be changed:

• expires_at

None of the fields are required. If a field is provided, the API tries to update it. Do not pass null for fields you do not want to change, that would mean setting the field to null (which is not possible for most fields).

For any field, passing the value that is already set is not treated as a change by the API. E.g. setting the same customer email the slip already has does not result in an additional email being sent.

We generally discourage changing the amount after the user has received an email or text message due to a poor user experience: The amount shown in a user's PDF slip or text message can differ from the amount shown by the cash register, which might be unexpected for the customer. If you need to update the amount after creating a slip, we recommend creating the slip without email and cell_phone number and setting them later, together with the amount.

Example Request Body

{
  "customer": {
    "email": "john@example.com",
    "cell_phone": "+495423112345"
  },
  "expires_at": "2016-01-10T12:34:56Z",
  "transactions": [
    {
      "id": "4729294329",
      "amount": "150.00",
      "displayed_due_at": "2020-06-12T07:32:19Z"
    }
  ],
  "reference_key": "NEWKEY"
}

Request Attributes

Download JSON schema

Example Response Body for HTTP status 200 with Content-Type application/json

{
  "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": "LDFKHSLFDHFL",
    "cell_phone_last_4_digits": "6789",
    "email": "john@example.com",
    "language": "de-DE"
  },
  "metadata": {
    "order_id": "1234",
    "invoice_no": "A123"
  },
  "transactions": [
    {
      "id": "4729294329",
      "currency": "EUR",
      "amount": "123.34",
      "displayed_due_at": "2020-06-12T07:32:19Z",
      "state": "pending",
      "country": "DE"
    }
  ],
  "nearest_stores": [
    {
      "title": "mobilcom-debitel",
      "logo": {
        "id": "17077"
      },
      "distance_m": 1160,
      "address": {
        "city": "Berlin",
        "country": "DE",
        "street_and_no": "Grunerstraße 20",
        "zipcode": "10179"
      },
      "opening_hours": {
        "days": [
          { "day": "sun", "open": [] },
          { "day": "mon", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "tue", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "wed", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "thu", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "fri", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "sat", "open": [{"begin": "10:00", "end": "21:00"}] }
        ]
      }
    },
    {
      "title": "dm-drogerie markt",
      "logo": {
        "id": "13045"
      },
      "distance_m": 1220,
      "address": {
        "city": "Berlin",
        "country": "DE",
        "street_and_no": "Alexanderplatz 1",
        "zipcode": "10178"
      },
      "opening_hours": {
        "days": [
          { "day": "sun", "open": [] },
          { "day": "mon", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "tue", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "wed", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "thu", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "fri", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "sat", "open": [{"begin": "09:00", "end": "22:00"}] }
        ]
      }
    },
    {
      "title": "dm-drogerie markt",
      "logo": {
        "id": "13045"
      },
      "distance_m": 1280,
      "address": {
        "city": "Berlin",
        "country": "DE",
        "street_and_no": "Henriette-Herz-Platz 4",
        "zipcode": "10178"
      },
      "opening_hours": {
        "days": [
          { "day": "sun", "open": [] },
          { "day": "mon", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "tue", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "wed", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "thu", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "fri", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "sat", "open": [{"begin": "09:00", "end": "21:00"}] }
        ]
      }
    }
  ]
}

Response Attributes

Download JSON schema

Headers

URL Parameters

Errors

General API Errors can also be returned by this resource. See also Errors.

Retrieve Slip PDF

GET /slips/{id}/media/pdf

Retrieve the slip's PDF representation for printing.

The customer usually receives the slip PDF via email or can access it via the checkout, so in most cases it is not necessary to download the PDF. In some cases this endpoint can be useful, for example if you want to print the PDF yourself send a letter to the customer.

Downloading the PDF is only possible for slips in the pending state.

Note: Due to security reasons this endpoint is disabled by default and can only be enabled by viafintech. Please feel free to contact us if you are interested in using this feature.

HTTP Status 200 with Content-Type application/pdf

Headers

URL Parameters

Errors

General API Errors can also be returned by this resource. See also Errors.

Resend Email / Text Message

POST /slips/{id}/resend/{message_type}

Resend the email or text message containing slip information like the barcode to the customer. Only possible for slips with a pending transaction. Text messages can only be sent for payment and partial payment slips and not for payout and refund slips.

Text messages can only be resent twice. After that, an attempt to resend a text message will return an error. Resending a text message by changing the customer:cell_phone number via PATCH also counts as a resend and is no longer possible when the limit has been reached.

Note that the sandbox API endpoint does not send text messages.

This endpoint returns an empty JSON object as response.

Example Response Body for HTTP status 202 with Content-Type application/json

{}

Headers

URL Parameters

Errors

General API Errors can also be returned by this resource. See also Errors.