README

Moip-PHP是一个库，它实现了生成Moip指令XML的抽象层，允许您在不污染代码的情况下集成API服务。快速示例：

include_once "autoload.inc.php";

$moip = new Moip_Api();
$moip->setEnvironment('test');
$moip->setCredential(array(
    'key' => 'ABABABABABABABABABABABABABABABABABABABAB',
    'token' => '01010101010101010101010101010101'
    ));

$moip->setUniqueID(false);
$moip->setValue('100.00');
$moip->setReason('Teste do Moip-PHP');

$moip->validate('Basic');

print_r($moip->send());

Moip-PHP使用Fluent接口标准，因此您可以使用以下方式实现上述示例：

include_once "autoload.inc.php";

$moip = new Moip_Api(); 
print_r($moip->setEnvironment('test')
        ->setCredential(array(
    'key' => 'ABABABABABABABABABABABABABABABABABABABAB',
    'token' => '01010101010101010101010101010101'
    ))->setUniqueID(false)
        ->setValue('100.00')
        ->setReason('Teste do Moip-PHP')
        ->validate('Basic')
        ->send());

可用方法

以下列出了您可以使用Moip-PHP的可用方法和详细信息。

Moip_Api()

构造函数。

Moip_Api()

$moip = new Moip_Api();

setEnvironment()

此方法用于定义请求将处理的环境，'test'表示将使用Moip的测试环境Sandbox，省略此方法则表示请求将在Moip的生产环境中处理。

重要：在定义环境时，请确保您使用的是对应环境的认证，在Moip中，每个环境都有自己的API认证密钥。

setEnvironment($environment) $environment : String ('test')

$moip->setEnvironment('test');

setCredential()

Moip要求您进行认证才能处理API请求，为此，在执行任何请求之前，您应向Moip提供API凭证，由TOKEN和KEY组成。

参数$credential是一个关联数组，包含key和token键（例如：array('key'=>'sua_key','token'=>'seu_token')）。如果您还没有这些数据，请查看如何通过Sandbox账户获取它们。

setCredential($credential)

$credential : Array('key','token')

$moip->setCredential(array(
        'key' => 'SUA_KEY',
    	'token' => 'SEU_TOKEN'
    	));

validate()

validate()方法将对您要处理的指令类型所需的必填数据进行验证，您可以选择两种验证级别之一：'Basic'和'Identification'。

1. Basic：将验证向Moip发送XML请求所需的最小数据。
2. Identification：将验证处理带有Moip标识的XML所需的数据，通常用于在Moip支付页面的第二步中重定向客户或使用Moip透明支付。

validate($validateType)

$validateType : String ('Basic' 或 'Identification')

$moip->validate('Identification');

setUniqueID()

setUniqueID()方法为Moip XML中的<IdProprio>标签赋值。

1. <IdProprio>：您的唯一订单标识符，该信息将发送到您的状态变更通知中，以便您识别订单并处理其状态。

setUniqueID($id)

$id : String

$moip->setUniqueID('ABCD123456789');

setValue()

setValue()方法为Moip XML中的<Valor>标签赋值。

1. <Valor>: 负责定义应支付的价值。

setValue($value)

$value : 数字

$moip->setValue('100.00');	

setAdds()

setAdds() 方法将值赋给 Moip XML 中的 "<Acrescimo>" 标签。

1. <Acrescimo>: 负责定义应支付额外价值的。

setAdds($value)

$value : 数字

$moip->setAdds('15.00');	

setDeduct()

setDeduct() 方法将值赋给 Moip XML 中的 "<Deducao>" 标签。

1. <Deducao>: 负责定义将从中扣除的折扣价值。

setDeduct($value)

$value : 数字

$moip->setDeduct('15.00');

setReason()

setReason() 方法将值赋给 Moip XML 中的 "<Razao>" 标签。

1. <Razao>: 负责定义支付的原因。
2. 此字段在一个支付指令中始终是必需的。

setReason($value)

$value : 字符串

$moip->setReason('Pagamento de teste do Moip-PHP');

setPayer()

setPayer() 方法将值赋给 Moip XML 中的 "<Pagador>" 节点。

1. <Pagador>: 包含进行支付的人的信息的节点。
2. name : <Nome> : 支付者的全名
3. email : <Email> : 支付者的电子邮件
4. payerId : <IdPagador> : 支付者的唯一标识符
5. identity : <Identidade> : 支付者的身份 (CPF)
6. phone : <TelefoneCelular> : 支付者的备用联系电话
7. billingAddress : <EnderecoCobranca> : 支付者的地址
8. address : <Logradouro> : 支付者的道路，街道，大道，等等。
9. number : <Numero> : 支付者的住宅号码
10. complement : <Complemento> : 支付者地址的补充信息
11. city : <Cidade> : 支付者地址的城市
12. neighborhood : <Bairro> : 支付者地址的街区
13. state : <Estado> : 支付者地址的州，以 ISO-CODE (UF) 格式
14. country : <Pais> : 支付者的国家，以 ISO-CODE 格式
15. zipCode : <CEP> : 地址的 CEP
16. phone : <TelefoneFixo> : 支付者的联系电话

setPayer($value)

$value : 数组 ('name','email','payerId','identity', 'phone','billingAddress' => Array('address','number','complement','city','neighborhood','state','country','zipCode','phone'))

$moip->setPayer(array('name' => 'Nome Sobrenome',
    	'email' => 'email@cliente.com.br',
    	'payerId' => 'id_usuario',
        'billingAddress' => array('address' => 'Rua do Zézinho Coração',
        		'number' => '45',
        		'complement' => 'z',
        		'city' => 'São Paulo',
        		'neighborhood' => 'Palhaço João',
        		'state' => 'SP',
        		'country' => 'BRA',
        		'zipCode' => '01230-000',
        		'phone' => '(11)8888-8888')));

addPaymentWay()

addPaymentWay() 方法将值赋给 Moip XML 中 "<FormasPagamento>" 节点的 "<FormaPagamento>" 标签。

<FormaPagamento>: 定义在 Moip 结账中向支付者显示的支付方式。

1. billet : 在 Moip 结账中提供 "银行汇票" 作为支付方式。
2. financing : 在 Moip 结账中提供 "分期付款" 作为支付方式。
3. debit : 在 Moip 结账中提供 "账户扣款" 作为支付方式。
4. creditCard : 在 Moip 结账中提供 "信用卡" 作为支付方式。
5. debitCard : 在 Moip 结账中提供 "借记卡" 作为支付方式。

addPaymentWay($way)

$way : 字符串 ('billet','financing','debit','creditCard','debitCard')

$moip->addPaymentWay('creditCard');
$moip->addPaymentWay('billet');
$moip->addPaymentWay('financing');
$moip->addPaymentWay('debit');
$moip->addPaymentWay('debitCard');

setBilletConf()

setBilletConf() 方法将值赋给 Moip XML 中的 "<Boleto>" 节点，该节点负责定义银行汇票的附加配置和自定义。

1. $expiration : 格式为 "AAAA-MM-DD" 的日期或天数。
2. $workingDays : 如果 "$expiration" 是天数，则可以设置 "true" 以在工作日中计算，默认为连续天数。
3. $instructions : 要打印在汇票上的附加消息，最多三条消息。
4. $uriLogo : 您的标志URL，最大尺寸为75像素宽和40像素高。

setBilletConf($expiration, $workingDays, $instructions, $uriLogo)

$expiration : Int 或 Date

$workingDays : Boolean

$instructions : Array()

$uriLogo : String

$moip->setBilletConf("2011-04-06",
        	false,
        	array("Primeira linha",
            	"Segunda linha",
            	"Terceira linha"),
        	"http://seusite.com.br/logo.gif");

addMessage()

addMessage() 方法为XML Moip中的 "<Mensagens>" 节点的 "<Mensagem>" 标签分配值。

1. <Mensagens>: 包含 "<Mensagens>" 的节点。
2. <Mensagem>: 定义在Moip结账页面显示的附加消息的标签。

addMessage($msg)

$msg : String

$moip->addMessage('Seu pedido contem os produtos X,Y e Z.');

setReturnURL()

setReturnURL() 方法为XML Moip中的 "<URLRetorno>" 标签分配值，该标签负责定义在通过Moip结账完成支付后买家将被重定向的URL。

setReturnURL($url)

$url : String

$moip->setReturnURL('https://meusite.com.br/cliente/pedido/bemvindodevolta');

setNotificationURL()

setNotificationURL() 方法为XML Moip中的 "<URLNotificacao>" 标签分配值，该标签负责定义Moip在支付状态更改时向其发送NASP（支付状态更改通知）的URL。

setNotificationURL($url)

$url : String

$moip->setNotificationURL('https://meusite.com.br/nasp/');

addComission()

addComission() 方法为XML Moip中的 "<Comissoes>" 标签分配值，负责将次级收款人分配给交易。

1. $reason : 次级收款人将接收定义的值的理由/原因。
2. $receiver: 接收值的用户的Moip登录名。
3. $value : 分配给次级收款人的值。
4. $percentageValue: 如果为 "true"，则定义值将根据交易总金额的百分比计算。
5. $ratePayer: 如果为 "true"，则定义此次级收款人将支付通过接收到的金额支付的Moip费用。

addComission($reason, $receiver, $value, $percentageValue, $ratePayer)

$reason : String

$receiver : String

$value : Number

$percentageValue: Boolean

$ratePayer : Boolean

$moip->addComission('Razão do Split',
		'recebedor_secundario',
		'5.00');
$moip->addComission('Razão do Split',
		'recebedor_secundario_2',
		'12.00',
		true,
		true);

addParcel()

addParcel() 方法为XML Moip中的 "<Parcelamentos>" 标签分配值，负责配置将提供给付款人的分期付款选项。

1. $min : 付款人可用的最小分期数。
2. $max : 付款人可用的最大分期数。
3. $rate : 每期利息月利率。
4. $transfer : 如果为 "true"，则定义Moip的默认利息值将由付款人支付。

addParcel($min, $max, $rate, $transfer)

$min : Number

$max : Number

$rate : Number

$transfer : Boolean

$moip->addParcel('2', '4');
$moip->addParcel('5', '7', '1.00');
$moip->addParcel('8', '12', null, true);

setReceiver()

setReceiver() 方法为 "<Recebedor>" 节点的 "<LoginMoIP>" 标签分配值，该标签标识将接收Moip付款的用户。

1. $receiver : 主要收款人的Moip登录名。

setReceiver($receiver)

$receiver : String

$moip->setReceiver('integracao@labs.moip.com.br');

getXML()

getXML() 方法将返回生成的XML，其中包含您配置的所有属性，此方法可以帮助您确切了解将发送给Moip的XML。

getXML()

$moip = new Moip_Api();
$moip->setEnvironment('test');
$moip->setCredential(array(
    'key' => 'ABABABABABABABABABABABABABABABABABABABAB',
    'token' => '01010101010101010101010101010101'
    ));
$moip->setUniqueID(false);
$moip->setValue('100.00');
$moip->setReason('Teste do Moip-PHP');
$moip->validate('Basic');

print_r($moip->getXML());

    //IRÁ? IMPRIMIR
    <?xml version="1.0" encoding="utf-8"?>
    <EnviarInstrucao>
        <InstrucaoUnica>
            <IdProprio></IdProprio>
            <Razao>Teste do Moip-PHP</Razao>
            <Valores>
                <Valor moeda="BRL">100.00</Valor>
            </Valores>
        </InstrucaoUnica>
    </EnviarInstrucao>

send()

send() 方法执行向Moip发送指令，并返回从Moip获得的响应数据。

1. 响应：成功时返回 "true"，发生错误时返回 "false"。
2. 错误：当 "response" 为 "false" 时，总是返回一个消息。
3. xml：当 "response" 为 "true" 时，总是返回 Moip 的响应 XML。

send()

$moip = new Moip_Api();
$moip->setEnvironment('test');
$moip->setCredential(array(
    'key' => 'ABABABABABABABABABABABABABABABABABABABAB',
    'token' => '01010101010101010101010101010101'
    ));
$moip->setUniqueID(false);
$moip->setValue('100.00');
$moip->setReason('Teste do Moip-PHP');
$moip->validate('Basic');

print_r($moip->send());

    //IRÁ? IMPRIMIR
    stdClass Object
    (
        [response] => 1
        [error] =>
        [xml] => <ns1:EnviarInstrucaoUnicaResponse xmlns:ns1="http://www.moip.com.br/ws/alpha/"><Resposta><ID>201209042007216380000000989104</ID><Status>Sucesso</Status><Token>M2C031R2Q0Z9W0Y4Q2S0H0W7E2G1Z6P3E8C0C0W050T01070Y9Y8V9G1F0F4</Token></Resposta></ns1:EnviarInstrucaoUnicaResponse>
    )

getAnswer()

getAnswer() 方法以对象形式返回 Moip 的响应数据。

1. response：当 Moip 的 "<Status>" 返回 "成功" 时返回 "true"，当返回 "失败" 时返回 "false"。
2. 错误：当 "response" 为 "false" 时，总是返回一个消息。
3. token：当 "response" 为 "true" 时，返回生成的支付 TOKEN。
4. payment_url：当 "response" 为 "true" 时，返回为准备将客户重定向到具有支付 TOKEN 的 Moip 结账 URL。

getAnswer()

$moip = new Moip_Api();
$moip->setEnvironment('test');
$moip->setCredential(array(
    'key' => 'ABABABABABABABABABABABABABABABABABABABAB',
    'token' => '01010101010101010101010101010101'
    ));

$moip->setUniqueID(false);
$moip->setValue('100.00');
$moip->setReason('Teste do Moip-PHP');
$moip->validate('Basic');
$moip->send();

print_r($moip->getAnswer());

//IRÁ? IMPRIMIR
stdClass Object
(
    [response] => 1
    [error] =>
    [token] => 92D091R2I0Y9X0E4T2K034L2H2V4H2J6L9R0S0T0K0N0L0T0Y9H879H144O8
    [payment_url] => https://desenvolvedor.moip.com.br/sandbox/Instrucao.do?token=92D091R2I0Y9X0E4T2K034L2H2V4H2J6L9R0S0T0K0N0L0T0Y9H879H144O8
)

queryParcel()

queryParcel() 方法返回一个数组，包含分期付款的信息以及每期的收费金额和相应的总支付金额（模拟利率）。

1. 请求

2. $login：用户的 Moip 登录。

3. $maxParcel：要查询的最大分期付款数。

4. $rate：模拟的利率。

5. $simulatedValue：将要模拟支付的金额。

6. 响应

7. response："true" 表示 Moip 的响应中 "<Status>" 为 "成功"，"false" 表示 "失败"。

8. installment：对应值的分期付款数量。

9. total：总支付金额。

10. rate：分配的利率。

11. value：每期的金额。

queryParcel($login, $maxParcel, $rate, $simulatedValue)

$login：字符串。

$maxParcel：数字。

$rate : Number

$simulatedValue：数字。

    $moip = new Moip_Api();
    $moip->setEnvironment('test');
    $moip->setCredential(array(
        'key' => 'ABABABABABABABABABABABABABABABABABABABAB',
        'token' => '01010101010101010101010101010101'
        ));


    print_r($moip->queryParcel('integracao@labs.moip.com.br', '4', '1.99', '100.00'));


    //IRÁ? IMPRIMIR
    Array
    (
        [response] => 1
        [installment] => Array
            (
                [1] => Array
                    (
                        [total] => 100.00
                        [rate] => 1.99
                        [value] => 100.00
                    )


                [2] => Array
                    (
                        [total] => 103.00
                        [rate] => 1.99
                        [value] => 51.50
                    )


                [3] => Array
                    (
                        [total] => 104.01
                        [rate] => 1.99
                        [value] => 34.67
                    )


                [4] => Array
                    (
                        [total] => 105.04
                        [rate] => 1.99
                        [value] => 26.26
                    )


            )


    )