Pass SCA payment indicators

DocsCurrentADVANCED

Last updated: Oct 21st, 9:06am

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

Required

You need an Advanced Credit and Debit Card payments integration.

Use Postman to explore and test PayPal APIs.

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
11    {
12      "currency_code": "USD",
13      "value": "100.00"
14    }
15  }],
16  "payment_source": {
17    "card": {
18      "number": "4111111111111111",
19      "expiry": "2020-02",
20      "name": "John Doe",
21      "billing_address":
22
23      {
24        "address_line_1": "2211 N First Street",
25        "address_line_2": "17.3.160",
26        "admin_area_1": "CA",
27        "admin_area_2": "San Jose",
28        "postal_code": "95131",
29        "country_code": "US"
30      },
31      "stored_credential":
32      {
33        "payment_initiator": "MERCHANT",
34        "payment_type": "RECURRING",
35        "usage": "SUBSEQUENT",
36        "previous_transaction_reference": "53963906K75832009"
37      }
38    }
39  }
40  },

Modify the code

Copy the code snippet and modify the values for stored_credential as needed.

Change BN-Code to your PayPal Partner Attribution ID.

payment_initiator - Required. The possible values are:
- CUSTOMER - A customer initiates the payment.
- MERCHANT - The merchant initiates the transaction and has established consent to charge the buyer.

payment_type - Required. The possible values are:
- 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 after a balance falls within a specified range. These transactions are also known as top-up.
- RECURRING - The merchant initiates a payment as part of recurring payments. The payment amounts can be variable and are on a fixed time interval.
- ONE_TIME - Default when no stored_credential is sent.

usage - The possible values are:
- FIRST - Save the card information or payment token for subsequent transactions. Collect consent from the buyer that you intend to save their payment information.
- SUBSEQUENT - The card information or payment token previously saved and is used in the transaction.
- DERIVED - PayPal derives the value of FIRST or SUBSEQUENT based on the data available to PayPal.

previous_transaction_reference - A PayPal transaction ID previously used to charge the buyer. It shows payment processors that you have established a contract with the buyer.

previous_network_transaction_reference - The possible values are:
- previous_network_transactionID - The transaction ID from a non-PayPal payment processor you previously used to process the payment.
- network - The transaction ID from a non-PayPal payment processor you previously used to process the payment.

network_transaction_reference - Reference values used by the card network to identify a transaction. The possible values are:
- ID - Required. A transaction reference ID returned by the scheme.
- NETWORK - Required. The name of the card network through which the transaction was routed.
- DATE - The date 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 to update your integration.

One time transaction

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

Recurring plan or subscription

Scenario	Payment initiator	Payment type	Usage
An initial transaction to sign up for the recurring charges. The buyer hasn't saved their card with you.	`CUSTOMER`	`RECURRING`	`FIRST`
An initial transaction to sign up for the recurring charges. The buyer has already saved their card with you.	`CUSTOMER`	`RECURRING`	`SUBSEQUENT`
Subsequent payments as part of a recurring plan.	`MERCHANT`	`RECURRING`	`SUBSEQUENT`
An initial customer-initiated transaction wasn't processed with PayPal. Merchants process recurring charges with PayPal.	`MERCHANT`	`RECURRING`	`SUBSEQUENT`

Unscheduled payment

Scenario	Payment initiator	Payment type	Usage
An initial transaction to sign up for an unscheduled payment. The buyer has not saved their card with you.	`CUSTOMER`	`UNSCHEDULED`	`FIRST`
An initial transaction to sign up for an unscheduled payment. The buyer has already saved their card with you.	`CUSTOMER`	`UNSCHEDULED`	`SUBSEQUENT`
Subsequent payments as part of the unscheduled contract.	`MERCHANT`	`UNSCHEDULED`	`SUBSEQUENT`
An initial customer-initiated transaction wasn't processed with PayPal. The merchant processes unscheduled charges with PayPal.	`MERCHANT`	`UNSCHEDULED`	`SUBSEQUENT`

Next steps

Required
Go live

How to take your application live.