SCA payment indicators for Website Payments Pro

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 an existing Direct Payments integration and are adding 3-D Secure to that integration using CardinalCommerce's Cardinal Cruise technology.
    • 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.

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

    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