Gateway Technical Documentation

Access and Basics

How to start

Before starting the registration process your organisation must meet several prerequisites in order to be successfully onboarded as a customer for Coop Pank Gateway API:

• You must have a valid customer contract with Coop Pank.
• You must sign an additional Coop Pank Gateway contract.
• You must obtain an authentication certificate(s):
  • If you use the certificate for authentication issued by SK ID Solutions AS, you can use it for both Sandbox and Live. For operators it is mandatory to use the authentication certificate issued by SK ID Solutions AS. For single clients it is strongly suggested.
  • If you request the certificates from Coop Pank CA, you need test certificate for Sandbox and the other one for Live environment.

On-boarding process for starting to use live environment:

• The first thing you should do is submit the application for Coop Pank Gateway at Coop Pank webpage. In case you need any help with services, contact your personal Business Client Manager.
• Based on your application, IT support team prepares your dedicated Sandbox test environment.
• For testing in Sandbox an authentication certificate is needed. Sandbox accepts certificates issued by SK ID Solutions AS or by Coop Pank. Additional information about requesting an authentication certificate from Coop Pank.
• Development and testing of your integrations can start after receiving a confirmation email.
• After you are done with testing and ready to proceed to live, inform your Business Client Manager.
• In case you used the authentication certificate issued by Coop Pank for testing, you should request for another certificate for live environment. Live environment can not be used with test certificate. If you used the authentication certificate issued by SK ID Solutions AS, you can continue to use it for live as well.
• Business Client Manager prepares and signs the Coop Pank Gateway contract.
• After your contract is signed you will receive a confirmation email that your services are ready to use.

For additional help, please contact your personal Business Client Manager or the IT Support Team gateway@cooppank.ee.

Clients and connection schemes

It's possible to use the Gateway API services as a single client or as an operator.

Single clients

Using it as a single client means that client itself is the owner of the authentication certificate and connection software. Certificate provides access to one customer or legal entity only.

Operators/service providers and end users using their services

Operators or service providers are the intermediary. They themselves own a certificate and provide the service to multiple customers or legal entities. It is usually for accounting software providers and other similar business cases.

In this scheme there are two kinds of clients:

• service provider itself (software owner, technical aggregator) - they are directly connected to Gateway API;
• end user clients, who use Gateway API through service providers - not directly connected to Gateway API.

Only service provider connection software is using Gateway API services directly. End users are using the service provider software. For all requests we also need to know the end user - the actual client that uses the service provider. For this we require two HTTP headers in addition to regular expected input:

• Client-Code (registration code)
• Client-Country (country code in ISO 3166-1 alpha-2 format - issuing country of registration code)

If these are missing from the request, you will get a corresponding error.

Certificates

Authentication (connection) certificates are necessary for both test and live environments. Certificates are necessary for single clients and operators/service providers. Certificate identifies and confirms on transport layer that messages were sent by customer's software to the Bank.

• You can use the certificate for authentication issued by SK ID Solutions AS, you can use it for both Sandbox and Live. For operators it is mandatory to use the authentication certificate issued by SK ID Solutions AS. For single clients it is strongly suggested. There is no need to exchange any files with the bank and you can start using immediately.

• Alternatively you can request the certificates from Coop Pank CA, you need test certificate for Sandbox and the other one for Live environment. It is an SSL Base64 PEM certificate that also requires a key.

  Process for Coop Pank CA certificate generation (ignore if you are using SK ID Solution AS certificate):

  1. Follow the instructions to create the CSR file and private key.
  2. For Sandbox environment's certificate attach the CSR file when submitting the application for Coop Pank Gateway (CSR file does not have to be digitally signed).
  3. For Live environment's certificate send the CSR file to your personal Business Client Manager after you are done with testing. The CSR file must be digitally signed by the company's official representative (according to Estonian Business Registry).
  4. IT support team will sign it with CA certificate and will send you a generated certificate.

To verify your certificates and test the basic connection to the API you can use the Communication Test services service in both Live and Sandbox.

Digital stamp of Coop Pank

It is possible to add the digital stamp of Coop Pank to the following messages:

• Automatic Account Statement;
• Account Statement;
• Payment Status Report.

Digital stamp can be added to all contract types, the use of the digital stamp in services must be agreed upon in the Coop Pank Gateway contract.

A digital stamp is added to all messages, as agreed upon in the contract, except for error type of messages presented in XML format. Adding a digital stamp creates an ASICE container. Each XML file is placed in a separate digital container. This means that one digital container can contain one XML file.

File names are assigned to the digital container and the file inside as follows:

Depending on whether the response is digitally stamped or not, Content_Type in Header of the response may vary accordingly. See more details: Messaging.

Environments

Gateway has two environments:

• Live environment
• Sandbox environment

Live

Live base URL is: https://cpgw.cooppank.ee/

Sandbox

Sandbox can be used to test your integrations when on-boarding or also any additional developments. It is technically also very similar to Live environment - the services, messages structure etc. is the same.

Sandbox base URL is: https://cpgw-sandbox.cooppank.ee/

Gateway API services

List of services which are available in the Gateway API.

Messaging

One of the main functions of Coop Pank Gateway is the messaging service. On the database side, it consists of two tables - request table and response table. Customer posts its requests to request table and gets its messages from response table. By default the response table returns oldest unread first. Messaging process consists of three steps: posting a request, getting the response and deleting the response.

Flow of API requests:

POST [base-url]/gateway/api/payment # initiate payment request
GET [base-url]/gateway/api/messages/next # receive response message
# handle message on customer side
DELETE [base-url]/gateway/api/messages/[Message-Response-Id] # delete read message to confirm it's received
POST [base-url]/gateway/api/account-statement # initiate account statement request
GET [base-url]/gateway/api/messages/next # receive response message with account statement data status
# handle message on customer side
 DELETE [base-url]/gateway/api/messages/[Message-Response-Id] # delete read message to confirm it's received
POST [base-url]/gateway/api/account-balance # initiate account balance request
GET [base-url]/gateway/api/messages/next # receive response message with account balance data status
# handle message on customer side
DELETE [base-url]/gateway/api/messages/[Message-Response-Id] # delete read message to confirm it's received
GET [base-url]/gateway/api/messages/next # receive the oldest unread/undeleted message
# handle message on customer side
DELETE [base-url]/gateway/api/messages/[Message-Response-Id] # delete read message to confirm it's received

Sending requests