README

Starling Bank 支付 API 对象

这是一个用于 PHP 8.1 的包，用于将请求响应体消息填充到 Starling Payments API 的请求中。

此包正在开发中，最初仅覆盖了我特别感兴趣的一些响应消息。现在正在添加生成请求消息体的对象。目标是扩展到包括完整的 PSR-7 消息（正文、标题、相对路径）。为了支持路径生成，可能需要添加上下文 UUID（例如创建账户地址时的账户 ID），因此构造函数将发生变化。

如果您想看到某些对象，可以通过 Pull Request 提交。

目前此包不包括请求消息，但将来可能会包括。我乐于接受 PR 来加快这一进程。

方法

Starling Payments API 使用 JSON 请求和响应体。JSON 响应将解码为嵌套的标量值数组。此包提供类，用于从该数据实例化对象。

最初，这些类只是简单的值对象，它们通过属性接收数据。随着时间的推移，将在类中添加更多逻辑来以更高层次的业务意义解释属性值。此外，值将被解析到更常见的对象，如 Money 和 Carbon，以进一步利用这些工具和支持这些库所提供的支持。

简单示例

可以通过此端点使用 Previous Payments API 获取账户地址的单笔支付。

/api/v1/{paymentBusinessUid}/account/{accountUid}/address/{addressUid}/payment/{paymentUid}

这返回与以下示例类似的数据结构

{
  "paymentBusinessUid": "e43d3060-2c83-4bb9-ac8c-c627b9c45f8b",
  "paymentAccountUid": "5347699b-d205-4272-aac6-ee9d7f2dddcf",
  "addressUid": "c0cee51b-700b-481d-8ac5-e2cd75929ef1",
  "paymentUid": "a4edcefd-97b5-46fc-9e79-004fe8f171b7",
  "sourceAccount": {
    "sortCode": "040050",
    "accountNumber": "12345678",
    "bic": "SRLGGB2L",
    "iban": "GB29NWBK60161331926819",
    "accountName": "Bobby Tables"
  },
  "destinationAccount": {
    "sortCode": "040050",
    "accountNumber": "12345678",
    "bic": "SRLGGB2L",
    "iban": "GB29NWBK60161331926819",
    "accountName": "Bobby Tables"
  },
  "direction": "INBOUND",
  "settlementAmount": {
    "currency": "GBP",
    "minorUnits": 11223344
  },
  "instructedAmount": {
    "currency": "GBP",
    "minorUnits": 11223344
  },
  "reference": "ABCD123456",
  "status": "ACCEPTED",
  "rejectedReason": {
    "code": "1234",
    "description": "Beneficiary Sort Code/Account Number unknown"
  },
  "requestedAt": "2017-06-05T11:47:58.801Z",
  "returnDetails": {
    "paymentBeingReturned": "954cbfb3-0de0-4f62-8043-00c5ccee0f12",
    "code": "1234",
    "description": "Beneficiary Sort Code/Account Number unknown"
  },
  "type": "SIP",
  "settlementCycleUid": "bba786ce-3580-4576-9cad-28a6b8f1b228",
  "fpsSettlementCycleId": "CYCLE_001",
  "fpsSettlementDate": "2017-06-05"
}

给定此数据结构作为 $data，可以像这样实例化值对象

use Consilience\Starling\Payments\Response\PaymentDetails;

$paymentDetails = PaymentDetails::fromArray($data);

// or

$paymentDetails = new PaymentDetails($data);

// or

$paymentDetails = PaymentDetails::fromResponse($psr7response);

每个属性都可以以多种方式引用

$status = $paymentDetails->status;

// or

$status = $paymentDetails->getProperty('status');

嵌套数据将依次实例化为值对象

$instructedCurrency = $paymentDetails->instructedAmount->currency;

instructedAmount 将是一个 CurrencyAndAmount 值对象。该对象支持转换为 Money\Money

$money = $paymentDetails->instructedAmount->toMoney();
var_dump($money);

/*
object(Money\Money)#28 (2) {
  ["amount":"Money\Money":private]=>
  string(3) "999"
  ["currency":"Money\Money":private]=>
  object(Money\Currency)#29 (1) {
    ["code":"Money\Currency":private]=>
    string(3) "GBP"
  }
}
*/

其他对象将有类似的转换。例如，可以通过将名称与 Carbon 连接来获取日期和日期时间属性，返回一个表示日期的 Carbon 对象。例如

var_dump($paymentDetails->fpsSettlementDate);

/*
string(10) "2018-01-05"
*/

var_dump($paymentDetails->fpsSettlementDateCarbon);

/*
object(Carbon\Carbon)#32 (3) {
  ["date"]=>
  string(26) "2018-01-05 00:00:00.000000"
  ["timezone_type"]=>
  int(3)
  ["timezone"]=>
  string(3) "UTC"
}
*/

日期时间对象（即时间戳）将使用它们提供的时区。没有时间的日期对象将返回 UTC 时区。

事情就是这样发展的，进展将在这里记录。

支持的消息

所有请求消息的命名空间为 Consilience\Starling\Payments\Request。

所有响应消息的命名空间为 Consilience\Starling\Payments\Response。

以下表格列出了您可以发送的请求以及存储响应的对象。

要创建响应对象，您可以使用响应体数据或响应 PSR-7 消息来实例化它。例如

use Consilience\Starling\Payments\Request\Models\Endpoint;
use Consilience\Starling\Payments\Request\GetPaymentServiceBusiness;
use Consilience\Starling\Payments\Response\BusinessInformation;

$endpoint = new Endpoint($myPaymentBusinessUid, Endpoint::INSTANCE_SANDBOX);
$message = new GetPaymentServiceBusiness($endpoint);

// $client is created to accept and send PSR-7 requests.
// Note also the client must use a signing provider suitable for
// the Starling Payments API.
$response = $client->send($message->getRequest());

// Create the response object from the HTTP respinse:
$responseObject = BusinessInformation::fromResponse($response);

var_dump($responseObject);

/*
object(Consilience\Starling\Payments\Response\BusinessInformation)#235 (4) {
  ["paymentBusinessUid":protected]=>
  string(36) "4b5de5aa-7752-21ea-8219-2f948454a2d1"
  ["name":protected]=>
  string(14) "My Business Name"
  ["netSenderCap":protected]=>
  object(Consilience\Starling\Payments\Response\Models\CurrencyAndAmount)#232 (3) {
    ["currency":protected]=>
    string(3) "GBP"
    ["minorUnits":protected]=>
    int(10000)
  }
}
*/

构建请求对象可能包括以下 Consilience\Starling\Payments\Request\Models 中的任何类

• CreatePaymentAccountAddressRequest
• CreatePaymentAccountRequest
• CurrencyAndAmount
• DomesticInstructionAccount
• 国内支付指令请求
• 端点
• 支付返回请求

响应消息可能包含以下低级模型

• Response\Models\AccountNumberAndSortCode
• Response\Models\CurrencyAndAmount
• Response\Models\PaymentDetailsAccount
• Response\Models\PaymentReturnDetails
• Response\Models\Balance
• Response\Models\ErrorDetail
• Response\Models\PaymentRejectionReason

支持Webhooks

• ServerRequest\FpsSchemeNotification

• ServerRequest\FpsInboundNotification

• ServerRequest\FpsRedirectionNotification

• ServerRequest\FpsReversalNotification (尚未进行测试)

• ServerRequest\AccountTransactionNotification (尚未进行测试)

• ServerRequest\MandateCreatedNotification

• ServerRequest\MandateCancelledNotification

• ServerRequest\MandateOriginatorChangedNotification

• ServerRequest\DirectCreditPaymentReceivedNotification

• ServerRequest\DirectDebitPaymentPaidNotification

• ServerRequest\DirectDebitPaymentRejectedNotification