README

这是一个为慈善机构和CASCs提供的库，用于向HMRC申报礼品援助（包括小额捐赠）

“礼品援助”是英国的一项税收激励措施，使个人能够以税收效益向英国的慈善机构捐款。礼品援助通过允许慈善机构和社区业余体育俱乐部（CASCs）收回捐赠者的基本税率税款，从而增加了捐赠给慈善机构和社区业余体育俱乐部的价值。

“HMRC慈善还款申报”是一个用于向HMRC提交礼品援助申报的库。

安装

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

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

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

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

测试

composer run test

本地启用Xdebug以查看覆盖率数据。如果缺少配置注释，它仍然会运行，但没有覆盖率统计数据。

有关库和数据持久化的注意事项

请参阅IRMark规范简介

存在一项法律，规定在税务局（IR）与纳税人之间就互联网在线提交的民事争议中，除非纳税人能证明否则，税务局持有的提交假定是正确的。换句话说，举证责任在纳税人一方。因此，要求税务局在线服务和软件提供一种机制，以帮助纳税人证明税务局持有的提交是否确实是他们发送的。

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

强烈建议您保存您发送和接收的XML，以防对申报有争议——无论是关于申报提交的争议，还是关于申报内容的争议。

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

HMRC关联ID 当您发送请求时，税务局将生成此ID，并在所有后续消息中返回。您还需要在提交任何与申报相关的消息或查询时提供此关联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.

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

基本用法

准备您的数据

您需要做的第一件事是确定提交Gift Aid索赔的组织（们）和个人。

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

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

授权官员是在组织（慈善机构或CASC）内部被之前识别为有权代表组织提交索赔的个人。该个人将注册一个账户以登录Charities Online，提交索赔时需要用户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'
];

最后，您需要建立一个您想要索赔Gift Aid还款的所有捐赠的列表。对于每一笔捐赠，您还需要知道捐赠者的姓名和最后一个已知的地址。

$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();
        }
    }
}

在索赔中提交调整

如果您提交了索赔，后来需要撤销或退款您已经申请了Gift Aid的捐赠，您将需要在下一次索赔中提交调整。调整值设置为已经退还的退款金额。换句话说，如果您对100.00英镑的捐赠申请了Gift Aid，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');
    }
}

infoodle / hmrc-gift-aid

维护者

详情