New version 1.1.0
Update information:
- Change for payment-product "domestic-budget-transfers-bgn"
- for details see definition "BudgetPaymentDetails"
- Added new definition "BICFI" for data element "creditorAgent"
Paths
/payments/{payment-product}
This method to initiate a payment initiation at the Postbank can be sent with a JSON body depending on the payment product in the path. There are the following payment products:
- domestic-credit-transfers-bgn - Credit payment (local in BGN)
- domestic-budget-transfers-bgn - Payment to the BG budget
- sepa-credit-transfers - Payment in EUR
- cross-border-transfers
Example request body definitions:
- pisRequestBodyBGNCreditTransfer
- pisRequestBodyBGNBudgetTransfer
- pisRequestBodySEPACreditTransfer
- pisRequestBodyCrossBorderTransfer
In the test tool is used only general request body with all parameters paymentInitiationServiceRequestBody
Creates a payment initiation resource addressable under {paymentId} with all data relevant for the corresponding payment product. This is the first step in the API to initiate the related payment
Types of payment products:
- domestic-credit-transfers-bgn
- domestic-budget-transfers-bgn
- sepa-credit-transfers
- cross-border-transfers
{
"enum": [
"domestic-credit-transfers-bgn",
"domestic-budget-transfers-bgn",
"sepa-credit-transfers",
"cross-border-transfers"
]
}ID of the request, unique to the call, as determined by the initiating party.
{
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
}The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP.
{
"pattern": "^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$"
}URI of the TPP, where the transaction flow shall be redirected to after a Redirect
If parameter is used then must be filled.
- If TRUE - REDIRECT Approach is applying.
- If FALSE - DECOUPLED Approach is applying.
- If parameter is not used then REDIRECT Approach is applying by default.
The forwarded Agent header field of the http request between PSU and TPP, if available.
The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP, if available.
The forwarded Geo Location header field of the corresponding http request between PSU and TPP if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
HTTP method used at the PSU – TPP interface, if available. Valid values are:
- GET
- POST
- PUT
- PATCH
- DELETE
{
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE"
]
}UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available.
Created
{
"schema": {
"type": "object",
"required": [
"transactionStatus",
"paymentId",
"_links"
],
"properties": {
"transactionStatus": {
"$ref": "#\/definitions\/TransactionStatus"
},
"paymentId": {
"type": "string",
"description": "resource identification of the generated payment initiation resource."
},
"transactionFees": {
"$ref": "#\/definitions\/Amount",
"description": "Can be used by the Postbank to transport transaction fees relevant for the underlying payments."
},
"transactionFeeIndicator": {
"type": "boolean",
"description": "If equals “true”, the transaction will involve specific transaction cost as shown by the Postbank in their public price list or as agreed between Postbank and PSU. If equals “false”, the transactiBad Request
Unauthorized
Forbidden
Internal Server Error
/payments/{payment-product}/{paymentId}
Returns the content of a payment object
Types of payment products:
- domestic-credit-transfers-bgn
- domestic-budget-transfers-bgn
- sepa-credit-transfers
- cross-border-transfers
{
"enum": [
"domestic-credit-transfers-bgn",
"domestic-budget-transfers-bgn",
"sepa-credit-transfers",
"cross-border-transfers"
]
}Resource identification of the generated payment initiation resource.
ID of the request, unique to the call, as determined by the initiating party.
{
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
}The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP.
{
"pattern": "^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$"
}The forwarded Agent header field of the http request between PSU and TPP, if available.
The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP, if available.
The forwarded Geo Location header field of the corresponding http request between PSU and TPP if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
HTTP method used at the PSU – TPP interface, if available. Valid values are:
- GET
- POST
- PUT
- PATCH
- DELETE
{
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE"
]
}UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available.
OK
{
"schema": {
"type": "object",
"example": {
"paymentInfo": {
"debtorAccount": {
"iban": "BG77BPBI000001"
},
"instructedAmount": {
"currency": "EUR",
"amount": 15
},
"creditorAccount": {
"iban": "BG77BPBI000002"
},
"debtorName": "Debtor EOOD",
"creditorName": "Trader EOOD",
"creditorAddress": {
"country": "BG"
},
"remittianceInformationUnstructed": "Ref Number Merchant",
"serviceLevel": "SEPA"
},
"payment-product": "sepa-credit-transfer",
"transactionStatus": "ACSP"
}
}
}Bad Request
Unauthorized
Forbidden
Internal Server Error
/payments/{payment-product}/{paymentId}/status
Payment initiation status request
Reads the transaction status of the payment
Types of payment products:
- domestic-credit-transfers-bgn
- domestic-budget-transfers-bgn
- sepa-credit-transfers
- cross-border-transfers
{
"enum": [
"domestic-credit-transfers-bgn",
"domestic-budget-transfers-bgn",
"sepa-credit-transfers",
"cross-border-transfers"
]
}Resource identification of the generated payment initiation resource.
ID of the request, unique to the call, as determined by the initiating party.
{
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
}The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP.
{
"pattern": "^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$"
}The forwarded Agent header field of the http request between PSU and TPP, if available.
The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP, if available.
The forwarded Geo Location header field of the corresponding http request between PSU and TPP if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
HTTP method used at the PSU – TPP interface, if available. Valid values are:
- GET
- POST
- PUT
- PATCH
- DELETE
{
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE"
]
}UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available.
OK
{
"schema": {
"type": "object",
"properties": {
"transactionStatus": {
"$ref": "#\/definitions\/TransactionStatus"
}
},
"example": {
"transactionStatus": "RCVD"
}
},
"headers": {
"X-Request-ID": {
"type": "string",
"description": "ID of the request, unique to the call, as determined by the initiating party."
}
}
}Bad Request
Unauthorized
Forbidden
Internal Server Error
Definitions
{
"type": "object",
"required": [
"currency",
"amount"
],
"properties": {
"currency": {
"type": "string",
"description": "ISO 4217 Alpha 3 currency code",
"pattern": "[A-Z]{3}"
},
"amount": {
"type": "string",
"pattern": "^[0-9]\\d{0,13}(\\.\\d{1,2})?$"
}
}
}
{
"type": "object",
"required": [
"country"
],
"properties": {
"street": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string"
},
"city": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"country": {
"type": "string",
"description": "ISO 3166 ALPHA2 country code",
"example": "SE",
"pattern": "[A-Z]{2}"
}
}
}
- SEPA - Used for SEPA payment
- URGP - Used for payments through RTGS System
- SDVA - Used for Cross border CT. Payment must be executed with same day value to the creditor
- NEXT - Used for Cross border CT. Payment must be executed with next working day value to the creditor
- SPOT - Used for Cross border CT. Payment must be executed with spot working day value to the creditor
{
"type": "string",
"example": "SEPA",
"enum": [
"SEPA",
"URGP",
"SDVA",
"NEXT",
"SPOT"
]
}
GOVT - Constant marker budget payment
{
"type": "string",
"enum": [
"GOVT"
]
}
- DEBT – Borne By Debtor
- CRED – Borne By Creditor
- SHAR – Shared in Credit Transfer context
- SLEV – Usefully in SEPA payments
{
"type": "string",
"example": "DEBT",
"enum": [
"DEBT",
"CRED",
"SHAR",
"SLEV"
]
}
{
"type": "object",
"properties": {
"taxPayerId": {
"description": "Mandatory, if position 13 in creditor account is equal to \"8\".",
"type": "string",
"pattern": "^[0-9]{1,13}$",
"maxLength": 13
},
"taxPayerType": {
"$ref": "#\/definitions\/TaxTypeCode"
},
"paymentCategory": {
"description": "Payment Category – 6 digit code. May be used if positions 13 and 14 in creditor account are equal to \"8\" and \"4\".",
"type": "string",
"pattern": "^[0-9]{1,6}$",
"maxLength": 6
}
}
}
BICFI
{
"type": "string",
"pattern": "[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}",
"default": "AAAADEBBXXX"
}
Tax Payer Type – 3 CAP letters code (Cyrillic allowed). Mandatory, if position 13 in creditor account is equal to "8".
{
"type": "string",
"enum": [
"EGN",
"EIK",
"PNF",
"ЕГН",
"ЕИК",
"ЛНЧ"
],
"maxLength": 3
}
{
"type": "object",
"properties": {
"scaRedirect": {
"$ref": "#\/definitions\/Href",
"description": "A link to a Postbank site where SCA is performed within the Redirect SCA approach."
},
"self": {
"$ref": "#\/definitions\/Href",
"description": "The link to the payment initiation resource created by the request itself. This link can be used later to retrieve the transaction status of the payment initiation."
},
"status": {
"$ref": "#\/definitions\/Href",
"description": "The link to retrieve the transaction status of the payment initiation."
}
}
}
The transaction status is filled with codes of the ISO 20022 data table. In this specification are using the following:
- "RCVD", which stands for "Received", where payment initiation has been received by the Bank.
- "PDNG", which stands for "Penfing", where further checks will be performed by the Bank before settlement routine.
- "RJCT", which stands for "Rejected", where payment initiation has been rejected.
- "ACSP", which stands for “AcceptedSettlementInProcess”, where the settlement routine regarding the debtor account of the payment has already been initiated.
- "ACSC", which stands for “AcceptedSettlementCompleted”, indicating that the money has been booked already from the debtor account.
{
"type": "string"
}
{
"type": "object",
"properties": {
"tppMessages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"category": {
"type": "string"
},
"code": {
"type": "string"
},
"text": {
"type": "string"
}
}
}
}
}
}
{
"type": "object",
"required": [
"instructedAmount",
"debtorAccount",
"creditorName",
"creditorAccount"
],
"properties": {
"debtorAccount": {
"$ref": "#\/definitions\/AccountReference"
},
"ultimateDebtor": {
"type": "string",
"maxLength": 70,
"description": "Mandatory for: domestic-budget-transfers-bgn. N.A. for: domestic-credit-transfers-bgn, sepa-credit-transfers, cross-border-transfers."
},
"instructedAmount": {
"$ref": "#\/definitions\/Amount"
},
"creditorAccount": {
"$ref": "#\/definitions\/AccountReference"
},
"creditorAgent": {
"$ref": "#\/definitions\/BICFI"
},
"creditorAgentName": {
"type": "string",
"description": "Mandatory for creditorAccount when payment is cross-border-transfers - If no IBAN used for creditorAccount. N.A. for: domestic-credit-transfers-bgn, domestic-budget-transfers-bgn, sepa-credit-transfers.",
"maxLength": 140
},
"creditorName": {
"type": "string",
"description": "Creditor Name",
"maxLength": 70
},
"creditorAddress": {
"description": "Mandatory for: cross-border-transfers. Optional for: sepa-credit-transfers. N.A. for: domestic-credit-transfers-bgn, domestic-budget-transfers-bgn.",
"$ref": "#\/definitions\/Address"
},
"purposeCode": {
"description": "Mandatory for: domestic-budget-transfers-bgn. N.A. for: domestic-credit-transfers-bgn, cross-border-transfers, sepa-credit-transfers.",
"$ref": "#\/definitions\/PurposeCode"
},
"chargeBearer": {
"description": "Optional",
"$ref": "#\/definitions\/ChargeBearerCode"
},
"remittanceInformationUnstructured": {
"type": "string",
"description": "Mandatory for: domestic-credit-transfers-bgn, domestic-budget-transfers-bgn. Optional for: sepa-credit-transfers, cross-border-transfers.",
"maxLength": 140
},
"serviceLevel": {
"description": "Optional",
"$ref": "#\/definitions\/ServiceLevelCode"
},
"budgetPaymentDetails": {
"description": "Used for: domestic-budget-transfers-bgn. N.A. for: domestic-credit-transfers-bgn, sepa-credit-transfers, cross-border-transfers.",
"$ref": "#\/definitions\/BudgetPaymentDetails"
}
}
}
{
"type": "object",
"required": [
"instructedAmount",
"debtorAccount",
"creditorName",
"creditorAccount"
],
"properties": {
"debtorAccount": {
"$ref": "#\/definitions\/AccountReference"
},
"instructedAmount": {
"$ref": "#\/definitions\/Amount"
},
"creditorAccount": {
"$ref": "#\/definitions\/AccountReference"
},
"creditorAgent": {
"$ref": "#\/definitions\/BICFI"
},
"creditorName": {
"type": "string",
"description": "Creditor Name",
"maxLength": 70
},
"creditorAddress": {
"$ref": "#\/definitions\/Address"
},
"remittanceInformationUnstructured": {
"type": "string",
"maxLength": 140
},
"serviceLevel": {
"$ref": "#\/definitions\/ServiceLevelCode"
},
"chargeBearer": {
"type": "string"
}
}
}
{
"type": "object",
"required": [
"instructedAmount",
"debtorAccount",
"ultimateDebtor",
"creditorName",
"creditorAccount",
"purposeCode",
"remittanceInformationUnstructured"
],
"properties": {
"debtorAccount": {
"$ref": "#\/definitions\/AccountReference"
},
"ultimateDebtor": {
"type": "string",
"maxLength": 70
},
"instructedAmount": {
"$ref": "#\/definitions\/Amount"
},
"creditorAccount": {
"$ref": "#\/definitions\/AccountReference"
},
"creditorName": {
"$ref": "#\/definitions\/BICFI"
},
"purposeCode": {
"$ref": "#\/definitions\/PurposeCode"
},
"remittanceInformationUnstructured": {
"type": "string",
"maxLength": 140
},
"serviceLevel": {
"$ref": "#\/definitions\/ServiceLevelCode"
},
"budgetPaymentDetails": {
"$ref": "#\/definitions\/BudgetPaymentDetails"
}
}
}
{
"type": "object",
"required": [
"instructedAmount",
"debtorAccount",
"creditorName",
"creditorAccount",
"remittanceInformationUnstructured"
],
"properties": {
"debtorAccount": {
"$ref": "#\/definitions\/AccountReference"
},
"instructedAmount": {
"$ref": "#\/definitions\/Amount"
},
"creditorAccount": {
"$ref": "#\/definitions\/AccountReference"
},
"creditorName": {
"$ref": "#\/definitions\/BICFI"
},
"remittanceInformationUnstructured": {
"type": "string",
"maxLength": 140
},
"serviceLevel": {
"$ref": "#\/definitions\/ServiceLevelCode"
}
}
}
{
"type": "object",
"required": [
"instructedAmount",
"debtorAccount",
"creditorName",
"creditorAccount",
"creditorAddress"
],
"properties": {
"debtorAccount": {
"$ref": "#\/definitions\/AccountReference"
},
"instructedAmount": {
"$ref": "#\/definitions\/Amount"
},
"creditorAccount": {
"$ref": "#\/definitions\/AccountReference"
},
"creditorAgent": {
"$ref": "#\/definitions\/BICFI"
},
"creditorAgentName": {
"type": "string",
"description": "Mandatory, if no IBAN used for creditorAccount.",
"maxLength": 140
},
"creditorName": {
"type": "string",
"description": "Creditor Name",
"maxLength": 70
},
"creditorAddress": {
"$ref": "#\/definitions\/Address"
},
"chargeBearer": {
"$ref": "#\/definitions\/ChargeBearerCode"
},
"remittanceInformationUnstructured": {
"type": "string",
"maxLength": 140
},
"serviceLevel": {
"$ref": "#\/definitions\/ServiceLevelCode",
"example": "SPOT"
}
}
}
{
"type": "object",
"properties": {
"iban": {
"type": "string",
"description": "IBAN of account, mandatory for debtorAccount for all payments and mandatory for creditorAccount when payment is: domestic-credit-transfers-bgn, domestic-budget-transfers-bgn, sepa-credit-transfers. Optional for creditorAccount when payment is cross-border-transfers. If no IBAN used then \"creditorAgentName\" have to be filled.",
"pattern": "[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}"
}
}
}
{
"type": "object",
"properties": {
"href": {
"type": "string"
}
}
}