README

PHP 对 Pagar.me API 的集成

安装和配置

要使用此库，您可以通过 composer 安装它，命令如下

composer require 'pagarme/pagarme-php-v3.7.10'

然后，只需将其导入到您的文件中并实例化 PagarMe 对象即可

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

$apiKey = 'ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0';
$pagarMe =  new \PagarMe\Sdk\PagarMe($apiKey);

注意：这里列出的所有示例都使用上面实例化的 $pagarMe 对象。

使用 SDK

参数 page 和 count

$page 表示页面编号，$count 表示记录数量。因此，如果您使用 $page = 2 和 $count = 20 来查找对象，则将返回最近的 20~40 个对象。

交易

本节将解释如何使用此库在 Pagar.me 中使用交易。

创建交易

<?php
$amount = 1000;
$installments = 1;
$capture = true;
$postbackUrl = 'http://requestb.in/pkt7pgpk';
$metadata = ['idProduto' => 13933139];

$customer = new \PagarMe\Sdk\Customer\Customer(
    [
        'name' => 'John Dove',
        'email' => 'john@site.com',
        'document_number' => '09130141095',
        'address' => [
            'street'        => 'rua teste',
            'street_number' => 42,
            'neighborhood'  => 'centro',
            'zipcode'       => '01227200',
            'complementary' => 'Apto 42',
            'city'          => 'São Paulo',
            'state'         => 'SP',
            'country'       => 'Brasil'
        ],
        'phone' => [
            'ddd'    => "15",
            'number' =>"987523421"
        ],
        'born_at' => '15021994',
        'sex' => 'M'
    ]
);

$card = $pagarMe->card()->create(
    '4242424242424242',
    'JOHN DOVE',
    '0722'
);

$recipient1 = $pagarMe->recipient()->get('re_civb4p9l7004xbm6dhsetkpj8');
$recipient2 = $pagarMe->recipient()->get('re_civb4o6zr003u3m6e8dezzja6');

$splitRule1 = $pagarMe->splitRule()->percentageRule(
    40,
    $recipient1,
    true, // liable
    true, // chargeProcessingFee,
    true // chargeReminder
);

$splitRule2 = $pagarMe->splitRule()->percentageRule(
    60,
    $recipient,
    true, // liable
    true, // chargeProcessingFee,
    false // chargeReminder
);

$splitrules = new PagarMe\Sdk\SplitRule\SplitRuleCollection();
$splitrules[0] = $splitRule1;
$splitrules[1] = $splitRule2;

// Credit Card Transaction
$transaction = $pagarMe->transaction()->creditCardTransaction(
    $amount,
    $card,
    $customer,
    $installments,
    $capture,
    $postbackUrl,
    $metadata,
    ["split_rules" => $splitrules]
);

// Boleto Transaction
$transaction2 = $pagarMe->transaction()->boletoTransaction(
    $amount,
    $customer,
    $postbackUrl,
    $metadata,
    ["split_rules" => $splitrules]
);

捕获交易

<?php
$transaction = $pagarMe->transaction()->get(4752390);
$amountToCapture = 1000;
$metadata = ['idProduto' => '123']; // Parâmetro opcional

$splitRules = new \PagarMe\Sdk\SplitRule\SplitRuleCollection(); // Parâmetro opcional

$recipient1 = $pagarMe->recipient()->get('re_cjqgt03fv02bq4k6e3xbxxbia');
$recipient2 = $pagarMe->recipient()->get('re_cjm0lfmy3001zaq6espflawv2');

$splitRule1 = $pagarMe->splitRule()->percentageRule(
    40,
    $recipient1,
    true, // liable
    true, // chargeProcessingFee,
    true // chargeReminder
);

$splitRule2 = $pagarMe->splitRule()->percentageRule(
    60,
    $recipient2,
    true, // liable
    true, // chargeProcessingFee,
    false // chargeReminder
);

$splitRules[] = $splitRule1;
$splitRules[] = $splitRule2;

$pagarMe->transaction()->capture($transaction, $amountToCapture, $metadata, $splitRules);

退款交易

<?php
$transaction = $pagarMe->transaction()->get("1627830");

// Credit Card Refund
$transaction = $pagarMe->transaction()->creditCardRefund($transaction);

// Boleto Refund
$bankAccount = $pagarMe->bankAccount()->create(
  '341',
  '0932',
  '58054',
  '5',
  '26268738888',
  'API BANK ACCOUNT',
  '1'
);

$transaction = $pagarMe->transaction()->boletoRefund($transaciton, $bankAccount);

此功能也适用于部分退款或分割退款。例如

部分退款交易

<?php
$transaction = $pagarMe->transaction()->get("1627835");
$amountRefunded = 20000;

// Credit card
$transaction = $pagarMe->transaction()->creditCardRefund(
    $transaction,
    $amountRefunded
);

// Boleto
$transaction = $pagarMe->transaction()->boletoRefund(
    $transaciton,
    $bankAccount,
    $amountRefunded
);

分割退款交易

Não possui essa feature.

返回交易

<?php
$transactionList = $pagarMe->transaction()->getList($page, $count);

返回单个交易

<?php
$transactionId = "1627864";
$transaction = $pagarMe->transaction()->get($transactionId);

返回交易应收款

Não possui essa feature.

返回单个交易应收款

Não possui essa feature.

返回交易操作历史

Não possui essa feature.

通知客户支付支票

Não possui essa feature.

返回交易事件

$transactionId = "1627864";
$transaction = $pagarMe->transaction()->get($transactionId);
$transactionEvents = $pagarMe->transaction()->events($transaction);

计算分期付款

此路由不是必需的，只是计算 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
$amount = 10000;
$rate = 13;
$rateFreeInstallments = 1;
$maxInstallments = 12;
$installments = $pagarMe->calculation()->calculateInstallmentsAmount(
    $amount,
    $rate,
    $rateFreeInstallments,
    $maxInstallments
);

$totalAmount = $installments[2]["total_amount"];
$installmentAmount = $installments[2]["installment_amount"];

测试支票支付

<?php
$transaction = $pagarMe->transaction()->payTransaction(1627871);

退款

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

Não possui essa feature.

信用卡

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

创建信用卡

<?php
//Create with card data
$cardNumber = '4242424242424242';
$cardHolderName = 'Aardvark Silva';
$cardExpirationDate = '1122';
$cardCvv = 123;
$card = $pagarMe->card()->create(
    $cardNumber,
    $cardHolderName,
    $cardExpirationDate,
    $cardCvv
);

//Create with card_hash
$card = $pagarMe->card()->createFromHash('card_hash');

返回信用卡

Não possui essa feature.

返回单个信用卡

$cardId = 'card_cj428xxsx01dt3f6dvre6belx';
$card = $pagarMe->card()->get(cardId);

计划

表示客户可以订阅的重复配置。这是定义重复价格、名称和频率的实体。

创建计划

$amount = 15000;
$days = 30;
$name = 'The Pro Plan - Platinum  - Best Ever';
$trialDays = 0;
$paymentsMethods = ['credit_card', 'boleto'];
$charges = null;
$installments = 1;

$plan = $pagarMe->plan()->create(
    $amount,
    $days,
    $name,
    $trialDays,
    $paymentsMethods,
    $charges,
    $installments
);

返回计划

<?php
$plans = $pagarMe->plan()->getList($page, $count);

返回单个计划

<?php
$plan = $pagarMe->plan()->get(164526);

更新计划

<?php
$oldPlan = $pagarMe->plan()->get(163871);
$oldPlan->setName('The Pro Plan - Susan');
$oldPlan->setTrialDays('7');

$newPlan = $pagarMe->plan()->update($oldPlan);

<?php
$planId = 136869;
$plan = $pagarMe->plan()->get($planId);

$cardId = 'card_cizri9czn00csfi6e1ygzw9vz';
$card = $pagarMe->card()->get($cardId);
$metadata = ['idAssinatura' => '123'];
$extraAttributtes = [
    'soft_descriptor' => 'Minha empresa'
];

$postbackUrl = 'http://requestb.in/zyn5obzy';

$customer = new \PagarMe\Sdk\Customer\Customer(
    [
        'name' => 'John Dove',
        'email' => 'john@site.com',
        'document_number' => '09130141095',
        'address' => new \PagarMe\Sdk\Customer\Address([
            'street'        => 'rua teste',
            'street_number' => 42,
            'neighborhood'  => 'centro',
            'zipcode'       => '01227200',
            'complementary' => 'Apto 42',
            'city'          => 'São Paulo',
            'state'         => 'SP',
            'country'       => 'Brasil'
        ]),
        'phone' => new \PagarMe\Sdk\Customer\Phone([
            'ddd'    => "15",
            'number' =>"987523421"
        ]),
        'born_at' => '15021994',
        'sex' => 'M'
    ]
);

// Credit card subscription
$subscription = $pagarMe->subscription()->createCardSubscription(
    $plan,
    $card,
    $customer,
    $postbackUrl,
    $metadata,
    $extraAttributes
);

// Boleto Subscription
$subscription = $pagarMe->subscription()->createBoletoSubscription(
    $transaction,
    $customer,
    $postbackUrl,
    $metadata,
    $extraAttributtes
);

订阅分割

<?php
$planId = 136869;
$plan = $pagarMe->plan()->get($planId);

$cardId = 'card_cizri9czn00csfi6e1ygzw9vz';
$card = $pagarMe->card()->get($cardId);
$metadata = ['idAssinatura' => '123'];

$postbackUrl = 'http://requestb.in/zyn5obzy';

$customer = new \PagarMe\Sdk\Customer\Customer(
    [
        'name' => 'John Dove',
        'email' => 'john@site.com',
        'document_number' => '09130141095',
        'address' => new \PagarMe\Sdk\Customer\Address([
            'street'        => 'rua teste',
            'street_number' => 42,
            'neighborhood'  => 'centro',
            'zipcode'       => '01227200',
            'complementary' => 'Apto 42',
            'city'          => 'São Paulo',
            'state'         => 'SP',
            'country'       => 'Brasil'
        ]),
        'phone' => new \PagarMe\Sdk\Customer\Phone([
            'ddd'    => "15",
            'number' =>"987523421"
        ]),
        'born_at' => '15021994',
        'sex' => 'M'
    ]
);

$splitRules = new \PagarMe\Sdk\SplitRule\SplitRuleCollection();

$recipient1 = $pagarMe->recipient()->get('re_cjqgt03fv02bq4k6e3xbxxbia');
$recipient2 = $pagarMe->recipient()->get('re_cjm0lfmy3001zaq6espflawv2');

$splitRule1 = $pagarMe->splitRule()->percentageRule(
    40,
    $recipient1,
    true, // liable
    true, // chargeProcessingFee,
    true // chargeReminder
);

$splitRule2 = $pagarMe->splitRule()->percentageRule(
    60,
    $recipient2,
    true, // liable
    true, // chargeProcessingFee,
    false // chargeReminder
);

$splitRules[] = $splitRule1;
$splitRules[] = $splitRule2;


// Credit card subscription
$subscription = $pagarMe->subscription()->createCardSubscription(
    $plan,
    $card,
    $customer,
    $postbackUrl,
    $metadata,
    ['split_rules' => $splitRules]
);

// Boleto Subscription
$subscription = $pagarMe->subscription()->createBoletoSubscription(
    $transaction,
    $customer,
    $postbackUrl,
    $metadata,
    ['split_rules' => $splitRules]
);

返回订阅

<?php
$subscription = $pagarMe->subscription()->get(205881);

返回订阅

<?php
$subscriptions = $pagarMe->subscription()->getList($page, $count);

更新订阅

<?php
$subscription = $pagarMe->subscription()->get(184577);
$newPlan = $pagarMe->plan()->get(166234);
$subscription->setPlan($newPlan);
$subscription->setPaymentMethod('credit_card');
$card = $pagarMe->card()->get('card_cj41mpuhc01bb3f6d8exeo072');
$subscription->setCard($card);

$updatedSubscription = $pagarMe->subscription()->update($subscription);

取消订阅

<?php
$subscriptionId = 205880;
$subscription = $pagarMe->subscription()->get($subscriptionId);
$subscription = $pagarMe->subscription()->cancel($subscription);

订阅交易

<?php
$subscriptionId = 205840;
$subscription = $pagarMe->subscription()->get($subscriptionId);
$transactions = $pagarMe->subscription()->transactions($subscription);

跳过收款

Não possui essa feature.

Postbacks

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

要获取有关postbacks的信息，需要3个信息，它们是：model、model_id和postback_id。

model：指的是产生该POSTback的对象。可以填写transaction或subscription的值。

model_id：指的是产生POSTback的对象的ID，即您想要访问POSTbacks的交易或订阅的ID。

postback_id：指的是特定的通知。对于每个订阅或交易的每个状态更改，都会生成一个POSTback。每个POSTback可以有几个交付尝试，这些尝试可以通过deliveries字段识别，而尝试的ID具有pd_前缀。在此参数中应发送的字段是POSTback的ID，它应通过po_前缀进行识别。

返回 postbacks

$transactionId = 1159049;
$transaction = $pagarMe->transaction()->get(transactionId);
$postbacks = $pagarMe->postback()->getList($transaction);

返回单个 postback

<?php
$transactionId = 1159049;
$transaction = $pagarMe->transaction()->get($transactionId);

$postbackId = 'po_ciat6ssga0022k06ng8vxg';
$postbacks = $pagarMe->postback()->get(
    $transaction,
    $postbackId
);

重新发送一个POSTback

<?php
$transactionId = 1662527;
$transaction = $pagarMe->transaction()->get($transactionId);

$postbackId = 'po_cj4haa8l4131bpi73glgzbnpp';
$postbacks = $pagarMe->postback()->redeliver(
    $transaction,
    $postbackId
);

验证POSTback请求

<?php
$postbackBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_HUB_SIGNATURE'];

if ($pagarMe->postback()->validateRequest($postbackBody, $signature) {
    echo "POSTback válido";
} else {
    echo "POSTback inválido";
}

注意：上面的代码仅作为示例，以展示验证过程。我们建议您使用由库或框架提供的工具来以更合适的方式恢复这些信息。

主要收款人余额

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

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

余额操作

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

操作历史记录

<?php
$operationList = $pagarMe->balanceOperation()->getList();

特定操作的历史记录

$operation = $pagarme->balanceOperation()->get(4861);

应收款

包含应收款数据的对象。应收款（应付款）在交易支付后自动生成。每个交易的分期都会生成一个应收款，也可以按收款人（如果进行了分割）进行分割。

返回应收款

<?php
$payables = $pagarMe->payable()->getList($page, $count);

返回单个应收款

<?php
$payable = $pagarMe->payable()->get("573310");

转账

转账代表从您的账户中提取资金。

创建转账

<?php
$amount = 10000;
$recipient = $pagarMe->recipient()->get('re_citkg218g00hl8q6dh1pr5mld');

$transfer = $pagarMe->transfer()->create(
    $amount,
    $recipient
);

返回转账

<?php
$transfers = $pagarMe->transfer()->getList($page, $count)

返回单个转账

<?php
$transfer = $pagarMe->transfer()->get("16264");

取消转账

<?php
$transfer = $pagarMe->transfer()->get("16264");
$canceledTransfer = $pagarMe->transfer()->cancel($transfer);

提前付款

要了解什么是提前支付，您必须访问此链接。

创建提前付款

<?php
$recipientId = "re_ciu4jif1j007td56dsm17yew9";
$recipient = new \PagarMe\Sdk\Recipient\Recipient([
    "id" => $recipientId
]);

$date = new \DateTime();
$date->add(new \DateInterval("P10D"));
$timeframe = 'end';
$requestedAmount = 13000;
$build = true;
$anticipation = $pagarMe->bulkAnticipation()->create(
    $recipient,
    $date,
    $timeframe,
    $requestedAmount,
    $build
);

获取提前付款限额

<?php
$recipientId = "re_ciu4jif1j007td56dsm17yew9";
$recipient = new \PagarMe\Sdk\Recipient\Recipient([
    "id" => recipientId
]);

$paymentDate = new \DateTime();
$paymentDate->add(new \DateInterval("P10D"));
$timeframe = 'end';
$limits = $pagarMe->bulkAnticipation()->limits(
    $recipient,
    $paymentDate,
    $timeframe
);

确认提前付款构建

<?php
$recipient = new \PagarMe\Sdk\Recipient\Recipient([
    "id" => "re_ciu4jif1j007td56dsm17yew9"
]);

$anticipation = new PagarMe\Sdk\BulkAnticipation\BulkAnticipation([
    "id" => "ba_cj3uppown001gvm6dqgmjw2ce"
]);

$anticipation = $pagarMe->bulkAnticipation()->confirm(
    $recipient,
    $anticipation
);

取消待定的提前付款

<?php
$recipient = new \PagarMe\Sdk\Recipient\Recipient([
    "id" => "re_ciu4jif1j007td56dsm17yew9"
]);

$anticipation = new PagarMe\Sdk\BulkAnticipation\BulkAnticipation([
    "id" => "ba_cj3ur2rpl002bpn6ektsnc9lu"
]);

$anticipation = $pagarMe->bulkAnticipation()->cancel(
    $recipient,
    $anticipation
);

删除正在构建的提前付款

<?php
$recipient = new \PagarMe\Sdk\Recipient\Recipient([
    "id" => "re_ciu4jif1j007td56dsm17yew9"
]);

$anticipation = new PagarMe\Sdk\BulkAnticipation\BulkAnticipation([
    "id" => "ba_cj3us6nal0022v86daxfamp4t"
]);

$anticipation = $pagarMe->bulkAnticipation()->delete(
    $recipient,
    $anticipation
);

返回提前付款

<?php
$recipietId = "re_ciu4jif1j007td56dsm17yew9";
$page = 1;
$count = 50;
$recipient = new \PagarMe\Sdk\Recipient\Recipient([
    "id" => $recipientId
]);
$anticipationList = $pagarMe->bulkAnticipation()->getList(
    $recipient,
    $page,
    $count
);

银行账户

银行账户标识了未来付款的汇款目的地。

创建银行账户

<?php
$bankCode = '341';
$agenciaNumber = '0932';
$accountNumber = '58054';
$accountDigit = '5';
$documentNumber = '26268738888';
$legalName = 'Conta Teste 2';
$agenciaDigit = '1';
$bankAccount = $pagarMe->bankAccount()->create(
    $bankCode,
    $agenciaNumber,
    $accountNumber,
    $accountDigit,
    $documentNumber,
    $legalName,
    $agenciaDigit
);

返回单个银行账户

<?php
$bankAccountId = 17411339;
$bankAccount = $pagarMe->bankAccount()->get($bankAccountId);

返回银行账户

<?php
$bankAccounts = $pagarMe->bankAccount()->getList($page, $count);

收款人

为了将交易分配给多个实体，每个实体都需要一个收款人。收款人包含收款人银行账户的信息，并具有其他信息，以了解它可以提前多少，或者何时自动提取您的账户资金。

创建收款人

<?php
$bankAccount = new \PagarMe\Sdk\BankAccount\BankAccount([
    "id" => 17490076
]);

$transferInterval = "monthly";
$transferDay = 13;
$transferEnabled = true;
$automaticAnticipationEnabled = true;
$anticipatableVolumePercentage = 42;
$recipient = $pagarMe->recipient()->create(
    $bankAccount,
    $transferInterval,
    $transferDay,
    $transferEnabled,
    $automaticAnticipationEnabled,
    $anticipatableVolumePercentage
);

返回收款人

<?php
$recipients = $pagarMe->recipient()->getList($page, $count);

返回单个收款人

<?php
$recipientId = "re_cj3g1cml000e75f6ehjnpsl9y";
$recipient = $pagarMe->recipient()->get($recipientId);

更新收款人

<?php
$recipientId = "re_ciu4jif1j007td56dsm17yew9";
$recipient = new \PagarMe\Sdk\Recipient\Recipient([
    "id" => $recipientId,
    "anticipatable_volume_percentage" => "50",
    "transfer_enabled" => true,
    "transfer_interval" => "monthly",
    "transfer_day" => 15,
    "bank_account" => new \PagarMe\Sdk\BankAccount\BankAccount([
        "id" => "17492906"
    ])
]);

$updatedRecipient = $pagarMe->recipient()->update(
    $recipient
);

收款人余额

<?php
$recipientId = "re_cj3g1cml000e75f6ehjnpsl9y";
$recipient = $pagarMe->recipient()->get($recipientId);
$balance = $pagarMe->recipient()->balance($recipient);

收款人余额操作

<?php
$recipientId = "re_cj3g1cml000e75f6ehjnpsl9y";
$recipient = $pagarMe->recipient()->get($recipientId);
$balance = $pagarMe->recipient()->balanceOperations($recipient, $page, $count);

收款人特定余额操作

<?php
$recipientId = "re_ciu4jif1j007td56dsm17yew9";
$recipient = $pagarMe->recipient()->get($recipientId);
$balanceOperationId = 2043993;
$operation = $pagarMe->recipient()->balanceOperation($recipient, $balanceOperationId);

客户

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

创建客户

<?php
$customer = $pagarMe->customer()->create(
    'John Dove',
    'john@site.com',
    '09130141095',
    /** @var $address \PagarMe\Sdk\Customer\Address */
    $address,
    /** @var $phone \PagarMe\Sdk\Customer\Phone */
    $phone,
    '15021994',
    'M'
);

返回客户

<?php
$customerList = $pagarMe->customer()->getList();

返回单个客户

<?php
$customer = $pagarme->customer()->get(11222);

支持

如果您有任何问题或建议，请在此处提交问题。

贡献

在向我们发送贡献之前，请先查看我们的贡献指南。

rededecisao / pagarme-php

维护者

详细信息

README

目录

安装和配置

使用 SDK

参数 page 和 count

交易

创建交易

捕获交易

退款交易

部分退款交易

分割退款交易

返回交易

返回单个交易

返回交易应收款

返回单个交易应收款

返回交易操作历史

通知客户支付支票

返回交易事件

计算分期付款

测试支票支付

退款

信用卡

创建信用卡

返回信用卡

返回单个信用卡

计划

创建计划

返回计划

返回单个计划

更新计划

订阅

创建订阅

订阅分割

返回订阅

返回订阅

更新订阅

取消订阅

订阅交易

跳过收款

Postbacks

返回 postbacks

返回单个 postback

重新发送一个POSTback

验证POSTback请求

主要收款人余额

余额操作

操作历史记录

特定操作的历史记录

应收款

返回应收款

返回单个应收款

转账

创建转账

返回转账

返回单个转账

取消转账

提前付款

创建提前付款

获取提前付款限额

确认提前付款构建

取消待定的提前付款

删除正在构建的提前付款

返回提前付款

银行账户

创建银行账户

返回单个银行账户

返回银行账户

收款人

创建收款人

返回收款人

返回单个收款人

更新收款人

收款人余额

收款人余额操作

收款人特定余额操作

客户

创建客户