Payment Process (PISP)

To make a payment, it is necessary to call the APIs in the following order.

For each payment, you need to have valid access_token. Therefore, POST Token call is made firstly on the Identity server for new access_token generation. After that is possible to initiate the payment.

The process from Initiate payment to Submission cannot be longer than 20 min.

PISP process Flow


Process for establish payment:

  • Get access token
  • Initialize payment iso/simple
  • Redirect to SCA
  • SCA
  • Redirect to TPP redirect URL
  • Get token by secret
  • Submission


GET Access token

Within this process can be used multiscope (PISP scope) or token by secret.


Initialize Payment - ISO

Method of service: HTTP POST

POST/PAYMENTS/STANDARD/ISO: This is the initialization method; the subject calls this endpoint to initiate the payment. The service allows you to initiate SEPA and Foreign payments in XML format (Pain.001.001.03 CGI format).

The generated access_token for the PISP (Simple) Standard payment initialization is valid for 20 minutes. Token could be obtained by TokenBySecret or by refresh_token obtained from SCA (not for purpose of submitting payment) or it could be used token which was used to submitting payment. Implemented token process is described in chapter Identity Server.

PISP: payment initialization and receiving orderID

Header structure

Request

Attributes structure
Optionality
Type
Description
Content-Type
Mandatory
String
Application/json or 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-LastLogged-Time
Optional
DateTime
Last date and time when user was logged to TPP app (RFC3339 format)


Response

Attributes structure
Optionality
Type
Description
Content-Type
Mandatory
String
Application/json or 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).


Request Body

XML request body according to ISO20022 for example:

<Document>

<CstmrCdtTrfInitn>

<GrpHdr>

<MsgId>1</MsgId>

<CreDtTm>2018-05-28T10:35:23.2939388+00:00</CreDtTm>

<NbOfTxs>1</NbOfTxs>

<InitgPty></InitgPty>

</GrpHdr>

<PmtInf>

<PmtInfId>1</PmtInfId>

<PmtMtd>TRF</PmtMtd>

<ReqdExctnDt>2018-05-28</ReqdExctnDt>

<Dbtr>

<Nm>platce1</Nm>

<PstlAdr>

<Ctry>SK</Ctry>

<AdrLine>Adresa1</AdrLine>

<AdrLine>Adresa2</AdrLine>

</PstlAdr>

</Dbtr>

<DbtrAcct>

<Id>

<IBAN>SK9575000000004001076646</IBAN>

</Id>

</DbtrAcct>

<DbtrAgt>

<FinInstnId></FinInstnId>

</DbtrAgt>

<CdtTrfTxInf>

<PmtId>

<EndToEndId>/VS8888888888/SS7777777777/KS4510</EndToEndId>

</PmtId>

<Amt>

<InstdAmt Ccy="EUR">1</InstdAmt>

</Amt>

<Cdtr>

<Nm>platce1</Nm>

<PstlAdr>

<Ctry>SK</Ctry>

<AdrLine>Adresa1</AdrLine>

<AdrLine>Adresa2</AdrLine>

</PstlAdr>

</Cdtr>

<CdtrAcct>

<Id>

<IBAN>SK9575000000004001076646</IBAN>

</Id>

</CdtrAcct>

<RmtInf>

<Ustrd>remitanceInfo</Ustrd>

</RmtInf>

</CdtTrfTxInf>

</PmtInf>

</CstmrCdtTrfInitn>

</Document>


XML message returned in response pain 002.001.03 following important elements:

Attributes
XML structure mapping
Optionality
Type
Description
orderId
TxInfAndSts/ AcctSvcrRef
Mandatory
String (35)
OrderId is Unique reference, as assigned by the account servicing institution, to unambiguously identify the instruction.
status
TxInfAndSts/ TxSts
Mandatory
Enum
Transaction status indicator is enumeration: - ACTC (AcceptedTechnicalValidation) - ACWC (AcceptedWithChange) - RJCT (Rejected)
reasonCode
TxInfAndSts/ StsRsnInf/Rs n
Optional
Enum
ISO 20022 Status Reason Code
statusDateTime
GrpHdr/CreD tTm
Mandatory
Enum
Transaction entry date. The date of receiving the transaction in a bank.


Redirect to SCA

Redirected to SCA with parameters in url.

URL address is composed from:

  • URI: apiauthorization.csob.sk
  • URL parameters:

Attributes structure
Optionality
Type
Description
client_id
Mandatory
String
Tpp Id obtained from enrollment
response_type
Mandatory
String
Hybrid flow, value is „code id_token“
redirect_uri
Mandatory
String
Redirect url to be redirected after SCA, redirect url muse be in list of url adddresses from enrollment
scope
Mandatory
String
requested scope complemented with scope openid and with scope offline_access (not in case of SCA for submission of payment)
State
Mandatory
String
Nonce
Mandatory
String
Request
Mandatory
String
OrderId from Payment initialization


SCA

This process is realized between Client and Identity Server.

SCA: client authentication and payment authorization on bank site.


Redirect to TPP

Response back to TPP include only URL address with code generated after successful SCA process.


Token by code

Token by CODE Is used to obtain AT for submission from returned CODE.

Identity server: receiving token

Request text:

  • Copy text from example
  • Client_id and client_secret (assigned to specific TPP)
  • In Code Use value of AuthCode receiving in previous step

Method returns access_token in the response


POST PaymentSubmission

Method of service: HTTP POST

The payment is initiated after successful finish payment initialization flow.

The generated access_token for the PISP Standard payment submission is valid for 20 minutes. Token could be from SCA for Payment confirmation/submission.

Authorization and Request-ID are included in Header:

  • Authorization: access_token from previous step
  • Request-ID: unique value (, implementation on TPP side)
  • Payment is submitted

Response structure

Attributes structure
Optionality
Type
Description
orderId
Mandatory
String
OrderId is Unique reference, as assigned by the account servicing institution, to unambiguously identify the instruction.
status
Mandatory
Enum
reasonCode
Optional
Enum
ISO 20022 Status Reason Code
statusDateTime
Mandatory
DateTime
The date and time in RFC3339 format at which a particular action has been requested or executed.

Payment is initiate after successful POST PaymentSubmission.


Init payment - JSON

The operation allows initialize payment in JSON format. The PISP sends JSON structure message based on ISO20022 pain.001.

Request structure

Level 1
Level 2
Optionality
Type
Description
instruction Identification
Mandatory
String [200]
Technical identification of the payment generated by a PISP (or PSU).
creationDate Time
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)
debtor
iban
Mandatory
String [34]
Debtor account International Bank Account Number (IBAN)
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)
instructed Amount
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
instructed Amount
currency
Mandatory
String[3]
Transaction amount currency. Formated in Alphabetic codes from ISO 4712.
requested ExecutionDate
Mandatory
Date
Expected execution date
endToEnd Identification
Optional
String (35)
Unique identification defined by a requestor (PSU).
remittance Information
Optional
String (140)
The text aimed as the information for a receiver of the transaction.


Response structure.

Level 1
Optionality
Type
Description
orderId
Mandatory
String
OrderId is Unique reference, as assigned by the account servicing institution, to unambiguously identify the instruction.
status
Mandatory
Enum
Transaction status indicator is enumeration: - ACTC (AcceptedTechnicalValidation) - ACWC (AcceptedWithChange) - RJCT (Rejected) - PDNG (Pending) - ACSP (AcceptedSettlementInProcess) - ACSC (AcceptedSettlementCompleted)
reasonCode
Optional
Enum
ISO 20022 Status 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


POST BalanceCheck

POST BalanceCheck is the same from the technical point of view as service used in PIISP described in chapter POST BalanceCheck. Service is possible call only with multiscope token with PISP scope.


GET Payment Status

Method of service: HTTP GET

Actual status of payment initiation and processing is transmitted between CSOB bank and third-party provider via technical data exchange. Third party provider is obliged to present this status to client in its application. Third party provider can ask for actual payment order status via API within 7 days after due date.

For Payment Status must be used any AT valid for PISP.

Request Parameters:

  • orderId: value in response of payment initialization (response POST Payment)
  • authorization: use access_token
  • requestID: unique value
  • Send

Response return the payment status.