Standard payment initiation - XML 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
  • single Foreign Payment

To initiate a payment, it is necessary to call APIs in correct order. The process from Initiate payment to Submission 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 - XML
Initiate POST request for Standard payment initiation with valid access token:

Standard payment initiation - XML
Version1
URL LIVE
URL SANDBOX
POST https://api.csob.sk/pisp/api/v1/payments/standard/iso
POST https://api.csob.sk/pisp-test/api/v1/payments/standard/iso

This service allows to initiate SEPA and Foreign payments in XML format (pain.001.001.03 CGI format by Slovak Banking Association). 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/xml
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

XML request according to ISO20022 pain.001.001.03 CGI by SBA:

Definition: ISO20022.credit.transfer.common.global.implementation.v1.1.CSOB.xlsx
Schema: pain.001.001.03.xsd


Response:

Header

Attributes structure
Optionality
Type
Description
Content-Type
Mandatory
String
application/xml
Response-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).

Body

XML response according to ISO20022 pain.001.001.03:

Definition: pain.002.001.03.CSOBv1.0.xlsx
Schema: pain.002.001.03.xsd


Example:

Request

POST https://api.csob.sk/pisp/api/v1/payments/standard/iso HTTP/1.1
Accept-Encoding: gzip,deflate
Authorization: e16a4178bc38d882d1eecc4434a4bea6b3a9862ff8ce213ac2e43a63410a3089
Request-ID: 8839449391
Correlation-ID: 0783255904
Process-ID: 9166592252
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: 2019-03-15T10:04:29+01:00
Content-Type: application/xml
Content-Length: 2528
Host: api.csob.sk
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5) 
<?xml version="1.0" encoding="utf-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03 pain.001.001.03.xsd">
    <CstmrCdtTrfInitn>
        <GrpHdr>
            <MsgId>MCCT1803221557465327386x</MsgId>
            <CreDtTm>2018-03-22T12:34:36</CreDtTm>
            <NbOfTxs>1</NbOfTxs>
            <CtrlSum>9.55</CtrlSum>
            <InitgPty>
                <Nm>TPP a.s.</Nm>
            </InitgPty>
        </GrpHdr>
        <PmtInf>
            <PmtInfId>18032200002</PmtInfId>
            <PmtMtd>TRF</PmtMtd>
            <BtchBookg>true</BtchBookg>
            <NbOfTxs>1</NbOfTxs>
            <CtrlSum>9.55</CtrlSum>
            <PmtTpInf>
                <SvcLvl>
                    <Cd>SEPA</Cd>
                </SvcLvl>
            </PmtTpInf>
            <ReqdExctnDt>2019-03-22</ReqdExctnDt>
            <Dbtr>
                <Nm>TPP a.s.</Nm>
            </Dbtr>
            <DbtrAcct>
                <Id>
                    <IBAN>SK4075000000007777777777</IBAN>
                </Id>
            </DbtrAcct>
            <DbtrAgt>
                <FinInstnId>
                    <BIC>CEKOSKBXXXX</BIC>
                </FinInstnId>
            </DbtrAgt>
            <ChrgBr>SLEV</ChrgBr>
            <CdtTrfTxInf>
                <PmtId>
                    <EndToEndId>/VS1234/SS567/KS8</EndToEndId>
                </PmtId>
                <Amt>
                    <InstdAmt Ccy="EUR">9.55</InstdAmt>
                </Amt>
                <CdtrAgt>
                    <FinInstnId>
                        <BIC>CEKOSKBX</BIC>
                        <PstlAdr>
                            <Ctry>SK</Ctry>
                        </PstlAdr>
                    </FinInstnId>
                </CdtrAgt>
                <Cdtr>
                    <Nm>PSD2 prijemca s.r.o.</Nm>
                    <PstlAdr>
                        <Ctry>SK</Ctry>
                        <AdrLine>Ulicova 5</AdrLine>
                        <AdrLine>Big City</AdrLine>
                    </PstlAdr>
                </Cdtr>
                <CdtrAcct>
                    <Id>
                        <IBAN>SK8175000000002222222222</IBAN>
                    </Id>
                </CdtrAcct>
                <RmtInf>
                    <Ustrd>Faktura c. X123M123L</Ustrd>
                </RmtInf>
            </CdtTrfTxInf>
        </PmtInf>
    </CstmrCdtTrfInitn>
</Document>

Response

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Content-Type: application/xml
Content-Encoding: gzip
Expires: -1
Vary: Accept-Encoding
Server-Process-ID: aRtyYEkSpszfAupafn5EV4Psi8xRjMK2
Process-ID: 9166592252
Correlation-ID: 0783255904
Response-ID: 8839449391
Strict-Transport-Security: max-age=31536000; includeSubDomains
Date: Fri, 15 Mar 2019 09:04:36 GMT 
<Document xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:pain.002.001.03 pain.002.001.03.xsd" xmlns="urn:iso:std:iso:20022:tech:xsd:pain.002.001.03" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <CstmrPmtStsRpt>
        <GrpHdr>
            <MsgId>SPIz03B8qCpS363a3cPEzzsI52</MsgId>
            <CreDtTm>2019-03-15T10:04:34.925+01:00</CreDtTm>
        </GrpHdr>
        <OrgnlGrpInfAndSts>
            <OrgnlMsgId>MCCT1803221557465327386x</OrgnlMsgId>
            <OrgnlMsgNmId>pain.001.001.03</OrgnlMsgNmId>
        </OrgnlGrpInfAndSts>
        <OrgnlPmtInfAndSts>
            <OrgnlPmtInfId>z03B8qCpS363a3cPEzzsI52</OrgnlPmtInfId>
            <TxInfAndSts>
                <TxSts>ACTC</TxSts>
                <AcctSvcrRef>z03B8qCpS363a3cPEzzsI52</AcctSvcrRef>
            </TxInfAndSts>
        </OrgnlPmtInfAndSts>
    </CstmrPmtStsRpt>
</Document>


Step 3: Redirect to CSOB for Strong Customer Authentication (SCA) and payment order authorization.
In redirection 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 API Authorization section). 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. 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.