SCA payment indicators for Website Payments Pro

DOCS

Last updated: Sept 19th, 12:53am

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

    1ACCT=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

      1ACCT=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

        1ACCT=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

          1ACCT=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

            1ACCT=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.

            • 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

            Scenario Payment initiator Payment category Card on file
            Single payment. Buyer doesn't intend to do a follow-on purchase or save their card. CUSTOMER ONE_TIME —
            Single payment. Buyer saves their card details for a future single payment. CUSTOMER ONE_TIME FIRST
            Single payment. Buyer uses a previously-saved card to complete the transaction. CUSTOMER ONE_TIME SUBSEQUENT

            Recurring plan or subscription

            Scenario Payment initiator Payment category Card on file
            Initial transaction to sign up for the recurring charges. Buyer hasn't saved their card with you. CUSTOMER RECURRING FIRST
            Initial transaction to sign up for the recurring charges. Buyer has already saved their card with you. CUSTOMER RECURRING SUBSEQUENT
            Subsequent payments as part of a recurring plan. MERCHANT RECURRING SUBSEQUENT
            Initial customer-initiated transaction wasn't processed with PayPal. Merchant processes recurring charge with PayPal. MERCHANT RECURRING SUBSEQUENT

            Unscheduled payment

            Scenario Payment initiator Payment category Card on file
            Initial transaction to sign up for an unscheduled payment. Buyer has not saved their card with you. CUSTOMER UNSCHEDULED FIRST
            Initial transaction to sign up for an unscheduled payment. Buyer has already saved their card with you. CUSTOMER UNSCHEDULED SUBSEQUENT
            Subsequent payments as part of the unscheduled contract. MERCHANT UNSCHEDULED SUBSEQUENT
            Initial customer-initiated transaction wasn't processed with PayPal. Merchant processes unscheduled charge with PayPal. MERCHANT UNSCHEDULED SUBSEQUENT

            Error response samples

            • PAYMENTCATEGORY is not passed for Merchant Initiated Transactions

                1TIMESTAMP=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

              1. CARDONFILE is sent as FIRST for Merchant Initiated Transactions

                  1TIMESTAMP=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

                1. CVV2 is passed for Merchant Initiated Transactions

                    1TIMESTAMP=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

                  1. 3D-Secure results are passed for Merchant Initiated Transactions

                      1TIMESTAMP=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

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

                        1TIMESTAMP=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

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

                          1TIMESTAMP=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

                        We use cookies to improve your experience on our site. May we use marketing cookies to show you personalized ads? Manage all cookies