Direct API Integration¶

Neogated BLIK – API Integration¶

This page provides guidance for integrating Neogated BLIK using the Direct API approach. Unlike the Hosted Payment Page (HPP) flow where the customer selects their payment method during the checkout process, the API flow assumes that BLIK has already been selected on your platform. This allows for a more seamless and controlled user experience.

With API integration, your platform is responsible for:

Presenting BLIK as a payment option
Collecting required customer data (email, first name, last name)
Initiating the payment request with the correct payment method type and data
Redirecting the customer to Neogated to complete BLIK authentication
Handling asynchronous callbacks and updating final payment status

🔧 Payment Method Type Format¶

When initiating a payment request, use the following payment method type:

neogated-blik

⚠️ Note: This exact type is required. Incorrect payment method types will result in request failures.

🧾 Required Payment Method Data¶

Each Neogated BLIK request must include the following customer details in the payment method data:

email – Customer email address
first_name – Customer first name
last_name – Customer last name

These fields are required by Neogated for regulatory and transactional reasons and must be collected before initiating the redirect.

📝 Optional Payment Method Data¶

The following fields are optional but recommended for better transaction processing:

Field	Type	Default	Description
`phone`	string	–	Customer phone number with country code
`country`	string	PL	ISO 3166-1 alpha-2 country code
`address`	string	–	Customer street address
`city`	string	–	Customer city
`postal_code`	string	–	Customer postal code
`state`	string	–	Customer state/region
`date_of_birth`	string	–	Customer date of birth (YYYY-MM-DD)
`language`	string	–	Preferred language code (e.g., pl, en)
`blik_code`	string	–	6-digit BLIK code if pre-collected

ℹ️ Note: If blik_code is provided, the customer may skip entering it on the Neogated checkout page.

Payment Gateway API 1.0.0¶

Endpoints¶

GET /api/transactions/{id}/status¶

Get Transaction Status

Description

Retrieve the current status of a transaction. Use this endpoint to poll for transaction status updates after redirect.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`bearerAuth`	header	string	N/A	No	JWT Bearer token
`Authorization`	header	string		No	Bearer token
`id`	path	string		No	Transaction ID returned from authorize response

Responses

200 OK404 Not Found

application/json

{
    "found": true,
    "transaction": {
        "id": "gfOZMUOlSioaGxCYHUAS",
        "reference": "blik-1773458831",
        "description": "BLIK Payment",
        "currency": "PLN",
        "amount": 10000,
        "status": "PENDING",
        "pending": true,
        "approved": false,
        "transaction_type": "PURCHASE",
        "payment_method": {
            "type": "neogated-blik",
            "brand": "neogated-blik"
        }
    }
}

{
    "found": true,
    "transaction": {
        "id": "gfOZMUOlSioaGxCYHUAS",
        "reference": "blik-1773458831",
        "description": "BLIK Payment",
        "currency": "PLN",
        "amount": 10000,
        "status": "APPROVED",
        "pending": false,
        "approved": true,
        "transaction_type": "PURCHASE",
        "payment_method": {
            "type": "neogated-blik",
            "brand": "neogated-blik"
        }
    }
}

Schema of the response body

{
    "type": "object",
    "description": "Response for transaction status check",
    "properties": {
        "found": {
            "type": "boolean",
            "description": "Whether the transaction was found"
        },
        "transaction": {
            "$ref": "#/components/schemas/ExtendedTransactionDto",
            "nullable": true,
            "description": "Transaction details if found"
        }
    }
}

application/json

{
    "found": false,
    "transaction": null
}

Schema of the response body

{
    "type": "object",
    "description": "Response for transaction status check",
    "properties": {
        "found": {
            "type": "boolean",
            "description": "Whether the transaction was found"
        },
        "transaction": {
            "$ref": "#/components/schemas/ExtendedTransactionDto",
            "nullable": true,
            "description": "Transaction details if found"
        }
    }
}

POST /api/transactions/authorize¶

Authorize BLIK Transaction

Description

Initiate Neogated BLIK transaction. Requirements: - An Authorization header with a valid Bearer token is required. - Payment method type must be neogated-blik - Payment method data with email, first_name, and last_name - Currency must be PLN

Input parameters

Parameter	In	Type	Default	Nullable	Description
`bearerAuth`	header	string	N/A	No	JWT Bearer token
`Authorization`	header	string		No	Bearer token (e.g., "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")

Request body

application/json

{
    "reference": "string",
    "terminal_id": "string",
    "description": "string",
    "currency": "PLN",
    "amount": 10000,
    "transaction_type": "PURCHASE",
    "payment_method": {
        "type": "neogated-blik",
        "data": {
            "email": "jan.kowalski@example.com",
            "first_name": "Jan",
            "last_name": "Kowalski",
            "phone": "+48123456789",
            "country": "PL",
            "address": "ul. Marszalkowska 1",
            "city": "Warszawa",
            "postal_code": "00-001",
            "state": "string",
            "date_of_birth": "1990-01-15",
            "language": "pl",
            "blik_code": "123456"
        }
    },
    "metadata": {},
    "return_url": "string",
    "error_url": "string",
    "cancel_url": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "properties": {
        "reference": {
            "type": "string",
            "description": "Unique transaction reference.",
            "maxLength": 40,
            "minLength": 1
        },
        "terminal_id": {
            "type": "string",
            "description": "Terminal identifier.",
            "minLength": 5,
            "maxLength": 20
        },
        "description": {
            "type": "string",
            "description": "Transaction description."
        },
        "currency": {
            "type": "string",
            "description": "Currency code (PLN only for BLIK).",
            "example": "PLN",
            "enum": [
                "PLN"
            ],
            "minLength": 3,
            "maxLength": 3
        },
        "amount": {
            "type": "integer",
            "format": "int64",
            "example": 10000,
            "description": "Transaction amount in minor units (groszy for PLN)."
        },
        "transaction_type": {
            "type": "string",
            "enum": [
                "PURCHASE"
            ],
            "description": "Type of transaction (only PURCHASE supported)."
        },
        "payment_method": {
            "type": "object",
            "properties": {
                "type": {
                    "type": "string",
                    "enum": [
                        "neogated-blik"
                    ],
                    "description": "Payment method type for BLIK."
                },
                "data": {
                    "type": "object",
                    "properties": {
                        "email": {
                            "type": "string",
                            "format": "email",
                            "description": "Customer email address (required).",
                            "example": "jan.kowalski@example.com"
                        },
                        "first_name": {
                            "type": "string",
                            "description": "Customer first name (required).",
                            "example": "Jan"
                        },
                        "last_name": {
                            "type": "string",
                            "description": "Customer last name (required).",
                            "example": "Kowalski"
                        },
                        "phone": {
                            "type": "string",
                            "description": "Customer phone number with country code.",
                            "example": "+48123456789"
                        },
                        "country": {
                            "type": "string",
                            "description": "ISO 3166-1 alpha-2 country code.",
                            "default": "PL",
                            "example": "PL"
                        },
                        "address": {
                            "type": "string",
                            "description": "Customer street address.",
                            "example": "ul. Marszalkowska 1"
                        },
                        "city": {
                            "type": "string",
                            "description": "Customer city.",
                            "example": "Warszawa"
                        },
                        "postal_code": {
                            "type": "string",
                            "description": "Customer postal code.",
                            "example": "00-001"
                        },
                        "state": {
                            "type": "string",
                            "description": "Customer state/region."
                        },
                        "date_of_birth": {
                            "type": "string",
                            "format": "date",
                            "description": "Customer date of birth (YYYY-MM-DD).",
                            "example": "1990-01-15"
                        },
                        "language": {
                            "type": "string",
                            "description": "Preferred language code.",
                            "example": "pl"
                        },
                        "blik_code": {
                            "type": "string",
                            "pattern": "^\\d{6}$",
                            "description": "6-digit BLIK code if pre-collected from customer.",
                            "example": "123456"
                        }
                    },
                    "required": [
                        "email",
                        "first_name",
                        "last_name"
                    ]
                }
            },
            "required": [
                "type",
                "data"
            ]
        },
        "metadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "Additional metadata for the transaction."
        },
        "return_url": {
            "type": "string",
            "description": "URL to redirect to after successful processing."
        },
        "error_url": {
            "type": "string",
            "description": "URL to redirect to on error."
        },
        "cancel_url": {
            "type": "string",
            "description": "URL to redirect to if the transaction is canceled."
        }
    },
    "required": [
        "reference",
        "terminal_id",
        "description",
        "currency",
        "amount",
        "transaction_type",
        "payment_method",
        "return_url",
        "error_url",
        "cancel_url"
    ]
}

Responses

200 OK422 Unprocessable Content

application/json

{
    "result": null,
    "action": null,
    "redirect": {
        "transaction_id": "txn_abc123",
        "session_id": "txn_abc123",
        "url": "https://gate.stg.neogated.com/checkout/blik-session-xyz789"
    },
    "form_submit": null
}

{
    "result": {
        "id": "txn_abc123",
        "merchant_id": "merchant_001",
        "order_id": "order_12345",
        "terminal_id": "terminal_001",
        "reference": "ref_12345",
        "description": "BLIK Payment",
        "currency": "PLN",
        "amount": 10000,
        "processing_result": {
            "payment_provider_id": "neogated",
            "payment_provider_account_id": "blik_config",
            "approval_code": null,
            "reference_number": null
        },
        "approved": false,
        "pending": false,
        "channel": "ecommerce",
        "transaction_type": "PURCHASE",
        "status": "DECLINED",
        "payment_method": {
            "method": "neogated-blik",
            "hash": null,
            "type": "neogated-blik",
            "masked": "BLIK ******"
        },
        "redirect_url": null,
        "normalized_amount": 10000,
        "errors": []
    },
    "action": null,
    "redirect": null,
    "form_submit": null
}

Schema of the response body

{
    "type": "object",
    "properties": {
        "result": {
            "$ref": "#/components/schemas/ExtendedTransactionDto",
            "description": "Extended transaction details."
        },
        "action": {
            "$ref": "#/components/schemas/ActionRequiredDto",
            "description": "Details for any required action."
        },
        "redirect": {
            "$ref": "#/components/schemas/RedirectDto",
            "description": "Redirect information for the transaction."
        },
        "form_submit": {
            "$ref": "#/components/schemas/FormSubmitDto",
            "description": "Form submission details if required."
        }
    },
    "description": "Response payload for executing a transaction."
}

application/json

{
    "errors": [
        {
            "message": "Invalid currency. BLIK only supports PLN.",
            "params": [
                "currency",
                "PLN"
            ],
            "property": "currency"
        }
    ],
    "method": "POST",
    "status": 422
}

{
    "errors": [
        {
            "message": "email is required in payment_method.data",
            "params": [
                "email"
            ],
            "property": "payment_method.data.email"
        }
    ],
    "method": "POST",
    "status": 422
}

Schema of the response body

{
    "type": "object",
    "properties": {
        "errors": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "message": {
                        "type": "string"
                    },
                    "params": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "property": {
                        "type": "string"
                    }
                }
            }
        },
        "method": {
            "type": "string"
        },
        "status": {
            "type": "integer"
        }
    }
}

Schemas¶

ActionRequiredDto¶

Name	Type	Description
`payment_data`	string
`session_id`	string
`token`	string
`transaction_id`	string
`type`	string

ExecuteTransactionResponseDto¶

Name	Type	Description
`action`	ActionRequiredDto	Details for any required action.
`form_submit`	FormSubmitDto	Form submission details if required.
`redirect`	RedirectDto	Redirect information for the transaction.
`result`	ExtendedTransactionDto	Extended transaction details.

ExtendedTransactionDto¶

Name	Type	Description
`amount`	integer(int64)
`approved`	boolean
`channel`	string
`currency`	string
`description`	string
`errors`	Array<>
`id`	string
`merchant_id`	string
`normalized_amount`	integer(int64)
`order_id`	string
`payment_method`	PaymentMethodDataDto
`pending`	boolean
`processing_result`	ProcessingResultDto
`redirect_url`	string
`reference`	string
`status`	TransactionStatus
`terminal_id`	string
`transaction_type`	string

FormSubmitDto¶

Name	Type	Description
`data`
`session_id`	string
`transaction_id`	string
`url`	string

NeogatedCallbackDto¶

Name	Type	Description
`accountReference`	string	Masked BLIK account reference.
`amount`	number(decimal)	Transaction amount in major units (e.g., 100.00 PLN).
`currency`	string	Currency code.
`psTransactionId`	string	Neogated transaction ID.
`status`	string	Payment status from Neogated.
`transactionId`	string	Your transaction ID.
`type`	string	Transaction type.
`userId`	string	Your customer ID.

PaymentMethodDataDto¶

Name	Type	Description
`brand`	string
`hash`	string
`masked`	string
`method`	string
`token`	string \| null
`type`	string

ProcessingResultDto¶

RedirectDto¶

Name	Type	Description
`session_id`	string
`transaction_id`	string
`url`	string

TransactionExecuteRequestDto¶

Name	Type	Description
`amount`	integer(int64)	Transaction amount in minor units (groszy for PLN).
`cancel_url`	string	URL to redirect to if the transaction is canceled.
`currency`	string	Currency code (PLN only for BLIK).
`description`	string	Transaction description.
`error_url`	string	URL to redirect to on error.
`metadata`		Additional metadata for the transaction.
`payment_method`	Properties: `type, data`
`reference`	string	Unique transaction reference.
`return_url`	string	URL to redirect to after successful processing.
`terminal_id`	string	Terminal identifier.
`transaction_type`	string	Type of transaction (only PURCHASE supported).

TransactionStatus¶

Type: string

TransactionStatusResponse¶

Name	Type	Description
`found`	boolean	Whether the transaction was found
`transaction`	ExtendedTransactionDto	Transaction details if found

Security schemes¶

Name	Type	Scheme	Description
bearerAuth	http	bearer