# PayPal (/docs/authentication/paypal)

PayPal 提供商的设置和使用。



<Steps>
  <Step>
    ### 获取你的 PayPal 凭证 [#获取你的-paypal-凭证]

    要与 PayPal 集成，你需要通过在 [PayPal 开发者门户](https://developer.paypal.com/dashboard) 创建应用程序来获取 API 凭证。

    按以下步骤操作：

    1. 在 PayPal 开发者门户创建账户
    2. 创建一个新的应用程序，[官方文档](https://developer.paypal.com/developer/applications/)
    3. 在“其他功能”下配置“使用 PayPal 登录”
    4. 设置你的返回 URL（重定向 URL）
    5. 配置用户信息权限
    6. 记录你的客户端 ID 和客户端密钥

    <Callout type="info">
      * PayPal 有两个环境：沙盒（用于测试）和正式（用于生产）
      * 用于测试时，请在“沙盒” → “账户”下创建沙盒测试账户
      * 你不能使用真实的 PayPal 账户在沙盒模式下测试——必须使用生成的测试账户
      * 你的 PayPal 应用程序设置中的返回 URL 必须与重定向 URI 完全匹配
      * PayPal API 不支持 localhost。你需要对重定向 URL 使用公共域名，对本地测试使用 HTTPS。可以使用 [NGROK](https://ngrok.com/) 或其他类似工具实现。
    </Callout>

    确保在应用程序设置中配置“使用 PayPal 登录”：

    1. 转到开发者门户中的应用程序
    2. 在“其他功能”下勾选“使用 PayPal 登录”
    3. 点击“高级设置”
    4. 输入你的返回 URL
    5. 选择你想要访问的用户信息（电子邮件、姓名等）
    6. 输入隐私政策和使用协议 URL

    <Callout type="info">
      * PayPal 在授权 URL 中不使用传统的 OAuth2 范围。相反，你可以在开发者仪表板中直接配置权限
      * 对于正式应用，PayPal 必须审核并批准你的应用，才能上线，这通常需要几周时间
    </Callout>
  </Step>

  <Step>
    ### 配置提供商 [#配置提供商]

    要配置提供商，你需要导入提供商并将其传递给 `socialProviders` 选项。

    ```ts title="auth.ts"
    import { betterAuth } from "better-auth"

    export const auth = betterAuth({
        socialProviders: {
            paypal: { // [!code highlight]
                clientId: process.env.PAYPAL_CLIENT_ID as string, // [!code highlight]
                clientSecret: process.env.PAYPAL_CLIENT_SECRET as string, // [!code highlight]
                environment: "sandbox", // or "live" for production //, // [!code highlight]
            }, // [!code highlight]
        },
    })
    ```

    #### 选项 [#选项]

    PayPal 提供商接受以下选项：

    * `environment`：`'sandbox' | 'live'` - 要使用的 PayPal 环境（默认：`'sandbox'`）
    * `requestShippingAddress`：`boolean` - 是否请求收货地址信息（默认：`false`）

    ```ts title="auth.ts"
    export const auth = betterAuth({
        socialProviders: {
            paypal: {
                clientId: process.env.PAYPAL_CLIENT_ID as string,
                clientSecret: process.env.PAYPAL_CLIENT_SECRET as string,
                environment: "live", // 用于生产环境
                requestShippingAddress: true, // 请求地址信息
            },
        },
    })
    ```
  </Step>

  <Step>
    ### 使用 PayPal 登录 [#使用-paypal-登录]

    要使用 PayPal 登录，你可以使用客户端提供的 `signIn.social` 函数。`signIn` 函数接受一个包含以下属性的对象：

    * `provider`：要使用的提供商。应设置为 `paypal`。

    ```ts title="auth-client.ts"
    import { createAuthClient } from "better-auth/client"
    const authClient =  createAuthClient()

    const signIn = async () => {
        const data = await authClient.signIn.social({
            provider: "paypal"
        })
    }
    ```

    ### 附加选项： [#附加选项]

    * `environment`：要请求的 PayPal 环境。
      * 默认值：`"sandbox"`
      * 选项：`"sandbox"` | `"live"`
    * `requestShippingAddress`：是否请求收货地址信息。
      * 默认值：`false`
    * `scope`：要请求的额外权限（与默认权限合并）。
      * 默认值：在 PayPal 开发者仪表板中配置
      * 注意：PayPal 不使用传统的 OAuth2 范围——权限在仪表板中设置
      * 有关更多详细信息，请参阅 [范围参考](https://developer.paypal.com/docs/log-in-with-paypal/integrate/reference/#scope-attributes)
    * `mapProfileToUser`：自定义函数，用于将 PayPal 配置文件数据映射到用户对象。
    * `getUserInfo`：自定义函数，用于获取用户信息。
      有关更多详细信息，请参阅 [用户参考](https://developer.paypal.com/docs/api/identity/v1/#userinfo_get)
    * `verifyIdToken`：自定义 ID 令牌验证函数。
  </Step>
</Steps>