Skip to main content

Documentation Index

Fetch the complete documentation index at: https://apidocs.bridge.xyz/llms.txt

Use this file to discover all available pages before exploring further.

To issue a card to a customer, you must request a cards endorsement on the Bridge Customer object. This endorsement has specific requirements that differ from other endorsements, and a customer’s eligibility may also depend on whether your card program is approved to operate in a given region. In addition, Bridge and Stripe perform validations on the address and other information provided for the Customer object. When the cards endorsement is approved, Bridge automatically creates a Cardholder object and returns the cardholder ID in the customer object. You use this ID to create cards via the Stripe API. The ability to create and use cards is dependent on an active approved cards endorsement. This page provides an overview of the cards endorsement request process, how to see the endorsement’s requirements and status, and common issues that may occur for a customer requesting the cards endorsement. Whether you’re onboarding a new customer or issuing a card to an existing one, use the Customer KYC Link endpoint with a ?endorsement=cards query parameter. 
GET /v0/customers/<customerID>/kyc_link?endorsement=cards
When requesting multiple endorsements at once (for example, cards and SEPA), use: 
?endorsement[]=cards&endorsement[]=sepa
The response returns a short-lived URL: 
{
    "url": "https://bridge.withpersona.com/inquiry?inquiry-id=inq_CncY1CqRivqDMcjkxW9PMv2aPBnE"
}
This opens a flow for the customer to complete KYC or confirm their previously-provided information is up to date. Don’t store this URL—it may expire at any time. If the customer completed KYC within the past 24 hours, they’re immediately approved for the cards endorsement. Otherwise, approval is not immediate—you must monitor the endorsement status via the Customer endpoint or webhooks.

​
Check endorsement status

The cards endorsement status is available on the Customer object in the endorsements array. You can also receive updates via the customer webhook event category. Once approved, the customer object will contain both the endorsed status and a stripe_cardholder_id: 
{
    "id": "1e210e5b-700e-41e6-a62a-0eb0b6ac1967",
    "first_name": "Jenny",
    "last_name": "Rosen",
    "email": "jenny.rosen@example.com",
    "status": "active",
    "type": "individual",
    "stripe_cardholder_id": "ich_1SVf3CG6FooBAru7mB2MSrDY",
    "endorsements": [
        {
            "name": "cards",
            "status": "approved",
            "requirements": {
                "complete": [
                    "terms_of_service_v1",
                    "first_name",
                    "last_name",
                    "tax_identification_number",
                    "email_address",
                    "address_of_residence",
                    "date_of_birth",
                    "proof_of_address",
                    "sanctions_screen",
                    "pep_screen",
                    "blocklist_lookup",
                    "min_age_18",
                    "database_lookup",
                    "government_id_verification",
                    "customer_region_supports_cards",
                    "customer_address_is_valid_for_cards"
                ],
                "pending": [],
                "missing": null,
                "issues": []
            }
        }
    ]
}
The stripe_cardholder_id represents a cardholder already created in Stripe that you can use directly to create cards via the Stripe API. Bridge manages the cardholder object—the Stripe Cardholder API is read-only for Bridge-managed cardholders. If you use Stripe webhooks, you’ll also receive an issuing_cardholder.created event when the cardholder is created.

​
Endorsement expiry and renewal

The cards endorsement is valid for 24 hours after approval. If no card is created within that window, the endorsement automatically transitions to revoked—this is a compliance requirement to ensure customer information is confirmed within 24 hours of card creation. When the endorsement is revoked, Bridge automatically transitions the Cardholder to an inactive status. To re-enable the customer, request a new KYC link for the cards endorsement. Once the customer completes the fresh KYC confirmation, the endorsement is re-approved and Bridge reactivates the cardholder in Stripe.

​
Eligibility issues

If there are eligibility issues, the endorsement will be in an incomplete state with details in the issues field. In addition to standard issues, the following are specific to the cards endorsement:
IssueDescription
endorsement_not_available_in_customers_regionCards isn’t supported in the customer’s country or state—either due to MTL regulations or because your program hasn’t been approved for that region.
residence_address_invalid_cityThe city name is invalid. For cards, city names have a maximum length of 30 characters and may only include letters, spaces, hyphens, and periods.
residence_address_invalid_address_line1The first address line must contain at least 4 characters.
residence_address_invalid_postal_codeA valid postal code is required (4–10 characters). Some countries without postal code systems receive a default, but most require one.
residence_address_invalid_subdivision_codeThe subdivision code was omitted or is invalid.
address_of_residence_postal_code_invalid_formatThe individual customer’s residence address has an invalid postal code.
address_of_operation_postal_code_invalid_formatThe commercial card business customer’s address of operation has an invalid postal code.
address_of_incorporation_postal_code_invalid_formatFor commercial card business customer’s address of incorporation has an invalid postal code.
For the cards endorsement, Bridge and Stripe apply stricter validations on the residence address, address of operation, or address of incorporation for the customer. You can see a comprehensive list of postal code validations performed by country here.

​
Managing KYC issues in the Bridge Dashboard

You can view and manage KYC status for all customers in the Customers section of the Bridge Dashboard. When a customer is missing required steps, their page will indicate what’s outstanding. When a fresh KYC is needed for the cards endorsement, the page will indicate that cards access is pending.