README

这是一个用于慈善机构和CASCs向HMRC申请Gift Aid（包括小额捐赠）的库

"Gift Aid"是英国一项税收激励措施，使个人能够以有效的方式向英国的慈善机构捐款。"Gift Aid"通过允许慈善机构和社区业余体育俱乐部（CASCs）从捐赠者的赠与中收回基本税率税款，从而增加了对慈善机构和CASCs的捐赠价值。

"HMRC慈善机构还款申请"是一个提交Gift Aid申请到HMRC的库。

库背景

Big Give在2021年从JustinBusschau/hmrc-gift-aid分叉了这个库，以及相应的php-govtalk库，因为这些库不再维护PHP的活跃版本。

我们不提供对该库的支持，但计划在未来一段时间内维护它，并对仍在接收安全支持的PHP版本进行测试。

在我们的平台上运行活动的慈善机构，如果他们使用我们的托管服务来申请Gift Aid，可以通过这里联系。

安装

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

{
    "require": {
        "thebiggive/hmrc-gift-aid": "^1.0"
    }
}

然后运行Composer以更新您的依赖项

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

测试

composer run test

在本地启用Xdebug以查看覆盖率数据。即使缺少配置注释，也应该继续运行。

有关库和数据处理的一些说明

来自IRMark规范的介绍

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

换句话说，您提交的XML必须包含某种形式的签名。签名可用于证明HMRC收到的确实是您打算发送的内容。HMRC将反过来，在他们发送给您的任何响应中包含类似的签名。在向HMRC政府网关提交的情况下，这个签名是IRmark（发音为IR Mark）。

强烈建议，您发送的XML和您接收的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.

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

基本用法

准备您的数据

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

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

$vendor = [
    'id' => '4321',
    'product' => 'ProductNameHere',
    'version' => '0.1.2'
];

授权官方 是组织（慈善机构或CASC）内部已被HMRC识别为有权代表组织提交索赔的个人。该个人将注册一个账户以登录到慈善机构在线，并在提交索赔时需要用户ID和密码。与索赔一起发送的附加数据（姓名和联系详情）必须与HMRC持有的信息一致。

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

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

$charity = [
    'name' => 'A charitible organisation',
    'id' => 'AB12345',
    'reg_no' => '2584789658',
    'regulator' => 'CCEW'
];

最后，您需要构建一份所有希望索赔礼品援助还款的捐赠清单。对于每笔捐赠，您还需要知道捐赠者的姓名和最后的已知地址。

$claim_items = [
    [
        'donation_date' => '2014-01-01',
        'title' => 'Mr',
        'first_name' => 'Jack',
        'last_name' => 'Peasant',
        'house_no' => '3',
        'postcode' => 'EC1A 2AB',
        'amount' => '123.45'
    ],
    [
        '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');
    }
}

thebiggive / hmrc-gift-aid

维护者

详细信息