# Handle consumer onboarding Manage rejection scenarios during consumer credit application and activation. Consumer onboarding has three phases: 1. **Credit application submission**: the platform collects KYC and underwriting data from the consumer. 2. **Credit application review**: underwriting and credit report fraud alert verification occurs. 3. **Revolving credit account activation**: the platform presents terms, records acceptance, and activates the credit policy. Review each section to understand how to handle errors that might occur when onboarding consumers. ## Handle application submission errors During application submission, your platform might need to handle fraud rejections, application timeouts, or identity verification requests from Stripe. The following diagram shows the steps involved for submitting a credit application. ![Diagram showing how the flow of a credit application submission](https://b.stripecdn.com/docs-statics-srv/assets/credit-application-submission.4d3339d67a1904f20709e5ac7b211636.png) ### Handle rejection for platform fraud checks Send an Adverse Action Notice (AAN) for any rejected application and record it for auditing. Stripe can send the AAN and create a suitable audit trail using a [custom email domain](https://docs.stripe.com/get-started/account/email-domain.md) and [co-branding](https://dashboard.stripe.com/settings/connect/emails). If the rejection is due to platform-managed origination fraud checks (for example, with a third-party tool such as Alloy or Sardine), notify Stripe. First, create a connected account for the consumer: ```curl curl https://api.stripe.com/v1/accounts \ -u "<>:" \ -d country=US \ -d "capabilities[transfers][requested]=true" \ -d "controller[stripe_dashboard][type]=none" \ -d "controller[fees][payer]=application" \ -d "controller[losses][payments]=application" \ -d "controller[requirement_collection]=application" \ -d business_type=individual \ -d "business_profile[mcc]=5999" \ --data-urlencode "business_profile[url]=https://www.example.com" ``` Next, create a credit underwriting record with the rejection information. This requires at minimum the consumer’s name and email. Don’t include underwriting information. ```curl curl https://api.stripe.com/v1/issuing/credit_underwriting_records/create_from_application \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "application[purpose]=credit_line_opening" \ -d "application[submitted_at]=1687656783" \ -d "credit_user[name]=Jenny Rosen" \ --data-urlencode "credit_user[email]=jenny.rosen@example.com" ``` Then report the decision as rejected. Specify up to four reasons: ```curl curl https://api.stripe.com/v1/issuing/credit_underwriting_records/{{CREDITUNDERWRITINGRECORD_ID}}/report_decision \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d decided_at=1687864060 \ -d "decision[type]=application_rejected" \ -d "decision[application_rejected][reasons][]=suspected_fraud" ``` ### Handle rejection for application timeout If a consumer doesn’t complete their application within 30 days of starting it, reject the application. - **Hosted Underwriting**: Stripe handles the timer and rejection emails. Trigger the timer by creating the issuing program on the consumer’s connected account at the point when the consumer clicks the final **Submit** button in your UI. - **BYO Underwriting**: You’re responsible for tracking the timer from when the consumer enters the application flow. To reject a timed-out application, follow the steps in [Reject for platform fraud checks](https://docs.stripe.com/issuing/consumer-issuing/onboarding.md#handle-rejection-for-platform-fraud-checks) using the reason code `incomplete_application`. ### Handle government ID verification Stripe performs its own KYC verification to comply with financial partner requirements, even if your platform has already verified the consumer. Most verification succeeds using the consumer’s personal data, but in some cases Stripe requires a government ID document upload. When this happens, Stripe returns `requirements` on the account indicating that the consumer needs to upload a document. See [Handle identity verification](https://docs.stripe.com/connect/handling-api-verification.md#handle-identity-verification) to implement this flow. ## Handle application review errors During application review, Stripe handles underwriting and fraud alert checks and notifies your platform of rejections through webhooks. The following diagram shows the steps involved during an application review. ![Diagram showing the steps of an application review](https://b.stripecdn.com/docs-statics-srv/assets/credit-application-review.c407fe02338e646569133464d3e917ad.png) ### Handle rejection for underwriting rules > Specific reason codes for underwriting rejections are subject to change. Stripe rejects or terminates a consumer’s application during underwriting in two cases: - Additional information is required, for example because the credit file was frozen. - The application was rejected because of knock-out rules in the underwriting policy. In either case, Stripe sends the appropriate regulated notices (either an AAN or a Notice of Incompleteness) to the consumer directly. Stripe notifies your platform through an `issuing.credit_underwriting_record.updated` webhook where `decision.type` is `application_rejected`. Based on `decision.application_rejected.reasons`, you can redirect the consumer to restart the application. The reason code `frozen_file_at_credit_bureau` indicates a frozen credit file. The consumer can re-apply after unfreezing it. For Hosted Underwriting, Stripe performs a soft credit pull (no impact on the consumer’s credit history), so re-application is safe. ### Handle rejection for fraud alerts > Specific reason codes for fraud alert rejections are subject to change. Stripe reviews credit reports for fraud alerts. An application might be rejected for two reasons: - **Additional information required:** - If the fraud alert doesn’t include a phone number, Stripe emails the consumer to request identity documents and auto-rejects after 30 days without a response. - If the fraud alert includes a phone number but the consumer doesn’t answer, Stripe sends a notice to verify identity and rejects after a second unanswered call. - **Confirmed fraud:** - The identity document provided can’t be verified. - The consumer confirms on the call that they didn’t apply for the card. As with underwriting rejections, Stripe sends the appropriate notices to the consumer. The `decision.type` on the credit underwriting record is `application_rejected` with a suitable reason code. If a consumer misses the window to verify their identity during a fraud alert check, `decision.application_rejected.reasons` includes the reason code `unable_to_verify_identity`. You can redirect the consumer to re-apply. ## Handle account activation errors During account activation, your platform presents the approval notice and handles edge cases that can occur after the consumer accepts the offer. The following diagram shows the steps involved during account activation. ![Diagram showing the flow of account activation](https://b.stripecdn.com/docs-statics-srv/assets/credit-activation.89c016ef839f66e47a43b59983d84750.png) ### Show the approval notice Under [Reg B](https://www.consumerfinance.gov/rules-policy/regulations/1002/9/#a-1-i), a credit card program must notify the consumer when their application is approved and include a credit score disclosure. Your platform is responsible for showing the approval status in your UI. Stripe sends the regulatory credit score disclosure notice to the consumer directly. ### Handle a frozen credit file at hard pull Stripe performs the hard credit pull only after the consumer accepts the offer. If the credit file is frozen at that point, Stripe sends a regulated notice to the consumer and notifies your platform with a webhook. You can redirect the consumer to re-apply. The 30-day response window resets at this stage. The consumer has 30 days to respond to the credit offer before Stripe sends an AAN. If a consumer places a fraud alert between the soft and hard pull, Stripe re-runs fraud alert verification. ### Handle watchlist screening rejection All cardholders pass through watchlist screening when you create a cardholder object. Stripe might mark a cardholder as `disabled` or `rejected`. When `disabled`, Stripe specifies the personal data required to continue verification. See [Issuing watchlist screening](https://docs.stripe.com/issuing/issuing-watchlist.md) for how to handle these scenarios. Providing the cardholder’s date of birth to Stripe at cardholder creation allows us to better match identities and reduces the likelihood of a screening rejection. > A consumer who successfully completes onboarding using the Accounts API must pass watchlist screening when their cardholder object is later created using `/v1/issuing/cardholders`.