Introduction

Aircash is a financial ICT platform based in Croatia and approved by the Croatian National Bank. It is valid in the European Union for payments and payouts between Croatian citizens.

Supported Countries

• Austria
• Belgium
• Bosnia-Herzegovina
• Bulgaria
• Croatia
• Cyprus
• Czech Republic
• Denmark
• Estonia
• Finland
• France
• Germany
• Greece
• Hungary
• Ireland
• Italy
• Kosovo
• Latvia
• Lithuania
• Luxembourg
• Macedonia
• Malta
• Montenegro
• Netherlands
• Poland
• Portugal
• Romania
• Serbia
• Slovakia
• Slovenia
• Spain
• Sweden

Supported Currencies

• BAM
• BGN
• CZK
• DKK
• EUR
• HUF
• PLN
• RON
• RSD
• SEK

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 block containing:
  • paymentMethod: “apmgw_Aircash“
• deviceDetails block containing: ipAddress
• billingAddress block containing: firstName, lastName, country, email
• userDetails block containing: firstName, lastName, country, email

Example /payment Request

{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "amount":"100",
  "currency":"EUR",
  "userTokenId":"<unique customer identifier in merchant system>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "paymentOption":{
    "alternativePaymentMethod":{
      "paymentMethod":"apmgw_Aircash"
    }
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "billingAddress":{
    "firstName": "John",
    "lastName": "Smith",
    "country":"FR",
    "email":"[email protected]"
  },
  "userDetails":{
    "firstName": "John",
    "lastName": "Smith",
    "country":"FR",
    "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

{
  "orderId":"350866838",
  "userTokenId":"Johnsmith02",
  "paymentOption":{
    "redirectUrl":"https://stage-frame.aircash.eu/56af2066-6bad-4076-b440-7882aad2179f",
    "userPaymentOptionId":"86087958",
  },
  "transactionStatus":"REDIRECT",
  "sessionToken":"9df79d89-b5e1-43f5-9743-b77a3633286c",
  "clientUniqueId":"20180327175242",
  "internalRequestId":594576168,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"2439523627382132721",
  "merchantSiteId":"224428",
  "version":"1.0",
  "clientRequestId":"20230118060805"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to the URL provided in urlDetails.notification, 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=350866838&userid=Johnsmith02&merchant_unique_id=20180327175242&customData=&productId=&first_name=John&last_name=Smith&email=JohnS%40test.com&currency=EUR&clientUniqueId=20180327175242&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Test+Street&address2=&country=France&state=&city=Yambol&zip=80410100&phone1=11111122200&phone2=&phone3=&client_ip=127.0.0.1&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Aircash+Direct&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=224428&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_Aircash&ID=&merchant_id=2439523627382132721&responseTimeStamp=2023-01-18.11%3A11%3A09&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Johnsmith02&userPaymentOptionId=86087958&TransactionID=711000000019096968&APMReferenceID=17DE6C15ADF17B000AE1A7B9D22AFA0C&orderTransactionId=1177543818&totalAmount=100.00&dynamicDescriptor=test&item_name_1=NA&item_number_1=&item_amount_1=100.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20230117&type=DEPOSIT&clientRequestId=20230118060805&relatedTransactionId=&sessionId=48fee1236f56e8eecf27be21fbf1&responsechecksum=2056d7654cb48ed55f07b2b566486e8562d54c2745e83023c1f27ca06550bfee&advanceResponseChecksum=deec74aa370b64ff0f3bcb2fee44773f73b26c6b67a9e9cf644f67d036f735e6',

Example /payment DMN with status=DECLINED

...'ppp_status=FAIL&Status=DECLINED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=9999&errScDescription=Default&Reason=Default&ReasonCode=9999&PPP_TransactionID=350794178&userid=Johnsmith02&merchant_unique_id=20180327175242&customData=&productId=&first_name=John&last_name=Smith&email=JohnS%40test.com&currency=EUR&clientUniqueId=20180327175242&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Test+Street&address2=&country=France&state=&city=Yambol&zip=80410100&phone1=11111122200&phone2=&phone3=&client_ip=127.0.0.1&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Aircash+Direct&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=224428&merchant_status=&action=&requestVersion=&message=DECLINED&merchantLocale=&unknownParameters=&payment_method=apmgw_Aircash&ID=&merchant_id=2439523627382132721&responseTimeStamp=2023-01-17.19%3A55%3A04&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Johnsmith02&userPaymentOptionId=86087958&TransactionID=711000000019072855&APMReferenceID=E25FDE7D25C05D0B87CF4F1993831404&orderTransactionId=1177447718&totalAmount=100.00&dynamicDescriptor=test&item_name_1=NA&item_number_1=&item_amount_1=100.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20230117&type=DEPOSIT&clientRequestId=20230117142204&relatedTransactionId=&sessionId=12afa8debcc12c8e5172c62fecea&responsechecksum=a26915868d61ec1fe8636d84d6eb689d71269a13812a97367ae80c4d12e0f0a8&advanceResponseChecksum=8ad42cea67954b3299af5f3f775deccad47d42d33259bd5f13c1ad610358e1ce',

Payout (Withdrawal) Flow

Follow these steps to perform a payout:

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":"<2-letter ISO country code>",
  "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_Aircash“
• apmData block containing:
  • Aircash_phone – The country code (without+) and the number (for example: 385981234567)
• billingAddress block 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_Aircash",
  "apmData":{
    "Aircash_phone": "385981234567",
  },
  "billingAddress":{
    "country":"FR",
    "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 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 DMN that includes the result of the transaction to the URL provided in urlDetails.notification, 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=0&PPP_TransactionID=350867998&userid=Johnsmith02&merchant_unique_id=20180327175242&customData=Jake+Test+Account&productId=&first_name=&last_name=&email=&currency=EUR&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=null&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=224428&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_Aircash&ID=&merchant_id=2439523627382132721&responseTimeStamp=2023-01-18.11%3A15%3A10&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=null&transactionType=Credit&externalEmail=&cardCompany=&user_token_id=Johnsmith02&userPaymentOptionId=86088908&TransactionID=711000000019097108&externalTransactionId=ed3ef198-402e-406c-a70e-fdbefd8ba3aa&totalAmount=100.0&dynamicDescriptor=test&feeAmount=&houseNumber=&customCurrency=&upoRegistrationDate=20230117&type=DEPOSIT&clientRequestId=20230118061540&relatedTransactionId=&responsechecksum=e093e1f19202fd877c82acfed8c31aefffc9035bc6dda0797196a466b888e75b&advanceResponseChecksum=d751c8c6cfce8966319ac36add99cdf752a01243cd0ff7e516afd3d36f12274b',

Example /payout DMN with status=DECLINED

...'ppp_status=FAIL&Status=DECLINED&ExErrCode=0&ErrCode=1&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=Unexpected+error%2C+please+contact+helpdesk&ReasonCode=0&PPP_TransactionID=350620268&userid=guyporateur2&merchant_unique_id=20180327175242&customData=Jake+Test+Account&productId=&first_name=&last_name=&email=&currency=EUR&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=null&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=224428&merchant_status=&action=&requestVersion=&message=DECLINED&merchantLocale=&unknownParameters=&payment_method=apmgw_Aircash&ID=&merchant_id=2439523627382132721&responseTimeStamp=2023-01-16.12%3A37%3A16&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=null&transactionType=Credit&externalEmail=&cardCompany=&user_token_id=guyporateur2&userPaymentOptionId=86033728&TransactionID=811000000001727208&totalAmount=20.0&dynamicDescriptor=test&feeAmount=&houseNumber=&customCurrency=&upoRegistrationDate=20230116&type=DEPOSIT&clientRequestId=&relatedTransactionId=&responsechecksum=bd77ce76ec0e1118e799bfd4a7d344dc7d61d0055856771d91de717a48513c49&advanceResponseChecksum=3fcaa72799578c4d4eca33d64b141fd06c719d992480c828f503519e0978591a',

User Experience

Payment with App

1. The user logs in to their Aircash app and selects the “Marketplace” option.
   
2. The user selects the supported shop or site to which money must be sent.
   
3. The user enters the amount to pay and the shop or site identification, which can be username, email, or ID, and press PAY.
   
4. The user presses PAY to confirm the transaction details.
   
   The transaction request is sent to the merchant to approve or reject.
   • If approved, the user receives an approval message on the app.
     
   • If rejected, the user sees an error message (with the reason if provided).

Payment with Cashier

1. The user is redirected to a QR page.
   
2. The user either scans the QR code with the App (desktop flow) or presses the code to activate the Aircash App (mobile flow).
3. The user presses the Pay button to complete the transaction.
   
   A success message appears and then closes automatically.
   

Testing

Please contact Aircash to obtain a test application.