README

ApcoPay PHP 库提供了使用 ApcoPay 网关处理金融交易的功能。

要求

需要 PHP 扩展 cURL。
需要 ApcoPay 的商户账户。请发送电子邮件至 hello@apcopay.eu 以设置商户账户。

安装

建议的安装方法是使用 Packagist 和 Composer。运行以下命令安装包并将其添加到项目的 composer.json 作为需求：

composer require apcopay/apcopay_php

或者，也可以通过复制此存储库中的内容到项目文件夹，并使用 PHP require 在文件上使用 ApcoPay PHP 库，如下所示下面。

描述

ApcoPay PHP 库

文件加载

可以使用以下选项加载 ApcoPay PHP 库文件

Composer 自动加载

有关 composer 自动加载的更多信息，请访问 https://getcomposer.org.cn/doc/01-basic-usage.md#autoloading

如果您已经设置了 composer 自动加载，请跳过此步骤

require __DIR__ . '/vendor/autoload.php';

PHP require

require __DIR__ . '/apcopay_php/src/ApcoPayGateway.php';
require __DIR__ . '/apcopay_php/src/Configuration.php';
require __DIR__ . '/apcopay_php/src/TransactionType.php';
require __DIR__ . '/apcopay_php/src/TransactionRequest.php';
require __DIR__ . '/apcopay_php/src/TransactionResponse.php';
require __DIR__ . '/apcopay_php/src/NotificationRequest.php';
require __DIR__ . '/apcopay_php/src/RedirectRequest.php';

初始化

ApcoPayGateway 配置需要以下 5 个参数

商户 ID - 在 ApcoPay 中的商户 ID/代码
商户密码 - 在 ApcoPay 中的商户密码
哈希密钥 - ApcoPay 中的哈希密钥词
通知 URL - 将交易状态通知发送到的 URL。应按以下通知请求示例进行处理。
重定向 URL - 用户在 3DS 支付后将被重定向到的 URL。应按以下重定向请求示例进行处理。

初始化 ApcoPayGateway 示例

$gateway = new ApcoPay\ApcoPayGateway(
    new ApcoPay\Configuration(
        "1234",
        "dfnu2345b2354vbu",
        "3ui423ui4",
        "https://merchanturl.com/apcopay/notification",
        "https://merchanturl.com/apcopay/redirect"
    )
);

处理交易

TransactionRequest

金额
currency_code - ISO 4217 数字代码
transaction_type - 由 TransactionType 类定义的数字代码
order_reference - 商户订单参考。不得包含 ||
卡号
卡 CVV
持卡人姓名
卡到期月份
卡到期年份
用户 IP
original_transaction_id - 之前交易的 ID
user_defined_function - 不得包含 ||

TransactionRequest 必需字段

TransactionResponse

result - 表示交易状态的交易结果
psp_id - ApcoPay 网关交易的 ID
bank_transaction_id - 银行交易的 ID
date - 交易日期。格式：yyyyMMdd
time - 交易时间。格式：HHmmss
acquirer_reference
授权码
地址验证响应
acquirer_code - 处理银行代码
用户 IP
user_defined_function
额外数据
card_country - 发卡国家

结果代码

接受的交易可能有以下结果之一

批准
已捕获
已作废
已注册（仅当卡为3Dsecure注册且需要与Visa/MasterCard进行验证时使用）

拒绝的交易结果在不同银行之间会有所不同

处理交易示例

$transactionRequest = new ApcoPay\TransactionRequest();
$transactionRequest->amount = "2.40";
$transactionRequest->currency_code = "978";
$transactionRequest->order_reference = "1234";
$transactionRequest->transaction_type = ApcoPay\TransactionType::Purchase;

$transactionRequest->card_number = "4444444444444444";
$transactionRequest->card_cvv = "123";
$transactionRequest->card_holder = "John Doe";
$transactionRequest->card_expiry_month = "12";
$transactionRequest->card_expiry_year = "2023";

$transactionResponse = $gateway->processTransaction($transactionRequest);

if ($transactionResponse->result === "CAPTURED" || $transactionResponse->result === "APPROVED" || $transactionResponse->result === "VOIDED") {
    // Transaction successful
} else if ($transactionResponse->result == 'ENROLLED') {
    $redirectUrl = "https://www.apsp.biz/pay/3DSFP2/verify.aspx?id=" . $transactionResponse->psp_id;
    // Redirect to $redirectUrl
} else {
    // Transaction failed
}

通知请求

注意：通知响应应始终返回HTTP状态码200，内容为“OK”

通知请求示例

$request = $_POST["params"];
$request = urldecode($request);
if (!$gateway->verify($request)) {
    die("Hash mismatch");
    return;
}
$notificationRequest = $gateway->parseNotification($request);
if ($notificationRequest->result === "OK") {
    // TODO: update order to successful
} else {
    // TODO: update order to declined
}
echo 'OK';
header("HTTP/1.1 200 OK");

重定向请求

重定向请求示例

$request = $_GET["params"];
$request = str_replace("\\\"", "\"", $request);
if (!$gateway->verify($request)) {
    die("Hash mismatch");
    return;
}
$redirectRequest = $gateway->parseRedirect($request);
if ($redirectRequest->result === "OK") {
    echo '<div>Transaction successful</div>';
    echo '<div>Order reference: ' . $redirectRequest->order_reference . '</div>';
} else {
    echo '<div>Transaction failed</div>';
    echo '<div>Order reference: ' . $redirectRequest->order_reference . '</div>';
    echo '<div>Result: ' . $redirectRequest->result . '</div>';
}

处理流程

正常交易流程

3DS交易流程

Apco Pay网络服务将验证提交的卡是否已注册3Dsecure
1. 如果卡未注册3ds，网络服务将返回前述章节中描述的普通响应
2. 如果卡已注册，客户端需要重定向到验证页面 https://www.apsp.biz/pay/3DSFP2/verify.aspx?id=4a502205024f474a8aa1933ceac42e56 其中Id需要替换为第一次响应返回的值
客户端必须继续验证并提交他的PIN
验证成功后，客户端将被重定向到配置中的redirection_url

参考交易流程

交易类型

交易类型详情

授权

授权 - 授权是两步过程中的第一步

如果批准，请求的金额将从提交的卡的信用额度中预留。因此，如果稍后完成捕获，将使用预留过程。

重要：授权（预留）期约为信用卡7天，借记卡3天（我们建议您与使用的银行确认）。一旦预留期过期，就不再可能捕获此交易。

捕获

捕获是上述两步过程中的第二步。捕获交易必须在“授权”交易之前进行。

要捕获的金额必须小于或等于授权金额。这也意味着可以捕获部分金额。

在捕获过程中，从客户账户扣除金额并记入商户账户。

购买

购买是在单步中完成的支付交易。

购买交易同时处理授权和捕获。

如果批准，请求的金额将从客户账户扣除并记入商户账户。

部分退款

退款是将付款退还给客户的交易。退还的金额可以是支付金额的一部分或全部。退款可以与现有的捕获或购买相关。在信用卡支付的情况下，退款将记入客户的信用卡账户。

重要：不允许游戏商户进行退款。

原始信用

原始信用用于支付比原始交易金额更大的金额。

作废购买、作废信用、作废捕获和作废授权

如果作废请求在原始交易日期的23:59（银行时区）之前执行 - 收单行将能够取消此交易。

测试

许可证

ApcoPay PHP库是开源软件，根据MIT许可证授权。

apcopay / apcopay_php

维护者

详细信息