README

PHP 对 Pagar.me API 的集成

索引

安装和配置
使用 SDK
支持
许可证
贡献

安装和配置

要使用此库，您可以通过 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或订阅的ID。

postback_id：指的是特定的通知。对于每个订阅或交易的每个状态变更，都会生成一个POSTback。每个POSTback可以有多个交付尝试，这些尝试可以通过字段deliveries识别，这些尝试的ID以pd_为前缀。应发送到该参数的字段是POSTback的ID，该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);

支持

如果您有任何问题或建议，请在此处创建一个问题。

贡献

在发送您的贡献之前，请参阅我们的贡献指南。

eaglesistemas / pagarme-php

维护者

详细信息

README

索引

安装和配置

使用 SDK

page 和 count 参数

交易

创建交易

捕获交易

退款交易

部分退款交易

分割退款交易

返回交易

返回单个交易

返回交易的应收款

返回单个交易的应收款

返回交易操作历史

通知客户支付票据

返回交易事件

计算分期付款

测试支付票据

退款

信用卡

创建信用卡

返回信用卡

返回单个信用卡

计划

创建计划

返回计划

返回单个计划

更新计划

订阅

创建订阅

订阅分割

返回订阅

返回订阅

更新订阅

取消订阅

订阅交易

跳过收款

Postbacks

返回 postbacks

返回单个 postback

重新发送POSTback

验证POSTback请求

主要收款人余额

余额操作

操作历史

特定操作历史

应收款

返回应收款

返回单个应收款

转账

创建转账

返回转账

返回单个转账

取消转账

预付款

创建预付款

获取预付款限制

确认预付款构建

取消待处理的预付款

删除预付款构建

返回预付款

银行账户

创建银行账户

返回银行账户

返回银行账户

收款人

创建收款人

返回收款人

返回单个收款人

更新收款人

收款人余额

收款人余额操作

收款人特定余额操作

客户

创建客户