Standard payment initiation - JSON API call flow (PISP)
This API allows to initiate single payment order via third party’s application. Following types of payment orders are available:
- single SEPA Credit Transfer
To initiate a payment, it is necessary to call APIs in correct order. The process from Initiate payment to payment authorization cannot be longer than 20 min.
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 standard payment - JSON
Initiate POST request for Standard payment initiation with valid access token:
Standard payment initiation - JSON
Version1
|
URL LIVE
URL SANDBOX
|
POST https://api.csob.sk/pisp/api/v1/payments/standard/sba
POST https://api.csob.sk/pisp-test/api/v1/payments/standard/sba
|
This service allows to initiate SEPA payments in JSON format according Slovak banking association standard. 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 |
name |
Mandatory |
String [70] |
Debtor name (first name and surname in case of individual persons or company name)For payment without debtor account, the value NOTPROVIDED can be used. |
debtor |
iban |
Mandatory |
String [34] |
Debtor account International Bank Account Number (IBAN)For payment without debtor account, the value SK387500DBACCNOTPROVIDED must be present. Account selected by client will be available via Batch payment order status service |
creditor |
name |
Mandatory |
String [70] |
Creditor name (first name and surname in case of individual persons or company name) |
creditor |
iban |
Mandatory |
String [34] |
Creditor account International Bank Account Number (IBAN) |
instructedAmount |
value |
Mandatory |
Number Float [12.2] |
Transaction amount value in account currency. 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. |
requestedExecutionDate |
Mandatory |
Date |
Expected execution date |
|
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. |
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 |
Example:
Request
POST https://api.csob.sk/pisp/api/v1/payments/standard/sba HTTP/1.1
Accept-Encoding: gzip,deflate
Authorization: 92038db562dd344304acf960240a3513f347acc7731a14d8250b89d09e3c586a
Request-ID: 5263214633
Correlation-ID: 6600511761
Process-ID: 7164376964
PSU-IP-Address: 192.168.88.1
PSU-Device-OS: Windows
PSU-User-Agent: SoapUI
PSU-Geo-Location: 2.050279, 45.338591
PSU-Last-Logged-Time: 2019-03-19T08:10:41+01:00
Content-Type: application/json;charset=UTF-8
Content-Length: 722
Host: api.csob.sk
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
{
"instructionIdentification": "9b76608457de48b2be531bd2804ae0b7",
"creationDateTime": "2099-09-30T13:54:32Z",
"debtor": {
"name": "PSD2 s.r.o",
"iban": "SK4075000000007777777777"
},
"creditor": {
"name": "JRD2 s.r.o ",
"iban": "SK8175000000002222222222"
},
"instructedAmount": {
"value": 8.09,
"currency": "EUR"
},
"endToEndIdentification": "/VS1/SS2/KS3",
"remittanceInformation": "PSD2 platba json",
"requestedExecutionDate": "2019-03-30"
}
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: cyvnChefw64zB86wCYqGy2UG8KpAgifz
Process-ID: 7164376964
Correlation-ID: 6600511761
Response-ID: 5263214633
Strict-Transport-Security: max-age=31536000; includeSubDomains
Date: Tue, 19 Mar 2019 07:10:48 GMT
{
"orderId": "6UYrbw35CddjepCndmGE51",
"status": "ACWC",
"statusDateTime": "2019-03-19T08:10:48+01:00"
}
Step 3: Redirect to CSOB for Strong Customer Authentication (SCA) and payment order authorization.
In redirect link, there must be Order ID obtained in Step 2. SCA and payment 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 payment and must be used in next step to submit the payment.
Step 5: Submit authorized payment.
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.