On this page
No Headings
Last updated: June 26, 2026
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.
Update the POST v2/checkout/orders request body to include stored_credential.
API endpoint used: Create order
curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
-H "Content-Type: application/json"\
-H "Authorization: Bearer <Access-Token>"\
-H 'PayPal-Partner-Attribution-Id: <BN-Code>' \
d '{
"intent": "CAPTURE",
"purchase_units": [{
"reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
"amount":
{
"currency_code": "USD",
"value": "100.00"
}
}],
"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"
},
"stored_credential":
{
"payment_initiator": "MERCHANT",
"payment_type": "RECURRING",
"usage": "SUBSEQUENT",
"previous_transaction_reference": "53963906K75832009"
}
}
}
},Copy the code snippet and modify the values for stored_credential as needed.
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. This field may not be returned for all networks. MasterCard refers to this field as "BankNet reference date". For some specific networks, such as MasterCard and Discover, this date field is mandatory when the previous_network_transaction_reference_id is passed.A successful request results in the following:
201 Created.You can use these common scenarios to determine how to update your integration.
| 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 |
| 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 |
| 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 |