README

版权

(c) 2016-2024, viafintech GmbH
https://www.viafintech.com

准备

API 凭证

使用 Barzahlen API 所必需的 API 凭证可以在 Barzahlen 控制中心 获取。注册成功后，将为您分配一个部门 ID 和支付密钥。

安装

可以使用 Composer 安装 Barzahlen PHP SDK。

composer require barzahlen/barzahlen-php

客户端

客户端会将您的应用程序连接到 Barzahlen API v2。使用部门 ID 和支付密钥启动它。如果想要在开发目的下将请求发送到沙盒，则可以将第三个可选参数设置为 true。可选：设置自定义用户代理。

use Barzahlen\Client;
use Barzahlen\Exception\ApiException;

$client = new Client('12345', 'f2a173a210c7c8e7e439da7dc2b8330b6c06fc04', true);
$client->setUserAgent('Awesome Project v1.0.1');

try {
    $response = $client->handle($request);
    $stdClass = json_decode($response);
    $array = json_decode($response, true);
} catch (ApiException $e) {
    // @TODO: handle exception
}

建议使用 try-catch 块包围 API 调用，因为错误会以异常的形式抛出。这样，它们可以按系统要求的进行记录。

API 将发送 JSON 作为响应。使用 json_decode() 将其转换为对象或关联数组。

请求

客户端可以处理五种不同的请求。可以使用设置器、数组或直接使用 JSON 字符串来设置所需和可选参数。

创建请求

要请求新的付款或退款单，只需启动一个新的 CreateRequest 并添加参数。以下是一个使用设置器、数组和纯 JSON 进行最小付款请求的三个示例。

付款单

use Barzahlen\Request\CreateRequest;

$request = new CreateRequest();
$request->setSlipType('payment');
$request->setCustomerKey('LDFKHSLFDHFL');
$request->setTransaction('14.95', 'EUR');

use Barzahlen\Request\CreateRequest;

$parameters = array(
    'slip_type' => 'payment',
    'customer' => array(
        'key' => 'LDFKHSLFDHFL'
    ),
    'transactions' => array(
        array(
            'amount' => '14.95',
            'currency' => 'EUR'
        )
    )
);

$request = new CreateRequest();
$request->setBody($parameters);

use Barzahlen\Request\CreateRequest;

$json = '{
  "slip_type": "payment",
  "customer": {
    "key": "LDFKHSLFDHFL"
  },
  "transactions": [
    { "currency": "EUR", "amount": "123.34" }
  ]
}';

$request = new CreateRequest();
$request->setBody($json);

退款单

这是一个最小退款请求的示例。请注意，金额是负数，并且不能超过初始付款金额。对于一笔付款，可以多次退款，总额不超过初始金额。

use Barzahlen\Request\CreateRequest;

$request = new CreateRequest();
$request->setSlipType('refund');
$request->setForSlipId('slp-1b41145c-2dd3-4e3f-bbe1-72c09fbf3f94');
$request->setTransaction('-14.95', 'EUR');

支付单

这是一个最小支付请求的示例。

支付单允许客户收取现金，并导致资金从您的部门转移。当支付与先前付款无关的资金时，请使用支付单。当退还客户先前通过 Barzahlen 支付的部分或全部资金时，请使用退款单。

use Barzahlen\Request\CreateRequest;

$request = new CreateRequest();
$request->setSlipType('payout');
$request->setCustomerKey('LDFKHSLFDHFL');
$request->setTransaction('-14.95', 'EUR');

更多参数

您可以根据 Barzahlen API v2 文档 设置更多参数。

$request->setReferenceKey('REFKEY123');
$request->setHookUrl('https://www.example.tld/barzahlen/callback');
$request->setExpiresAt('2016-04-01T12:34:56Z');
$request->setCustomerKey('[email protected]');
$request->setCustomerCellPhone('01234567910');
$request->setCustomerEmail('[email protected]');
$request->setCustomerLanguage('de-DE');
$request->setAddress(array(
            'street_and_no' => 'Wallstr. 14a',
            'zipcode' => '10179',
            'city' => 'Berlin',
            'country' => 'DE'
        ));
$request->addMetadata('promo', 'summer2016');

客户数据可以作为数组设置，expiresAt 值可以是 DateTime 对象。您还可以使用设置器进行链式调用。

$expire = new \DateTime();
$expire->modify('+1 week');

$request->setExpiresAt($expire)
        ->setCustomer(array(
            'cell_phone' => '01234567910'
            'key' => '[email protected]'
            'email' => '[email protected]'
            'language' => 'de-DE'
        ));

示例响应

当前单据状态的表示。（内容取决于发送的参数。）

{
  "id": "slp-d90ab05c-69f2-4e87-9972-97b3275a0ccd",
  "slip_type": "payment",
  "division_id": "1234",
  "reference_key": "O64737X",
  "hook_url": "https://psp.example.com/hook",
  "expires_at": "2016-01-10T12:34:56Z",
  "customer": {
    "key": "LDFKHSLFDHFL",
    "cell_phone_last_4_digits": "6789",
    "email": "[email protected]",
    "language": "de-DE"
  },
  "checkout_token": "djF8Y2hrdHxzbHAtMTM4ZWI3NzUtOWY5Yy00NzYwLWI4ZTAtYTNlZWNmYjQ5M2IxfElBSThZMnd6SFYwbjJpMm9aSUpvREpnYnhNS3c5Z2x3elJOanlLblZJeFk9",
  "metadata": {
    "order_id": "1234",
    "invoice_no": "A123"
  },
  "transactions": [
    {
      "id": "4729294329",
      "currency": "EUR",
      "amount": "123.34",
      "state": "pending"
    }
  ],
  "nearest_stores": [
    {
      "title": "mobilcom-debitel",
      "logo": {
        "id": "17077"
      },
      "distance_m": 1160,
      "address": {
        "city": "Berlin",
        "country": "DE",
        "street_and_no": "Grunerstraße 20",
        "zipcode": "10179"
      },
      "opening_hours": {
        "days": [
          { "day": "sun", "open": [] },
          { "day": "mon", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "tue", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "wed", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "thu", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "fri", "open": [{"begin": "10:00", "end": "21:00"}] },
          { "day": "sat", "open": [{"begin": "10:00", "end": "21:00"}] }
        ]
      }
    },
    {
      "title": "dm-drogerie markt",
      "logo": {
        "id": "13045"
      },
      "distance_m": 1220,
      "address": {
        "city": "Berlin",
        "country": "DE",
        "street_and_no": "Alexanderplatz 1",
        "zipcode": "10178"
      },
      "opening_hours": {
        "days": [
          { "day": "sun", "open": [] },
          { "day": "mon", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "tue", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "wed", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "thu", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "fri", "open": [{"begin": "09:00", "end": "22:00"}] },
          { "day": "sat", "open": [{"begin": "09:00", "end": "22:00"}] }
        ]
      }
    },
    {
      "title": "dm-drogerie markt",
      "logo": {
        "id": "13045"
      },
      "distance_m": 1280,
      "address": {
        "city": "Berlin",
        "country": "DE",
        "street_and_no": "Henriette-Herz-Platz 4",
        "zipcode": "10178"
      },
      "opening_hours": {
        "days": [
          { "day": "sun", "open": [] },
          { "day": "mon", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "tue", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "wed", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "thu", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "fri", "open": [{"begin": "08:30", "end": "21:00"}] },
          { "day": "sat", "open": [{"begin": "09:00", "end": "21:00"}] }
        ]
      }
    }
  ]
}

更新请求

要之后更改单据参数，请使用单据 ID 启动一个新的 UpdateRequest。使用设置器、数组或 JSON 字符串设置您的新或更新的参数。只有挂起状态的单据才能更新。有关更多信息，请参阅 Barzahlen API v2 文档。

use Barzahlen\Request\UpdateRequest;

$request = new UpdateRequest('slp-f26bcd0b-556b-4285-b0b3-ba54052df97f');
$request->setCustomer(array(
    'email' => '[email protected]',
    'cell_phone' => '012345678910'
));
$request->setExpiresAt('2016-01-10T12:34:56Z');
$request->setTransaction('4729294329', '150.00');
$request->setReferenceKey('NEWKEY');

可以使用 DateTime 对象使用 expiresAt() 方法，并且可以使用链式设置器。响应将包含包含更新信息的 JSON。

检索请求、重发请求、作废请求

最后三个请求不需要通过设置器、数组或 JSON 设置任何其他参数。可以在客户端发送之前使用单据 ID（和消息类型）启动它们。

use Barzahlen\Request\RetrieveRequest;
use Barzahlen\Request\ResendRequest;
use Barzahlen\Request\InvalidateRequest;

// get current information on the slip
$request = new RetrieveRequest('slp-f26bcd0b-556b-4285-b0b3-ba54052df97f');

// resend email / text message to customer
$request = new ResendRequest('slp-f26bcd0b-556b-4285-b0b3-ba54052df97f', 'email');
$request = new ResendRequest('slp-f26bcd0b-556b-4285-b0b3-ba54052df97f', 'text_message');

// invalidate slip immediately
$request = new InvalidateRequest('slp-f26bcd0b-556b-4285-b0b3-ba54052df97f');

检索 PDF 请求

检索单据的 PDF 表示形式以打印。仅对挂起状态的单据可以进行 PDF 下载。

注意：出于安全考虑，此端点默认禁用，只能由Barzahlen启用。如果您想使用此功能，请随时联系我们。

use Barzahlen\Request\RetrievePdfRequest;

$request = new RetrievePdfRequest('slp-f26bcd0b-556b-4285-b0b3-ba54052df97f');

// contains pdf data
$response = $client->handle($request);

Webhook

当收据状态发生变化时（例如，客户在零售合作伙伴处付款）且已设置钩子URL时，Barzahlen会将POST请求发送到该钩子URL，以便通知您变化。使用支付密钥初始化Webhook类，并使用它来验证传入请求的标头和正文。

use Barzahlen\Webhook;

$header = $_SERVER;
$body = file_get_contents('php://input');
$webhook = new Webhook('f2a173a210c7c8e7e439da7dc2b8330b6c06fc04');

if ($webhook->verify($header, $body)) {
    $stdClass = json_decode($body);
    $array = json_decode($body, true);
    // @TODO: send 200 status code, update order
} else {
    // @TODO: send 400 status code, log error
}

支持

viacash团队将乐意帮助您解决任何问题或疑问。

请发送电子邮件至 [email protected] 或访问我们的解决方案中心 https://www.viafintech.com/overview-solutions/。