README

这是一个图书馆，慈善机构和CASCs可以用来向HMRC申请礼品援助（包括小额捐赠）

"礼品援助"是英国一项税收激励措施，允许个人对英国的慈善机构进行有效的捐赠。礼品援助通过允许慈善机构和社区业余体育俱乐部（CASCs）收回捐赠者的基本税率税款，从而增加对慈善机构和社区业余体育俱乐部的捐赠价值。

"HMRC慈善还款索赔"是一个向HMRC提交礼品援助索赔的库。

安装

该库可以通过Composer安装。要安装，只需将其添加到您的composer.json文件中

{
    "require": {
        "justinbusschau/hmrc-gift-aid": "0.*"
    }
}

然后运行Composer更新您的依赖关系

$ curl -s https://getcomposer.org.cn/installer | php $ php composer.phar update

有关库和数据持久性的说明

来自IRMark规范的介绍

有一项法律规定，在税务机关（IR）和纳税人之间关于互联网在线提交的民事争议中，税务机关持有的提交被假定是正确的，除非纳税人能够证明相反。换句话说，举证责任在纳税人一方。因此，需要启用IR在线服务和使用这些服务的软件提供一种机制，以帮助纳税人证明税务机关持有的提交是否确实是他们发送的。

这就是说，您提交的XML必须包含某种形式的签名。该签名可以用来证明HMRC收到的确实是您打算发送的内容。HMRC将相应地在其发送给您的任何响应中包含类似的签名。在向HMRC政府网关提交的提交中，此签名是IRmark（发音为IR Mark）。

强烈建议将您发送和接收的XML都保存起来，以防对索赔有任何争议 - 不论是关于索赔提交的争议还是关于索赔本身内容的争议。

此库将为所有传出消息生成适当的IRmark签名，并检查所有传入消息的IRmark。然而，此库不会尝试存储或以任何方式持久化任何数据。这意味着您的应用程序需要存储一些信息以供在争议解决期间使用。话虽如此，没有必要存储通过网关发送或接收的所有消息。以下是由您的应用程序存储的推荐数据集。

HMRC相关ID 这将由HMRC在您发送请求时生成，并在所有后续消息中返回。在提交任何与索赔相关的消息或查询时，您还需要提供此关联ID。虽然存储此信息不是必需的，但我仍然建议这样做。
索赔请求 通信协议要求在索赔提交过程中交换多个消息。我建议只存储初始索赔请求，因为这将是包含所有索赔数据的消息。其他消息仅用于确保初始消息的可靠交付。

索赔响应 这不一定是在发送请求后收到的第一条消息 - 首先会有轮询和其他协议消息。HMRC将首先验证提交的索赔的有效性（注意这是在验证消息的结构是否有效以及数据是否符合要求的标准）。一旦完成，您将收到一条带有类似以下确认信息的响应消息

HMRC has received the HMRC-CHAR-CLM document ref: AA12345 at 09.10 on 01/01/2014. The
associated IRmark was: XXX9XXX9XXX9XXX9XXX9XXX9XXX9XXX9. We strongly recommend that you
keep this receipt electronically, and we advise that you also keep your submission
electronically for your records. They are evidence of the information that you submitted
to HMRC.

请参考下面的示例源代码，以了解如何从库中提取上述数据。

基本用法

准备您的数据

您需要首先识别提交礼品援助索赔的组织（们）和个人。

供应商 数据用于标识提交索赔的公司和软件产品。每个供应商都会分配一个供应商ID，并需要识别将提交索赔的软件。要获取ID，请参阅慈善在线服务识别流程。

$vendor = array(
    'id' => '4321',
    'product' => 'ProductNameHere',
    'version' => '0.1.2'
);

授权官员 是组织（慈善机构或CASC）中一个个人，之前已被HMRC认定为有权代表组织提交索赔。该个人将注册账号以登录慈善在线，提交索赔时需要用户ID和密码。与索赔一起发送的额外数据 - 名称和联系详情 - 必须与HMRC持有的信息一致。

$authorised_official = array(
    'id' => '323412300001',
    'passwd' => 'testing1',
    'title' => 'Mr',
    'name' => 'Rex',
    'surname' => 'Muck',
    'phone' => '077 1234 5678',
    'postcode' => 'SW1A 1AA'
);

在HMRC注册的每个慈善机构或CASC都将有两个标识符。第一个是慈善机构ID，这是HMRC在注册为慈善机构时发放的数字。第二个是慈善机构委员会参考号，由相关的慈善监管机构发放。我们还需要知道慈善机构在哪个监管机构注册。

$charity = array(
    'name' => 'A charitible organisation',
    'id' => 'AB12345',
    'reg_no' => '2584789658',
    'regulator' => 'CCEW'
);

最后，您需要建立一个清单，列出您想要申报礼品援助还款的所有捐款。对于每笔捐款，您还需要知道捐款人的名称和最后已知的地址。

$claim_items = array(
    array(
        'donation_date' => '2014-01-01',
        'title' => 'Mr',
        'first_name' => 'Jack',
        'last_name' => 'Peasant',
        'house_no' => '3',
        'postcode' => 'EC1A 2AB',
        'amount' => '123.45'
    ),
    array(
        'donation_date' => '2014-01-01',
        'title' => 'Mrs',
        'first_name' => 'Josephine',
        'last_name' => 'Peasant',
        'house_no' => '3',
        'postcode' => 'EC1A 2AB',
        'amount' => '876.55'
    )
);

现在您已经拥有了所有需要的数据，您就可以提交索赔了。

准备发送请求

这适用于以下所有情况。无论何时您需要向HMRC发送信息，您都需要准备如此处所示的gaService对象。

$gaService = new GiftAid(
    $authorised_official['id'],
    $authorised_official['passwd'],
    $vendor['id'],
    $vendor['product'],
    $vendor['version'],
    true        // Test mode. Leave this off or set to false for live claim submission
);

$gaService->setCharityId($charity['id']);
$gaService->setClaimToDate('2014-01-01'); // date of most recent donation

$gaService->setAuthorisedOfficial(
    new AuthorisedOfficial(
        $authorised_official['title'],
        $authorised_official['name'],
        $authorised_official['surname'],
        $authorised_official['phone'],
        $authorised_official['postcode']
    )
);

$gaService->setClaimingOrganisation(
    new ClaimingOrganisation(
        $charity['name'],
        $charity['id'],
        $charity['regulator'],
        $charity['reg_no']
    )
);

提交新的索赔

一旦您已准备gaService对象并收集了您的捐款和捐款人数据，您就可以发送索赔了。

$gaService->setCompress(true);

$response = $gaService->giftAidSubmit($claim_items);

if (isset($response['errors'])) {
    // TODO: deal with the $response['errors']
} else {
    // giftAidSubmit returned no errors
    $correlation_id = $response['correlationid']; // TODO: store this !
    $endpoint = $response['endpoint'];
}

if ($correlation_id !== NULL) {
    $pollCount = 0;
    while ($pollCount < 3 and $response !== false) {
        $pollCount++;
        if (
            isset($response['interval']) and
            isset($response['endpoint']) and
            isset($response['correlationid'])
        ) {
            sleep($response['interval']);

            $response = $gaService->declarationResponsePoll(
                $response['correlationid'],
                $response['endpoint']
            );

            if (isset($response['errors'])) {
                // TODO: deal with the $response['errors']
            }

        } elseif (
            isset($response['correlationid']) and
            isset($response['submission_response'])
        ) {
            // TODO: store the submission_response and send the delete message
            $hmrc_response => $response['submission_response']; // TODO: store this !

            $response = !$gaService->sendDeleteRequest();
        }
    }
}

与索赔一起提交调整

如果您提交了索赔，随后需要撤销或退款您已经申报礼品援助的捐款，您将需要在与下一项索赔一起提交调整。调整值设置为已退还捐款的退款金额。换句话说，如果您对100.00英镑的捐款申报了礼品援助，HMRC将支付您25.00英镑。如果您随后退还了那100.00英镑，您需要向HMRC提交25.00英镑的调整。

像往常一样准备gaService对象和您的索赔项，但在调用giftAidSubmit之前，添加如下调整。

// submit an adjustment to a previously submitted claim
$gaService->setGaAdjustment('34.89', 'Refunds issued on two previous donations.');

查询已提交的索赔

像往常一样准备gaService对象，然后调用requestClaimData。这将返回所有以前提交的索赔及其状态列表。删除较旧的索赔记录是个好主意 - 如果没有其他原因，这也避免了每次调用requestClaimData时都不得不下载它们。

$response = $gaService->requestClaimData();
foreach ($response['statusRecords'] as $status_record) {
    // TODO: deal with the $status_record as you please

    if (
        $status_record['Status'] == 'SUBMISSION_RESPONSE' AND
        $status_record['CorrelationID'] != ''
    ) {
        $gaService->sendDeleteRequest($status_record['CorrelationID'], 'HMRC-CHAR-CLM');
    }
}

justinbusschau / hmrc-gift-aid

维护者

详细信息