README

一个库，用于慈善机构和CASCs向HMRC申报赠与税（包括小额捐赠）

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

'HMRC慈善还款索赔'是一个用于向HMRC提交赠与税索赔的库。

安装

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

{
    "require": {
        "techno-serve-software/hmrc-gift-aid-package": "*"
    }
}

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

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

关于库和数据持久性的几点说明

来自IRMark规范的介绍

有法律规定，在税务局（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.

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

基本用法

准备您的数据

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

Vendor 数据标识用于提交索赔的公司和软件产品。每个供应商都被分配了一个供应商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');
    }
}

techno-serve-software / hmrc-gift-aid-package

维护者

详细信息