### Get Payment Methods Source: https://docs.paynow.pl/docs/reference/v3/get-payment-methods This example demonstrates how to retrieve available payment methods using an API key, signature, and idempotency key. ```APIDOC ## GET /v3/payments/paymentmethods ### Description Retrieves a list of available payment methods for a given transaction. ### Method GET ### Endpoint https://api.sandbox.paynow.pl/v3/payments/paymentmethods ### Parameters #### Header Parameters - **Api-Key** (string) - Required - Your API key for authentication. - **Signature** (string) - Required - The calculated signature for the request. - **Idempotency-Key** (string) - Required - Ensures that the request is processed only once. - **Accept** (string) - Required - Specifies the desired response format, typically 'application/json'. - **User-Agent** (string) - Optional - The User-Agent header for the request. #### Query Parameters - **amount** (number) - Optional - The transaction amount. Allowed values: PL, EUR, USD, GBP. - **currency** (string) - Optional - The currency for the transaction. Allowed values: PL, EUR, USD, GBP. - **applePayEnabled** (boolean) - Optional - Specifies if Apple Pay is enabled. Allowed values: true, false. ### Request Example ```json { "example": "" } ``` ### Response #### Success Response (200) - **paymentMethods** (array) - A list of available payment methods. - **name** (string) - The name of the payment method. - **code** (string) - The code representing the payment method. - **isApplePay** (boolean) - Indicates if the payment method is Apple Pay. #### Response Example ```json { "example": "{\n \"paymentMethods\": [\n {\n \"name\": \"Card\",\n \"code\": \"card\",\n \"isApplePay\": false\n },\n {\n \"name\": \"Apple Pay\",\n \"code\": \"applepay\",\n \"isApplePay\": true\n }\n ]\n}" } ``` ``` -------------------------------- ### Get Seller Balances (C#) Source: https://docs.paynow.pl/docs/reference/v3/get-sellers-balances-request Example of how to make a GET request to retrieve seller balances using HttpClient in C#. Ensure to include the Api-Key and Signature headers for authentication. ```csharp var client = new HttpClient(); var request = new HttpRequestMessage(HttpMethod.Get, "https://api.sandbox.paynow.pl/v3/balances/sellers/:sellerId"); request.Headers.Add("Accept", "application/json"); request.Headers.Add("Api-Key", "{{apiKey}}"); request.Headers.Add("Signature", "{{calculatedSignature}}"); var response = await client.SendAsync(request); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` -------------------------------- ### Seller Balance Response Example Source: https://docs.paynow.pl/docs/v3/marketplace Example structure of the response when retrieving seller balances, showing available balance and frozen escrow amount. ```JSON { "balance": { "amount": 500 }, "escrow": { "amount": 100 } } ``` -------------------------------- ### Get Refund Status (C#) Source: https://docs.paynow.pl/docs/reference/v3/get-refund-status Example using HttpClient in C# to fetch refund status. Ensure you have the correct API key, signature, and idempotency key. ```csharp var client = new HttpClient(); var request = new HttpRequestMessage(HttpMethod.Get, "https://api.sandbox.paynow.pl/v3/refunds/:refundId/status"); request.Headers.Add("Accept", "application/json"); request.Headers.Add("Api-Key", "{{apiKey}}"); request.Headers.Add("Signature", "{{calculatedSignature}}"); request.Headers.Add("Idempotency-Key", "{{idempotencyKey}}"); var response = await client.SendAsync(request); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` -------------------------------- ### 201 Created Response Example Source: https://docs.paynow.pl/docs/reference/v3/init-boarding-process This is an example of a successful response when a seller is created. ```json { "sellerId": "MB3-42Y-HRI-K9G", "sellerApplicationUrl": "https://melements.pl/...", "status": "NEW" } ``` -------------------------------- ### Get Payment Methods Request (C#) Source: https://docs.paynow.pl/docs/reference/v3/get-payment-methods Example of making a GET request to the payment methods endpoint using HttpClient in C#. Ensure you replace placeholders like {{apiKey}}, {{calculatedSignature}}, and {{idempotencyKey}} with actual values. ```csharp var client = new HttpClient(); var request = new HttpRequestMessage(HttpMethod.Get, "https://api.sandbox.paynow.pl/v3/payments/paymentmethods"); request.Headers.Add("Accept", "application/json"); request.Headers.Add("Api-Key", "{{apiKey}}"); request.Headers.Add("Signature", "{{calculatedSignature}}"); request.Headers.Add("Idempotency-Key", "{{idempotencyKey}}"); var response = await client.SendAsync(request); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` -------------------------------- ### Successful Response - Get Payment Methods Source: https://docs.paynow.pl/docs/reference/v3/get-payment-methods This example shows the structure of a successful response when retrieving payment methods. It includes details like method ID, name, description, image URL, status, and authorization type. ```json [ { "type": "PBL", "paymentMethods": [ { "id": 1000, "name": "mTransfer", "description": "Zapłać przez mTransfer", "image": "https://static.sandbox.paynow.pl/payment-method-icons/1000.png", "status": "ENABLED", "authorizationType": "REDIRECT" } ] } ] ``` -------------------------------- ### Voucher Reservation Response Example Source: https://docs.paynow.pl/docs/v3/marketplace Example response after successfully reserving voucher funds. It includes the reservation ID, payer amount, voucher amount, and how the voucher amount is distributed among sellers. ```JSON { "voucherReservationId": "ABC-123-456-789", "payerAmount": 15671, "voucherAmount": 30000, "transfers": [ { "sellerId": "MB9-CWR-7R9-QMP", "payerGrossAmount": 11041, "voucherGrossAmount": 21134 }, { "sellerId": "MB2-GRP-A23-P10", "payerGrossAmount": 4630, "voucherGrossAmount": 8866 } ] } ``` -------------------------------- ### 409 Conflict Response Example Source: https://docs.paynow.pl/docs/reference/v3/init-boarding-process This example shows a conflict response, such as when a seller application is already being processed. ```json { "errorType": "CONFLICT", "message": "Seller application with given nip is currently processed" } ``` -------------------------------- ### Get BLIK Payment Method Details Source: https://docs.paynow.pl/docs/v3/white-label-payment Retrieve a list of available payment methods, ensuring to fetch them before each payment creation. This example shows the structure for a BLIK payment method with authorizationType 'CODE'. ```json [ { "type": "BLIK", "paymentMethods": [ { "id": 2007, "name": "BLIK", "description": "Płacę z BLIKIEM", "image": "https://static.devel.integrator.emfale.com/payment-method-icons/2007.png", "status": "ENABLED", "authorizationType": "CODE" } ] } ] ``` -------------------------------- ### Example Error Responses Source: https://docs.paynow.pl/docs/reference/v3/send-cancel-request Provides example JSON payloads for various error scenarios. ```APIDOC ## Example Error Responses ### Bad Request Example ```json { "statusCode": 400, "errors": [ { "errorType": "VALIDATION_ERROR", "message": "Missing field XXX" }, { "errorType": "INVALID_PAYMENT_TRANSFER_STATUS", "message": "Payment transfer for given seller is in wrong status XXX" } ] } ``` ### Unauthorized Example ```json { "statusCode": 401, "errors": [ { "errorType": "UNAUTHORIZED", "message": "Unauthorized, invalid or missing credentials" } ] } ``` ### Not Found Example ```json { "statusCode": 404, "errors": [ { "errorType": "NOT_FOUND", "message": "Resource not found" } ] } ``` ### Conflict Example ```json { "statusCode": 409, "errors": [ { "errorType": "CONFLICT", "message": "Payment transfer for given seller is in wrong status {currentStatus=XXX}" } ] } ``` ### Internal Server Error Example ```json { "statusCode": 500, "errors": [ { "errorType": "INTERNAL_SERVER_ERROR", "message": "Internal server error" } ] } ``` ### Service Unavailable Example ```json { "statusCode": 503, "errors": [ { "errorType": "SYSTEM_TEMPORARILY_UNAVAILABLE", "message": "Service is temporarily unavailable" } ] } ``` ``` -------------------------------- ### Not Found Error Example Source: https://docs.paynow.pl/docs/reference/v3/cancel-refund This JSON example shows a 'Not Found' error response. It includes the status code and an error object specifying that the requested resource could not be located. ```json { "statusCode": 404, "errors": [ { "errorType": "NOT_FOUND", "message": "Resource not found" } ] } ``` -------------------------------- ### Bad Request Response Example (Signature Missing) Source: https://docs.paynow.pl/docs/reference/v3/send-voucher-reservation-request Example of a bad request response due to a missing signature. This indicates an issue with authentication or request integrity. ```json { "statusCode": 400, "errors": [ { "errorType": "SIGNATURE_MISSING", "message": "Missing field XXX" }, { "errorType": "IDEMPOTENCY_KEY_MISSING", "message": "Missing field XXX" } ] } ``` -------------------------------- ### Service Temporarily Unavailable Error Example Source: https://docs.paynow.pl/docs/reference/v3/cancel-refund This JSON example illustrates a 'Service Temporarily Unavailable' error. It signifies that the service is currently down and provides the status code and a relevant error message. ```json { "statusCode": 503, "errors": [ { "errorType": "SYSTEM_TEMPORARILY_UNAVAILABLE", "message": "Service is temporarily unavailable" } ] } ``` -------------------------------- ### GDPR Clauses Response Example Source: https://docs.paynow.pl/docs/reference/v3/data-processing-notices This is an example of a successful response containing GDPR clauses. Each clause includes a title, content, and the locale it applies to. ```json [ { "title": "mElements S.A. with its registered office in Warsaw, 00-850 at ul. Prosta 18 is the controller of your personal data.", "content": "The personal data provided by the Buyer will be used by mElements S.A. to execute the payment transaction.
The agreement for the provision of the \"Paynow\" Payment Integrator service constitutes the legal basis for the processing of personal data by mElements S.A.
Personal data may be made available to the following entities: Personal data will be stored for a period not longer than 5 years after the termination of the agreement by one of the parties (in the event of a court dispute). After the expiry of the above periods, mElements will anonymise personal data.
The Buyer has the right to access and rectify, transfer, delete, limit or object to the processing of his/her personal data. The Buyer also has the right to lodge a complaint with the supervisory body for the protection of personal data in the manner indicated on the website uodo.gov.pl . Provision of data is voluntary, but necessary for the execution of payment, and failure to provide data may result in the rejection of the payment.
More information on the rules governing the processing of your personal data by mElements can be found in the Privacy Policy
The function of the Personal Data Protection Officer is performed by an employee of mElements S.A., who can be contacted at: iod@melements.pl", "locale": "en-GB" } ] ``` -------------------------------- ### Success Response (200 OK) Source: https://docs.paynow.pl/docs/reference/v3/get-sellers-balances-request This example shows a successful response containing the seller's balance and escrow amounts. The amounts are represented in the smallest currency unit. ```json { "balance": { "amount": 50000 }, "escrow": { "amount": 15000 } } ``` -------------------------------- ### Get Payment Methods Source: https://docs.paynow.pl/docs/reference/v3/get-payment-methods Fetches a list of all available payment methods for the project. ```APIDOC ## GET /v3/payment-methods ### Description Retrieves a list of available payment methods for the project. ### Method GET ### Endpoint /v3/payment-methods ### Parameters #### Query Parameters - **type** (string) - Optional - Type of method used for payment. Possible values: [`APPLE_PAY`, `BLIK`, `CARD`, `ECOMMERCE`, `GOOGLE_PAY`, `PAYPO`, `PBL`] ### Response #### Success Response (200) - **paymentMethods** (object[]) - An array of payment method objects. - **id** (integer) - Required - Unique identifier of payment method. - **name** (string) - Required - Short name of payment method. - **description** (string) - Required - Description of payment method. - **image** (string) - Required - Url for payment method icon. - **status** (string) - Required - Current status of payment method. Possible values: [`ENABLED`, `DISABLED`]. - **authorizationType** (string) - Required - Authorization type. In case of `REDIRECT` the payment authorization happens on Paynow site. In case of `CODE` the `Payment Request` sent to Paynow needs to contain the `authorizationCode`. Possible values: [`REDIRECT`, `CODE`]. #### Response Example ```json [ { "type": "PBL", "paymentMethods": [ { "id": 1000, "name": "mTransfer", "description": "Zapłać przez mTransfer", "image": "https://static.sandbox.paynow.pl/payment-method-icons/1000.png", "status": "ENABLED", "authorizationType": "REDIRECT" } ] } ] ``` #### Error Response (400) - **statusCode** (integer) - Error status code. - **errors** (object[]) - Required - Array of error objects. - **errorType** (string) - Error type. Possible values: [`FORBIDDEN`, `NOT_FOUND`, `RATE_LIMIT_REACHED`, `SYSTEM_TEMPORARILY_UNAVAILABLE`, `VALIDATION_ERROR`, `VERIFICATION_FAILED`, `PAYMENT_AMOUNT_TOO_SMALL`, `PAYMENT_AMOUNT_TOO_LARGE`, `IDEMPOTENCY_KEY_MISSING`, `SIGNATURE_MISSING`]. - **message** (string) - Error description. #### Error Response Example (400) ```json { "statusCode": 400, "errors": [ { "errorType": "VALIDATION_ERROR", "message": "Missing field XXX" }, { "errorType": "VALIDATION_ERROR", "message": "Invalid format of field YYY" } ] } ``` #### Error Response (401) - **statusCode** (integer) - Error status code. - **errors** (object[]) - Required - Array of error objects. - **errorType** (string) - Error type. Possible values: [`UNAUTHORIZED`]. - **message** (string) - Error description. #### Error Response Example (401) ```json { "statusCode": 401, "errors": [ { "errorType": "UNAUTHORIZED", "message": "Unauthorized, invalid or missing credentials" } ] } ``` #### Error Response (404) - **statusCode** (integer) - Error status code. - **errors** (object[]) - Required - Array of error objects. - **errorType** (string) - Error type. Possible values: [`NOT_FOUND`]. - **message** (string) - Error description. #### Error Response Example (404) ```json { "statusCode": 404, "errors": [ { "errorType": "NOT_FOUND", "message": "Resource not found" } ] } ``` #### Error Response (500) - **statusCode** (integer) - Error status code. - **errors** (object[]) - Required - Array of error objects. - **errorType** (string) - Error type. Possible values: [`INTERNAL_SERVER_ERROR`]. - **message** (string) - Error description. #### Error Response Example (500) ```json { "statusCode": 500, "errors": [ { "errorType": "INTERNAL_SERVER_ERROR", "message": "Internal server error" } ] } ``` #### Error Response (503) - **statusCode** (integer) - Error status code. - **errors** (object[]) - Required - Array of error objects. - **errorType** (string) - Error type. Possible values: [`SYSTEM_TEMPORARILY_UNAVAILABLE`]. - **message** (string) - Error description. #### Error Response Example (503) ```json { "statusCode": 503, "errors": [ { "errorType": "SYSTEM_TEMPORARILY_UNAVAILABLE", "message": "Service is temporarily unavailable" } ] } ``` ``` -------------------------------- ### Get Seller Application Status (Response) Source: https://docs.paynow.pl/docs/v3/marketplace Retrieves the current status of a seller's onboarding application using their seller ID. ```json { "sellerId": "MBC-G58-B69-AT2", "sellerApplicationUrl": "https://panel.paynow.pl/", "status": "COMPLETED" } ``` -------------------------------- ### Bad Request - Validation Error Example Source: https://docs.paynow.pl/docs/reference/v3/send-cancel-request This example shows a 400 Bad Request response due to validation errors, such as missing fields or incorrect payment transfer status. ```json { "statusCode": 400, "errors": [ { "errorType": "VALIDATION_ERROR", "message": "Missing field XXX" }, { "errorType": "INVALID_PAYMENT_TRANSFER_STATUS", "message": "Payment transfer for given seller is in wrong status XXX" } ] } ``` -------------------------------- ### 409 Conflict Response Example (Schema) Source: https://docs.paynow.pl/docs/reference/v3/init-boarding-process This is the schema for a conflict response. ```json { "errorType": "CONFLICT", "message": "string" } ``` -------------------------------- ### Get Data Processing Notices with API Key Authentication (C#) Source: https://docs.paynow.pl/docs/reference/v3/data-processing-notices This C# code snippet demonstrates how to make a GET request to retrieve data processing notices using API Key authentication. Ensure you have the HttpClient class available and replace placeholders with your actual API key, calculated signature, and idempotency key. ```csharp var client = new HttpClient(); var request = new HttpRequestMessage(HttpMethod.Get, "https://api.sandbox.paynow.pl/v3/payments/dataprocessing/notices"); request.Headers.Add("Accept", "application/json"); request.Headers.Add("Api-Key", "{{apiKey}}"); request.Headers.Add("Signature", "{{calculatedSignature}}"); request.Headers.Add("Idempotency-Key", "{{idempotencyKey}}"); var response = await client.SendAsync(request); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` -------------------------------- ### Get Seller Application Status Source: https://docs.paynow.pl/docs/reference/v3/get-application-status Fetches the application status of a seller. ```APIDOC ## GET /v3/boarding/merchants/sellers/:sellerId ### Description Get seller application status. ### Method GET ### Endpoint https://api.sandbox.paynow.pl/v3/boarding/merchants/sellers/:sellerId ### Parameters #### Header Parameters - **Api-Key** (string) - required - Unique key used to authenticate API requests. - **Signature** (string) - required - The Signature header is used to ensure the request’s body integrity and to confirm that its content has not changed. - **Accept** (string) - required - The Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand. Can be set to `*/*`. - **Content-Type** (string) - required - The Content-Type entity header is used to indicate the media type of the resource. ``` -------------------------------- ### Create Payment with Voucher Response Source: https://docs.paynow.pl/docs/v3/marketplace This is an example response when creating a payment with a voucher card. It includes a redirect URL, payment ID, and status. ```json { "redirectUrl": "https://paywall.sandbox.paynow.pl/NOLV-8F9-08K-WGD?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwb3NJZCI6IjEwMDAiLCJwYXltZW50SWQiOiJOT0xWLThGOS0wOEstV0dEIiwiZXhwIjoxNTU0ODEzMTY4fQ.71TLjI8U8p0c_hhC1Nj3cAPU3mtzYW4ylGo8qVeB18o", "paymentId": "NOLV-8F9-08K-WGD", "status": "NEW" } ``` -------------------------------- ### Get Sellers Balances Source: https://docs.paynow.pl/docs/reference/v3/get-sellers-balances-request Fetches the balance information for a given seller ID. ```APIDOC ## GET https://api.sandbox.paynow.pl/v3/balances/sellers/:sellerId ### Description Retrieves the balance information for a specific seller. ### Method GET ### Endpoint https://api.sandbox.paynow.pl/v3/balances/sellers/:sellerId ### Parameters #### Path Parameters - **sellerId** (string) - Required - Seller ID obtained during seller boarding. Possible values: `>= 15 characters` and `<= 15 characters`, Value must match regular expression `^([a-zA-Z0-9]{3}(-[a-zA-Z0-9]{3}){3})$` #### Header Parameters - **Api-Key** (string) - Required - Unique key used to authenticate API requests. - **Signature** (string) - Required - The Signature header is used to ensure the request’s body integrity and to confirm that its content has not changed. - **Accept** (string) - Required - The Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand. Can be set to `*/*`. ``` -------------------------------- ### Create Payment with Voucher Request Body Source: https://docs.paynow.pl/docs/v3/marketplace This is an example request body for creating a payment with a voucher card. Ensure the amount and transfers match the reservation details. ```json { "amount": 45671, "externalId": "234567898654", "description": "Test transaction", "buyer": { "email": "jan.kowalski@melements.pl" }, "voucherReservationId": "ABC-123-456-789", "transfers": [ { "sellerId": "MB9-CWR-7R9-QMP", "grossAmount": "32175", "feeAmount": "500" }, { "sellerId": "MB2-GRP-A23-P10", "grossAmount": "13496", "feeAmount": "60" } ] } ``` -------------------------------- ### Get Sellers Balances - Success Response Source: https://docs.paynow.pl/docs/reference/v3/get-sellers-balances-request Returns the seller's balance and escrow amounts. The amounts are in the smallest currency unit (e.g., grosz for PLN). ```APIDOC ## GET /sellers/balances ### Description Retrieves the current balance and escrow amounts for a seller. ### Method GET ### Endpoint /sellers/balances ### Parameters #### Query Parameters None #### Request Body None ### Response #### Success Response (200) - **balance** (object) - Required - Seller balance amount - **amount** (integer) - Required - Amount of given balance in the smallest unit of the balance currency (grosz in the case of PLN). - **escrow** (object) - Required - Seller balance amount - **amount** (integer) - Required - Amount of given balance in the smallest unit of the balance currency (grosz in the case of PLN). #### Response Example ```json { "balance": { "amount": 50000 }, "escrow": { "amount": 15000 } } ``` ``` -------------------------------- ### Payment Request Response Structure Source: https://docs.paynow.pl/docs/v3/payments Example of a successful payment request response. It includes a redirect URL, the payment ID, and the initial payment status. ```json { "redirectUrl": "https://paywall.sandbox.paynow.pl/NOLV-8F9-08K-WGD?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwb3NJZCI6IjEwMDAiLCJwYXltZW50SWQiOiJOT0xWLThGOS0wOEstV0dEIiwiZXhwIjoxNTU0ODEzMTY4fQ.71TLjI8U8p0c_hhC1Nj3cAPU3mtzYW4ylGo8qVeB18o", "paymentId": "NOLV-8F9-08K-WGD", "status": "NEW" } ``` -------------------------------- ### Example Notification Request Source: https://docs.paynow.pl/docs/v3/integration This cURL command demonstrates the structure of an HTTP POST request Paynow sends to your notification URL, including the Signature header and JSON payload. ```shell curl -X POST \ \ -H 'Signature: F69sbjUxBX4eFjfUal/Y9XGREbfaRjh/zdq9j4MWeHM=' \ -H 'Content-Type: application/json' \ -d \ '{ "paymentId": "NOLV-8F9-08K-WGD", "externalId": "9fea23c7-cd5c-4884-9842-6f8592be65df", "status": "CONFIRMED", "modifiedAt": "2018-12-12T13:24:52" }' ``` -------------------------------- ### Voucher Reservation Success Response Source: https://docs.paynow.pl/docs/reference/v3/send-voucher-reservation-request Example of a successful response when a voucher reservation is created. This includes IDs and amounts for the reservation. ```json { "voucherReservationId": "FW3-4R3-AP1-VSM", "payerAmount": 5671, "voucherAmount": 40000, "transfers": [ { "sellerId": "MBV-A4F-H2W-ARS", "payerGrossAmount": 5671, "voucherGrossAmount": 40000 } ] } ``` -------------------------------- ### Initialize Onboarding Request (C#) Source: https://docs.paynow.pl/docs/reference/v3/init-boarding-process Use this code to send a POST request to initialize the seller onboarding process. Ensure to include your Api-Key and a calculated Signature in the headers. ```csharp var client = new HttpClient(); var request = new HttpRequestMessage(HttpMethod.Post, "https://api.sandbox.paynow.pl/v3/boarding/merchants/sellers/init"); request.Headers.Add("Accept", "application/json"); request.Headers.Add("Api-Key", "{{apiKey}}"); request.Headers.Add("Signature", "{{calculatedSignature}}"); var content = new StringContent("{\n \"nip\": 7624888859,\n \"notificationUrl\": \"https://api.sandbox.paynow.pl/...\"\n}", null, "application/json"); request.Content = content; var response = await client.SendAsync(request); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` -------------------------------- ### Initialize Seller Onboarding (Minimum Request) Source: https://docs.paynow.pl/docs/v3/marketplace Initiates the seller onboarding process with the minimum required information (NIP). ```json { "nip": "1145934848" } ``` -------------------------------- ### Initialize Seller Onboarding (Response) Source: https://docs.paynow.pl/docs/v3/marketplace The response received after successfully initiating seller onboarding, containing the seller ID and application URL. ```json { "sellerId": "MBC-G58-B69-AT2", "sellerApplicationUrl": "https://panel.paynow.pl/", "status": "NEW" } ``` -------------------------------- ### Initialize Onboarding Source: https://docs.paynow.pl/docs/reference/v3/init-boarding-process Initiates the onboarding process for a new seller. This endpoint requires an API Key and a calculated signature for authentication. ```APIDOC ## POST /v3/boarding/merchants/sellers/init ### Description Initiates the onboarding process for a new seller. This endpoint requires an API Key and a calculated signature for authentication. ### Method POST ### Endpoint https://api.sandbox.paynow.pl/v3/boarding/merchants/sellers/init ### Parameters #### Header Parameters - **Api-Key** (string) - Required - Your API key for authentication. - **Signature** (string) - Required - The calculated signature for request verification. - **Accept** (string) - Required - Specifies the desired response format, typically 'application/json'. - **Content-Type** (string) - Required - Indicates the format of the request body, typically 'application/json'. #### Request Body - **nip** (integer) - Required - The seller's NIP (Tax Identification Number). - **notificationUrl** (string) - Required - The URL to which Paynow will send notifications regarding the onboarding process. ### Request Example ```json { "nip": 7624888859, "notificationUrl": "https://api.sandbox.paynow.pl/..." } ``` ### Response #### Success Response (201 Created) - **sellerId** (string) - Required - The unique identifier for the seller. - **sellerApplicationUrl** (string) - Required - The URL to redirect the seller to complete the onboarding. - **status** (string) - Required - The current status of the onboarding process, typically 'NEW'. #### Response Example (201) ```json { "sellerId": "MB3-42Y-HRI-K9G", "sellerApplicationUrl": "https://melements.pl/...", "status": "NEW" } ``` #### Error Responses - **400 Bad Request**: Indicates issues with the request payload, such as validation errors. - **statusCode** (integer) - Required - The HTTP status code. - **errors** (object[]) - Required - An array of error objects. - **errorType** (string) - Required - The type of error (e.g., 'VALIDATION_ERROR'). - **message** (string) - Description of the error. - **401 Unauthorized**: Indicates invalid or missing authentication credentials. - **statusCode** (integer) - Required - The HTTP status code. - **errors** (object[]) - Required - An array of error objects. - **errorType** (string) - Required - The type of error (e.g., 'UNAUTHORIZED'). - **message** (string) - Description of the error. - **409 Conflict**: Indicates a conflict with the current state of the resource, such as a seller application already being processed. - **errorType** (string) - Required - The type of error (e.g., 'CONFLICT'). - **message** (string) - Description of the error. - **500 Internal Server Error**: Indicates an unexpected server error. - **statusCode** (integer) - Required - The HTTP status code. - **errors** (object[]) - Required - An array of error objects. - **errorType** (string) - Required - The type of error (e.g., 'INTERNAL_SERVER_ERROR'). - **message** (string) - Description of the error. ``` -------------------------------- ### Initialize Seller Boarding Process API Endpoint Source: https://docs.paynow.pl/docs/reference/v3/init-boarding-process Use this endpoint to start the seller onboarding process. Ensure you include the required API-Key and Signature headers, and set the Content-Type to application/json. ```http POST https://api.sandbox.paynow.pl/v3/boarding/merchants/sellers/init ``` -------------------------------- ### Initialize Onboarding Request Body Source: https://docs.paynow.pl/docs/reference/v3/init-boarding-process This is the JSON body required to initiate the seller onboarding process. It includes the seller's NIP and a notification URL. ```json { "nip": 7624888859, "notificationUrl": "https://api.sandbox.paynow.pl/..." } ``` -------------------------------- ### Send Payment Request (C#) Source: https://docs.paynow.pl/docs/reference/v3/send-payment-request Demonstrates how to send a POST request to create a payment. Includes setting headers for API key, signature, idempotency, and content type. Ensure you have the HttpClient class available. ```csharp var client = new HttpClient(); var request = new HttpRequestMessage(HttpMethod.Post, "https://api.sandbox.paynow.pl/v3/payments"); request.Headers.Add("Accept", "application/json"); request.Headers.Add("Api-Key", "{{apiKey}}"); request.Headers.Add("Signature", "{{calculatedSignature}}"); request.Headers.Add("Idempotency-Key", "{{idempotencyKey}}"); var content = new StringContent("true", null, "application/json"); request.Content = content; var response = await client.SendAsync(request); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` -------------------------------- ### Get Seller Balances Source: https://docs.paynow.pl/docs/reference/v3/get-sellers-balances-request This snippet shows how to make a GET request to retrieve the balances for a specific seller. ```APIDOC ## GET /v3/balances/sellers/:sellerId ### Description Retrieves the balances for a specific seller. ### Method GET ### Endpoint https://api.sandbox.paynow.pl/v3/balances/sellers/:sellerId ### Parameters #### Path Parameters - **sellerId** (string) - Required - The unique identifier of the seller. #### Header Parameters - **Api-Key** (string) - Required - Your Paynow API key for authentication. - **Signature** (string) - Required - The calculated signature for request verification. - **Accept** (string) - Required - Specifies the desired response format, typically 'application/json'. ### Request Example ```csharp var client = new HttpClient(); var request = new HttpRequestMessage(HttpMethod.Get, "https://api.sandbox.paynow.pl/v3/balances/sellers/:sellerId"); request.Headers.Add("Accept", "application/json"); request.Headers.Add("Api-Key", "{{apiKey}}"); request.Headers.Add("Signature", "{{calculatedSignature}}"); var response = await client.SendAsync(request); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` ### Response #### Success Response (200) - **balance** (number) - The current balance of the seller. - **currency** (string) - The currency of the balance. ``` -------------------------------- ### Configure Shop URLs with HttpClient (C#) Source: https://docs.paynow.pl/docs/reference/v3/send-shop-urls-configuration Use this C# HttpClient example to send a PATCH request to update your shop's notification and continue URLs. Ensure you include your API key and a calculated signature in the headers. ```csharp var client = new HttpClient(); var request = new HttpRequestMessage(HttpMethod.Patch, "https://api.sandbox.paynow.pl/v3/configuration/shop/urls"); request.Headers.Add("Api-Key", "{{apiKey}}"); request.Headers.Add("Signature", "{{calculatedSignature}}"); var content = new StringContent("{\n \"notificationUrl\": \"https://shopdomain.com/paynow/notifications\",\n \"continueUrl\": \"https://shopdomain.com/paynow/callback\"\n}", null, "application/json"); request.Content = content; var response = await client.SendAsync(request); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` -------------------------------- ### PHP SDK Example for Signature Generation (v3) Source: https://docs.paynow.pl/docs/v3/integration This PHP code demonstrates how to use the SignatureCalculator class from the Paynow SDK to generate a v3 signature. Ensure all components like idempotency key, body, and parameters are correctly prepared. ```php $idempotencyKey = ''; $body = []; $parameters = [] $signature = SignatureCalculator::generateV3( '97a55694-5478-43b5-b406-fb49ebfdd2b5', 'b305b996-bca5-4404-a0b7-2ccea3d2b64b, $idempotencyKey, $body ? json_encode($body, JSON_UNESCAPED_SLASHES) : '', $parameters ); ``` -------------------------------- ### C# Example for Sending Voucher Reservation Request Source: https://docs.paynow.pl/docs/reference/v3/send-voucher-reservation-request This C# code snippet demonstrates how to send a POST request to the voucher reservation endpoint. It includes setting up the HttpClient, request details, headers, and content. Ensure you replace placeholders like {{apiKey}}, {{calculatedSignature}}, and {{idempotencyKey}} with actual values. The request body specifies the voucher code, amount, and transfer details. ```csharp var client = new HttpClient(); var request = new HttpRequestMessage(HttpMethod.Post, "https://api.sandbox.paynow.pl/v3/vouchers/reservations"); request.Headers.Add("Accept", "application/json"); request.Headers.Add("Api-Key", "{{apiKey}}"); request.Headers.Add("Signature", "{{calculatedSignature}}"); request.Headers.Add("Idempotency-Key", "{{idempotencyKey}}"); var content = new StringContent("{\n \"voucherCode\": \"VC1-YBF-4FW-SFM\",\n \"amount\": 45671,\n \"transfers\": [\n {\n \"sellerId\": \"MB3-4FF-IXA-ACM\",\n \"grossAmount\": 45671\n }\n ]\n}", null, "application/json"); request.Content = content; var response = await client.SendAsync(request); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` -------------------------------- ### Conflict - Wrong Payment Status Example Source: https://docs.paynow.pl/docs/reference/v3/send-cancel-request This example shows a 409 Conflict response, often occurring when a payment transfer is in an incorrect status for the requested operation. ```json { "statusCode": 409, "errors": [ { "errorType": "CONFLICT", "message": "Payment transfer for given seller is in wrong status {currentStatus=XXX}" } ] } ``` -------------------------------- ### Bad Request Response (Schema Example) Source: https://docs.paynow.pl/docs/reference/v3/send-payment-request An example of a bad request response, typically indicating validation errors or missing fields. The 'errors' array contains details about each issue. ```json { "statusCode": 0, "errors": [ {}, {} ] } ``` -------------------------------- ### Initialize Seller Boarding Process Source: https://docs.paynow.pl/docs/reference/v3/init-boarding-process Initiates the seller boarding process. This endpoint requires authentication and specific request body parameters. ```APIDOC ## POST https://api.sandbox.paynow.pl/v3/boarding/merchants/sellers/init ### Description Initializes the seller boarding process. ### Method POST ### Endpoint https://api.sandbox.paynow.pl/v3/boarding/merchants/sellers/init ### Parameters #### Header Parameters - **Api-Key** (string) - Required - Unique key used to authenticate API requests. - **Signature** (string) - Required - The Signature header is used to ensure the request’s body integrity and to confirm that its content has not changed. - **Accept** (string) - Required - The Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand. Can be set to `*/*`. - **Content-Type** (string) - Required - The Content-Type entity header is used to indicate the media type of the resource. Must be `application/json`. #### Request Body - **nip** (string) - Required - Polish tax identification number. Possible values: `>= 10 characters` and `<= 10 characters`. - **notificationUrl** (string) - Optional - The URL that the status notification will be sent to. Possible values: `<= 1000 characters`. ``` -------------------------------- ### Initialize Seller Boarding Source: https://docs.paynow.pl/docs/v3/marketplace Initiates the seller boarding process by providing the seller's NIP. The API returns a unique seller ID, an application URL for the seller to complete the process, and the initial status. ```APIDOC ## POST /v3/boarding/merchants/sellers/init ### Description Initiates the seller boarding process. After initiation, the Paynow system returns a `sellerApplicationUrl` to which the customer should be redirected to complete registration, identity verification, and settlement account verification. ### Method POST ### Endpoint /v3/boarding/merchants/sellers/init ### Parameters #### Request Body - **nip** (string) - Required - The seller's tax identification number. - **notificationUrl** (string) - Optional - URL for seller status notifications. ``` -------------------------------- ### Generic Error Schema Example Source: https://docs.paynow.pl/docs/reference/v3/send-cancel-request This is a generic schema example for various error types, including CONFLICT, FORBIDDEN, NOT_FOUND, RATE_LIMIT_REACHED, SYSTEM_TEMPORARILY_UNAVAILABLE, VALIDATION_ERROR, VERIFICATION_FAILED, IDEMPOTENCY_KEY_MISSING, SIGNATURE_MISSING, INVALID_PAYMENT_STATUS, and INVALID_PAYMENT_TRANSFER_STATUS. ```json { "statusCode": 0, "errors": [ { "errorType": "CONFLICT", "message": "string", "value": "string" } ] } ``` -------------------------------- ### Get Payment Status with API Key Source: https://docs.paynow.pl/docs/reference/v3/get-payment-status This C# snippet demonstrates how to make a GET request to the /v3/payments/:paymentId/status endpoint. Ensure you replace placeholders like {{apiKey}}, {{calculatedSignature}}, and {{idempotencyKey}} with your actual values. The 'Accept' header is set to 'application/json'. ```csharp var client = new HttpClient(); var request = new HttpRequestMessage(HttpMethod.Get, "https://api.sandbox.paynow.pl/v3/payments/:paymentId/status"); request.Headers.Add("Accept", "application/json"); request.Headers.Add("Api-Key", "{{apiKey}}"); request.Headers.Add("Signature", "{{calculatedSignature}}"); request.Headers.Add("Idempotency-Key", "{{idempotencyKey}}"); var response = await client.SendAsync(request); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync()); ``` -------------------------------- ### Request Body for Seller Onboarding Initialization Source: https://docs.paynow.pl/docs/reference/v3/init-boarding-process The request body must include the seller's Polish tax identification number (nip). Optionally, you can provide a notificationUrl for status updates. The nip must be exactly 10 characters long. ```json { "nip": "string (required)", "notificationUrl": "string" } ``` -------------------------------- ### Get Seller Application Status API Endpoint Source: https://docs.paynow.pl/docs/reference/v3/get-application-status Use this GET request to retrieve the status of a seller's application. Replace ':sellerId' with the actual seller's ID. Ensure you include the required 'Api-Key', 'Signature', 'Accept', and 'Content-Type' headers for authentication and proper request handling. ```http GET ## https://api.sandbox.paynow.pl/v3/boarding/merchants/sellers/:sellerId ``` -------------------------------- ### Get Seller Balances Source: https://docs.paynow.pl/docs/v3/marketplace Retrieves the current balance and escrow amount for a specific seller. ```APIDOC ## GET /v3/balances/sellers/{sellerId} ### Description Retrieves the balance and escrow amounts for a given seller. ### Method GET ### Endpoint /v3/balances/sellers/{sellerId} ### Parameters #### Path Parameters - **sellerId** (string) - Required - The unique identifier of the seller. ### Response #### Success Response (200) - **balance.amount** (integer) - The seller's available balance. - **escrow.amount** (integer) - The seller's balance frozen in escrow. ### Response Example ```json { "balance": { "amount": 500 }, "escrow": { "amount": 100 } } ``` ``` -------------------------------- ### Making a Payment Request with cURL Source: https://docs.paynow.pl/docs/v3/payments Example of how to make a POST request to the Paynow payments endpoint using cURL. Ensure correct headers like Api-Key, Signature, and Idempotency-Key are included. ```bash curl --request POST 'https://api.sandbox.paynow.pl/v3/payments' \ -H 'Content-Type: application/json' \ -H 'Api-Key: 97a55694-5478-43b5-b406-fb49ebfdd2b5' \ -H 'Signature: lGOrwYvoRYwWcKSEtE/YDn8go1w/i5dj8Rv/ytIvXVE=' \ -H 'Idempotency-Key: 59c6dd26-f905-487b-96c9-fd1d2bd76885' \ --data-raw '{ "amount": 45671, "externalId": "234567898654", "description": "Test transaction", "buyer": { "email": "jan.kowalski@melements.pl" } }' ``` -------------------------------- ### Get Refund Status Source: https://docs.paynow.pl/docs/reference/v3/get-refund-status Fetches the status of a specific refund using its unique ID. ```APIDOC ## GET /v3/refunds/{refundId}/status ### Description Retrieves the current status of a refund transaction. ### Method GET ### Endpoint /v3/refunds/{refundId}/status ### Parameters #### Path Parameters - **refundId** (string) - Required - Unique ID of a refund generated by Paynow ### Response #### Success Response (200) - **refundId** (string) - Required - Unique ID of a refund generated by Paynow - **status** (RefundStatus) - Required - Current status of the refund. Possible values: [`NEW`, `PENDING`, `SUCCESSFUL`, `FAILED`, `CANCELLED`] - **failureReason** (FailureReason) - Optional - Refund failure reason. Possible values: [`CARD_BALANCE_ERROR`, `BUYER_ACCOUNT_CLOSED`, `OTHER`] #### Response Example ```json { "refundId": "REFA-321-123-888", "status": "SUCCESSFUL" } ``` #### Error Responses - **400 Bad Request**: Returned when the request is malformed or contains invalid data. - **401 Unauthorized**: Returned when authentication credentials are invalid or missing. - **404 Not Found**: Returned when the specified refund ID does not exist. - **500 Internal Server Error**: Returned when an unexpected error occurs on the server. - **503 Service Unavailable**: Returned when the service is temporarily unavailable. ```