应用场景
境外信用卡支付：visa、master
须知与准备
支持EWAY的主要地区(本文以澳大利亚为主要应用地区)
- 澳大利亚：https://www.eway.com.au
- 香港：https://eway.io/hk
- 澳门：https://eway.io/mo
- 新西兰：https://eway.io/nz
- 新加坡：https://eway.io/sg
开发者文档：https://eway.io/api-v3
沙箱(sandbox)环境管理后台登录入口：
https://sandbox.myeway.com.au/Login.aspx
生产(production)环境管理后台登录入口：
https://www.eway.com.au
温馨提示:
当你注册好账号后，沙箱环境的帐号也同时注册了，例如你注册的邮箱为：
xxx@gmail.com
对应的沙箱帐号为：
xxx@gmail.com.sand
PHP下载eway SDK（本文使用的SDK版本：1.3）
$ composer require eway/eway-rapid-php
下文所有接口都需要实例化一个$client对象，参数用到 apiKey, apiPassword, apiEndpoint，其中apiKey, apiPassword在管理后台可找到。
eway.jpg
Client实例化代码
<?php
$apiKey = '60CF3Ce97nRS1Z1Wp5m9kMmzHHEh8Rkuj31QCtVxjPWGYA9FymyqsK0Enm1P6mHJf0THbR';
$apiPassword = 'API-P4ss';
$apiEndpoint = \Eway\Rapid\Client::MODE_SANDBOX; // Use \Eway\Rapid\Client::MODE_PRODUCTION when you go live
$client = \Eway\Rapid::createClient($apiKey, $apiPassword, $apiEndpoint);
由于篇幅限制，下文涉及到接口(请求|响应)参数的说明，只列出必填项，其他非必填项可参考官方文档
接入支付功能
文档上介绍了很多种方法支付方式，本文先挑选一种最常、最易上手的支付方式进行介绍
Transparent Redirect：这种方式可以给用户提供便捷安全的支付环境，主要由前端通过官方js-sdk将银行卡数据传输给eway发起支付，接入难度低。
- Step 1: 新建一个
access code
通过持卡人信息和交易信息生成 access code，最主要的参数是交易信息，持卡人信息可选。
请求参数说明
| 参数名 | 是否必填 | 最大长度 | 数据类型 | 描述 |
|---|---|---|---|---|
| RedirectUrl | 必填 | 512 | string | 支付成功后触发的重定向地址 |
| Payment | 必填 | - | Object | 交易信息，数据结构见下表 |
Payment对象说明
| 参数名 | 是否必填 | 最大长度 | 数据类型 | 描述 |
|---|---|---|---|---|
| TotalAmount | 必填 | 10 | int | 交易总金额，以最小货币单位为单位，例如 价值$27的商品，TotalAmount为2700 |
最基础的请求示例
<?php
$client = \Eway\Rapid::createClient($apiKey, $apiPassword, $apiEndpoint);
$transaction = [
'Payment' => [
'TotalAmount' => 1000, //以分为单位，这里是10澳币
],
'RedirectUrl' => 'http://www.eway.com.au', //根据实际情况替换为自己的重定向地址
'TransactionType' => \Eway\Rapid\Enum\TransactionType::PURCHASE,
];
$response = $client->createTransaction(\Eway\Rapid\Enum\ApiMethod::TRANSPARENT_REDIRECT, $transaction);
响应示例
<?php
// See the JSON tab for all the available $response properties
if (!$response->getErrors()) {
$accessCode = $response->AccessCode;
$formUrl = $response->FormActionURL;
} else {
foreach ($response->getErrors() as $error) {
echo "Error: ".\Eway\Rapid::getMessage($error)."<br>";
}
}
响应参数说明
| 参数名 | 最大长度 | 数据类型 | 描述 |
|---|---|---|---|
| AccessCode | 512 | string | 交易订单的唯一标识符 |
| FormActionURL | 512 | string | Step 2作为参数传给EWAY |
| ... | ... | ... | ... |
接口调起后，会拿到EWAY返回的Access Code，此字段贯穿整个交易流程，是交易订单的唯一标识符，在后续的接口中都会用上。其次还有 FormActionURL 字段也是作为Step 2中的必填参数
- Step 2: 前端提交用户银行卡信息到EWAY
后端把 access code传给前端，由前端汇集所有参数通过eway js-sdk传给eway进行支付扣费
请求参数说明
| 参数名 | 是否必填 | 描述 |
|---|---|---|
| EWAY_ACCESSCODE | 必填 | Step 1返回的access code
|
| EWAY_PAYMENTTYPE | 必填 | 支付方式，枚举值：Credit Card, PayPal, MasterPass, VisaCheckout
|
| EWAY_CARDNAME | 必填 | 持卡人姓名 |
| EWAY_CARDNUMBER | 必填 | 银行卡号码 |
| EWAY_CARDEXPIRYMONTH | 必填 | 信用卡过期月份 |
| EWAY_CARDEXPIRYYEAR | 必填 | 信用卡过期年份 |
| EWAY_CARDCVN | 必填 | 信用卡安全码 |
前端HTML示例
<form method="POST" action="<<FormActionURL Goes Here>>" id="payment_form">
<input type="hidden" name="EWAY_ACCESSCODE" value="<<AccessCode Goes Here>>" />
<input type="hidden" name="EWAY_PAYMENTTYPE" value="Credit Card" />
Card Name: <input type="text" name="EWAY_CARDNAME" />
Card Number: <input type="text" name="EWAY_CARDNUMBER" />
Card Expiry Month: <input type="text" name="EWAY_CARDEXPIRYMONTH" />
Card Expiry Year: <input type="text" name="EWAY_CARDEXPIRYYEAR" />
Card Start Date: <input type="text" name="EWAY_CARDSTARTMONTH" />
Card Start Year: <input type="text" name="EWAY_CARDSTARTYEAR" />
Card Issue Number: <input type="text" name="EWAY_CARDISSUENUMBER" />
Card CVN: <input type="text" name="EWAY_CARDCVN" />
<input type="submit" value="Process" text="Process" />
</form>
Card Start Year非必填
Card Start Month非必填
Card Issue Number非必填
根据自己的UI风格可以把这个Form表单调整一下嵌入自己的页面上。
前端javascript 示例代码
<script type="text/javascript" src="https://api.ewaypayments.com/JSONP/v3/js"></script>
<script type="text/javascript">
// Add the submit handler
var form = document.getElementById("payment_form");
if (form.addEventListener) {
//Modern browsers
form.addEventListener("submit", ewayAjax, false);
} else if (form.attachEvent) {
//Old IE
form.attachEvent('onsubmit', ewayAjax);
}
function ewayAjax(e) {
// call eWAY to process the request
eWAY.process(
document.getElementById("payment_form"),
{
autoRedirect: false,
onComplete: function (data) {
// this is a callback to hook into when the requests completes
alert('The JSONP request has completed.');
if (data.Is3DSecure) {
//支付成功
window.location.replace(data.RedirectUrl);
}
},
onError: function (e) {
// this is a callback you can hook into when an error occurs
alert('There was an error processing the request');
},
onTimeout: function (e) {
// this is a callback you can hook into when the request times out
alert('The request has timed out.');
}
}
);
// Stop the form from submitting
e.preventDefault();
}
</script>
- Step 3: 查询支付结果
请求参数说明
| 参数名 | 是否必填 | 最大长度 | 数据类型 | 描述 |
|---|---|---|---|---|
| AccessCode | 必填 | 512 | string | 订单唯一标识符 |
请求示例
<?php
$client = \Eway\Rapid::createClient($apiKey, $apiPassword, $apiEndpoint);
$response = $client->queryTransaction('A10012yIV2-MEEfkk7b7oYZqtulwNHv2dAFLv7T2guZEpjwBMHJoU-KxQihXVV10unFYbOUJ9Ob58oALLxn88_rzWDJhyq1-qW_hZ-xYjS3kdsCSNLtFHVESfDRVPWZqisLto');
响应示例
<?php
// See the JSON tab for all the available properties
$transactionResponse = $response->Transactions[0];
if ($transactionResponse->TransactionStatus) {
echo 'Payment successful! ID: '.$transactionResponse->TransactionID;
} else {
$errors = split(', ', $transactionResponse->ResponseMessage);
foreach ($errors as $error) {
echo "Payment failed: ".\Eway\Rapid::getMessage($error)."<br>";
}
}
响应参数说明
| 参数名 | 最大长度 | 数据类型 | 描述 |
|---|---|---|---|
| AccessCode | 512 | string | 交易订单的唯一标识符 |
| TransactionStatus | 16 | boolean | 交易是否成功完成 |
| TransactionID | 8 | int | 交易完成后的交易单号 |
| TotalAmount | 10 | int | 交易金额 |
| Errors | 512 | string | 当发生错误时，返回错误码。详情见Response Code |
| ... | ... | ... | ... |
记得把TransactionID保存好，后续退款逻辑需要用到。
接入退款功能
对应文档：https://eway.io/api-v3/#refunds
请求参数说明
| 参数名 | 是否必填 | 最大长度 | 数据类型 | 描述 |
|---|---|---|---|---|
| Refund | 必填 | - | object | 退款详情信息 |
Refund对象说明
| 参数名 | 是否必填 | 最大长度 | 数据类型 | 描述 |
|---|---|---|---|---|
| TotalAmount | 必填 | 10 | int | 退款金额，不能大于所属订单总金额 |
| TransactionID | 必填 | 8 | string | 交易订单号 |
| ... | ... | ... | ... | ... |
请求示例
<?php
$client = \Eway\Rapid::createClient($apiKey, $apiPassword, $apiEndpoint);
$refund = [
'Refund' => [
'TransactionID' => 11259550,
'TotalAmount' => 100
],
];
$response = $client->refund($refund);
响应示例
<?php
// See the JSON tab for all the available $response properties
if ($response->TransactionStatus) {
echo 'Refund successful! ID: '.$response->TransactionID;
} else {
if ($response->getErrors()) {
foreach ($response->getErrors() as $error) {
echo "Error: ".\Eway\Rapid::getMessage($error)."<br>";
}
} else {
echo 'Sorry, your refund failed';
}
}
响应参数说明
| 参数名 | 最大长度 | 数据类型 | 描述 |
|---|---|---|---|
| AccessCode | 512 | string | 交易订单的唯一标识符 |
| TransactionStatus | 16 | boolean | 退款是否成功完成 |
| TransactionID | 8 | int | 交易单号 |
| TotalAmount | 10 | int | 退款金额 |
| Refund | object | - | 退款对象信息 |
| Errors | 512 | string | 当发生错误时，返回错误码。详情见Response Code |
| ... | ... | ... | ... |
Refund对象说明
| 参数名必填 | 最大长度 | 数据类型 | 描述 |
|---|---|---|---|
| TotalAmount | 10 | int | 此次退款金额，不能大于所属订单剩余可退总金额 |
| TransactionID | 8 | string | EWAY退款单号 |
| ... | ... | ... | ... |
网友评论