Payment services
The main purpose of the Payments API is to initiate and authorize a payment on a bank client’s behalf. It also includes additional services such as getting information about the payment.
To call these services, you need to possess the PSD2 PISP scope.
Initiate payment
POST /api/csob/psd2/v1/my/payments
Initiate a new payment transaction. In order to complete the transaction, the Start transaction authorization service needs to be called.
Request security requirements
| Feature | Required |
|---|---|
| Certificate | ✔ |
| API key header | ✔ |
| Access token header | ✔ |
Supported features
| Feature | Supported |
|---|---|
| Paging | ✘ |
| Sorting | ✘ |
| Filtering | ✘ |
Operation-specific errors
| HTTP status code | Error | Description |
|---|---|---|
| 400 | FIELD_MISSING | Missing account number |
| 400 | FIELD_MISSING | Payment type not specified |
| 400 | FIELD_MISSING | Amount not specified |
| 400 | FIELD_MISSING | Missing currency |
| 400 | FIELD_MISSING | Missing BIC |
| 400 | FIELD_MISSING | Missing BIC or bank address |
| 400 | FIELD_MISSING | Requested execution date not specified |
| 400 | FIELD_MISSING | RemittanceInformation not specified |
| 400 | FIELD_MISSING | Missing purpose |
| 400 | FIELD_INVALID | Invalid characters in the KS field |
| 400 | FIELD_INVALID | Invalid characters in the VS field |
| 400 | FIELD_INVALID | Invalid characters in the SS field |
| 400 | FIELD_INVALID | Incorrect requested execution date |
| 400 | FIELD_INVALID | Currency not domestic |
| 400 | FIELD_INVALID | Unknown payment type |
| 400 | FIELD_INVALID | Unsupported payment type |
| 400 | FIELD_INVALID | Invalid bank country |
| 400 | FIELD_INVALID | Currency not in EUR |
| 400 | FIELD_INVALID | Invalid characters in EndToEndReference |
| 400 | FIELD_INVALID | Invalid characters in RemittanceInformation |
| 400 | FIELD_INVALID | Invalid characters in UltimateDebtorName |
| 400 | FIELD_INVALID | Invalid characters in UltimateDebtorId |
| 400 | FIELD_INVALID | Invalid characters in UltimateCreditorName |
| 400 | FIELD_INVALID | Invalid characters in UltimateCreditorId |
| 400 | FIELD_INVALID | Incorrect IBAN format |
| 400 | FIELD_INVALID | IBAN and BIC do not match |
| 400 | FIELD_INVALID | IBAN and bank country do not match |
| 400 | FIELD_INVALID | The BIC country and bank country do not match |
| 400 | FIELD_INVALID | Invalid characters in address |
| 400 | FIELD_INVALID | Invalid country code |
| 400 | FIELD_INVALID | Invalid characters in bank reference |
| 400 | FIELD_INVALID | Invalid characters in reference |
| 400 | FIELD_INVALID | Invalid characters in bank address |
| 400 | FIELD_INVALID | Invalid characters in purpose |
| 400 | AUTH_INVALID_METHOD | The authorization method is invalid for the given account |
| 400 | AC01 | Invalid account number |
| 400 | AC04 | Account closed |
| 400 | AC09 | Invalid account currency |
| 400 | AM06 | Too low amount |
| 400 | AM11 | Invalid transaction currency |
| 400 | RC01 | Incorrect bank identifier |
| 403 | AG01 | Consent to check account balance not granted |
| 403 | FORBIDDEN | No disposal rights |
Please refer to the Overview section for the error response data structure and a list of errors common to all operations.
Request schema
{
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object",
"properties": {
"paymentIdentification": {
"type": "object",
"properties": {
"instructionIdentification": {
"type": "string",
"maxLength": 35,
"description": "Unique identification of the payment instruction."
},
"endToEndIdentification": {
"type": "string",
"maxLength": 35,
"description": "Payment identification agreed between the debtor and creditor. If not provided, the payment provider will fill in *NOTPROVIDED*."
}
},
"required": [
"instructionIdentification"
]
},
"paymentTypeInformation": {
"type": "object",
"properties": {
"instructionPriority": {
"type": "string",
"default": "NORM",
"pattern": "(NORM|HIGH|INST)",
"description": "Priority of the payment instruction. Can be NORM, HIGH or INST."
}
}
},
"amount": {
"type": "object",
"properties": {
"instructedAmount": {
"type": "object",
"properties": {
"value": {
"type": "number",
"minimum": 0,
"maximum": 9999999999999.99,
"multipleOf": 0.01,
"description": "The amount to be transferred before deducting fees."
},
"currency": {
"type": "string",
"maxLength": 3,
"pattern": "^[A-Z]{3}$"
}
},
"required": [
"value",
"currency"
]
},
"equivalentAmount": {
"type": "object",
"description": "Amount expressed in the creditors currency. Used for Cover of FX transactions.",
"properties": {
"value": {
"type": "number",
"minimum": 0,
"maximum": 9999999999999.99,
"multipleOf": 0.01,
"description": "The amount to be transferred before deducting fees."
},
"currency": {
"type": "string",
"maxLength": 3,
"pattern": "^[A-Z]{3}$"
}
},
"required": [
"value",
"currency"
]
}
}
},
"requestedExecutionDate": {
"type": "string",
"description": "Requested date to execute the transaction in YYYY-MM-DD format."
},
"exchangeRateInformation": {
"type": "object",
"properties": {
"exchangeRate": {
"type": "number",
"description": "Rate expressed as a decimal, eg, 0.7 is 7/10 and 70%."
},
"rateType": {
"type": "string",
"pattern": "(AGREED|SALE|SPOT)",
"description": "The used rate type which can be AGREED, SALE or SPOT."
},
"contractIdentification": {
"type": "string",
"maxLength": 35,
"description": "Identification of the contract for the agreed exchange rate."
}
}
},
"chargeBearer": {
"type": "string",
"pattern": "(DEBT|CRED|SHAR|SLEV)",
"description": "Charge bearer type code."
},
"chargesAccount": {
"type": "object",
"description": "Used in case the debtors account should not be charged.",
"properties": {
"identification": {
"type": "object",
"properties": {
"iban": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$",
"description": "Identification of the account to charge fees from."
}
},
"required": [
"iban"
]
},
"currency": {
"type": "string",
"maxLength": 3,
"pattern": "^[A-Z]{3}$",
"description": "Currency of the account."
}
},
"required": [
"identification"
]
},
"ultimateDebtor": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 140,
"description": "Name of the ultimate debtor."
},
"postalAddress": {
"type": "object",
"properties": {
"streetName": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string",
"maxLength": 16
},
"postCode": {
"type": "string",
"maxLength": 16
},
"townName": {
"type": "string",
"maxLength": 35
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter country codes as defined in ISO 3166."
},
"addressLine": {
"type": "array",
"description": "Address value in non structured form.",
"items": {
"type": "string",
"maxLength": 70
}
}
}
},
"identification": {
"type": "object",
"description": "Identification of the ultimate debtor",
"properties": {
"organisationIdentification": {
"type": "object",
"description": "Identification of an organization",
"properties": {
"bicOrBei": {
"type": "string",
"maxLength": 35,
"pattern": "^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$",
"description": "Bank identification code."
},
"other": {
"type": "object",
"description": "Other identification of the organization.",
"properties": {
"identification": {
"type": "string",
"maxLength": 35
},
"schemeName": {
"type": "object",
"properties": {
"proprietary": {
"type": "string",
"maxLength": 35
}
}
},
"issuer": {
"type": "string",
"maxLength": 35,
"description": "Issuer of the identification document."
}
}
}
}
},
"privateIdentification": {
"type": "object",
"description": "Identification of an individual person.",
"properties": {
"other": {
"type": "object",
"properties": {
"identification": {
"type": "string",
"maxLength": 35,
"description": "Unique identification of the person."
},
"schemeName": {
"type": "object",
"properties": {
"proprietary": {
"type": "string",
"maxLength": 35,
"description": "Type of the identification document."
},
"issuer": {
"type": "string",
"maxLength": 35,
"description": "Issuer of the identification document."
}
}
}
}
}
}
}
}
}
}
},
"debtor": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 140,
"description": "Name of the debtor."
},
"postalAddress": {
"type": "object",
"properties": {
"streetName": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string",
"maxLength": 16
},
"postCode": {
"type": "string",
"maxLength": 16
},
"townName": {
"type": "string",
"maxLength": 35
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter country codes as defined in ISO 3166."
},
"addressLine": {
"type": "array",
"description": "Address value in non structured form.",
"items": {
"type": "string",
"maxLength": 70
}
}
}
}
}
},
"debtorAccount": {
"type": "object",
"properties": {
"identification": {
"type": "object",
"description": "Identification of the debtor's account.",
"properties": {
"iban": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$",
"description": "Account number in the IBAN format."
},
"other": {
"type": "object",
"properties": {
"identification": {
"type": "string",
"maxLength": 34,
"description": "Local BBAN format of the account number."
}
}
}
},
"required": [
"iban"
]
},
"currency": {
"type": "string",
"maxLength": 3,
"pattern": "^[A-Z]{3}$",
"description": "Currency of the account."
}
},
"required": [
"identification"
]
},
"intermediaryAgent1": {
"type": "object",
"description": "Intermediate bank involved in the transaction.",
"properties": {
"financialInstitutionIdentification": {
"type": "object",
"properties": {
"bic": {
"type": "string",
"maxLength": 35,
"pattern": "^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$",
"description": "Bank identification code."
},
"clearingSystemMemberIdentification": {
"type": "object",
"properties": {
"clearingSystemIdentification": {
"type": "object",
"description": "Identification of the intermediate clearing system.",
"properties": {
"code": {
"type": "string",
"maxLength": 5,
"description": "Code identifying the local clearing system."
},
"proprietary": {
"type": "string",
"maxLength": 35,
"description": "Identification of the local clearing system."
}
}
},
"memberIdentification": {
"type": "string",
"maxLength": 35,
"description": "Identification code of the clearing member."
}
}
},
"name": {
"type": "string",
"maxLength": 70,
"description": "A known name used to identify the intermediate party."
},
"postalAddress": {
"type": "object",
"properties": {
"streetName": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string",
"maxLength": 16
},
"postCode": {
"type": "string",
"maxLength": 16
},
"townName": {
"type": "string",
"maxLength": 35
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter country codes as defined in ISO 3166."
},
"addressLine": {
"type": "array",
"description": "Address value in non structured form.",
"items": {
"type": "string",
"maxLength": 70
}
}
}
},
"other": {
"type": "object",
"description": "Other form of unique identification of the intermediate bank.",
"properties": {
"identification": {
"type": "string",
"maxLength": 35
}
}
}
}
}
}
},
"creditorAgent": {
"type": "object",
"description": "Bank of the creditor.",
"properties": {
"financialInstitutionIdentification": {
"type": "object",
"properties": {
"bic": {
"type": "string",
"maxLength": 35,
"pattern": "^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$",
"description": "Bank identification code."
},
"clearingSystemMemberIdentification": {
"type": "object",
"properties": {
"clearingSystemIdentification": {
"type": "object",
"description": "Identification of the clearing system.",
"properties": {
"code": {
"type": "string",
"maxLength": 5,
"description": "Code identifying the local clearing system."
},
"proprietary": {
"type": "string",
"maxLength": 35,
"description": "Identification of the local clearing system."
}
}
},
"memberIdentification": {
"type": "string",
"maxLength": 35,
"description": "Identification code of the clearing member."
}
}
},
"name": {
"type": "string",
"maxLength": 70,
"description": "A known name used to identify the party."
},
"postalAddress": {
"type": "object",
"properties": {
"streetName": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string",
"maxLength": 16
},
"postCode": {
"type": "string",
"maxLength": 16
},
"townName": {
"type": "string",
"maxLength": 35
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter country codes as defined in ISO 3166."
},
"addressLine": {
"type": "array",
"description": "Address value in non structured form.",
"items": {
"type": "string",
"maxLength": 70
}
}
}
},
"other": {
"type": "object",
"description": "Other form of unique identification of the bank.",
"properties": {
"identification": {
"type": "string",
"maxLength": 35
}
}
}
}
}
}
},
"creditor": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 140,
"description": "Name of the creditor."
},
"postalAddress": {
"type": "object",
"properties": {
"streetName": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string",
"maxLength": 16
},
"postCode": {
"type": "string",
"maxLength": 16
},
"townName": {
"type": "string",
"maxLength": 35
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter country codes as defined in ISO 3166."
},
"addressLine": {
"type": "array",
"description": "Address value in non structured form.",
"items": {
"type": "string",
"maxLength": 70
}
}
}
}
}
},
"creditorAccount": {
"type": "object",
"properties": {
"identification": {
"type": "object",
"description": "Identification of the creditor's account.",
"properties": {
"iban": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$",
"description": "Account number in the IBAN format."
},
"other": {
"type": "object",
"properties": {
"identification": {
"type": "string",
"maxLength": 34,
"description": "Local BBAN format of the account number."
}
}
}
},
"required": [
"iban"
]
},
"currency": {
"type": "string",
"maxLength": 3,
"pattern": "^[A-Z]{3}$",
"description": "Currency of the account."
}
},
"required": [
"identification"
]
},
"ultimateCreditor": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 140,
"description": "Name of the ultimate creditor."
},
"postalAddress": {
"type": "object",
"properties": {
"streetName": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string",
"maxLength": 16
},
"postCode": {
"type": "string",
"maxLength": 16
},
"townName": {
"type": "string",
"maxLength": 35
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter country codes as defined in ISO 3166."
},
"addressLine": {
"type": "array",
"description": "Address value in non structured form.",
"items": {
"type": "string",
"maxLength": 70
}
}
}
},
"identification": {
"type": "object",
"description": "Identification of the ultimate creditor",
"properties": {
"organisationIdentification": {
"type": "object",
"description": "Identification of an organization",
"properties": {
"bicOrBei": {
"type": "string",
"maxLength": 35,
"pattern": "^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$",
"description": "Bank identification code."
},
"other": {
"type": "object",
"description": "Other identification of the organization.",
"properties": {
"identification": {
"type": "string",
"maxLength": 35
},
"schemeName": {
"type": "object",
"properties": {
"proprietary": {
"type": "string",
"maxLength": 35
}
}
},
"issuer": {
"type": "string",
"maxLength": 35,
"description": "Issuer of the identification document."
}
},
"required": [
"identification"
]
}
}
},
"privateIdentification": {
"type": "object",
"description": "Identification of an individual person.",
"properties": {
"other": {
"type": "object",
"properties": {
"identification": {
"type": "string",
"maxLength": 35,
"description": "Unique identification of the person."
},
"schemeName": {
"type": "object",
"properties": {
"proprietary": {
"type": "string",
"maxLength": 35,
"description": "Type of the identification document."
},
"issuer": {
"type": "string",
"maxLength": 35,
"description": "Issuer of the identification document."
}
}
}
},
"required": [
"identification"
]
}
}
}
}
}
}
},
"purpose": {
"type": "object",
"description": "Purpose of the transaction.",
"properties": {
"code": {
"type": "string",
"maxLength": 4,
"description": "Purpose code."
},
"proprietary": {
"type": "string",
"maxLength": 35,
"description": "Free-form text describing the purpose."
}
}
},
"instructionForNextAgent": {
"type": "string",
"maxLength": 140,
"description": "Instructions for the next processing bank."
},
"remittanceInformation": {
"type": "object",
"properties": {
"structured": {
"type": "object",
"properties": {
"creditorReferenceInformation": {
"type": "object",
"properties": {
"reference": {
"type": "array",
"description": "Reference for only domestic payments allowing to specify VS, KS and SS.",
"items": {
"type": "string",
"maxLength": 35
}
}
}
}
}
},
"unstructured": {
"type": "string",
"maxLength": 140,
"description": "Information for the creditor."
}
}
}
},
"required": [
"paymentIdentification",
"amount",
"debtorAccount",
"creditorAccount"
]
}
Specific implementation requirements
For some types of payments, API implementation requires different values than specified in the JSON schema specification. Details are described in the following table.
| JSON Path | Paymet type | Description |
|---|---|---|
| $.creditor.name | FOREIGN, SEPA | Minimum length is 3 chars. |
| $.remittanceInformation.unstructured | FOREIGN, SEPA | Minimum length is 3 chars. |
| $.creditor.postalAddress.addressLine[1] | FOREIGN | Minimum length is 3 chars. The condition applies to payments to the US (regardless of the payment currency), or for the payment in the USD currency (regardless of recipient country) |
Sample request
HTTP
POST /api/csob/psd2/v1/my/payments HTTP/1.1
Host: api.csob.cz
APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b
Content-Type: application/json
Authorization: Bearer 3/ilqobO3amOBPtHHLZsmTP7p3Z6Y0s6JvOdm1d1cwIhBdMEJZHr0wdG2f24CwbFAC
Cache-Control: no-cache
{
"paymentIdentification": {
"instructionIdentification": "NejakeID41785962314574"
},
"paymentTypeInformation": {
"instructionPriority": "NORM"
},
"amount": {
"instructedAmount": {
"value": 1245.44,
"currency": "CZK"
}
},
"requestedExecutionDate": "2017-01-31",
"debtorAccount": {
"identification": {
"iban": "CZ7508000000002108589434"
},
"currency": "CZK"
},
"creditorAccount": {
"identification": {
"iban": "CZ6330300000000000000123"
},
"currency": "CZK"
},
"remittanceInformation": {
"unstructured": "VS/7418529630/SS/1234567890"
}
}
cURL
curl -X POST \n https://api.csob.cz/api/csob/psd2/v1/my/payments \n -H 'APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b' \n -H 'Authorization: Bearer 3/ilqobO3amOBPtHHLZsmTP7p3Z6Y0s6JvOdm1d1cwIhBdMEJZHr0wdG2f24CwbFAC' \n -H 'Cache-Control: no-cache' \n -H 'Content-Type: application/json' \n -d '{
"paymentIdentification": {
"instructionIdentification": "NejakeID41785962314574"
},
"paymentTypeInformation": {
"instructionPriority": "NORM"
},
"amount": {
"instructedAmount": {
"value": 1245.44,
"currency": "CZK"
}
},
"requestedExecutionDate": "2017-01-31",
"debtorAccount": {
"identification": {
"iban": "CZ7508000000002108589434"
},
"currency": "CZK"
},
"creditorAccount": {
"identification": {
"iban": "CZ6330300000000000000123"
},
"currency": "CZK"
},
"remittanceInformation": {
"unstructured": "VS/7418529630/SS/1234567890"
}
}'
Response schema
{
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object",
"properties": {
"paymentIdentification": {
"type": "object",
"properties": {
"instructionIdentification": {
"type": "string",
"maxLength": 35,
"description": "Unique identification of the payment instruction."
},
"endToEndIdentification": {
"type": "string",
"maxLength": 35,
"description": "Payment identification agreed between the debtor and creditor. If not provided, the payment provider will fill in *NOTPROVIDED*."
},
"transactionIdentification": {
"type": "string",
"maxLength": 35,
"description": "Unique identification of the transaction. Used in further operations, such as signing of the payment transaction."
}
},
"required": [
"instructionIdentification",
"transactionIdentification"
]
},
"paymentTypeInformation": {
"type": "object",
"properties": {
"instructionPriority": {
"type": "string",
"default": "NORM",
"pattern": "(NORM|HIGH|INST)",
"description": "Priority of the payment instruction. Can be NORM, HIGH or INST."
},
"serviceLevel": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "(DOMESTIC|FOREIGN|SEPA)",
"description": "Type of the payment."
}
},
"required": [
"code"
]
}
},
"required": [
"serviceLevel"
]
},
"amount": {
"type": "object",
"properties": {
"instructedAmount": {
"type": "object",
"properties": {
"value": {
"type": "number",
"minimum": 0,
"maximum": 9999999999999.99,
"multipleOf": 0.01,
"description": "The amount to be transferred before deducting fees."
},
"currency": {
"type": "string",
"maxLength": 3,
"pattern": "^[A-Z]{3}$"
}
},
"required": [
"value",
"currency"
]
},
"equivalentAmount": {
"type": "object",
"description": "Amount expressed in the creditors currency. Used for Cover of FX transactions.",
"properties": {
"value": {
"type": "number",
"minimum": 0,
"maximum": 9999999999999.99,
"multipleOf": 0.01,
"description": "The amount to be transferred before deducting fees."
},
"currency": {
"type": "string",
"maxLength": 3,
"pattern": "^[A-Z]{3}$"
}
},
"required": [
"value",
"currency"
]
}
}
},
"requestedExecutionDate": {
"type": "string",
"description": "Requested date to execute the transaction in YYYY-MM-DD format."
},
"exchangeRateInformation": {
"type": "object",
"properties": {
"exchangeRate": {
"type": "number",
"description": "Rate expressed as a decimal, eg, 0.7 is 7/10 and 70%."
},
"rateType": {
"type": "string",
"pattern": "(AGREED|SALE|SPOT)",
"description": "The used rate type which can be AGREED, SALE or SPOT."
},
"contractIdentification": {
"type": "string",
"maxLength": 35,
"description": "Identification of the contract for the agreed exchange rate."
}
}
},
"chargeBearer": {
"type": "string",
"pattern": "(DEBT|CRED|SHAR|SLEV)",
"description": "Charge bearer type code."
},
"chargesAccount": {
"type": "object",
"description": "Used in case the debtors account should not be charged.",
"properties": {
"identification": {
"type": "object",
"properties": {
"iban": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$",
"description": "Identification of the account to charge fees from."
}
},
"required": [
"iban"
]
},
"currency": {
"type": "string",
"maxLength": 3,
"pattern": "^[A-Z]{3}$",
"description": "Currency of the account."
}
},
"required": [
"identification"
]
},
"ultimateDebtor": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 70,
"description": "Name of the ultimate debtor."
},
"postalAddress": {
"type": "object",
"properties": {
"streetName": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string",
"maxLength": 16
},
"postCode": {
"type": "string",
"maxLength": 16
},
"townName": {
"type": "string"
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter country codes as defined in ISO 3166."
},
"addressLine": {
"type": "array",
"description": "Address value in non structured form.",
"items": {
"type": "string",
"maxLength": 70
}
}
}
},
"identification": {
"type": "object",
"description": "Identification of the ultimate debtor",
"properties": {
"organisationIdentification": {
"type": "object",
"description": "Identification of an organization",
"properties": {
"bicOrBei": {
"type": "string",
"maxLength": 35,
"pattern": "^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$",
"description": "Bank identification code."
},
"other": {
"type": "object",
"description": "Other identification of the organization.",
"properties": {
"identification": {
"type": "string",
"maxLength": 35
},
"schemeName": {
"type": "object",
"properties": {
"proprietary": {
"type": "string",
"maxLength": 35
}
}
},
"issuer": {
"type": "string",
"maxLength": 35,
"description": "Issuer of the identification document."
}
}
}
}
},
"privateIdentification": {
"type": "object",
"description": "Identification of an individual person.",
"properties": {
"other": {
"type": "object",
"properties": {
"identification": {
"type": "string",
"maxLength": 35,
"description": "Unique identification of the person."
},
"schemeName": {
"type": "object",
"properties": {
"proprietary": {
"type": "string",
"maxLength": 35,
"description": "Type of the identification document."
}
}
},
"issuer": {
"type": "string",
"maxLength": 35,
"description": "Issuer of the identification document."
}
}
}
}
}
}
}
}
},
"debtor": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 70,
"description": "Name of the debtor."
},
"postalAddress": {
"type": "object",
"properties": {
"streetName": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string",
"maxLength": 16
},
"postCode": {
"type": "string",
"maxLength": 16
},
"townName": {
"type": "string"
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter country codes as defined in ISO 3166."
},
"addressLine": {
"type": "array",
"description": "Address value in non structured form.",
"items": {
"type": "string",
"maxLength": 70
}
}
}
}
}
},
"debtorAccount": {
"type": "object",
"properties": {
"identification": {
"type": "object",
"description": "Identification of the debtor's account.",
"properties": {
"iban": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$",
"description": "Account number in the IBAN format."
},
"other": {
"type": "object",
"properties": {
"identification": {
"type": "string",
"maxLength": 34,
"description": "Local BBAN format of the account number."
}
}
}
},
"required": [
"iban"
]
},
"currency": {
"type": "string",
"maxLength": 3,
"pattern": "^[A-Z]{3}$",
"description": "Currency of the account."
}
},
"required": [
"identification"
]
},
"intermediaryAgent1": {
"type": "object",
"description": "Intermediate bank involved in the transaction.",
"properties": {
"financialInstitutionIdentification": {
"type": "object",
"properties": {
"bic": {
"type": "string",
"maxLength": 35,
"pattern": "^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$",
"description": "Bank identification code."
},
"clearingSystemMemberIdentification": {
"type": "object",
"properties": {
"clearingSystemIdentification": {
"type": "object",
"description": "Identification of the intermediate clearing system.",
"properties": {
"code": {
"type": "string",
"maxLength": 5,
"description": "Code identifying the local clearing system."
},
"proprietary": {
"type": "string",
"maxLength": 35,
"description": "Identification of the local clearing system."
}
}
},
"memberIdentification": {
"type": "string",
"maxLength": 35,
"description": "Identification code of the clearing member."
}
}
},
"name": {
"type": "string",
"maxLength": 70,
"description": "A known name used to identify the intermediate party."
},
"postalAddress": {
"type": "object",
"properties": {
"streetName": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string",
"maxLength": 16
},
"postCode": {
"type": "string",
"maxLength": 16
},
"townName": {
"type": "string",
"maxLength": 35
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter country codes as defined in ISO 3166."
},
"addressLine": {
"type": "array",
"description": "Address value in non structured form.",
"items": {
"type": "string",
"maxLength": 70
}
}
}
},
"other": {
"type": "object",
"description": "Other form of unique identification of the intermediate bank.",
"properties": {
"identification": {
"type": "string",
"maxLength": 35
}
}
}
}
}
}
},
"creditorAgent": {
"type": "object",
"description": "Bank of the creditor.",
"properties": {
"financialInstitutionIdentification": {
"type": "object",
"properties": {
"bic": {
"type": "string",
"maxLength": 35,
"pattern": "^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$",
"description": "Bank identification code."
},
"clearingSystemMemberIdentification": {
"type": "object",
"properties": {
"clearingSystemIdentification": {
"type": "object",
"description": "Identification of the clearing system.",
"properties": {
"code": {
"type": "string",
"maxLength": 5,
"description": "Code identifying the local clearing system."
},
"proprietary": {
"type": "string",
"maxLength": 35,
"description": "Identification of the local clearing system."
}
}
},
"memberIdentification": {
"type": "string",
"maxLength": 35,
"description": "Identification code of the clearing member."
}
}
},
"name": {
"type": "string",
"maxLength": 70,
"description": "A known name used to identify the party."
},
"postalAddress": {
"type": "object",
"properties": {
"streetName": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string",
"maxLength": 16
},
"postCode": {
"type": "string",
"maxLength": 16
},
"townName": {
"type": "string",
"maxLength": 35
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter country codes as defined in ISO 3166."
},
"addressLine": {
"type": "array",
"description": "Address value in non structured form.",
"items": {
"type": "string",
"maxLength": 70
}
}
}
},
"other": {
"type": "object",
"description": "Other form of unique identification of the bank.",
"properties": {
"identification": {
"type": "string",
"maxLength": 35
}
}
}
}
}
}
},
"creditor": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 70,
"description": "Name of the creditor."
},
"postalAddress": {
"type": "object",
"properties": {
"streetName": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string",
"maxLength": 16
},
"postCode": {
"type": "string",
"maxLength": 16
},
"townName": {
"type": "string",
"maxLength": 35
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter country codes as defined in ISO 3166."
},
"addressLine": {
"type": "array",
"description": "Address value in non structured form.",
"items": {
"type": "string",
"maxLength": 70
}
}
}
}
}
},
"creditorAccount": {
"type": "object",
"properties": {
"identification": {
"type": "object",
"description": "Identification of the creditor's account.",
"properties": {
"iban": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$",
"description": "Account number in the IBAN format."
},
"other": {
"type": "object",
"properties": {
"identification": {
"type": "string",
"maxLength": 34,
"description": "Local BBAN format of the account number."
}
}
}
},
"required": [
"iban"
]
},
"currency": {
"type": "string",
"maxLength": 3,
"pattern": "^[A-Z]{3}$",
"description": "Currency of the account."
}
},
"required": [
"identification"
]
},
"ultimateCreditor": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 70,
"description": "Name of the ultimate creditor."
},
"postalAddress": {
"type": "object",
"properties": {
"streetName": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string",
"maxLength": 16
},
"postCode": {
"type": "string",
"maxLength": 16
},
"townName": {
"type": "string"
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter country codes as defined in ISO 3166."
},
"addressLine": {
"type": "array",
"description": "Address value in non structured form.",
"items": {
"type": "string",
"maxLength": 70
}
}
}
},
"identification": {
"type": "object",
"description": "Identification of the ultimate creditor",
"properties": {
"organisationIdentification": {
"type": "object",
"description": "Identification of an organization",
"properties": {
"bicOrBei": {
"type": "string",
"maxLength": 35,
"pattern": "^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$",
"description": "Bank identification code."
},
"other": {
"type": "object",
"description": "Other identification of the organization.",
"properties": {
"identification": {
"type": "string",
"maxLength": 35
},
"schemeName": {
"type": "object",
"properties": {
"proprietary": {
"type": "string",
"maxLength": 35
}
}
},
"issuer": {
"type": "string",
"maxLength": 35,
"description": "Issuer of the identification document."
}
},
"required": [
"identification"
]
}
}
},
"privateIdentification": {
"type": "object",
"description": "Identification of an individual person.",
"properties": {
"other": {
"type": "object",
"properties": {
"identification": {
"type": "string",
"maxLength": 35,
"description": "Unique identification of the person."
},
"schemeName": {
"type": "object",
"properties": {
"proprietary": {
"type": "string",
"maxLength": 35,
"description": "Type of the identification document."
},
"issuer": {
"type": "string",
"maxLength": 35,
"description": "Issuer of the identification document."
}
}
}
},
"required": [
"identification"
]
}
}
}
}
}
}
},
"purpose": {
"type": "object",
"description": "Purpose of the transaction.",
"properties": {
"code": {
"type": "string",
"maxLength": 4,
"description": "Purpose code."
},
"proprietary": {
"type": "string",
"maxLength": 35,
"description": "Free-form text describing the purpose."
}
}
},
"instructionForNextAgent": {
"type": "string",
"maxLength": 140,
"description": "Instructions for the next processing bank."
},
"remittanceInformation": {
"type": "object",
"properties": {
"structured": {
"type": "object",
"properties": {
"creditorReferenceInformation": {
"type": "object",
"properties": {
"reference": {
"type": "array",
"description": "Reference for only domestic payments allowing to specify VS, KS and SS.",
"items": {
"type": "string",
"maxLength": 35
}
}
}
}
}
},
"unstructured": {
"type": "string",
"description": "Information for the creditor."
}
}
},
"signInfo": {
"type": "object",
"properties": {
"state": {
"type": "string",
"description": "Transaction authorization state."
},
"signId": {
"type": "string",
"description": "Identification of the transaction authorization request."
},
"signInfo": {
"type": "string",
"description": "Transaction status identifier."
}
},
"required": [
"state",
"signId",
"signInfo"
]
}
},
"required": [
"paymentIdentification",
"amount",
"debtorAccount",
"creditorAccount",
"signInfo"
]
}
Transaction code description
Transaction types
| Transaction Type | Description |
|---|---|
| DOMESTIC | Domestic payment |
| FOREIGN | Foreign payment (EHP/NONEHP) |
| SEPA | SEPA payment |
Transaction Authorization State
| State Code | Description |
|---|---|
| OPEN | Transaction created. |
| FAILED | Transaction expired or failed due to unsuccesfull authentification attempts. |
| CANCELLED | Transaction cancelled |
| CONFIRMED | Transactions confirmed by the client. |
Transaction status identifier
| Sign Info Code | Description |
|---|---|
| ACTC | AcceptedTechnicalValidation - Authentication and syntactical and semantical validation are successful. |
| RJCT | Rejected - Payment initiation or individual transaction included in the payment initiation has been rejected. |
| ACWC | AcceptedWithChange - Instruction is accepted but a change will be made, such as date or remittance not change. |
Sample response
HTTP/1.1 200 OK
{
"paymentIdentification": {
"instructionIdentification": "NejakeID41785962314574",
"transactionIdentification": "048885570000001020045"
},
"paymentTypeInformation": {
"instructionPriority": "NORM",
"serviceLevel": {
"code": "DOMESTIC"
}
},
"amount": {
"instructedAmount": {
"value": 10050.15,
"currency": "CZK"
}
},
"requestedExecutionDate": "2017-02-20",
"debtorAccount": {
"identification": {
"iban": "CZ0708000000001019382023"
},
"currency": "CZK"
},
"creditorAccount": {
"identification": {
"iban": "CZ0708000000001019540081"
},
"currency": "CZK"
},
"remittanceInformation": {
"structured": {
"creditorReferenceInformation": {
"reference": [
"VS:501",
"KS:9",
"SS:1005"
]
}
}
},
"signInfo": {
"state": "OPEN",
"signId": "164298331754922"
}
}
Get payment details
GET /api/csob/psd2/v1/my/payments/{paymentId}
Get details of a created but not yet authorized payment transaction.
Request URI parameters
- paymentId: identification of the payment transaction returned by the Initiate payment service in the paymentIdentification/transactionIdentification attribute
Request security requirements
| Feature | Required |
|---|---|
| Certificate | ✔ |
| API key header | ✔ |
| Access token header | ✔ |
Supported features
| Feature | Supported |
|---|---|
| Paging | ✘ |
| Sorting | ✘ |
| Filtering | ✘ |
Operation-specific errors
| HTTP status code | Error | Description |
|---|
Please refer to the Overview section for the error response data structure and a list of errors common to all operations.
Sample request
HTTP
GET /api/csob/psd2/v1/my/payments/048885570000001020045 HTTP/1.1
Host: api.csob.cz
APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b
Content-Type: application/json
Authorization: Bearer 3/ilqobO3amOBPtHHLZsmTP7p3Z6Y0s6JvOdm1d1cwIhBdMEJZHr0wdG2f24CwbFAC
Cache-Control: no-cache
cURL
curl -X GET \n https://api.csob.cz/api/csob/psd2/v1/my/payments/048885570000001020045 \n -H 'APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b' \n -H 'Authorization: Bearer 3/ilqobO3amOBPtHHLZsmTP7p3Z6Y0s6JvOdm1d1cwIhBdMEJZHr0wdG2f24CwbFAC' \n -H 'Cache-Control: no-cache' \n -H 'Content-Type: application/json'
Response schema
{
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object",
"properties": {
"paymentIdentification": {
"type": "object",
"properties": {
"instructionIdentification": {
"type": "string",
"maxLength": 35,
"description": "Unique identification of the payment instruction."
},
"endToEndIdentification": {
"type": "string",
"maxLength": 35,
"description": "Payment identification agreed between the debtor and creditor. If not provided, the payment provider will fill in *NOTPROVIDED*."
},
"transactionIdentification": {
"type": "string",
"maxLength": 35,
"description": "Unique identification of the transaction. Used in further operations, such as signing of the payment transaction."
}
},
"required": [
"instructionIdentification",
"transactionIdentification"
]
},
"paymentTypeInformation": {
"type": "object",
"properties": {
"instructionPriority": {
"type": "string",
"default": "NORM",
"pattern": "(NORM|HIGH|INST)",
"description": "Priority of the payment instruction. Can be NORM, HIGH or INST."
},
"serviceLevel": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "(DOMESTIC|FOREIGN|SEPA)",
"description": "Type of the payment."
}
},
"required": [
"code"
]
}
},
"required": [
"serviceLevel"
]
},
"amount": {
"type": "object",
"properties": {
"instructedAmount": {
"type": "object",
"properties": {
"value": {
"type": "number",
"minimum": 0,
"maximum": 9999999999999.99,
"multipleOf": 0.01,
"description": "The amount to be transferred before deducting fees."
},
"currency": {
"type": "string",
"maxLength": 3,
"pattern": "^[A-Z]{3}$"
}
},
"required": [
"value",
"currency"
]
},
"equivalentAmount": {
"type": "object",
"description": "Amount expressed in the creditors currency. Used for Cover of FX transactions.",
"properties": {
"value": {
"type": "number",
"minimum": 0,
"maximum": 9999999999999.99,
"multipleOf": 0.01,
"description": "The amount to be transferred before deducting fees."
},
"currency": {
"type": "string",
"maxLength": 3,
"pattern": "^[A-Z]{3}$"
}
},
"required": [
"value",
"currency"
]
}
}
},
"requestedExecutionDate": {
"type": "string",
"description": "Requested date to execute the transaction in YYYY-MM-DD format."
},
"exchangeRateInformation": {
"type": "object",
"properties": {
"exchangeRate": {
"type": "number",
"description": "Rate expressed as a decimal, eg, 0.7 is 7/10 and 70%."
},
"rateType": {
"type": "string",
"pattern": "(AGREED|SALE|SPOT)",
"description": "The used rate type which can be AGREED, SALE or SPOT."
},
"contractIdentification": {
"type": "string",
"maxLength": 35,
"description": "Identification of the contract for the agreed exchange rate."
}
}
},
"chargeBearer": {
"type": "string",
"pattern": "(DEBT|CRED|SHAR|SLEV)",
"description": "Charge bearer type code."
},
"chargesAccount": {
"type": "object",
"description": "Used in case the debtors account should not be charged.",
"properties": {
"identification": {
"type": "object",
"properties": {
"iban": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$",
"description": "Identification of the account to charge fees from."
}
},
"required": [
"iban"
]
},
"currency": {
"type": "string",
"maxLength": 3,
"pattern": "^[A-Z]{3}$",
"description": "Currency of the account."
}
},
"required": [
"identification"
]
},
"ultimateDebtor": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 70,
"description": "Name of the ultimate debtor."
},
"postalAddress": {
"type": "object",
"properties": {
"streetName": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string",
"maxLength": 16
},
"postCode": {
"type": "string",
"maxLength": 16
},
"townName": {
"type": "string"
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter country codes as defined in ISO 3166."
},
"addressLine": {
"type": "array",
"description": "Address value in non structured form.",
"items": {
"type": "string",
"maxLength": 70
}
}
}
},
"identification": {
"type": "object",
"description": "Identification of the ultimate debtor",
"properties": {
"organisationIdentification": {
"type": "object",
"description": "Identification of an organization",
"properties": {
"bicOrBei": {
"type": "string",
"maxLength": 35,
"pattern": "^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$",
"description": "Bank identification code."
},
"other": {
"type": "object",
"description": "Other identification of the organization.",
"properties": {
"identification": {
"type": "string",
"maxLength": 35
},
"schemeName": {
"type": "object",
"properties": {
"proprietary": {
"type": "string",
"maxLength": 35
}
}
},
"issuer": {
"type": "string",
"maxLength": 35,
"description": "Issuer of the identification document."
}
}
}
}
},
"privateIdentification": {
"type": "object",
"description": "Identification of an individual person.",
"properties": {
"other": {
"type": "object",
"properties": {
"identification": {
"type": "string",
"maxLength": 35,
"description": "Unique identification of the person."
},
"schemeName": {
"type": "object",
"properties": {
"proprietary": {
"type": "string",
"maxLength": 35,
"description": "Type of the identification document."
}
}
},
"issuer": {
"type": "string",
"maxLength": 35,
"description": "Issuer of the identification document."
}
}
}
}
}
}
}
}
},
"debtor": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 70,
"description": "Name of the debtor."
},
"postalAddress": {
"type": "object",
"properties": {
"streetName": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string",
"maxLength": 16
},
"postCode": {
"type": "string",
"maxLength": 16
},
"townName": {
"type": "string"
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter country codes as defined in ISO 3166."
},
"addressLine": {
"type": "array",
"description": "Address value in non structured form.",
"items": {
"type": "string",
"maxLength": 70
}
}
}
}
}
},
"debtorAccount": {
"type": "object",
"properties": {
"identification": {
"type": "object",
"description": "Identification of the debtor's account.",
"properties": {
"iban": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$",
"description": "Account number in the IBAN format."
},
"other": {
"type": "object",
"properties": {
"identification": {
"type": "string",
"maxLength": 34,
"description": "Local BBAN format of the account number."
}
}
}
},
"required": [
"iban"
]
},
"currency": {
"type": "string",
"maxLength": 3,
"pattern": "^[A-Z]{3}$",
"description": "Currency of the account."
}
},
"required": [
"identification"
]
},
"intermediaryAgent1": {
"type": "object",
"description": "Intermediate bank involved in the transaction.",
"properties": {
"financialInstitutionIdentification": {
"type": "object",
"properties": {
"bic": {
"type": "string",
"maxLength": 35,
"pattern": "^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$",
"description": "Bank identification code."
},
"clearingSystemMemberIdentification": {
"type": "object",
"properties": {
"clearingSystemIdentification": {
"type": "object",
"description": "Identification of the intermediate clearing system.",
"properties": {
"code": {
"type": "string",
"maxLength": 5,
"description": "Code identifying the local clearing system."
},
"proprietary": {
"type": "string",
"maxLength": 35,
"description": "Identification of the local clearing system."
}
}
},
"memberIdentification": {
"type": "string",
"maxLength": 35,
"description": "Identification code of the clearing member."
}
}
},
"name": {
"type": "string",
"maxLength": 70,
"description": "A known name used to identify the intermediate party."
},
"postalAddress": {
"type": "object",
"properties": {
"streetName": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string",
"maxLength": 16
},
"postCode": {
"type": "string",
"maxLength": 16
},
"townName": {
"type": "string",
"maxLength": 35
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter country codes as defined in ISO 3166."
},
"addressLine": {
"type": "array",
"description": "Address value in non structured form.",
"items": {
"type": "string",
"maxLength": 70
}
}
}
},
"other": {
"type": "object",
"description": "Other form of unique identification of the intermediate bank.",
"properties": {
"identification": {
"type": "string",
"maxLength": 35
}
}
}
}
}
}
},
"creditorAgent": {
"type": "object",
"description": "Bank of the creditor.",
"properties": {
"financialInstitutionIdentification": {
"type": "object",
"properties": {
"bic": {
"type": "string",
"maxLength": 35,
"pattern": "^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$",
"description": "Bank identification code."
},
"clearingSystemMemberIdentification": {
"type": "object",
"properties": {
"clearingSystemIdentification": {
"type": "object",
"description": "Identification of the clearing system.",
"properties": {
"code": {
"type": "string",
"maxLength": 5,
"description": "Code identifying the local clearing system."
},
"proprietary": {
"type": "string",
"maxLength": 35,
"description": "Identification of the local clearing system."
}
}
},
"memberIdentification": {
"type": "string",
"maxLength": 35,
"description": "Identification code of the clearing member."
}
}
},
"name": {
"type": "string",
"maxLength": 70,
"description": "A known name used to identify the party."
},
"postalAddress": {
"type": "object",
"properties": {
"streetName": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string",
"maxLength": 16
},
"postCode": {
"type": "string",
"maxLength": 16
},
"townName": {
"type": "string",
"maxLength": 35
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter country codes as defined in ISO 3166."
},
"addressLine": {
"type": "array",
"description": "Address value in non structured form.",
"items": {
"type": "string",
"maxLength": 70
}
}
}
},
"other": {
"type": "object",
"description": "Other form of unique identification of the bank.",
"properties": {
"identification": {
"type": "string",
"maxLength": 35
}
}
}
}
}
}
},
"creditor": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 70,
"description": "Name of the creditor."
},
"postalAddress": {
"type": "object",
"properties": {
"streetName": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string",
"maxLength": 16
},
"postCode": {
"type": "string",
"maxLength": 16
},
"townName": {
"type": "string",
"maxLength": 35
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter country codes as defined in ISO 3166."
},
"addressLine": {
"type": "array",
"description": "Address value in non structured form.",
"items": {
"type": "string",
"maxLength": 70
}
}
}
}
}
},
"creditorAccount": {
"type": "object",
"properties": {
"identification": {
"type": "object",
"description": "Identification of the creditor's account.",
"properties": {
"iban": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$",
"description": "Account number in the IBAN format."
},
"other": {
"type": "object",
"properties": {
"identification": {
"type": "string",
"maxLength": 34,
"description": "Local BBAN format of the account number."
}
}
}
},
"required": [
"iban"
]
},
"currency": {
"type": "string",
"maxLength": 3,
"pattern": "^[A-Z]{3}$",
"description": "Currency of the account."
}
},
"required": [
"identification"
]
},
"ultimateCreditor": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 70,
"description": "Name of the ultimate creditor."
},
"postalAddress": {
"type": "object",
"properties": {
"streetName": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string",
"maxLength": 16
},
"postCode": {
"type": "string",
"maxLength": 16
},
"townName": {
"type": "string"
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter country codes as defined in ISO 3166."
},
"addressLine": {
"type": "array",
"description": "Address value in non structured form.",
"items": {
"type": "string",
"maxLength": 70
}
}
}
},
"identification": {
"type": "object",
"description": "Identification of the ultimate creditor",
"properties": {
"organisationIdentification": {
"type": "object",
"description": "Identification of an organization",
"properties": {
"bicOrBei": {
"type": "string",
"maxLength": 35,
"pattern": "^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$",
"description": "Bank identification code."
},
"other": {
"type": "object",
"description": "Other identification of the organization.",
"properties": {
"identification": {
"type": "string",
"maxLength": 35
},
"schemeName": {
"type": "object",
"properties": {
"proprietary": {
"type": "string",
"maxLength": 35
}
}
},
"issuer": {
"type": "string",
"maxLength": 35,
"description": "Issuer of the identification document."
}
},
"required": [
"identification"
]
}
}
},
"privateIdentification": {
"type": "object",
"description": "Identification of an individual person.",
"properties": {
"other": {
"type": "object",
"properties": {
"identification": {
"type": "string",
"maxLength": 35,
"description": "Unique identification of the person."
},
"schemeName": {
"type": "object",
"properties": {
"proprietary": {
"type": "string",
"maxLength": 35,
"description": "Type of the identification document."
},
"issuer": {
"type": "string",
"maxLength": 35,
"description": "Issuer of the identification document."
}
}
}
},
"required": [
"identification"
]
}
}
}
}
}
}
},
"purpose": {
"type": "object",
"description": "Purpose of the transaction.",
"properties": {
"code": {
"type": "string",
"maxLength": 4,
"description": "Purpose code."
},
"proprietary": {
"type": "string",
"maxLength": 35,
"description": "Free-form text describing the purpose."
}
}
},
"instructionForNextAgent": {
"type": "string",
"maxLength": 140,
"description": "Instructions for the next processing bank."
},
"remittanceInformation": {
"type": "object",
"properties": {
"structured": {
"type": "object",
"properties": {
"creditorReferenceInformation": {
"type": "object",
"properties": {
"reference": {
"type": "array",
"description": "Reference for only domestic payments allowing to specify VS, KS and SS.",
"items": {
"type": "string",
"maxLength": 35
}
}
}
}
}
},
"unstructured": {
"type": "string",
"description": "Information for the creditor."
}
}
},
"signInfo": {
"type": "object",
"properties": {
"state": {
"type": "string",
"description": "Transaction authorization state."
},
"signId": {
"type": "string",
"description": "Identification of the transaction authorization request."
},
"signInfo": {
"type": "string",
"description": "Transaction status identifier."
}
},
"required": [
"state",
"signId",
"signInfo"
]
}
},
"required": [
"paymentIdentification",
"amount",
"debtorAccount",
"creditorAccount",
"signInfo"
]
}
Transaction code description
Transaction types
| Transaction Type | Description |
|---|---|
| DOMESTIC | Domestic payment |
| FOREIGN | Foreign payment (EHP/NONEHP) |
| SEPA | SEPA payment |
Transaction Authorization State
| State Code | Description |
|---|---|
| OPEN | Transaction created. |
| FAILED | Transaction expired or failed due to unsuccesfull authentification attempts. |
| CANCELLED | Transaction cancelled |
| CONFIRMED | Transactions confirmed by the client. |
Transaction status identifier.
| Sign Info Code | Description |
|---|---|
| ACTC | AcceptedTechnicalValidation - Authentication and syntactical and semantical validation are successful. |
| RJCT | Rejected - Payment initiation or individual transaction included in the payment initiation has been rejected. |
| ACWC | AcceptedWithChange - Instruction is accepted but a change will be made, such as date or remittance not change. |
Sample response
HTTP/1.1 200 OK
{
"paymentIdentification": {
"instructionIdentification": "NOTPROVIDED",
"transactionIdentification": "048885570000001020045"
},
"paymentTypeInformation": {
"instructionPriority": "NORM",
"serviceLevel": {
"code": "DOMESTIC"
}
},
"amount": {
"instructedAmount": {
"value": 10050.15,
"currency": "CZK"
}
},
"requestedExecutionDate": "2017-02-20",
"debtorAccount": {
"identification": {
"iban": "CZ0708000000001019382023"
},
"currency": "CZK"
},
"creditorAccount": {
"identification": {
"iban": "CZ0708000000001019540081"
},
"currency": "CZK"
},
"remittanceInformation": {
"structured": {
"creditorReferenceInformation": {
"reference": [
"VS:501",
"KS:9",
"SS:1005"
]
}
}
},
"signInfo": {
"state": "OPEN",
"signId": "164298331754922"
}
}
Get payment status
GET /api/csob/psd2/v1/payments/{paymentId}/status
Get status of a created payment transaction.
Possible payment statuses are the following:
| Status code | Description |
|---|---|
| ACTC | AcceptedTechnicalValidation - Authentication and syntactical and semantical validation are successful |
| RJCT | Rejected – Payment initiation or individual transaction included in the payment initiation has been rejected |
| ACSP | AcceptedSettlementInProcess - All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution |
| ACSC | AcceptedSettlementCompleted - Settlement on the debtor´s account has been completed |
| ACWC | AcceptedWithChange - Instruction is accepted but a change will be made, such as date or remittance not change |
Request URI parameters
- paymentId: identification of the payment transaction returned by the Initiate payment service in the paymentIdentification/transactionIdentification attribute
Request security requirements
| Feature | Required |
|---|---|
| Certificate | ✔ |
| API key header | ✔ |
| Access token header | ✘ |
Supported features
| Feature | Supported |
|---|---|
| Paging | ✘ |
| Sorting | ✘ |
| Filtering | ✘ |
Operation-specific errors
| HTTP status code | Error | Description |
|---|
Please refer to the Overview section for the error response data structure and a list of errors common to all operations.
Sample request
HTTP
GET /api/csob/psd2/v1/payments/048885570000001020045/status HTTP/1.1
Host: api.csob.cz
APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b
Content-Type: application/json
Cache-Control: no-cache
cURL
curl -X GET \n https://api.csob.cz/api/csob/psd2/v1/payments/048885570000001020045/status \n -H 'APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b' \n -H 'Cache-Control: no-cache' \n -H 'Content-Type: application/json'
Response schema
{
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object",
"properties": {
"instructionStatus": {
"type": "string",
"enum": [
"ACTC",
"RJCT",
"ACSP",
"ACSC",
"ACWC"
]
}
},
"required": [
"instructionStatus"
]
}
Sample response
HTTP/1.1 200 OK
{
"instructionStatus": "ACTC"
}
Cancel payment
DELETE /api/csob/psd2/v1/my/payments/{paymentId}
Cancel a created but not yet authorized payment transaction.
Request URI parameters
- paymentId: identification of the payment transaction returned by the Initiate payment service in the paymentIdentification/transactionIdentification attribute
Request security requirements
| Feature | Required |
|---|---|
| Certificate | ✔ |
| API key header | ✔ |
| Access token header | ✔ |
Supported features
| Feature | Supported |
|---|---|
| Paging | ✘ |
| Sorting | ✘ |
| Filtering | ✘ |
Operation-specific errors
| HTTP status code | Error | Description |
|---|---|---|
| 409 | CONFLICT | Payment already canceled |
Please refer to the Overview section for the error response data structure and a list of errors common to all operations.
Sample request
HTTP
DELETE /api/csob/psd2/v1/my/payments/048885570000001020045 HTTP/1.1
Host: api.csob.cz
APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b
Content-Type: application/json
Authorization: Bearer 3/ilqobO3amOBPtHHLZsmTP7p3Z6Y0s6JvOdm1d1cwIhBdMEJZHr0wdG2f24CwbFAC
Cache-Control: no-cache
cURL
curl -X DELETE \n https://api.csob.cz/api/csob/psd2/v1/my/payments/048885570000001020045 \n -H 'APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b' \n -H 'Authorization: Bearer 3/ilqobO3amOBPtHHLZsmTP7p3Z6Y0s6JvOdm1d1cwIhBdMEJZHr0wdG2f24CwbFAC' \n -H 'Cache-Control: no-cache' \n -H 'Content-Type: application/json'
Sample response
HTTP/1.1 200 OK
Get transaction authorization details
GET /api/csob/psd2/v1/my/payments/{paymentId}/sign/{signId}
Get information of a payment authorization.
After initiating a payment transaction, an authorization, also called signing, procedure is created. This needs to be then authorized via the Start transaction authorization service in order to complete the payment transaction.
The response of this service contains a collection of supported authorization methods. It is up to you to choose one and use it when calling the Start transaction authorization service. ČSOB currently supports two methods:
- SOTP: Use this one when you want the bank client authorizes the transaction using their mobile phone via the ČSOB Smart Key application (must be installed on the phone)
- USERAGENT_REDIRECT: When using this scenario, the user’s browser will be redirected to a bank’s authorization page
Request URI parameters
- paymentId: identification of the payment transaction returned by the Initiate payment service in the paymentIdentification/transactionIdentification attribute
- signId: identification of the payment authorization returned by the Initiate payment service in the signInfo/signId attribute
Request security requirements
| Feature | Required |
|---|---|
| Certificate | ✔ |
| API key header | ✔ |
| Access token header | ✔ |
Supported features
| Feature | Supported |
|---|---|
| Paging | ✘ |
| Sorting | ✘ |
| Filtering | ✘ |
Operation-specific errors
| HTTP status code | Error | Description |
|---|
Please refer to the Overview section for the error response data structure and a list of errors common to all operations.
Sample request
HTTP
GET /api/csob/psd2/v1/my/accounts HTTP/1.1
Host: api.csob.cz
APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b
Content-Type: application/json
Authorization: Bearer 3/FPLYXU5t3muiv1DiOYWRiAZj9DXM3hYbwh2u4miKG7gg1aUPpWsVP5Nkrv9W8Zdn
Cache-Control: no-cache
cURL
curl -X GET \n https://api.csob.cz/api/csob/psd2/v1/my/accounts \n -H 'APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b' \n -H 'Authorization: Bearer 3/FPLYXU5t3muiv1DiOYWRiAZj9DXM3hYbwh2u4miKG7gg1aUPpWsVP5Nkrv9W8Zdn' \n -H 'Cache-Control: no-cache' \n -H 'Content-Type: application/json'
Response schema
{
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object",
"properties": {
"scenarios": {
"type": "array",
"items": {
"type": "string",
"description": "Collection of codes of a supported authorization methods."
}
},
"signInfo": {
"type": "object",
"properties": {
"state": {
"type": "string",
"description": "Transaction authorization state."
},
"signId": {
"type": "string",
"description": "Identification of the transaction authorization request."
}
},
"required": [
"state",
"signId"
]
}
},
"required": [
"scenarios",
"signInfo"
]
}
Transaction code description
Transaction Authorization State
| State Code | Description |
|---|---|
| OPEN | Transaction created. |
| FAILED | Transaction expired or failed due to unsuccesfull authentification attempts. |
| CANCELLED | Transaction cancelled |
| CONFIRMED | Transactions confirmed by the client. |
Sample response
HTTP/1.1 200 OK
{
"scenarios": [
"SOTP",
"USERAGENT_REDIRECT"
],
"signInfo": {
"state": "OPEN",
"signId": "164298331754922"
}
}
Start transaction authorization
POST /api/csob/psd2/v1/my/payments/{paymentId}/sign/{signId}
Start the authorization flow of an initiated payment.
In general, there may be several authorization methods, such as sending a text message to the bank client with an one time password or using a federated authorization when the client is redirected to an authorization page. Which method is used is determined by the authoriztionType attribute in the request of this call.
To get a list of codes of supported authorization methods, use the Get transaction authorization details service.
ČSOB currently supports two methods:
- SOTP: Use this one when you want the bank client authorizes the transaction using their mobile phone via the ČSOB Smart Key application (must be installed on the phone)
- USERAGENT_REDIRECT: When using this scenario, the user’s browser will be redirected to a bank’s authorization page
In both cases the authorization flow is similar:
- You call this service to start the payment authorization and specify your redirect URI. This will be either an address for the user’s browser or an app link for a mobile phone.
- The service will reply with a URI which you should redirect the user to. Again, it will be either a link for a browser or an app link.
- You redirect the user to the provided bank system URI. This will start the authorization process in which the user will confirm the payment, e.g. from a mobile app, by an authorization SMS, etc.
- The bank system will redirect the user back to your site or an mobile app using the redirect URI you specified when you called this service.
- Poll the Get transaction authorization details service to see updated status of the authorization.
Request URI parameters
- paymentId: identification of the payment transaction returned by the Initiate payment service in the paymentIdentification/transactionIdentification attribute
- signId: identification of the payment authorization returned by the Initiate payment service in the signInfo/signId attribute
Request security requirements
| Feature | Required |
|---|---|
| Certificate | ✔ |
| API key header | ✔ |
| Access token header | ✔ |
Supported features
| Feature | Supported |
|---|---|
| Paging | ✘ |
| Sorting | ✘ |
| Filtering | ✘ |
Operation-specific errors
| HTTP status code | Error | Description |
|---|---|---|
| 400 | AUTH_TX_EXPIRED | The transaction has already expired |
| 403 | FORBIDDEN | Transaction rejected |
Please refer to the Overview section for the error response data structure and a list of errors common to all operations.
Request schema
{
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object",
"properties": {
"authorizationType": {
"type": "string",
"description": "The CODE value of the authorization scenario"
},
"signRedirectUrl": {
"type": "string",
"description": "The URI (web site or a mobile app link) to redirect the user to after starting the payment authorization procedure"
}
},
"required": [
"authorizationType",
"signRedirectUrl"
]
}
Sample request
HTTP
POST /api/csob/psd2/v1/my/payments/048885570000001020045/sign/164298331754922 HTTP/1.1
Host: api.csob.cz
APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b
Content-Type: application/json
Authorization: Bearer 3/ilqobO3amOBPtHHLZsmTP7p3Z6Y0s6JvOdm1d1cwIhBdMEJZHr0wdG2f24CwbFAC
Cache-Control: no-cache
{
"authorizationType": "USERAGENT_REDIRECT",
"signRedirectUrl": "https://finadvisor.domain.com/sign-redirect"
}
cURL
curl -X POST \n 'https://api.csob.cz/api/csob/psd2/v1/my/payments/048885570000001020045sign/164298331754922' \n -H 'APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b' \n -H 'Authorization: Bearer 3/ilqobO3amOBPtHHLZsmTP7p3Z6Y0s6JvOdm1d1cwIhBdMEJZHr0wdG2f24CwbFAC' \n -H 'Cache-Control: no-cache' \n -H 'Content-Type: application/json' \n -d '{
"authorizationType": "USERAGENT_REDIRECT",
"signRedirectUrl": "https://finadvisor.domain.com/sign-redirect"
}'
Response schema
{
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object",
"properties": {
"authorizationType": {
"type": "string",
"description": "The CODE value of authorization scenario."
},
"href": {
"type": "object",
"description": "Reference to invoke federated authorization.",
"properties": {
"url": {
"type": "string",
"description": "The URL link or package of federated authorization."
},
"id": {
"type": "string",
"description": "The ID to invoke federated authorization."
}
},
"required": [
"url"
]
},
"method": {
"type": "string",
"description": "Method to use the href link for federated authorization."
},
"formData": {
"type": "object",
"description": "Values in use case of POST method of federated authorization.",
"properties": {
"SAMLRequest": {
"type": "string",
"description": "SAML value in use case of federated authorization (authorizationType=USERAGENT_REDIRE CT)."
},
"relayState": {
"type": "string",
"description": "relayState return value in use case of federated authorization (authorizationType=USERAGENT_REDIRE CT)."
}
}
},
"signInfo": {
"type": "object",
"properties": {
"state": {
"type": "string",
"description": "The transaction authorization state."
},
"signId": {
"type": "string",
"description": "Identification of the transaction authorization request."
}
},
"required": [
"state",
"signId"
]
}
},
"required": [
"authorizationType",
"signInfo"
]
}
Transaction code description
Transaction Authorization State
| State Code | Description |
|---|---|
| OPEN | Transaction created. |
| FAILED | Transaction expired or failed due to unsuccesfull authentification attempts. |
| CANCELLED | Transaction cancelled |
| CONFIRMED | Transactions confirmed by the client. |
Sample response
HTTP/1.1 200 OK
{
"authorizationType":"USERAGENT_REDIRECT",
"href":{
"url":"https://identita.csob.cz/mobile/auth/?session_id=OrUDAWCvRV3RW1vTr0TIWowRsl47uPvB"
},
"signInfo":{
"state":"OPEN",
"signId":"164298331754922"
}
}