openapi: 3.1.0
info:
title: Technical documentation for integration with the Axepta transactional system.
version: 1.0.1
# --- --- --- --- INTRODUCTION
description: |
# The documentation contains information about the RESTful API of the Axepta payment system.
Communication is carried out by exchanging information saved in JSON format.
Each request should include an appropriate authorization method.
Each valid address consists of three parts:
- the base request address `https://api.axepta.pl/v1`,
- the client identifier `/merchant/{merchantId}`,
- a function that uniquely defines the scope of data the request concerns (e.g. `/transaction` or `/payment`).
Each request to the server should include authorization data in the headers (**Authorization token**).
> Integration data is available in the [Axepta administration panel](https://axepta.bnpparibas.pl/)
# --- --- --- --- CONTACT
contact:
name: Technical support
email: wsparcie@axepta.pl
# --- --- --- --- EXTERNAL LINKS
x-externalLinks:
- label: Axepta.pl
url: https://axepta.pl/
# --- --- --- --- SERVERS
servers:
- url: https://api.axepta.pl/v1
description: Production server.
- url: https://api.sandbox.axepta.pl/v1
description: Sandbox - test server.
# --- --- --- --- SECURITY
security:
- "Authorization token": []
# --- --- --- --- TAGS
tags:
- name: transaction
description: |
Transaction operations
- name: payment-link
description: |
Payment link operations
- name: refund
description: |
Refund-related operations
- name: profile
description: |
Managing an existing profile
- name: paymentId
description: |
X
# --- --- --- --- COMPONENTS
components:
securitySchemes:
"Authorization token":
type: http
scheme: bearer
bearerFormat: http
# example: rfnqddfumcjcuwrrbzqdgtgj4kbifau5s0n026d43tniao7nfwyu1a5gmg78akl3
schemas:
payment-link:
type: object
required: [ serviceId, amount, currency, orderId, customer ]
properties:
serviceId:
type: string
example: 000eec9b-7248-4dae-98f2-56aab6a53927
maxLength: 36
format: uuid
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
description: |
Store identifier as `UUID v4`
amount:
type: integer
description: |
Transaction amount in the smallest currency unit, e.g. **grosz**
currency:
type: string
maxLength: 3
enum: [ PLN, EUR ]
description: |
Transaction currency in `ISO 4217` format
orderId:
type: string
maxLength: 100
pattern: "^[A-Za-z0-9#_\\-\\.\\/ \\u00C0-\\u02C0]+$"
description: |
Merchant order number,
**allowed characters**: A-Za-z0-9#_-.\/ plus space (0x20) and UNICODE range 00C0 - 02C0 (incl. Polish diacritics)
title:
type: string
maxLength: 255
pattern: "^[A-Za-z0-9#_\\-\\.\\/ \\u00C0-\\u02C0]+$"
description: |
Order title, allowed characters: A-Za-z0-9#&_-"',./ plus space (0x20) and UNICODE range 00C0 - 02C0 (incl. Polish diacritics).
customer:
type: object
required: [ firstName, lastName, email ]
properties:
firstName:
type: string
maxLength: 100
pattern: "^[A-Za-z0-9#_\\-\\.\\/ \\u00C0-\\u02C0\\u0400-\\u04FF]+$"
description: |
Customer first name,
**allowed characters**: A-Za-z0-9#&_-"',.\/ plus space (0x20) and UNICODE range 00C0 - 02C0 (incl. Polish diacritics), 0400 - 04FF (Cyrillic)
lastName:
type: string
maxLength: 100
pattern: "^[A-Za-z0-9#_\\-\\,\\.\\\\\\\\/ \\u00C0-\\u02C0\\u0400-\\u04FF\"']+$"
description: |
Customer last name,
**allowed characters**: A-Za-z0-9#&_-"',.\/ plus space (0x20) and UNICODE range 00C0 - 02C0 (incl. Polish diacritics), 0400 - 04FF (Cyrillic)
email:
type: string
maxLength: 200
format: email
description: |
E-mail address in a format compliant with `RFC 5322` and `RFC 6531`
phone:
type: string
maxLength: 20
pattern: "^[0-9\\+\\- ]+$"
description: |
Phone number,
**allowed characters**: 0-9+- and space (0x20)
cid:
type: string
maxLength: 36
pattern: "^[A-Za-z0-9\\x2D]+$"
description: |
Customer identifier. (Required for `oneclick`, `recurring` payments),
**allowed characters**: A-Za-z0-9 and hyphen (0x2D)
returnUrl:
type: string
maxLength: 300
format: uri
description: |
Return URL from the external payment page if the transaction status is not resolved
successReturnUrl:
type: string
maxLength: 300
format: uri
description: |
Return URL from the external payment page after a successful payment
failureReturnUrl:
type: string
maxLength: 300
format: uri
description: |
Return URL from the external payment page in case of a payment error
visibleMethod:
type: array
description: |
Visibility of payment methods; by default, all methods available for the store are visible.
[Description in section 5.3 Payment methods visibility](https://bump.sh/pgw/doc/axepta-api/topic/topic-5-3-widocznosc-metod-platnosci)
paywall.forceCardChannel:
type: string
description: |
Force card payment mode. Allows initializing a card payment in profile-saving mode.
Available values: ecom3ds, oneclick, recurring. When using oneclick or recurring, customer.cid is required.
activeTo:
type: integer, null
description: |
Transaction expiration date as a Unix timestamp in seconds (seconds since 1970-01-01 UTC)
(value must be >= 1 and <= 4294967295). If not provided or null, the transaction is valid indefinitely.
Not completing the payment by this time will cancel it.
distributor:
type: string
description: |
Distributor name, allowed value: "shoper".
surcharge:
type: boolean
description: |
Flag determining whether payer charging will be used for the given order.
Allowed values: 'true', 'false' (requires surcharge flag enabled during onboarding).
deactivate-profile:
# Deactivates a profile
type: object
required: [ paymentProfileId ]
properties:
paymentId:
type: string
maxLength: 36
format: uuid
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
description: |
Profile identifier as `UUID v4`
transactionId:
# Retrieves transaction data
type: object
required: [ paymentId ]
properties:
paymentId:
type: string
example: 805f9c2c-e7ee-4606-b201-ee09032c49b0
maxLength: 36
format: uuid
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
description: |
Unique transaction identifier (UUID v4)
cancel:
# Cancels a payment
type: object
required: [ serviceId, paymentId ]
properties:
serviceId:
type: string
example: 000eec9b-7248-4dae-98f2-56aab6a53927
maxLength: 36
format: uuid
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
description: |
Store identifier as `UUID v4`
paymentId:
type: string
example: 805f9c2c-e7ee-4606-b201-ee09032c49b0
maxLength: 36
format: uuid
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
description: |
Payment link identifier
refund:
# Refund
type: object
required: [ type, serviceId, amount ]
properties:
type:
type: string
enum: [ refund ]
description: |
Action type
serviceId:
type: string
maxLength: 36
format: uuid
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
description: |
Store identifier as `UUID v4`
amount:
type: integer
description: |
Transaction amount in the smallest currency unit, e.g. **grosz**
transaction:
type: object
required: [ type, serviceId, clientIp, amount, currency, orderId, paymentMethod, paymentMethodChannel, customer, successReturnUrl, failureReturnUrl ]
properties:
type:
type: string
enum: [ sale ]
example: sale
description: |
Transaction type. Allowed values: sale
serviceId:
type: string
maxLength: 36
format: uuid
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
description: |
Store identifier as `UUID v4`
amount:
type: integer
description: |
Transaction amount in the smallest currency unit, e.g. **grosz**
currency:
type: string
maxLength: 3
enum: [ PLN, EUR ]
description: |
Transaction currency in `ISO 4217` format
orderId:
type: string
maxLength: 100
pattern: "^[A-Za-z0-9#_\\-\\.\\/ \\u00C0-\\u02C0]+$"
description: |
Merchant order number; allowed characters: A-Za-z0-9#_-./ plus space (0x20) and UNICODE range 00C0 - 02C0 (incl. Polish diacritics)
title:
type: string
maxLength: 255
pattern: "^[A-Za-z0-9#_\\-\\.\\/ \\u00C0-\\u02C0]+$"
description: |
Transaction title; allowed characters: A-Za-z0-9#&_-"',./ plus space (0x20) and UNICODE range 00C0 - 02C0 (incl. Polish diacritics)
paymentMethod:
type: string
description: |
Method used to process the order. More information in section [1.4 Transaction methods and channels]
paymentMethodChannel:
type: string
description: |
Payment channel designation. More information in section [1.4 Transaction methods and channels]
successReturnUrl:
type: string
maxLength: 300
format: uri
description: |
Return URL from the external payment page after a successful payment
failureReturnUrl:
type: string
maxLength: 300
format: uri
description: |
Return URL from the external payment page in case of a payment error
returnUrl:
type: string
maxLength: 300
format: uri
description: |
Default return URL.
clientIp:
type: string
format: ipv4, ipv6
description: |
The payer's real IP address provided in `IPv4` or `IPv6`. Required when providing [blikCode](#operation-post-parameter-transaction-body-application-json-blikCode).
activeTo:
type: integer, null
description: |
Transaction expiration date as a Unix timestamp in seconds (seconds since 1970-01-01 UTC)
(value must be >= 1 and <= 4294967295). If not provided or null, the transaction is valid indefinitely.
Not completing the payment by this time will cancel it.
blikCode:
type: integer
maxLength: 6
description: |
BLIK code value for transactions where the code is provided via API.
distributor:
type: string
description: |
Distributor name, allowed value: "shoper".
customer:
type: object
required: [ firstName, lastName, email ]
properties:
firstName:
type: string
maxLength: 100
description: |
Customer first name,
**allowed characters**: A-Za-z0-9#&_-"',.\/ plus space (0x20) and UNICODE range 00C0 - 02C0 (incl. Polish diacritics), 0400 - 04FF (Cyrillic)
lastName:
type: string
maxLength: 100
description: |
Customer last name,
**allowed characters**: A-Za-z0-9#&_-"',.\/ plus space (0x20) and UNICODE range 00C0 - 02C0 (incl. Polish diacritics), 0400 - 04FF (Cyrillic)
email:
type: string
maxLength: 200
format: email
description: |
E-mail address in a format compliant with `RFC 5322` and `RFC 6531`
phone:
type: string
maxLength: 20
pattern: "^[0-9\\+\\- ]+$"
description: |
Phone number,
**allowed characters**: 0-9+- and space (0x20)
cid:
type: string
maxLength: 36
pattern: "^[A-Za-z0-9\\x2D]+$"
description: |
Customer/payer identifier assigned by the merchant; allowed characters: A-Za-z0-9 and hyphen (0x2D)
locale:
type: string
description: |
Payer locale; determines the language of the e-mail informing that the payment process has started; allowed values: pl, en.
card:
type: object
required: [ firstName, lastName, number, month, year, cvv ]
description: |
Card payment data. (Required for card payments)
properties:
firstName:
type: string
maxLength: 100
description: |
Cardholder first name; allowed characters: A-Za-z0-9#&_-"',./ plus space (0x20) and UNICODE range 00C0 - 02C0 (incl. Polish diacritics)
lastName:
type: string
maxLength: 100
description: |
Cardholder last name; allowed characters: A-Za-z0-9#&_-"',./ plus space (0x20) and UNICODE range 00C0 - 02C0 (incl. Polish diacritics)
number:
type: string
maxLength: 16
description: Card number
month:
type: string
maxLength: 2
description: Card expiry - month
year:
type: string
maxLength: 4
description: Card expiry - year
cvv:
type: string
maxLength: 4
description: Card CVV code
additionalData:
type: object
description: |
Payer browser information required when performing card payments with 3DS authorization.
report:
type: object
required: [ uuid, taskName, type, status, settings ]
properties:
uuid:
type: string
description: |
Report UUID
plannedReportUuid:
type: string
description: |
UUID of the scheduled report (if the report was generated from a scheduled report). It will be `null` for one-time reports.
taskName:
type: string
description: |
Report task type
type:
type: string
description: |
Report type
status:
type: string
description: |
Report status
settings:
type: object
description: |
Report settings
generatedAt:
type: number
description: |
Report generation timestamp
# --- --- --- --- PATHS --- --- --- --- ENDPOINTS
paths:
/merchant/{merchantId}/transaction:
post:
tags: [ transaction ]
summary: Create a transaction
description: |
In accordance with PCI DSS requirements (set by payment organizations), processing, transmitting, or storing card numbers and other card data is prohibited.
If you have a valid PCI DSS certificate and want to provide a card payment form on your store website - please contact Axepta support.
If you redirect directly to the Axepta card payment form, this is not required.
parameters:
- in: path
name: merchantId
schema:
type: string
description: Client identifier
required: true
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/transaction"
example:
type: sale
serviceId: a3a5b7ad-ab73-46f0-97f2-3238f8bd450d
amount: 100
currency: PLN
title: Title 123
orderId: 123-123
paymentMethod: blik
paymentMethodChannel: blik
successReturnUrl: hhttps://domain.com/success
failureReturnUrl: https://domain.com/failure
customer:
firstName: Jan
lastName: Kowalski
phone: 48512512512
email: jan.kowalski@example.com
/merchant/{merchantId}/transaction/{transactionId}:
get:
tags: [ transaction ]
summary: Retrieve transaction data
description: |
Retrieve transaction data
parameters:
- in: path
name: merchantId
required: true
schema:
type: string
description: Client identifier
example: 000eec9b-7248-4dae-98f2-56aab6a53927
- in: path
name: transactionId
schema:
type: string
maxLength: 36
format: uuid
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
description: Unique transaction identifier (UUID v4),
required: true
example: 805f9c2c-e7ee-4606-b201-ee09032c49b0
/merchant/{merchantId}/profile/cid/{cid}:
get:
tags: [ profile ]
summary: Retrieve profile by cid
parameters:
- in: path
name: merchantId
schema:
type: string
description: Client identifier
required: true
- in: path
name: cid
required: true
schema:
type: string
maxLength: 36
pattern: "^[A-Za-z0-9\\x2D]+$"
description: Payer identifier assigned by the merchant.
/merchant/{merchantId}/profile/id/{paymentProfileId}:
parameters:
- in: path
name: merchantId
schema:
type: string
description: Client identifier
required: true
- in: path
name: paymentProfileId
required: true
schema:
type: string
maxLength: 36
pattern: "^[A-Za-z0-9\\x2D]+$"
description: Card profile identifier,
get:
tags: [ profile ]
summary: Retrieve card profile by id
delete:
tags: [ profile ]
summary: Deactivate card profile by id.
description: Deactivate OneClick or recurring profile for the given paymentProfileId.
/merchant/{merchantId}/profile/deactivate:
post:
tags: [ profile ]
summary: Deactivates the profile with the identifier provided in the request
parameters:
- in: path
name: merchantId
schema:
type: string
description: Client identifier
required: true
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/deactivate-profile"
example:
paymentProfileId: 000eec9b-7248-4dae-98f2-56aab6a53927
/merchant/{merchantId}/payment-link:
post:
tags: [ payment-link ]
summary: Create a payment link order
description: ""
parameters:
- in: path
name: merchantId
schema:
type: string
description: Client identifier
required: true
example: 3hqitucfo8jh5kqlp7s6
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/payment-link"
example:
serviceId: a3a5b7ad-ab73-46f0-97f2-3238f8bd450d
amount: 3000
currency: PLN
orderId: 123
returnUrl: https://domain.com/return
successReturnUrl: https://domain.com/success
failureReturnUrl: https://domain.com/failure
notificationUrl: https://domain.com/notification
customer:
firstName: Jan
lastName: Kowalski
email: jan.kowalski@example.com
/merchant/{merchantId}/payment/{paymentId}:
get:
tags: [ payment-link ]
summary: Retrieve payment data
parameters:
- in: path
name: merchantId
schema:
type: string
description: Client identifier
required: true
- in: path
name: paymentId
schema:
type: string
description: Unique identifier of the payment the refund relates to.
required: true
/merchant/{merchantId}/payment/{paymentId}/refund:
post:
tags: [ refund ]
summary: Perform a payment refund
parameters:
- in: path
name: merchantId
schema:
type: string
description: Client identifier
required: true
- in: path
name: paymentId
required: true
schema:
type: string
maxLength: 36
format: uuid
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
description: |
Transaction identifier as `UUID v4`
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/refund"
example:
type: refund
serviceId: 000eec9b-7248-4dae-98f2-56aab6a53927
amount: 100
/merchant/{merchantId}/payment/cancel:
post:
tags: [ payment-link ]
summary: Cancel a payment link
parameters:
- in: path
name: merchantId
schema:
type: string
description: Client identifier
required: true
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/cancel"
example:
type: cancel
serviceId: 000eec9b-7248-4dae-98f2-56aab6a53927
paymentId: 805f9c2c-e7ee-4606-b201-ee09032c49b0
x-topics:
# --- --- --- --- 1. Statuses
- title: 1.1. Transaction statuses (transaction).
content: |
Transactions and payment links can have the following statuses:
| Status | Description |
|--------------|-----------------------------------------------------|
| `new` | New, not processed transaction |
| `pending` | Waiting for status |
| `rejected` | Transaction rejected |
| `settled` | Transaction completed |
| `error` | Transaction error |
| `cancelled` | Transaction cancelled |
- title: 1.2. Payment link order statuses - (payment).
content: |
# Payment link order statuses - (payment).
Orders can have the following statuses:
| Status | Description |
|--------------|-----------------------------------------------------|
| `new` | New, not processed order |
| `pending` | Waiting for status |
| `rejected` | Order rejected |
| `settled` | Order completed |
| `error` | Order error |
| `cancelled` | Order cancelled |
- title: 1.3. Authorization methods.
content: |
Request headers (authorization methods)
The integration supports authorization with an authorization token.
The token can be found in the [Axepta administration panel](https://axepta.bnpparibas.pl/), under `Settings` and then the `API Keys` tab.
To authorize a request, include the authorization data in the server request headers:
```
Accept: application/json
Content-Type: application/json
Authorization: Bearer {token}
```
HTTP response codes:
| HTTP code | Meaning |
|----------|------------------------------------------------------------------------|
| `200` | Authorization correct |
| `401` | Unauthorized access; request to a resource that requires authentication |
| `500` | Server error |
> Example request header
```
Accept: application/json
Content-Type: application/json
Authorization: Bearer ad8y3hdoashco8fh49fhiahfb237f8hoihsd0f2hfikljf023h8
```
- title: 1.4. Transaction processing methods and channels
content: |
Transactions can be processed using the following methods:
| Name | `paymentMethod` value | `paymentMethodChannel` value |
|------------------|------------------------|------------------------------|
| Online transfers | `pbl` | Table below |
| Card payment | `card` | Table below |
| BLIK payment | `blik` | `blik` |
- title: 1.4.1. Pay By Link online transfer
content: |
Pay By Link transfers can be processed using the following bank services:
| Parameter value | Service name |
|---------------------|-------------------------------------------------|
| `bnpparibas` | Pay with BNP Paribas (GOonline) |
| `bnpparibascorpo` | Pay with BNP Paribas (GOonline Biznes) |
| `mtransfer` | mTransfer - mBank |
| `bzwbk` | Przelew24 - Erste |
| `pekao24` | Pekao24Przelew - Bank Pekao |
| `inteligo` | Pay with Inteligo |
| `ing` | Pay with ING |
| `ipko` | Pay with iPKO |
| `getin` | Pay with Velo Bank |
| `creditagricole` | Credit Agricole e-transfer |
| `alior` | Pay with Alior Bank |
| `pbs` | Bank Nowy BFG |
| `millennium` | Millennium - online payments |
| `citi` | Transfer from Citi Handlowy |
| `bos` | Pay with BOŚ |
| `pocztowy` | Pocztowy24 |
| `plusbank` | Pay with Plus Bank |
| `bs` | Bank Spółdzielczy |
| `bspb` | Bank Spółdzielczy in Brodnica |
| `nest` | nestPrzelew |
- title: 1.4.2. Card payment.
content: |
Card payments can be processed using the following services:
| Parameter value | Service name |
|----------------|-----------------------------------|
| `ecom3ds` | 3DS card payment |
| `oneclick` | Payment using `oneclick` service |
| `recurring` | Payment using `recurring` service |
| `click2pay` | Payment using `click2pay` |
- title: 1.4.3. BLIK payment.
content: |
BLIK payments can be processed using the following services:
| Parameter Value 'paymentMethod' | Parameter Value 'paymentMethodChannel' |
|------------------------------------------|--------------------------------------------|
| 'blik' | 'blik' |
>Creating a transaction with the additional parameter 'blikCode' will result in sending the code to BLIK
| Parameter | Description |
|---------------------------------|--------------------------------------------|
| 'blikCode' | integer(6), acceptable characters: 0-9 |
# --- --- --- --- 2. Endpoints
- title: 2. RESTful API methods
content: |
**Production URL:** `https://api.axepta.pl`
**Sandbox URL:** `https://api.sandbox.axepta.pl`
| Endpoint | Purpose | Method |
|----------|---------|--------|
| `/{merchantId}/transaction` | Creates a new transaction | `POST` |
| `/{merchantId}/transaction/{transactionId}` | Retrieves transaction data | `GET` |
| `/{merchantId}/payment-link` | Creates a new payment link | `POST` |
| `/{merchantId}/payment/{paymentId}/refund` | Performs a payment refund | `POST` |
| `/{merchantId}/payment/{paymentId}` | Retrieves payment data | `GET` |
| `/{merchantId}/transaction/profile` | Charges an existing card profile | `POST` |
| `/{merchantId}/profile/cid/{cid}` | Retrieves profiles for the given `cid` | `GET` |
| `/{merchantId}/profile/id/{paymentProfileId}` | Retrieves profile by `id` | `GET` |
| `/{merchantId}/profile/deactivate` | Deactivates the profile with the identifier from the request| `POST` |
| `/{merchantId}/profile/id/{paymentProfileId}` | Deactivates the profile with the given `paymentProfileId` | `DELETE` |
| `/{merchantId}/payment/cancel` | Cancels a payment link | `POST` |
where:
- `merchantId` - client identifier,
- `serviceId` - store identifier for which specific transaction methods are available (UUID v4),
- `cid` - customer/payer identifier assigned by the merchant,
- `transactionId` - unique transaction identifier (UUID v4),
- `paymentProfileId` - card profile identifier,
- `paymentId` - unique payment link identifier (UUID v4).
# --- --- --- --- 3. Transactions
- title: 3. Creating a new transaction via API
content: |
> In accordance with PCI DSS requirements (set by payment organizations), processing, transmitting, or storing card numbers and other card data is prohibited.
> If you have a valid PCI DSS certificate and want to provide a card payment form on your store website - please contact Axepta support.
If you redirect directly to the Axepta card payment form, this is not required.
To create a new transaction, send a `POST` request containing information about the new order to the API endpoint:
```
https://api.axepta.pl/v1/merchant/{merchantId}/transaction
```
where:
- `merchantId` - client identifier.
- title: 3.1. HTTP Request transaction API
content: |
### Example URL to send the POST request to
```
https://api.axepta.pl/v1/merchant/6yt3gjtm9p7b8h9xsdqz/transaction
```
### Request payload
```json
{
"type": "sale",
"serviceId": "62f574ed-d4ad-4a7e-9981-89ed7284aaba",
"amount": 9900,
"currency": "PLN",
"orderId": "12",
"clientIp": "192.168.10.2",
"paymentMethod": "pbl",
"paymentMethodChannel": "bnpparibas",
"successReturnUrl": "https://domain.com/success",
"failureReturnUrl": "https://domain.com/failure",
"customer": {
"firstName": "Maciej",
"lastName": "Kowalski",
"email": "jan.kowalski@example.com"
}
}
```
### Payload parameters
| Parameter | Type | Required | Description |
|---------------------|-----------------------|----------|-------------|
| `type` | string | ✔️ | Transaction type.
**Allowed values**: `sale`. |
| `serviceId` | string(36) | ✔️ | Store identifier as UUID v4. |
| `clientIp` | string | ✔️ | Client IP address in IPv4 or IPv6 format. |
| `amount` | integer(1-999999999) | ✔️ | Transaction amount in the smallest currency unit, e.g. grosz. |
| `currency` | string(3) | ✔️ | Transaction currency in ISO 4217 format. |
| `orderId` | string(100) | ✔️ | Merchant order number;
**allowed characters**: A-Za-z0-9#_-.\/ plus space (0x20) and UNICODE range 00C0 - 02C0. |
| `title` | string(255) | - | Transaction title;
**allowed characters**: A-Za-z0-9#&_-"',.\/ plus space (0x20) and UNICODE range 00C0 - 02C0. |
| `paymentMethod` | string | ✔️ | Order processing method. More information in section [1.4 Transaction methods and channels]. |
| `paymentMethodChannel` | string | ✔️ | Payment channel. More information in section [1.4 Transaction methods and channels]. |
| `successReturnUrl` | string(300) | ✔️ | Return URL after successful payment. |
| `failureReturnUrl` | string(300) | ✔️ | Return URL in case of payment error. |
| `returnUrl` | string(300) | ✔️ | Default return URL. |
| `customer` | object | ✔️ | Customer data. |
| `billing` | object | - | Payer data. |
| `shipping` | object | - | Delivery data. |
| `card` | object | - | Card payment data. (Required for `card` payments) |
| `additionalData` | object | - | Payer browser information required for card payments with 3DS authorization. |
| `activeTo` | integer, null | - | Transaction expiration date as Unix timestamp (seconds). If not provided or null, transaction is valid indefinitely. |
| `distributor` | string | - | Distributor name, allowed value: "shoper". |
| `surcharge` | boolean | - | Flag determining whether payer charging will be used for the transaction. Allowed values: 'true', 'false' (requires onboarding setting). |
| `blikCode` | integer(6) | - | BLIK code value for transactions where the code is provided via API. |
> If the request contains `billing`, `shipping` or `card`, additional parameters described below are required.
#### customer
| Parameter | Type | Required | Description |
|-------------|--------------|----------|-------------|
| `firstName` | string(100) | ✔️ | Customer first name; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters)|
| `lastName` | string(100) | ✔️ | Customer last name; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `cid` | string(36) | - | Customer/payer identifier assigned by merchant; allowed characters: A-Za-z0-9 and hyphen (0x2D). |
| `phone` | string(20) | - | Phone number; allowed characters: 0-9+- and space (0x20). |
| `email` | string(200) | ✔️ | Email address. |
| `locale` | string(2) | - | Payer locale; determines email language; **allowed values**: `pl`, `en`. |
The default email language is Polish for PLN transactions and English for other currencies.
#### billing
| Parameter | Type | Required | Description |
|---------------------|--------------|----------|-------------|
| `firstName` | string(100) | ✔️ | First name; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `lastName` | string(100) | ✔️ | Last name; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `company` | string(200) | - | Company name; allowed characters: A-Za-z0-9-"'/,. plus space and UNICODE 00C0 - 02C0 (including Polish diacritical characters)|
| `street` | string(200) | - | Street; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `city` | string(100) | - | City; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `region` | string(100) | - | Region; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `postalCode` | string(30) | - | Postal code; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `countryCodeAlpha2` | string(2) | - | Country code Alpha2. |
#### shipping
| Parameter | Type | Required | Description |
|---------------------|--------------|----------|-------------|
| `firstName` | string(100) | ✔️ | First name; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `lastName` | string(100) | ✔️ | Last name; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `company` | string(200) | - | Company name; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters). |
| `street` | string(200) | - | Street; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `city` | string(100) | - | City; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `region` | string(100) | - | Region; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `postalCode` | string(30) | - | Postal code; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `countryCodeAlpha2` | string(2) | - | Country code Alpha2. |
#### card
| Parameter | Type | Required | Description |
|------------|-------------|----------|-------------|
| `firstName`| string(100) | ✔️ | Cardholder first name; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `lastName` | string(100) | ✔️ | Cardholder last name; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `number` | string(16) | ✔️ | Card number |
| `month` | string(2) | ✔️ | Expiry month |
| `year` | string(4) | ✔️ | Expiry year |
| `cvv` | string(4) | ✔️ | CVV code |
- title: 3.2. Browser data
content: |
When generating a card payment that requires 3D Secure authorization, information about the payer's browser must be collected and passed in an additional `additionalData` object.
The structure is as follows:
| Parameter | Type | Required | Description |
|---------------------|----------|----------|-------------|
|`browser` | object | ✔️ | Information about the payer's browser |
|`browser.ip` | string | ✔️ | IP address. Allowed values: "ipv4", "ipv6" |
|`browser.language` | string | ✔️ | Browser language specified in UNICODE format, e.g. "pl-PL" |
|`browser.jsEnabled` | boolean | ✔️ | Specifies whether JavaScript support is enabled in the browser |
|`browser.timezoneOffset`| integer | ✔️ | Time-zone offset value between UTC and the cardholder browser's local time, in minutes. |
|`browser.userAgent` | string | ✔️ | Information about the client application used |
|`browser.accept` | string | ✔️ | Exact contents of the HTTP accept headers, MIME type |
|`browser.javaEnabled`| boolean | ✔️ | Specifies whether Java support is enabled in the browser |
|`browser.screenColorDepth`| integer | ✔️ | Color depth bit value for image display in bits per pixel, obtained from the cardholder browser, range: 1-48 bits |
|`browser.screenHeight`| integer | ✔️ | Browser window height in px |
|`browser.screenWidth`| integer | ✔️ | Browser window width in px |
#### Example of the object being passed
```json
"additionalData": {
"browser": {
"ip": "127.0.0.1",
"language": "pl-PL",
"jsEnabled": true,
"timezoneOffset": 100,
"userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome 87.0.4280.66 Safari/537.36",
"accept": "application/json, text/javascript, */*; q=0.01",
"javaEnabled": false,
"screenColorDepth": 24,
"screenHeight": 1080,
"screenWidth": 2560
}
}
```
- title: 3.3. HTTP Response
content: |
### Server response
If the request registering a new order is successful, the server will respond with HTTP status `200` and information about the newly created transaction:
```json
{
"status": "SUCCESS",
"data": {
"transaction": {
"id": "21090680-8938-467b-a53e-a68862356e2e",
"type": "sale",
"status": "pending",
"source": "api",
"createdAt": 1688379004,
"modifiedAt": 1688379004,
"notificationUrl": "https://1234.requestcatcher.com/",
"serviceId": "3283bb82-1203-4064-86ad-27868f985769",
"amount": 10000,
"currency": "PLN",
"orderId": "1",
"paymentMethod": "pbl",
"paymentMethodChannel": "ing",
"payment": {
"id": "8254d179-9063-47a2-adb4-5d8322679378",
"status": "new"
}
},
"action": {
"type": "redirect",
"url": "https://paywall.sandbox.axepta.pl/sandbox/8254d179-9063-47a2-
adb4-5d8322679378/21090680-8938-467b-a53e-a68862356e2e",
"method": "GET",
"contentType": "",
"contentBodyRaw": ""
},
"omG": "G9q"
}
}
```
The response includes the following objects: `transaction` and `action`.
The `transaction` object is identical to the one sent in the order registration request and contains several additional parameters:
| Parameter | Type | Description |
|------------|---------|-------------|
| `id` | string | Transaction identifier in UUID v4 format. Unique for each order. |
| `status` | string | Order status. |
| `source` | string | Order source. It can have the following values: `api` or `web`. |
| `createdAt` | integer | Order creation date in UNIX TIMESTAMP UTC format. |
| `notificationUrl` | string | Notification address |
| `modifiedAt` | integer | Date of the last transaction status change in UNIX TIMESTAMP UTC format. |
| `payment` | object | Payment data to which the transaction is assigned |
The second additional object is `action`. This object appears only if the payer must be redirected to an external page, as in the case of a `Pay-By-Link` payment.
This object contains additional fields whose meaning is described below:
| Parameter | Type | Description |
|-----------------|--------|-------------|
| `type` | string | Action type. |
| `url` | string | URL address in the event that the payer must be redirected to another page (e.g. a bank page). |
| `method` | string | POST or GET method. |
| `contentType` | string | Entry in the bank request header specifying the payload type. |
| `contentBodyRaw`| string | Request payload. |
### HTTP statuses
| HTTP Code | Meaning |
|----------|---------|
| `200` | Request completed successfully. Transaction created |
| `400` | Bad request, invalid request payload. |
| `401` | Unauthorized access. Request for a resource that requires authentication. |
| `403` | No permission to perform the request. |
| `404` | Unknown resource. |
| `422` | Payload is correct but does not contain the required parameters. |
| `500` | Server error. |
| `503` | System unavailable. |
- title: 3.4 Multipayouts
content: |
This option is available when the multipayout feature is enabled. Only for accounts at BNP Paribas Bank.
Transactions are performed according to the description in point 3.1, with one additional parameter in the `data.multipayout[]` object:
| Parameter | Type | Required | Description |
|-----------|-------------------------|----------|-------------|
| `iban` | string | ✔️ | Bank account number |
| `amount` | integer(1-999999999) | ✔️ | Transaction amount in the smallest currency unit, e.g. grosz. |
| `label` | string | ✔️ | Recipient name (max 35 characters), *Allowed characters*: A-Za-z0-9-"',. as well as the space character (0x20) and characters in the UNICODE range 00C0 - 02C0 (including Polish diacritical characters), |
| `title` | string | - | Transfer title (max 105 characters), *Allowed characters*: A-Za-z0-9#&_-"',.\/ as well as the space character (0x20) and characters in the UNICODE range 00C0 - 02C0 (including Polish diacritical characters), optional parameter. Its presence causes the given transaction to be separated on the recipient's account. *Important:* Providing this parameter for one element requires it to be provided for the others. |
> If the sum of the `amount` fields in the `multipayout` parameter is lower than the total order amount, the remaining funds will go to the default account of the store owner.
> The minimum and maximum transaction amount is given in the table in point [11. Minimum and maximum values of transaction and refund amounts].
#### Example request:
```json
{
"type": "sale",
"serviceId": "62f574ed-d4ad-4a7e-9981-89ed7284aaba",
"amount": 9900,
"currency": "PLN",
"orderId": "12",
"clientIp": "192.168.10.2",
"paymentMethod": "pbl",
"paymentMethodChannel": "bnpparibas",
"successReturnUrl": "https://domain.com/success",
"failureReturnUrl": "https://domain.com/failure",
"customer": {
"firstName": "Maciej",
"lastName": "Kowalski",
"email": "jan.kowalski@example.com"
},
"data": {
"multipayout": [
{
"iban": "PL55105000026800208114085773",
"amount": 100,
"label": "Company name 0"
},
{
"iban": "PL55105000026800208114085773",
"amount": 200,
"label": "Company name 1"
}
]
}
}
```
# --- --- --- --- 4. Refunds
- title: 4. Performing a refund
content: |
> When performing multiple refund transactions simultaneously, at least a 5-second delay should be introduced between consecutive transactions.
> The refund is performed for the highest-value transaction assigned to the given payment. This action can be performed before the payment is fully completed.
A refund is correctly performed by sending a POST request to the address:
```
https://api.axepta.pl/v1/merchant/{merchantId}/payment/{paymentId}/refund
```
where:
- `merchantId` - client identifier,
- `paymentId` - unique identifier of the payment to which the refund applies.
- title: 4.1 HTTP Request for performing a refund
content: |
### Example address to which the POST request should be sent
```
https://api.axepta.pl/v1/merchant/6yt3gjtm9p7b8h9xsdqz/payment/925767db-962a-49ee-916e-783de9b62a73/refund
```
### Request payload
```json
{
"type": "refund",
"serviceId": "000eec9b-7248-4dae-98f2-56aab6a53927",
"amount": 100
}
```
### Payload parameters
| Parameter | Type | Required | Description |
|---------------------|-------------------------|----------|-------------|
| `type` | string | ✔️ | Transaction type.
**Allowed values**: `refund`. |
| `serviceId` | string(36) | ✔️ | store identifier as UUID v4. |
| `amount` | integer(1-999999999) | ✔️ | Transaction amount in the smallest currency unit, e.g. grosz. |
- title: 4.2 HTTP Response
content: |
### Server response
If the refund is performed successfully, the server will respond with HTTP status `200`:
```json
{
"status": "SUCCESS",
"data": {
"paymentRefundId": "e6853cef-7d1b-409f-81c4-bab92e4fb75z",
"serviceId": "000eec9b-7248-4dae-98f2-56aab6a53927",
"paymentId": "925767db-962a-49ee-916e-783de9b62a73",
"amount": 100,
"amountRefunded": 0,
"status": "pending",
"transactions": [
{
"transaction": {
"id": "5023f30e-9909-41bd-a8a8-9cc9b161badf",
"type": "refund",
"status": "new",
"source": "api",
"createdAt": 1650024191,
"modifiedAt": 1650024191,
"serviceId": "000eec9b-7248-4dae-98f2-56aab6a53927",
"amount": 100,
"currency": "PLN",
"orderId": "1",
"paymentMethod": "blik",
"paymentMethodChannel": "blik",
"payment": {
"id": "925767db-962a-49ee-916e-783de9b62a73",
"status": "settled"
}
}
}
]
}
}
```
# --- --- --- --- 5. Orders
- title: 5. Creating a new payment link via API
content: |
To create a new payment link, a `POST` request containing information about the new payment link should be sent to the API endpoint:
```
https://api.axepta.pl/v1/merchant/{merchantId}/payment-link
```
where:
* `merchantId` - client identifier.
- title: 5.1. HTTP Request
content: |
### Example address to which the POST request should be sent
```
https://api.axepta.pl/v1/merchant/6yt3gjtm9p7b8h9xsdqz/payment-link
```
### Request payload
```json
{
"serviceId": "62f574ed-d4ad-4a7e-9981-89ed7284aaba",
"amount": 1000,
"currency": "PLN",
"orderId": "139",
"successReturnUrl": "https://domain.com/success",
"failureReturnUrl": "https://domain.com/failure",
"customer": {
"firstName": "Jan",
"lastName": "Kowalski",
"email": "jan.kowalski@example.com"
}
}
```
### Payload parameters
| Parameter | Type | Required | Description |
|---------------------|-------------------------|----------|-------------|
| `serviceId` | string(36) | ✔️ | store identifier as UUID v4. |
| `amount` | integer(1-999999999) | ✔️ | Transaction amount in the smallest currency unit, e.g. grosz. |
| `currency` | string(3) | ✔️ | Transaction currency in ISO 4217 format. |
| `orderID` | string(100) | ✔️ | Merchant order number,
**allowed characters**: A-Za-z0-9#_-.\/ as well as the space character (0x20) and characters in the UNICODE range 00C0 - 02C0 (including Polish diacritical characters) |
| `title` | string(255) | - | Order title,
**allowed characters**: A-Za-z0-9#&_-"',.\/ as well as the space character (0x20) and characters in the UNICODE range 00C0 - 02C0 (including Polish diacritical characters) |
| `returnUrl` | string(300) | - | Return address from the external payment handling page in the event the transaction status remains unresolved. |
| `successReturnUrl` | string(300) | - | Return address from the external payment handling page when the payment is completed successfully. |
| `failureReturnUrl` | string(300) | - | Return address from the external payment handling page when a payment error occurs. |
| `customer` | object | ✔️ | Customer data. |
| `activeTo` | integer, null | - | Transaction expiration date as a Unix timestamp in seconds (time measured in seconds since the start of 1970 UTC)
(**the value must be greater than or equal to 1 and less than or equal to 4294967295**). If it is not passed or is null, the transaction is always valid. Failure to complete the payment by that time will result in its cancellation. |
| `paywall.forceCardChannel` | string | - | Forces the card payment mode. Allows card payment initialization in card profile saving mode.
**Available values:** `ecom3ds`, `oneclick`, `recurring`. When using `oneclick` or `recurring`, the `customer.cid` parameter is required. |
| `distributor` | string | - | Distributor name, allowed value: "shoper". |
| `visibleMethod` | array | - | Visibility of payment methods; by default all methods available for the store are visible. Description in point 5.3 |
| `surcharge` | boolean | - | Flag determining whether payer surcharge will be used for the given order. Allowed values: 'true', 'false' (the surcharge flag must be enabled during the onboarding process). |
Parameters for `customer`:
| Parameter | Type | Required | Description |
|-------------|--------------|----------|-------------|
| `firstName` | string(100) | ✔️ | Customer first name,
**allowed characters**: A-Za-z0-9#&_-"',.\/ as well as the space character (0x20) and characters in the UNICODE range 00C0 - 02C0 (including Polish diacritical characters) |
| `lastName` | string(100) | ✔️ | Customer last name,
**allowed characters**: A-Za-z0-9#&_-"',.\/ as well as the space character (0x20) and characters in the UNICODE range 00C0 - 02C0 (including Polish diacritical characters) |
| `email` | string(200) | ✔️ | E-mail address. |
| `phone` | string(20) | - | Phone number,
**allowed characters**: 0-9+- and the space character (0x20). |
| `cid` | string(36) | - | Customer/payer identifier assigned by the merchant. (Required for oneclick and recurring payments),
**allowed characters**: A-Za-z0-9 and hyphen (0x2D) |
- title: 5.2. HTTP Response
content: |
### Server response
If the request registering a new payment link is successful, the server will respond with HTTP status `200` and information about the newly created payment link:
```json
{
"status": "SUCCESS",
"data": {
"paymentLink": {
"paymentId": "58b1c723-d99d-4fb3-a597-eaac08846a90",
"url": "https://paywall.int.axepta.pl/pay/58b1c723-d99d-4fb3-a597-eaac08846a90"
}
}
}
```
The response contains the `status` object indicating the success of the operation, and `data.paymentLink` with the following content:
| Parameter | Type | Description |
|------------|---------|-------------|
| `paymentId` | string | Payment identifier in UUID v4 format. Unique for each order. |
| `url` | string | Payment link URL. |
### HTTP statuses
| HTTP Code | Meaning |
|----------|---------|
| `200` | Request completed successfully. Transaction created |
| `400` | Bad request, invalid request payload. |
| `401` | Unauthorized access. Request for a resource that requires authentication. |
| `403` | No permission to perform the request. |
| `404` | Unknown resource. |
| `422` | Payload is correct but does not contain the required parameters. |
| `500` | Server error. |
| `503` | System unavailable. |
- title: 5.3. Payment method visibility
content: |
It is possible to declare which payment methods are visible on the gateway by using the additional `visibleMethod` parameter.
By default, all payment methods available for the store are visible.
| Value | Description |
|------------|-------------|
| `pbl` | Fast transfers |
| `blik` | Blik |
| `card` | Card payment |
| `wallet` | GooglePay and ApplePay wallet payment |
#### Structure example:
```json
"visibleMethod": [
"pbl",
"blik",
"card",
"wallet"
]
```
- title: 5.4. Multipayouts
content: |
This option is available when the multipayout feature is enabled.
The payment link is created according to the description in point 5, together with an additional `multipayout` parameter:
| Parameter | Type | Required | Description |
|-----------|-------------------------|----------|-------------|
| `iban` | string(28) | ✔️ | Bank account number |
| `amount` | integer(1-999999999) | ✔️ | Transaction amount in the smallest currency unit, e.g. grosz. |
| `label` | string(35) | ✔️ | Recipient name,
*Allowed characters*: A-Za-z0-9-"',. as well as the space character (0x20) and characters in the UNICODE range 00C0 - 02C0 (including Polish diacritical characters), |
| `title` | string(105) | - | Transfer title,
*Allowed characters*: A-Za-z0-9#&_-"',.\/ as well as the space character (0x20) and characters in the UNICODE range 00C0 - 02C0 (including Polish diacritical characters), optional parameter. Its presence causes the given transaction to be separated on the recipient's account.
**Important:** Providing this parameter for one element requires it to be provided for the others. |
#### Structure example:
```json
{
"multipayout": [
{
"iban": "PL55105000026800208114085773",
"amount": 100,
"label": "Company name 0"
},
{
"iban": "PL55105000026800208114085773",
"amount": 200,
"label": "Company name 1"
}
]
}
```
- title: 5.6. Cancelling a payment link
content: |
To cancel a created payment link, send a `POST` request to `https://api.axepta.pl/v1/merchant/{merchantId}/payment/cancel`
The request body should contain the following parameters:
| Name | Required parameter | Type | Description |
|-------------|--------------------|--------|-------------|
| `serviceId` | **Yes** | string | Store identifier |
| `paymentId` | **Yes** | string | Payment link identifier |
### Example request
```json
{
"serviceId": "000eec9b-7248-4dae-98f2-56aab6a53927",
"paymentId": "805f9c2c-e7ee-4606-b201-ee09032c49b0"
}
```
- title: 6. Notifications
content: |
To correctly configure sending transaction notifications to the store, enter the URL used for verification in the Axepta administration panel.
When a transaction status changes, Axepta servers send notifications to the URL indicated by the merchant.
The merchant’s server (e.g. the store) is required to respond with status `200 OK` and body `{"status":"ok"}`, which indicates that the notification has been correctly received and processed by the merchant’s server.\
Notifications are sent according to the following schedule:
* 3 times every second, then
* 5 times every 5 minutes, then
* 5 times every 60 minutes, then
* 5 times every 360 minutes, then
* 5 times every 720 minutes.
> If the merchant’s server returns status 200 OK, or if the notification is not received before the end of the retry cycle, Axepta servers stop retrying the notification delivery.
- title: 6.1. Notification BODY content
content: |
Notifications are sent as a `JSON` object via `POST` and have the following form:
```json
{
"payment": {
"id": "53a97f55-81af-46fa-921b-0a6eaf184c30",
"title": "43",
"amount": 100,
"status": "settled",
"created": 1689938459,
"orderId": "43",
"currency": "PLN",
"modified": 1689938483,
"serviceId": "3283bb82-1203-4064-86ad-27868f985769",
"notificationUrl": "https://domain.com/",
"amountPaid": 100,
"amountRefunded": 0,
"amountSubmittedRefund": 0,
"transactions": [
{
"id": "ab163b2e-0cf5-4478-a673-a1afb22c9535",
"type": "sale",
"status": "settled",
"source": "web",
"created": 1689938476,
"modified": 1689938483,
"notificationUrl": "https://domain.com/",
"serviceId": "3283bb82-1203-4064-86ad-27868f985769",
"amount": 100,
"currency": "PLN",
"title": "43",
"orderId": "43",
"paymentMethod": "blik",
"paymentMethodChannel": "blik"
}
],
"notifyTransactionData": {
"id": "ab163b2e-0cf5-4478-a673-a1afb22c9535",
"type": "sale"
}
}
}
```
A notification may consist of the following objects:
- `payment` - contains information about the created payment link,
- `transaction` - contains information about transactions if they were created for a given payment link,
- `notifyTransactionData` - specifies which exact transaction the notification refers to. This object is helpful when there is more than one payment method for a single payment.
- title: 6.2. Notification headers content
content: |
Additionally, the following parameters are included in the HTTP headers:
```
Content-Type: application/json; charset=UTF-8
X-Axepta-Signature: merchantid=6yt3gjtm9p7b8h9xsdqz;serviceid=63f574ed-d4ad-407e-9981-39ed7584a7b7;signature=20cdc8646eb268ea754842bdf0db1df21a2cf0b1c6e3e16e74ef7f7cca8f5450;alg=sha256
```
where:
* `merchantid` - client identifier,
* `serviceid` - store identifier,
* `signature` - notification signature,
* `alg` - hash algorithm (possible values: `sha256`).
> Verifying the notification signature is a critical part of authenticating the information transmitted in the notification package.
- title: 6.3. Notification signature verification method
content: |
The header containing the notification signature has the following format:
```
X-axepta-Signature: merchantid=[...];serviceid=[...];signature=[...];alg=[...]
```
To authenticate the source and verify the integrity of the notification message, perform the following steps:
1. From the headers of the incoming package delivered to the notification URL, read the `X-Axepta-Signature` value,
2. Then extract the values of `signature` and `alg`,
3. Depending on the hash algorithm specified in `alg`, calculate the appropriate hash:
```text
string incoming_signature = x_axepta_signature[signature]
string body = notification_body
string own_signature = hash(body + private_key, alg)
```
4. Compare the calculated `own_signature` value with `incoming_signature` read from the header,
5. If `own_signature` and `incoming_signature` are identical, the notification message is correct and comes from a trusted source.
> Transaction status changes should be applied only if signature verification succeeds.
- title: 7. Retrieving transaction data
content: |
To retrieve order data, send a `GET` request to:
```
https://api.axepta.pl/v1/merchant/{merchantId}/transaction/{transactionId}
```
where:
- `merchantId` - client identifier,
- `transactionId` - unique transaction identifier (UUID v4),
- title: 7.1. HTTP Request
content: |
### Example URL to send the GET request to
```
https://api.axepta.pl/v1/merchant/6yt3gjtm9p7b8h9xsdqz/transaction/5013e9ff-ece1-452a-9bd9-3b867a952794
```
- title: 7.2. HTTP Response
content: |
If the request to retrieve transaction data is successful, the server responds with HTTP status `200` and transaction information.
### Server response
```json
{
"status": "SUCCESS",
"data": {
"transaction": {
"id": "5013e9ff-ece1-452a-9bd9-3b867a952794",
"type": "sale",
"status": "pending",
"source": "api",
"createdAt": 1631261710,
"modifiedAt": 1631261710,
"notificationUrl": "http://domain.com/",
"serviceId": "33532abf-f5f7-42b7-aa68-d4f93ebad053",
"amount": 100,
"currency": "PLN",
"orderId": "123456",
"paymentMethod": "pbl",
"paymentMethodChannel": "bnpparibas",
"payment": {
"id": "41f9f9fa-c7d0-4f08-8fb9-007cc24428a6",
"status": "pending"
}
}
}
}
```
- title: 8. OneClick and recurring payments
content: |
`oneclick` payments consist of charging a customer/payer profile that has already been registered in the Axepta system. The first payment requires verification and providing full payment instrument details. Each subsequent payment is performed by charging based on the identifier assigned to the payment instrument.
`recurring` payments consist of cyclic charging of the customer's payment instrument without verification. Registration of the payment instrument is performed similarly to `oneclick`. In accordance with payment organization regulations, the payment must be repeatable in terms of amount and time period.
When making payments, remember that each payment instrument must have its own unique customer/payer identifier - `cid`.
- title: 8.1 Registering a new profile
content: |
> Profile registration via API is available only for merchants who have a PCI-DSS certificate.
> If you do not have a PCI-DSS certificate, use registration via the payment link API as described in [5. Creating a new payment link via API], where you need to include the `paywall.forceCardChannel` parameter with an appropriate value.
Registering a new profile via API is done by creating a new card transaction (section 3) with `paymentMethodChannel` set to `oneclick` or `recurring`.
#### Server response
When the transaction is accepted, the standard notification will be returned enriched with an additional `statusCode` field and a `paymentProfile` section with the following structure:
```json
{
"paymentProfile": {
"id": "d6a5bd6c-8e9c-496e-beb2-f0ca08215645",
"merchantMid": "6yt3gjtm9p7b8h9xsdqz",
"merchantCustomerId": "123",
"firstName": "Jan",
"lastName": "Kowalski",
"maskedNumber": "****1791",
"month": "10",
"year": "2020",
"organization": "MASTERCARD",
"isActive": 1,
"profile": "ONE_CLICK"
}
}
```
where:
| Parameter | Type | Description |
|----------|------|-------------|
| `id` | string | Profile identifier |
| `merchantMid` | string | Client identifier |
| `merchantCustomerId` | string(3) | Payer identifier, allowed characters: A-Za-z0-9_- |
| `firstName` | string | First name of the payment instrument holder |
| `lastName` | string | Last name of the payment instrument holder |
| `maskedNumber` | integer | Four asterisks and the last four digits of the payment instrument |
| `month` | string | Card expiry month |
| `year` | string | Card expiry year |
| `organization` | string | Payment organization that issued the registered card |
| `isActive` | integer | Profile activity: 1 - active, 0 - inactive |
| `profile` | string | Profile type |
- title: 8.2. Charging an existing profile
content: |
After successful profile registration, the `paymentProfileId` parameter will be returned. It is required in order to charge the profile.
To charge an existing profile, send a `POST` request to:
```
https://api.axepta.pl/v1/merchant/{merchantId}/transaction/profile
```
where:
* `merchantId` - client identifier.
#### Example URL to send the POST request to
```
https://api.axepta.pl/v1/merchant/6yt3gjtm9p7b8h9xsdqz/transaction/profile
```
#### Request payload
```json
{
"serviceId": "63f574ed-d4ad-407e-9981-39ed7584a7b7",
"paymentProfileId": "39ac1087-e632-41ff-acb8-8d661068a9d5",
"amount": 100,
"currency": "PLN",
"orderId": "123456"
}
```
where:
| Parameter | Type | Required | Description |
|----------|------|----------|-------------|
| `serviceId` | string(36) | ✔️ | Store identifier as UUID v4. |
| `paymentProfileId` | string(36) | ✔️ | Identifier of the profile to be charged. |
| `amount` | integer(1-999999999) | ✔️ | Amount in the smallest currency unit, e.g. grosz. |
| `currency` | string(3) | ✔️ | Currency in ISO 4217 format. |
| `orderID` | string(100) | ✔️ | Merchant order number - allowed characters: A-Za-z0-9#_-.\/ plus space and UNICODE 00C0 - 02C0. |
| `title` | string(255) | - | Transaction title - allowed characters: A-Za-z0-9#&_-"',.\/ plus space and UNICODE 00C0 - 02C0. |
#### Possible statuses
Attempting to charge a profile can return two statuses:
| Status | Type | Description |
|--------|------|-------------|
| `Success` | string | Success - profile charged |
| `Fail` | string | Error - profile was not charged |
#### Server response
If an attempt is made to charge an inactive profile, the response will look like:
```json
{
"status": "FAIL",
"message": "Payment profile inactive.",
"data": {
"errorCode": "PAYMENT_PROFILE_INACTIVE",
"errorId": 120301,
"bqh": "6jO"
}
}
```
#### ErrorCode descriptions
When the server returns status "FAIL", the following errors (`errorCode`) may occur:
| errorCode | Type | Description |
|----------|------|-------------|
| `PAYMENT_PROFILE_INACTIVE` | string | Payment profile deactivated |
| `PAYMENT_PROFILE_NOT_FOUND` | string | Payment profile not found |
| `SCHEMA_VALIDATION` | string | Character validation error. The request payload is invalid or does not meet character requirements |
- title: 8.3 Managing an existing profile
content: "The description of individual available functionalities is provided in the subsections."
- title: 8.3.1 Multipayout
content: |
It is possible to charge an existing card profile with the multipayout option. To do this, add the data described in section 5.4 Multipayouts to the request body used for charging the card profile.
#### Example payload
```json
{
"serviceId": "63f574ed-d4ad-407e-9981-39ed7584a7b7",
"paymentProfileId": "39ac1087-e632-41ff-acb8-8d661068a9d5",
"amount": 303,
"currency": "PLN",
"orderId": "test",
"data": {
"multipayout": [
{
"label": "1",
"iban": "PL01100010100000001010010000",
"amount": 102
},
{
"label": "2",
"iban": "PL00101000000000001000100000",
"amount": 201
}
]
}
}
```
- title: 8.3.2 Retrieve profile by `cid`
content: |
To retrieve a payer profile for a given `cid`, send a `GET` request to:
```
https://api.axepta.pl/v1/merchant/{merchantId}/profile/cid/{cid}
```
where:
* `merchantId` - client identifier.
* `cid` - payer identifier assigned by the merchant.
#### Response body
```json
{
"status": "SUCCESS",
"data": {
"paymentProfiles": [
{
"id": "949058db-fe93-4d70-4384-96f7fc5728d2",
"firstName": "Jan",
"lastName": "Kowalski",
"maskedNumber": "411111****1111",
"month": "12",
"year": "2029",
"organization": "MASTERCARD",
"isActive": 1,
"profile": "RECURRING"
},
{
"id": "949058db-ae07-4ce8-4d70-a1ea1f80b7c2",
"firstName": "Jan",
"lastName": "Kowalski",
"maskedNumber": "411111****1111",
"month": "12",
"year": "2029",
"organization": "MASTERCARD",
"isActive": 1,
"profile": "RECURRING"
}
],
"iqZ": "k9I"
}
}
```
- title: 8.3.3 Retrieve card profile by `id`
content: |
To retrieve information about a card profile, send a `GET` request to:
```
https://api.axepta.pl/v1/merchant/{merchantId}/profile/id/{paymentProfileId}
```
where:
* `merchantId` - client identifier.
* `paymentProfileId` - card profile identifier.
#### Response body
```json
{
"status": "SUCCESS",
"data": {
"paymentProfile": {
"id": "addcabf2-5229-4d70-a175-67f7fc5728d1",
"firstName": "Jan",
"lastName": "Kowalski",
"maskedNumber": "411111****1111",
"month": "12",
"year": "2029",
"organization": "MASTERCARD",
"isActive": 1,
"profile": "RECURRING"
},
"qtt": "GHb"
}
}
```
- title: 8.3.4 Deactivate card profile by `id`
content: |
To deactivate a card profile by `id`, send a `DELETE` request to:
```
https://api.axepta.pl/v1/merchant/{merchantId}/profile/id/{paymentProfileId}
```
where:
* `merchantId` - client identifier.
* `paymentProfileId` - card profile identifier.
#### Response body
```json
{
"status": "SUCCESS",
"data": {
"paymentProfile": {
"id": "rfgcabf2-5229-4d70-a175-96f7fc3458d5",
"firstName": "Jan",
"lastName": "Kowalski",
"maskedNumber": "411111****1111",
"month": "12",
"year": "2029",
"organization": "MASTERCARD",
"isActive": 0,
"profile": "RECURRING"
},
"Jcd": "sBR"
}
}
```
- title: 9. Retrieving payment data
content: |
To retrieve payment data, send a `GET` request to:
```
https://api.axepta.pl/v1/merchant/{merchantId}/payment/{paymentId}
```
where:
- `merchantId` - client identifier,
- `paymentId` - unique payment identifier
- title: 9.1 HTTP Request
content: |
### Example URL to send the GET request to
```
https://api.axepta.pl/v1/merchant/6yt3gjtm9p7b8h9xsdqz/payment/1572084b-4b63-40a7-90b1-17199172a385
```
- title: 9.2 HTTP Response
content: |
If the request to retrieve payment data is successful, the server responds with HTTP status `200` and payment information.
### Server response
```json
{
"status": "SUCCESS",
"data": {
"payment": {
"id": "1572084b-4b63-40a7-90b1-17199172a385",
"url": "https://paywall.axepta.pl/pay/1572084b-4b63-40a7-90b1-17199172a385",
"serviceId": "10af53c6-35ce-4713-81ba-883501277d40",
"orderId": "123123123",
"amount": "100",
"amountPaid": 0,
"amountRefunded": 0,
"amountSubmittedRefund": 0,
"currency": "PLN",
"status": "new",
"isActive": true,
"createdAt": 1631540831,
"modifiedAt": 1631540831,
"isGenerated": false,
"isUsed": false,
"isConfirmVisited": false,
"returnUrl": "https://domain.com/return",
"failureReturnUrl": "https://domain.com/failure",
"successReturnUrl": "https://domain.com/success",
"customer": {
"firstName": "Jan",
"lastName": "Kowalski",
"email": "jan.kowalski@example.com",
"phone": "501501501",
"locale": "pl",
"cid": "123"
}
}
}
}
```
- title: 10. Reports - API Report Documentation
content: |
The API enables generation of transaction reports in CSV format.
Reports can be sent via email or through a webhook.
- title: 10.1. Reports - Authorization
content: |
All endpoints require Basic Authentication.
**Header**: `Authorization: Basic `
The API key is available in the [Axepta administration panel](https://axepta.bnpparibas.pl/)
The key is available to a user with the Administrator role.
Settings -> 'API keys' tab -> 'default' -> 'details' -> 'authorization token' field.
The **Report** key must be selected.
- title: 10.2. Report Types
content: "The report types are described in the subsections"
- title: 10.2.1 Transaction Report (CSV)
content: |
Basic transaction report in CSV format.
**Request Body**:
```json
{
"taskName": "report_csv",
"type": "transaction",
"columns": [
"transactionInternalId",
"transactionAmount",
"transactionStatus",
"transactionCreated"
],
"conditions": {
"date": {
"from": 1609459200,
"to": 1612137599,
"timezone": "Europe/Warsaw"
},
"language": "EN",
"filters": {
"serviceUuid": ["service-uuid-1", "service-uuid-2"],
"paymentMethodCode": ["card", "blik"],
"transactionIsPaidOut": ["payout", "partial"],
"transactionStatus": ["settled", "pending"],
"transactionType": ["sale", "refund"]
}
},
"formatting": {
"columnSeparator": ",",
"numberSeparator": "."
},
"destination": {
"email": ["admin@example.com", "report@example.com"],
"callbackUrl": "https://your-domain.com/webhook/report"
}
}
```
**Fields**:
- `taskName` (string, required) - `"report_csv"`
- `type` (string, required) - `"transaction"`
- `columns` (array, required) - List of columns to include (min. 1)
- `conditions` (object, required):
- `date` (object, required):
- `from` (number, required) - Unix timestamp in seconds
- `to` (number, required) - Unix timestamp in seconds
- `timezone` (string, optional) - Time zone in TZ database format (e.g. `"Europe/Warsaw"`, `"UTC"`) - default `"Europe/Warsaw"`
- `language` (string, optional) - `"EN"` or `"PL"` (default PL)
- `filters` (object, optional):
- `serviceUuid` (array[string], optional) - List of service UUIDs
- `paymentMethodCode` (array[enum], optional) - Payment methods
- `transactionIsPaidOut` (array[enum], optional) - Payout status
- `transactionStatus` (array[enum], optional) - Transaction status
- `transactionType` (array[enum], optional) - Transaction type
- `formatting` (object, optional):
- `columnSeparator` (string, optional) - Column separator in the CSV file (e.g. `","`, `";"`, `"|"`)
- `numberSeparator` (string, optional) - Decimal separator in numbers (e.g. `"."`, `","`)
- `destination` (object, optional):
- `email` (array[string], optional) - List of email addresses (max 64 characters each)
- `callbackUrl` (string, optional) - Webhook URL
---
- title: 10.2.2. Transaction Report by Payout (CSV)
content: |
Report of transactions associated with payouts.
**Availability**: Panel only
**Request Body**:
```json
{
"taskName": "report_csv",
"type": "transaction_on_payout",
"columns": [
"transactionInternalId",
"transactionAmount",
"transactionIsPaidOut"
],
"conditions": {
"date": {
"from": 1609459200,
"to": 1612137599,
"timezone": "Europe/Warsaw"
},
"language": "PL",
"filters": {
"serviceUuid": ["service-uuid-1"],
"paymentMethodCode": ["card"],
"transactionStatus": ["settled"],
"transactionType": ["sale"]
}
},
"formatting": {
"columnSeparator": ";",
"numberSeparator": ","
},
"destination": {
"email": ["finance@example.com"],
"callbackUrl": "https://your-domain.com/webhook/report"
}
}
```
**Fields**:
- `taskName` (string, required) - `"report_csv"`
- `type` (string, required) - `"transaction_on_payout"`
- `columns` (array, required) - List of columns (min. 1)
- `conditions` (object, required):
- `date` (object, required)
- `language` (string, optional)
- `filters` (object, optional) - **Note**: No `transactionIsPaidOut` in this type!
- `formatting` (object, optional)
- `destination` (object, optional) - As in the transaction report
**Note**:
- This report does **NOT** support the `transactionIsPaidOut` filter.
---
- title: 10.2.3. Transaction Settlement Report (CSV)
content: |
Report of settled transactions only.
**Availability**: Panel only
**Request Body**:
```json
{
"taskName": "report_csv",
"type": "transaction_settled",
"columns": [
"transactionInternalId",
"transactionAmount",
"transactionSettled"
],
"conditions": {
"date": {
"from": 1609459200,
"to": 1612137599,
"timezone": "Europe/Warsaw"
},
"filters": {
"serviceUuid": ["service-uuid-1"],
"paymentMethodCode": ["card", "blik"],
"transactionIsPaidOut": ["payout"],
"transactionType": ["sale"]
}
},
"formatting": {
"columnSeparator": ",",
"numberSeparator": "."
},
"destination": {
"email": ["accounting@example.com"]
}
}
```
**Fields**:
- `taskName` (string, required) - `"report_csv"`
- `type` (string, required) - `"transaction_settled"`
- `columns` (array, required) - List of columns (min. 1)
- `conditions` (object, required):
- `date` (object, required)
- `filters` (object, optional) - **Note**: No `transactionStatus` in this type!
- `destination` (object, optional)
**Note**:
- This report does **NOT** support the `transactionStatus` filter.
- Supports formatting via `timezone` (in `date`), `columnSeparator` and `numberSeparator` (in `formatting`).
---
- title: 10.3. Report - Enums
content: |
### ReportTaskNameEnum
Report task type:
- `report_csv` - Report in CSV format
### ReportTypeEnum
Report type:
- `transaction` - Basic transaction report
- `transaction_on_payout` - Transactions on payout
- `transaction_settled` - Settled transactions only
### ReportStatusEnum
Report status:
- `new` - New, waiting for processing
- `preparing` - Preparing data
- `prepared` - Data prepared
- `generating` - Generating file
- `generated` - Report generated and ready
- `error` - Error during generation
- `deleted` - Report deleted
- `cancelled` - Report cancelled
### ReportColumnEnum
Available columns (all optional, select as needed):
**Quota (Order)**:
- `quotaUuid` - Order UUID
- `quotaStatus` - Order status
- `quotaAmount` - Order amount
- `quotaPayerFirstName` - Payer first name
- `quotaPayerLastName` - Payer last name
- `quotaPayerPhone` - Payer phone
- `quotaPayerEmail` - Payer email
**Payer**:
- `payerAccountNumber` - Payer account number
**Transaction**:
- `transactionInternalId` - Transaction ID
- `transactionType` - Transaction type (sale/refund)
- `transactionAmount` - Transaction amount
- `transactionMerchantOrderId` - Merchant order ID
- `transactionTitle` - Transaction title
- `transactionStatus` - Transaction status
- `transactionIsPaidOut` - Whether paid out
- `transactionSettled` - Settlement timestamp
- `transactionCreated` - Creation timestamp
- `transactionModified` - Modification timestamp
- `transactionRelatedInternalId` - Related transaction ID
- `transactionFeeAmount` - Fee amount
**Payment Method**:
- `paymentMethodName` - Payment method name
- `paymentMethodCode` - Payment method code
- `paymentMethodChannelName` - Payment channel name
- `paymentMethodChannelCode` - Payment channel code
**Service**:
- `serviceUuid` - Service UUID
- `serviceName` - Service name
**Currency**:
- `currencyIso4217` - ISO 4217 currency code
### PaymentMethodCodeEnum
Payment methods:
- `blik` - BLIK
- `card` - Payment card
- `pbl` - Bank transfer (Pay by Link)
- `wallet` - E-wallet
### TransactionStatusEnum
Transaction statuses:
- `new` - New
- `pending` - Pending
- `authorized` - Authorized
- `submitted_for_settlement` - Submitted for settlement
- `settled` - Settled
- `rejected` - Rejected
- `error` - Error
- `cancelled` - Cancelled
### TransactionTypeEnum
Transaction types:
- `sale` - Sale
- `refund` - Refund
### TransactionPaidOutEnum
Payout status:
- `payout` - Fully paid out
- `partial` - Partially paid out
- `not_payout` - Not paid out
### ReportFrequencyEnum
Frequency of generating scheduled reports:
- `day` - Daily (report for the previous day)
- `week` - Weekly (report for the previous week)
- `month` - Monthly (report for the previous month)
**Note**: Applies only to scheduled reports (planned reports).
### LanguageCode
Report language (column headers):
- `EN` - English
- `PL` - Polish
### Timezone
Time zone used for formatting date and time in the report:
- **Location**: In the `conditions.date.timezone` object
- Format: TZ database (e.g. `"Europe/Warsaw"`, `"America/New_York"`)
- Default: `"Europe/Warsaw"`
- Full list of available zones: [TZ database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
### Formatting (object)
The `formatting` object contains CSV file formatting settings:
**Column Separator** (`columnSeparator`):
- `,` (comma)
- `;` (semicolon)
- `|` (vertical bar)
- `\t` (tab)
**Number Separator** (`numberSeparator`):
- `.` (dot)
- `,` (comma)
---
- title: 10.4. Webhook
content: |
If you provide `callbackUrl` in `destination`, the system will send a webhook after the report is generated.
### Webhook Request
**Method**: `POST`
**URL**: Your `callbackUrl`
**Headers**:
```
Content-Type: application/json
```
**Body** (identical to GET response):
```json
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"plannedReportUuid": "650e8400-e29b-41d4-a716-446655440001",
"taskName": "report_csv",
"type": "transaction",
"status": "generated",
"settings": {
"columns": ["transactionInternalId", "transactionAmount"],
"conditions": {
"date": {
"from": 1609459200,
"to": 1612137599
},
"filters": {
"transactionStatus": ["settled"]
}
},
"destination": {
"email": ["report@example.com"]
}
},
"generatedAt": 1612137600
}
```
**Note**: The `plannedReportUuid` field will be present only if the report was generated from a scheduled report. For one-time reports (created via `POST /report`), this field will be `null` or absent.
### Webhook handling
1. **Webhook is sent when**: `status` reaches a final state (`generated`, `error`, `deleted`, `cancelled`)
2. **Required response**: The server **MUST** respond with HTTP status **200** and body:
```json
{
"status": "ok"
}
```
3. **Retry**: If the webhook returns an error (status other than 200) or times out, the system will automatically retry delivery
**Example of correct webhook handling** (Node.js/Express):
```javascript
app.post('/webhook/report', (req, res) => {
const report = req.body;
console.log(`Report ${report.uuid} has status: ${report.status}`);
if (report.status === 'generated') {
// Report ready - download the file or send notification
console.log(`Report generated at: ${report.generatedAt}`);
} else if (report.status === 'error') {
// Generation error
console.error(`Error generating report ${report.uuid}`);
}
// IMPORTANT: You MUST respond 200 with { status: "ok" }
res.status(200).json({ status: 'ok' });
});
```
---
## Usage examples
### Simple transaction report
```bash
curl -X POST "https://api.example.com/v1/merchant/MERCHANT123/report" \
-H "Authorization: Basic dXNlcjpwYXNz" \
-H "Content-Type: application/json" \
-d '{
"taskName": "report_csv",
"type": "transaction",
"columns": ["transactionInternalId", "transactionAmount", "transactionStatus"],
"conditions": {
"date": {
"from": 1609459200,
"to": 1612137599,
"timezone": "Europe/Warsaw"
}
}
}'
```
### Report with filtering and webhook
```bash
curl -X POST "https://api.example.com/v1/merchant/MERCHANT123/report" \
-H "Authorization: Basic dXNlcjpwYXNz" \
-H "Content-Type: application/json" \
-d '{
"taskName": "report_csv",
"type": "transaction",
"columns": ["transactionInternalId", "transactionAmount", "transactionStatus"],
"conditions": {
"date": {
"from": 1609459200,
"to": 1612137599,
"timezone": "Europe/Warsaw"
},
"language": "PL",
"filters": {
"paymentMethodCode": ["card", "blik"],
"transactionStatus": ["settled"]
}
},
"formatting": {
"columnSeparator": ";",
"numberSeparator": ","
},
"destination": {
"email": ["report@example.com"],
"callbackUrl": "https://your-domain.com/webhook/report"
}
}'
```
### Retrieve report
```bash
curl -X GET "https://api.example.com/v1/merchant/MERCHANT123/report/550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Basic "
```
### Download report file
```bash
curl -X GET "https://api.example.com/v1/merchant/MERCHANT123/report/550e8400-e29b-41d4-a716-446655440000/download" \
-H "Authorization: Basic " \
-o report.csv
```
### Create scheduled report
```bash
curl -X POST "https://api.example.com/v1/merchant/MERCHANT123/planned-report" \
-H "Authorization: Basic " \
-H "Content-Type: application/json" \
-d '{
"taskName": "report_csv",
"type": "transaction",
"columns": ["transactionInternalId", "transactionAmount", "transactionStatus"],
"conditions": {
"date": {
"timezone": "Europe/Warsaw"
},
"language": "PL"
},
"formatting": {
"columnSeparator": ";",
"numberSeparator": ","
},
"destination": {
"email": ["report@example.com"]
},
"frequency": "day",
"activeFrom": 1609459200,
"isActive": true,
"name": "Daily transaction report"
}'
```
### Update scheduled report
```bash
curl -X PUT "https://api.example.com/v1/merchant/MERCHANT123/planned-report/550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Basic " \
-H "Content-Type: application/json" \
-d '{
"isActive": false,
"frequency": "week"
}'
```
- title: 11. Sandbox
content: |
Axepta offers a sandbox test mode as part of verifying that the integration works correctly.
The sandbox test environment can be found by visiting: [https://axepta.sandbox.bnpparibas.pl/](https://axepta.sandbox.bnpparibas.pl/)
To create a new account, click `Create Merchant account`, and then provide an email address to which an account activation link will be sent.
After activating the account, simply log in using the generated login and the previously set password.
A test store will be assigned to the account, which will have its own integration keys.
**Sandbox URL:** `https://api.sandbox.axepta.pl`
- title: 11.1. Cards in the sandbox environment.
content: |
To test card payments, use the following data.
| Card issuer | Number | Month | Year | CVV | 3-D Secure | Behavior |
|-------------|------------------|-------|------|-----|-------------|-----------------------------|
| Visa | 4012001007002005 | 12 | 29 | 123 | no | Provider error |
| Visa | 4111111111111111 | 12 | 29 | 123 | no | Payment completed |
- title: 11.1. PBL transactions in the sandbox environment.
content: |
To test PBL transactions, use the following data.
| Title | Behavior |
|---------------|-----------------------------------------------|
| TEST-100010 | Provider error |
- title: 11.2. BLIK in the sandbox environment.
content: |
To test BLIK transactions, use the following data.
| Code | Behavior |
|---------------|-----------------------------------------------|
| 777000 | Completed |
# Testing asynchronous errors
The Axepta API enables you to test Blik payments by simulating asynchronous errors through the use of the amount, title, and blikCode parameters.
# Throwing asynchronous errors using `blikCode`
Here’s a table representation of the provided Blik codes and their statuses:
| blikCode | Status | Status Code |
|-----------|-----------------------------------|----------------------|
| 999000 | SETTLED | |
| 912111 | REJECTED | ALIAS_DECLINED |
| 927111 | REJECTED | TAS_DECLINED |
| 934111 | REJECTED | USER_DECLINED |
| 969111 | REJECTED | SEC_DECLINED |
| 956111 | REJECTED | SYSTEM_ERROR |
| 961111 | REJECTED | GENERAL_ERROR |
| 960111 | REJECTED | INSUFFICIENT_FUNDS |
| 989111 | REJECTED | TIMEOUT |
| 990111 | REJECTED | LIMIT_EXCEEDED |
| 949111 | REJECTED | USER_TIMEOUT |
| 902111 | REJECTED | ISSUER_DECLINED |
- Important note!
>Despite the transaction status being set to "Rejected", an additional asynchronous notification is sent at the end of the transaction process. This notification includes the relevant `StatusCode`.
#Throwing asynchronous errors using `amount`
Here’s a table representation of the provided amount values and their statuses.
For testing errors with amounts, you should use the blikCode: 777 xxx (where xxx can be any digits).
| amount | Status | Status Code |
|-----------|---------------------------------|----------------------|
| 28800 | REJECTED | ALIAS_DECLINED |
| 19200 | REJECTED | TAS_DECLINED |
| 14400 | REJECTED | USER_DECLINED |
| 21600 | REJECTED | SEC_DECLINED |
| 26400 | REJECTED | SYSTEM_ERROR |
| 36000 | REJECTED | GENERAL_ERROR |
| 12000 | REJECTED | INSUFFICIENT_FUNDS |
| 31200 | REJECTED | TIMEOUT |
| 9600 | REJECTED | LIMIT_EXCEEDED |
| 33600 | REJECTED | USER_TIMEOUT |
| 16800 | REJECTED | ISSUER_DECLINED |
#Testing synchronous errors
The Axepta API enables you to test Blik payments by simulating synchronous errors through the use of the blikCode value.
#Throwing synchronous errors using blikCode
Here’s a table representation of the provided blikCode values and transaction statuses:
| blikCode | Status | Status Code |
|-----------|---------------------------------|----------------------|
| 123444 | REJECTED | ER_WRONG_TICKET |
- title: 12. Minimum and maximum values for transaction and refund amounts.
content: |
The following limits apply for each payment method:
| Payment method | Minimum payment amount (PLN) | Maximum payment amount (PLN) |
|-----------------------------|------------------------------|------------------------------|
| Pay-By-Link online transfers| 0.37 (0.50)* | 999 999.99 |
| BLIK payment | 0.1 | 50 000 |
| Card payment | 0.05 | 999 999.99 |
| Wallet payment | 0.05 | 999 999.99 |
| One-click payment | 0.05 | 999 999.99 |
| Recurring payment | 0.05 | 999 999.99 |
(*) For nestPrzelew, I Pay with Plus Bank, and Spółdzielcza Grupa Bankowa it is 0.50 PLN
| Payment method | Minimum payment amount (EUR) | Maximum payment amount (EUR) |
|-----------------------------|------------------------------|------------------------------|
| Card payment | 0.01 | 999 999.99 |
| Wallet payment | 0.01 | 999 999.99 |
| One-click payment | 0.01 | 999 999.99 |
| Recurring payment | 0.01 | 999 999.99 |
Outside these thresholds, the given payment method is not available.
- title: Postman Collection
content: |
[Download Postman Collections.](https://data.axepta.pl/example/axepta_postman.zip)
To use the Postman collections, you must add your keys from the test environment.
> [Sandbox Description](https://bump.sh/pgw/doc/axepta-api/en/topic/topic-11-sandbox)