matheuscmpm/pagarme-php

4.0.6 2023-07-27 12:09 UTC

This package is auto-updated.

Last update: 2024-09-27 14:52:02 UTC


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',
]);

此功能还支持部分撤销或使用split的撤销。例如

部分撤销交易

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

使用split撤销交易

<?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'
]);

争议

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

<?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'
    ]
]);

订阅split

<?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,即您要访问POSTback的交易的ID或订阅的ID。

postback_id:指特定的通知。对于每个订阅或交易的每次状态变更,都会生成一个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'
]);