Implementing the EBICS Protocol with SEPA Payments
PeopleSoft Financial Gateway supports the use of EBICS to send SEPA files to the bank. This topic discusses using the EBICS protocol.
The EBICS (Electronic Banking Internet Communication Standard) protocol is SEPA compliant and can transmit ISO 20022 standard messages in XML format. The system issues SEPA Credit Transfer payment files.
Important! As of Update Image 39, Oracle PeopleSoft no longer supports any version of EBICS (Electronic Banking Internet Communication Standard) protocol.
|
Page Name |
Definition Name |
Usage |
|---|---|---|
|
EBICS_INFO |
Initialize and manage user keys and bank public keys. See also Understanding Using the EBICS Protocol with SEPA Payments. |
|
|
EBICS_ITEM_LIST |
Manage the EBICS information item list. |
PeopleSoft Financial Gateway supports the use of EBICS to send SEPA files to the bank.
EBICS implementation includes two main areas: key management and initialization, and file transmission.
These EBICS messages (versions H003 and H004) are supported for key management and initialization. They are constructed by the delivered EBICS code and are not predefined messages in Integration Broker:
INI (Initial transmit public key).
PUB (Transmit public key).
HIA (Initial transmit public key).
HCA (Transmit public key).
HPB (Download bank’s public keys).
The following diagram illustrates EBICS in a PeopleSoft system:
Users can initialize and manage their keys and bank public keys through the EBICS Information setup page, and leverage the EBICS protocol for payment file upload through Financial Gateway Payment Dispatch.
Layout Properties
You must specify EBICS attributes on your bank integration layouts. Navigate to the Bank Integration Layouts page (). Set up the EBICS layout property codes as follows:
EBICS_ID – Use the EBICS ID set up in the system.
EBICS_ORD_TYPE – Enter string value FUL.
EBICS_FORMAT – Use the order type value provided by the bank.
Specifications
PeopleSoft Financial Gateway provides the following functionality for EBICS version 2.4.2:
Supports EBICS XML messages, based on these schemas:
ebics_keymgmt_request.xsd
ebics_keymgmt_response.xsd
ebics_orders.xsd
ebics_request.xsd
ebics_response.xsd
ebics_types.xsd
xmldsig-core-schema.xsd
Supports ZIP compression of order data.
Encrypts order data (E002).
Provides BASE64 coding of order data.
Provides segmentation of order data.
Adds an electronic signature for the order data (A005).
Identifies and authenticates the signature (X002).
Offers key management.
Supports EBICS upload transactions.
Integrating Your PeopleSoft System with EBICS
EBICS depends on HTTPS over TLS which must be fully functional on PeopleTools. Your PeopleSoft system administrator and PeopleSoft application developer must do the following to integrate EBICS with your PeopleSoft system:
Establish application server settings where the EBICS gateway will be set up.
Use PeopleSoft Integration Broker’s local gateway as the default gateway or create a new one.
Obtain and import the EBICS certification files from the SSL certification authority (CA), Entrust.
Modify Web server environment and Integration Gateway properties files.
Add Integration Broker node and routing definitions for EBICS under service operation EBICS_SERVICE_OPR.
All transaction messages sent though Integration Broker to the bank are synchronous messages. In order to troubleshoot a transactional issue between the Peoplesoft system and EBICS, you need to turn on logging for the SAMPLE_ROUTING routing definition.
EBICS return codes are defined in the message catalog as shown in this table:
|
Message Number |
Return Code |
Short Description |
Long Description |
|---|---|---|---|
|
1 |
000000 |
EBICS transaction OK |
No technical errors occurred during processing of the EBICS request |
|
2 |
011101 |
Segment number not reached |
The total number of segments transmitted during transaction initialization was not reached |
|
3 |
061001 |
Authentication signature error |
Verification of the authentication signature was not successful |
|
4 |
061002 |
Message not EBICS conformant |
The syntax of the received message does not conform with EBICS specifications |
|
5 |
061099 |
Internal EBICS error |
An internal error occurred during processing of the EBICS request |
|
6 |
091008 |
Bank key invalid |
The public bank key that is available to the subscriber is invalid |
|
7 |
091011 |
The transmitted HostID is unknown |
The transmitted HostID is unknown on the bank's side |
|
8 |
091117 |
The bank system does not support the requested order size |
Upload or download of an order file of improper size |
|
9 |
091120 |
The partner ID of the ES file is not identical to the partner ID of the submitter. |
On verifying the submitted signatures a partner ID was found in the document UserSignatureData that is not identical to the subscriber's partner ID in the request header |
|
10 |
091201 |
The algorithm version of the bank-technical keys is not supported by the financial institution |
The algorithm version of the bank-technical keys is not supported by the financial institution |
|
11 |
091204 |
The key length of the bank technical key is not supported by the financial institution |
Ask the financial institution for information on permitted key lengths, regenerate key |
|
12 |
091208 |
Certificate is not valid because it has expired |
Reject of the Request is mandatory if X509 v3 is supported. The user state remains unchanged. |
|
13 |
091209 |
Certificate is not valid because it is not yet in effect |
Reject of the Request is mandatory if X509 v3 is supported. The user state remains unchanged. |
|
14 |
091218 |
The key or certificate sent is the same as the signature key/certificate |
the key or certificate sent is the same as the signature key/certificate |
|
17 |
100002 |
Bank response message signature verify fail |
|
|
18 |
091002 |
EBICS Invalid User or User State |
Either the initiating party is not known to the bank system or the subscriber state that is stored in the bank of the initiating party is inadmissible with regard to the order type |
|
19 |
090004 |
EBICS Invalid Order Data Format |
The transferred order data does not correspond with the specified format |
|
20 |
091203 |
EBICS Key Manager Unsupported Version Encryption |
The algorithm version of the encryption key is not supported by the financial institution (order types HIA, HSA, and HCA) |
|
21 |
091202 |
EBICS Key Manager Unsupported Version Authentication |
The algorithm version of the authentication key is not supported by the financial institution (order types HIA, HSA, and HCA) |
|
22 |
091205 |
EBICS Key Manager Key Length Error Authentication |
The key length of the authentication key is not supported by the financial institution (order types HIA, HSA, HCS, and HCA) |
|
23 |
091206 |
EBICS Key Manager Key Length Error Encryption |
The key length of the encryption key is not supported by the financial institution (order types HIA, HSA, HCS, and HCA) |
|
24 |
091003 |
EBICS User Unknown |
The initiating party is not known to the bank system |
|
25 |
091004 |
EBICS Invalid User State |
The subscriber state of the initiating party that is stored in the bank system is inadmissible with regard to the order type |
|
26 |
091103 |
EBICS Suspected Message Replay |
A message replay has been identified (Nonce/Timestamp pair doubled) or the difference of clock time between client and server exceeds the (parametrisable) tolerance limit |
|
27 |
091301 |
EBICS Signature Verification Failed |
Verification of the ES has failed In the case of asynchronously implemented orders, the error can occur during preliminary verification. |
|
28 |
091306 |
EBICS Duplicate Signature |
The signatory has already signed the order on hand |
|
29 |
091010 |
XML invalid according to EBICS XML schema |
XML validation with EBICS schema failed or XML not well-formed |
|
30 |
091113 |
Message Content Semantically not Compliant to EBICS |
The received message complies syntactically EBICS XML schema, but not semantically to the EBICS guidelines, e.g. IZV upload with UZHNN requires NumSegments = 0 |
|
31 |
091005 |
EBICS Order Type Invalid |
The order type is unknown or not approved for use with EBICS |
|
32 |
091006 |
EBICS Order Type not Supported |
The selected order type is optional with EBICS and is not supported by the financial institution |
|
33 |
090003 |
EBICS Authorization Order Type Failed |
The subscriber is not entitled to submit orders of the selected order type |
|
34 |
091121 |
The specified order attribute is not compatible with the order in the bank system |
For example, order attribute "UZHNN" for an order with order attribute "DZHNN", order attribute "DZHNN" for an order with order attribute "UZHNN" or "OZHNN" |
|
35 |
091101 |
Transaction ID Invalid |
The supplied transaction ID is invalid |
|
36 |
091102 |
Transaction Cancelled |
The transaction was cancelled at the server’s end since recovery of the transaction is not supported or is no longer possible due to the recovery counter being too high |
|
37 |
061101 |
Synchronisation Necessary |
Recovery of the transaction requires synchronisation between the customer system and the bank system |
|
38 |
091105 |
EBICS Recovery not Supported |
The bank system does not support Recovery |
|
39 |
091104 |
Segment Number Exceeded |
The total segment number from transaction initialization was exceeded, i.e. the attribute @lastSegment was set to false when the last segment was transmitted |
|
40 |
091009 |
Segment Size Exceeded |
The specified size of an upload order data segment has been exceeded |
|
41 |
091217 |
EBICS Only X509 Support |
With respect to certificates, the bank system only supports the evaluation of X509 data |
|
42 |
091214 |
EBICS X509 UNKNOWN CERTIFICATE AUTHORITY |
The chain cannot be verified due to an unknown certificate authority (CA) |
Entering Certificates Into the Keystore
When a customer uploads the keystore file to PeopleSoft, three certificates are required. These three certificates must have a corresponding alias name:
authentication
encryption
signature
The PeopleSoft system recognizes the certificates based on their alias names.
The following rules apply:
The three certificates are not interchangeable. They each have a different purpose. For example, the authentication alias must correspond to the authentication certification.
You must use your own password and keystore name when creating the keystore.
This example shows how to create and add the three certificates into keystore:
keytool -genkeypair -keystore
ebicskeystore -keyalg rsa -alias authentication -sigalg SHA256withRSA
keytool -genkeypair -keystore
ebicskeystore -keyalg rsa -alias encryption -sigalg SHA256withRSA
keytool -genkeypair -keystore
ebicskeystore -keyalg rsa -alias signature -sigalg SHA256withRSA
Use the EBICS Information page (EBICS_INFO) to initialize and manage keys and bank public keys.
Navigation:
This example illustrates the fields and controls on the EBICS Information page. You can find definitions for the fields and controls later on this page.
Field or Control |
Description |
|---|---|
EBICS ID |
Enter an EBICS ID. |
Host ID |
Enter the Host ID. |
Partner ID |
Enter the Partner ID. |
User ID |
Enter the User ID. |
Target Node |
Select a target node. The lookup prompt shows the target nodes that have the routing attached to service operation EBICS_SERVICE_ORP. |
Country Code |
Select a country code. |
Connect Status |
Displays the connection status. |
Version |
Select H003 or H004 to indicate which EBICS standard version is supported for this EBICS ID. |
User Keys
Field or Control |
Description |
|---|---|
Keystore File |
Displays the name of the keystore file in the database. |
Upload Key Store |
Click this button to upload the key store file attachment. The selected file will be upload to database as a key store file. This process does not check the file type. |
Initialization |
Click this button to initialize a key for a new EBICS ID. Available only after the key store file has been successfully uploaded when setting up a new EBICS ID. Enter the key store password on the Load Key Store page and click the OK button. The process check the Upload Key Store file against the entered password. If the key store file is the correct type, the process checks out the public keys from key store file. Based on the number and type of the public keys, the system then populates the Load CERT List page, which contains these fields:
Select an action check box—Update Signature Key or Update AU and Encrypt Keys. Click the OK button to communicate the password to the bank, and save the successfully initialized keys to database. If any of the three keys is lost from the key store file, the related field and the Action check boxes are unavailable. |
Change Keys |
Click this button to change keys for an existing EBICS ID. |
Get Bank Keys |
Click this button to send the HPB (download bank’s public keys) message to the bank to get bank keys for X002 and E002. |
Owned Keys grid |
Displays user-owned keys. |
Bank Keys
The Bank Keys grid shows the public bank keys, including an alias name, effective date, and active status.
Use the EBICS Item List page (EBICS_ITEM_LIST) to manage the EBICS information item list.
Navigation:
This example illustrates the fields and controls on the EBICS Item List page.
