philipbrown / worldpay
WorldPay.com的PHP包装器
Requires
- php: >=5.4
- beberlei/assert: ~2.0
- symfony/http-foundation: ~2.0
Requires (Dev)
- phpunit/phpunit: ~4.0
README
PHP 5.4+版的WorldPay支付网关的包装器。
WorldPay是一个易于使用且广为人知且值得信赖的支付网关。然而,关于该服务的几乎所有内容都已过时。使用WorldPay最令人沮丧的事情之一是缺乏良好的文档或官方库。结果是,WorldPay的文档是支离破碎或残缺不全,代码示例完全不足。
WorldPay似乎也使一切比必要的更加复杂。
我决定制作这个软件包,以抽象掉许多这些复杂性,并提供一个清晰且易于使用的API,用于创建WorldPay请求并监听响应。此软件包还将经过良好的单元测试,并通过PHP Composer作为无框架的软件包提供。
注意:如果您打算将多个支付网关集成到您的应用程序中,并且您不会使用WorldPay的所有功能(例如FuturePay或自定义参数),您可能应该使用Omnipay。
安装
将philipbrown/worldpay
添加到composer.json
中的依赖项。
{ "require": { "philipbrown/worldpay": "~3.0" } }
使用composer update
更新您的软件包。
WorldPay是如何工作的?
使用WorldPay网关创建新的支付基本上遵循以下三个步骤
- 您创建一个包含交易信息的请求。这可以是从交易的基本细节到您客户的完整资料。
- 客户将被重定向到WorldPay的安全服务器以输入他们的支付信息。永远不会在您的服务器上存储客户信息。
- 然后,WorldPay会发送一个可选的响应回您的服务器作为回调。您可以使用此回调来更新数据库或设置在交易完成后需要运行的任何流程。
此WorldPay软件包允许您轻松创建新的请求并捕获相应的响应
WorldPay环境、路由和回调
默认情况下,WorldPay有开发
和生产
环境。这允许您使用开发
环境测试您的应用程序,而无需处理真实支付。
然而,通常情况下,您可能需要除了开发
和生产
之外的多达多个环境。
例如,您可能希望有一个本地
环境或一个测试
环境,这些环境实际上不会击中WorldPay服务器。
如果您在生产
环境中发送WorldPay请求,您的请求体必须包含一个testMode
参数的值为0
。在所有其他环境中,此参数必须设置为100
。
要设置您的环境
use PhilipBrown\WorldPay\Environment; $env = Environment::set('production'); $env->asInt(); // 0 $env = Environment::set('development'); $env->asInt(); // 100 $env = Environment::set('local'); $env->asInt(); // 100
您必须通过创建一个新的路由并将其传递给请求来指定请求发送的位置。
安装和购物车ID
在您的WorldPay账户中创建一个新的安装时,它将自动分配一个instId
。在向WorldPay发送请求时,您需要提供此ID。
WorldPay还允许您设置一个将附加到请求的cartId
。这将使确定交易来源变得更加容易。
货币
当您向WorldPay发送请求时,您需要包含表示交易的货币的字符串表示形式。这些货币的列表可以在/src/currencies.php
下找到。
设置货币
use PhilipBrown\WorldPay\Currency; $currency = Currency::set('GBP');
交易值
请求应包含交易的总金额作为单个金额。这应设置为字符串值。
交易密钥
为了防止对交易请求进行未授权的篡改,WorldPay允许您设置一个密钥。然后,该密钥将用于您必须发送给WorldPay的每个请求的交易签名的哈希中。
要设置密钥,请进入您的WorldPay账户,并从菜单中选择安装。
接下来,选择您的安装并填写标记为交易MD5密钥的字段。
回调密码
交易完成后,WorldPay(可选)将向您的服务器发送回调请求。这允许您运行任何可能的交易后过程。
为了验证此请求,WorldPay将在请求正文中包含一个回调密码。您可以通过您的商户账户中的安装仪表板设置此密码。
创建请求
要向WorldPay发送请求,请创建一个新的PhilipBrown\WorldPay\Request
实例
$request = new Request( Environment::set('testing'), // Environment '123', // InstId 'My shop', // CartId 'my secret', // Secret '10.00', // Value Currency::set('GBP'), // Currency http://shop.test/callbacks/worldpay', // Route ['name' => 'Philip Brown'] // Data );
设置签名字段
默认情况下,您将需要包括instId
、cartId
、currency
、amount
字段在您的交易签名哈希中。
您可以通过将字段名称数组传递给setSignatureFields()
方法向签名添加额外的字段
$request->setSignatureFields(['name']);
向WorldPay发送请求
您有两种方式可以向WorldPay发送请求。
首先,一旦创建了Request
对象,您可以将客户自动重定向到WorldPay
$request->send();
这将返回一个Symfony\Component\HttpFoundation\RedirectResponse
实例。
其次,您可以将请求准备好,以便在将客户重定向到WorldPay之前显示一个确认页面。此确认页面必须包含一个隐藏表单和一个提交按钮,该按钮将客户带到WorldPay
$body = $request->prepare();
这将返回一个PhilipBrown\WorldPay\Body
实例,这是一个不可变对象。
现在,您可以创建如下所示的确认页面
<h1>Confirm your purchase</h1> <p>Thank you {{ $customer->first_name }} for choosing to buy with us.</p> <p>To confirm your purchase click the button below.</p> <p>You will be taken to WorldPay's secure server where you can complete your transaction.</p> <form action="{{ $body->route }}" method="POST"> @foreach ($body->data as $key => $value) <input type="hidden" name="{{ $key }}" value="{{ $value }}"> @endforeach <input type="hidden" name="signature" value="{{ $body->signature }}"> <input type="submit" value="Complete your purchase!"> </form>
接受响应
WorldPay可以在每次发生交易时可选地向您发送支付响应。此支付响应作为对您的服务器端点的POST
请求发送。
WorldPay会将回调密码包含在响应体中,以便您验证请求确实来自WorldPay。
要创建一个新的响应,实例化一个新的Response
对象,并将其回调密码和POST
请求的正文传递给它
use PhilipBrown\WorldPay\Response; $response = new Response('qwerty', $_POST);
Response
是一个不可变对象,它为您提供了访问POST
请求正文的方式
echo $response->name; // 'Philip Brown'
Response
对象还包含一些辅助方法
// Asserts the response is from WorldPay $response->isValid(); // Asserts the transaction was successful $response->isSuccess(); // Asserts the transaction was cancelled $response->isCancelled(); // Asserts the transaction was in the production environment $response->isProduction(); // Asserts the transaction was in the development environment $response->isDevelopment();
所有上述方法都返回一个bool
响应。