심층 분석: PayPal 통합 파트 2: PayPal REST API

이 튜토리얼에서는 PayPal REST API와 C#을 사용하여 결제하는 방법을 보여 드리겠습니다. Ruby, Node.js, Python, PHP 등과 같은 다양한 언어에 제공되는 모든 라이브러리는 매우 유사하므로 여기에 있는 모든 개념은 모든 라이브러리에 적용 가능합니다.

프로젝트 설정

먼저 Visual Studio 2015에서 파일 > 새로 만들기 > 프로젝트 로 MVC 프로젝트를 만들고 ASP.NET Application을 선택했습니다.

새로운 MVC 6을 사용하는 ASP.NET 5 Web Application 템플릿을 선택합니다. 익숙하다면 MVC 5와 유사합니다.

아래 사진에서 볼 수 있듯이 솔루션에 일부 파일과 폴더를 추가했습니다. 주목해야 할 두 가지 주요 사항은 다음과 같습니다.

1. References에서 이 프로젝트를 Mac OS X 또는 Linux에서 실행할 수 있는 대상 DNX Core 5.0을 제거했지만 필요한 PayPal 라이브러리는 아직 업데이트되지 않았습니다.
2. 컨트롤러를 간단하고 명확하게 유지할 수 있도록 PayPal 호출 논리를 캡슐화할 "서비스" 폴더를 추가했습니다.

NuGet을 사용하여 PayPal SDK를 설치하세요. 솔루션 이름을 마우스 오른쪽 버튼으로 클릭하고 NuGet 패키지 관리를 선택한 다음 "PayPal"을 검색하여 설치하세요.

PayPal 앱 만들기

애플리케이션을 PayPal과 통합하려면 PayPal 개발자로 이동하여 REST API 애플리케이션에서 애플리케이션 만들기를 클릭해야 합니다.

앱 이름을 지정하고 앱과 연결할 샌드박스 개발자 계정을 선택하세요. 테스트 목적으로 http://sandbox.paypal.com으로 이동하여 샌드박스 로그인 세부 정보를 사용하여 로그인하여 테스트 PayPal 계정 및 거래를 볼 수 있습니다.

앱 만들기를 클릭하면 클라이언트 ID와 비밀 토큰이 포함된 확인 화면이 나타납니다.

아래 스크린샷과 같이 clientId 및 clientSecret 토큰을 appsettings.json에 복사합니다.

테스트 결제

PayPal은 테스트를 위한 샌드박스 환경을 제공합니다. 여기에서 테스트 구매자 및 판매자 계정을 생성할 수 있습니다. 가입하고 나면 개발자 계정과 연결된 샌드박스에 기업 계정이 생성됩니다.

새 테스트 계정을 만들려면 개발자 웹사이트에 로그인한 다음 제어판 탭을 클릭하고 샌드박스 > 계정으로 이동하세요. 여기에서 테스트 계정 목록(사용 가능한 경우)을 볼 수 있습니다.

아직 테스트 계정을 만들지 않았다면 오른쪽 상단의 계정 만들기를 클릭하여 최소한 테스트 개인 계정과 테스트 비즈니스 계정을 만드세요.

테스트 계정을 만든 후 이전 양식에서 각 계정에 할당한 테스트 이메일 주소와 비밀번호를 사용하여 www.sandbox.paypal.com을 통해 로그인할 수 있습니다. 이는 개인 테스트 계정을 사용하여 구매할 때 자금이 테스트 비즈니스 계정으로 이체되는지 여부를 테스트하는 데 유용합니다. 이제 PayPal과의 통합을 시작하고 자금이 한 계좌에서 다른 계좌로 이체되는지 테스트할 준비가 되었습니다.

单一 PayPal 付款

PayPal 提供不同的付款方式。您可以使用直接信用卡付款，这意味着您的客户无法看到 PayPal 登录页面或摘要 - 这一切都发生在您的网站上。为此，您需要符合 PCI 标准，我建议使用 Stripe，因为您只需要使用其 JavaScript 库的 SSL。另一方面，要通过 PayPal 付款，需要三个步骤：

1. 指定付款信息以创建付款。
2. 获得付款批准，将您的客户重定向至 PayPal 以批准交易。
3. 在 PayPal 将您的客户重定向回您的网站后，执行付款以获取资金。

在我的 MVC 项目的 Services 文件夹中，我创建了 PayPalPaymentService 类，并在其中添加了以下方法：

public static Payment CreatePayment(string baseUrl, string intent)
{
    // ### Api Context
    // Pass in a `APIContext` object to authenticate 
    // the call and to send a unique request id 
    // (that ensures idempotency). The SDK generates
    // a request id if you do not pass one explicitly. 
    var apiContext = PayPalConfiguration.GetAPIContext();

    // Payment Resource
    var payment = new Payment()
    {
        intent = intent,    // `sale` or `authorize`
        payer = new Payer() { payment_method = "paypal" },
        transactions = GetTransactionsList(),
        redirect_urls = GetReturnUrls(baseUrl, intent)
    };

    // Create a payment using a valid APIContext
    var createdPayment = payment.Create(apiContext);

    return createdPayment;
}

private static List<Transaction> GetTransactionsList()
{
    // A transaction defines the contract of a payment
    // what is the payment for and who is fulfilling it. 
    var transactionList = new List<Transaction>();

    // The Payment creation API requires a list of Transaction; 
    // add the created Transaction to a List
    transactionList.Add(new Transaction()
    {
        description = "Transaction description.",
        invoice_number = GetRandomInvoiceNumber(),
        amount = new Amount()
        {
            currency = "USD",
            total = "100.00",       // Total must be equal to sum of shipping, tax and subtotal.
            details = new Details() // Details: Let's you specify details of a payment amount.
            {
                tax = "15",
                shipping = "10",
                subtotal = "75"
            }
        },
        item_list = new ItemList()
        {
            items = new List<Item>()
            {
                new Item()
                {
                    name = "Item Name",
                    currency = "USD",
                    price = "15",
                    quantity = "5",
                    sku = "sku"
                }
            }
        }
    });
    return transactionList;
}

private static RedirectUrls GetReturnUrls(string baseUrl, string intent)
{
    var returnUrl = intent == "sale" ? "/Home/PaymentSuccessful" : "/Home/AuthorizeSuccessful";

    // Redirect URLS
    // These URLs will determine how the user is redirected from PayPal 
    // once they have either approved or canceled the payment.
    return new RedirectUrls()
    {
        cancel_url = baseUrl + "/Home/PaymentCancelled",
        return_url = baseUrl + returnUrl
    };
}

public static Payment ExecutePayment(string paymentId, string payerId)
{
    // ### Api Context
    // Pass in a `APIContext` object to authenticate 
    // the call and to send a unique request id 
    // (that ensures idempotency). The SDK generates
    // a request id if you do not pass one explicitly. 
    var apiContext = PayPalConfiguration.GetAPIContext();
    
    var paymentExecution = new PaymentExecution() { payer_id = payerId };
    var payment = new Payment() { id = paymentId };

    // Execute the payment.
    var executedPayment = payment.Execute(apiContext, paymentExecution);

    return executedPayment;
}

此调用中传递了一些参数：

• 意图：三个可能的值：“销售”用于立即付款，“授权”用于授权稍后捕获付款，或“订单”用于创建订单。当您获得授权稍后收取付款时，您有 3 天的保证期限，不过您最多可以在 29 天后尝试收取付款。
• 付款人：此付款的资金来源、所使用的付款方式 - PayPal 电子钱包付款、银行直接借记卡或直接信用卡。
• 交易：用于指定付款金额，并可以选择指定要支付的项目。如果需要，您还可以指定小计、运费和税费。
• 重定向网址：指定 PayPal 在交易后将您的客户重定向到的网址，以便您可以更新数据库并显示确认消息。

可以从控制器中使用以前的功能，如下所示：

public IActionResult CreatePayment()
{
    var payment = PayPalPaymentService.CreatePayment(GetBaseUrl(), "sale");
    
    return Redirect(payment.GetApprovalUrl());
}

public IActionResult PaymentCancelled()
{
    // TODO: Handle cancelled payment
    return RedirectToAction("Error");
}

public IActionResult PaymentSuccessful(string paymentId, string token, string PayerID)
{
    // Execute Payment
    var payment = PayPalPaymentService.ExecutePayment(paymentId, PayerID);

    return View();
}

如您所见，我创建了三个操作：

• CreatePayment：这是触发付款的操作。它会调用 PayPal 以创建付款，然后将用户重定向到 PayPal 以批准交易。
• 付款成功：这是 PayPal 在成功付款后将客户重定向回来的操作。此时，我们可以执行付款，将资金转入我们的商家帐户。
• PaymentCancelled：如果用户取消审批流程，则将用户从 PayPal 重定向到此操作。此时，您可能希望让客户选择重试或与您联系。

授权付款以便稍后获取

此场景与前一个案例非常相似。如果您尝试预订尚未上市的产品，您可能需要使用此方法。获得这笔付款的步骤是：

1. 授权付款：此调用的“意图”参数应为“授权”。
2. 获取付款：请记住，授权最多可保证 3 天，但您可以尝试获取最长 29 天的付款。

为了实现这种类型的付款，我只在 PayPalPaymentService 类中添加了一个新方法来捕获付款：

public static Capture CapturePayment(string paymentId)
{
    var apiContext = PayPalConfiguration.GetAPIContext();

    var payment = Payment.Get(apiContext, paymentId);
    var auth = payment.transactions[0].related_resources[0].authorization;

    // Specify an amount to capture.  By setting 'is_final_capture' to true, all remaining funds held by the authorization will be released from the funding instrument.
    var capture = new Capture()
    {
        amount = new Amount()
        {
            currency = "USD",
            total = "4.54"
        },
        is_final_capture = true
    };

    // Capture an authorized payment by POSTing to
    // URI v1/payments/authorization/{authorization_id}/capture
    var responseCapture = auth.Capture(apiContext, capture);

    return responseCapture;
}

然后，我在 HomeController 中添加了两个新操作来显示此类付款：

public IActionResult AuthorizePayment()
{
    var payment = PayPalPaymentService.CreatePayment(GetBaseUrl(), "authorize");
    
    return Redirect(payment.GetApprovalUrl());
}

public IActionResult AuthorizeSuccessful(string paymentId, string token, string PayerID)
{
    // Capture Payment
    var capture = PayPalPaymentService.CapturePayment(paymentId);

    return View();
}

• AuthorizePayment 是触发付款的操作。它与之前的“CreatePayment”函数非常相似，但在本例中我们将“authorize”作为意图参数传递。
• AuthorizeSuccessful 是在成功批准 PayPal 付款后将重定向您的客户的操作。此时，我正在捕获付款，但您可以将 paymentId 保存在数据库中，并在需要时捕获付款。

在这些代码示例中，为了简单起见，我对付款变量值进行了硬编码。在您的实际应用程序中，您可能会将它们包装在将所有这些值作为变量的方法中，以便可以动态设置和重用所有内容。

订阅

这在 PayPal 中称为“结算计划” - 您可以创建定期付款计划，并通过创建结算协议为您的客户订阅结算计划。使用 PayPal REST API，您可以创建、更新或删除结算计划；如果您想构建一个管理面板来管理您的企业的这些事情，您可能会使用这个东西。

向客户创建经常性费用的步骤如下：

1. 创建结算计划并激活它。创建结算计划后，它会处于“已创建”状态。它需要通过发出 PATCH 请求来激活。
2. 创建结算协议并执行：对“创建结算协议”调用的响应包括指向approval_url和execute_url的链接。我们需要获得计费协议的批准，然后执行计费协议。

计费计划

创建结算计划

创建定义计费周期的计费计划。这是我们创建计划时需要传递的参数的摘要。

• 名称：计费计划的名称。
• 说明：计费计划的说明。
• 类型：对于固定次数的定期付款，允许的值为“FIXED”；对于手动取消之前重复的计划，允许的值为“INFINITE”。
• 商户首选项：这是一个指定首选项的对象，例如设置费用、付款的最大失败尝试次数、返回 URL、取消 URL、通知 URL，PayPal 在付款后将在其中重定向用户。
• 付款定义：此计划的付款定义数组。通常，该数组将具有一两个付款定义。如果我们想提供免费试用或折扣价格试用，那么我们会设置两种付款定义。第一个定义是试用期，第二个定义是定期付款。付款定义的属性包括名称、类型（试用或常规）、频率（日、周、月、年）、 >频率间隔（如果我们将频率设置为“周”并将频率间隔设置为“1”，则我们定义每周付款）、向客户收费的金额，以及cycles 是总付款次数。 收费模式用于指定计划金额之外的运费和税费。

这是一个代码片段，展示了如何创建计费计划：

// Define the plan and attach the payment definitions and merchant preferences.
// More Information: https://developer.paypal.com/webapps/developer/docs/api/#create-a-plan
var billingPlan = new Plan
{
    name = "Tuts+ Plus",
    description = "Monthly plan for courses.",
    type = "fixed",
    // Define the merchant preferences.
    // More Information: https://developer.paypal.com/webapps/developer/docs/api/#merchantpreferences-object
    merchant_preferences = new MerchantPreferences()
    {
        setup_fee = GetCurrency("0"), // $0
        return_url = "returnURL", // Retrieve from config
        cancel_url = "cancelURL", // Retrieve from config
        auto_bill_amount = "YES",
        initial_fail_amount_action = "CONTINUE",
        max_fail_attempts = "0"
    },
    payment_definitions = new List<PaymentDefinition>
    {
        // Define a trial plan that will only charge $9.99 for the first
        // month. After that, the standard plan will take over for the
        // remaining 11 months of the year.
        new PaymentDefinition()
        {
            name = "Trial Plan",
            type = "TRIAL",
            frequency = "MONTH",
            frequency_interval = "1",
            amount = GetCurrency("0"), // Free for the 1st month
            cycles = "1",
            charge_models = new List<ChargeModel>
            {
                new ChargeModel()
                {
                    type = "TAX",
                    amount = GetCurrency("1.65") // If we need to charge Tax
                },
                new ChargeModel()
                {
                    type = "SHIPPING",
                    amount = GetCurrency("9.99") // If we need to charge for Shipping
                }
            }
        },
        // Define the standard payment plan. It will represent a monthly
        // plan for $19.99 USD that charges once month for 11 months.
        new PaymentDefinition
        {
            name = "Standard Plan",
            type = "REGULAR",
            frequency = "MONTH",
            frequency_interval = "1",
            amount = GetCurrency("15.00"),
            // > NOTE: For `IFNINITE` type plans, `cycles` should be 0 for a `REGULAR` `PaymentDefinition` object.
            cycles = "11",
            charge_models = new List<ChargeModel>
            {
                new ChargeModel
                {
                    type = "TAX",
                    amount = GetCurrency("2.47")
                },
                new ChargeModel()
                {
                    type = "SHIPPING",
                    amount = GetCurrency("9.99")
                }
            }
        }
    }
};

// Get PayPal Config
var apiContext = PayPalConfiguration.GetAPIContext();

// Create Plan
plan.Create(apiContext);

新创建的结算计划处于 CREATED 状态。将其激活为“活动”状态，以便您的客户可以订阅该计划。要激活该计划，我们需要发出 PATCH 请求：

// Activate the plan
var patchRequest = new PatchRequest()
{
    new Patch()
    {
        op = "replace",
        path = "/",
        value = new Plan() { state = "ACTIVE" }
    }
};
plan.Update(apiContext, patchRequest);

如您所见，PayPal 库是其 REST API 的直接包装器，这很好，但与 Stripe 等其他 API 相比，该 API 也非常复杂。因此，将所有 PayPal 通信包装在对象中，为我们的应用程序提供更清晰、更简单的 API，这确实是一个不错的选择。在这里您可以看到封装在多个带有参数的函数中的代码的样子：

public static Plan CreatePlanObject(string planName, string planDescription, string returnUrl, string cancelUrl,
    string frequency, int frequencyInterval, decimal planPrice,
    decimal shippingAmount = 0, decimal taxPercentage = 0, bool trial = false, int trialLength = 0, decimal trialPrice = 0)
{
    // Define the plan and attach the payment definitions and merchant preferences.
    // More Information: https://developer.paypal.com/docs/rest/api/payments.billing-plans/
    return new Plan
    {
        name = planName,
        description = planDescription,
        type = PlanType.Fixed,

        // Define the merchant preferences.
        // More Information: https://developer.paypal.com/webapps/developer/docs/api/#merchantpreferences-object
        merchant_preferences = new MerchantPreferences()
        {
            setup_fee = GetCurrency("1"),
            return_url = returnUrl,
            cancel_url = cancelUrl,
            auto_bill_amount = "YES",
            initial_fail_amount_action = "CONTINUE",
            max_fail_attempts = "0"
        },
        payment_definitions = GetPaymentDefinitions(trial, trialLength, trialPrice, frequency, frequencyInterval, planPrice, shippingAmount, taxPercentage)
    };
}

private static List<PaymentDefinition> GetPaymentDefinitions(bool trial, int trialLength, decimal trialPrice,
    string frequency, int frequencyInterval, decimal planPrice, decimal shippingAmount, decimal taxPercentage)
{
    var paymentDefinitions = new List<PaymentDefinition>();

    if (trial)
    {
        // Define a trial plan that will charge 'trialPrice' for 'trialLength'
        // After that, the standard plan will take over.
        paymentDefinitions.Add(
            new PaymentDefinition()
            {
                name = "Trial",
                type = "TRIAL",
                frequency = frequency,
                frequency_interval = frequencyInterval.ToString(),
                amount = GetCurrency(trialPrice.ToString()),
                cycles = trialLength.ToString(),
                charge_models = GetChargeModels(trialPrice, shippingAmount, taxPercentage)
            });
    }

    // Define the standard payment plan. It will represent a 'frequency' (monthly, etc)
    // plan for 'planPrice' that charges 'planPrice' (once a month) for #cycles.
    var regularPayment = new PaymentDefinition
    {
        name = "Standard Plan",
        type = "REGULAR",
        frequency = frequency,
        frequency_interval = frequencyInterval.ToString(),
        amount = GetCurrency(planPrice.ToString()),
        // > NOTE: For `IFNINITE` type plans, `cycles` should be 0 for a `REGULAR` `PaymentDefinition` object.
        cycles = "11",
        charge_models = GetChargeModels(trialPrice, shippingAmount, taxPercentage)
    };
    paymentDefinitions.Add(regularPayment);

    return paymentDefinitions;
}

private static List<ChargeModel> GetChargeModels(decimal planPrice, decimal shippingAmount, decimal taxPercentage)
{
    // Create the Billing Plan
    var chargeModels = new List<ChargeModel>();
    if (shippingAmount > 0)
    {
        chargeModels.Add(new ChargeModel()
        {
            type = "SHIPPING",
            amount = GetCurrency(shippingAmount.ToString())
        });
    }
    if (taxPercentage > 0)
    {
        chargeModels.Add(new ChargeModel()
        {
            type = "TAX",
            amount = GetCurrency(String.Format("{0:f2}", planPrice * taxPercentage / 100))
        });
    }

    return chargeModels;
}

更新结算计划

您可以通过提出“PATCH”请求来更新现有结算方案的信息。这是一个包装该调用的函数：

public static void UpdateBillingPlan(string planId, string path, object value)
{
    // PayPal Authentication tokens
    var apiContext = PayPalConfiguration.GetAPIContext();

    // Retrieve Plan
    var plan = Plan.Get(apiContext, planId);

    // Activate the plan
    var patchRequest = new PatchRequest()
    {
        new Patch()
        {
            op = "replace",
            path = path,
            value = value
        }
    };
    plan.Update(apiContext, patchRequest);
}

要更新计费计划描述，我们可以调用此函数并传递正确的参数：

UpdateBillingPlan(
    planId: "P-5FY40070P6526045UHFWUVEI", 
    path: "/", 
    value: new Plan { description = "new description" });

删除结算计划

理想情况下，当您不想接受新客户加入结算计划时，您需要将其更新为“非活动”状态。这不会影响该计划的现有计费协议。只需调用 UpdateBillingPlan 函数即可完成此操作：

UpdateBillingPlan(
    planId: "P-5FY40070P6526045UHFWUVEI",
    path: "/",
    value: new Plan { state = "INACTIVE" });

计费协议

创建计费协议

创建一个或多个结算计划后，您希望开始让客户注册您的订阅计划。为此，您需要收集客户详细信息并向 PayPal 提出请求。为了能够测试此功能，我向 HomeController 添加了几个操作：

public IActionResult Subscribe()
{
    var plan = PayPalSubscriptionsService.CreateBillingPlan("Tuts+ Plan", "Test plan for this article", GetBaseUrl());

    var subscription = PayPalSubscriptionsService.CreateBillingAgreement(plan.id, 
        new PayPal.Api.ShippingAddress
        {
            city = "London", 
            line1 = "line 1",
            postal_code = "SW1A 1AA",
            country_code = "GB"
        }, "Pedro Alonso", "Tuts+", DateTime.Now);
    
    return Redirect(subscription.GetApprovalUrl());
}

public IActionResult SubscribeSuccess(string token)
{
    // Execute approved agreement
    PayPalSubscriptionsService.ExecuteBillingAgreement(token);

    return View();
}

public IActionResult SubscribeCancel(string token)
{
    // TODO: Handle cancelled payment
    return RedirectToAction("Error");
}

• 订阅：这是调用的第一个操作。它正在创建一个测试结算计划，然后创建该计划的结算协议（订阅），并将用户重定向到 PayPal 以确认付款。
• 订阅成功：此操作是成功订阅后用作“返回 URL”的操作。协议令牌标识符在查询字符串中传递，我们使用此令牌来执行计费协议并使其处于活动状态。
• SubscribeCancel： 此操作用作“取消 URL”。如果由于某种原因付款失败，或者您的客户取消了 PayPal 付款，用户将采取此操作，您需要处理此问题。也许可以提供重试的选项。

正如您在前面的代码片段中看到的，我已将大部分功能包装在几个方法中。第一个是上一节中解释的“CreateBillingPlan”。第二个是“CreateBillingAgreement”，用于为用户订阅计划：

public static Agreement CreateBillingAgreement(string planId, ShippingAddress shippingAddress, 
    string name, string description, DateTime startDate)
{
    // PayPal Authentication tokens
    var apiContext = PayPalConfiguration.GetAPIContext();

    var agreement = new Agreement()
    {
        name = name,
        description = description,
        start_date = startDate.ToString("yyyy-MM-ddTHH:mm:ss") + "Z",
        payer = new Payer() { payment_method = "paypal" },
        plan = new Plan() { id = planId },
        shipping_address = shippingAddress
    };
    
    var createdAgreement = agreement.Create(apiContext);
    return createdAgreement;
}

第三种方法是“ExecuteBillingAgreement”。成功订阅批准后，我们​​使用返回的令牌来激活订阅：

public static void ExecuteBillingAgreement(string token)
{
    // PayPal Authentication tokens
    var apiContext = PayPalConfiguration.GetAPIContext();

    var agreement = new Agreement() { token = token };
    var executedAgreement = agreement.Execute(apiContext);
}

暂停计费协议

使用此方法暂停协议：

public static void SuspendBillingAgreement(string agreementId)
{
    var apiContext = PayPalConfiguration.GetAPIContext();

    var agreement = new Agreement() { id = agreementId };
    agreement.Suspend(apiContext, new AgreementStateDescriptor()
        { note = "Suspending the agreement" });
}

重新激活计费协议

这个与上一个非常相似：

public static void ReactivateBillingAgreement(string agreementId)
{
    var apiContext = PayPalConfiguration.GetAPIContext();

    var agreement = new Agreement() { id = agreementId };
    agreement.ReActivate(apiContext, new AgreementStateDescriptor()
        { note = "Reactivating the agreement" });
}

取消计费协议

使用此功能取消计划：

public static void CancelBillingAgreement(string agreementId)
{
    var apiContext = PayPalConfiguration.GetAPIContext();

    var agreement = new Agreement() { id = agreementId };
    agreement.Cancel(apiContext, new AgreementStateDescriptor()
        { note = "Cancelling the agreement" });
}

更新计费协议

这个选项非常有限，我希望从这次通话中可以更改订阅计划，以升级或降级客户。与 Stripe 不同，单次调用不支持此功能。您需要通过取消当前协议并创建新的升级或降级协议来处理这种情况。这并不理想，但将来可能会改变。

结论

这是人们用来与 PayPal 集成的最常用功能的概述。他们的 API 比本文中解释的集成方法要大得多 - 您还可以发放退款和部分退款，并且他们针对本文涵盖的示例中的边缘情况提供了许多不同的选项。如果您有兴趣获得有关任何特定集成的更多详细信息，请在评论中留下建议。

위 내용은 심층 분석: PayPal 통합 파트 2: PayPal REST API의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!