Introduction

Przelewy24 is a Polish Internet service that provides real-time online payments with low risk of returns to the merchants. It is a chargeback risk-free option that does not require any additional personal information. It provides a trusted payment method familiar to consumers in Poland and the convenience of paying in their local currency.

Supported Countries

• Poland

Supported Currencies

• PLN

Payment (Deposit) Flow

Follow these steps to perform a payment using Nuvei REST API integration:

1. Generate a sessionToken

Press here for details.

2. Send a /payment Request

Perform the payment by sending a /payment request with its mandatory parameters including:

• userTokenId
• amount
• currency
• paymentOption.alternativePaymentMethod class containing:
  • paymentMethod: “apmgw_P24“
• deviceDetails class containing: ipAddress
• billingAddress class containing: firstName, lastName,  country, email
• userDetails class containing: firstName, lastName,  country, email

Marketplace merchants must also include the marketplace addendum with its mandatory parameters, including subMerchantId. With certain providers, if the request includes subMerchantName, Nuvei sends it to the provider as the point of sale, up to 50 characters. Otherwise, Nuvei sends subMerchantId.

Example /payment Request

{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "amount":"200",
  "currency":"PLN",
  "userTokenId":"<unique customer identifier in merchant system>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "paymentOption":{
    "alternativePaymentMethod":{
      "paymentMethod":"apmgw_P24"
    }
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "country": "PL",
    "email": "[email protected]"
  },
  "userDetails":{
    "firstName": "John",
    "lastName": "Smith",
    "country": "PL",
    "email": "[email protected]"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

The response generates and returns a redirect URL (redirectUrl) to redirect the customer to the payment page, as well as a UPO (userPaymentOptionId) for use in future transactions.

Example /payment Response

{
  "internalRequestId": 34214681,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "5634436935940029474",
  "merchantSiteId": "242181",
  "version": "1.0",
  "sessionToken": "cda8f9f8-8850-4d06-8c93-21321034a78c",
  "orderId": "41282111",
  "userTokenId": "TeoTokenRESTnewv2_P24",
  "paymentOption": {
    "redirectUrl": "https://sandbox.przelewy24.pl/trnRequest/B7A8D57BC5-2262D4-6421FE-FCCE9723AF",
    "userPaymentOptionId": "2153040561",
    "card": {}
  },
  "transactionStatus": "REDIRECT"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payment request.

Example Payment DMN with Status=APPROVED

...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=41282111&userid=TeoTokenRESTnewv2_P24&merchant_unique_id=&customData=&productId=&first_name=John&last_name=Doe&email=teo%40test.com&currency=PLN&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=65%2C%C2%A0Overlea%C2%A0str&address2=&country=Poland&state=&city=Toronto&zip=K0A%C2%A00A2&phone1=&phone2=&phone3=&client_ip=&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=P24MS-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=&shippingState=&shippingCity=&shippingAddress=&shippingZip=&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=242181&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_P24&ID=&merchant_id=5634436935940029474&responseTimeStamp=2023-10-10.14%3A43%3A43&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=TeoTokenRESTnewv2_P24&userPaymentOptionId=2153040561&TransactionID=2110000000011204978&externalTransactionId=4295408779&APMReferenceID=64F24171BD09CD9DF3CBBE746B0F4D02&orderTransactionId=22862821&totalAmount=7.00&dynamicDescriptor=static+test&item_name_1=NA&item_number_1=&item_amount_1=7.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&externalToken_blockedCard=&externalToken_cardAcquirerId=&externalToken_cardAcquirerName=&externalToken_cardBin=&externalToken_cardBrandId=&externalToken_cardBrandName=&externalToken_cardExpiration=&externalToken_cardLength=&externalToken_cardMask=&externalToken_cardName=&externalToken_cardTypeId=&externalToken_cardTypeName=&externalToken_clubName=&externalToken_creditCompanyId=&externalToken_creditCompanyName=&externalToken_extendedCardType=&externalToken_Indication=&externalToken_tokenValue=&externalToken_tokenProvider=&ECIRaw=&cryptogram=&upoRegistrationDate=20231005&type=DEPOSIT&clientRequestId=&relatedTransactionId=&sessionId=a0a459c43e90b67758ac261be6fb&responsechecksum=446cfbf0aa4a7511b415d8e888603bba&advanceResponseChecksum=711f71778a59049092f69696ad005b71',

Payout (Withdrawal) Flow

Follow these steps to perform a payout using Nuvei REST API integration:

1. Register a userTokenId

A userTokenId is a field in the Nuvei system containing the user’s identifier in the merchant system.

If you do not have a userTokenId registered in the Nuvei system for this user, then register one by sending a /createUser request, including email, countryCode, firstName, and lastName.

Example /createUser Request

{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "userTokenId":"<unique user identifier in merchant system>",
  "email":"[email protected]",
  "countryCode":"PL",
  "firstName":"John",
  "lastName":"Smith",
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

Example /createUser Response

{
  "userId":78403498,
  "internalRequestId":552360538,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"2439523627382132721",
  "merchantSiteId":"224428",
  "version":"1.0",
  "clientRequestId":"20221108130736"
}

The request registers the userTokenId (userId) in the Nuvei system, which is needed to generate a UPO in the next step.

2. Create the UPO

Create a UPO by sending an /addUPOAPM request and include:

• userTokenId – The unique user identifier in your system.
• paymentMethodName: “apmgw_P24“
• apmData class containing:
  • p24_iban – User’s IBAN
• billingAddress class containing: country and email

Example /addUPOAPM Request

{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "userTokenId":"<unique customer identifier in merchant system>",
  "paymentMethodName":"apmgw_P24",
  "apmData":{
    "p24_iban":"<user's IBAN>"
  },
  "billingAddress":{
    "country":"PL",
    "email":"[email protected]",
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

The request returns an encrypted userPaymentOptionId (UPO) representing the user’s APM account details.

Example /addUPOAPM Response

{
  "userPaymentOptionId":83458468,
  "internalRequestId":553078068,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"2439523627382132721",
  "merchantSiteId":"224428",
  "version":"1.0",
  "clientRequestId":"20221109154215"
}

3. Send a /payout Request

Send a /payout request and include:

• userPaymentOptionId, which contains the user’s previously stored APM account details.
• userDetails class containing firstName, lastName, email, address, city, and zip.

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.

User Experience

Payment

1. The user is redirected to the Przelewy24 website.
   
2. The user selects a bank or other payment option.
   
3. The user reviews and confirms the details of the payment.
   
4. The user is redirected to the website of the bank or payment option.
   The user experience is different according to bank or payment option. This example reflects the user experience for BLIK.
   
5. The user confirms the payment in the BLIK (or bank) mobile app.
   
6. The user receives confirmation the payment was completed.
   

Testing

Test credentials and testing scenarios can be provided by Nuvei if necessary. You can contact Nuvei support for assistance.