Alipay Easy SDK

The SDK provides extension methods to handle advanced scenarios without changing the core API structure:

• ISV Proxy Calling: Use .agent("auth_token") to perform calls on behalf of an agent.
• Custom Async Notification: Use .asyncNotify("url") to override the global notifyUrl for a specific request.
• Optional Business Parameters: Use .optional(key, value) or .batchOptional(Map<String, Object>) to set fields within biz_content.

These extension methods can be chained in any order.

// Example of combining extensions
Factory.Payment.FaceToFace()
    .agent("ca34ea491e7146cc87d25fca24c4cD11") // ISV Agent
    .asyncNotify("https://www.test.com/callback") // Specific callback
    .optional("seller_id", "2088102146225135") // Single optional param
    .preCreate("Apple iPhone11", "2234567890", "5799.00");

// Using batchOptional for multiple business parameters
Map<String, Object> optionalArgs = new HashMap<>();
optionalArgs.put("seller_id", "2088102146225135");
optionalArgs.put("discountable_amount", "8.88");

Factory.Payment.FaceToFace()
    .batchOptional(optionalArgs)
    .preCreate("Apple iPhone11", "2234567890", "5799.00");

The following table highlights the differences in developer experience:

// Alipay Easy SDK Example
Factory.Payment.Common().create("Iphone6 16G", "202003019443", "0.10", "2088002656718920");

// Alipay SDK Example (Traditional)
AlipayTradeCreateRequest request = new AlipayTradeCreateRequest();
AlipayTradeCreateModel model = new AlipayTradeCreateModel();
model.setSubject("Iphone6 16G");
model.setOutTradeNo("202003019443");
model.setTotalAmount("0.10");
model.setBuyerId("2088002656718920");
request.setBizModel(model);
alipayClient.execute(request);

Using the SDK involves three main steps: setting global options, making the API call, and handling the response or exceptions.

1. Set Options: Use Factory::setOptions() once globally.
2. API Call: Navigate the capability hierarchy using Factory::capability()->scenario()->method().
3. Handle Response: Use Alipay\EasySDK\Kernel\Util\ResponseChecker to verify if the call was successful.

<?php

require 'vendor/autoload.php';
use Alipay\EasySDK\Kernel\Factory;
use Alipay\EasySDK\Kernel\Util\ResponseChecker;
use Alipay\EasySDK\Kernel\Config;

// 1. Set global options
Factory::setOptions(getOptions());

try {
    // 2. Make API call (e.g., Unified Order Creation)
    $result = Factory::payment()->common()->create("iPhone6 16G", "20200326235526001", "88.88", "2088002656718920");
    
    $responseChecker = new ResponseChecker();
    
    // 3. Handle response
    if ($responseChecker->success($result)) {
        echo "Success";
    } else {
        echo "Failed: " . $result->msg . " " . $result->subMsg;
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

function getOptions() {
    $options = new Config();
    $options->protocol = 'https';
    $options->gatewayHost = 'openapi.alipay.com';
    $options->signType = 'RSA2';
    $options->appId = 'YOUR_APP_ID';
    $options->merchantPrivateKey = 'YOUR_PRIVATE_KEY';
    $options->alipayCertPath = '/path/to/alipayCert.crt';
    $options->alipayRootCertPath = '/path/to/alipayRoot.crt';
    $options->merchantCertPath = '/path/to/appCert.crt';
    return $options;
}

The SDK provides extension methods to modify API requests dynamically before execution.

ISV Proxy Calling (agent)

Use agent($appAuthToken) to perform a call on behalf of an ISV.

Custom Asynchronous Notification (asyncNotify)

Use asyncNotify($url) to set a specific callback URL for a single request. This overrides the global notifyUrl in Config.

Business Parameters (optional and batchOptional)

Use these to set optional fields within the biz_content of an API request:

• optional($key, $value): Sets a single optional parameter.
• batchOptional($array): Sets multiple optional parameters at once using an associative array.

These methods can be chained in any order.

// Example: Combining multiple extensions
Factory::payment()->faceToFace()
    ->agent("ca34ea491e7146cc87d25fca24c4cD11")
    ->asyncNotify("https://www.test.com/callback")
    ->optional("seller_id", "2088102146225135")
    ->batchOptional(["timeout_express" => "10m", "body" => "Iphone6 16G"])
    ->preCreate("Apple iPhone11 128G", "2234567890", "5799.00");

A standard API call follows three steps:

1. Set parameters: Call Factory.SetOptions once globally.
2. Invoke API: Use the Factory pattern to navigate to the desired capability and method.
3. Handle response: Use ResponseChecker.Success(response) to verify if the call succeeded and handle exceptions with a try-catch block.

Example: Creating a Face-to-Face Payment QR code.

using System;
using Alipay.EasySDK.Factory;
using Alipay.EasySDK.Kernel;
using Alipay.EasySDK.Kernel.Util;
using Alipay.EasySDK.Payment.FaceToFace.Models;

// ... inside Main ...
Factory.SetOptions(GetConfig());
try
{
    AlipayTradePrecreateResponse response = Factory.Payment.FaceToFace()
        .PreCreate("Apple iPhone11 128G", "2234567234890", "5799.00");

    if (ResponseChecker.Success(response))
    {
        Console.WriteLine("Success");
    }
    else
    {
        Console.WriteLine($"Failed: {response.Msg}, {response.SubMsg}");
    }
}
catch (Exception ex)
{
    Console.WriteLine($"Exception: {ex.Message}");
}