[NOT USED] APM Payments (REST API)

Overview

This topic describes how to accept payments from your customers via APMs using Nuvei REST API methods.

Follow these APM REST API integration steps:

1. Get sessionToken

Each API session begins with a /getSessionToken call to receive a sessionToken for use in the subsequent API calls.

Example `/getSessionToken` Request

{
  "merchantSiteId":"<your merchantSiteId>",
  "merchantId":"<your merchantId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

Example `/getSessionToken` Response

{
  "sessionToken":"f7763a23-9847-49c6-8ea5-96597aff6f78",
  "internalRequestId":272443598,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"479748173730597238",
  "merchantSiteId":"204388",
  "version":"1.0",
  "clientRequestId":"20210428200753"
}

2. APM Payment Form

Present a payment form containing the list of APMs for your customers to choose from. Use either of these approaches:

Hard-Coded Approach – If you offer a simple set of pre-defined APMs (only a few APMs and for a few countries), then you can simply hard-code their input parameters into your payment form.

Holistic/Real-Time/Dynamic Approach – If you wish to offer a dynamic list of APMs in many countries, then use the /getMerchantPaymentMethods API method to retrieve the relevant APMs for the customer.

3. Initiate an APM Payment

Send a /payment method call to initiate the APM payment.

Parameter	Description
Credential parameters	`merchantId`, `merchantSiteId`, `clientRequestId`, `timeStamp`, `checksum`.
paymentOption	The `paymentOption` class contains details of the payment method selected by the customer for the transaction. There are two options: `paymentOption.alternativePaymentMethod` – For a new customer, the `alternativePaymentMethod` class allows you to specify the APM selected by the customer for use in this transaction. See APM Input Fields and APIs for details. `paymentOption.userPaymentOptionId` – For a returning customer, you can provide the identifier representing the customer's previously stored (by Nuvei) payment method.
amount	Payment `amount`.
currency	The transaction `currency`.

Example `/payment` Request

{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "currency":"USD",
  "amount":"200",
  "userTokenId":"230811147",
  "paymentOption":{
    "alternativePaymentMethod":{
      "paymentMethod":"apmgw_MoneyBookers",
      "account_id":"SkrillTestUser3"
    }
  },
  "billingAddress":{
    "country":"US",
    "email":"john.smith@email.com"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

The response parameters returned can vary depending on the APM.

See the /payment method documentation for a description of all the possible output parameters.

Example `/payment` Response

{
  "orderId":"284832898",
  "userTokenId":"230811147",
  "paymentOption":{
    "redirectUrl":"https://pay.skrill.com?sid=566c3869b901337398818e17f78a5525",
    "userPaymentOptionId":"53857808",
    "card":{
      
    }
  },
  "transactionStatus":"REDIRECT",
  "sessionToken":"f7763a23-9847-49c6-8ea5-96597aff6f78",
  "internalRequestId":272443728,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"479748173730597238",
  "merchantSiteId":"204388",
  "version":"1.0",
  "clientRequestId":"20210428200916"
}

Parameter	Details
transactionStatus	The status of the transaction. For Direct APM only. Possible values: APPROVED, DECLINED, ERROR, REDIRECT
redirectUrl	The APM’s URL to redirect to. For Redirect APM only.
reason	The error reason, in the event of an error.
transactionId	The unique transaction ID assigned by Nuvei. This ID is needed for future related requests, such as a refund.
userPaymentOptionId	An ID assigned for the processed user’s card for future transaction to be performed by the same user. Refer to Card-on-File for further details.

4. Redirect to the APM

Use the redirectUrl (returned in the response to the initial /payment request above) to redirect your customer to the APM’s URL.

5. DMN Response for APM

After processing transactions through an APM, Nuvei returns a Direct Merchant Notification (DMN) that includes the result of the transaction in status and in payment_method, which identifies the payment method that the customer selected.

There are three possible values of status:

APPROVED: The transaction was processed and approved by the APM processor.
DECLINED: The transaction was processed by the APM processor and declined.
PENDING: The transaction is being processed by the APM processor.

Transactions are processed synchronously and asynchronously depending on the APM. When an APM processes the transaction asynchronously, the length of time that passes before the transaction is processed can be several seconds to several days.
After the final result (APPROVED or DECLINED) is received from the APM processor, Nuvei sends the merchant an additional DMN with the same transaction data as the previous DMN, containing the final transaction status.

If a customer fails to perform the next step in the APM transaction process, then the transaction remains in PENDING status and no additional notifications are sent.

Example `/payment` DMN with `status`=PENDING

...'ppp_status=PENDING&PPP_TransactionId=257354778&userid=&merchant_unique_id=5CXS9TWCNFJP&customData=&productId=&first_name=Test&last_name=Test&email=test%40test.com&currency=EUR&clientUniqueId=5CXS9TWCNFJP&Status=PENDING&customField1=merchantName&customField2=merchantName&customField3=merchantName&customField4=merchantName&customField5=&customField6=&customField7=&customField8=&customField9=merchantName&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=billing_address1&address2=&country=Germany&state=&city=billing_city&zip=9999&phone1=123456&phone2=&phone3=&client_ip=192.168.5.1&nameOnCard=&cardNumber=&bin=&acquirerId=&expMonth=&expYear=&Token=&tokenId=&ExErrCode=0&ErrCode=0&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=197846&merchant_status=&action=&requestVersion=&message=PENDING&merchantLocale=&unknownParameters=&payment_method=apmgw_expresscheckout&Id=&merchant_id=4960497427404081578&responseTimeStamp=2020-03-21.15:42:48&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=ralphv5%40safecharge.com&cardCompany=&eci=&user_token_id=testPaypal&userPaymentOptionId=47865938&TransactionId=1110000000004579353&ExternalaccountId=3ZPD52JF4XY4S&externalAccountDescription=account_id:3ZPD52JF4XY4S%7Cemail:ralphv5%40safecharge.com&externalTransactionId=40T14511AV6745111&APMReferenceID=B586E22F7608F7416E201A9EBC58AF69&orderTransactionId=1044765948&totalAmount=20.00&dynamicDescriptor=%3F&Reason=&ReasonCode=0&item_name_1=NA&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&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20200321&type=DEPOSIT&clientRequestId=20200321174049&relatedTransactionId=&apmPayerInfo=Address:Confirmed%3BPayer:verified%3BCountry:GB%3BFirstName:Ralph%3BLastName:Van+Coevorden&responsechecksum=0606f157a5075d1d4dc11db7279deb9afd2b933575845bd71e5db99747db30d3&advanceResponseChecksum=1b85115ce2647e02461a4ad93d5a04873cb049470ec1e82b6d66d205ef9e4cfe',

Example `/payment` DMN with `status`=APPROVED

...'ppp_status=OK&PPP_TransactionId=257354778&userid=&merchant_unique_id=5CXS9TWCNFJP&customData=&productId=&first_name=Test&last_name=Test&email=test%40test.com&currency=EUR&clientUniqueId=5CXS9TWCNFJP&Status=APPROVED&customField1=merchantName&customField2=merchantName&customField3=merchantName&customField4=merchantName&customField5=&customField6=&customField7=&customField8=&customField9=merchantName&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=billing_address1&address2=&country=Germany&state=&city=billing_city&zip=9999&phone1=123456&phone2=&phone3=&client_ip=192.168.5.1&nameOnCard=&cardNumber=&bin=&acquirerId=&expMonth=&expYear=&Token=&tokenId=&ExErrCode=0&ErrCode=0&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=197846&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_expresscheckout&Id=&merchant_id=4960497427404081578&responseTimeStamp=2020-03-21.15:42:49&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=ralphv5%40safecharge.com&cardCompany=&eci=&user_token_id=testPaypal&userPaymentOptionId=47865938&TransactionId=1110000000004579353&ExternalaccountId=3ZPD52JF4XY4S&externalAccountDescription=account_id:3ZPD52JF4XY4S%7Cemail:ralphv5%40safecharge.com&externalTransactionId=40T14511AV6745111&APMReferenceID=B586E22F7608F7416E201A9EBC58AF69&orderTransactionId=1044765948&totalAmount=20.00&dynamicDescriptor=%3F&Reason=&ReasonCode=0&item_name_1=NA&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&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&upoRegistrationDate=20200321&type=DEPOSIT&clientRequestId=20200321174049&relatedTransactionId=&apmPayerInfo=Address:Confirmed%3BPayer:verified%3BCountry:GB%3BFirstName:Ralph%3BLastName:Van+Coevorden&responsechecksum=7721cf5aea6773ac011df0f2224481041ecfff2ebc08bd265ec5b10c3f5ea4d5&advanceResponseChecksum=2164dc8cd5d93a4529dd6894f20563639ac22b953b06cdd0c5c4f1fb4e2cd3d3',

Overview

1. Get sessionToken

Example /getSessionToken Request

Example /getSessionToken Response