Standing order initiation API call flow (PISP)


This API allows to initiate standing order.


Step 1: Use the access token with the scope PISP
Obtaining access token can be based on SCA by OAuth 2.0 Authorization code grant flow (SCA) or on OAuth 2.0 Client credentials grant flow (Token by secret). See Authorization API section.


Step 2: Initiate standing order
Initiate POST request for Standing order initiation with valid access token:

Standing order initiation
Version1
URL LIVE
URL SANDBOX
POST https://api.csob.sk/pisp/api/v1/payments/standingOrder/sba
POST https://api.csob.sk/pisp-test/api/v1/payments/standingOrder/sba

This service allows to initiate Standing order in JSON format. Only EUR payments within SEPA area are allowed (excluding Switzerland and Monaco). On API Explorer web site there is a possibility to test the API online (Try it) and download API definition (WADL, Open API).


Request:

Header

Attributes structure
Optionality
Type
Description
Content-Type
Mandatory
String
application/json;charset=UTF-8
Authorization
Mandatory
String
Authorization is defined in RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage
Request-ID
Mandatory
String
A unique identifier of a particular request message. Although it may be arbitrary string, it is strongly recommended to use a Universally Unique Identifier (UUID) version 4 form (RFC4122).
Correlation-ID
Optional
String
A unique correlation identifier correlates the request and the response messages as a pair especially useful for audit logs. Although it may be arbitrary string, it is strongly recommended to use a Universally Unique Identifier (UUID) version 4 form (RFC4122).
Process-ID
Optional
String
Identifier of a business or technical process to what the set of requests and response pairs are organized (e.g. paging of transaction history should have same ProcessID). Although it may be arbitrary string, it is strongly recommended to use a Universally Unique Identifier (UUID) version 4 form (RFC4122).
PSU–IP-Address
Mandatory
String
Identifier of a customer’s IP address from which he/she is connected to the TPP infrastructure. It might be in the format of IPv4 o IPv6 address.
ASPSP shall indicate which values are acceptable.
PSU-Device-OS
Mandatory
String
A customer’s device and/or operating system identification from which he/she is connected to the TPP infrastructure.
PSU-User-Agent
Mandatory
String
A customer’s web browser of other client device identification from which he/she is connected to the TPP infrastructure. Agent header field of the http request between PSU and TPP.)
PSU-GeoLocation
Optional
String
The GPS coordinates of the current customer’s location in the moment of connection to the TPP infrastructure. (Required GPS format: Latitude, Longitude)
PSU-Last-Logged-Time
Optional
DateTime
Last date and time when user was logged to TPP app (RFC3339 format).

Body

Attributes structure
Level 1
Level 2
Optionality
Type
Description
instructionIdentification
Mandatory
String [200]
Technical identification of the payment generated by a PISP (or PSU).
creationDateTime
Optional
DateTime
The date and time in RFC3339 format at which a particular action has been requested or executed.
debtor
iban
Mandatory
String [34]
Debtor account International Bank Account Number (IBAN)
creditor
name
Optional
String [70]
Creditor name (first name and surname in case of individual persons or company name)
creditor
addressLine1
Optional
String [35]
Creditor address.
Example: Street and number
creditor
addressLine2
Optional
String [35]
Creditor address.
Example: Town
creditor
iban
Mandatory
String [34]
Creditor account International Bank Account Number (IBAN)
instructedAmount
value
Mandatory
Number Float [9.2]
Transaction amount value. Numeric value of the amount as a fractional number. The fractional part has a maximum of two digits.
instructedAmount
currency
Mandatory
String[3]
Transaction amount currency. Formated in Alphabetic codes from ISO 4712.
Only EUR is allowed.
endToEndIdentification
Optional
String [35]
Unique identification defined by a requestor (PSU)
remittanceInformation
Optional
String [140]
The text aimed as the information for a receiver of the transaction.
standingOrderName
Mandatory
String [40]
Standing order name.
startDate
Mandatory
Date
Date of the first payment.
startDate and frequency are used for calculating the next processing day.
Example: 08.11.2019
Annualy (YEAR): every 8th day in November
semi-annually (SEMI): every 8th day in November, May
quarterly (QUTR): every 8th day in November, February, May, August
monthly (MNTH): every 8th day in month
weekly (WEEK): every Friday
daily (DAIL): every day
endDate
Optional
Date
Expiry date of the standing order.
If it is not present, validity of standing order is not limited.
frequency
Mandatory
Enum
Frequency of the payment. Frequency and startDate are used for calculating the next processing day. For details, see startDay field.
Value: (DAIL, WEEK, MNTH, QUTR, SEMI, YEAR)


Response:

Header

Attributes structure
Optionality
Type
Description
Content-Type
Mandatory
String
application/json
Response-ID
Mandatory
String
An unique identifier of a particular request message. Although it may be arbitrary string, it is strongly recommended to use a Universally Unique Ifentifier (UUID) version 4 form (RFC4122).
Correlation-ID
Optional
String
A unique correlation identifier correlates the request and the response messages as a pair especially useful for audit logs. Although it may be arbitrary string, it is strongly recommended to use a Universally Unique Identifier (UUID) version 4 form (RFC4122).
Process-ID
Optional
String
Identifier of a business or technical process to what the set of requests and response pairs are organized (e.g. paging of transaction history should have same ProcessID). Although it may be arbitrary string, it is strongly recommended to use a Universally Unique Identifier (UUID) version 4 form (RFC4122).

Body

Attributes structure
Optionality
Type
Description
orderId
Mandatory
String
OrderId is Unique reference, as assigned by the account
servicing institution, to unambiguously identify the instruction. This ID is needed to be present in further requests
status
Mandatory
Enum
Transaction status indicator is enumeration:
- ACTC (AcceptedTechnicalValidation)
- ACWC (AcceptedWithChange)
- RJCT (Rejected)
reasonCode
Optional
Enum
ISO 20022 Reason Code*
statusDateTime
Mandatory
DateTime
The date and time in RFC3339 format at which a particular action has been requested or executed.
request
Optional
String
Signed JWT - security mitigation for unauthorized payment request changes
Not used in CSOB
*Link to Reason Code enumeration https://www.iso20022.org/sites/default/files/2021-03/ExternalCodeSets_4Q2020_February2021_v1.xlsx (sheets: 16-StatusReason, 60-ReceivedReason, 61-AcceptedReason, 62-PendingProcessingReason, 63-RejectedReason)


Example:

Request

POST https://api.csob.sk/pisp/api/v1/payments/standingOrder/sba HTTP/1.1
Accept-Encoding: gzip,deflate
Authorization: nfLnmy5hGQrNKbPnfAasw2FDVw4fw6kWjVapMVa9zJw8emNvTU
Request-ID: 9311964435
Correlation-ID: 7955014014
Process-ID: 9870741923
PSU-IP-Address: 192.168.88.1
PSU-Device-OS: windows
PSU-User-Agent: chrome
PSU-Geo-Location: 2.050279, 45.338591
PSU-Last-Logged-Time: 2021-03-03T17:33:50+01:00
Content-Type: application/json;charset=UTF-8
Content-Length: 683
Host: api.csob.sk
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5) 
{
  "instructionIdentification": "51624456095292114818544183286885146",
  "creationDateTime": "2021-01-14T13:54:32Z",
  "debtor": {
    "iban": "SK4075000000007777777777"
  },
  "creditor": {
    "name": "JRD2 s.r.o ",
    "addressLine1": "Pod kopcom 5",
    "addressLine2": "Sobrance",
    "iban": "SK8175000000002222222222"
  },
  "instructedAmount": {
    "value": 0.17,
    "currency": "EUR"
  },
  "endToEndIdentification": "/VS123456/SS654321/KS0308",
  "remittanceInformation": "Sprava pre prijemcu",
  "standingOrderName": "JRD 2 trvaly prikaz",
  "startDate": "2021-03-04",
  "endDate": "2021-05-10",
  "frequency": "DAIL"
}

Response

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Content-Type: application/json
Content-Encoding: gzip
Expires: -1
Vary: Accept-Encoding
Server-Process-ID: 67rBbafXzazKxC9aC9QEhfMTd7e73n3H
Process-ID: 9870741923
Correlation-ID: 7955014014
Response-ID: 9311964435
Strict-Transport-Security: max-age=31536000; includeSubDomains
Date: Tue, 19 Mar 2019 07:10:48 GMT 
{
    "orderId": "SO4gGLA3RxzfYtHHo4c",
    "status": "ACTC",
    "statusDateTime": "2021-03-03T17:33:52+01:00"
}


Step 3: Redirect to CSOB for Strong Customer Authentication (SCA) and standing order authorization.
In redirect link, there must be Order ID obtained in Step 2. SCA and standing order authorization is realized by client in bank environment using credentials issued by the bank (see section API Authorization/SCA). After this procedure, client is redirected back to third party application. In redirect link, there is an authorization code, which must be used in next step.


Step 4: Exchange authorization code for access token
Initiate POST request for Authorization code with a code obtained in Step 3. For details see Authorization API/Authorization code section. In response, there is an access token, which is binded to specific request and must be used in next step to submit the standing order.


Step 5: Submit authorized standing order.
Initiate POST request for Standard payment submission with valid access token obtained in Step 4. For Details see Payment initiation API (PISP) / Standard payment submission section.