User authentication

Goal

Detect when a payment requires step-up authentication and present the authentication UI so the user can complete the payment.

Steps

Step 1: Configure the authorization UI

What you need to do

Decide how the authentication UI will be presented to the user (iframe or redirect/webview) and configure the authorization request accordingly.

How to do it

1. Determine the presentation method based on your application environment (see determining how to display the authentication UI)
2. If the user should be redirected at completion of the flow, include the redirect_url parameter in the request to authorize-payment.

Step 2: Detect when authentication is required

What you need to do

Detect when the response from the authorization engine indicates that the user must authenticate.

The authorization engine may request user authentication on any payment, regardless of whether the user processing using a new card or a previously-stored credential.

How to do it

1. When calling authorize-payment, if the HTTP status code of the response is 202 Accepted, authentication is required.
2. Persist the intent id with your internal transaction record and return the authentication url to your frontend in order to display it to the user.

Step 3: Retrieve the final payment result

What you need to do

After the authentication process concludes, determine the final status of the payment.

How to do it

1. Make an authenticated request to get-an-intent from your application.
2. Use the returned status to update your internal transaction record and notify the user about success or failure.

Authorize Payment With Authentication Redirect

curl --request POST \
  --url https://sandbox.pushcash.com/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "user_lVpbPL0K1XIiHx0DxipRbD",
  "amount": 2500,
  "currency": "USD",
  "direction": "cash_in",
  "credential_id": "cred_sandbox_123",
  "redirect_url": "https://yourapp.com/payment/complete"
}
'

Authentication Required - 202 Accepted

{
  "id": "intent_sandbox_dMggQ93ZYH6DH9LBhVeijE",
  "url": "https://cdn.pushcash.com/ux/intent_sandbox_dMggQ93ZYH6DH9LBhVeijE"
}

Determining how to display the authentication UI

Choose the presentation based on how the user accesses your application:

• Web (mobile or desktop): present the authentication UI in an iframe. The authentication UI will signal the conclusion of the flow by submitting a message to the top-level browser window using postMessage.
• Native mobile app or embedded webview: present the UI in a secure system webview (e.g. iOS ASWebAuthenticationSession).

If using redirects, set redirect_url on the authorization request. For mobile webviews, use a custom scheme (e.g. pushcash://) and dismiss the webview when the redirect URL matches.

Integration checklist

• Include redirect_url in the authorize request if you will be redirecting the user to the authentication flow vs. using an iframe embed
• Handle 202 Accepted responses from authorize-payment and present the authentication UI hosted at url to the user.
• Persist the intent id before presenting the authentication experience to the user alongside your internal transaction record.
• Test authentication required response from authorization engine using test card 6011 0009 9013 9424
• Test a payment decline after the user completes authentication using test card 5999 9819 6976 9283

Next steps

Now that you can process payments which require user authentication, learn how to enable webhook notifications to receive asynchronous updates on the final payment result.