NAV Navbar
Logo
shell

eInvoices Aggregation API

Purpose

Younify Electronic Invoice product allows Banks to propose new services to their customers. Bank users will be able to retrieve, manage and pay all their invoices using the e-banking platform.

This API presents the technical implementation details of the operations exposed by Sonic+Pay to Banks in order to implement Younify Electronic Invoice product.

Audience

This API is designed for the engineering teams of Bank and Sonic+Pay.

Getting started

If you would like to test or use eInvoices Aggregation API, please contact us at sales@younify.io.

We will sign a Service Aggrement that will grant you access to your private sandbox that includes:

Definitions and abbreviations

Term / Abbreviation Description
Invoice Emitter This is any Invoice provider (utility, insurance, telecommunication company) that is issuing recurrent invoices to his customers.
Invoice Emitter Customer Represents the contract/accounts/consumption points that a person or company can have with an Invoice Emitter.
A person/company can have multiple contracts/accounts/consumption points for an Invoice Emitter. (E.g. A person has multiple houses and for each one he has a contract with the same electricity company. In this case that person will have an Invoice Emitter Customer for each contract).
Bank This is any bank that is joining Younify platform.
Bank Customer Represents the end user that is accessing the Internet Banking application of a Bank.
Custom Code Represents a code that a customer can find on an invoice: ClientCode, AccountNumber, InvoiceId, phone number, etc.
Younify email Represents the email that Younify is creating for the user in order to be used to manually setup Invoice Emitters.
The Younify email:
  • Not accessible directly by the user.
  • All emails received will be automatically forwarded to user personal email.
The domain of the Younify email can have the domain name of Younify or acustom domain name of the bank.

Overview

Younify platform acts as a middleware between banks and invoice emitters.

Overview

The diagram above presents Banks, Invoice Emitters and Younify context:

Description

Invoice Emitters integration

In order to fulfill the workflows described below, Younify system will connect with partner Invoice Emitter platforms and perform the following workflows:

Younify system has two types of integration with the Invoice Emitter systems:

Manual integration

For the Invoice Emitters in this category, the customer needs to setup manually his account. The bank customer will receive a Younify email that needs to be setup on Invoice Emitter platform to receive their invoices on this email. Younify platform will parse the emails received from Invoice Emitters in order to extract the invoices for the bank customer (the email received in customer’s Younify email will be automatically forwarded to his personal email).

Automatic integration

The Invoice Emitters in this category, are fully manageable by the customer from the Internet Banking application of the bank.

General workflows

Younify product functionality can be separated in 3 main categories:

Enrollment

The bank customer has different options to discover and activate his Invoice Emitters:

When the bank customer activates Younify using bank platform, a matching by CNP/CUI process starts and his Younify email is generated.

Once he activates an Invoice Emitter discovered by CNP/CUI, he will receive his unpaid invoices and all future invoices issued by the Invoice Emitter. For an active customer, Younify system will match his profile with all new Invoice Emitters that enroll with the platform. The bank customer will be able to activate the new Invoice Emitters discovered (by CNP/CUI).

At any point, the bank customer has the option to deactivate the Younify service for each of active Invoice Emitters. If one of the Invoice Emitter is deactivated, Younify will not receive invoices from Invoice Emitter for that specific bank customer.


Matching and activation by CNP/CUI

Matching and activation CNP/CUI


Matching and activation by custom codes

Matching and activation by custom codes


Manual setup Invoice Emitter

Manual setup Invoice Emitter


Deactivation

The deactivation of an invoice emitter has different flows for the bank customer:

Deactivation

The flow above represents the deactivation of an invoice emitter fully integrated with Younify.

Customer invoices

By accessing the Internet Banking application of the Bank, the customer has the option to view all Invoice Emitters discovered through the process of enrollment (active or inactive), status of the account (details, balance, etc.), the list of unpaid invoices with the necessary details and supporting PDF file of each invoice.

The customer has different options: activate Invoice Emitter, deactivate Invoice Emitter, view unpaid invoices details, view PDF files, pay invoices.

Customer invoices

Payment notification

The bank customer is able to pay the unpaid invoices displayed in the Internet Banking (invoice amount or different amount). The actual payment is handled by the Bank using the bank standard workflow of utility payment.

Younify system will receive a payment notification, which will be transmitted to the Invoice Emitter (only for the ones fully integrated with Younify). As a response to the payment notification, the Invoice Emitter will update the balance and status of the invoices accordingly.

In case there are issues in the bank payment process and Younify had received a payment notification, the Bank system is able to “cancel” the payment notification.

Payment notification

Architecture

Security and authorization

The authorization of the call from the client to the server should be made using Two-way SSL authentication in case of Web Services integration.

For each call to the server, the client should send a client certificate issued by the server’s certificate authority. If the client certificate is validated by the server, the call will be authorized.

As an alternate scenario, the authentication can be made using a signature based authentication mechanism, by providing a shared secret and generate a HMAC-SHA256 signature.

In case other integration styles are selected for some of the operations, all exchanges between the systems should be made on an encrypted channel.

Encryption of the connection

In order to secure the communication between the client and server, all data in transit on the internet should be encrypted.

If the server uses his own Certificate Authority, the client should be notified and should receive the Root and Intermediate Certificates (if needed), in order to trust the server when making the web service call.

As an extra level of securing and encrypting the communication between the Bank system and Younify system, at Bank’s request the two systems can use VPN(Virtual Private Network) to connect.

IP Filtering

Each client of the Web Service should have its IP added in the server whitelist firewall.

Availability and response time

Younify system guarantees 99.7% availability of the service over a trailing 365 days period. The web services that will be implemented by the Bank system should have the same availability rate or similar

Based on the integration style and operation type, the following SLA is applied.

SLA Type Description Reason Timing
A Real time User is waiting for a system response. Less than 2 seconds
B Near Real Time Stakeholder is waiting for a system notification Less than 5 minutes
C Scheduled Not time sensitive Less than 24 hours

The SLA can be related to the time when a notification is initiated by one of the systems (PROVIDER or BENEFICIARY) and to a response time.

Notification time SLA type

The SLA related to notifications that should be initiated by one of the systems (PROVIDER and BENEFICIARY) are detailed for each operation.

Response time SLA type

Operations that are implemented using REST, should respond with timing according to SLA type A.

Network Communication

We would recommend a minimum network bandwidth of 100Mbps in order to sustain the peaks. Based on the expected number of concurrent users this value should be adjusted.

REST API Overview

General information

A client references a resource by making a HTTP call to an URI that follows REST standard. The client application can use HTTP verbs to manipulate the data represented by the URI.

Method Action
GET Retrieve a specific item of the resource.
POST Create or initiate a resource
PUT Update the resource with the body of the enclosed request
DELETE Remove the resource

The URI has the following pattern:

<domain-name>/api/{version}/{resource}

In the rest of the document, the URI to access a resource will be provided with the following format:

GET /api/{version}/resource/:parameter

API Responses

HTTP Codes

The HTTP status code is embedded inside the header of the response.

20X Status codes indicate the success of the call:

HTTP Status code Descrption
200 OK The request is OK (this is the standard response for successful HTTP requests)
201 CREATED The resource has been created.


All other codes indicate that something went wrong:

HTTP Status code Descrption
400 Bad Request The request cannot be fulfilled due to bad syntax
403 Unauthorized Missing authentication information
404 Not Found Method/Data not found
500 Internal Server Error A generic error message, given when no more specific message is suitable

Response Format

{
   "code": 1001,
   "description": "Missing mandatory fields."
}

The stream format should be JSON encoded in UTF-8. If the call is successful, the WS will return an object containing the API response.

In case where the return is different from 20X, the body response can provide an object with the details of the error message.

Technical Errors

HTTP Status code Code Descrption
500 -1 Exception processing request.
403 -2 Missing authentication information


Application Errors

HTTP Status code Code Descrption
500 1000 Failed to parse request parameters/body.
400 1001 Missing mandatory fields.
400 1002 Field <parameter> does not have a valid format or has an unknown value.
400 1003 Fields<parameter> exceeds limit.

Besides the generic errors listed above, which may apply to all operations, each operation has its own specific error codes. Those error cases are listed for each operation separately.

Data types

Data exchanged between the client and server should have the following value ranges based on the type:

Data type Value range
string Is detailed at the level of each field. Ex. string(20)
int Minimum value: -2^31 (-2.147.483.648)
Maximum value: 2^31-1 (2.147.483.648)
long Minimum value: -2^63 (-9.223.372.036.854.775.808)
Maximum value: 2^63-1 (9.223.372.036.854.775.807)
double Minimum value: 1.7e–308
Maximum value: 1.7e+308
boolean true or false


API Reference (available on Younify)

Activate Younify

POST /api/{version}/customers

This operation will be used by the bank system to activate the Younify system for a customer. By activating the service, a customer will accept Younify terms and conditions and Younify system will start customer matching by CNP/CUI on available Invoice Emitter systems. Younify system will automatically create a Younify email for the customer based on his personal email, needed for manually setup of Invoice Emitters.

Once a customer is matched with an Invoice Emitter, he will be able to activate that specific Invoice Emitter and start receiving his invoices in the bank system.

The response of this operation specifies if the customer that has activated Younify already has invoices in Younify. He will be able to see his invoices on the search screen (this situation appears when the customer already has an account in Younify).

SLA type: A

POST /api/v1/customers

{
  "customerId": "23",
  "code": "1570121116722",
  "type": 0,
  "firstName": "Sebastian",
  "lastName": "Goga",
  "email": "sebastian.goga@email.com",
  "phone": "0740223344",
  "address": "str. Gognastului nr. 112",
  "city": "Alba Iulia",
  "county": "RO-AB",
  "country": "RO",
  "tcVersion": "v1.0",
  "tcDatetime": "2015-03-12T21:45:07+01:00"
}

Request

Parameter Required Type Details
customerId yes string(50) Customer bank internal identifier. This id will be used for all other operations.
code yes string(25) - CNP: if the customer is a person
- CUI: if the customer is a company
- IBAN: if the customer isn’t Romanian.
type yes int Type of customer:
- 0 : person
- 1 : company
- 2: non-resident person
- 3: non-resident company
firstName no string(255) In case of company should use this field for the name of the company
lastName no string(255)
email yes string(255) Customer email address will be used to generate his Younify custom email address.
phone no string(20)
address no string(255)
city no string(50)
county no string(5) County should be represented in ISO 3166-2:RO format (ex. RO-AB, RO-B)
country no string(2) Country should be represented in ISO 3166-1 alpha-2 format (ex. RO)
tcVersion yes string(10) Version of the terms and conditions that customer has accepted when enabling Younify.
tcDatetime yes string(25) Represents the time when the terms and conditions were accepted. The date should be represented in ISO 8601 format (YYYY-MM-DDThh:mm:ssTZ)

Response

{
  "hasInvoices": true,
}

Response

Parameter Required Type Details
hasInvoices yes boolean Specifies if the new customer has already invoices in Younify.

Specific errors

HTTP Status Code Code Description
400 12016 Customer id: {0} is duplicated for code: {1}
400 12025 Customer id: {0} is duplicated for email: {1}
400 12021 Terms&Conditions Version: {0} is not the latest version.

Get Younify email

GET /api/{version}/customers/{customerId}/customEmail

This operation will be used to retrieve the Younify email for a customer. The Younify email once created at a previous step will not change in time for a customer.

SLA type: A

GET /api/v1/customers/34/customEmail

Request

Parameter Required Type Details
customerId yes string(50) Represent bank customer identifier

Response

{
  "email": "sebastian.goga@ydocs.io"
}

Response

Parameter Required Type Details
email yes string(255) Represents the email generated by Younify for the user (the domain can be specific for the bank).

Specific errors

HTTP Status Code Code Description
404 12003 Customer not found for the provided customerId: {customerId}.

Change customer personal email

PUT /api/{version}/customers/{customerId}/email

This operation will be used to update the customer personal email. By changing the personal email of a customer, the Younify email address name will remain the same, but the forwarding rules will be changed to this new email.

All new emails received on Younify email will be automatically forwarded to the updated email address of the customer.

SLA type: A

PUT /api/v1/customers/34/email

{
  "email": "sebastian.goga@ydocs.io"
}

Request

Parameter Required Type Details
customerId yes string(50) Represent bank customer identifier
email yes string(255) Bank customer personal email.

Response: HTTP Status Code 200

Response

No response parameters with HTTP 200 status code.

Specific errors

HTTP Status Code Code Description
404 12003 Customer not found for the provided customerId: {customerId}.

Retrieve available Invoice Emitter list

GET /api/{version}/emitters

This operation will be used for retrieving the list of Invoice Emitters available in Younify platform. The list contains the full list of Invoice Emitters: automatic and manual activation.

SLA type: A

GET /api/{version}/emitters

Request

No request body

Response

[{
  "emitterId": "12",
  "emitterName": "APA CTTA S.A.",
  "fiscalNumber": "21237755",
  "logo": "https://partners.younify.ro/logo/12.png",
  "url": "http://apaalba.ro",
  "fullIntegration": true,
  "video": null,
  "needSigning": true,
  "allowCustomCodeMatching": true,
  "allowPartialPayment": true
}, {
  "emitterId": "13",
  "emitterName": "Agenția de Furnizare a Energiei Electrice Alba",
  "fiscalNumber": "21237756",
  "logo": "https://partners.younify.ro/logo/13.png",
  "url": "http://www.electricafurnizare.ro",
  "fullIntegration": false,
  "video": "https://www.youtube.com/watch?v=tb91sUU4rUs",
  "needSigning": false,
  "allowCustomCodeMatching": false,
  "allowPartialPayment": true
}]

Response

Parameter Required Type Details
invoiceEmitters yes array of InvoiceEmitter Available invoice emitters.

Details on “InvoiceEmitter” object:

Parameter Required Type Details
emitterId yes string(50) Invoice emitter identifier
emitterName yes string(255) Name of the Invoice Emitter
fiscalNumber yes string(10) Represents the fiscal number of the Invoice Emitter company.
logo no string(255) Link to the logo of the invoice emitter.
url yes string(255) Represents the link to Invoice Emitter website.
fullIntegration yes boolean - true: Invoice emitter is fully integrated and matching is done automatically
- false: Invoice emitter requires manual setup from customer.
video no string(255) Link to a tutorial on how the customer should setup this Invoice Emitter using his Younify Email.
This field will be empty for full integrated Invoice Emitters.
needSigning yes boolean - true: customer needs to sign specific terms & conditions when activating an Invoice Emitter Customer account. The specific Terms&Conditions can be retrieved using operation “Retrieve Terms&Conditions for Invoice Emitter”.
- false: customer should not sign any terms&conditions when activation an Invoice Emitter Customer account.
allowCustomCodeMatching yes boolean Specifies if the Invoice Emitter allows matching with custom codes.
allowPartialPayment yes boolean Specifies if the invoices can be paid partially or only with the full amount.

Specific errors

No specific errors.

Retrieve Invoice Emitter Customers for customer

GET /api/{version}/customers/{customerId}/emitterCustomers

This operation will be used to retrieve the list of Invoice Emitter Customers for a customer. The list will contain Invoice Emitter Customer matched by CNP/CUI (active or inactive), activated by custom codes (active) and activated manually with at least one invoice in the past 12 month.

In case the customer cancels his contract with the Invoice Emitter, Younify system will be notified for customer deactivation.

SLA type: A

GET /api/{version}/customers/23/emitterCustomers

Request

Parameter Required Type Details
customerId yes string(50) Represent bank customer identifier

Response

[{
  "emitterCustomerId": "23441",
  "emitterId": "12",
  "emitterName": "APA CTTA S.A.",
  "logo": "https://partners.younify.ro/logo/12.png",
  "details": "str. Gognastului nr. 112, Alba Iulia, Alba, 5005612523",
  "balance": 0,
  "currency": null,
  "fullIntegration": false,
  "onlineAccount": true,
  "active": false
}, {
  "emitterCustomerId": "82115",
  "emitterId": "13",
  "emitterName": "Agenția de Furnizare a Energiei Electrice Alba",
  "logo": "https://partners.younify.ro/logo/13.png",
  "details": "str. Meseriilor nr.67, Alba Iulia, Alba, 500121223",
  "balance": 500.23,
  "currency": "RON",
  "fullIntegration": true,
  "onlineAccount": true,
  "active": true
}]

Response

Parameter Required Type Details
invoiceEmitterCustomers yes array of InvoiceEmitterCustomer Matched Invoice Emitter Customers.

Details on “InvoiceEmitterCustomer” object:

Parameter Required Type Details
emitterCustomerId yes string(50) Invoice emitter customer identifier
emitterId yes string(50) Invoice emitter identifier
emitterName yes string(255) Name of the Invoice Emitter
logo no string(255) Link to the logo of the invoice emitter.
details yes string(255) Contains details on the consumption point of the customer (name, address, codes). This information will help the customer to identify different consumption points.
balance yes double Represents the current balance of the customer for this specific consumption point.
currency no string(3) Represents the currency and it should be transmitted using ISO4217:2008 currency code format.
In case the Invoice Emitter customer is inactive, the value of this field will be null.
fullIntegration yes boolean - true: Invoice emitter of Invoice Emitter Customer is fully integrated
- false: : Invoice emitter of Invoice Emitter Customer is manually integrated.
onlineAccount yes boolean Specifies if the discovered Invoice Emitter Customer has an online account with the InvoiceEmitter.

In case the customer doesn’t have an online account, he will not be able to activate the current Invoice Emitter Customer.

After he creates an online account on the Invoice Emitter platform, he will be able to activate the Invoice Emitter Customer.
active yes boolean Specifies if the Invoice Emitter Customer is active.

Specific errors

HTTP Status Code Code Description
404 12003 Customer not found for the provided customerId: {customerId}.

Activate Invoice Emitter Customer

POST /api/{version}/customers/init

This operation will be used to activate an Invoice Emitter Customer account that was matched using CNP/CUI. By activating an Invoice Emitter Customer all unpaid invoices (details and PDF) will be retrieved and customer will be marked as active. For any active Invoice Emitter Customer, the Invoice Emitter send updates regarding invoices (already sent invoices to Younify) and send new issued invoices.

In case the customer cancels his contract with the Invoice Emitter, Younify system will be notified for customer deactivation.

SLA type: A

POST /api/{version}/customers/init

{
  "customerId": "123187",
  "emitterCustomerId": "22",
  "emitterId": "8",
  "tcVersion": "v1.0",
  "tcDatetime": "2015-03-12T21:45:07+01:00"
}

Request

Parameter Required Type Details
customerId yes string(50) Represent bank customer identifier
emitterCustomerId yes string(50) Invoice emitter customer identifier
emitterId yes string(50) Invoice emitter identifier
tcVersion no string(10) Version of the terms and conditions that customer has accepted when enabling the invoice emitter.
*Required for Invoice “needSigning”=true
tcDatetime no string(25) Represents the time when the terms and conditions were accepted. The date should be represented in ISO 8601 format ( YYYY-MM-DDThh:mm:ssTZ ).
*Required for Invoice “needSigning”=true

Response

{
  "balance": 500,
  "currency": "RON",
  "invoiceCount": 3
}

Response

Parameter Required Type Details
balance yes double Represents the current balance of the customer for this specific consumption point.
currency yes string(3) Represents the currency and it should be transmitted using ISO4217:2008 currency code format
invoiceCount yes int Represents the number of unpaid invoices received from the Invoice Emitter when activating the account. The invoices will be retrieved on “search invoices” operation.

Specific errors

HTTP Status Code Code Description
404 12003 Customer not found for the provided customerId: {customerId}.
404 12004 Emitter Customer not found for the provided emitterCustomerId: {emitterCustomerId}.
404 12005 Invoice Emitter not found for the provided emitterId: {emitterId}.
500 12012 Customer {customerId} for emitter customer id {emitterCustomerId} already associated for invoice emitter {emitterId}.
400 12019 Terms & Conditions need to be signed for emitter: {emitterId}.
400 12021 Terms&Conditions Version: {0} is not the latest version.
400 12026 Failed to activate Emitter Customer, as he doesn’t have an online account on Invoice Emitter platform.

Activate Invoice Emitter Customer by custom codes

POST /api/{version}/customers/customCodes

This operation will be used to match and activate an Invoice Emitter Customer using custom codes: ClientCode, AccountNumber, InvoiceId, etc. The values of the custom codes are usually available on the invoice. If the customer enters valid custom codes, Younify system will retrieve all unpaid invoices for the account consumption point and the customer is marked as active. For any active Invoice Emitter Customer, the Invoice Emitter send updates regarding invoices (already sent invoices to Younify) and sends new issued invoices.

SLA type: A

POST /api/{version}/customers/customCodes

{
    "customerId": "23",
    "emitterId": "12",
    "tcVersion": "v1.0",
    "tcDatetime": "2015-03-12T21:45:07+01:00",
    "customCodes": [{
        "name": "clientCode",
        "value": "98273498232"
    }, {
        "name": "invoiceReference",
        "value": "18372627"
    }]
}

Request

Parameter Required Type Details
customerId yes string(50) Represent bank customer identifier
emitterId yes string(50) Invoice emitter identifier
customCodes yes array of CustomCode List of custom codes specific for a customer invoice
tcVersion no string(10) Version of the terms and conditions that customer has accepted when enabling the invoice emitter.
*Required for Invoice “needSigning”=true
tcDatetime no string(25) Represents the time when the terms and conditions were accepted. The date should be represented in ISO 8601 format ( YYYY-MM-DDThh:mm:ssTZ ).
*Required for Invoice “needSigning”=true

Details on “CustomCode” object:

Parameter Required Type Details
name yes string(255) Name of the custom code.
value yes string(255) Customer specific value for the code.

Response

{
    "invoiceEmitterCustomer": {
        "emitterCustomerId": "23441",
        "emitterId": "12",
        "emitterName": "APA CTTA S.A.",
        "logo": "https://partners.younify.ro/logo/12.png",
        "details": "str. Gognastului nr. 112, Alba Iulia, Alba, 5005612523",
        "balance": 200,
        "currency": "RON",
        "fullIntegration": true,
        "onlineAccount": true,
        "active": true
    },
    "invoiceCount": 2
}

Response

Parameter Required Type Details
invoiceEmitterCustomer yes InvoiceEmitterCustomer object Invoice emitter customer object.
invoiceCount yes int Represents the number of unpaid invoices received from the Invoice Emitter when activating the account. The invoices will be retrieved on “search invoices” operation.

Details on “InvoiceEmitterCustomer” object:

Parameter Required Type Details
emitterCustomerId yes string(50) Invoice emitter customer identifier
emitterId yes string(50) Invoice emitter identifier
emitterName yes string(255) Name of the Invoice Emitter
logo no string(255) Link to the logo of the invoice emitter.
details yes string(255) Contains details on the consumption point of the customer (name, address, codes). This information will help the customer to identify different consumption points.
balance yes double Represents the current balance of the customer for this specific consumption point.
currency no string(3) Represents the currency and it should be transmitted using ISO4217:2008 currency code format.
In case the Invoice Emitter customer is inactive, the value of this field will be null.
fullIntegration yes boolean - true: Invoice emitter of Invoice Emitter Customer is fully integrated
- false: : Invoice emitter of Invoice Emitter Customer is manually integrated.
onlineAccount yes boolean Specifies if the discovered Invoice Emitter Customer has an online account with the InvoiceEmitter.

In case the customer doesn’t have an online account, he will not be able to activate the current Invoice Emitter Customer.

After he creates an online account on the Invoice Emitter platform, he will be able to activate the Invoice Emitter Customer.
active yes boolean Specifies if the Invoice Emitter Customer is active.

Specific errors

HTTP Status Code Code Description
404 12005 Invoice Emitter not found for the provided emitterId: {emitterId}.
404 12003 Customer not found for the provided customerId: {customerId}.
404 12010 No invoice emitter customer found for the provided custom codes.
400 12020 Invoice emitter: {emitterId} does not allow matching with custom codes.
400 12019 Terms & Conditions need to be signed for emitter: {emitterId}.
400 12021 Terms&Conditions Version: {0} is not the latest version.
400 12026 Failed to activate Emitter Customer, as he doesn’t have an online account on Invoice Emitter platform.

Retrieve Terms&Conditions for Invoice Emitter

GET /api/{version}/emitters/{emitterId}/terms?language={language}

This operation will be used for retrieving the Terms&Conditions version and text for each Invoice Emitter. The Terms&Conditions should be signed by the bank customer when activating an Invoice Emitter Customer (CNP/CUI or custom codes).

SLA type: A

GET /api/{version}/emitters/12/terms?language=ro

Request

Parameter Required Type Details
emitterId yes string(50) Invoice emitter identifier
language no string(1) Language should be represented in ISO 639-1 format (ex. ro, en).
By default, Younify system sends the details in two languages: ro and en. At banks request, the details can be sent in additional languages.
Default value is “ro”.

Response

{
    "tcVersion": "v1.0",
    "tcFile": "SW52b2ljZSBQREYgZmlsZS4NCg0KTG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3Rld
               HVyIGFkaXBpc2NpbmcgZWxpdC4gVml2YW11cyBuaXNsIGxlY3R1cywgc3VzY2lwaXQgdml0YWUgbW
               9 sZXN0aWUgc2VkLCBhdWN0b3Igbm9uIHB1cnVzLiBWZXN0aWJ1bHVtIGNvbnZhbGxpcywgbG9yZW0
               gcXVpcyB2ZXN0aWJ1bHVtIGFsaXF1YW0sIGxpYmVybyBhcmN1IHByZXRpdW0gZWxpdCwgbm9uIHZh
               cml1cyBtYWduYSBsaWd1bGEgbmVjIG1pLiBTZWQgdml2ZXJyYSBwb3N1ZXJlIHZlaGljdWxhLiBFd
               GlhbSBwb3J0YSBtZXR1cyBldSBzYXBpZW4gdGluY2lkdW50IGxhY2luaWEuIEZ1c2NlIHV0IHB1cn
               VzIGEgZW5pbSBzb2xsaWNpdHVkaW4gZWxlaWZlbmQgdml0YWUgZXUgbmlzbC4gUHJvaW4gY3Vyc3V
               zIHZlbmVuYXRpcyBlbmltLCBub24gZmF1Y2lidXMgZWxpdCBwbGFjZXJhdCBmZXVnaWF0LiBNYXVy
               aXMgdml2ZXJyYSBtaSBuaWJoLCBub24gY29uZGltZW50dW0gbGliZXJvIGxhb3JlZXQgZXQuIE51b
               GxhbSB2ZWhpY3VsYSBleCB2aXRhZSB2ZWxpdCBjdXJzdXMgY29udmFsbGlzLiBBbGlxdWFtIG5lYy
               BkaWduaXNzaW0gdmVsaXQuDQoNCg0K "
}

Response

Parameter Required Type Details
tcVersion yes string(10) Version of the terms & conditions.
tcFile no string(50KB) PDF file that contain the text of the terms & conditions.
The string will be the encoded base64 string of the file byte[]. The size of the file will not exceed 50KB.

Specific errors

HTTP Status Code Code Description
404 12005 Invoice Emitter not found for the provided emitterId: {emitterId}.
404 12022 Terms & Conditions data not available for emitter: {emitterId}.

Retrieve custom codes list for Invoice Emitter

GET /api/{version}/emitters/{emitterId}/codes?language={language}

This operation will be used to retrieve the list of custom codes that need to be filled in by the bank customer that is activating an Invoice Emitter using custom codes.

SLA type: A

GET /api/{version}/emitters/12/codes?language=en

Request

Parameter Required Type Details
emitterId yes string(50) Invoice emitter identifier
language no string(1) Language should be represented in ISO 639-1 format (ex. ro, en).
By default, Younify system sends the details in two languages: ro and en. At banks request, the details can be sent in additional languages.
Default value is “ro”.

Response

[{
    "name": "clientCode",
    "displayName": "Client code",
    "description": "Please enter the client code (Ex. 2331721)",
    "regex": "[0-9]+",
    "order": 0
}, {
    "name": "invoiceId",
    "displayName": "Invoice number",
    "description": "Please enter the Invoice number (Ex. 781763/1)",
    "regex": null,
    "order": 1
}]

Response

Parameter Required Type Details
customCodes yes array of CustomCode Custom codes list for an Invoice Emitter.

Details on “CustomCode” object:

Parameter Required Type Details
name yes string(50) Name of the custom code. Example: clientCode, accountContract.
displayName yes string(50) Displayable name of the custom code. Example: Client Code, Account Contract.
description yes string(255) Short description of the code. This description can be used as a tooltip on the custom code field.
regex yes string(255) Regular expression to validate the format of the custom code.
order yes int Represents the order in which the codes should be displayed to the bank customer.

Specific errors

HTTP Status Code Code Description
404 12005 Invoice Emitter not found for the provided emitterId: {emitterId}.
400 12020 Invoice emitter: {emitterId} does not allow matching with custom codes.

Validate custom code format

GET /api/{version}/emitters/{emitterId}/codes/{name}/value/{value}/validate

This operation will be used to verify the format of a specific custom code. There are cases where the code can’t be validated automatically through regular expressions.

SLA type: A

GET /api/{version}/emitters/12/codes/clientCode/value/71265312/validate

Request

Parameter Required Type Details
emitterId yes string(50) Invoice emitter identifier
name yes string(50) Name of the custom code. Example: clientCode, accountContract.
value yes string(50) Value entered by the bank customer for the code.

Response: HTTP Status Code 200

Response

No response parameters with HTTP 200 status code.

Specific errors

HTTP Status Code Code Description
404 12005 Invoice emitter not found for the provided emitterId: {emitterId}
404 12017 Code name is not valid: {name}.
400 12018 Code with name: {name} does not have a valid format.
400 12020 Invoice emitter: {emitterId} does not allow matching with custom codes.

Search invoices

GET /api/{version}/customers/{customerId}/invoices?pageNumber={pageNumber}&pageSize={pageSize}&sortBy={sortBy}&asc={asc}&daysToDisplayPaid={daysToDisplayPaid}&updateInvoiceStatus={updateInvoiceStatus}&language={language}

This operation will be used to retrieve unpaid invoices for the bank customer. In the list of invoices returned by this operation it will be included also paid invoices from the last x days (number of days is added as parameter to the request).

SLA type: A

GET /api/{version}/customers/22/invoices?pageNumber=0&pageSize=10&sortBy=dueDate&asc=false&daysToDisplayPaid=60&updateInvoiceStatus=false&language=en

Request

Parameter Required Type Details
customerId yes string(50) Represent bank customer identifier
pageNumber yes int Represents page number for the invoices search. (Default value is 0)
pageSize yes int Represent number of invoices to be returned. (Default value is 10)
sortBy yes string(20) Represent the field that the invoices should be sorted by.
Available values:
- dueDate: sort invoices based on due date on the invoice. As there can be also paid invoices in the result, a second sort criteria will be applied by default in order to group and return unpaid invoices first, followed by paid once. When sorting by “dueDate”, the order will always be set to “desc”.
- invoiceEmitter: sort invoices by Invoice Emitter name.
- invoiceAmount: sort invoices by current amount on the invoice.
- balance: sort invoices by the balance on the Invoice Emitter.
Default sort value is: dueDate.
asc yes boolean Represent the direction of sorting.
daysToDisplayPaid yes int Represents number of days for which the paid invoice will be returned in the search result.
Default value is 30 days.
updateInvoiceStatus yes boolean When sorting by dueDate (the result also groups the invoices based on their status), if there are updates on the invoices (invoice payment or marking an invoice as paid/unpaid), the order of the invoices may change (the invoice may appear on a different page for a new search).

By default, the place of the invoice will remain the same when the user changes the status of the invoices.

To reset the order of invoices, call the search operation with this parameter set to true. It is recommended to do this action when the user starts a new search (requests page 0).

Default value is false
language yes string(2) Language should be represented in ISO 639-1 format (ex. ro, en).

Response

{
    "currentPage": 0,
    "totalPages": 1,
    "invoices": [{
        "invoiceId": "1827368122",
        "type": 0,
        "emitterId": "12",
        "emitterName": "APA CTTA S.A.",
        "fullIntegration": true,
        "emitterCustomerId": "23441",
        "logo": "https://partners.younify.ro/logo/12.png",
        "iban": "RO49AAAA1B31007593840000",
        "details": "Sebastian Goga, str. Gognastului, nr. 112",
        "currentAmount": 233.5,
        "amountToBePaid": 233.5,
        "balance": 233.5,
        "currency": "RON",
        "paymentCurrency": "RON",
        "dateOfIssue": "2015-06-25",
        "dueDate": "2015-07-25",
        "allowStatusChange": true,
        "customCodes": [{
            "name": "clientCode",
            "displayName": "Client code",
            "value": "98273498232"
        }, {
            "name": "invoiceReference",
            "displayName": "Invoice number",
            "value": "18372627"
        }],
        "pdfType": 0,
        "status": 0
    }, {
        "invoiceId": "389861424",
        "type": 0,
        "emitterId": "13",
        "emitterName": "Agenția de Furnizare a Energiei Electrice Alba",
        "fullIntegration": true,
        "emitterCustomerId": "23441",
        "logo": "https://partners.younify.ro/logo/13.png",
        "iban": "RO49AAAA1B31007593840000",
        "details": "Sebastian Goga, str. Gognastului, nr. 112",
        "currentAmount": 55.23,
        "amountToBePaid": 55.23,
        "balance": 55.23,
        "currency": "RON",
        "paymentCurrency": "RON",
        "dateOfIssue": "2015-06-17",
        "dueDate": "2015-07-18",
        "allowStatusChange": false,
        "customCodes": [{
            "name": "clientCode",
            "displayName": "Client code",
            "value": "582661-1"
        }, {
            "name": "invoiceReference",
            "displayName": "Invoice number",
            "value": "389861424"
        }],
        "pdfType": 1,
        "status": 0
    }]
}

Response

Parameter Required Type Details
currentPage yes int Current page of the search result.
totalPages yes int Total number of pages.
invoices yes array of Invoice List of invoice objects.

Details on “Invoice” object:

Parameter Required Type Details
invoiceId yes string(100) Represent the invoice number.
type yes int Represents the type of the invoice:
- 0: invoice
- 1: other: there are situations where the Invoice Emitter can sent notifications to active customers like: citation, notification.
When the invoice has the type “other”, the “details” field contains information on the invoice.
emitterId yes string(50) Invoice emitter identifier.
emitterName yes string(50) Name of the Invoice Emitter.
emitterLogo yes string(50) Link to the logo of the invoice emitter.
fullIntegration yes boolean - true: Invoice emitter is fully integrated and matching is done automatically
- false: Invoice emitter requires manual setup from customer.
emitterCustomerId yes string(50) Invoice emitter customer identifier.
iban no string(34) Represents the bank account number of the invoice emitter where the payments should be processed for the invoice. The format of the IBAN is transmitted using ISO 13616-1:2007.
details yes string(255) Contains details on the consumption point of the customer (name, address, codes). This information will help the customer to identify different consumption points.
currentAmount yes double It represents the amount for the presented invoice.
amountToBePaid yes double Represents the remaining amount to be paid on the presented invoice. It can have a different value from the currentAmount field, as the customer might have paid partially or in advance.
balance yes double Represents the current balance of the customer for this specific consumption point.
currency yes string(3) Represents the currency and it should be transmitted using ISO4217:2008 currency code format.
paymentCurrency yes string(3) Indicated the currency in which the payment should be done. In case the currency and paymentCurrency are different, the amount to be paid should be calculated at BNR rate on payment date. In this case, the bank should force the client to pay entire amount of money for this invoice.
dateOfIssue no string(10) Represents the date of issue of the bill. The date should be represented in ISO 8601 format ( YYYY-MM-DD )
dueDate no string(10) Represents the due date of the bill. The date should be represented in ISO 8601 format ( YYYY-MM-DD )
allowStatusChange no boolean The status of the invoice can be changed by the bank customer (mark invoice as paid/unpaid)
customCodes yes array of ExtendedCustomCode List of custom codes specific for the invoice.
pdfType yes int - 0: invoice pdf: the PDF associated with this invoice represents the invoice PDF issued by the Invoice Emitter.
- 1: invoice details: the PDF associated with this invoice is not the actual invoice issued by the Invoice Emitter, as the Invoice Emitter does not actually issue an invoice or Younify cannot retrieve the invoice from the Invoice Emitter.
status yes int - 0: due: the invoice is unpaid and due date is in the future.
- 1: overdue: the invoice is unpaid and due date has passed.
- 2: paid: the invoice is paid.
- 3: canceled: the invoice was cancelled by the Invoice Emitter.
- 4: pending: a payment was initiated for the invoice, but was not allocated yet to the invoice. In case an invoice has an “allocation pending” status, it will not be available for payment until the status is changed back to “due”/”overdue”.

Details on “ExtendedCustomCode” object:

Parameter Required Type Details
name yes string(255) Name of the custom code. Example: clientCode, accountContract.
displayName yes string(255) Displayable name of the custom code. Example: Client Code, Account Contract.
value yes string(50) Value entered by the bank customer for the code.

Specific errors

HTTP Status Code Code Description
404 12003 Customer not found for the provided customerId: {customerId}.

Retrieve invoice PDF

GET /api/{version}/emitters/{emitterId}/emitterCustomers/{emitterCustomerId}/invoices/{invoiceId}/customers/{customerId}

This operation will be used to download a specific invoice PDF.

SLA type: A

GET /api/{version}/emitters/23/emitterCustomers/5612/invoices/389861424/customers/4432

Request

Parameter Required Type Details
emitterId yes string(50) Invoice emitter identifier.
invoiceId yes string(100) Represent the invoice number.
emitterCustomerId yes string(50) Invoice emitter customer identifier.
customerId yes string(50) Represent bank customer identifier.

Response

{
    "file": "SW52b2ljZSBQREYgZmlsZS4NCg0KTG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3
            RldHVyIGFkaXBpc2NpbmcgZWxpdC4gVml2YW11cyBuaXNsIGxlY3R1cywgc3VzY2lwaXQgdml0Y
            WUgbW9sZXN0aWUgc2VkLCBhdWN0b3Igbm9uIHB1cnVzLiBWZXN0aWJ1bHVtIGNvbnZhbGxpc
            ywgbG9yZW0gcXVpcyB2ZXN0aWJ1bHVtIGFsaXF1YW0sIGxpYmVybyBhcmN1IHByZXRpdW0gZ
            WxpdCwgbm9uIHZhcml1cyBtYWduYSBsaWd1bGEgbmVjIG1pLiBTZWQgdml2ZXJyYSBwb3N1ZX
            JlIHZlaGljdWxhLiBFdGlhbSBwb3J0YSBtZXR1cyBldSBzYXBpZW4gdGluY2lkdW50IGxhY2luaWEuI
            EZ1c2NlIHV0IHB1cnVzIGEgZW5pbSBzb2xsaWNpdHVkaW4gZWxlaWZlbmQgdml0YWUgZXUgb
            mlzbC4gUHJvaW4gY3Vyc3VzIHZlbmVuYXRpcyBlbmltLCBub24gZmF1Y2lidXMgZWxpdCBwbGFj
            ZXJhdCBmZXVnaWF0LiBNYXVyaXMgdml2ZXJyYSBtaSBuaWJoLCBub24gY29uZGltZW50dW0g
            bGliZXJvIGxhb3JlZXQgZXQuIE51bGxhbSB2ZWhpY3VsYSBleCB2aXRhZSB2ZWxpdCBjdXJzdXM
            gY29udmFsbGlzLiBBbGlxdWFtIG5lYyBkaWduaXNzaW0gdmVsaXQuDQoNCg0K ",
    "type": "application/pdf"
}

Response

Parameter Required Type Details
file yes string(200KB) The string will be the encoded base64 string of the file byte[]. The size of the file will not exceed 200KB.
type yes string(20) Represents the MIME type of the file. The logo image can have the following types:
application/pdf

Specific errors

HTTP Status Code Code Description
404 12003 Customer not found for the provided customerId: {customerId}.
404 12004 Emitter Customer not found for the provided emitterCustomerId: {emitterCustomerId}.
404 12005 Invoice emitter not found for the provided emitterId: {emitterId}.
404 12006 Invoice not found for the provided invoiceId: {invoiceId}
404 12011 Invoice pdf file not available at this moment from Invoice Emitter.

Invoice payment notification

PUT /api/{version}/emitters/{emitterId}/invoices/{invoiceId}/payment

This operation will be used by the Bank system to notify Younify system that an amount of money was paid for a specific invoice. Younify will notify the Invoice Emitter (full integration only) regarding the payment that was processed and retrieve the new status of invoices from the Invoice Emitters.

SLA type: A

PUT /api/{version}/emitters/23/invoices/389861424/payment

{
    "customerId": "4432",
    "emitterCustomerId": "5612",
    "amount": 233,
    "currency": "RON",
    "transactionId": "3422",
    "channel": "younify",
    "iban": "RO49BBBB1C31007593840000",
    "customCodes": [{
            "name": "clientCode",
            "value": "98273498232"
        },
        {
            "name": "invoiceReference",
            "value": "18372627"
        }
    ]
}

Request

Parameter Required Type Details
customerId yes string(50) Represent bank customer identifier.
emitterCustomerId yes string(50) Invoice emitter customer identifier.
emitterId yes string(50) Invoice emitter identifier.
invoiceId yes string(100) Represent the invoice number.
transactionId yes string(50) Represents a transaction identifier. It can be used to relate to an in progress payment notification or an invoice payment cancellation.
amount yes double Amount of money paid by the customer for an invoice
currency yes string(3) Represents the currency and it should be transmitted using ISO4217:2008 currency code format
channel yes string(50) An invoice can be paid using the Younify menu from internet banking, utility payment service from internet banking, with cash at the cashier or other methods. Represents the channel used to initiate the payment.

At a later step final string should be defined based of available different channels. It can have values like: younify-IB, younify-cashier, younify-robot, etc.
iban no string(34) Represents the bank account of the invoice emitter where the invoice payment was processed. The format of the IBAN is transmitted using ISO 13616-1:2007.

In case this field is NULL, the customer should be triggered to enter the IBAN where the money should be transferred.
customCodes yes array of CustomCode List of custom codes specific for the invoice.

Details on “CustomCode” object:

Parameter Required Type Details
name yes string(50) Name of the custom code. Example: clientCode, accountContract.
value yes string(50) Value entered by the bank customer for the code.

Response: HTTP Status Code 200

Response

No response parameters with HTTP 200 status code.

Specific errors

HTTP Status Code Code Description
404 12003 Customer not found for the provided customerId: {customerId}.
404 12004 Emitter Customer not found for the provided emitterCustomerId: {emitterCustomerId}.
404 12005 Invoice emitter not found for the provided emitterId: {emitterId}.
404 12006 Invoice not found for the provided invoiceId: {invoiceId}
400 12007 Duplicate transactionId: {transactionId}.

Cancel invoice payment notification

DELETE /api/{version}/emitters/{emitterId}/invoices/{invoiceId}/payment

This operation will be used by the bank to notify Younify that a previous invoice payment was cancelled. Younify will notify the Invoice Emitter (full integration only) regarding the cancelled payment and retrieve the new status of invoices from the Invoice Emitter.

SLA type: A

DELETE /api/{version}/emitters/23/invoices/389861424/payment

{
    "customerId": "4432",
    "emitterCustomerId": "5612",
    "transactionId": "3422"
}

Request

Parameter Required Type Details
customerId yes string(50) Represent bank customer identifier.
emitterCustomerId yes string(50) Invoice emitter customer identifier.
emitterId yes string(50) Invoice emitter identifier.
invoiceId yes string(100) Represent the invoice number.
transactionId yes string(50) Represents a transaction identifier. Should be related to an invoice payment notification.

Response: HTTP Status Code 200

Response

No response parameters with HTTP 200 status code.

Specific errors

HTTP Status Code Code Description
404 12003 Customer not found for the provided customerId: {customerId}.
404 12004 Emitter Customer not found for the provided emitterCustomerId: {emitterCustomerId}.
404 12005 Invoice emitter not found for the provided emitterId: {emitterId}.
404 12006 Invoice not found for the provided invoiceId: {invoiceId}
400 12008 Transaction id ({transactionId}) does not belong to a payment.
400 12015 Payment for provided transaction id is final and can’t be cancelled.

Change invoice status

PUT /api/{version}/customers/{customerId}/emitters/{emitterId}/emitterCustomers/{emitterCustomerId}/invoices/{invoiceId}?paid={paid}

This operation will be used by the Bank system to notify Younify system that an invoice was marked as PAID / UNPAID by the bank customer. Only invoices from Invoice Emitters with light integration can have their statuses changed, as Invoice Emitters with full integration the status of the invoice is given by the Invoice Emitter.

The invoices that can have their status changed are marked with “allowStatusChange” flag.

SLA type: A

PUT /api/{version}/customers/23/emitters/10/emitterCustomers/55/invoices/42323-1?paid=true

Request

Parameter Required Type Details
customerId yes string(50) Represent bank customer identifier.
emitterId yes string(50) Invoice emitter identifier.
emitterCustomerId yes string(50) Invoice emitter customer identifier.
invoiceId yes string(100) Represent the invoice number.
paid yes boolean New status on the invoice.

Response: HTTP Status Code 200

Response

No response parameters with HTTP 200 status code.

Specific errors

HTTP Status Code Code Description
404 12003 Customer not found for the provided customerId: {customerId}.
404 12004 Emitter Customer not found for the provided emitterCustomerId: {emitterCustomerId}.
404 12005 Invoice emitter not found for the provided emitterId: {emitterId}.
404 12006 Invoice not found for the provided invoiceId: {invoiceId}

Deactivate Invoice Emitter customer

DELETE /api/{version}/customers/{customerId}/emitters/{emitterId}/emitterCustomers/{emitterCustomerId}

This operation will be used by the Bank system to notify Younify system to dismiss association between customer and invoice emitter. This means that a bank customer will not be using Younify services for a specific Invoice Emitter or that specific customer is no longer a customer.

By dissociating a customer from an Invoice Emitter, the Invoice Emitter will no longer send invoices for that Invoice Emitter Customer.

This operation refers only to the Invoice Emitters fully integrated with Younify.

SLA type: A

DELETE /api/{version}/customers/123187/emitters/22/emitterCustomers/23

Request

Parameter Required Type Details
customerId yes string(50) Represent bank customer identifier.
emitterCustomerId yes string(50) Invoice emitter customer identifier.
emitterId yes string(50) Invoice emitter identifier.

Response: HTTP Status Code 200

Response

No response parameters with HTTP 200 status code.

Specific errors

HTTP Status Code Code Description
404 12003 Customer not found for the provided customerId: {customerId}.
404 12004 Emitter Customer not found for the provided emitterCustomerId: {emitterCustomerId}.
404 12005 Invoice emitter not found for the provided emitterId: {emitterId}.

Deactivate customer

DELETE /api/{version}/customers/{customerId}

This operation will be used by the Bank system to notify Younify system to dismiss association between a customer and all of the invoice emitters. This means that a bank customer will not be using Younify services to retrieve his invoices.

By dissociating a customer from an Invoice Emitter, the Invoice Emitter will no longer send invoices for that Invoice Emitter Customer.

This operation refers only to the Invoice Emitters fully integrated with Younify. If the user has invoice emitters with manual integration the bank will display the information necessary for the user to deactivate manually the Invoice Emitter.

SLA type: A

DELETE /api/v1/customers/34

Request

Parameter Required Type Details
customerId yes string(50) Represent bank customer identifier.

Response: HTTP Status Code 200

Response

No response parameters with HTTP 200 status code.

Specific errors

HTTP Status Code Code Description
404 12003 Customer not found for the provided customerId: {customerId}.

Async operation feedback

POST /api/{version}/operations/feedback

This operation will be used to notify Younify system regarding the list of errors that occurred during the validation of data sent through operations that involve large amount of data transfer.

In case the list of errors is empty, all data was processed with success.

SLA type: C

POST /api/{version}/operations/feedback

{
    "correlationId": "b63e5ebc-1f56-11e7-93ae-92361f002671",
    "errors": [{
            "code": 11010,
            "description": "Customer not found for the provided customerId: 23."
        },
        {
            "code": 11010,
            "description": "Customer not found for the provided customerId: 24."
        }
    ]
}

Request

Parameter Required Type Details
correlationId yes string(50) Correlation identifier to be matched with a batch identifier.
errors yes array of Error List of application errors.

Details on “Error” object:

Parameter Required Type Details
code yes long Error code.
description yes string(50) Description of the error.

Response: HTTP Status Code 200

Response

No response parameters with HTTP 200 status code.

Specific errors

HTTP Status Code Code Description
400 12020 Correlation identifier: {correlationId} not available.

Notifications

New Invoice Emitter Customer available for customer

GET /api/{version}/notifications/customers?pageNumber={pageNumber}&pageSize={pageSize}&from={from}&to={to}

This operation will be used by the Bank system to retrieve updates regarding new matched Invoice Emitter Customers (account/contract/consumption points) for the existing Bank customers that had enabled Younify.

Also, when a new Invoice Emitter is connecting to Younify platform, all available customers are sent for matching on the new Invoice Emitter system. If the available customers are matched on the new Invoice Emitter, the association is with the Invoice Emitter is available for Bank system using this operation.

In case a matched customer signs a new contract with an existing Invoice Emitter, Younify system will be notified and this information will be available for Bank system. Once a bank customer is associated with an Invoice Emitter, the customer can activate that account/consumption point.

This operation will retrieve information only for the Invoice Emitters that are fully integrated.

SLA type: A

GET /api/{version}/notifications/customers?pageNumber=0&pageSize=10&from=2015-03-12T21:45:07%2B01:00&to=2015-03-12T22:45:07%2B01:00

Request

Parameter Required Type Details
pageNumber no int Represents page number for the search. (Default value is 0)
pageSize no int Represent number of items to be returned. (Default value is 10).
To retrieve all records in the selected period, this value should be set to 0. Please note that response may be large.
from no string(30) Represents the date time from when the items will be retrieved.
The date should be represented in ISO 8601 format ( YYYY-MM-DDThh:mm:ssTZ ).
(Default value: <current date> - <30 days>)
to no string(30) Represents the date time from when the items will be retrieved.
The date should be represented in ISO 8601 format ( YYYY-MM-DDThh:mm:ssTZ ).
(Default value: <current date>)

Response

{
    "currentPage": 0,
    "totalPages": 1,
    "invoiceEmitterCustomers": [{
        "customerId": "34",
        "emitterCustomerId": "23441",
        "emitterId": "12",
        "emitterName": "APA CTTA S.A.",
        "logo": "https://partners.younify.ro/logo/12.png",
        "details": "str. Gognastului nr. 112, Alba Iulia, Alba, 5005612523",
        "balance": 0,
        "currency": null,
        "fullIntegration": true,        
        "onlineAccount": true,
        "active": false,
        "notificationDate": "2015-03-12T22:45:07+01:00"
    }, {
        "customerId": "102",
        "emitterCustomerId": "82115",
        "emitterId": "13",
        "emitterName": "Agenția de Furnizare a Energiei Electrice Alba",
        "logo": "https://partners.younify.ro/logo/13.png",
        "details": "str. Meseriilor nr.67, Alba Iulia, Alba, 500121223",
        "balance": 0,
        "currency": null,
        "fullIntegration": true,        
        "onlineAccount": true,
        "active": false,
        "notificationDate": "2015-03-12T22:45:07+01:00"
    }]
}

Response

Parameter Required Type Details
currentPage yes int Current page of the search result.
totalPages yes int Total number of pages.
invoiceEmitterCustomers yes array of NotificationInvoiceEmitterCustomer Matched Invoice Emitter Customers.

Details on “NotificationInvoiceEmitterCustomer” object:

Parameter Required Type Details
customerId yes string(50) Customer bank internal identifier.
emitterCustomerId yes string(50) Invoice emitter customer identifier.
emitterId yes string(50) Invoice emitter identifier.
emitterName yes string(255) Name of the Invoice Emitter.
logo no string(255) Link to the logo of the invoice emitter.
details yes string(255) Contains details on the consumption point of the customer (name, address, codes). This information will help the customer to identify different consumption points.
balance yes double Represents the current balance of the customer for this specific consumption point.
currency no string(3) Represents the currency and it should be transmitted using ISO4217:2008 currency code format.
In case the Invoice Emitter customer is inactive, the value of this field will be null.
fullIntegration yes boolean - true: Invoice emitter of Invoice Emitter Customer is fully integrated
- false: : Invoice emitter of Invoice Emitter Customer is manually integrated.
onlineAccount yes boolean Specifies if the discovered Invoice Emitter Customer has an online account with the InvoiceEmitter.

In case the customer doesn’t have an online account, he will not be able to activate the current Invoice Emitter Customer.

After he creates an online account on the Invoice Emitter platform, he will be able to activate the Invoice Emitter Customer.
active yes boolean Specifies if the Invoice Emitter Customer is active.
notificationDate yes string(25) Represents the date time of the notification.
The date should be represented in ISO 8601 format (YYYY-MM-DDThh:mm:ssTZ).

Specific errors

No specific errors.

New Invoice for customer

GET /api/{version}/notifications/invoices?pageNumber={pageNumber}&pageSize={pageSize}&from={from}&to={to}

This operation will be used by the Bank system to retrieve updates regarding new invoices available in Younify for active bank customers of the bank.

SLA type: A

GET /api/{version}/notifications/invoices?pageNumber=0&pageSize=10&from=2015-03-12T21:45:07%2B01:00&to=2015-03-12T22:45:07%2B01:00

Request

Parameter Required Type Details
pageNumber no int Represents page number for the search. (Default value is 0)
pageSize no int Represent number of items to be returned. (Default value is 10).
To retrieve all records in the selected period, this value should be set to 0. Please note that response may be large.
from no string(30) Represents the date time from when the items will be retrieved.
The date should be represented in ISO 8601 format ( YYYY-MM-DDThh:mm:ssTZ ).
(Default value: <current date> - <7 days>)
to no string(30) Represents the date time from when the items will be retrieved.
The date should be represented in ISO 8601 format ( YYYY-MM-DDThh:mm:ssTZ ).
(Default value: <current date>)

Response

{
    "currentPage": 0,
    "totalPages": 1,
    "invoiceSummaries": [{
        "customerId": "34",
        "invoiceId": "1827368122",
        "type": 0,
        "emitterId": "12",
        "emitterName": "APA CTTA S.A.",
        "emitterLogo": "https://partners.younify.ro/logo/12.png",
        "fullIntegration": true,
        "details": "Sebastian Goga, str. Gognastului, nr. 112",
        "currentAmount": 233.5,
        "balance": 233.5,
        "currency": "RON",      
        "dateOfIssue": "2015-06-25",
        "dueDate": "2015-07-25",
        "status": 0,
        "notificationDate": "2015-03-12T22:45:07+01:00"
    }, {
        "customerId": "102",
        "invoiceId": "389861424",
        "type": 0,
        "emitterId": "13",
        "emitterName": "Agenția de Furnizare a Energiei Electrice Alba",
        "emitterLogo": "https://partners.younify.ro/logo/13.png",
        "fullIntegration": false,
        "details": "Sebastian Goga, str. Gognastului, nr. 112",
        "currentAmount": 55.23,
        "balance": 55.23,
        "currency": "RON",
        "dateOfIssue": "2015-06-17",
        "dueDate": "2015-07-18",
        "status": 0,
        "notificationDate": "2015-03-12T22:45:07+01:00"
    }]
}

Response

Parameter Required Type Details
currentPage yes int Current page of the search result.
totalPages yes int Total number of pages.
invoiceEmitterCustomers yes array of NotificationInvoiceSummary Summary of the new received invoices.

Details on “NotificationInvoiceSummary” object:

Parameter Required Type Details
customerId yes string(50) Customer bank internal identifier.
invoiceId yes string(100) Represent the invoice number.
type yes int Represents the type of the invoice:
- 0: invoice
- 1: other: there are situations where the Invoice Emitter can sent notifications to active customers like: citation, notification.
When the invoice has the type “other”, the “details” field contains information on the invoice.
emitterId yes string(50) Invoice emitter identifier.
emitterName yes string(50) Name of the Invoice Emitter.
emitterLogo yes string(50) Link to the logo of the invoice emitter.
fullIntegration yes boolean - true: Invoice emitter is fully integrated and matching is done automatically
- false: Invoice emitter requires manual setup from customer.
details yes string(255) Contains details on the consumption point of the customer (name, address, codes). This information will help the customer to identify different consumption points.
currentAmount yes double It represents the amount for the presented invoice.
balance yes double Represents the remaining amount to be paid on the presented invoice. It can have a different value from the currentAmount field, as the customer might have paid partially or in advance.
currency yes string(3) Represents the currency and it should be transmitted using ISO4217:2008 currency code format.
dateOfIssue no string(10) Represents the date of issue of the bill. The date should be represented in ISO 8601 format ( YYYY-MM-DD )
dueDate no string(10) Represents the due date of the bill. The date should be represented in ISO 8601 format ( YYYY-MM-DD )
status yes int - 0: due: the invoice is unpaid and due date is in the future.
- 1: overdue: the invoice is unpaid and due date has passed.
- 2: paid: the invoice is paid.
- 3: canceled: the invoice was cancelled by the Invoice Emitter.
- 4: pending: a payment was initiated for the invoice, but was not allocated yet to the invoice. In case an invoice has an “allocation pending” status, it will not be available for payment until the status is changed back to “due”/”overdue”.
notificationDate yes string(25) Represents the date time of the notification.
The date should be represented in ISO 8601 format (YYYY-MM-DDThh:mm:ssTZ).

Specific errors

No specific errors.

Due date for invoice

GET /api/{version}/notifications/invoices/due?pageNumber={pageNumber}&pageSize={pageSize}&from={from}&to={to}

This operation will be used by the Bank system to retrieve updates regarding customer invoices that have the due date in 2 days.

SLA type: A

GET /api/{version}/notifications/invoices/due?pageNumber=0&pageSize=10&from=2015-03-12T21:45:07%2B01:00&to=2015-03-12T22:45:07%2B01:00

Request

Parameter Required Type Details
pageNumber no int Represents page number for the search. (Default value is 0)
pageSize no int Represent number of items to be returned. (Default value is 10).
To retrieve all records in the selected period, this value should be set to 0. Please note that response may be large.
from no string(30) Represents the date time from when the items will be retrieved.
The date should be represented in ISO 8601 format ( YYYY-MM-DDThh:mm:ssTZ ).
(Default value: <current date> - <7 days>)
to no string(30) Represents the date time from when the items will be retrieved.
The date should be represented in ISO 8601 format ( YYYY-MM-DDThh:mm:ssTZ ).
(Default value: <current date>)

Response

{
    "currentPage": 0,
    "totalPages": 1,
    "invoiceSummaries": [{
        "customerId": "34",
        "invoiceId": "1827368122",
        "type": 0,
        "emitterId": "12",
        "emitterName": "APA CTTA S.A.",
        "emitterLogo": "https://partners.younify.ro/logo/12.png",
        "fullIntegration": true,
        "details": "Sebastian Goga, str. Gognastului, nr. 112",
        "currentAmount": 233.5,
        "balance": 233.5,
        "currency": "RON",
        "dateOfIssue": "2015-06-25",
        "dueDate": "2015-07-25",
        "status": 0,
        "notificationDate": "2015-03-12T22:45:07+01:00"     
    }, {
        "customerId": "102",
        "invoiceId": "389861424",
        "type": 0,
        "emitterId": "13",
        "emitterName": "Agenția de Furnizare a Energiei Electrice Alba",
        "emitterLogo": "https://partners.younify.ro/logo/13.png",
        "fullIntegration": false,
        "details": "Sebastian Goga, str. Gognastului, nr. 112",
        "currentAmount": 55.23,
        "balance": 55.23,
        "currency": "RON",
        "dateOfIssue": "2015-06-17",
        "dueDate": "2015-07-18",
        "status": 0,
        "notificationDate": "2015-03-12T22:45:07+01:00"
    }]
}

Response

Parameter Required Type Details
currentPage yes int Current page of the search result.
totalPages yes int Total number of pages.
invoiceEmitterCustomers yes array of NotificationInvoiceSummary Summary of the invoices having the due in 2 days.

Details on “NotificationInvoiceSummary” object:

Parameter Required Type Details
customerId yes string(50) Customer bank internal identifier.
invoiceId yes string(100) Represent the invoice number.
type yes int Represents the type of the invoice:
- 0: invoice
- 1: other: there are situations where the Invoice Emitter can sent notifications to active customers like: citation, notification.
When the invoice has the type “other”, the “details” field contains information on the invoice.
emitterId yes string(50) Invoice emitter identifier.
emitterName yes string(50) Name of the Invoice Emitter.
emitterLogo yes string(50) Link to the logo of the invoice emitter.
fullIntegration yes boolean - true: Invoice emitter is fully integrated and matching is done automatically
- false: Invoice emitter requires manual setup from customer.
details yes string(255) Contains details on the consumption point of the customer (name, address, codes). This information will help the customer to identify different consumption points.
currentAmount yes double It represents the amount for the presented invoice.
balance yes double Represents the remaining amount to be paid on the presented invoice. It can have a different value from the currentAmount field, as the customer might have paid partially or in advance.
currency yes string(3) Represents the currency and it should be transmitted using ISO4217:2008 currency code format.
dateOfIssue no string(10) Represents the date of issue of the bill. The date should be represented in ISO 8601 format ( YYYY-MM-DD )
dueDate no string(10) Represents the due date of the bill. The date should be represented in ISO 8601 format ( YYYY-MM-DD )
status yes int - 0: due: the invoice is unpaid and due date is in the future.
- 1: overdue: the invoice is unpaid and due date has passed.
- 2: paid: the invoice is paid.
- 3: canceled: the invoice was cancelled by the Invoice Emitter.
- 4: pending: a payment was initiated for the invoice, but was not allocated yet to the invoice. In case an invoice has an “allocation pending” status, it will not be available for payment until the status is changed back to “due”/”overdue”.
notificationDate yes string(25) Represents the date time of the notification.
The date should be represented in ISO 8601 format (YYYY-MM-DDThh:mm:ssTZ).

Specific errors

No specific errors.

Invoice payment

GET /api/{version}/notifications/invoices/payments?pageNumber={pageNumber}&pageSize={pageSize}&from={from}&to={to}

This operation will be used by the Bank system to retrieve updates regarding existing invoices that have been paid (full or partial) using other channels (direct at the Invoice Emitter office, other banks or any other means of payment). The service retrieves the current status of the invoices.

SLA type: A

GET /api/{version}/notifications/invoices/payments?pageNumber=0&pageSize=10&from=2015-03-12T21:45:07%2B01:00&to=2015-03-12T22:45:07%2B01:00

Request

Parameter Required Type Details
pageNumber no int Represents page number for the search. (Default value is 0)
pageSize no int Represent number of items to be returned. (Default value is 10).
To retrieve all records in the selected period, this value should be set to 0. Please note that response may be large.
from no string(30) Represents the date time from when the items will be retrieved.
The date should be represented in ISO 8601 format ( YYYY-MM-DDThh:mm:ssTZ ).
(Default value: <current date> - <7 days>)
to no string(30) Represents the date time from when the items will be retrieved.
The date should be represented in ISO 8601 format ( YYYY-MM-DDThh:mm:ssTZ ).
(Default value: <current date>)

Response

{
    "currentPage": 0,
    "totalPages": 1,
    "invoiceSummaries": [{
        "customerId": "34",
        "invoiceId": "1827368122",
        "type": 0,
        "emitterId": "12",
        "emitterName": "APA CTTA S.A.",
        "emitterLogo": "https://partners.younify.ro/logo/12.png",
        "fullIntegration": true,
        "details": "Sebastian Goga, str. Gognastului, nr. 112",
        "currentAmount": 233.5,
        "balance": 233.5,
        "currency": "RON",
        "dateOfIssue": "2015-06-25",
        "dueDate": "2015-07-25",
        "status": 0,
        "notificationDate": "2015-03-12T22:45:07+01:00"     
    }, {
        "customerId": "102",
        "invoiceId": "389861424",
        "type": 0,
        "emitterId": "13",
        "emitterName": "Agenția de Furnizare a Energiei Electrice Alba",
        "emitterLogo": "https://partners.younify.ro/logo/13.png",
        "fullIntegration": false,
        "details": "Sebastian Goga, str. Gognastului, nr. 112",
        "currentAmount": 55.23,
        "balance": 55.23,
        "currency": "RON",
        "dateOfIssue": "2015-06-17",
        "dueDate": "2015-07-18",
        "status": 0,
        "notificationDate": "2015-03-12T22:45:07+01:00"     
    }]
}

Response

Parameter Required Type Details
currentPage yes int Current page of the search result.
totalPages yes int Total number of pages.
invoiceEmitterCustomers yes array of NotificationInvoiceSummary Summary of the invoices that have the status changed.

Details on “NotificationInvoiceSummary” object:

Parameter Required Type Details
customerId yes string(50) Customer bank internal identifier.
invoiceId yes string(100) Represent the invoice number.
type yes int Represents the type of the invoice:
- 0: invoice
- 1: other: there are situations where the Invoice Emitter can sent notifications to active customers like: citation, notification.
When the invoice has the type “other”, the “details” field contains information on the invoice.
emitterId yes string(50) Invoice emitter identifier.
emitterName yes string(50) Name of the Invoice Emitter.
emitterLogo yes string(50) Link to the logo of the invoice emitter.
fullIntegration yes boolean - true: Invoice emitter is fully integrated and matching is done automatically
- false: Invoice emitter requires manual setup from customer.
details yes string(255) Contains details on the consumption point of the customer (name, address, codes). This information will help the customer to identify different consumption points.
currentAmount yes double It represents the amount for the presented invoice.
balance yes double Represents the remaining amount to be paid on the presented invoice. It can have a different value from the currentAmount field, as the customer might have paid partially or in advance.
currency yes string(3) Represents the currency and it should be transmitted using ISO4217:2008 currency code format.
dateOfIssue no string(10) Represents the date of issue of the bill. The date should be represented in ISO 8601 format ( YYYY-MM-DD )
dueDate no string(10) Represents the due date of the bill. The date should be represented in ISO 8601 format ( YYYY-MM-DD )
status yes int - 0: due: the invoice is unpaid and due date is in the future.
- 1: overdue: the invoice is unpaid and due date has passed.
- 2: paid: the invoice is paid.
- 3: canceled: the invoice was cancelled by the Invoice Emitter.
- 4: pending: a payment was initiated for the invoice, but was not allocated yet to the invoice. In case an invoice has an “allocation pending” status, it will not be available for payment until the status is changed back to “due”/”overdue”.
notificationDate yes string(25) Represents the date time of the notification.
The date should be represented in ISO 8601 format (YYYY-MM-DDThh:mm:ssTZ).

Specific errors

No specific errors.

Push Notification (Optional)

Bank system can receive real-time notifications for: new Invoice Emitter Customers available, new invoices received by the active customers, invoices due and payments on current invoices; by exposing a set of services.

New Invoice Emitter Customer available for customer notification

POST /api/{version}/customers/emitterCustomers

This operation will be used to notify the Bank system that a new Invoice Emitter Customer (account/contract/consumption points) are matched with the existing Bank customers that had enabled Younify.

Also, when a new Invoice Emitter is connecting to Younify platform, all available customers are sent for matching on the new Invoice Emitter system. If the available customers are matched on the new Invoice Emitter, the association is with the Invoice Emitter is sent to the Bank system using this operation. In case a matched customer signs a new contract with an existing Invoice Emitter, Younify system will be notified and Younify system will notify Bank system. Once a bank customer is associated with an Invoice Emitter, the customer can activate that account/consumption point.

As there can be large amount of data transferred between the two systems, the information should be sent in batches. Each batch should contain a number of maximum 10000 entries.

SLA type: A

POST /api/{version}/customers/emitterCustomers

{
    "correlationId": "b63e5ebc-1f56-11e7-93ae-92361f002671",
    "invoiceEmitterCustomers": [{
        "customerId": "23",
        "emitterCustomerId": "23441",
        "emitterId": "12",
        "emitterName": "APA CTTA S.A.",
        "logo": "https://partners.younify.ro/logo/12.png",
        "details": "str. Gognastului nr. 112, Alba Iulia, Alba, 5005612523",
        "balance": 0,
        "currency": null,
        "fullIntegration": true,
        "onlineAccount": true,
        "active": false
    }, {
        "customerId": "102",
        "emitterCustomerId": "82115",
        "emitterId": "13",
        "emitterName": "Agenția de Furnizare a Energiei Electrice Alba",
        "logo": "https://partners.younify.ro/logo/13.png",
        "details": "str. Meseriilor nr.67, Alba Iulia, Alba, 500121223",
        "balance": 0,
        "currency": null,
        "fullIntegration": true,
        "onlineAccount": true,
        "active": false
    }]
}

Request

Parameter Required Type Details
correlationId yes string(50) Batch feedback correlation identifier.
invoiceEmitterCustomers yes array of NotificationInvoiceEmitterCustomer Matched Invoice Emitter Customs.

Details on “NotificationInvoiceEmitterCustomer” object:

Parameter Required Type Details
customerId yes string(50) Customer bank internal identifier.
emitterCustomerId yes string(50) Invoice emitter customer identifier.
emitterId yes string(50) Invoice emitter identifier.
emitterName yes string(255) Name of the Invoice Emitter.
logo no string(255) Link to the logo of the invoice emitter.
details yes string(255) Contains details on the consumption point of the customer (name, address, codes). This information will help the customer to identify different consumption points.
balance yes double Represents the current balance of the customer for this specific consumption point.
currency no string(3) Represents the currency and it should be transmitted using ISO4217:2008 currency code format.
In case the Invoice Emitter customer is inactive, the value of this field will be null.
fullIntegration yes boolean - true: Invoice emitter of Invoice Emitter Customer is fully integrated
- false: : Invoice emitter of Invoice Emitter Customer is manually integrated.
onlineAccount yes boolean Specifies if the discovered Invoice Emitter Customer has an online account with the InvoiceEmitter.

In case the customer doesn’t have an online account, he will not be able to activate the current Invoice Emitter Customer.

After he creates an online account on the Invoice Emitter platform, he will be able to activate the Invoice Emitter Customer.
active yes boolean Specifies if the Invoice Emitter Customer is active.

Response: HTTP Status Code 200

Response

No response parameters with HTTP 200 status code.

As there are can be a large amount of data transferred and can take a lot of time to be processed, all application errors will be transmitted using Async operation feedback operation. When submitting the operation errors, the correlationId parameter should be sent in order to identify the batch with the feedback.

Data that didn’t failed validation should be processed accordingly.

All technical errors (authorization, parsing) will be returned as a response.

Specific errors

The errors displayed below will have to be sent using Async operation feedback operation as a feedback for this operation.

HTTP Status Code Code Description
404 11003 Customer not found for the provided customerId: {customerId}.

New Invoice for customer notification

POST /api/{version}/customers/invoices

This operation will be used to notify the Bank system that a new invoice was received for a customer.

As there can be large amount of data transferred between the two systems, the information should be sent in batches. Each batch should contain a number of maximum 10000 entries.

SLA type: A

POST /api/{version}/customers/invoices

{
    "correlationId": "bd7b9c6a-1f58-11e7-93ae-92361f002671",
    "invoiceSummaries": [{
        "customerId": "23",
        "invoiceId": "1827368122",
        "type": 0,
        "emitterId": "12",
        "emitterName": "APA CTTA S.A.",
        "emitterLogo": "https://partners.younify.ro/logo/12.png",
        "fullIntegration": true,
        "details": "Sebastian Goga, str. Gognastului, nr. 112",
        "currentAmount": 233.5,
        "balance": 233.5,
        "currency": "RON",
        "dateOfIssue": "2015-06-25",
        "dueDate": "2015-07-25",
        "status": 0
    }, {
        "customerId": "102",
        "invoiceId": "389861424",
        "type": 0,
        "emitterId": "13",
        "emitterName": "Agenția de Furnizare a Energiei Electrice Alba",       
        "emitterLogo": "https://partners.younify.ro/logo/13.png",
        "fullIntegration": false,
        "details": "Sebastian Goga, str. Gognastului, nr. 112",
        "currentAmount": 55.23,
        "balance": 55.23,
        "currency": "RON",
        "dateOfIssue": "2015-06-17",
        "dueDate": "2015-07-18",
        "status": 0
    }]
}

Request

Parameter Required Type Details
correlationId yes string(50) Batch feedback correlation identifier.
invoiceSummaries yes array of NotificationInvoiceSummary New invoices available in Younify.

Details on “NotificationInvoiceSummary” object:

Parameter Required Type Details
customerId yes string(50) Customer bank internal identifier.
invoiceId yes string(100) Represent the invoice number.
type yes int Represents the type of the invoice:
- 0: invoice
- 1: other: there are situations where the Invoice Emitter can sent notifications to active customers like: citation, notification.
When the invoice has the type “other”, the “details” field contains information on the invoice.
emitterId yes string(50) Invoice emitter identifier.
emitterName yes string(50) Name of the Invoice Emitter.
emitterLogo yes string(50) Link to the logo of the invoice emitter.
fullIntegration yes boolean - true: Invoice emitter is fully integrated and matching is done automatically
- false: Invoice emitter requires manual setup from customer.
details yes string(255) Contains details on the consumption point of the customer (name, address, codes). This information will help the customer to identify different consumption points.
currentAmount yes double It represents the amount for the presented invoice.
balance yes double Represents the remaining amount to be paid on the presented invoice. It can have a different value from the currentAmount field, as the customer might have paid partially or in advance.
currency yes string(3) Represents the currency and it should be transmitted using ISO4217:2008 currency code format.
dateOfIssue no string(10) Represents the date of issue of the bill. The date should be represented in ISO 8601 format ( YYYY-MM-DD )
dueDate no string(10) Represents the due date of the bill. The date should be represented in ISO 8601 format ( YYYY-MM-DD )
status yes int - 0: due: the invoice is unpaid and due date is in the future.
- 1: overdue: the invoice is unpaid and due date has passed.
- 2: paid: the invoice is paid.
- 3: canceled: the invoice was cancelled by the Invoice Emitter.
- 4: pending: a payment was initiated for the invoice, but was not allocated yet to the invoice. In case an invoice has an “allocation pending” status, it will not be available for payment until the status is changed back to “due”/”overdue”.

Response: HTTP Status Code 200

Response

No response parameters with HTTP 200 status code.

As there are can be a large amount of data transferred and can take a lot of time to be processed, all application errors will be transmitted using Async operation feedback operation. When submitting the operation errors, the correlationId parameter should be sent in order to identify the batch with the feedback.

Data that didn’t failed validation should be processed accordingly.

All technical errors (authorization, parsing) will be returned as a response.

Specific errors

The errors displayed below will have to be sent using Async operation feedback operation as a feedback for this operation.

HTTP Status Code Code Description
404 11003 Customer not found for the provided customerId: {customerId}.

Due date for invoice

PUT /api/{version}/customers/invoices/due

This operation will be used to notify the Bank system that existing invoices for customer have the due day in the following days.

As there can be large amount of data transferred between the two systems, the information should be sent in batches. Each batch should contain a number of maximum 10000 entries.

SLA type: A

PUT /api/{version}/customers/invoices/due

{
    "correlationId": "bd7b9c6a-1f58-11e7-93ae-92361f002671",
    "invoiceSummaries": [{
        "customerId": "23",
        "invoiceId": "1827368122",
        "type": 0,
        "emitterId": "12",
        "emitterName": "APA CTTA S.A.",
        "emitterLogo": "https://partners.younify.ro/logo/12.png",
        "fullIntegration": true,
        "details": "Sebastian Goga, str. Gognastului, nr. 112",
        "currentAmount": 233.5,
        "balance": 233.5,
        "currency": "RON",
        "dateOfIssue": "2015-06-25",
        "dueDate": "2015-07-25",
        "status": 2
    }, {
        "customerId": "102",
        "invoiceId": "389861424",
        "type": 0,
        "emitterId": "13",
        "emitterName": "Agenția de Furnizare a Energiei Electrice Alba",
        "emitterLogo": "https://partners.younify.ro/logo/13.png",
        "fullIntegration": false,
        "details": "Sebastian Goga, str. Gognastului, nr. 112",
        "currentAmount": 55.23,
        "balance": 55.23,
        "currency": "RON",
        "dateOfIssue": "2015-06-17",
        "dueDate": "2015-07-18",
        "status": 2
    }]
}

Request

Parameter Required Type Details
correlationId yes string(50) Batch feedback correlation identifier.
invoiceSummaries yes array of NotificationInvoiceSummary Invoices the have the due date in 2 days.

Details on “NotificationInvoiceSummary” object:

Parameter Required Type Details
customerId yes string(50) Customer bank internal identifier.
invoiceId yes string(100) Represent the invoice number.
type yes int Represents the type of the invoice:
- 0: invoice
- 1: other: there are situations where the Invoice Emitter can sent notifications to active customers like: citation, notification.
When the invoice has the type “other”, the “details” field contains information on the invoice.
emitterId yes string(50) Invoice emitter identifier.
emitterName yes string(50) Name of the Invoice Emitter.
emitterLogo yes string(50) Link to the logo of the invoice emitter.
fullIntegration yes boolean - true: Invoice emitter is fully integrated and matching is done automatically
- false: Invoice emitter requires manual setup from customer.
details yes string(255) Contains details on the consumption point of the customer (name, address, codes). This information will help the customer to identify different consumption points.
currentAmount yes double It represents the amount for the presented invoice.
balance yes double Represents the remaining amount to be paid on the presented invoice. It can have a different value from the currentAmount field, as the customer might have paid partially or in advance.
currency yes string(3) Represents the currency and it should be transmitted using ISO4217:2008 currency code format.
dateOfIssue no string(10) Represents the date of issue of the bill. The date should be represented in ISO 8601 format ( YYYY-MM-DD )
dueDate no string(10) Represents the due date of the bill. The date should be represented in ISO 8601 format ( YYYY-MM-DD )
status yes int - 0: due: the invoice is unpaid and due date is in the future.
- 1: overdue: the invoice is unpaid and due date has passed.
- 2: paid: the invoice is paid.
- 3: canceled: the invoice was cancelled by the Invoice Emitter.
- 4: pending: a payment was initiated for the invoice, but was not allocated yet to the invoice. In case an invoice has an “allocation pending” status, it will not be available for payment until the status is changed back to “due”/”overdue”.

Response: HTTP Status Code 200

Response

No response parameters with HTTP 200 status code.

As there are can be a large amount of data transferred and can take a lot of time to be processed, all application errors will be transmitted using Async operation feedback operation. When submitting the operation errors, the correlationId parameter should be sent in order to identify the batch with the feedback.

Data that didn’t failed validation should be processed accordingly.

All technical errors (authorization, parsing) will be returned as a response.

Specific errors

The errors displayed below will have to be sent using Async operation feedback operation as a feedback for this operation.

HTTP Status Code Code Description
404 11003 Customer not found for the provided customerId: {customerId}.

Invoice payment notification

PUT /api/{version}/customers/invoices

This operation will be used to notify the Bank system that existing invoices have been paid (full or partial) using other channels (direct at the Invoice Emitter office, other banks or any other means of payment).

As there can be large amount of data transferred between the two systems, the information should be sent in batches. Each batch should contain a number of maximum 10000 entries.

SLA type: A

PUT /api/{version}/customers/invoices

{
    "correlationId": "bd7b9c6a-1f58-11e7-93ae-92361f002671",
    "invoiceSummaries": [{
        "customerId": "23",
        "invoiceId": "1827368122",
        "type": 0,
        "emitterId": "12",
        "emitterName": "APA CTTA S.A.",
        "emitterLogo": "https://partners.younify.ro/logo/12.png",
        "fullIntegration": true,
        "details": "Sebastian Goga, str. Gognastului, nr. 112",
        "currentAmount": 233.5,
        "balance": 0,
        "currency": "RON",
        "dateOfIssue": "2015-06-25",
        "dueDate": "2015-07-25",
        "status": 2
    }, {
        "customerId": "102",
        "invoiceId": "389861424",
        "type": 0,
        "emitterId": "13",
        "emitterName": "Agenția de Furnizare a Energiei Electrice Alba",
        "emitterLogo": "https://partners.younify.ro/logo/13.png",
        "fullIntegration": false,
        "details": "Sebastian Goga, str. Gognastului, nr. 112",
        "currentAmount": 55.23,
        "balance": 0,
        "currency": "RON",
        "dateOfIssue": "2015-06-17",
        "dueDate": "2015-07-18",
        "status": 2
    }]
}

Request

Parameter Required Type Details
correlationId yes string(50) Batch feedback correlation identifier.
invoiceSummaries yes array of NotificationInvoiceSummary Invoices that have the status changed.

Details on “NotificationInvoiceSummary” object:

Parameter Required Type Details
customerId yes string(50) Customer bank internal identifier.
invoiceId yes string(100) Represent the invoice number.
type yes int Represents the type of the invoice:
- 0: invoice
- 1: other: there are situations where the Invoice Emitter can sent notifications to active customers like: citation, notification.
When the invoice has the type “other”, the “details” field contains information on the invoice.
emitterId yes string(50) Invoice emitter identifier.
emitterName yes string(50) Name of the Invoice Emitter.
emitterLogo yes string(50) Link to the logo of the invoice emitter.
fullIntegration yes boolean - true: Invoice emitter is fully integrated and matching is done automatically
- false: Invoice emitter requires manual setup from customer.
details yes string(255) Contains details on the consumption point of the customer (name, address, codes). This information will help the customer to identify different consumption points.
currentAmount yes double It represents the amount for the presented invoice.
balance yes double Represents the remaining amount to be paid on the presented invoice. It can have a different value from the currentAmount field, as the customer might have paid partially or in advance.
currency yes string(3) Represents the currency and it should be transmitted using ISO4217:2008 currency code format.
dateOfIssue no string(10) Represents the date of issue of the bill. The date should be represented in ISO 8601 format ( YYYY-MM-DD )
dueDate no string(10) Represents the due date of the bill. The date should be represented in ISO 8601 format ( YYYY-MM-DD )
status yes int - 0: due: the invoice is unpaid and due date is in the future.
- 1: overdue: the invoice is unpaid and due date has passed.
- 2: paid: the invoice is paid.
- 3: canceled: the invoice was cancelled by the Invoice Emitter.
- 4: pending: a payment was initiated for the invoice, but was not allocated yet to the invoice. In case an invoice has an “allocation pending” status, it will not be available for payment until the status is changed back to “due”/”overdue”.

Response: HTTP Status Code 200

Response

No response parameters with HTTP 200 status code.

As there are can be a large amount of data transferred and can take a lot of time to be processed, all application errors will be transmitted using Async operation feedback operation. When submitting the operation errors, the correlationId parameter should be sent in order to identify the batch with the feedback.

Data that didn’t failed validation should be processed accordingly.

All technical errors (authorization, parsing) will be returned as a response.

Specific errors

The errors displayed below will have to be sent using Async operation feedback operation as a feedback for this operation.

HTTP Status Code Code Description
404 11003 Customer not found for the provided customerId: {customerId}.