Introduction

The Instant Bank Payments APMs are tailored for the Nordic and Baltic regions, supporting local transactions in Sweden, Denmark (payouts only), Estonia, and Finland. They enable businesses to process payments directly to recipients’ bank accounts, ensuring fast, secure, and efficient transactions that align with local banking systems and preferences.

Supported Countries

Sweden
Denmark
Estonia
Finland

Supported Currencies

Payment (Deposit) Flow

If you wish to perform a payout transaction in the future, you need to use the same userTokenId and userPaymentOptionId values that are generated in this payment transaction.

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 – Must be the three-letter ISO code for the currency supported by the paymentMethod.

paymentOption.alternativePaymentMethod class containing:

`paymentMethod`	Supported Country	Supported Currency
`paymentMethod`: "apmgw_Instant_Bank_Payments_SE"	Sweden	SEK
`paymentMethod`: "apmgw_Instant_Bank_Payments_EE"	Estonia	EUR
`paymentMethod`: "apmgw_Instant_Bank_Payments_FI"	Finland	EUR

Payments (deposits) not supported in Denmark.

deviceDetails class containing: ipAddress
billingAddress class containing: firstName, lastName, country, email – country must be the two-letter ISO code for the country supported by the paymentMethod.
userDetails class containing: firstName, lastName, country, email – country must be the two-letter ISO code for the country supported by the paymentMethod.

Example `/payment` Request

{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientRequestId": "<unique request ID in merchant system>",
  "amount": "200",
  "currency": "SEK",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "paymentOption": {
    "alternativePaymentMethod": {
      "paymentMethod": "apmgw_Instant_Bank_Payments_SE"
    }
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "country": "SE",
    "email": "[email protected]"
  },
  "userDetails": {
    "firstName": "John",
    "lastName": "Smith",
    "country": "SE",
    "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": 40308821,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "5416795427517477813",
  "merchantSiteId": "186111",
  "version": "1.0",
  "clientRequestId": "20240419090923",
  "sessionToken": "11cb82d9-7da8-49c1-aec6-7516e1842b95",
  "orderId": "42932311",
  "paymentOption": {
    "redirectUrl": "https://checkout-sandbox.zimpler.net/v4/se/deposit/8afce8fb1eb40b95c77f",
    "userPaymentOptionId": "2153232561",
    "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=42932311&userid=&merchant_unique_id=&customData=&productId=&first_name=Fname&last_name=Lname&email=test%40mymail.com&currency=SEK&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Sancho+el+fuerte+15&address2=&country=Sweden&state=&city=Stockholm&zip=%24%7BzipU%7D&phone1=0987654321&phone2=&phone3=&client_ip=93.146.254.172&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=ZimplerMS-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=SE0950516241337264&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=186111&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_Instant_Bank_Payments_SE&ID=&merchant_id=5416795427517477813&responseTimeStamp=2024-04-19.06%3A10%3A30&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&userPaymentOptionId=&TransactionID=2610000000000021200&externalTransactionId=8afce8fb1eb40b95c77f&APMReferenceID=D03D83ECA11D1085B14465D16297854F&orderTransactionId=24340451&totalAmount=10.00&dynamicDescriptor=hristo+descriptor&item_name_1=NA&item_number_1=&item_amount_1=10.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&type=DEPOSIT&clientRequestId=20240419090923&relatedTransactionId=&sessionId=4f94e29fbf1832b85454e366d961&responsechecksum=be9489f6727cc0f12c33b67c41786e77981777cd3b58f5a5e7d51093f444ff7e&advanceResponseChecksum=56ee3fa26331e8f69d95268b888330b5cc263ffb4e68301428629e29f2861df0',

Example Payment DMN with `Status`=PENDING

...'ppp_status=PENDING&Status=PENDING&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=42932761&userid=&merchant_unique_id=&customData=&productId=&first_name=Fname&last_name=Lname&email=test%40mymail.com&currency=EUR&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Sancho+el+fuerte+15&address2=&country=Estonia&state=&city=Tallinn&zip=%24%7BzipU%7D&phone1=0987654321&phone2=&phone3=&client_ip=93.146.254.172&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=ZimplerMS-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=186111&merchant_status=&action=&requestVersion=&message=PENDING&merchantLocale=&unknownParameters=&payment_method=apmgw_Instant_Bank_Payments_EE&ID=&merchant_id=5416795427517477813&responseTimeStamp=2024-04-19.06%3A57%3A30&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&userPaymentOptionId=&TransactionID=2610000000000021212&externalTransactionId=28149aa2ffdae78ba0a5&APMReferenceID=4ECB4500239572DD2D2652AD26ABE9C0&orderTransactionId=24340571&totalAmount=10.00&dynamicDescriptor=hristo+descriptor&item_name_1=NA&item_number_1=&item_amount_1=10.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&type=DEPOSIT&clientRequestId=20240419095649&relatedTransactionId=&sessionId=524bd866fb1d3083cbf84a8b0557&responsechecksum=50e6dbb6df7b08e9cb12b3c3dc36125aefc4d9a3cda39773d57f844a38a3a4dc&advanceResponseChecksum=07bfbefa61d1c470764081b0b2d1aca1121971029a02f18bf206823515527d71',

Payout (Withdrawal) Flow

To perform a payout with Instant Bank Payments using Nuvei REST API integration, you need to collect the customer’s bank account details using the /accountCapture method before sending the /payout request:

Generate a sessionToken. Press here for details.

Send an /accountCapture request that includes the following mandatory fields as shown in the example request below:

userTokenId – Unique customer identifier in merchant system.

`paymentMethod`	Supported Country	Supported Currency
`paymentMethod`: "apmgw_Instant_Bank_Payments_SE"	Sweden	SEK
`paymentMethod`: "apmgw_Instant_Bank_Payments_DK"	Denmark	DKK
`paymentMethod`: "apmgw_Instant_Bank_Payments_EE"	Estonia	EUR
`paymentMethod`: "apmgw_Instant_Bank_Payments_FI"	Finland	EUR

currencyCode – Must be the three-letter ISO code for the currency supported by the paymentMethod.

countryCode – Must be the two-letter ISO code for the country supported by the paymentMethod.

Example `/accountCapture` Request

{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique customer identifier in merchant system>",
  "paymentMethod": "apmgw_Instant_Bank_Payments_DK",
  "currencyCode": "DKK",
  "countryCode": "DK"
}

The response include a redirectUrl.

Example `/accountCapture` Response

{
  "internalRequestId": 40319601,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "5416795427517477813",
  "merchantSiteId": "186111",
  "version": "1.0",
  "sessionToken": "0bf52704-9ee1-4115-88d2-a5d40ad04c2a",
  "redirectUrl": "https://checkout-sandbox.zimpler.net/v4/dk/accounts/91c2e3f990ade789b793",
  "userTokenId": "IBP_DK1"
}

Use redirectUrl to redirect the customer to the APM provider’s account details capture page.
The customer enters account details.
Nuvei stores the data in a userPaymentOptionId (UPO) identifier, and sends a DMN with the newly created userPaymentOptionId to urlDetails.notificationUrl, which Nuvei recommends including in the /accountCapture request.
Send a /payout request and include the userPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.

Example Payout DMN with `Status`=Approved

...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=&PPP_TransactionID=42937331&userid=IBP_DK1&merchant_unique_id=20180327175242&customData=hristo_tr_test&productId=&first_name=&last_name=&email=&currency=DKK&pmDisplayName=DK5000400440116243&clientUniqueId=20180327175242&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=DK&state=&city=&zip=&phone1=&phone2=&phone3=&client_ip=&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&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=186111&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_Instant_Bank_Payments_DK&ID=&merchant_id=5416795427517477813&responseTimeStamp=2024-04-19.11%3A32%3A46&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Credit&externalEmail=&cardCompany=&eci=&user_token_id=IBP_DK1&userPaymentOptionId=2153196941&TransactionID=2610000000000021295&externalTransactionId=5dcf3cdf-a69e-43df-807a-02562e42b09c&totalAmount=10.0&dynamicDescriptor=hristo+descriptor&feeAmount=&houseNumber=&customCurrency=&upoRegistrationDate=20240419&type=DEPOSIT&clientRequestId=&relatedTransactionId=&responsechecksum=8cf73edaae202fd8bfe15120f069b7f5589d9268d859f880c36d332f0591f553&advanceResponseChecksum=d24bb8ac97e140bf4d263500d7e190d50e1994f47e88cbc142866f7650a0ce3e',