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