BaaS API documentation

We use cryptographic signature to authorize API requests.
To configure your API keys for selected entity please login to our banking app Developer Section.
You have to configure your whitelisted IPs and public key which will be used for request signature verification.
Do not share your private key with anybody. We will never asks you for private key.

Please note that we use api.narvi.com fully qualified domain to interact with your integration. All your api requests should use this domain to communicate with our REST API.

Each request needs to have the following headers:
- API-KEY-ID - api key id gathered from configured api key Developer Section
- API-REQUEST-ID - request ID, valid UUID, can't be duplicated across requests
- API-REQUEST-SIGNATURE - request signature

API-REQUEST-ID (Request ID)
- valid UUID,
- it can't be duplicated across requests

API-REQUEST-SIGNATURE (Request signature)
Request signature is the signature of sha256 of the concatenated following items (request descriptor)
- the absolute request url without query params (e.g. http://api.narvi.com/rest/v1.0/transactions/create)
- the uppercase request method (e.g. POST, GET, PUT, DELETE)
- request ID - valid UUID, can't be duplicated across requests
- query params encoded in JSON canonical form - RFC 7159 JSON (The order of JSON key-value pairs is very important. Please double-check that it is in the correct canonical form. All query parameters keys and values must have the string type. Use an empty string instead if there are no query parameters).
- payload encoded in JSON canonical form - RFC 7159 JSON (The order of JSON key-value pairs is very important. Please double-check that it is in the correct canonical form. Use an empty string instead if there is no payload)
- if payload contains file object use sha256 of the file content to create payload canonical form for request descriptor

Signature example
For GET request https://api.narvi.com/?account_pid=KFGKJ5L27ASGTZAO&kind=CREDIT the signature should be created as follow:
- generate request uuid: e.g. da43520e-800b-41c5-a4a9-7287a64c87fa
- generate request descriptor: https://api.narvi.com/rest/v1.0/transactions/listGETda43520e-800b-41c5-a4a9-7287a64c87fa{"\account_pid":"KFGKJ5L27ASGTZAO","kind":"CREDIT"}
- generate sha256 of the request descriptor
- generate signature with hashing algorithm sha256 of the generated sha256 above
- encode the signature with base64

For POST request https://api.narvi.com/rest/v1.0/transactions/create with the payload
{"account_pid": "KFGKJ5L27ASGTZAO" ,"recipient": {"name": "John Doe", "number": "FI8379600186405354" ,"bic": "NARIFXX", "country": "FI"}, "currency": "EUR","amount": 100, "remittance_information":{"ustrd": "test transfer"}}
the signature should be created as follow:
- generate request ID: e.g. da43520e-800b-41c5-a4a9-7287a64c87fa
- generate request descriptor: https://api.narvi.com/rest/v1.0/transactions/createPOSTda43520e-800b-41c5-a4a9-7287a64c87fa{"account_pid":"KFGKJ5L27ASGTZAO","amount":"100","currency":"EUR","recipient":{"bic":"NARIFXX","country":"FI","name":"John Doe","number":"FI8379600186405354"},"remittance_information":{"ustrd":"test transfer"}}
- generate sha256 of the request descriptor
- generate signature with hashing algorithm sha256 of the generated sha256 above
- encode the signature with base64

To enable webhooks, please login to Developer Section and configure webhook endpoints for selected entity. After you enable them, we will push real-time event data to your application's webhook endpoint when events happen in your banking account. We use HTTPS to send webhook events to your app as a JSON payload that includes an Event object.

The full list of IP addresses that api.narvi.com may resolve to is:
3.76.153.24

We attempt to deliver the event to your webhook endpoint for up to 3 days with an exponential back off. In the log section of the Dashboard, you can view when the next retry will occur. If your endpoint has been disabled or deleted when we attempt a retry, future retries are cancelled.
Your endpoint must quickly return a successful status code (2xx) prior to any complex logic that could cause a timeout. For example, you must return a 200 response before updating a customer’s balance.

HTTP payloads that are delivered to your webhook's configured URL endpoint will contain several special headers:
- USER-AGENT - always equal 'webhook'
- WEBHOOK-REQUEST-TIMESTAMP - timestamp in millisecond when webhook action occured
- WEBHOOK-REQUEST-EVENT-TYPE - the event type
- WEBHOOK-REQUEST-EVENT-PID - event public id
- WEBHOOK-REQUEST-SIGNATURE - This is the sha256 hex digest of the request body and parameters

Webhook signature must be checked by integrated application before processing the webhook data.
Webhook signature is the sha256 hex digest of the concatenated following items (request descriptor)
- the absolute webhook endpoint without query params (e.g. https://example.com/webhook/handler)
- the uppercase request method (e.g. POST, GET, PUT, DELETE)
- current timestamp in microseconds (taken from request header WEBHOOK-REQUEST-TIMESTAMP)
- event type (taken from request header WEBHOOK-REQUEST-EVENT-TYPE)
- event public id (taken from request header WEBHOOK-REQUEST-EVENT-PID)
- query params encoded in JSON canonical form - RFC 7159 JSON (The order of JSON key-value pairs is very important. Please double-check that it is in the correct canonical form. All query parameters keys and values must have the string type. Use an empty string instead if there are no query parameters)
- payload encoded in JSON canonical form - RFC 7159 JSON (The order of JSON key-value pairs is very important. Please double-check that it is in the correct canonical form. Use an empty string instead if there is no payload)
- webhook secret taken from developer panel