Migrate your basic card integration

Migrate your mobile app to an integration that can handle bank requests for card authentication.

If you followed the Card payments without bank authentication guide, your integration creates payments that decline when a bank asks the customer to authenticate the purchase.

If you start seeing many failed payments like the one in the Dashboard below or with an error code of requires_action_not_handled in the API, upgrade your basic integration to handle, rather than decline, these payments.

Use this guide to learn how to upgrade the integration you built in the previous guide to add server and client code that prompts the customer to authenticate the payment by displaying a modal.

Note

See a full sample of this integration on GitHub.

Check if the payment requires authentication Server-side

Make three changes to the endpoint on your server that creates the PaymentIntent:

1. Remove the error_on_requires_action parameter to no longer fail payments that require authentication. Instead, the PaymentIntent status changes to requires _ action .
2. Add the confirmation _ method parameter to indicate that you want to explicitly (manually) confirm the payment again on the server after handling authentication requests.
3. Add the use_stripe_sdk parameter to enable your mobile client to handle additional authentication steps.

Command Line

Select a language

curl

Ruby

Python

PHP

Node.js

Java

Go

.NET

No results

Then update your “generate response” function to handle the requires_action state instead of erroring:

Command Line

Select a language

curl

Ruby

Python

PHP

Node.js

Java

Go

.NET

No results

# If the request succeeds, check the
# PaymentIntent's `status` and handle
# its `next_action`.

Ask the customer to authenticate Client-side

Next, update your iOS code to tell Stripe to show a modal if the customer needs to authenticate.

Use handleNextActionForPayment when a PaymentIntent has a status of requires_action. If successful, the PaymentIntent will have a status of requires_confirmation and you need to confirm the PaymentIntent again on your server to finish the payment.

Select a language

Objective-C

Swift

No results

- (void)handleResponse:(NSDictionary *)json {
 if (json[@"error"] != nil) {
 // Display the error to the customer
 } else if (json[@"requiresAction"]) {
 // Payment requires additional actions
 NSString *clientSecret = json[@"clientSecret"];
 STPPaymentHandler *paymentHandler = [STPPaymentHandler sharedHandler];
 [paymentHandler handleNextActionForPayment:clientSecret
 withAuthenticationContext:self
 returnURL:nil
 completion:^(STPPaymentHandlerActionStatus status, STPPaymentIntent *paymentIntent, NSError *handleActionError) {
 switch (status) {
 case STPPaymentHandlerActionStatusFailed: {
 // Display handleActionError to the customer
 break;
 }
 case STPPaymentHandlerActionStatusCanceled: {
 // Canceled
 break;
 }
 case STPPaymentHandlerActionStatusSucceeded: {
 // The card action has been handled
 // Send the PaymentIntent ID to your server and confirm it again
 break;
 }
 default:
 break;
 }
 }];
 } else {
 // Display success message
 }
}

# pragma mark STPAuthenticationContext
- (UIViewController *)authenticationPresentingViewController {
 return self;
}

Confirm the PaymentIntent again Server-side

Using the same endpoint you set up earlier, confirm the PaymentIntent again to finalise the payment and fulfil the order. The payment attempt fails and transitions back to requires_payment_method if it isn’t confirmed again within one hour.

Command Line

Select a language

curl

Ruby

Python

PHP

Node.js

Java

Go

.NET

No results

Test the integration

Use our test cards in a sandbox to verify that your integration was properly updated. Stripe displays a fake authentication page inside the modal in a sandbox that lets you simulate a successful or failed authentication attempt. In live mode the bank controls the UI of what’s displayed inside the modal.