SCA payment indicators

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.

Know before you code

You'll need an advanced credit and debit card payments integration.

Add request parameter

Update the POST v2/checkout/orders request body to include stored_payment_source.

Sample request

API endpoint used: Create order

curl -v -X POST https://api.sandbox.paypal.com/v2/checkout/orders \
  -H "Content-Type: application/json"\
  H "Authorization: Bearer <Access-Token>"\
  d '{
    "intent": "CAPTURE",
    "purchase_units": [{
      "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
      "amount":

    {
      "currency_code": "USD",
      "value": "100.00"
    }
  }],
  "application_context": {
    "stored_payment_source":

    {
      "payment_initiator": "MERCHANT",
      "payment_type": "RECURRING",
      "usage": "SUBSEQUENT",
      "previous_transaction_reference": "53963906K75832009"
    }
  },
  "payment_source": {
    "card": {
      "number": "4111111111111111",
      "expiry": "2020-02",
      "name": "John Doe",
      "billing_address":

      {
        "address_line_1": "2211 N First Street",
        "address_line_2": "17.3.160",
        "admin_area_1": "CA",
        "admin_area_2": "San Jose",
        "postal_code": "95131",
        "country_code": "US"
      }
    }
  }
  },

Modify the code

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

  • payment_initiator values (required):
    • CUSTOMER — Customer initiates the payment.
    • MERCHANT — Merchant initiates the transaction and the merchant has established consent to charge the buyer.
  • payment_type values (required):
    • 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 &emdash; default when no stored_payment_source is sent.
  • usage 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.
    • DERIVED — PayPal derives the value of FIRST or SUBSEQUENT based on data available to PayPal.
  • previous_transaction_reference — PayPal transaction ID previously used to charge the buyer. Shows payment processors that you have established a contract with the buyer.
  • previous_network_transaction_reference values:
    • previous_network_transactionID — 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.
  • network_transaction_reference — Reference values used by the card network to identify a transaction.
    • ID (required) — Transaction reference ID returned by the scheme.
    • NETWORK (required) — Name of the card network through which the transaction was routed.
    • DATE — The date that the transaction was authorized by the scheme.

Step result

A successful request results in the following:

  • A return status code of HTTP 201 Created.
  • A JSON response body that contains the processor response.

Use cases

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

One time transaction

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

Recurring plan or subscription

Scenario Payment initiator Payment type Usage
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 type Usage
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

Next steps

Test and go live