SCA payment indicators

Last updated: Aug 15th, 7:30am

If you process payments that require Strong Customer Authentication (SCA), you need to provide additional context about the transaction with payment indicators. The payment indicators ensure that buyer authentication, card on file, and other factors are appropriately handled. Pass these payment indicators to avoid rejected transactions.

To provide additional transaction context, include stored_payment_source in your create order request.

Know before you code

Required

Required integration:

  • Advanced checkout integration
See advanced checkout integration

Add request parameter

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

Sample request

API endpoint used: Create order

    1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
    2-H "Content-Type: application/json" \
    3-H "Authorization: Bearer <Access-Token>" \
    4-H "PayPal-Partner-Attribution-Id: <BN-Code>" \
    5-d '{
    6 "intent": "CAPTURE",
    7 "purchase_units": [{
    8 "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
    9 "amount": {
    10 "currency_code": "USD",
    11 "value": "100.00"
    12 }
    13 }],
    14 "payment_source": {
    15 "card": {
    16 "number": "4111111111111111",
    17 "expiry": "2020-02",
    18 "name": "John Doe",
    19 "billing_address":
    20 {
    21 "address_line_1": "2211 N First Street",
    22 "address_line_2": "17.3.160",
    23 "admin_area_1": "CA",
    24 "admin_area_2": "San Jose",
    25 "postal_code": "95131",
    26 "country_code": "US"
    27 },
    28 "stored_credential":
    29 {
    30 "payment_initiator": "MERCHANT",
    31 "payment_type": "RECURRING",
    32 "usage": "SUBSEQUENT",
    33 "previous_transaction_reference": "53963906K75832009"
    34 }
    35 }
    36 }
    37 }'

    Modify the code

    Copy the code snippet and modify the values for stored_credential as follows:

    payment_initiatorRequired
    ValueDescription
    CUSTOMERCustomer initiates the payment.
    MERCHANTMerchant initiates the transaction and the merchant has established consent to charge the buyer.
    payment_typeRequired
    ValueDescription
    UNSCHEDULEDPayments 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_.
    RECURRINGMerchant 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_TIMEDefault when no stored_credential is sent.
    usage
    ValueDescription
    FIRSTSave card information or payment token to use in subsequent transactions. Collect consent from the buyer that you intend to save their payment information.
    SUBSEQUENTCard information or payment token was previously saved and is used in the transaction.
    DERIVEDThe value of FIRST or SUBSEQUENT is determined based on the data available.
    previous_transaction_reference

    Transaction ID previously used to charge the payer. Shows payment processors that you have established a contract with the payer.

    previous_network_transaction_reference
    ValueDescription
    previous_network_transactionIDTransaction ID from a non-PayPal payment processor that you have previously used to process the payment.
    networkTransaction ID 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.

    ValueDescription
    ID RequiredTransaction reference ID returned by the scheme.
    NETWORK RequiredName of the card network through which the transaction was routed.
    DATEThe 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

    ScenarioPayment initiatorPayment typeUsage
    Single payment. Payer doesn't intend to make another purchase or save their card.CUSTOMERONE_TIMEDERIVED
    Single payment. Payer saves their card details for a future single payment.CUSTOMERONE_TIMEFIRST
    Single payment. Payer uses a previously-saved card to complete the transaction.CUSTOMERONE_TIMESUBSEQUENT

    Recurring plan or subscription

    ScenarioPayment initiatorPayment typeUsage
    Initial transaction to sign up for the recurring charges. Payer hasn't saved their card.CUSTOMERRECURRINGFIRST
    Initial transaction to sign up for the recurring charges. Payer has already saved their card.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 typeUsage
    Initial transaction to sign up for an unscheduled payment. Payer has not saved their card.CUSTOMERUNSCHEDULEDFIRST
    Initial transaction to sign up for an unscheduled payment. Payer has already saved their card.CUSTOMERUNSCHEDULEDSUBSEQUENT
    Subsequent payments as part of the unscheduled contract.MERCHANTUNSCHEDULEDSUBSEQUENT
    Initial payer-initiated transaction wasn't processed with PayPal. Merchant processes unscheduled charge with PayPal.MERCHANTUNSCHEDULEDSUBSEQUENT

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