DOCSEARCHbyAlgolia
Submit Docs

PayNow API Reference

website·Indexed 35 days ago

https://docs.paynow.pl

Documentation for the PayNow payment gateway, featuring API version 3.0.5 and legacy version 1. Includes guides and endpoints for creating payments, managing refunds, card tokenization, white label payments, payment links, and GDPR clause retrieval.

Tokens
23K
Snippets
89
Records
147
Agent score
60%

What's inside PayNow

  1. Overview of Paynow Marketplace functionality

    v3
    Paynow Marketplace allows platforms (partners) to process single transactions involving multiple sellers. The system automatically splits funds based on defined transfers to each participating seller.

  2. Overview of Paynow Card Tokenization

    v3
    Card tokenization allows merchants to save card data as a unique token, enabling customers with shop accounts to process subsequent payments without re-entering card details. Tokenization occurs on the Paynow page after redirection. Payments with saved cards can be handled via the Paynow paywall or via a 'White Label' model where the card is selected directly in the shop checkout.

  3. Get started with Paynow API integration

    Paynow (part of the mBank Group) provides secure payment services for e-commerce. Developers can access the following resources to begin integration:

    • API Documentation: General integration and usage descriptions.
    • API Reference: Detailed descriptions of Paynow API endpoints.
    • Postman Workspace: A repository of Postman collections containing API usage examples.
    • Business FAQ: Information regarding payments for business operations.

    For technical support, contact support@paynow.pl.

  4. Understand the Paynow Multi-payouts model

    v3

    Multi-payouts is a payment model for a closed group of sellers operating under one shared URL. It allows a customer to make a single payment that is automatically split between multiple legal entities (each with their own seller accounts) or distributed across multiple payout accounts for a single merchant.

    Key characteristics include:

    • Hierarchy: Consists of one Lead entity and one or more Additional entities.
    • Customer Experience: The buyer sees a single checkout and is unaware of the internal payment split.
    • Fund Distribution: Paynow performs the split based on instructions from the lead entity.
    • Commissions: Paynow can deduct and pass a commission from additional entities to the lead entity for platform maintenance.
    • Refunds: All refunds are initiated via the lead entity's API access.

  5. Understand PayNow Payments API architecture

    The PayNow Payments API follows the REST architectural pattern. All communication between the server and clients is conducted via JSON messages. Request data must be included within the body of the HTTP requests.

  6. Handle GDPR compliance for White Label payments

    v1

    Because White Label payments bypass the Paynow payment page, the merchant is responsible for displaying legally required GDPR information about the payment operator.

    1. Retrieve the GDPR clauses from the Notices endpoint. This content can be cached but should not be hardcoded.
    2. Display the title and content of the notice to the buyer on the store's website.
    3. Send a link to the store and a screenshot of the embedded GDPR clauses to support@paynow.pl for verification.

    Failure to complete this verification will result in the White Label feature being disabled. In that case, providing an authorizationCode for BLIK payments will trigger a BAD_REQUEST error.

    {
  "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...",
  "locale": "en-GB"
}

  7. Set up and integrate Multi-payouts

    v3

    To integrate Multi-payouts, follow these steps:

    1. Create a sandbox account at https://panel.sandbox.paynow.pl/auth/register.
    2. Contact Paynow support via email (support@paynow.pl) to activate the Multi-payouts feature.
    3. Confirm the shared URL used by the cooperating entities.
    4. Specify the number of additional entities required.
    5. Retrieve your API credentials.
    6. Integrate with the Paynow API.
    7. Test both positive and negative payment paths.
    8. Test the refund process on your platform.

  8. Implement White Label Pay-by-Link (PBL) and PayPo payments

    v3
    To use White Label for PBL and PayPo methods, create a payment using a predefined payment method following the standard process for predefined payment methods.

  9. Implement White Label BLIK payments

    v3
    White Label integration for BLIK allows buyers to enter their authorization code directly on the store's website instead of being redirected to a payment gateway. To implement this, you must first retrieve the list of payment methods to identify the BLIK method where authorizationType is equal to CODE. When creating the payment request, you must include the authorizationCode field.
    {
  "amount": "409272",
  "externalId": "c7b55386-ba45-4537-96a5-bb77c6910418",
  "paymentMethodId": 2007,
  "currency": "PLN",
  "description": "Testowa transakcja",
  "continueUrl": "https://melements.pl",
  "buyer": {
    "email": "jan.kowalski@melements.pl",
    "firstName": "Jan",
    "lastName": "Kowalski",
    "locale": "pl-PL",
    "phone": {
      "prefix": "+48",
      "number": "120932212"
    }
  },
  "authorizationCode": "123456"
}

  10. Process payments and refunds with Multi-payouts

    v3

    Multi-payouts uses the same logic and request structure as the Paynow Marketplace integration. To process a payment or refund, use the Marketplace API structures where each sellerId in the request is assigned to a specific Additional entity.

    Important Considerations for Refunds:

    • It is recommended to check seller balances before initiating a refund.
    • You can enable 'Awaiting refunds' in the shop settings via the Paynow Merchant Panel.

  11. Update Paynow plugins for saved card payments

    v3

    To support saved card payments, ensure your Paynow plugin is updated to at least the following versions (latest versions are recommended):

    • Prestashop: 1.7.1 or higher
    • Woocommerce: 2.5.1 or higher
    • Magento: 1.5.0 or higher

  12. Handle asynchronous payment status notifications

    v3
    Paynow sends asynchronous notifications via HTTP POST requests to a configured notification URL whenever a payment status changes. To ensure security and message integrity, your system must validate the Signature header of every incoming notification; if the calculated signature does not match the header value, the message should be ignored.
    # Example of a notification message received by your server
curl -X POST \
<notification URL> \
-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": "2024--06-01T13:24:52"
}'