- METHOD TYPEE-wallet
- PAYMENTS
- PAYOUTS
- REFUNDS
- RECURRING
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¤cy=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¤cy=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
andemail
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=¤cy=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=¤cy=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
- The user logs in to their Aircash app and selects the “Marketplace” option.
- The user selects the supported shop or site to which money must be sent.
- The user enters the amount to pay and the shop or site identification, which can be username, email, or ID, and press PAY.
- 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).
- If approved, the user receives an approval message on the app.
Payment with Cashier
- The user is redirected to a QR page.
- The user either scans the QR code with the App (desktop flow) or presses the code to activate the Aircash App (mobile flow).
- 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.