Introduction

The EFT Payments APM provides an in-flow identity verification check for deposits and withdrawals. Built for sports betting and iGaming operators in Canada, EFT Payments APM is an electronic funds transfer (EFT) solution that provides a safe and simple way to accept bank account‑based payments supported by state‑of‑the‑art risk management.

Supported Countries

• Canada

Supported Currencies

• CAD

REST API 1.0

Payment (Deposit) Flow

A payment is performed using the REST API /payment request.

• Payment (without UPO) —The first time a customer uses a particular bank account to perform a payment transaction, Nuvei stores the bank account details in an encrypted UPO (User Payment Option) record in the Nuvei system for use in future transactions.
• Payment (with UPO)—For subsequent payment transactions, Nuvei offers the user the option to select one of the UPOs instead of recapturing bank account details.

Payment (without UPO)

1. Generate a sessionToken.
   
   For details, see Authentication.

2. Send a /payment request with its mandatory parameters including:
   • userTokenId
   • amount
   • currency
   • paymentOption.alternativePaymentMethod class containing:
     • paymentMethod:“apmgw_Instant_Bank_Transfer”
   • deviceDetails class containing: ipAddress
   • billingAddress class containing: firstName, lastName, address, city, state, zip, country, phone
   • userDetails class containing: firstName, lastName, address, city, state, zip, country, phone

Example /payment without UPO Request

{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "currency": "CAD",
  "amount": "100",
  "paymentOption": {
    "alternativePaymentMethod": {
      "paymentMethod": "apmgw_Instant_Bank_Transfer"
    }
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "billingAddress":{
    "firstName":"John",
    "lastName":"Smith",
    "email":"[email protected]",
    "phone":"16139575555",
    "address":"24 Sussex Drive",
    "city":"Ottawa",
    "zip":"K1M 1M4",
    "state":"ON",
    "country":"CA",
  },
  "userDetails":{
    "firstName":"John",
    "lastName":"Smith",
    "email":"[email protected]",
    "phone":"16139575555",
    "address":"24 Sussex Drive",
    "city":"Ottawa",
    "zip":"K1M 1M4",
    "state":"ON",
    "country":"CA",
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

The response generates and returns a redirect URL (redirectUrl) to redirect the customer to the payment page and a UPO (userPaymentOptionId) for use in future transactions.

Example /payment without UPO Response

{
  "orderId":"38503331",
  "userTokenId":"Siltoken545989",
  "paymentOption":{
    "redirectUrl":"https://ibt-mint.pay-direct.ca/verification?code=6cac9e0d-616f-4e0b-9da4-661e36d73b35",
    "userPaymentOptionId":"8399641",
  },
  "transactionStatus":"REDIRECT",
  "sessionToken":"4c05abf8-3bf4-4465-85bc-f169d30899b5",
  "clientUniqueId":"uniqueIdCC",
  "internalRequestId":23608581,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"4972436454212160565",
  "merchantSiteId":"209631",
  "version":"1.0",
  "clientRequestId":"20221221111018"
}

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 to include in the /payment request (see Example Payment DMNs).

Payment (with UPO)

1. Generate a sessionToken.
   
   For details, see Authentication.

2. Send a /payment request with its mandatory parameters including:
   • userPaymentOptionId
   • amount
   • deviceDetails class containing: ipAddress

Example /payment with UPO Request

{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "currency": "CAD",
  "amount": "100",
  "paymentOption": {
    "userPaymentOptionId": "<UPO received from previous deposit>"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

The response generates and returns a redirect URL (redirectUrl) to redirect the customer to the payment page.

Example /payment with UPO Response

{
  "reason": "",
  "orderId": "36298951",
  "transactionStatus": "REDIRECT",
  "clientRequestId": "2VXORP7A1",
  "internalRequestId": 17817211,
  "version": "1.0",
  "merchantSiteId": "126006",
  "merchantId": "2502136204546424962",
  "clientUniqueId": "695701003",
  "errCode": 0,
  "paymentOption": {
    "redirectUrl": "https://cdn-int.safecharge.com/safecharge_resources/v1/get_to_post/index.html?eyJhbGciOiJSUzI1NiJ9.eyJkZXRhaWxzIjoiRUM5OURFMkU0NjdBQUQ1QUU4NkQ3MzAwNjMzRkFFRTVDNTEwOEIxMjRENzI0NjgzREM5OEE1NTczMzU0NzY2NjFDNjc5MDgyMjhGMzU1NzlFQ0Y0RUUxM0QwNURGNTJGNkZCNjFFNjU5ODQxMTM3Q0Y2RjFFNjU3Nzc5MDI0MTg0NjE4NEJDODhFRjYyOUQ2MzkzQjc2NjQ3MzYwQUQxNzFDNUExQzJBNzE5MkEzMTYzMTlFQzlFNTY3MTlDQTNFODc2OUU0OTlEODRGQUZEMUZBRUM1RjUzNjEwREQ1QkIwRDU3Qjg1MUI2OUY1RjM0QzU4ODlFMUZFNERDQjI2NTAwRTFCM0VGNTA3MEJCMDAyRjg0ODM4MEI0MDMyRTBGQjY0NjY4REZDRjc4QzFFNjJBMDlERTYyMkE3RjEyNTQ0MkYzRkFFNUM1MzlGMzgwNkVGOTIwNTM0QUM4MjBFNDU0NTI1NzlERkM0OEQ3QkZBRUUyQTJERDZDQjRDMjE5RENCN0YzRjgyQ0Y2RDBGOTJGMzQ0Mjc1NjQ4REY1RDY2MEFDNUNEQ0Y2QzE4RDA2MzAzMEM5OTNEMUNBRjUyNDUyQjY1ODJGREQ0NUU4NjJEN0M0NDE3NDc1RDNFRkY0NkFCMzdDRUNGQ0NDM0U5OTA0REFERjBBNDY4QTFCNjI2NzA1MUM4OTVBOTkxNkQ0NjFCQ0I4QkQ0NkQzMDE4Mjc4RjE3NkEyOTI5MkI3OTYxQTUzNTk0RTA0NUJDM0IxMkUzOEI5MDhBRDkyQjE1NTI1QTA2QjVCQTU4NUZBOEE2MEQ4Q0VDOTRDMzBENDU0MUU2RENCRkM1NTJDMDFEMjc5RjBFMTczNTU1QTU4NEMzMDdGNEE2QTc4RjlGNEVCRTQ4OTVCRTA5MkEwQTQzMzE5OTg4ODA2MTQyQ0NCMjU1M0ZDM0JGQkI5M0ZCMTU5QjI1OUNGMzUxRjk2ODM5NDBFMzFFOTgzRUNBNDU5MEI1RkE5N0Q1MUNDMjc2MTUwQzZFM0I1NTlGODVGREQ0NTVCMjMzMEM5OEMyMzhDODUxODQ2NUNDRkJDNDIwODAwNEJCNzlGMTJFN0NDOTE2RDFDOTUwQkQ4RUQwQzJGRTNCRkVEQzUwNzMyNEYxMEMwNUY4NDIzQzI1MEIxMEEwRTFCMEY3OTU1NEJCMTU4N0QzMkQ5QzVDN0NGQ0Y2NTc4RTkwRTFEQUQ4NDY3Mzc2MzJGMzE0MEQ1RjMyNEVCN0JGQkQ4RDYwOEE3NDk0Rjg5MUNGMTM4QzBFQjY1NkRFOUJBNjRDOTlCQ0I3NDk3MzIzMjZCOTQyMkMyM0U3OEMwQ0I3RkVCOUZGQTQ1OTI5QyIsIm1lcmNoYW50X2lkIjoiU2ZDaGFyZ2UiLCJpdiI6IjIxQzdFNzhCQTQ5MTUyMzFGNTM1QkEzMDBGNjA3OUJDIiwidXJsIjoiaHR0cHM6Ly9zdGFnaW5nLnZlcmlmaWVkYWNoLmNvbS9jb25zdW1lci9BY3F1aXJlSW5mb0dhdGV3YXkuZG8ifQ.oJcwsoVB8wQXXNGi71Diqb3Lhm_6Vj3b5elO9w2ya67iG6IXP0jcFRWssBldiFvqlszE0t0GyEjgllvoZqXejt7GqcGmpUrGuJjrJL7T6yvnv15ApKSSNOKC_O2Q2yxU5l1IxHpY7vWkl3__oDJ0zMEjCyK4czW_B63-ZaGplfI0o0Mn3Aw1Vzoxn17UBjS7i4zRDm448wq2tnIfm9WBvFbR79Qdh6lJwUWI_xdwik8L3oR67MEC35w8SV9XCMjwX_WqOvaqk_mq1WXOxM0X1ooAmw6Tmd3jMM37od583ReT3GlbfDtU6NlBDAgrxEjwr807HGnQXSlKSMsxJoWnhw",
    "userPaymentOptionId": "8061731",
    "card": {}
  },
  "sessionToken": "1be68338-e45e-4c81-b617-e1bfb94cae3e",
  "userTokenId": "2J6QZH3UF9E2",
  "status": "SUCCESS"
}

After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payment request (see Example Payment DMNs).

Account Capture

When processing a payout request, the account capture feature enables a merchant to redirect the user to the user’s bank payment page where the user enters the account details.

The following flow describes how the customer’s account details must first be captured before processing the payout request:

1. Generate a sessionToken.
   
   For details, see Authentication.

2. Send an /accountCapture request with its mandatory parameters including:
   • userTokenId – Unique customer identifier in merchant system.
   • paymentMethod: “apmgw_Instant_Bank_Transfer“
   • currencyCode: CAD
   • countryCode: CA
   • userDetails class containing: firstName, lastName, address, city, state, zip, country, phone
   • deviceDetails class containing: ipAddress

Example /accountCapture Request

{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "paymentMethod":"apmgw_Instant_Bank_Transfer",
  "userTokenId":"<unique customer identifier in merchant system>",
  "currencyCode":"CAD",
  "countryCode":"CA",
  "amount":"200",
  "userDetails":{
    "firstName":"John",
    "lastName":"Smith",
    "address":"24 Sussex Drive",
    "phone":"16139575555",
    "zip":"K1M 1M4",
    "city":"Ottawa",
    "state":"ON",
    "email":"[email protected]",
    "country":"CA"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
}

The request returns a redirectUrl.

Example /accountCapture Response

{
  "redirectUrl":"https://fl-mint.pay-direct.ca/loadUser?code=1fe32df7-7d49-4f27-823e-7b4f7acfc153&merchant-return-url=https%3A%2F%2Fjumpbox.safecharge.com%2Fdmz%2FApmConnector%2FbankCapture%2FAC0CC72D6776ED9138EB6C0B6E54303B",
  "userTokenId":"Siltoken69",
  "sessionToken":"40ea5008-16be-49c3-a05a-78e5cc3ce041",
  "internalRequestId":23984041,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"4972436454212160565",
  "merchantSiteId":"209631",
  "version":"1.0"
}

Use the redirectUrl to redirect the customer to the merchant’s page, where the customer logs in to a bank account and confirms the payout request. Once the bank account information is captured, Nuvei generates and returns an encrypted userPaymentOptionId (UPO) representing the user’s APM account details. A DMN is sent with the userPaymentOptionId, which is used to proceed with the payout.

Example /accountCapture DMN

...'ppp_status=OK&ExErrCode=&ErrCode=&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=&PPP_TransactionID=&userid=139790461&merchant_unique_id=&customData=&productId=&first_name=&last_name=&email=&currency=CAD&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=&address2=&country=CA&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=&total_handling=&total_shipping=&total_tax=&buyButtonProductBundleId=&merchant_site_id=209631&merchant_status=&action=&requestVersion=&message=&merchantLocale=&unknownParameters=&payment_method=apmgw_Instant_Bank_Transfer&ID=&merchant_id=4972436454212160565&responseTimeStamp=2023-02-06.16%3A28%3A12&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=&externalEmail=&cardCompany=&eci=&user_token_id=siltokenhahhajjhhh13&userPaymentOptionId=2152803291&TransactionID=&totalAmount=&dynamicDescriptor=&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&type=ACCOUNT_CAPTURE&clientRequestId=&relatedTransactionId=&responsechecksum=df70110354d570e87daf70291a6d874c&advanceResponseChecksum=6a26bc6c966d9b5361a94ad818da7b9b',

Payout (Withdrawal) Flow

A payout is performed using the REST API /payout request, which requires using a UPO. A UPO can be generated in the following ways:

• A UPO is automatically created upon successful completion of a /payment request, as described in Payment (Deposit) Flow.
• A UPO is created once a user confirms an /accountCapture request, as described in Account Capture.

Once you have the UPO, send a /payout request and include the userPaymentOptionId that contains the user’s previously stored APM account details.

After the transaction is processed, Nuvei sends a 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=0&PPP_TransactionID=38706451&userid=ScMigrationTest3&merchant_unique_id=12345&customData=QA+test+merchant&productId=test_name_1&first_name=John&last_name=Doe&[email protected]&currency=CAD&customField1=meccabingo.com&customField2=a2db82db-8186-44bb-a6d9-cb9f8f7ea25e&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=rnk_pr01&invoice_id=&address1=Test+Address&address2=&country=Canada&state=ONTARIO&city=Ontario&zip=M6T+1J1&phone1=%2B14161238888&phone2=&phone3=&client_ip=192.206.151.131&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Paramount+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=209631&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=en_US&unknownParameters=&payment_method=apmgw_Instant_Bank_Transfer&ID=&merchant_id=123456789&responseTimeStamp=2023-02-14.08%3A49%3A31&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Siltoken&user_token=auto&userPaymentOptionId=2152807311&TransactionID=2110000000008617162&externalTransactionId=OVVRDYZH2VCS3C4CZJTCHO5Y74E5HU&APMReferenceID=F3C37FF9BD57D340F81D23A41053957B&orderTransactionId=19382671&totalAmount=10.00&dynamicDescriptor=NuveiDescriptor&item_name_1=test_name_1&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=&upoRegistrationDate=20230214&type=DEPOSIT&clientRequestId=&relatedTransactionId=&sessionId=f1980c09a347815b5c3dd6c675ed&responsechecksum=42111be8df56ebd2bb11a40157820894&advanceResponseChecksum=d2c15bc9edfebc4ffe6a1e7ddd8ebc94',

Representment Process

After a successful “deposit” (payment) request is submitted, it is still possible for the APM provider to return a notification containing these errors: 901 (insufficient funds) or 908 (uncollected funds) when the APM provider attempts to charge the customer’s account. If so, the APM provider does not decline the deposit at that point, but instead attempts to collect the funds (“representment”) one additional time.

• If a representment is successful, then no further notifications are sent.
• Upon the first unsuccessful attempt, the merchant receives a DMN with status=UPDATE and a representmentInformation parameter (see Example DMN with status: UPDATE).
• The DMN also includes the nextActionDate parameter that contains the date scheduled for the next attempt to charge (debit) the customer’s bank account. The date when the payment is represented is the following week from the financial institution’s return date. This means that for any returns received on Monday–Friday (banks do not send any returns on the weekends), the represent is scheduled for the following Friday.
• If this second attempt fails, a final notification is sent that the deposit was declined.

Example Payment DMNs

Example DMN with status: APPROVED

...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=38503331&userid=Siltoken545989&merchant_unique_id=uniqueIdCC&customData=customData&productId=&first_name=John&last_name=Doe&[email protected]&currency=CAD&clientUniqueId=uniqueIdCC&customField1=merchantName&customField2=merchantName&customField3=merchantName&customField4=merchantName&customField5=&customField6=&customField7=&customField8=&customField9=merchantName&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=65+Overlea+Blvd+%23230&address2=&country=Canada&state=ONTARIO&city=Toronto&zip=M6T+1J1&phone1=%2B14161238888&phone2=&phone3=&client_ip=192.206.151.131&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Paramount+Direct&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=CA&shippingState=ONTARIO&shippingCity=Toronto&shippingAddress=65+Overlea+Blvd+%23230&shippingZip=M6T+1J1&shippingFirstName=&shippingLastName=&shippingPhone=&shippingCell=&shippingMail=&total_discount=2.00&total_handling=0.00&total_shipping=1.00&total_tax=1.00&buyButtonProductBundleId=&merchant_site_id=209631&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_Instant_Bank_Transfer&ID=&merchant_id=123456789&responseTimeStamp=2022-12-21.09%3A13%3A43&buyButtonProductId=&webMasterId=webMasterId&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Siltoken545989&userPaymentOptionId=8399641&TransactionID=2110000000008090959&externalTransactionId=O43ZVXLATNEANP6TVLO3BSTDFYRMxb&APMReferenceID=5FA51E308E092FD2968DB4E6FDE25668&orderTransactionId=19253611&totalAmount=100.00&dynamicDescriptor=NuveiDescriptor&item_name_1=watch&item_number_1=&item_amount_1=50.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&item_name_2=color&item_number_2=&item_amount_2=50.00&item_quantity_2=1&item_discount_2=0.00&item_handling_2=0.00&item_shipping_2=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20221221&type=DEPOSIT&clientRequestId=20221221111018&relatedTransactionId=&sessionId=3f2a30e81ffcdbf915e51ea77410&responsechecksum=1842674366bf0a4854a1ce59beebe900&advanceResponseChecksum=0a680747154408efc96ff2d894649553',

Example DMN with status: UPDATE

...'ppp_status=OK&Status=UPDATE&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=38574641&userid=ScMigrationTest3&merchant_unique_id=12345&customData=QA+test+merchant&productId=test_name_1&first_name=John&last_name=Doe&[email protected]&currency=CAD&customField1=meccabingo.com&customField2=a2db82db-8186-44bb-a6d9-cb9f8f7ea25e&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=rnk_pr01&invoice_id=&address1=Test+Address&address2=&country=Canada&state=ONTARIO&city=Ontario&zip=K8N+1W0&phone1=%2B14161238888&phone2=&phone3=&client_ip=192.206.151.131&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Paramount+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=209631&merchant_status=&action=&requestVersion=&message=UPDATE&merchantLocale=en_US&unknownParameters=&payment_method=apmgw_Instant_Bank_Transfer&ID=&merchant_id=123456789&responseTimeStamp=2023-01-12.15%3A20%3A43&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=Siltoken055570&user_token=auto&userPaymentOptionId=8409271&TransactionID=2110000000008284927&APMReferenceID=7D5B481B04BAADE2117128DAAF5837C6&orderTransactionId=19299601&totalAmount=20.00&dynamicDescriptor=NuveiDescriptor&item_name_1=test_name_1&item_number_1=&item_amount_1=20.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=20230112&type=DEPOSIT&clientRequestId=&relatedTransactionId=&representmentInformation=RETURNED_WITH_REPRESENTMENT%2C+nextActionDate%3D2023-01-13&sessionId=658d7ba658128ea0112b80102d93&responsechecksum=b3242d7e830e3a96e2c0d589e62f7df5&advanceResponseChecksum=b8063972c99b272553e4b0984',

REST API 2.0

Payment (Deposit) Flow

1. Send a REST 2.0 /payments request that includes the following mandatory parameters:
   • buyerDetails.buyerId
   • amount
   • currency
   • paymentOption.alternativePaymentMethod.name = “instantBankTransfer”
   • deviceDetails class containing:
     • ipAddress
   • buyerDetails.billingAddress class containing:
     • address
     • city
     • state
     • zip
     • countryCode
   • buyerDetails class containing:
     • firstName
     • lastName
     • phone

Example /payments Request

{
    "processingEntityId": "<<processingEntityId>>",
    "amount": 1,
    "currency": "CAD",
    "transactionType": "Sale",
    "paymentOption": {
        "alternativePaymentMethod": {
            "name": "instantBankTransfer"
        }
    },
    "custom": {
        "description": "Some description"
    },
    "urlDetails": {
        "webhookUrl": "<<webhook URL>>",
        "successUrl": "<<success URL>>",
        "failureUrl": "<<failure URL>>",
        "pendingUrl": "<<pending URL>>"
    },
    "deviceDetails": {
        "ipAddress": "192.168.2.38"
    },
    "buyerDetails": {
        "buyerId": "IBT-test01",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "phone": "4161238888",
        "billingAddress": {
            "address": "30 Alenbi st",
            "zip": "M6T1J1",
            "city": "Berlin",
            "countryCode": "CA",
            "phone": "4161238888",
            "state": "ON"
        }
    }
}

Example /payments Response

{ 
    "paymentId": "c1937af109314d0ab5f5b88d0e0d55dd",
    "amount": 1,
    "currency": "CAD",
    "transactionType": "Sale",
    "result": { 
      "status": "redirect"
    },
    "redirectUrl": "https://ibt-mint.pay-direct.ca/verification?code=06f5a381-7b91-4bfc-b3ec-d559618636e8",
    "paymentOption": {
      "alternativePaymentMethod": {
         "name": "instantBankTransfer",
         "paymentTokenId": "900298a470e2414baa428c7bee282984"
     }
    }
}

After processing, Nuvei sends a webhook notification to the URL specified in urlDetails.webhookUrl. The webhook includes the transaction status and associated metadata.

Payment Using Stored Token

After the initial payment, the response returns a paymentTokenId which can be used for future payments. REST API 2.0 removes all UPO references and replaces them
fully with paymentTokenId.

1. Send a /payments request, using a stored token, that includes the following mandatory parameters:
   • paymentOption.paymentToken.paymentTokenId
   • amount
   • deviceDetails.ipAddress

Example /payments Request Using Stored Token

{
  "processingEntityId": "<<processingEntityId>>",
  "amount": 60,
  "currency": "CAD",
  "paymentOption": {
    "paymentToken": {
      "paymentTokenId": "<<paymentTokenId>>",
      "additionalData": {
        "cvv": "090"
      }
    }
  },
  "deviceDetails": {
    "ipAddress": "192.168.2.38"
  },
  "buyerDetails": {
    "buyerId": "test1233ssw2",
    "firstName": "John",
    "lastName": "JSmith",
    "companyName": "Nuvei Corp",
    "locale": "bg-BG",
    "dateOfBirth": "1978-01-01",
    "email": "[email protected]",
    "phone": "+1234567889",
    "billingAddress": {
      "state": "TX",
      "city": "Austin",
      "zip": "78652",
      "countryCode": "US"
    },
    "shippingAddress": {
      "sameAsBilling": true
    }
  }
}

Payout (Withdrawal) Flow

1. Send a /payouts request, use one of the following methods:

• • Alternative Payment 
    • paymentOption.alternativePaymentMethod.name = “instantBankTransfer”
    • Include buyerDetails and deviceDetails.ipAddress
  • Stored Token
    • paymentOption.paymentToken.paymentTokenId
    • Include the matching buyerDetails.buyerId

Example /payout Request

{
  "processingEntityId": "<<processingEntityId>>",
  "amount": 60,
  "currency": "CAD",
  "paymentOption": {
    "paymentToken": {
      "paymentTokenId": "<<paymentTokenId>>"
    }
  },
  "deviceDetails": {
    "ipAddress": "145.89.23.67"
  },
  "buyerDetails": {
    "buyerId": "CA-BUYER-456",
    "firstName": "John",
    "lastName": "Smith",
    "email": "[email protected]",
    "phone": "+1-4161238888",
    "billingAddress": {
      "city": "Toronto",
      "zip": "M6T1J1",
      "countryCode": "CA"
    }
  }
}

Representment Process

In REST 2.0, a representment update is delivered as a webhook notification.

• If a representment is successful, no further webhook notification is sent.
• If the first representment attempt is unsuccessful, the merchant receives a webhook notification that includes status=update and a representmentInformation parameter.
• For the next debit attempt, the webhook notification includes nextActionDate.
• If a second representment attempt fails, a final webhook notification indicates the deposit is declined.

Example Webhook Notification (Status: APPROVED)

{
"authorizingEntityId": "<<authorizingEntityId>>",
"processingEntityId": "<<processsingEntityId>>",
"buyerId": "buyer-id",
"transactionId": "356445569218979008",
"paymentId": "d3adf5aba4094ba2bc0319f8ab0f559b",
"version": "2.0",
"amount": 47.97,
"currency": "CAD",
"transactionType": "Sale",
"result": {
"status": "approved"
},
"timeStamp": "2026-01-13T11:58:33.411382227Z",
"partialApproval": {
"requestedAmount": 47.97,
"requestedCurrency": "CAD"
},
"paymentOption": {
"alternativePaymentMethod": {
"name": "interacETransfer",
"data": {
"mobilePhone": "4161238888",
"email": "[email protected]"
},
"paymentTokenId": "00ad2eab8a7947d3981a3480115d198c"
}
},
"merchantTransactionId": "49021062",
"recipientDetails": {
"firstName": "Ernestine",
"middleName": "Muller",
"lastName": "Lynch",
"email": "[email protected]",
"phone": "882725321545012085",
"address": "5309 Gorczany KnollEast Dorothatown",
"addressLine2": "24220 Dotty LockTorihaven",
"identificationType": "PassportNumber",
"identificationValue": "39121496276945921228",
"cardHolderEntityType": "Business",
"accountReference": "3281585385584611834450639736452404",
"addressDetails": {
"address": "496 Barry MillsWest Amos",
"addressLine2": "4133 Phylicia BranchGenarostad",
"street": "str. Default Street",
"zip": "12345",
"city": "Lorath",
"state": "CO",
"countryCode": "CA"
}
}
}

User Experience

First-Time Payment

For first-time payment, the user is redirected to the ‘PayDirect’ page where the user does the following:

1. Selects a bank.
2. Logs in to the bank page.
3. Selects the account.
4. Confirms the deposit.
   A confirmation is displayed.

Returning User

If a user has performed a payment and the user’s UPO is saved, the user does not need to log in to the bank page again to complete a payment.