Important: NVP/SOAP is a legacy integration method. We accept new integrations and support existing integrations, but there are newer solutions. If you're starting an integration, we recommend our latest solutions.

When merchants process a payment that requires Strong Customer Authentication (SCA), they must provide additional context about the transaction. The additional context, or payment indicator, ensures that buyer authentication and card on file, among other factors, are appropriately handled. Failure to pass these payment indicators might result in rejected transactions.

Integration steps

  • These integration steps assume you have successfully onboarded to Website Payments Pro.
  • These payment indicators apply to the DoDirectPayment NVP/SOAP request message and DoReferenceTransaction NVP/SOAP request message.
  • You'll need to create a transaction request.
  • Follow recent or additional guidelines based on your region.

Sample request

Customer Initiated Transaction (CIT) recurring first

ACCT=XXXXXXXXXXXXXXXX&AMT=1.00&ITEMAMT=1.00&SHIPPINGAMT=0.00&HANDLINGAMT=0.00&TAXAMT=0.00&L_NAME0=Student chemistry set 8 kits&CURRENCYCODE=USD&USER=idc-automation-amex-us-pro-t1_api1.paypal.com&SIGNATURE=XXXXXXXXX&PWD=XXXXXX&METHOD=DoDirectPayment&EXPDATE=112020&PAYMENTACTION=Authorization&L_TAXAMT0=0.00&L_AMT0=1.00&L_QTY0=1&RETURNFMFDETAILS=1&phonenum=5555555555&VERSION=217&PAYMENTCATEGORY=RECURRING&PAYMENTINITIATOR=CUSTOMER&CARDONFILE=FIRST

Merchant Initiated Transaction (MIT) recurring subsequent

ACCT=XXXXXXXXXXXXXXXX&AMT=1.00&ITEMAMT=1.00&SHIPPINGAMT=0.00&HANDLINGAMT=0.00&TAXAMT=0.00&L_NAME0=Student chemistry set 8 kits&CURRENCYCODE=USD&USER=idc-automation-amex-us-pro-t1_api1.paypal.com&SIGNATURE=XXXX&PWD=XXXXX&METHOD=DoDirectPayment&EXPDATE=112020&PAYMENTACTION=Authorization&L_TAXAMT0=0.00&L_AMT0=1.00&L_QTY0=1&RETURNFMFDETAILS=1&phonenum=5555555555&VERSION=217&PAYMENTCATEGORY=RECURRING&PAYMENTINITIATOR=MERCHANT&CARDONFILE=SUBSEQUENT&PREVIOUSTRANSACTIONID=1SJ82848KJ814470T

CIT unscheduled first

ACCT=XXXXXXXXXXXXXXXX&AMT=1.00&ITEMAMT=1.00&SHIPPINGAMT=0.00&HANDLINGAMT=0.00&TAXAMT=0.00&L_NAME0=Student chemistry set 8 kits&CURRENCYCODE=USD&USER=qa76-ukbus-seller1_api1.paypal.com&SIGNATURE=XXXXX&PWD=XXXXXX&METHOD=DoDirectPayment&EXPDATE=112020&PAYMENTACTION=Authorization&L_TAXAMT0=0.00&L_AMT0=1.00&L_QTY0=1&RETURNFMFDETAILS=1&phonenum=5555555555&VERSION=217&PAYMENTCATEGORY=UNSCHEDULED&PAYMENTINITIATOR=CUSTOMER&CARDONFILE=FIRST

MIT unscheduled subsequent

ACCT=XXXXXXXXXXXXXXXX&AMT=1.00&ITEMAMT=1.00&SHIPPINGAMT=0.00&HANDLINGAMT=0.00&TAXAMT=0.00&L_NAME0=Student chemistry set 8 kits&CURRENCYCODE=USD&USER=idc-automation-amex-us-pro-t1_api1.paypal.com&SIGNATURE=XXXXXX&PWD=XXXXXXX&METHOD=DoDirectPayment&EXPDATE=112020&PAYMENTACTION=Authorization&L_TAXAMT0=0.00&L_AMT0=1.00&L_QTY0=1&RETURNFMFDETAILS=1&phonenum=5555555555&VERSION=217&PAYMENTCATEGORY=UNSCHEDULED&PAYMENTINITIATOR=MERCHANT&CARDONFILE=SUBSEQUENT&PREVIOUSTRANSACTIONID=1JJ124387D132544E

MIT recurring subsequent using network transaction ID

ACCT=XXXXXXXXXXXXXXXX&AMT=1.00&ITEMAMT=1.00&SHIPPINGAMT=0.00&HANDLINGAMT=0.00&TAXAMT=0.00&L_NAME0=Student chemistry set 8 kits&CURRENCYCODE=USD&USER=idc-automation-amex-us-pro-t1_api1.paypal.com&SIGNATURE=XXXXXX&PWD=XXXXXXXX&METHOD=DoDirectPayment&EXPDATE=112020&PAYMENTACTION=Authorization&L_TAXAMT0=0.00&L_AMT0=1.00&L_QTY0=1&RETURNFMFDETAILS=1&phonenum=5555555555&VERSION=217&PAYMENTCATEGORY=RECURRING&PAYMENTINITIATOR=MERCHANT&CARDONFILE=SUBSEQUENT&PREVIOUSNETWORKTRANSACTIONID=123456789&PREVIOUSNETWORKTRANSACTIONDATE=1120&PREVIOUSNETWORKTRANSACTIONBRAND=Visa

Modify the code

Copy the code snippet and modify the values, as needed.

Note: We recommended that you pass these parameters for full network compliance.

  • PAYMENTINITIATOR values (required if parameters in this list are passed):
    • CUSTOMER — Customer initiates the payment. Also referred to as a Customer Initiated Transaction (CIT).
    • MERCHANT — Merchant initiates the transaction and the merchant has established consent to charge the buyer. Also referred to as a Merchant Initiated Transaction (MIT).
  • PAYMENTCATEGORY values (required if parameters in this list are passed):
    • UNSCHEDULED — Payments that the merchant initiates and are not on a specified schedule. For example, this includes preauthorized transactions where the merchant can charge the buyer once a balance falls within a specified range. These transactions are also referred to as top-up.
    • RECURRING — Merchant initiates a payment as part of a series of recurring payments. The payment amounts can be variable and are on a fixed time interval.
    • ONE_TIME — Single, one-time payment.
  • CARDONFILE values:
    • FIRST — Save card information or payment token to use in subsequent transactions. Collect consent from the buyer that you intend to save their payment information.
    • SUBSEQUENT — Card information or payment token was previously saved and is used in the transaction.
  • PREVIOUSTRANSACTIONID — PayPal transaction ID previously used to charge the buyer. Shows payment processors that you have established a contract with the buyer.
  • PREVIOUSNETWORKTRANSACTIONID, PREVIOUSNETWORKTRANSACTIONDATE, and PREVIOUSNETWORKTRANSACTIONBRAND values:
    • PREVIOUSNETWORKTRANSACTIONID — Transaction ID from a non-PayPal payment processor that you have previously used to process the payment.
    • NETWORK — TransactionID from a non-PayPal payment processor that you have previously used to process the payment.
  • VERSION — Send the appropriate version to indicate that you are passing the SCA payment indicators.

Use cases

You can use these common scenarios to determine how you'll update your integration.

One time transaction

ScenarioPayment initiatorPayment categoryCard on file
Single payment. Buyer doesn't intend to do a follow-on purchase or save their card.CUSTOMERONE_TIME—
Single payment. Buyer saves their card details for a future single payment.CUSTOMERONE_TIMEFIRST
Single payment. Buyer uses a previously-saved card to complete the transaction.CUSTOMERONE_TIMESUBSEQUENT

Recurring plan or subscription

ScenarioPayment initiatorPayment categoryCard on file
Initial transaction to sign up for the recurring charges. Buyer hasn't saved their card with you.CUSTOMERRECURRINGFIRST
Initial transaction to sign up for the recurring charges. Buyer has already saved their card with you.CUSTOMERRECURRINGSUBSEQUENT
Subsequent payments as part of a recurring plan.MERCHANTRECURRINGSUBSEQUENT
Initial customer-initiated transaction wasn't processed with PayPal. Merchant processes recurring charge with PayPal.MERCHANTRECURRINGSUBSEQUENT

Unscheduled payment

ScenarioPayment initiatorPayment categoryCard on file
Initial transaction to sign up for an unscheduled payment. Buyer has not saved their card with you.CUSTOMERUNSCHEDULEDFIRST
Initial transaction to sign up for an unscheduled payment. Buyer has already saved their card with you.CUSTOMERUNSCHEDULEDSUBSEQUENT
Subsequent payments as part of the unscheduled contract.MERCHANTUNSCHEDULEDSUBSEQUENT
Initial customer-initiated transaction wasn't processed with PayPal. Merchant processes unscheduled charge with PayPal.MERCHANTUNSCHEDULEDSUBSEQUENT

Error response samples

  • PAYMENTCATEGORY is not passed for Merchant Initiated Transactions

    TIMESTAMP=2020%2d08%2d26T14%3a44%3a35Z&CORRELATIONID=13bf2a9e3682b&ACK=Failure&VERSION=217&BUILD=54790461&L_ERRORCODE0=10004&L_SHORTMESSAGE0=Transaction%20refused%20because%20of%20an%20invalid%20argument%2e%20See%20additional%20error%20messages%20for%20details%2e&L_LONGMESSAGE0=Please%20provide%20PaymentCategory%20for%20Merchant%20Initiated%20Transactions%2e&L_SEVERITYCODE0=Error&AMT=1%2e00&CURRENCYCODE=USD

  • CARDONFILE is sent as FIRST for Merchant Initiated Transactions

    TIMESTAMP=2020%2d08%2d26T14%3a46%3a26Z&CORRELATIONID=35d1fc1835079&ACK=Failure&VERSION=217&BUILD=54790461&L_ERRORCODE0=10004&L_SHORTMESSAGE0=Transaction%20refused%20because%20of%20an%20invalid%20argument%2e%20See%20additional%20error%20messages%20for%20details%2e&L_LONGMESSAGE0=Merchant%20Initiated%20Transaction%20is%20not%20supported%20when%20CardOnFile%20is%20FIRST%2e&L_SEVERITYCODE0=Error&AMT=1%2e00&CURRENCYCODE=USD

  • CVV2 is passed for Merchant Initiated Transactions

    TIMESTAMP=2020%2d08%2d26T14%3a48%3a06Z&CORRELATIONID=7da02e70aa567&ACK=Failure&VERSION=217&BUILD=54790461&L_ERRORCODE0=10004&L_SHORTMESSAGE0=Transaction%20refused%20because%20of%20an%20invalid%20argument%2e%20See%20additional%20error%20messages%20for%20details%2e&L_LONGMESSAGE0=Merchant%20Initiated%20Transaction%20is%20not%20supported%20when%20CVV%20is%20present%20in%20the%20request&L_SEVERITYCODE0=Error&AMT=1%2e00&CURRENCYCODE=USD

  • 3D-Secure results are passed for Merchant Initiated Transactions

    TIMESTAMP=2020%2d08%2d26T14%3a49%3a10Z&CORRELATIONID=a7e5231fa344f&ACK=Failure&VERSION=217&BUILD=54790461&L_ERRORCODE0=10004&L_SHORTMESSAGE0=Transaction%20refused%20because%20of%20an%20invalid%20argument%2e%20See%20additional%20error%20messages%20for%20details%2e&L_LONGMESSAGE0=Merchant%20Initiated%20Transaction%20is%20not%20supported%20when%203%2dD%20Secure%20authentication%20results%20are%20present%20in%20the%20request&L_SEVERITYCODE0=Error&AMT=1%2e00&CURRENCYCODE=USD

  • Both PREVIOUSTRANSACTIONID and previous network transaction related data are passed for Merchant Initiated Transactions

    TIMESTAMP=2020%2d08%2d26T14%3a50%3a14Z&CORRELATIONID=2609542dfc839&ACK=Failure&VERSION=217&BUILD=54790461&L_ERRORCODE0=10004&L_SHORTMESSAGE0=Transaction%20refused%20because%20of%20an%20invalid%20argument%2e%20See%20additional%20error%20messages%20for%20details%2e&L_LONGMESSAGE0=Please%20pass%20either%20Previous%20Transaction%20or%20Previous%20Network%20Transaction%20for%20Merchant%20Initiated%20Transactions%2e&L_SEVERITYCODE0=Error&AMT=1%2e00&CURRENCYCODE=USD

  • PREVIOUSTRANSACTIONID or previous network transaction related data are passed for Customer Initiated Transactions

    TIMESTAMP=2020%2d08%2d26T14%3a51%3a51Z&CORRELATIONID=3338bc0949ca1&ACK=Failure&VERSION=217&BUILD=54790461&L_ERRORCODE0=10004&L_SHORTMESSAGE0=Transaction%20refused%20because%20of%20an%20invalid%20argument%2e%20See%20additional%20error%20messages%20for%20details%2e&L_LONGMESSAGE0=Customer%20Initiated%20Transaction%20is%20not%20supported%20when%20Previous%20Transaction%20or%20Previous%20Network%20Transaction%20is%20present%20in%20the%20request%2e&L_SEVERITYCODE0=Error&AMT=1%2e00&CURRENCYCODE=USD
ReferencePayPal.comPrivacyCookiesSupportLegalContact