README

MoIP v2 PHP客户端SDK

最简单快捷的方式将Moip集成到您的PHP应用中

SDK当前状态

统计数据

版本

索引

安装
配置认证
- 通过BasicAuth
- 通过OAuth
使用示例:
- 客户端
- 订单
  - 创建
  - 查询
    - 特定订单
    - 所有订单
- 支付
- 退款
- OAuth (Moip Connect)
  - 请求用户访问权限
  - 生成OAuth访问令牌
- 多订单
  - 创建
  - 查询
- 多支付
  - 创建
  - 查询
- Moip账户
- Moip余额
  - 查询
- 银行账户
  - 创建
  - 查询
  - 列表
  - 更新
  - 删除
- 转账
  - 创建
  - 查询
  - 列表
  - 反冲
- 通知偏好
  - 创建
  - 查询
  - 删除
  - 列表
- Webhooks
  - 查询
包
异常处理
文档
测试
许可
Slack社区

包

依赖项

require

PHP >= 5.5
rmccue/requests >= 1.0

require-dev

phpunit/phpunit ~ 4.0

安装

在您的shell中执行

composer require moip/moip-sdk-php

配置认证

通过Basic Auth

require 'vendor/autoload.php';

use Moip\Moip;
use Moip\Auth\BasicAuth;

$token = '01010101010101010101010101010101';
$key = 'ABABABABABABABABABABABABABABABABABABABAB';

$moip = new Moip(new BasicAuth($token, $key), Moip::ENDPOINT_SANDBOX);

通过OAuth

require 'vendor/autoload.php';

use Moip\Moip;
use Moip\Auth\OAuth;

$access_token = '33031e2aad484051b89030487e59d133_v2';
$moip = new Moip(new OAuth($access_token), Moip::ENDPOINT_SANDBOX);

客户端

创建一个买家

本例中将创建一个包含客户数据的订单 - 包括交货和支付地址。

$customer = $moip->customers()->setOwnId(uniqid())
    ->setFullname('Fulano de Tal')
    ->setEmail('fulano@email.com')
    ->setBirthDate('1988-12-30')
    ->setTaxDocument('22222222222')
    ->setPhone(11, 66778899)
    ->addAddress('BILLING',
        'Rua de teste', 123,
        'Bairro', 'Sao Paulo', 'SP',
        '01234567', 8)
    ->addAddress('SHIPPING',
                'Rua de teste do SHIPPING', 123,
                'Bairro do SHIPPING', 'Sao Paulo', 'SP',
                '01234567', 8)
    ->create();
print_r($customer);

查询一个买家的数据

$customer = $moip->customers()->get('CUS-Q3BL0CAJ2G33');
print_r($customer);

添加信用卡

$customer = $moip->customers()->creditCard()
    ->setExpirationMonth('05')
    ->setExpirationYear(2018)
    ->setNumber('4012001037141112')
    ->setCVC('123')
    ->setFullName('Jose Portador da Silva')
    ->setBirthDate('1988-12-30')
    ->setTaxDocument('CPF', '33333333333')
    ->setPhone('55','11','66778899')
    ->create(CUSTOMER_ID);
print_r($customer);

删除信用卡

$moip->customers()->creditCard()->delete(CREDIT_CARD_ID);

订单

使用我们刚刚创建的买家创建一个订单

本例中包含多个产品，并指定运费、附加费和折扣金额。

$order = $moip->orders()->setOwnId(uniqid())
    ->addItem("bicicleta 1",1, "sku1", 10000)
    ->addItem("bicicleta 2",1, "sku2", 11000)
    ->addItem("bicicleta 3",1, "sku3", 12000)
    ->addItem("bicicleta 4",1, "sku4", 13000)
    ->addItem("bicicleta 5",1, "sku5", 14000)
    ->addItem("bicicleta 6",1, "sku6", 15000)
    ->addItem("bicicleta 7",1, "sku7", 16000)
    ->addItem("bicicleta 8",1, "sku8", 17000)
    ->addItem("bicicleta 9",1, "sku9", 18000)
    ->addItem("bicicleta 10",1, "sku10", 19000)
    ->setShippingAmount(3000)->setAddition(1000)->setDiscount(5000)
    ->setCustomer($customer)
    ->create();
print_r($order);

查询一个订单

特定订单

$order = $moip->orders()->get('ORD-KZCH1S1ORAH23');
print_r($order);

所有订单

无筛选

$orders = $this->moip->orders()->getList();

筛选

$filters = new Filters();
$filters->greaterThanOrEqual(OrdersList::CREATED_AT, '2017-08-17');
$filters->in(OrdersList::PAYMENT_METHOD, ['BOLETO', 'DEBIT_CARD']);
$filters->lessThan(OrdersList::VALUE, 100000);

$orders = $this->moip->orders()->getList(null, $filters);

分页

$orders = $this->moip->orders()->getList(new Pagination(10,0));

查询特定值

$orders = $this->moip->orders()->getList(null, null, 'josé silva');

也可以同时使用分页、筛选和查询特定值

$filters = new Filters();
$filters->greaterThanOrEqual(OrdersList::CREATED_AT, '2017-08-17');
$filters->lessThan(OrdersList::VALUE, 100000);

$orders = $this->moip->orders()->getList(new Pagination(10,0), $filters, 'josé silva');

支付

创建

信用卡

创建订单后，只需在该订单中创建一个支付即可。

插入持卡人信息

要使用第三方信用卡（当客户不是将要使用的信用卡的持卡人）进行信用卡支付，必须将这些数据区分开来并正确地通知每个步骤。

$holder = $moip->holders()->setFullname('Jose Silva')
    ->setBirthDate("1990-10-10")
    ->setTaxDocument('22222222222', 'CPF')
    ->setPhone(11, 66778899, 55)
    ->setAddress('BILLING', 'Avenida Faria Lima', '2927', 'Itaim', 'Sao Paulo', 'SP', '01234000', 'Apt 101');

使用哈希值

有关使用卡信息生成哈希值的更多详细信息，请参阅文档。

$hash = 'i1naupwpTLrCSXDnigLLTlOgtm+xBWo6iX54V/hSyfBeFv3rvqa1VyQ8/pqWB2JRQX2GhzfGppXFPCmd/zcmMyDSpdnf1GxHQHmVemxu4AZeNxs+TUAbFWsqEWBa6s95N+O4CsErzemYZHDhsjEgJDe17EX9MqgbN3RFzRmZpJqRvqKXw9abze8hZfEuUJjC6ysnKOYkzDBEyQibvGJjCv3T/0Lz9zFruSrWBw+NxWXNZjXSY0KF8MKmW2Gx1XX1znt7K9bYNfhA/QO+oD+v42hxIeyzneeRcOJ/EXLEmWUsHDokevOkBeyeN4nfnET/BatcDmv8dpGXrTPEoxmmGQ==';
$payment = $order->payments()
    ->setCreditCardHash($hash, $holder)
    ->setInstallmentCount(3)
    ->setStatementDescriptor('teste de pag')
    ->execute();
print_r($payment);

使用卡信息

此方法需要PCI认证。请参阅文档。

$payment = $order->payments()->setCreditCard(12, 21, '4073020000000002', '123', $holder)
    ->execute();
print_r($payment);

使用银行汇票创建支付

$logo_uri = 'https://cdn.moip.com.br/wp-content/uploads/2016/05/02163352/logo-moip.png';
$expiration_date = new DateTime();
$instruction_lines = ['INSTRUÇÃO 1', 'INSTRUÇÃO 2', 'INSTRUÇÃO 3'];
$payment = $order->payments()  
    ->setBoleto($expiration_date, $logo_uri, $instruction_lines)
    ->execute();
print_r($payment);

使用银行转账创建支付

在线银行转账支付也仅发送3个参数

您希望显示的logo的URL，以下用变量表示：$return_uri;
到期日，以下用变量表示：$expiration_date;
变量 $bank_number 表示的银行编号（目前唯一可能的值是 341，代表 Itaú 银行）。

$bank_number = '341';
$return_uri = 'https://moip.com.br';
$expiration_date = new DateTime();
$payment = $order->payments()                    
    ->setOnlineBankDebit($bank_number, $expiration_date, $return_uri)
    ->execute();
print_r($payment);

查询

$payment = $moip->payments()->get('PAYMENT-ID');
print_r($payment);

捕获预授权支付

$captured_payment = $payment->capture();
print_r($captured_payment);

取消预授权支付

用于取消预授权支付的 avoid 方法已被 cancel 方法替代。

$payment = $payment->cancel();
print_r($payment);

退款

要执行退款，需要具有您要退款的支付对象的 Payment 或仅传递支付 ID。

信用卡

总金额

使用对象

$refund = $payment->refunds()->creditCardFull();
print_r($refund);

部分金额

使用对象

$refund = $payment->refunds()->creditCardPartial(30000);
print_r($refund);

银行账户

总金额

使用对象

$type = 'CHECKING';
$bank_number = '001';
$agency_number = 4444444;
$agency_check_number = 2;
$account_number = 1234;
$account_check_number = 4;
$refund = $payment->refunds()
    ->bankAccountFull(
        $type,
        $bank_number,
        $agency_number,
        $agency_check_number,
        $account_number,
        $account_check_number,
        $customer
    );
print_r($refund);

部分金额

使用对象

$amount = 30000;
$type = 'SAVING';
$bank_number = '001';
$agency_number = 4444444;
$agency_check_number = 2;
$account_number = 1234;
$account_check_number = 4;
$refund = $payment->refunds()
    ->bankAccountPartial(
        $amount,
        $type,
        $bank_number,
        $agency_number,
        $agency_check_number,
        $account_number,
        $account_check_number,
        $customer
    );
print_r($refund);

查询退款

$refund = $payment->refunds()->get($refund_id);

OAuth (Moip Connect)

请求用户访问权限

要请求权限，您需要调用 getAuthUrl 方法（该方法构建 URL）并将用户重定向到生成的 URL。用户需要授予权限，然后将被重定向到您的 App 指定的 URL，并将其作为属性传递给 Connect 对象。

作为属性传递的 URL 必须与创建 APP 时注册的 URL 完全相同，如果存在任何差异，用户将无法正确重定向。

一旦获得权限，您将收到一个 code，它将允许您生成用于认证的 accessToken 并处理涉及其他用户的请求。

$redirect_uri = 'http://seusite.com.br/callback.php';
$client_id = 'APP-18JTHC3LOMT9';
$scope = true;
$connect = new Connect($redirect_uri, $client_id, $scope, Connect::ENDPOINT_SANDBOX);
$connect->setScope(Connect::RECEIVE_FUNDS)
    ->setScope(Connect::REFUND)
    ->setScope(Connect::MANAGE_ACCOUNT_INFO)
    ->setScope(Connect::RETRIEVE_FINANCIAL_INFO);
header('Location: '.$connect->getAuthUrl());

生成OAuth访问令牌

以下我们将使用 authorize 方法生成 OAuth 访问令牌。请注意，必须实例化 Connect 对象并按照以下示例传递参数。

我们使用变量 $code 发送用户权限收到的 code，并使用 setCode 方法将其插入对象中。

作为属性传递的 URL 必须与创建 APP 时注册的 URL 完全相同，如果存在任何差异，则无法恢复 accessToken。

$redirect_uri = 'http://seusite.com.br/callback.php';
$client_id = 'APP-18JTHC3LOMT9';
$scope = true;
$connect = new Connect($redirect_uri, $client_id, $scope, Connect::ENDPOINT_SANDBOX);
$client_secret = '20f76456f6ec4874a1f38082d3139326';
$connect->setClientSecret($client_secret);
$code = 'f9053ca6e9853dd73f0bc4f332a5ce337b0bb0da';
$connect->setCode($code);
$auth = $connect->authorize();
print_r($auth);

多订单

创建多订单

$order = $moip->orders()->setOwnId(uniqid())
    ->addItem("bicicleta 1",1, "sku1", 10000)
    ->addItem("bicicleta 2",1, "sku2", 11000)
    ->addItem("bicicleta 3",1, "sku3", 12000)
    ->addItem("bicicleta 4",1, "sku4", 13000)
    ->setShippingAmount(3000)
    ->setAddition(1000)
    ->setDiscount(5000)
    ->setCustomer($customer)
    ->addReceiver('MPA-VB5OGTVPCI52', 'PRIMARY', NULL);
$order2 = $moip->orders()->setOwnId(uniqid())
    ->addItem("bicicleta 1",1, "sku1", 10000)
    ->addItem("bicicleta 2",1, "sku2", 11000)
    ->addItem("bicicleta 3",1, "sku3", 12000)
    ->setShippingAmount(3000)
    ->setAddition(1000)
    ->setDiscount(5000)
    ->setCustomer($customer)
    ->addReceiver('MPA-IFYRB1HBL73Z', 'PRIMARY', NULL);

$multiorder = $this->moip->multiorders()
    ->setOwnId(uniqid())
    ->addOrder($order)
    ->addOrder($order2)
    ->create();
print_r($multiorder);

查询多订单

$multiorder_id = 'ORD-KZCH1S1ORAH25';
$multiorder = $moip->multiorders()->get($multiorder_id);
print_r($multiorder);

多支付

创建多支付

$hash = 'i1naupwpTLrCSXDnigLLTlOgtm+xBWo6iX54V/hSyfBeFv3rvqa1VyQ8/pqWB2JRQX2GhzfGppXFPCmd/zcmMyDSpdnf1GxHQHmVemxu4AZeNxs+TUAbFWsqEWBa6s95N+O4CsErzemYZHDhsjEgJDe17EX9MqgbN3RFzRmZpJqRvqKXw9abze8hZfEuUJjC6ysnKOYkzDBEyQibvGJjCv3T/0Lz9zFruSrWBw+NxWXNZjXSY0KF8MKmW2Gx1XX1znt7K9bYNfhA/QO+oD+v42hxIeyzneeRcOJ/EXLEmWUsHDokevOkBeyeN4nfnET/BatcDmv8dpGXrTPEoxmmGQ==';
$payment = $multiorder->multipayments()
    ->setCreditCardHash($hash, $customer)
    ->setInstallmentCount(3)
    ->setStatementDescriptor('teste de pag')
    ->execute();
print_r($payment);

查询

$payment = $moip->payments()->get('MULTIPAYMENT-ID');
print_r($payment);

Moip账户

创建

$street = 'Rua de teste';
$number = 123;
$district = 'Bairro';
$city = 'Sao Paulo';
$state = 'SP';
$zip = '01234567';
$complement = 'Apt. 23';
$country = 'BRA';
$area_code = 11;
$phone_number = 66778899;
$country_code = 55;
$identity_document = '4737283560';
$issuer = 'SSP';
$issue_date = '2015-06-23';
$account = $moip->accounts()
    ->setName('Fulano')
    ->setLastName('De Tal')
    ->setEmail('fulano@email2.com')
    ->setIdentityDocument($identity_document, $issuer, $issue_date)
    ->setBirthDate('1988-12-30')
    ->setTaxDocument('16262131000')
    ->setType('MERCHANT')
    ->setPhone($area_code, $phone_number, $country_code)
    ->addAlternativePhone(11, 66448899, 55)
    ->addAddress($street, $number, $district, $city, $state, $zip, $complement, $country)        
    ->setCompanyName('Empresa Teste', 'Teste Empresa ME')
    ->setCompanyOpeningDate('2011-01-01')
    ->setCompanyPhone(11, 66558899, 55)
    ->setCompanyTaxDocument('69086878000198')
    ->setCompanyAddress('Rua de teste 2', 123, 'Bairro Teste', 'Sao Paulo', 'SP', '01234567', 'Apt. 23', 'BRA')
    ->setCompanyMainActivity('82.91-1/00', 'Atividades de cobranças e informações cadastrais')
    ->create();
print_r($account);

查询

$account = $moip->accounts()->get(ACCOUNT_ID);
print_r($account);

检查用户是否已拥有 Moip 账户

// retorna verdadeiro se já possui e falso caso não possuir conta Moip
$moip->accounts()->checkAccountExists(CPF);

获取Moip账户的公钥

$keys = $moip->keys()->get();
print_r($keys);

Moip余额

余额是特定 Moip 账户当前可用、不可用（已锁定）和未来值的组合。

此 API 为 2.1 版本，包含 header Accept，值为 application/json;version=2.1。

查询余额

$balances = $moip->balances()->get();

需要 OAuth 认证。

银行账户

银行账户是特定 Moip 账户的银行住所。此 API 允许创建、查询和修改银行账户数据。

创建银行账户

$bank_account = $moip->bankaccount()
    ->setBankNumber('237')
    ->setAgencyNumber('12345')
    ->setAgencyCheckNumber('0')
    ->setAccountNumber('12345678')
    ->setAccountCheckNumber('7')
    ->setType('CHECKING')
    ->setHolder('Demo Moip', '622.134.533-22', 'CPF')
    ->create($moip_account_id);

查询银行账户

$bank_account = $moip->bankaccount()->get($bank_account_id);

列出银行账户

$bank_accounts = $moip->bankaccount()->getList($account_id)->getBankAccounts();

更新银行账户

$bank_account = $moip->bankaccount()
    ->setAccountCheckNumber('8')
    ->update($bank_account_id);

删除银行账户

$moip->bankaccount()->delete($bank_account_id);

通知偏好

创建

$notification = $moip->notifications()->addEvent('ORDER.*')
    ->addEvent('PAYMENT.AUTHORIZED')
    ->setTarget('http://requestb.in/1dhjesw1')
    ->create();
print_r($notification);

查询

$notification = $this->moip->notifications()->get('NPR-N6QZE3223P98');
print_r($notification);

删除

$notification = $moip->notifications()->delete('NOTIFICATION-ID');
print_r($notification);

列表

$notifications = $moip->notifications()->getList();
print_r($notifications);

Webhooks

默认情况下，PHP 仅准备接收一些类型的 content-type（application/x-www-form-urlencoded 和 multipart/form-data）。然而，Moip 平台以 JSON 格式发送数据，这是语言默认情况下未准备接收的。为了接收并访问 Moip 发送的数据，您需要将以下代码添加到接收 webhooks 的文件中

// Pega o RAW data da requisição
$json = file_get_contents('php://input');
// Converte os dados recebidos
$response = json_decode($json, true);

查询

无分页或资源/事件过滤

$moip->webhooks()->get();

分页和资源/事件过滤

$moip->webhooks()->get(new Pagination(10, 0), 'ORD-ID', 'ORDER.PAID');

转账

转账是在 Moip 账户和另一个支付账户（可以是银行账户或特定 Moip 账户）之间进行的资金流动。

创建/执行转账

通过银行账户

$amount = 500;
$bank_number = '001';
$agency_number = '1111';
$agency_check_number = '2';
$account_number = '9999';
$account_check_number = '8';
$holder_name = 'Nome do Portador';
$tax_document = '22222222222';

$transfer = $moip->transfers()
    ->setTransfers($amount, $bank_number, $agency_number, $agency_check_number, $account_number, $account_check_number)
    ->setHolder($holder_name, $tax_document)
    ->execute();

print_r($transfer);

要使用已注册的银行账户执行转账

$transfer = $moip->transfers()
    ->setTransfersToBankAccount($amount, $bank_account_id)
    ->execute();

查询转账

$transfer_id = 'TRA-28HRLYNLMUFH';
$transfer = $moip->transfers()->get($transfer_id);

print_r($transfer);

列出转账

无分页

$transfers = $moip->transfers()->getList();

分页

$transfers = $moip->transfers()->getList(new Pagination(10,0));

撤销转账

$transfer_id = 'TRA-28HRLYNLMUFH';

$transfer = $moip->transfers()->revert($transfer_id);

异常处理

当 API 发生错误时，会抛出 UnexpectedException 异常以处理意外错误，UnautorizedException 异常以处理认证错误，以及 ValidationException 异常以处理验证错误。

try {
    $moip->customers()->setOwnId(uniqid())
        ->setFullname('Fulano de Tal')
        ->setEmail('fulano@email.com')
        //...
        ->create();
} catch (\Moip\Exceptions\UnautorizedException $e) {
    //StatusCode 401
    echo $e->getMessage();
} catch (\Moip\Exceptions\ValidationException $e) {
    //StatusCode entre 400 e 499 (exceto 401)
    printf($e->__toString());
} catch (\Moip\Exceptions\UnexpectedException $e) {
    //StatusCode >= 500
    echo $e->getMessage();
}

文档

官方文档

测试

默认情况下，测试不向 Moip API 发送任何请求。可以运行测试以针对 Sandbox 环境进行，为此只需设置环境变量

MOIP_ACCESS_TOKEN 是您的 Moip 应用程序的认证令牌。

如何注册您的 Moip 应用程序

要注册您的 Moip 应用程序，您需要提供访问密钥。如何获取访问密钥。

示例

export MOIP_ACCESS_TOKEN=76926cb0305243c8adc79aad54321ec1_v2
vendor/bin/phpunit -c .

许可

麻省理工学院许可证

Slack 社区

有疑问吗？在 Slack 上联系我们吧！

moip / moip-sdk-php

维护者

详细信息

README

MoIP v2 PHP客户端SDK

包

依赖项

require

require-dev

安装

配置认证

通过Basic Auth

通过OAuth

客户端

创建一个买家

查询一个买家的数据

添加信用卡

删除信用卡

订单

使用我们刚刚创建的买家创建一个订单

查询一个订单

特定订单

所有订单

无筛选

筛选

分页

查询特定值

支付

创建

信用卡

插入持卡人信息

使用哈希值

使用卡信息

使用银行汇票创建支付

使用银行转账创建支付

查询

捕获预授权支付

取消预授权支付

退款

信用卡

总金额

使用对象

部分金额

使用对象

银行账户

总金额

使用对象

部分金额

使用对象

查询退款

OAuth (Moip Connect)

请求用户访问权限

生成OAuth访问令牌

多订单

创建多订单

查询多订单

多支付

创建多支付

查询

Moip账户

创建

查询

检查用户是否已拥有 Moip 账户

获取Moip账户的公钥

Moip余额

查询余额

银行账户

创建银行账户

查询银行账户

列出银行账户

更新银行账户

删除银行账户

通知偏好

创建

查询

删除

列表

Webhooks

查询

无分页或资源/事件过滤