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 in E.164 format (e.g., `+12125551234`). Validated using Google libphonenumber `isPossibleNumber` — the number must be a plausible length for its 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

Response 200 OK

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"
        }
    }
}

Response 404 Not 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"
}

⚠️ 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 the transaction completes (approved, declined, canceled, or error)."
        }
    },
    "required": [
        "reference",
        "terminal_id",
        "description",
        "currency",
        "amount",
        "transaction_type",
        "payment_method",
        "return_url"
    ]
}

Response 200 OK

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."
}

Response 422 Unprocessable Entity

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
`payment_data`	string
`session_id`	string
`token`	string
`transaction_id`	string
`type`	string

ExecuteTransactionResponseDto¶

Name	Type
`action`	ActionRequiredDto
`form_submit`	FormSubmitDto
`redirect`	RedirectDto
`result`	ExtendedTransactionDto

ExtendedTransactionDto¶

Name	Type
`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
`data`
`session_id`	string
`transaction_id`	string
`url`	string

NeogatedCallbackDto¶

Name	Type
`accountReference`	string
`amount`	number(decimal)
`currency`	string
`psTransactionId`	string
`status`	string
`transactionId`	string
`type`	string
`userId`	string

PaymentMethodDataDto¶

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

ProcessingResultDto¶

RedirectDto¶

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

TransactionExecuteRequestDto¶

Name	Type
`amount`	integer(int64)
`currency`	string
`description`	string
`metadata`
`payment_method`	Properties: `type, data`
`reference`	string
`return_url`	string
`terminal_id`	string
`transaction_type`	string

TransactionStatus¶

Type: string

TransactionStatusResponse¶

Name	Type
`found`	boolean
`transaction`	ExtendedTransactionDto

Security schemes¶

Name	Type	Scheme	Description
bearerAuth	http	bearer