liveecommerce/pagarme-php

维护者

详细信息

github.com/liveecommerce/pagarme-php

安装: 12 063

依赖者: 0

建议者: 0

安全: 0

星标: 1

关注者: 1

分支: 149


README

这个SDK旨在使其灵活,以便所有人都能使用所有版本的API的所有功能。

您可以通过访问此链接来访问Pagar.me的官方文档。

索引

安装

使用以下命令安装库

composer require pagarme/pagarme-php

配置

要将库包含到您的项目中,只需执行以下操作

<?php
require('vendor/autoload.php');

$pagarme = new PagarMe\Client('SUA_CHAVE_DE_API');

定义自定义头

  1. 如果需要,可以定义自定义HTTP头用于请求。为此,只需在创建Client对象时提供它们即可。
<?php
require('vendor/autoload.php');

$pagarme = new PagarMe\Client(
    'SUA_CHAVE_DE_API',
    ['headers' => ['MEU_HEADER_CUSTOMIZADO' => 'VALOR HEADER CUSTOMIZADO']]
); 

然后,您可以使用该客户端向Pagar.me发送请求,如下所示。

交易

在本节中,将解释如何使用该库在Pagar.me中处理交易。

创建交易

<?php
$transaction = $pagarme->transactions()->create([
    'amount' => 1000,
    'payment_method' => 'credit_card',
    'card_holder_name' => 'Anakin Skywalker',
    'card_cvv' => '123',
    'card_number' => '4242424242424242',
    'card_expiration_date' => '1220',
    'customer' => [
        'external_id' => '1',
        'name' => 'Nome do cliente',
        'type' => 'individual',
        'country' => 'br',
        'documents' => [
          [
            'type' => 'cpf',
            'number' => '00000000000'
          ]
        ],
        'phone_numbers' => [ '+551199999999' ],
        'email' => 'cliente@email.com'
    ],
    'billing' => [
        'name' => 'Nome do pagador',
        'address' => [
          'country' => 'br',
          'street' => 'Avenida Brigadeiro Faria Lima',
          'street_number' => '1811',
          'state' => 'sp',
          'city' => 'Sao Paulo',
          'neighborhood' => 'Jardim Paulistano',
          'zipcode' => '01451001'
        ]
    ],
    'shipping' => [
        'name' => 'Nome de quem receberá o produto',
        'fee' => 1020,
        'delivery_date' => '2018-09-22',
        'expedited' => false,
        'address' => [
          'country' => 'br',
          'street' => 'Avenida Brigadeiro Faria Lima',
          'street_number' => '1811',
          'state' => 'sp',
          'city' => 'Sao Paulo',
          'neighborhood' => 'Jardim Paulistano',
          'zipcode' => '01451001'
        ]
    ],
    'items' => [
        [
          'id' => '1',
          'title' => 'R2D2',
          'unit_price' => 300,
          'quantity' => 1,
          'tangible' => true
        ],
        [
          'id' => '2',
          'title' => 'C-3PO',
          'unit_price' => 700,
          'quantity' => 1,
          'tangible' => true
        ]
    ]
]);

捕获交易

<?php
$capturedTransaction = $pagarme->transactions()->capture([
    'id' => 'ID_OU_TOKEN_DA_TRANSAÇÃO',
    'amount' => VALOR_TOTAL_COM_CENTAVOS
]);

退款交易

<?php
$refundedTransaction = $pagarme->transactions()->refund([
    'id' => 'ID_OU_TOKEN_DA_TRANSAÇÃO',
]);

此功能还支持部分退款或拆分退款。例如

部分退款交易

<?php
$partialRefundedTransaction = $pagarme->transactions()->refund([
    'id' => 'ID_OU_TOKEN_DA_TRANSAÇÃO',
    'amount' => 'VALOR_PARCIAL_DO_ESTORNO',
]);

使用拆分退款交易

<?php
$refundedTransactionWithSplit = $pagarme->transactions()->refund([
    'id' => 'ID_OU_TOKEN_DA_TRANSAÇÃO',
    'amount' => '6153',
    'split_rules' => [
        [
            'id' => 'sr_cj41w9m4d01ta316d02edaqav',
            'amount' => '3000',
            'recipient_id' => 're_cj2wd5ul500d4946do7qtjrvk'
        ],
        [
            'id' => 'sr_cj41w9m4e01tb316dl2f2veyz',
            'amount' => '3153',
            'recipient_id' => 're_cj2wd5u2600fecw6eytgcbkd0',
            'charge_processing_fee' => 'true'
        ]
    ]
]);

返回交易

<?php
$transactions = $pagarme->transactions()->getList();

如果需要,您可以使用参数来过滤此搜索,例如,如果您只想过滤已支付的交易,则可以使用以下代码

<?php
$paidTransactions = $pagarme->transactions()->getList([
    'status' => 'paid'
]);

返回单个交易

<?php
$transactions = $pagarme->transactions()->get([
    'id' => 'ID_DA_TRANSAÇÃO' 
]);

返回交易的应收账款

<?php
$transactionPayables = $pagarme->transactions()->listPayables([
    'id' => 'ID_DA_TRANSAÇÃO'
]);

返回单个交易的应收账款

<?php
$transactionPayable = $pagarme->transactions()->getPayable([
    'transaction_id' => 'ID_DA_TRANSAÇÃO',
    'payable_id' => 'ID_DO_PAYABLE'
]);

返回交易的运营历史

<?php
$transactionOperations = $pagarme->transactions()->listOperations([
    'id' => 'ID_DA_TRANSAÇÃO',
]);

通知客户支付支票

<?php
$transactionPaymentNotify = $pagarme->transactions()->collectPayment([
    'id' => 'ID_DA_TRANSAÇÃO',
    'email' = > 'cliente@email.com'
]);

返回交易事件

<?php
$transactionEvents = $pagarme->transactions()->events([
    'id' => 4262049,
]);

计算分期付款

此路由不是强制使用的。它仅用于计算Pagar.me的分期付款。

为了解释方便,我们将使用以下值

amount: 1000, free_installments: 4, max_installments: 12, interest_rate: 3

free_installments参数决定了无息分期数量。也就是说,如果它被设置为4,则前四个分期不会改变其原始价值。

在此路由中,计算简单利息,计算方法如下

valorTotal = valorDaTransacao * ( 1 + ( taxaDeJuros * numeroDeParcelas ) / 100 )

那么,使用上述值,在第五期,计算如下

valorTotal = 1000 * (1 + (3 * 5) / 100)

因此,第五期的支付金额将是购买总额的15%,总计1150。

如果您想使用此路由,请使用以下代码

<?php
$calculateInstallments = $pagarme->transactions()->calculateInstallments([
    'amount' => 'VALOR_DA_TRANSAÇÃO_EM_CENTAVOS',
    'free_installments' => 'PARCELAS_SEM_JUROS',
    'max_installments' => 'MÁXIMO_DE_PARCELAS',
    'interest_rate' => 'TAXA_DE_JUROS_AO_MÊS'
]);

测试支票支付

<?php
$paidBoleto = $pagarme->transactions()->simulateStatus([
    'id' => 'ID_DA_TRANSAÇÃO',
    'status' => 'paid'
]);

退款

您可以使用以下代码查看您账户中发生的所有退款

<?php
$refunds = $pagarme->refunds()->getList();

如果您愿意,可以使用过滤器仅获取特定交易的退款,例如

<?php
$transactionRefunds = $pagarme->refunds()->getList([
    'transaction_id' => 'ID_DA_TRANSAÇÃO_ESTORNADA'
]);

退货

与退款类似,您还可以查看账户中发生的所有chargebacks。

<?php
$transactionChargebacks = $pagarme->refunds()->getList();

每次您通过我们的API进行请求时,我们都会保存持卡人的信息,以便将来您可以在新的收费中利用这些信息,甚至实现一键购买等功能。

创建卡

<?php
$card = $pagarme->cards()->create([
    'holder_name' => 'Yoda',
    'number' => '4242424242424242',
    'expiration_date' => '1225',
    'cvv' => '123'
]);

返回卡

<?php
$cards = $pagarme->cards()->getList();

如有必要,您可以按某些特定卡片数据筛选,例如,以下代码将获取所有visa品牌的卡片

<?php
$visaCards = $pagarme->cards()->getList([
    'brand' => 'visa'
]);

返回单个卡

<?php
$card = $pagarme->cards()->get([
    'id' => 'ID_DO_CARTÃO'
]);

计划

表示一个客户可以订阅的重复配置。它是定义重复价格、名称和周期的实体

创建计划

<?php
$plan = $pagarme->plans()->create([
    'amount' => '15000',
    'days' => '30',
    'name' => 'The Pro Plan - Platinum - Best ever'
]);

返回计划

<?php
$plans = $pagarme->plans()->getList();

返回单个计划

<?php
$plan = $pagarme->plans()->get(['id' => '123456']);

更新计划

<?php
$updatedPlan = $pagarme->plans()->update([
    'id' => '365403',
    'name' => 'The Pro Plan - Susan',
    'trial_days' => '7',
]);

订阅

创建订阅

<?php
$substription = $pagarme->subscriptions()->create([
    'plan_id' => 123456,
    'payment_method' => 'credit_card',
    'card_number' => '4111111111111111',
    'card_holder_name' => 'UNIX TIME',
    'card_expiration_date' => '0722',
    'card_cvv' => '123',
    'postback_url' => 'http://postbacj.url',
    'customer' => [
        'email' => 'time@unix.com',
        'name' => 'Unix Time',
        'document_number' => '75948706036',
        'address' => [
            'street' => 'Rua de Teste',
            'street_number' => '100',
            'complementary' => 'Apto 666',
            'neighborhood' => 'Bairro de Teste',
            'zipcode' => '11111111'
        ],
        'phone' => [
            'ddd' => '01',
            'number' => '923456780'
        ],
        'sex' => 'other',
        'born_at' => '1970-01-01',
    ],
    'metadata' => [
        'foo' => 'bar'
    ]
]);

使用card_id创建订阅

<?php
// Criando o cartão
$card = $pagarme->cards()->create([
    'holder_name' => 'Yoda',
    'number' => '4242424242424242',
    'expiration_date' => '1225',
    'cvv' => '123'
]);

$substription = $pagarme->subscriptions()->create([
    'plan_id' => 365403,
    'card_id' => $card->id,
    'payment_method' => 'credit_card',
    'postback_url' => 'http://www.pudim.com.br',
    'customer' => [
        'email' => 'time@unix.com',
        'name' => 'Unix Time',
        'document_number' => '75948706036',
        'address' => [
            'street' => 'Rua de Teste',
            'street_number' => '100',
            'complementary' => 'Apto 666',
            'neighborhood' => 'Bairro de Teste',
            'zipcode' => '88370801'
        ],
        'phone' => [
            'ddd' => '01',
            'number' => '923456780'
        ],
        'sex' => 'other',
        'born_at' => '1970-01-01',
    ],
    'metadata' => [
        'foo' => 'bar'
    ]
]);

与订阅拆分

<?php
$substription = $pagarme->subscriptions()->create([
    'plan_id' => 123456,
    'card_id' => 'card_abc123456',
    'payment_method' => 'credit_card',
    'postback_url' => 'http://www.pudim.com.br',
    'customer' => [
        'email' => 'time@unix.com',
        'name' => 'Unix Time',
        'document_number' => '75948706036',
        'address' => [
            'street' => 'Rua de Teste',
            'street_number' => '100',
            'complementary' => 'Apto 666',
            'neighborhood' => 'Bairro de Teste',
            'zipcode' => '88370801'
        ],
        'phone' => [
            'ddd' => '01',
            'number' => '923456780'
        ],
        'sex' => 'other',
        'born_at' => '1970-01-01',
    ],
    'amount' => 10000,
    'split_rules' => [
        [
            'recipient_id' => 're_abc1234abc1234abc1234abc1',
            'percentage' => 20,
            'liable' => true,
            'charge_processing_fee' => true,
        ],
        [
            'recipient_id' => 're_abc1234abc1234abc1234abc1',
            'percentage' => 80,
            'liable' => true,
            'charge_processing_fee' => true,
        ]
    ],
    'metadata' => [
        'foo' => 'bar'
    ]
]);

返回订阅

<?php
$substription = $pagarme->subscriptions()->get([
    'id' => 123456
]);

返回订阅

<?php
$substription = $pagarme->subscriptions()->getList();

如有必要,您可以在搜索中应用过滤器。例如,如果您想获取某个计划的所有订阅,您可以使用以下代码

<?php
$planSubstriptions = $pagarme->subscriptions()->getList([
    'plan_id' => 'ID_DO_PLANO'
]);

更新订阅

<?php
$updatedSubscription = $pagarme->subscriptions()->update([
    'id' => 1234,
    'plan_id' => 4321,
    'payment_method' => 'boleto'
]);

取消订阅

<?php
$canceledSubscription = $pagarme->subscriptions()->cancel([
    'id' => 12345
]);

订阅交易

<?php
$substriptionTransactions = $pagarme->subscriptions()->transactions([
    'subscription_id' => 1245
]);

跳过收款

<?php
$settledCharges = $pagarme->subscriptions()->settleCharges([
    'id' => 12345,
    'charges' => 5
]);

Postbacks

创建交易或订阅时,您可以在请求中传递postback_url参数。这是一个您的系统URL,它将接收有关这些交易/订阅状态变化的每次通知。

要获取有关postbacks的信息,需要以下3个信息:modelmodel_idpostback_id

model:指生成该POSTback的对象。可以填写transactionsubscription

model_id:指生成POSTback的对象的ID,即您想访问POSTbacks的交易或订阅的ID。

postback_id:指特定的通知。对于每个订阅或交易状态的变化,都会生成一个POSTback。对于每个订阅或交易状态的变化,都会生成一个POSTback。对于每个订阅或交易状态的变化,都会生成一个POSTback。对于每个订阅或交易状态的变化,都会生成一个POSTback。每个POSTback可能有多次尝试交付,这些尝试可以通过deliveries字段识别,而尝试的ID以pd_为前缀。应发送到此参数的字段是POSTback的ID,应以po_为前缀。

返回Postbacks

<?php
$postbacks = $pagarme->postbacks()->getList([
    'model' => 'subscription',
    'model_id' => 'ID_DA_ASSINATURA'
]);

返回单个Postback

<?php
$postback = $pagarme->postbacks()->get([
    'model' => 'transaction',
    'model_id' => 'ID_DA_TRANSAÇÃO',
    'postback_id' => 'po_cjlzhftd2006xg573fwelfg9y'
]);

重发POSTback

<?php
$postbackRedeliver = $pagarme->postbacks()->redeliver([
    'model' => 'subscription',
    'model_id' => 'ID_DA_ASSINATURA',
    'postback_id' => 'po_cjlzhftd2006xg573fwelfg9y'
]);

验证POSTback请求

<?php
$postbackPayload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_HUB_SIGNATURE'];
$postbackIsValid = $pagarme->postbacks()->validate($postbackPayload, $signature);

注意:上述代码仅作为示例,以说明验证过程。我们建议您使用由库或框架提供的工具以更合适的方式获取这些信息。

主要收款人余额

要了解您的账户余额,您可以使用以下代码

<?php
$balance = $pagarme->balances()->get();

余额操作

使用此对象,您可以跟踪Pagar.me账户中发生的所有财务变动。

操作历史

<?php
$balanceOperations = $pagarme->balanceOperations()->getList();

如有必要,您可以通过参数传递过滤器,例如

<?php
$balanceOperations = $pagarme->balanceOperations()->getList([
    'status' => 'available'
]);

特定操作的历史

<?php
$balanceOperation = $pagarme->balanceOperations()->get([
    'id' => 'BALANCE_OPERATION_ID'
]);

应收账款

包含应收款数据的对象。应收款(应付账款)在交易支付后自动生成。对于交易的每个分期都会生成一个应收款,在分割的情况下,应收款也可以按收款人分割。

返回应收账款

<?php
$payables = $pagarme->payables()->getList();

如果需要,您可以在搜索应付账款时应用过滤器,例如,您可以检索所有与某笔交易相关的应付账款。

<?php
$transactionPayables = $pagarme->payables()->getList([
    'transaction_id' => 'ID_DA_TRANSAÇÃO'
]);

返回单个应收账款

<?php
$payable = $pagarme->payables()->get([
    'id' => 'ID_DO_PAYABLE'
]);

转账

转账代表您账户的提款。

创建转账

<?php
$transfer = $pagarme->transfers()->create([
    'amount' => 1000,
    'recipient_id' => 're_cjeptpdyg03u3cb6elj68p5ej'
]);

返回转账

<?php
$transfers = $pagarme->transfers()->getList();

如果需要,您可以在搜索中应用过滤器,例如。

<?php
$recipientTransfers = $pagarme->transfers()->getList([
    'recipient_id' => 'ID_DO_RECEBEDOR'
]);

返回单个转账

<?php
$transfer = $pagarme->transfers()->get([
    'id' => 'ID_DA_TRANSFERÊNCIA'
]);

取消转账

<?php
$canceledTransfer = $pagarme->transfers()->cancel([
    'id' => 'ID_DA_TRANSFERÊNCIA'
]);

预付款

要了解什么是预付款,您必须访问此链接:链接

创建预付款

<?php
$anticipation = $pagarme->bulkAnticipations()->create([
    'recipient_id' => 're_cjeptpdyg03u3cb6elj68p5ej',
    'build' => 'true',
    'payment_date' => '1536883200000',
    'requested_amount' => '300000',
    'timeframe' => 'start'
]);

获取预付款限制

<?php
$anticipationLimits = $pagarme->bulkAnticipations()->getLimits([
    'recipient_id' => 'ID_DO_RECEBEDOR',
    'payment_date' => '1536883200000',
    'timeframe' => 'start'
]);

确认预付款构建

<?php
$confirmedAnticipation = $pagarme->bulkAnticipations()->confirm([
    'recipient_id' => 'ID_DO_RECEBEDOR',
    'bulk_anticipation_id' => 'ID_DA_ANTECIPAÇÃO',
]);

取消挂起的预付款

<?php
$canceledAnticipation = $pagarme->bulkAnticipations()->cancel([
    'recipient_id' => 'ID_DO_RECEBEDOR',
    'bulk_anticipation_id' => 'ID_DA_ANTECIPAÇÃO',
]);

删除正在构建的预付款

<?php
$deletedAnticipation = $pagarme->bulkAnticipations()->delete([
    'recipient_id' => 'ID_DO_RECEBEDOR',
    'bulk_anticipation_id' => 'ID_DA_ANTECIPAÇÃO',
]);

返回预付款

<?php
$anticipations = $pagarme->bulkAnticipations()->getList([
    'recipient_id' => 'ID_DO_RECEBEDOR'
]);

如果需要,您可以在搜索中应用过滤器,例如,通过预付款金额进行搜索。

<?php
$anticipations = $pagarme->bulkAnticipations()->getList([
    'recipient_id' => 'ID_DO_RECEBEDOR',
    'amount' => 'VALOR_ANTECIPADO'
]);

银行账户

银行账户标识了未来付款的款项将发送到哪个账户。

创建银行账户

<?php
$bankAccount = $pagarme->bankAccounts()->create([
    'bank_code' => '341',
    'agencia' => '0932',
    'agencia_dv' => '5',
    'conta' => '58054',
    'conta_dv' => '1',
    'document_number' => '26268738888',
    'legal_name' => 'API BANK ACCOUNT'
]);

返回银行账户

<?php
$bankAccount = $pagarme->bankAccounts()->get([
    'id' => 'ID_DA_CONTA_BANCÁRIA'
]);

返回银行账户

<?php
$bankAccounts = $pagarme->bankAccounts()->getList();

如果您想,您可以在搜索银行账户时应用过滤器,例如,通过银行代码进行筛选。

<?php
$bankAccounts = $pagarme->bankAccounts()->getList([
    'bank_code' => '341'
]);

收款人

要将交易分配给多个实体,每个实体都需要有一个收款人。收款人包含将款项发送到的银行账户信息,以及其他信息,例如,它能够提前多少款项,或何时自动提取您的账户款项。

创建收款人

<?php
$recipient = $pagarme->recipients()->create([
    'anticipatable_volume_percentage' => '85', 
    'automatic_anticipation_enabled' => 'true', 
    'bank_account_id' => '17899179', 
    'transfer_day' => '5', 
    'transfer_enabled' => 'true', 
    'transfer_interval' => 'weekly'
]);

返回收款人

<?php
$recipients = $pagarme->recipients()->getList();

如果需要,您可以在搜索中应用过滤器。例如,如果您想返回所有已启用转账功能的收款人,您可以使用此代码。

<?php
$transferEnabledRecipients = $pagarme->recipients()->getList([
    'transfer_enabled' => true
]);

返回单个收款人

<?php
$recipient = $pagarme->recipients()->get([
    'id' => 'ID_DO_RECEBEDOR'
]);

更新收款人

<?php
$updatedRecipient = $pagarme->recipients()->update([
    'id' => 'ID_DO_RECEBEDOR',
    'anticipatable_volume_percentage' => 80,
    'transfer_day' => 4
]);

收款人余额

<?php
$recipientBalance = $pagarme->recipients()->getBalance([
    'recipient_id' => 'ID_DO_RECEBEDOR',
]);

收款人余额操作

<?php
$recipientBalanceOperations = $pagarme->recipients()->listBalanceOperation([
    'recipient_id' => 'ID_DO_RECEBEDOR'
]);

收款人特定余额操作

<?php
$recipientBalanceOperation = $pagarme->recipients()->getBalanceOperation([
    'recipient_id' => 'ID_DO_RECEBEDOR',
    'balance_operation_id' => 'ID_DA_OPERAÇÃO'
]);

客户

客户代表您商店或业务的使用者。该对象包含有关他们的信息,如姓名、电子邮件和电话,以及其他字段。

创建客户

<?php
$customer = $pagarme->customers()->create([
    'external_id' => '#123456789',
    'name' => 'João das Neves',
    'type' => 'individual',
    'country' => 'br',
    'email' => 'joaoneves@norte.com',
    'documents' => [
      [
        'type' => 'cpf',
        'number' => '11111111111'
      ]
    ],
    'phone_numbers' => [
      '+5511999999999',
      '+5511888888888'
    ],
    'birthday' => '1985-01-01'
]);

返回客户

<?php
$customers = $pagarme->customers()->getList();

返回单个客户

<?php
$customer = $pagarme->customers()->get([
    'id' => 'ID_DO_CLIENTE'
]);

支付链接

创建支付链接

<?php
$paymentLink = $pagarme->paymentLinks()->create([
    'amount' => 10000,
    'items' => [
        [
            'id' => '1',
            'title' => "Fighter's Sword",
            'unit_price' => 4000,
            'quantity' => 1,
            'tangible' => true,
            'category' => 'weapon',
            'venue' => 'A Link To The Past',
            'date' => '1991-11-21'
        ],
        [
            'id' => '2',
            'title' => 'Kokiri Sword',
            'unit_price' => 6000,
            'quantity' => 1,
            'tangible' => true,
            'category' => 'weapon',
            'venue' => "Majora's Mask",
            'date' => '2000-04-27'
        ],
    ],
    'payment_config' => [
        'boleto' => [
            'enabled' => true,
            'expires_in' => 20
        ],
        'credit_card' => [
            'enabled' => true,
            'free_installments' => 4,
            'interest_rate' => 25,
            'max_installments' => 12
        ],
        'default_payment_method' => 'boleto'
    ],
    'max_orders' => 1,
    'expires_in' => 60
]);

返回支付链接

<?php
$paymentLinks = $pagarme->paymentLinks()->getList();

返回单个支付链接

<?php
$paymentLink = $pagarme->paymentLinks()->get([
    'id' => 'ID_DO_LINK_DE_PAGAMENTO'
]);

取消支付链接

<?php
$canceledPaymentLink = $pagarme->paymentLinks()->cancel([
    'id' => 'ID_DO_LINK_DE_PAGAMENTO'
]);

高级搜索(Elasticsearch)

执行搜索

<?php
$search = $pagarme->search()->get([                
    "type" => "transaction",
    "query" => [
        "query" => [
            "terms" => [
                "items.id" => [8, 9] // Busca transações com itens de ID 8 e 9
            ]
        ]
    ]
]);