VIAMO PayGate API (2.0.0)

• timestamp — used wherever an exact point in time is expected; the value is a number and represents the number of seconds since the start of the Unix epoch
• date — used where the whole calendar day carries the meaning rather than a specific time (e.g. the validity of a recurring payment mandate); the value is a string in ISO 8601 format YYYY-MM-DD (e.g. 2029-03-15). The day is always inclusive — a mandate with expiresOn 2029-03-15 is valid for the whole of 15 March 2029
• amount — all amounts are in cents, whole numbers, type number (e.g. €2.43 is 243)
• object — every object carries an object field telling what type of object it is (e.g. payment, recurring)
• list — if the response is a list, a list object is returned with the fields object, url, hasMore (true if more objects match the criteria than were returned) and data (at most 50 objects)
• POST request body — the request body may be sent either as JSON (Content-Type: application/json) or as a form (Content-Type: application/x-www-form-urlencoded); the response is always JSON

The merchant authenticates against the API with an assigned API key in the HTTP header X-API-KEY. Calls are only accepted from pre-registered IP addresses. All calls must be made over HTTPS — calls over HTTP or without authentication end with an error.

The API key must be kept safe. Never share it in publicly accessible places such as GitHub, client-side code and the like.

A recurring BLIK payment lets a merchant charge the payer without their interaction, based on a consent (a mandate) the payer confirmed in their banking app. Three models are supported:

Mandate lifecycle:

1. On the merchant's site the payer expresses the intent to set up a recurring payment (a mandatory requirement of the BLIK scheme).
2. The merchant sends POST /payments with a BLIK code (blik.type=TICKET) and a recurring block — the invitation to set up a mandate is attached to an ordinary payment. The amount may also be 0 (the mandate is set up without charging the payer anything); a zero amount is allowed only together with a recurring block, otherwise the request fails with WRONG_AMOUNT. No transaction fee is charged for a zero-amount payment. Beware: with a zero amount there is nothing to settle, so an issuer that does not support PAYID aliases rejects the whole payment (PAYID_NOT_SUPPORTED) — the same as with refuseNoPayid=true. The mandate is created in the INVITED state; its id is returned in the recurringId field.
3. In the banking app the payer confirms both the payment and the mandate setup in a single step.
4. Once the issuer registers the alias, the mandate moves to the ACTIVE state — the merchant is notified by a webhook (payloadType=recurring). Only from this moment on can the mandate be charged. If the registration does not happen within 24 hours, the mandate moves to the REJECTED state.
5. Charging: POST /payments with blik.type=RECURRING and blik.recurringId. The issuer has up to 72 hours to authorise it — the payment stays in the PROCESSING state; the merchant polls GET /payments/{id}. With models A and O an immediate answer can be requested (blik.noDelay=true).
6. A rejected payment can be retried through blik.retryPaymentId (the id of the rejected payment) — the payment keeps the same id; it can be retried at most 3 times (4 attempts in total). Retries do not extend the 72-hour window of the original payment, they only share it.
7. A mandate ends: by the payer cancelling it in the banking app, by the merchant cancelling it (DELETE /recurrings/{id}), or by expiry. The merchant is notified by a webhook about every state change.

Refunding a payment made from a mandate is done the standard way through POST /stornos.

If the merchant has a notification URL configured, VIAMO sends an HTTP POST with a notification object to it. The payloadType field determines the payload type:

• alias — a OneClick alias change (an alias object)
• recurring — a recurring payment mandate change (a recurring object); if the notification concerns a specific payment (loss of the MIT exemption, scaRejected), its id is in the paymentId field

The authenticity of the payload can be verified through the sign field — see below.

Object signature (sign)

The recurring and alias objects carry a sign field. By verifying it the merchant makes sure the payload comes from VIAMO and was not altered on the way — this applies equally to webhooks and to the responses of GET /recurrings/{id}, GET /recurrings/search and GET /aliases/search.

The signature is made with the merchant's assigned API key — the very same value used to authenticate PAPI calls (the X-API-KEY header). The key is a shared secret: it enters the hash, but is never itself transmitted in the payload.

Procedure:

1. Concatenate the field values in the given order, without any separator, exactly in the form they have in the JSON (numbers in decimal, unformatted).
2. Encode the string as UTF-8 and compute SHA-256.
3. Write the result as a lowercase hexadecimal string, 64 characters.

A missing field enters the signature as the literal null (four characters). The payload is serialised without empty fields, so a field you do not see in the JSON enters the string as null — this concerns expiresOn of both a mandate and an alias (with no end of validity) as well as appLabel of an alias.

Example — a mandate with no end of validity, API key TEST_API_KEY_123:

id        = b3f1c0d4e5a6478fa1b2c3d4e5f60718
state     = ACTIVE
model     = M
expiresOn = (field missing)

string:   b3f1c0d4e5a6478fa1b2c3d4e5f60718ACTIVEMnullTEST_API_KEY_123
sign:     676d7bd8d58d4f63f3e21e636f82093e0a88afd259af4786fbfa51290064d9f4

Example — a mandate with an end of validity (expiresOn enters as a date, exactly as it is in the JSON):

id        = b3f1c0d4e5a6478fa1b2c3d4e5f60718
state     = ACTIVE
model     = A
expiresOn = 2029-03-15

string:   b3f1c0d4e5a6478fa1b2c3d4e5f60718ACTIVEA2029-03-15TEST_API_KEY_123
sign:     79dd1332418f5d9359b06fa34892a3a0dd301dff28cdc00abea69cbf8a2de630

Example — an alias:

userId    = payer@example.com
appKey    = 655158
appLabel  = TEST APP
expiresOn = 1798761600
state     = VALID

string:   payer@example.com655158TEST APP1798761600VALIDTEST_API_KEY_123
sign:     e62668164aed280de0f68d999a0b51c1285e0dea26a68c9f006f2cfe3bacef4f

Creating a BLIK payment (LEVEL 0), payment status and payment search.

Mandates for recurring BLIK payments — created through POST /payments with a recurring block.

Refunding (storno) a payment.

Payout requests and their status.

The merchant's current balance.

Registered BLIK OneClick aliases (UID) for one-click payments.