Sandbox

The main objective of the Sandbox Environment is to expose the bank’s APIs without offering access to sensitive data. It basically provides a simulation of the functionality of the bank’s actual backend systems, using a dummy set of data for testing purposes.

 


 

Sandbox Database Assumptions

The Sandbox Database was designed to address the particular needs and meet the purposes of this Environment. To this end, the database implementation was based on a few assumptions:

  1. For greater flexibility and independence among various third-party developers and their applications, each client application with a specific clientId will have access to a different subset of data. To achieve this, a template of basic data has been set, which is replicated each time an application with a new clientId attempts to connect to the database. The purpose of this replication is to provide each client application that connects to the Sandbox environment with the same initial set of dummy data.
  2.  A data reset mechanism is also provided, in case the tests performed block one or more of the available functions (for instance, by draining the available balance  of all the provided accounts, thus impeding future transactions).
  3. The template dataset consists of 3 users (UserA, UserB, UserC), with each one holding a specific number of accounts and/or cards (credit, debit, prepaid).
  4. Since the database contains only the particular dummy data, in order to get a valid response from several of the APIs, certain predefined values must be used, otherwise exceptions are thrown. These values are presented in detail in the following sections.
  5. Each login session with a generated oAuth token will expire after 60 minutes. After this timeframe, the client application will need to login again.

 


 

Valid Data Scenarios

Since the Sandbox database contains only a limited sample of dummy data, it is necessary to follow certain guidelines and use specific predefined data values in order to get valid responses. Otherwise, exceptions are thrown as explained below.

Login - User Authentication - Authorization

Sandbox uses the oAuth protocol for user authentication and authorization. Each client application will redirect to a specific page where users must insert their credentials to get authenticated. Upon successful authentication, they are redirected to an authorization page, and once they grant authorization rights to the client application, they are ready to use the application, via which they implicitly invoke the bank’s APIs.

Within the Sandbox environment, the valid credentials for user authentication are :

Username

UserA / UserB / UserC (case insensitive)

Password

123

If the aforementioned process is completed successfully, an oAuth Bearer token is generated which is saved in the Sandbox database and required as an Authorization Header for every request when calling the APIs (except for General Info APIs which do not require user authentication to generate a valid response).

 

Customer APIs

The existing API GET /customer/info does not require any further input apart from the Authorization Header containing an active token.

 

Security APIs

The calls of the implemented APIs are :

POST /{TokenType}/generate,

POST /{TokenType}/generate/force,

GET /token/validate/{TokenValue} and

GET /{TokenType}/validate/{TokenValue}.

All the above API calls require the Authorization Header, as well as one or two path parameters :

TokenType

extrapin / otp

TokenValue

3288000

 

Lookups APIs

The API call GET /POP/list has no required parameters, while the API call GET /POP/{PointTypeName}/list needs one parameter :

PointTypeName

none / atm / aps / branch / ebranch / all

 

Accounts APIs

The API call GET /accounts/list does not require any further input apart from the Authorization Header containing an active token.

The API /accounts/{accountId}/details requires the Authorization Header, as well as one path parameter:

accountId

The accountId can be retrieved from the response generated by invoking the first API

The API /accounts/{accountId}/transactions/{input_filter} requires the Authorization Header, as well as two path parameters :

accountId

The accountId can be retrieved from the response generated by invoking the first API

input_filter

{

      "fromDate": "2017-9-1",

      "toDate": "2018-1-30",

      "fromRow": "",

      "pageSize": 20,

      "lastBalance": 0.0

  }

Note

There are a couple of sample transactions for every user and account. To retrieve them, try the above input_filter.

As soon as the user performs a single or mass monetary transaction, the Account Transactions API will return a valid response when the proper timeframes are selected.

On the contrary, if there are no records of transactions within the selected timeframe, the following json object will be returned :

{

              “AccountTransactions”: [],

              “PagingInfo”: {

                            “RowIndex”: 0,

                            “MaxRows”: 0,

                            “CountRows”: false,

                            “TotalRowsCount”: 0

              }

}

 

Cards APIs

The following API calls require only the Authorization Header :

/cards/list
/cards/credit/list
/cards/debit/list
/cards/prepaid/list

The APIs regarding card details are :

/cards/{cardId}/details
/cards/credit/{cardId}/details
/cards/debit/{cardId}/details
/cards/prepaid/{cardId}/details

These APIs require the Authorization Header, as well as one path parameter:

cardId

The cardId can be retrieved from the response generated by invoking the respective ‘list’ API

The APIs regarding card transactions are :

/cards/{cardId}/transactions/{input_filter}
/cards/credit/{cardId}/transactions/{input_filter}
/cards/debit/{cardId}/transactions/{input_filter}
/cards/prepaid/{cardId}/transactions/{input_filter}

These APIs require the Authorization Header, as well as two path parameters :

cardId

The cardId can be retrieved from the response generated by invoking the respective ‘list’ API

input_filter

{

      "fromDate": "2017-9-1",

      "toDate": "2018-1-30",

      "fromRow": "",

      "pageSize": 20,

      "lastBalance": 0.0

  }

Note

There are a couple of sample transactions for every user and card. To retrieve them, try the above input_filter. 

 

Transactions APIs

The first set of APIs involve single monetary transfers from an account owned by the user to an IBAN of an account, either within the bank (owned by the same user or another client of Piraeus Bank) or from another bank (remittance).

The API /TransferToIban and /TransferToIban/Validate require the Authorization Header, as well as a JSON object within the request body :

transferToIban_input

{  

      "AccountId": "string",

      "IBAN": "string",

      "Amount": 0.0,

      "Reason": "string",

      "Currency": "EUR",

      "ChargeType": "string",

      "Priority": "string",

      "ContactPhone": "306911111111",

      "BeneficiaryName": "string",

      "SepaInfo": "123456"

}

 The API /TransferToIban/Execute/{SessionKey} needs the Authorization Header, as well as one path parameter :

SessionKey

The SessionKey can be retrieved from the response generated by invoking the /TransferToIban/Validate API

 

Warning

As mentioned before, TransferToIban refers to single monetary transactions between an account owned by the user and an account belonging to one of three potential destinations: the same user, another user within the bank and another person holding an account in a different bank.

Therefore, for this API to generate valid results, the destination IBAN should be one of the following :

 

Valid IBANs in case of Transfers within the  Bank

GR2801718220007022123123123

GR1801718220007022123456789

GR9001718220007025111222333

GR0101718220007027000112113

GR0101718220007052999999000

Valid IBANs in case of Remittance

GR9202600260000000000299650

CY22002001550000000000084100

 

The second set of APIs refers to bulk monetary transfers from an account owned by the user to a set of other IBANs, according to file, which is to be uploaded. In Sandbox environment, the file can be random, however its filename has to be unique every time.

The APIs /BulkPayment and /BulkPayment/Validate require the Authorization Header, as well as the file to be uploaded, while the API /BulkPayment/Execute/{SessionKey} requires the Authorization Header, as well as one path parameter :

SessionKey

The SessionKey can be retrieved from the response generated by invoking the /BulkPayment/Validate API

 

The third set of transactions APIs refers to payroll payments from an account owned by the user to a set of other IBANs, according to file, which is to be uploaded. Again, in Sandbox environment, the file can be random, however its filename has to be unique every time.

The APIs /Payroll and /Payroll/Validate require the Authorization Header, as well as the file to be uploaded, and a JSON object being one of the form-data elements containing the extra payroll information :

payroll_params

{

"AssetFrom":"agBqAGcAdwAxAHUAZQBpALcKtwDKV%2bLF%2bkC3Fc7p%2fLY%3d",

"AssetType":1,

"ContractNumber":"3051",

"DisketteNumber":1,

"NumberOfPayments":2,

"Description":"AAA",

"PaymentDate":"2017-06-07T21:00:00.000Z",

"Amount":2.3,

"Currency":"EUR",

"payload" : ""

}

 The API /Payroll/Execute/{SessionKey} requires the Authorization Header, as well as one path parameter :

SessionKey

The SessionKey can be retrieved from the response generated by invoking the /Payroll/Validate API

 

Note

Since the purpose of the Sandbox environment is to provide a simulation with dummy data, the process of file upload has been simplified and does not involve file content validation. Therefore, the only data stored includes information about the user performing the upload, the filename and date / time of upload.

The only precondition to validate the upload is that the filename has not been used before by the same User and ClientId. Then, a FileID is generated and returned, which will be used for the next step of BulkPayment / Payroll Validate.

 

Finally, there are four APIs which return history and details for BulkPayment and Payroll transactions :

 

/BulkPayment/History/{input_filter}

This API requires the Authorization Header, as well as one path parameter :

input_filter

{

"fromDate": "2017-01-01T14:36:55.6597275+03:00",

"toDate": "2017-12-09T14:36:55.6597275+03:00"

}

 /BulkPayment/{PaymentCode}/{PaymentDate}/Details

This API requires the Authorization Header, as well as two path parameters :

PaymentCode

The PaymentCode can be retrieved from the response generated by invoking the /BulkPayment/History API

PaymentDate

The PaymentDate can be retrieved from the response generated by invoking the /BulkPayment/History API

/Payroll/History/{input_filter}

This API requires the Authorization Header, as well as one path parameter :

input_filter

{

"TypeOfAction": 0,

"fromDate": "2017-01-01T14:36:55.6597275+03:00",

"toDate": "2017-12-09T14:36:55.6597275+03:00"

}

/Payroll/{PaymentCode}/Details

This API requires the Authorization Header, as well as two path parameters :

PaymentCode

The PaymentCode can be retrieved from the response generated by invoking the /Payroll/History API

 

Note

As soon as the user performs a BulkPayment or Payroll the respective History API will return a valid response when proper timeframes are selected. On the contrary, the Details APIs will only return the following message :

       “Τα αναλυτικά στοιχεία δεν είναι διαθέσιμα”

If there are no records of BulkPayment or Payroll transactions within the selected timeframe, the following message will be generated :

       “Η συναλλαγή σας δεν εκτελέστηκε λόγω προβλήματος στην επικοινωνία. Παρακαλούμε ξαναδοκιμάστε σε λίγο”

However, as described below, there are certain predefined scenarios where both History and Details are available.

 

In order to retrieve information from both the History and Details APIs, the required input and expected output is summarized in the following tables.

 

A. BulkPayment History

Input

{

"fromDate": "2015-02-01T00:00:00.00",

"toDate": "2015-08-01T00:00:00.00"

}

Output

{

"MassTransferFiles": [

{

"WinbankReference": "999000836",

"UserFileName": "PPS_3483057_15012801.EPPS",

"InputDate": "2015-02-12 00:00:00.0",

"SequenceNo": "999000836",

"TotalPayments": 3,

"StatusCode": "77",

"StatusCodeDescription": "",

"Comments": "",

"TotalOrderAmount": 60

},

{

"WinbankReference": "424",

"UserFileName": "καινουργιο_ νεο _30 χαρακτηρες",

"InputDate": "2015-04-01 00:00:00.0",

"SequenceNo": "653",

"TotalPayments": 3,

"StatusCode": "91",

"StatusCodeDescription": "Απέτυχε",

"Comments": "Ασυμφωνία Κωδικού Εταιρείας",

"TotalOrderAmount": 502085.05

},

{

"WinbankReference": "999001215",

"UserFileName": "PPS 3483057 15012801.EPPS",

"InputDate": "2015-06-05 00:00:00.0",

"SequenceNo": "999001215",

"TotalPayments": 3,

"StatusCode": "94",

"StatusCodeDescription": "",

"Comments": "Ολοκλήρωση επεξεργασίας αρχείου",

"TotalOrderAmount": 60

},

{

"WinbankReference": "999001218",

"UserFileName": "PPS 3483057 15012801.EPPS",

"InputDate": "2015-06-05 00:00:00.0",

"SequenceNo": "999001218",

"TotalPayments": 2,

"StatusCode": "2",

"StatusCodeDescription": "Εκτελείται Τώρα",

"Comments": "Επιτυχής έλεγχος αρχείου EPPS",

"TotalOrderAmount": 40

},

{

"WinbankReference": "999001217",

"UserFileName": "PPS 3483057 15012801.EPPS",

"InputDate": "2015-06-05 00:00:00.0",

"SequenceNo": "999001217",

"TotalPayments": 3,

"StatusCode": "4",

"StatusCodeDescription": "Παραλήφθηκε το απαντητικό αρχείο",

"Comments": "Ολοκλήρωση επεξεργασίας αρχείου",

"TotalOrderAmount": 60

},

{

"WinbankReference": "999001206",

"UserFileName": "PPS 3483057 15012801.EPPS",

"InputDate": "2015-06-05 00:00:00.0",

"SequenceNo": "999001206",

"TotalPayments": 2,

"StatusCode": "16",

"StatusCodeDescription": "",

"Comments": "Ολοκλήρωση επεξεργασίας αρχείου",

"TotalOrderAmount": 40

}

],

"EppsCode": 3483057

}

 

Input

{

"fromDate": "2017-01-01T00:00:00.00",

"toDate": "2017-06-30T00:00:00.00"

}

Output

{
"
MassTransferFiles": [
{
"WinbankReference": "981383524",
"UserFileName": "SEPA-20170626-12.xml",
"InputDate": "2017-06-26 00:00:00.0",
"SequenceNo": "981383524","TotalPayments": 1,
"StatusCode": "91",
"StatusCodeDescription": "Απέτυχε",
"Comments": "Εχει ξανασταλεί αρχείο με unq file nbr:12",
"TotalOrderAmount": 22
}],
"
EppsCode": 0
}

 

B. BulkPayment Details

Input

/BulkPayment/981383524/2017-06-26/Details

Output

{
"
FileData": {
"WinbankReference": "981383524",
"UserFileName": "SEPA-20170626-12.xml",
"InputDate": "2017-06-26 00:00:00.0",
"SequenceNo": "981383524",
"TotalPayments": 1,
"StatusCode": "91",
"StatusCodeDescription": "Απέτυχε",
"Comments": "Εχει ξανασταλεί αρχείο με unq file nbr:12",
"TotalOrderAmount": 22
},
"
FileDetails": [{
"RemittanceIndex": "1",
"PaymentReference": "",
"ExecutionDate": 1498435200000,
"BranchCode": "",
"PaymentType": "-",
"Country": "",
"Beneficiary": "Γιώργος Ανδρέου",
"PaymentDetails": "Μαζική Πληρωμή 2017-06-26",
"DebitAccount": "",
"CreditAccount": "GR1501720530005053000154783",
"BeneficiaryBank": "",
"BeneficiaryBankBic": "",
"PaymentNumber": "",
"Amount": 22
}],
"
ExecutionDate": 1498435200000,
"
DebitAccount": "GR1501720530005053000154783"
}

 

C. Payroll History

Input

{

"fromDate": "2015-02-01T00:00:00.00",

"toDate": "2015-08-01T00:00:00.00"

}

Output

{
"
FilePaymentsList": [{
"PayrollPayment": {
"AssetFromAccountNumberDashed": "5054-017448-432",
"AssetFromAccountIbanDashed": "",
"PayrollPaymentCode": "20170626-9273-2",
"PayrollPaymentDate": 1498424400000,
"ContractNumber": "9273",
"EmployeeCount": 1,
"PaymentDate": 1498424400000
},
"Description": "Payroll 06-2017",
"ReturnedEmployees": 0,
"ReturnedAmount": {
"Amount": 0,
"Currency": null,
"AmountType": null,
"BackendAmountType": null,
"AmountDate": null
},
"SubmittedAt": 1498424400000,
"ReceivedBy": "Διαδίκτυο"
}]
}