ClearBank.Net 1.0.25

ClearBank.NET

ClearBank 集成非官方 .NET 客户端，通过他们的 API 创建在线支付。英国银行支付处理自动化。作为 NuGet 软件包 发布。此软件包旨在尽可能简单。

以下是一些先决条件

1. 创建 Azure KeyVault

从访问策略中添加角色和“密钥权限”以进行签名和验证。Azure KeyVault 支持 HSM（硬件安全模块）托管的密钥。

2. 配置“证书”选项卡

例如，使用新的自签名证书，但必须选择 PEM 格式。

下载证书，一个 PEM 文件。

3. 使用 Open-SSL 创建 CSR 并将其上传到 ClearBank 门户

openssl.exe req -new -sha256 -key "c:\temp\downloaded.pem" -out file.csr

• 上传到门户 https://institution-sim.clearbank.co.uk/
• 复制消息框中的私钥（一个长字符串）。在此配置中需要此信息，因为它将用于 POST 头 Authorization: Bearer (the long string)

更新：现在可以直接从 Azure Key Vault 获取 CSR，通过选择证书并点击“证书操作”→“下载 CSR”。

（4. 可选：使用 FI-API-Signtool 确保正确性）

签名的方式与此仓库类似，但官方代码更混乱，因为它是 C#。 GitHub - clearbank/fi-api-signtool

5. 开始使用此库

您的用户代码可能如下所示

let doSomeTransactions =
    let clearbankDefaultConfig =
        {
            BaseUrl = "https://institution-api-sim.clearbank.co.uk/"
            PrivateKey = "..."
            AzureKeyVaultName =  "myVault"
            AzureKeyVaultCredentials = DefaultCredentials
        } : ClearbankConfigruation

    let azureKeyVaultCertificateName = "my-cert"
    let fromAccount = UK_Domestic("60-01-34", "51112345")

    let target1 = 
        {
            To = UK_Domestic("20-20-15", "55555555")
            AccountHolder = "Mr Test"
            Sum = 123.00m
            Currency = "GBP"
            Description = "Phone Bill"
            PaymentReference = "123456789"
            TransactionId = "12345" // End-to-end: You identify corresponding webhooks with this.
        } |> ClearBank.createCreditTransfer

    let target2 = 
        {
            To = UK_Domestic("40-47-84", "70872490")
            AccountHolder = "John Doe"
            Sum = 123.00m
            Currency = "GBP"
            Description = "Some money"
            PaymentReference = "12345"
            TransactionId = "12345"
        } |> ClearBank.createCreditTransfer

    let xReqId = Guid.NewGuid()
    let instructions = ClearBank.createPaymentInstruction "Batch123" fromAccount  [| target1 ; target2 |]
    ClearBank.transferPayments clearbankDefaultConfig azureKeyVaultCertificateName xReqId [| instructions |] |> Async.RunSynchronously

如果您在 KeyVault 认证方面遇到问题，您可以更改配置中的 AzureKeyVaultCredentials。

    let clearbankDefaultConfig =
        {
            BaseUrl = "https://institution-api-sim.clearbank.co.uk/"
            PrivateKey = "..."
            AzureKeyVaultName =  "..."
            AzureKeyVaultCertificateName = "..."
            AzureKeyVaultCredentials =
                CredentialsWithOptions (
                    Azure.Identity.DefaultAzureCredentialOptions (
                        //ExcludeEnvironmentCredential = true
                        //,ExcludeManagedIdentityCredential = true
                        ExcludeSharedTokenCacheCredential = true
                        ,ExcludeVisualStudioCredential = true
                        //,ExcludeVisualStudioCodeCredential = true
                        //,ExcludeAzureCliCredential = true
                        //,ExcludeInteractiveBrowserCredential = true
                    )) 
            LogUnsuccessfulHandler = None
        } : ClearbankConfiguration

最后一个 LogUnsuccessfulHandler 属性是可选的错误日志回调。例如，您可以将其替换为 Some logging，并有一个函数

    let logging(status,content) =
        match ClearBank.parseClarBankErrorContent content with
        | ClearBankEmptyResponse -> Console.WriteLine "Response was empty"
        | ClearBankTransactionError errors -> errors |> Seq.iter(fun (tid,err) -> Console.WriteLine("Transaction id " + tid + " failed for " + err))
        | ClearBankGeneralError(title, detail) -> Console.WriteLine(title + ", " + detail)
        | ClearBankUnknownError content -> Console.WriteLine("JSON: " + content)

创建账户

有方法 ClearBank.createNewAccount 可以用来创建新账户。

获取账户和交易

存在方法 ClearBank.getAccounts，您可以使用它获取余额，以及 ClearBank.getTransactions 配置 pageSize pageNumber startDate endDate

Webhook 响应

为了接收 webhooks，您需要有外部库之外的自定义服务器，然而，此库中提供了一些辅助类。

使用这些类时，您的服务器代码可能看起来如下：

type CBWebhookController() as this =
    inherit ApiController()

    member __.Post ()
        async {
            // 1. Verify the webhook against your ClearBank public key:

            // Download the public key (a .pem file) from your ClearBank portal and use a converter such as https://raskeyconverter.azurewebsites.net/PemToXml to convert the text to XML
            let publicKeyXml = "<RSAKeyValue>...</RSAKeyValue>"

            let signature = this.Request.Headers.GetValues("DigitalSignature") |> Seq.tryHead |> Option.map Convert.FromBase64String //add some error handling
            let! bodyJson = this.Request.Content.ReadAsStringAsync() |> Async.AwaitTask

            let! isVerified = ClearBank.verifySignature publicKeyXml signature bodyJson //proceed only if true

            // 2. Parse and handle the request:
            let parsed = ClearBankWebhooks.parsePaymentsCall bodyJson

            // Use parsed.Type to get the webhook type.
            // Different types may have the corresponding end-to-end transactionId in different places.
            // Fetch your transaction based on that id, and do whatever you want.

            //    match parsed.Type with
            //    | "TransactionSettled" -> ...
            //    | "PaymentMessageAssessmentFailed" -> ...
            //    | "PaymentMessageValidationFailed" -> ...
            //    | "TransactionRejected" -> ...
            //    | _ -> (* "FITestEvent" *) ...

            // 3. Create response
            return! ClearBankWebhooks.createResponse clearbankDefaultConfig azureKeyVaultCertificateName this.Request parsed.Nonce

        } |> Async.StartAsTask

要测试 webhooks，您可以使用例如 Fiddler 来组成它们，并使用 https://webhook.site/ 来获取它们的调用。