- METHOD TYPEE-wallet
- PAYMENTS
- PAYOUTS
- REFUNDS
- RECURRING
Introduction
PayWithCrypto allows making payments using crypto currencies such as Bitcoin. Crypto currencies are digital currencies that use cryptography for security.
Supported Countries
- Åland Islands
- American Samoa
- Andorra
- Angola
- Anguilla
- Antigua and Barbuda
- Armenia
- Aruba
- Australia
- Austria
- Azerbaijan
- Bahamas
- Bahrain
- Belgium
- Belize
- Benin
- Bermuda
- Bhutan
- Bonaire, Sint Eustatius and Saba
- Botswana
- Brazil
- British Virgin Islands
- Brunei Darussalam
- Bulgaria
- Canada
- Cape Verde
- Chad
- Chile
- Colombia
- Comoros
- Cook Islands
- Costa Rica
- Côte dIvoire
- Croatia
- Curaçao
- Cyprus
- Czech Republic
- Denmark
- Djibouti
- Dominica
- Dominican Republic
- El Salvador
- Equatorial Guinea
- Eritrea
- Estonia
- Eswatini
- Ethiopia
- Falkland Islands (Malvinas)
- Faroe Islands
- Fiji
- Finland
- France
- French Guiana
- French Polynesia
- Gabon
- Gambia
- Georgia
- Germany
- Ghana
- Gibraltar
- Greece
- Greenland
- Grenada
- Guadeloupe
- Guam
- Guatemala
- Guernsey
- Guinea
- Guyana
- Honduras
- Hong Kong
- Hungary
- Iceland
- India
- Indonesia
- Ireland
- Isle of Man
- Israel
- Italy
- Jersey
- Kazakhstan
- Kenya
- Kiribati
- Kuwait
- Laos
- Latvia
- Lesotho
- Liberia
- Liechtenstein
- Lithuania
- Luxembourg
- Macau
- Madagascar
- Malawi
- Malaysia
- Maldives
- Malta
- Marshall Islands
- Martinique
- Mauritania
- Mauritius
- Mayotte
- Mexico
- Micronesia
- Moldova
- Monaco
- Mongolia
- Montserrat
- Namibia
- Nauru
- New Caledonia
- New Zealand
- Niger
- Niue
- Norfolk Island
- Northern Mariana Islands
- Norway
- Oman
- Palau
- Papua New Guinea
- Paraguay
- Peru
- Pitcairn
- Poland
- Portugal
- Qatar
- Réunion
- Romania
- Rwanda
- Saint Barthélemy
- Saint Helena, Ascension and Tristan da Cunha
- Saint Kitts and Nevis
- Saint Martin (French part)
- Saint Pierre and Miquelon
- Saint Vincent and the Grenadines
- Samoa
- San Marino
- Sao Tome & Prin.
- Seychelles
- Sierra Leone
- Singapore
- Slovakia
- Slovenia
- Solomon Islands
- South Africa
- Spain
- Sri Lanka
- St Lucia
- St Maarten
- Suriname
- Svalbard and Jan Mayen
- Sweden
- Switzerland
- Taiwan
- Tajikistan
- Timor-Leste
- Togo
- Tokelau
- Tonga
- Turkmenistan
- Turks and Caicos Islands
- Tuvalu
- United Arab Emirates
- United Kingdom
- United States
- Uruguay
- US Virgin Islands
- Uzbekistan
- Vatican City State (Holy See)
- Wallis and Futuna
- Zambia
Supported Currencies
- AED
- ARS
- AUD
- AZN
- BAM
- BDT
- BGN
- BHD
- BOB
- BRL
- BYR
- CAD
- CDF
- CHF
- CLP
- CNY
- COP
- CRC
- CZK
- DKK
- DOP
- DZD
- EGP
- ETB
- EUR
- GBP
- GEL
- GHS
- GTQ
- HKD
- HNL
- HRK
- HUF
- IDR
- ILS
- INR
- IQD
- ISK
- JOD
- JPY
- KES
- KGS
- KRW
- KWD
- KZT
- LBP
- LKR
- MAD
- MDL
- MMK
- MNT
- MOP
- MXN
- MYR
- MZN
- NGN
- NIO
- NOK
- NPR
- NZD
- OMR
- PAB
- PEN
- PHP
- PKR
- PLN
- PYG
- QAR
- RON
- RSD
- RUB
- RWF
- SAR
- SEK
- SGD
- SLL
- SVC
- SYP
- THB
- TND
- TRY
- TWD
- TZS
- UAH
- UGX
- USD
- UYU
- UZS
- VEF
- VND
- XAF
- XOF
- YER
- ZAR
- ZMW
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_PayWithCrypto“
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_PayWithCrypto" } }, "deviceDetails":{ "ipAddress":"<customer's IP address>" }, "billingAddress":{ "firstName": "John", "lastName": "Smith", "country":"FR", "email":"john.smith@email.com" }, "userDetails":{ "firstName": "John", "lastName": "Smith", "country":"FR", "email":"john.smith@email.com" }, "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.nuvei.com/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, the user receives a Direct Merchant Notification (DMN) (sent to the notificationUrl
parameter you can provide in the request) that includes the result of the transaction.
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":"john.smith@email.com", "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_PayWithCrypto“apmData
block containing:coindirect_ cryptoAddress
coindirect_ cryptoCurrency
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_PayWithCrypto", "apmData":{ "coindirect_ cryptoAddress": "<your cryptoAddress>", "coindirect_ cryptoCurrency": "<your cryptoCurrency" }, "billingAddress":{ "country":"FR", "email":"john.smith@email.com", }, "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, the user receives a DMN (sent to the notificationUrl
parameter you can provide in the request) that includes the result of the transaction.
User Experience
Payment With App
- The user is redirected to a payment page, where a QR code page is displayed with the ability to copy details if you do not use a mobile app. The price is guaranteed for 15 minutes.
- From the crypto wallet, the user scans the QR code or copy/pastes the information into the wallet and confirms the payment.
- The user is redirected back to the merchant store.
Overpayment
- The user is informed that they paid more than the crypto quoted amount and they should request a refund for the extra amount.
- The user needs to provide their wallet address to receive the excess amount, excluding network fees.
- The user gets confirmation that the refund is being processed.
- Once the refund is processed, an email is sent to the user.
Underpayment
- If the user pays less than the crypto quoted amount, the user is informed that they paid less than the quoted crypto amount. The system informs them that they need to request a refund to get their money back.
- The user needs to provide their wallet address to receive the excess amount, excluding network fees.
- The user gets confirmation that the refund is being processed.
- Once the refund is processed, an email is sent to the user.
Expired Payment
- The user is informed that they paid after the expiration time.
- The user gets a confirmation that the refund is being processed.
- Once the refund is processed, an email is sent to the user.
Testing
Test information:
CryptoAddress: “2N5NZXKaZRsdK9SPi1bTxBnteCcB16YkSxY”,
CryptoCurrency: “BTC”
The tester first needs to send a JSON request.
{ "payment": { "merchantTransactionID": "John_{{$timestamp}}", "amount": 1333, "coindirect_cryptoCurrency": "BTC", "MethodID": 112, "ReturnURL": "http://demo2.nuvei.com/redirect.php", "Customer": { "email": "ionut.cucu@nuvei.com", "firstName": "John", "lastName": "Ska" } } }
Once the request is sent, they are taken to the following provider page.
Press the icon in the bottom left of the screen to open the Status Simulator. This simulates all suggested scenarios, and the tester can select the status from the following menu.