Attributes

• METHOD TYPEE-commerce
• PAYMENTS
• PAYOUTS
• REFUNDS
• RECURRING

Introduction

Instant Swiss Payout is an instant payment method used for domestic payouts in Switzerland. Instant payments enable real-time transfers between accounts, eliminating traditional banking delays.

Supported Countries

• Switzerland

Supported Currencies

• CHF

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":"CH",
  "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 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 – Unique customer identifier in the merchant’s system.
• paymentMethodName: “apmgw_InstantSwissPayout“
• apmData block containing:
  • postFinanceIban– IBAN for the user’s bank account

Example /addUPOAPM Request

{
  "merchantSiteId": "<your merchantSiteId>",
  "merchantId": "<your merchantId>",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "timeStamp": "<YYYYMMDDHHmmss>",
  "apmData": {
    "postFinanceIban": "CH7809000000770137905"
  },
  "paymentMethodName": "apmgw_InstantSwissPayout",
  "checksum": "<calculated checksum>"
}

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

Example /addUPOAPM Response

{
  "internalRequestId": 958495268,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "5970183043540730700",
  "merchantSiteId": "238459",
  "version": "1.0",
  "clientRequestId": "20240318091527",
  "userPaymentOptionId": 106005808
}

3. Send a /payout Request

Send a /payout request and include the userPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.

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.

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=45135281&userid=PostFinanceApprovedWDViaREST&merchant_unique_id=20180327175242&customData=IvanSite&productId=&first_name=&last_name=&email=&currency=CHF&pmDisplayName=CH7809000000770137905&clientUniqueId=20180327175242&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=&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=253281&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_InstantSwissPayout&ID=&merchant_id=2716997754195194041&responseTimeStamp=2025-02-24.08%3A57%3A48&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Credit&externalEmail=&cardCompany=&eci=&user_token_id=PostFinanceApprovedWDViaREST&userPaymentOptionId=2153726631&TransactionID=2610000000000148913&externalTransactionId=P3sc_DSPd87XwyIZCN_GoYlCTml8Nw2Z7dBS&totalAmount=17.15&dynamicDescriptor=QA+Test+site&feeAmount=&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=&maskedNetworkTokenNumber=&upoRegistrationDate=20250224&type=DEPOSIT&clientRequestId=&relatedTransactionId=&responsechecksum=4f453930f3c3fb38848180c1ab1ba183&advanceResponseChecksum=c5cde9684013f79a154d721c4ce1a357',

User Experience

Payout

• The user enters the following parameters:
  • Withdrawal amount
  • IBAN

Testing

• For testing approved payout transactions:
  • IBAN: CH7809000000770137905
  • First name: Matias
  • Last Name: Simeon-PF
  • Address: 4102 Binningen
• For testing declined payout transactions:
  • IBAN: CH0809000000770136352
  • First name: Magnus
  • Last Name: Küng-PF
  • Address: 6362 Stansstad