README

A PHP API wrapper for Zainpay.

要求

Curl（除非使用 Guzzle）
PHP 7.4 或更高版本

安装

通过 Composer 安装

composer require zainpay/sdk:dev-main

通过下载安装

从发布页面下载一个版本。解压缩，然后

 require 'path/to/src/autoload.php';

用法

此 SDK 附带辅助类，可以帮助为您的 SDK 提供全局设置。
此外，还提供了方法，可以帮助在实例化的请求对象中覆盖全局设置。
重写思想的引入是为了在 async 环境中安全使用此 SDK。

示例：全局设置

示例说明如何设置全局令牌和模式，可以在类或系统中使用

    use Zainpay\SDK\Engine;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

示例：覆盖全局设置

示例说明如何覆盖令牌和模式

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\ZainBox;

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

    // Set the mode to development (test server) and provide your public key
    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    // Alternatively, set the mode to production (live server)
    Engine::setMode(Engine::MODE_PRODUCTION);
    Engine::setToken('<PUBLIC_KEY>');

    // Or use the ZainBox class for more flexibility
    ZainBox::instantiate()
        ->withMode(Engine::MODE_PRODUCTION)
        ->withToken('<PUBLIC_KEY>');

注意： Engine 类接受以下参数

模式 - 这些是常量值，如果设置为 Engine::MODE_DEVELOPMENT，将使用 sandbox API，如果设置为 Engine::MODE_PRODUCTION，将使用 production(live) API。
令牌 - 这是您的公钥，可以在您的仪表板上找到。
有关 SDK 提供的服务的更多信息，请参阅文档。

响应方法

Response->hasSucceeded() : 检查请求是否成功
Response->hasFailed() : 检查请求是否失败
Response->getStatus() : 返回响应状态
Response->getCode() : 返回响应代码
Response->getData() : 返回响应数据
Response->getDescription() : 返回响应描述
Response->getResponse() : 返回整个响应
Response->getErrorMessage(): 当响应没有正文时返回错误信息

如何使用响应

以下示例展示了如何使用响应方法访问响应；

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\Card;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = Card::instantiate()->initializeCardPayment(
        '3000',
        'Q6166237864',
        'info@test.com',
        '08000000000',
        'THbfnDvK5o',
        'https://example.net/webhook/zainpay',
    );

    if ($response->hasSucceeded()){
        var_dump($response->getCode());
        var_dump($response->getStatus());
        var_dump($response->getDescription());
        var_dump($response->getData());
    }

    if ($response->hasFailed()){
        var_dump($response->getErrorMessage());
        var_dump($response->getCode());
        var_dump($response->getStatus());
        var_dump($response->getDescription());
        var_dump($response->getData()); //this will return error fields or null if there is no data
    }

响应

    {
        "code": "00",
        "data": "https://dev.zainpay.ng/merchant/redirect-payment?e=V5fvxGjb8wwLvOPZXYyaNMlVZSDrkAdv4ne19X7uiCdqu0kNOOAkMcjbGjApMcivvyLb4vj4azuusyWqC87vtME5n1psVTXai0pIdH61aTdrWJhQFCuYV3a7xJSWiNdDndxh2zNQNl74l2gUpQwhniASWarYUXLl2soyAUAkeAPJ1pUPlTmZddNiYqzgSMhoO1T4OMWk",
        "description": "card processing initialization",
        "status": "200 OK"
    }

使用响应方法访问响应

$response->getStatus() : 200 OK

$response->getCode() : 00

$response->getDescription() : card processing initialization

$response->getData() : https://dev.zainpay.ng/merchant/redirect-payment?e=V5fvxGjb8wwLvOPZXYyaNMlVZSDrkAdv4ne19X7uiCdqu0kNOOAkMcjbGjApMcivvyLb4vj4azuusyWqC87vtME5n1psVTXai0pIdH61aTdrWJhQFCuYV3a7xJSWiNdDndxh2zNQNl74l2gUpQwhniASWarYUXLl2soyAUAkeAPJ1pUPlTmZddNiYqzgSMhoO1T4OMWk

卡

卡支付初始化

此请求允许商家初始化卡支付。

响应中返回的数据字段是一个 URL，您可以将用户重定向到该 URL 进行支付。

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\Card;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = Card::instantiate()->initializeCardPayment(
        '3000',                                 //amount        - required (string)
        'Q6166237864',                          //txnRef        - required (string)
        'info@test.com',                        //payerEmail    - required (string)
        '08000000000',                          //payerMobileNo - required (string)
        'THbfnDvK5o',                           //zainboxCode   - required (string)
        'https://example.net/webhook/zainpay',  //callbackUrl   - required (string)
    );

    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "data": "https://dev.zainpay.ng/merchant/redirect-payment?e=V5fvxGjb8wwLvOPZXYyaNMlVZSDrkAdv4ne19X7uiCdqu0kNOOAkMcjbGjApMcivvyLb4vj4azuusyWqC87vtME5n1psVTXai0pIdH61aTdrWJhQFCuYV3a7xJSWiNdDndxh2zNQNl74l2gUpQwhniASWarYUXLl2soyAUAkeAPJ1pUPlTmZddNiYqzgSMhoO1T4OMWk",
        "description": "card processing initialization",
        "status": "200 OK"
    }

卡支付验证

此请求可用于验证资金存入或卡支付：注意，它仅返回 amountAfterCharges

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\Card;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = Card::instantiate()->verifyCardPayment(
        '51328349733' //txnRef - required (string)
    );

    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "data": {
            "amount": {
                "amount": 100
            },
            "bankName": "",
            "beneficiaryAccountName": "4427505285",
            "beneficiaryAccountNumber": "4427505285",
            "narration": "Approved by Financial Institution",
            "paymentDate": "2022-08-09T15:56:01.686777",
            "paymentRef": "Z9I8XkNRta1hq2dlmMzlhwQ9F60dLw",
            "sender": "Zainpay Card",
            "senderName": "Zainpay Card",
            "txnDate": "2022-08-09T15:56:01.685982",
            "txnRef": "Q6166237864",
            "txnType": "deposit",
            "zainboxCode": "THbfnDvK5o"
        },
        "description": "successful",
        "status": "200 OK"
    }

卡支付验证 V2

此请求可用于验证资金存入或卡支付：注意，这与第一个不同，因为它将允许您查看存入金额、交易费用和 amountAfterCharges

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\Card;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = Card::instantiate()->verifyCardPaymentV2(
        '<Transaction-Reference>' //txnRef - required (string)
    );

    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "data": {
            "depositedAmount": "100000",
            "txnChargesAmount": "6400",
            "amountAfterCharges": "93600",
            "bankName": "ZainMFB",
            "beneficiaryAccountName": "idris",
            "beneficiaryAccountNumber": "7964524199",
            "narration": "gift",
            "paymentDate": "2021-12-28T11:48:35.044886444",
            "paymentRef": "a1oA0ws127quism",
            "sender": "900989098",
            "senderName": "hassan ",
            "txnDate": "2021-12-28T11:48:35.044777507",
            "txnRef": "730003356",
            "txnType": "deposit",
            "zainboxCode": "xmaldoaYnakaAAVOAE",
            "callBackUrl": "http://gofundme.ng/webhook",
            "emailNotification": "user@user.com",
            "zainboxName": "users",
            
        },
        "description": "successful",
        "status": "200 OK"
    }

通过 Zainbox 获取卡交易

此请求可用于获取特定 zainbox 的所有卡交易

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\Card;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = Card::instantiate()->zainboxTransactionHistory(
        'THbxyfjkd20',  //zainboxCode -  required (string)
        20,             //count       -  required (int)         : specify how many records you want   
        '2023-11-01',   //dateFrom    -  optional (string|null) : specify start date 
        '2023-11-30'    //dateTo      -  optional (string|null) : specify end date
    );

    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "data": [
            {
                "amount": "19900.0",
                "cardLastFourDigits": "",
                "cardType": "others",
                "paymentRef": "dVE8Dsh4brW3FNAJa5REEvnhICHmU9",
                "settledAccountNumber": "7966884043",
                "txnDate": "2023-10-03T12:10:08",
                "txnRef": "txn_0065004100",
                "txnStatus": "success",
                "zainboxCode": "THbfnDvK5o"
            },
            {
                "amount": "19900.0",
                "cardLastFourDigits": "",
                "cardType": "others",
                "paymentRef": "uisygRZV6xzH0yYVuRzBp7dlXQ3bfC",
                "settledAccountNumber": "7966884043",
                "txnDate": "2023-10-03T11:28:53",
                "txnRef": "txn_0065004099",
                "txnStatus": "success",
                "zainboxCode": "THbfnDvK5o"
            },
        ],
        "description": "successful",
        "status": "200 OK"
    }

获取所有 Zainboxes 的卡交易

此请求可用于获取所有 zainbox 的所有卡交易

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\Card;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = Card::instantiate()->merchantTransactionHistory(
        null,    //zainboxCode - optional (string|null)  : filter by zainboxCode or null to return all zainboxes
        20,      //count       - required (int), specify : how many records you want to return  
        null,    //dateFrom    - optional (string|null)  : specify start date 
        null     //dateTo      - optional (string|null)  : specify end date
    );

    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

  {
      "code": "00",
      "data": [
          {
              "amount": "19900.0",
              "cardLastFourDigits": "",
              "cardType": "others",
              "paymentRef": "dVE8Dsh4brW3FNAJa5REEvnhICHmU9",
              "settledAccountNumber": "7966884043",
              "txnDate": "2023-10-03T12:10:08",
              "txnRef": "txn_0065004100",
              "txnStatus": "success",
              "zainboxCode": "THbfnDvK5o"
          },
          {
              "amount": "19900.0",
              "cardLastFourDigits": "",
              "cardType": "others",
              "paymentRef": "uisygRZV6xzH0yYVuRzBp7dlXQ3bfC",
              "settledAccountNumber": "7966884043",
              "txnDate": "2023-10-03T11:28:53",
              "txnRef": "txn_0065004099",
              "txnStatus": "success",
              "zainboxCode": "THbfnDvK5o"
          },
      ],
      "description": "successful",
      "status": "200 OK"
  }

对卡支付进行核对

此请求可用于付款人已被扣除，但支付未反映在交易列表中的场景

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\Card;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = Card::instantiate()->reconcileCardPayment(
        'CARD1234',  //txnRef -  required (string)
    );

    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "data": {
            "paymentRef": "abUoNagV7ls4LaABR6qSWmyz1vOVBW",
    		"txnDate": "2023-08-14T15:27:03",
    		"txnRef": "txn_000060",
    		"txnStatus": "success"
        },
        "description": "successful",
        "status": "200 OK"
    }

Zainbox

创建 Zainbox

zainbox 是一个虚拟桶，允许商家创建无限多个虚拟账户。

此请求允许商家创建 zainbox。

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\ZainBox;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = ZainBox::instantiate()->create(
        "Box Test 1",                   //name                      - required (string),
        "test@email.com",               //emailNotification         - required (string),
        ['php','sdk'],                  //tags                      - optional (array|null)
        "https://example.com/webhook",  //callbackUrl               - required (string)
        "description",                  //description               - optional (string|null) 
        "Test",                         //codeNamePrefix            - optional (string|null) - prefix that you want to add to the codeName for easy identification 
        false                           //allowAutoInternalTransfer - optional (bool|null) - if set to true, whenever money is deposited on any of the zainbox VAs it will be automatically transferred to settlement account.
    );


    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "status": "Success",
        "description": "successful",
        "data": {
            "codeName": "333_zB2lg6lJtcGzP5XqouN9",
            "name": "wecode-contribution"
        }
    }

获取所有 Zainboxes

此请求允许商家获取所有创建的 zainbox。

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\ZainBox;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = ZainBox::instantiate()->list();

    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "data": [
            {
                "callbackUrl": "http://10e1-41-184-106-54.ngrok.io/notification",
                "codeName": "THbfnDvK5o",
                "name": "test-box",
                "tags": "land, management"
            },
            {
                "callbackUrl": "https://powershop.ng/notification",
                "codeName": "rAqwjnYO5chL3QuV7yk0",
                "name": "powershop8",
                "tags": "discos, kedco, aedc"
            }
        ],
        "description": "successful",
        "status": "Success"
    }

更新 Zainbox

允许您更新 zainbox 详细信息，如回调 URL、电子邮件通知等

注意，您不能更新 zainboxCode。

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\ZainBox;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    string  $name,
            ?string $emailNotification,
            ?array  $tags,
            ?string $callbackUrl,
            ?string $description,
            ?bool   $allowAutoInternalTransfer,
            string  $zainboxCode

    $response = ZainBox::instantiate()->update(
        "Box Test 1",                   //name                      - required (string),
        "test@email.com",               //emailNotification         - required (string|null),
        ['php','sdk'],                  //tags                      - optional (array|null)
        "https://example.com/webhook",  //callbackUrl               - required (string)
        "description",                  //description               - optional (string|null) 
        false                           //allowAutoInternalTransfer - optional (bool|null) : if set to true, whenever money is deposited on any of the zainbox VAs it will be automatically transferred to settlement account.
        "zainboxCode",                 //zainboxCode                - required (string)
    );


    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "status": "Success",
        "description": "successful",
        "data": {
            "codeName": "333_zB2lg6lJtcGzP5XqouN9",
            "name": "wecode-contribution"
        }
    }

Zainbox 配置文件和当前计费计划

获取 Zainbox 的完整配置文件，包括账户到账户和跨行转账的当前计费计划

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\ZainBox;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = ZainBox::instantiate()->profile(
        '<ZainboxCode>' //zainboxCode - required (string)
    );

    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "description": "successful",
        "status": "Success",
        "data": {
            "zainbox": {
                "callbackUrl": "https://:5000/notification",
                "codeName": "THbfnDvK5o",
                "name": "test-box",
                "tags": "land, management"
            },
            "account2AccountBilling": {
                "fixedCharge": "1000",
                "percentageCharge": 1.5
            },
            "interBankBilling": {
                "fixedCharge": "5000.0",
                "percentageCharge": 1.4
            }
        }
    }

创建或更新 Zainbox 结算

此请求允许商家为 zainbox 创建计划结算。请注意，在任何给定时间，zainbox 只能有一个类型的结算。

计划结算分为三个类别

T1: 交易加一个工作日 T1 调度的值。周期必须是每天。
T2: 交易加 7 天 对于 T7 调度，交易加七天应该是周一、周二、周三、周四、周五、周六或周日。
T3: 交易加 30 天 T30 调度的周期值应为 1-30 或 lastDayOfMonth

*重要提示

像 2 月 28 日和 2 月 29 日这样的日子，以及只有 30 天的月份，将由 lastDayOfMonth 覆盖。

有效载荷的 settlementAccountList 参数是银行账户数组和/或列表，以及相应的结算百分比。

将状态设置为 false 以禁用自动结算

场景

假设您有一个包含三个虚拟账户的 zainbox，并且您想将其设置为这三个虚拟账户的总存款在每次交易加一天（T1）时在两个账户之间分割。第一个结算账户有 90% 的资金，而第二个账户只有 10%。

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\ZainBox;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = ZainBox::instantiate()->createSettlement(
            'new-daily-settlement',//name - required (string)
            'THbfnDvK5op',         //zainboxCode - required (string)
            'T1',                  //scheduleType  - required (string)
            'Daily',               //schedulePeriod - required (string)
            [                      //settlementAccountList required (array) : contains list of ConstructSettlementAccountPayload
                ZainBox::ConstructSettlementAccountPayload(
                    "1234567890", //accountNumber - required (string)
                    "0009",       //bankCode      - required (string)
                    "90"          //percentage    - required (float)
                ),
                ZainBox::ConstructSettlementAccountPayload(
                    "0234567892", //accountNumber - required (string)
                    "0020",       //bankCode      - required (string)
                    "10"          //percentage    - required (float)
                ),
            ],                   
            true,                //status required (bool)
    );

    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "description": "successful",
        "status": "200 OK"
    }

获取 Zainbox 结算

此请求允许商家获取与 zainbox 关联的结算（s）

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\ZainBox;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = ZainBox::instantiate()->getSettlement(
        '<zainboxCode>' //zainboxCode - required (string)
    );

    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "data": {
            "name": "new-daily-settlement3",
            "schedulePeriod": "Daily",
            "scheduleType": "T1",
            "settlementAccounts": [
                {
                    "accountNumber": "4424699900",
                    "bankCode": "000017",
                    "percentage": "50"
                },
                {
                    "accountNumber": "4429775715",
                    "bankCode": "000017",
                    "percentage": "50"
                }
            ],
            "zainbox": "settl_W5HMsiwQB3HdtCbvUnBN"
        },
        "description": "Successful",
        "status": "200 OK"
    }

获取 Zainbox 收到的总付款

获取特定时间段内特定 zainbox 所有的虚拟账户收集的总金额，包括转账和存款交易

参数: zainboxCode（必填），dateFrom（可选，如果未提供，系统返回当前月份的数据），dateTo（可选）

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\ZainBox;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = Card::instantiate()->totalPaymentCollectedByZainbox(
        'THbxyfjkd20',  //zainboxCode -  required (string)
        '2022-02',      //dateFrom    -  optional (string|null) : specify start date 
        '2022-03'       //dateTo      -  optional (string|null) : specify end date
    );

    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "data": [
        {
            "count": 4,
            "dateFrom": "2022-02",
            "dateTo": "2022-03",
            "total": "12690",
            "transactionType": "deposit"
        },
            {
            "count": 4,
            "dateFrom": "2022-02",
            "dateTo": "2022-03",
            "total": "29038",
            "transactionType": "transfer"
        }
        ],
        "description": "Summary grouped by txn type",
        "status": "Success"
    }

获取所有 Zainboxes 收到的总付款

获取特定期间内所有虚拟账户在所有zainbox中收集的总金额之和，包括转账和存款交易

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\ZainBox;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = Card::instantiate()->totalPaymentCollectedByMerchant(
        '2022-02',   //dateFrom    -  optional (string|null) : specify start date 
        '2022-03'    //dateTo      -  optional (string|null) : specify end date
    );

    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "data": [
        {
            "count": 4,
            "dateFrom": "2022-02",
            "dateTo": "2022-03",
            "total": "12690",
            "transactionType": "deposit"
        },
            {
            "count": 4,
            "dateFrom": "2022-02",
            "dateTo": "2022-03",
            "total": "29038",
            "transactionType": "transfer"
        }
        ],
        "description": "Summary grouped by txn type",
        "status": "Success"
    }

获取 Zainbox 交易列表

此请求允许您获取特定zainbox的交易列表

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\ZainBox;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = ZainBox::instantiate()->transactionList(
        'zainboxCode',             //zainboxCode    - required (string)
        20,                        //count          - required (int)         : number of transactions you want to return
        '4426334208',              //accountNumber  - optional (string|null) : use to filter transactions ortherwise use null value.
        'deposit',                 //txnType        - optional (string|null) : use to filter transactions ortherwise use null value. e.g [deposit|transfer]
        'virtualAccountTransfer',  //paymentChannel - optional (string|null) : use to filter transactions ortherwise use null value. e.g [cardPayment|virtualAccountTransfer]
        null,                      //dateFrom       - optional (string|null) : use to filter transactions ortherwise use null value.
        null,                      //dateTo         - optional (string|null) : use to filter transactions ortherwise use null value.
    );

    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "data": [
        {
            "accountNumber": "7964524199",
            "amount": 45000,
            "balance": 45000,
            "narration": "",
            "transactionDate": "2021-12-28T11:47:45",
            "transactionRef": "",
            "transactionType": "deposit"
        },
        {
            "accountNumber": "7964524199",
            "amount": 923000,
            "balance": 968000,
            "narration": "",
            "transactionDate": "2021-12-28T11:48:35",
            "transactionRef": "",
            "transactionType": "deposit"
        }],
        "description": "successful",
        "status": "Success"
    }

获取 Zainbox 虚拟账户

此请求允许您获取与zainbox关联的所有虚拟账户

    use Zainpay\SDK\Engine;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');
    $response = \Zainpay\SDK\ZainBox::instantiate()->listVirtualAccounts(
    '<zainboxCode>' //zainboxCode - required (string)
    );
    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    [
        {
            "bankAccount": "4426334208",
            "bankName": "035",
            "name": "John Saminu Sunday"
        },
        {
            "bankAccount": "7969472891",
            "bankName": "035",
            "name": "Idris Urmi Bello"
        }
    ]

虚拟账户

创建虚拟账户

创建虚拟账户。将虚拟账户映射到zainbox。一个zainbox可以包含多个虚拟账户。

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\VirtualAccount;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');
    $response = VirtualAccount::instantiate()->createVirtualAccount(
        'wemaBank'                      //bankType      - required (Enum[wemaBank, polaris, zainMFB])
        '22000000000'                   //bvn           - required (string)
        'Nura'                          //firstName     - required (string)
        'Yusuf'                         //surname       - required (string)
        'test@gmail.com'                //email         - required (string)
        '08012345678'                   //mobileNumber  - required (string)
        '12-08-1999'                    //dob           - required (string)
        'M'                             //gender        - required (string)
        'No 21 AA Rufai street, Kano'   //address       - required (string)
        'Mr'                            //title         - required (string)
        'Kano'                          //state         - required (string)
        'zainboxCode'                   //zainboxCode   - required (string)
    );

    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "data": {
            "accountName": "Nura Yusuf ",
            "accountNumber": "4426334208", 
            "accountType": "",
            "bankName": "wemaBank",
            "email": "test@gmail.com"
        },
        "description": "Successful",
        "status": "Success"
    }

获取虚拟账户余额

此请求允许您获取虚拟账户号的当前钱包余额

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\VirtualAccount;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = VirtualAccount::instantiate()->balance(
    '7966884043' //virtualAccoutNumber - required (string)
    );
    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "data":
        {
            "accountName": "Aminu Nasar Adam", 
            "accountNumber": "7966884043", 
            "balanceAmount": 372555, 
            "transactionDate": "2021-10-13T13:45:52" 
        }, 
        "description": "successful",
        "status": "Success" 
    }

更新虚拟账户状态

此请求允许您激活或停用虚拟账户。

注意：将状态字段设置为true将激活虚拟账户，而设置为false将停用它。

重要提示已停用的虚拟账户将无法接收或转账资金

    use Zainpay\SDK\Engine;
        use Zainpay\SDK\VirtualAccount;


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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = VirtualAccount::instantiate()->listVirtualAccounts(
    'zainboxCode', //zainboxCode - required (string)
    '7966884043',  //virtualAccoutNumber - required (string)
    true           //status - required (boolean)
    );
    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "description": "Successfully Updated Account",
        "status": "success"
    }

一个 Zainbox 的所有虚拟账户余额

此请求允许商户获取zainbox中所有虚拟账户的所有当前账户余额。

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\VirtualAccount;


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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = VirtualAccount::instantiate()->allVirtualAccountsBalanceOfZainBox(
    'zainboxCode' //zainboxCode - required (string)
    );

    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "data":  
        [
            {
            "accountName": "Aminu Nasar",
            "accountNumber": "7966884043",
            "balanceAmount": 372555,
            "transactionDate": "2021-10-13T13:45:52"
            },
            {
            "accountName": "Khalid Ali Sani",
            "accountNumber": "1234567890",
            "balanceAmount": 200,
            "transactionDate": "2021-12-13T13:45:52"
            },
            {
            "accountName": "Nura Bala Usman",
            "accountNumber": "9900778833",
            "balanceAmount": 105000,
            "transactionDate": "2022-01-29T13:45:52"
            }
        ],
        "description": "successful",
        "status": "Success"
    }

虚拟账户交易

此请求允许您获取账户的所有交易

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\VirtualAccount;


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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = ZainBox::instantiate()->transactionList(
        'zainboxCode',             //accountNumber  - required (string)
        20,                        //count          - required (int)         : number of transactions you want to return
        'deposit',                 //txnType        - optional (string|null) : use to filter transactions ortherwise use null value. e.g [deposit|transfer]
        'virtualAccountTransfer',  //paymentChannel - optional (string|null) : use to filter transactions ortherwise use null value. e.g [cardPayment|virtualAccountTransfer]
        null,                      //dateFrom       - optional (string|null) : use to filter transactions ortherwise use null value.
        null,                      //dateTo         - optional (string|null) : use to filter transactions ortherwise use null value.
    );

    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "data": [
            {
                "accountNumber": "7966884043",
                "destinationAccountNumber": "2000002105",
                "amount": 7289,
                "balance": 379844,
                "narration": "",
                "transactionDate": "2021-10-13T13:41:39",
                "transactionRef": "",
                "transactionType": "transfer"
            },
            {
                "accountNumber": "7966884043",
                "destinationAccountNumber": "1234567890",
                "amount": 7289,
                "balance": 372555,
                "narration": "",
                "transactionDate": "2021-10-13T13:45:52",
                "transactionRef": "",
                "transactionType": "transfer"
            }
        ],
        "description": "successful",
        "status": "Success"
    }

通过 Zainbox 获取所有虚拟账户

获取与zainbox关联的所有虚拟账户

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\VirtualAccount;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');
    $response = \Zainpay\SDK\ZainBox::instantiate()->listVirtualAccounts(
    '<zainboxCode>' //zainboxCode - required (string)
    );
    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "data":  
        [
            {
            "accountName": "Aminu Nasar",
            "accountNumber": "7966884043",
            "balanceAmount": 372555,
            "transactionDate": "2021-10-13T13:45:52"
            },
            {
            "accountName": "Khalid Ali Sani",
            "accountNumber": "1234567890",
            "balanceAmount": 200,
            "transactionDate": "2021-12-13T13:45:52"
            },
            {
            "accountName": "Nura Bala Usman",
            "accountNumber": "9900778833",
            "balanceAmount": 105000,
            "transactionDate": "2022-01-29T13:45:52"
            }
        ],
        "description": "successful",
        "status": "Success"
    }

转账验证

请求可用于通过在成功转账后获得的txnRef验证已发布的转账

参数: txnRef（必填）。

    use Zainpay\SDK\Engine;
    use Zainpay\SDK\VirtualAccount;

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

    Engine::setMode(Engine::MODE_DEVELOPMENT);
    Engine::setToken('<PUBLIC_KEY>');

    $response = VirtualAccount::instantiate()->verifyTransfer(
        '<Transaction-Reference>' //txnRef - required (string)
    );

    if ($response->hasSucceeded()){
        var_dump($response->getData());
    }

响应

    {
        "code": "00",
        "data": {
            "amount": "8431",
            "destinationAccountNumber": "0044159752",
            "destinationBankCode": "000005",
            "narration": "lunch for naimat",
            "sourceAccountNumber": "7964524199",
            "txnDate": "2021-12-29T08:00:49",
            "txnStatus": "success"
        },
        "description": "successful",
        "status": "Success"
    }

存款验证