cmpayments/orderapi-sdk-php

CMPayments 订单 API SDK

维护者

详细信息

github.com/cmpayments/orderapi-sdk-php

源代码

问题

安装次数: 8,471

依赖项: 0

建议者: 0

安全性: 0

星标: 1

关注者: 1

分支: 4

开放问题: 0

v1.14.1 2024-01-26 16:25 UTC

Requires

  • php: >=5.5.9

Requires (Dev)

proprietary 915b93ef5ac83abb4a6938fea435fb6e4f8d6c42

This package is auto-updated.

Last update: 2024-08-26 17:41:39 UTC

README

Build Status Software License Total Downloads

有关订单 API 调用的更多信息，请参阅文档。此 SDK 是一个工具箱，有关 Webdirect 或一键结账的内部工作原理的更多信息，请参阅集成手册https://www.docdatapayments.com/developer/api/。

安装

要安装 SDK，只需使用 Composer: composer require cmpayments/orderapi-sdk-php

设置连接

通过填写 username 和 password 来设置连接。如果您想使用沙箱环境，将 true 作为第三个参数添加。所有请求都由此客户端创建。

<?php
$client = new CMPayments\OrderApi\Client('<username>', '<password>');

创建请求

此请求将描述一个带有许多可选字段的完整请求。

首先创建一个 merchantOrderReference，该参考指向您对此订单的内部唯一参考，并由系统在商家后台中用于信息目的。

<?php
$merchantOrderReference = time();

支付偏好指定了在此订单上进行的所有付款应使用的设置。用您的自己的支付配置文件替换 <payment_profile>。

<?php
$paymentPreferences = new CMPayments\OrderApi\Requests\Elements\PaymentPreference();
$paymentPreferences->setProfile('<payment_profile>')
   ->setNumberOfDaysToPay(14)
   ->addPeriod(7, 'unknown')
   ->addPeriod(7);

通过 CSS 配置文件支持不同的视觉样式。此配置文件的 ID 可以设置如下

<?php
$menuPreference = new CMPayments\OrderApi\Requests\Elements\MenuPreferences();
$menuPreference->setCssId(1);

支付系统需要每个订单的购物者信息。也可以提供 name 元素，并包含更多信息，如 middlename、suffix、prefix 等。

<?php
$shopper = new CMPayments\OrderApi\Requests\Elements\Shopper();
$name = new CMPayments\OrderApi\Requests\Elements\Name();
$name->setFirstname('Testpersoon-nl')
   ->setLastname('Approved');

/* Note: date of birth must be a \DateTime */
$dateOfBirth = DateTime::createFromFormat('Y-m-d', '1970-07-10');
$shopper->setShopperId('<customer_id>')
   ->setName($name)
   ->setEmail('accepted@yourdomain.com')
   ->setLanguageCode('nl')
   ->setGender('M')
   ->setDateOfBirth($dateOfBirth)
   ->setPhoneNumber('0612345678');

设置交易的账单和送货信息。在这个例子中，账单和送货地址是相同的，即使收件人的姓名也相同。

<?php
$billToAddress = new CMPayments\OrderApi\Requests\Elements\Address();
$billToAddress->setStreet('street')
   ->setHouseNumber('1')
   ->setHouseNumberAddition('A')
   ->setPostalCode('1234AA')
   ->setCity('Amsterdam')
   ->setCountryCode('NL');
$billToName = $name;
$shipToAddress = $billToAddress;
$shipToName = $name;

创建了一个包含 3 个产品的发票。1 张金士顿 microSD 卡和 2 张《孤独星球泰国》DVD

<?php
$invoice = new CMPayments\OrderApi\Requests\Elements\Invoice();
/* The total amount to pay incl. vat */
$paymentAmount = CMPayments\OrderApi\Requests\Elements\Amount::EUR(33.30);
/* specify the vat-rules per item */
$vat1 = new CMPayments\OrderApi\Requests\Elements\Vat();
$vat1->setAmount(CMPayments\OrderApi\Requests\Elements\Amount::EUR(2.10))->setRate(21);
$vat2 = new CMPayments\OrderApi\Requests\Elements\Vat();
$vat2->setAmount(CMPayments\OrderApi\Requests\Elements\Amount::EUR(1.20))->setRate(6);

/*
 * Define product 1
 */
$item1 = new CMPayments\OrderApi\Requests\Elements\Item();
$item1VatRate = new CMPayments\OrderApi\Requests\Elements\Vat();
$item1VatRate->setAmount(CMPayments\OrderApi\Requests\Elements\Amount::EUR(2.10))->setRate(21);
$item1TotalVatRate = new CMPayments\OrderApi\Requests\Elements\Vat();
$item1TotalVatRate->setAmount(CMPayments\OrderApi\Requests\Elements\Amount::EUR(2.10))->setRate(21);
$item1->setName('Kingston microSD kaart 32GB')
   ->setCode('SDC4/4GB-2ADP')
   ->setQuantity(CMPayments\OrderApi\Requests\Elements\Quantity::pieces(1))
   ->setDescription('Kingston microSD kaart 32GB met adapter')
   ->setImage('http://www.google.nl/images/srpr/logo3w.png')
   ->setNetAmount(CMPayments\OrderApi\Requests\Elements\Amount::EUR(10.00))
   ->setGrossAmount(CMPayments\OrderApi\Requests\Elements\Amount::EUR(12.10))
   ->setVat($item1VatRate)
   ->setTotalNetAmount(CMPayments\OrderApi\Requests\Elements\Amount::EUR(10.00))
   ->setTotalGrossAmount(CMPayments\OrderApi\Requests\Elements\Amount::EUR(12.10))
   ->setTotalVat($item1VatRate);

/*
 * Define product 2 (note: setQuantity has 2 pieces)
 */
$item2 = new CMPayments\OrderApi\Requests\Elements\Item();
$item2VatRate = new CMPayments\OrderApi\Requests\Elements\Vat();
$item2VatRate->setAmount(CMPayments\OrderApi\Requests\Elements\Amount::EUR(0.60))->setRate(6);
$item2TotalVatRate = new CMPayments\OrderApi\Requests\Elements\Vat();
$item2TotalVatRate->setAmount(CMPayments\OrderApi\Requests\Elements\Amount::EUR(1.20))->setRate(6);
$item2->setName('Lonely Planet Thailand')
   ->setCode('9781741791570')
   ->setQuantity(CMPayments\OrderApi\Requests\Elements\Quantity::pieces(2))
   ->setDescription('Tourism and travel information incl. maps, history, culture and transport in Thailand')
   ->setImage('http://upload.wikimedia.org/wikipedia/en/b/bc/Wiki.png')
   ->setNetAmount(CMPayments\OrderApi\Requests\Elements\Amount::EUR(10.00))
   ->setGrossAmount(CMPayments\OrderApi\Requests\Elements\Amount::EUR(10.60))
   ->setVat($item2VatRate)
   ->setTotalNetAmount(CMPayments\OrderApi\Requests\Elements\Amount::EUR(20.00))
   ->setTotalGrossAmount(CMPayments\OrderApi\Requests\Elements\Amount::EUR(21.20))
   ->setTotalVat($item2TotalVatRate);

/*
 * Add all elements to the invoice
 */
$invoice->setTotalNetAmount(CMPayments\OrderApi\Requests\Elements\Amount::EUR(30.00))
   ->addTotalVatAmount($vat1)
   ->addTotalVatAmount($vat2)
   ->addItem($item1)
   ->addItem($item2)
   ->setShipTo($shipToName, $shipToAddress)
   ->setAdditionalDescription('Add. Description');

/*
 * Create the actual request
 */
$createRequest = $client->createRequest();

/*
 * Add all invoice elements
 */
$createRequest->addMerchantOrderReference($merchantOrderReference)
   ->addPaymentPreferences($paymentPreferences)
   ->addMenuPreferences($menuPreference)
   ->addShopper($shopper)
   ->addTotalGrossAmount($paymentAmount)
   ->addBillTo($billToName, $billToAddress)
   ->addDescription('default transaction')
   ->addReceiptText('Thanks for your purchase')
   ->addInvoice($invoice)
   ->addIntegrationInfo(new CMPayments\OrderApi\Requests\Elements\IntegrationInfo('My webshop name or plugin', 'v1.0.0'));

最后一步是将 CreateRequest 发送到 API。

<?php
//Do the actual request to the endpoint
$createResponse = $client->executeCreateRequest($createRequest);

一键结账

如果您不想为每种支付方式创建不同的视图，则可以使用默认的结账页面。注意：一键结账是必须在其账户中启用的功能

<?php
$opcResponse = $client->createOnePageCheckOut($createResponse->createSuccess->key)
->setClientLanguage('nl')
->setReturnUrlCancelled('https://www.yourdomain.com/cancelled')
->setReturnUrlError('https://www.yourdomain.com/error')
->setReturnUrlPending('https://www.yourdomain.com/pending')
->setReturnUrlSuccess('https://www.yourdomain.com/succes');

header('Location: ' . $opcResponse->getPaymentUrl());

startRequest

start 请求是针对 Webdirect 场景的，其中可以无需与购物者在线互动即可启动支付。在这个例子中，我们将启动 iDEAL 交易。注意：start 请求功能是必须在其账户中启用的功能

此 API 中的 iDEAL 发行者列表

  • ABNAMRO
  • ASN
  • BUNQ
  • FRIESLANDBANK
  • ING
  • KNAB
  • RABO
  • REGIOBANK
  • SNS
  • TRIODOS
  • VANLANSCHOT
<?php
$paymentMethodData = new CMPayments\OrderApi\Requests\Elements\PaymentInput\IdealPaymentInput();
$paymentMethodData->setIssuerId('RABO');
$shopperInfo = new CMPayments\OrderApi\Requests\Elements\ShopperInfo();
$shopperInfo->setBrowserAccept('*/*')->setBrowserUserAgent('notfound')->setShopperIp('10.0.0.1');

$startRequest = $client->createStartRequest($createResponse->createSuccess->key);
$startRequest->addPaymentAmount($paymentAmount) /* from above */
    ->addPaymentMethodData($paymentMethodData) /* from above */
    ->addReturnUrl('https://www.yourdomain.tld/return?status=redirect')
    ->addShopperInfo($shopperInfo)
    ->addIntegrationInfo(new CMPayments\OrderApi\Requests\Elements\IntegrationInfo('My webshop name or plugin', 'v1.0.0'));

$startResponse = $client->executeStartRequest($startRequest);

//  Store the payment ID somewhere, you will need it later
$_SESSION['payment_id'] = $startResponse->startSuccess->paymentResponse->paymentSuccess->id

//In the response there is an redirect url to redirect the customer to
header('Location: ' . $startResponse->startSuccess->redirect->url);

proceedRequest

proceed 请求是针对 Webdirect 场景的，其中购物者被重定向到收单行。它用于在商家从收单行返回后完成授权。例如，当购物者被直接发送到 iDEAL 或 3D Secure 时。

<?php
//Create a proceeed request
$proceedRequest = $client->createProceedRequest(<payment_id>);
//Tell the request that it has to be an iDEAL proceed
$proceedRequest->Ideal();
//Execute the request
$proceedResponse = $client->executeProceedRequest($proceedRequest);

captureRequest

捕获请求的目的是强制支付系统捕获一个已成功授权处理的可接受订单。然而，在所有情况下并不需要此操作。根据支付方式，支付系统提供了一个选项，在预定义的天数后自动捕获支付订单。此选项支持像AfterPay和Klarna发票这样的支付方式，其中只有在产品准备发货时才会发货。

<?php
$captureRequest = $client->createCaptureRequest(payment_id>, CMPayments\OrderApi\Requests\Elements\Amount::EUR(33.30));
$captureResponse = $client->executeCaptureRequest($captureRequest);

statusRequest

状态请求可用于检索反映订单、其支付和其捕获或退款的实际状态的报告。状态请求用于确定订单是否被视为“已支付”。

<?php
$statusRequest = $client->createStatusRequest(<PaymentOrderKey>);
$statusResponse = $client->executeStatusRequest($statusRequest);

statusExtendedRequest

扩展状态请求可用于检索订单、其支付和其捕获或退款的其他信息。

<?php
$statusExtendedRequest = $client->createExtendedStatusRequest(<PaymentOrderKey>);
$statusExtendedResponse = $client->executeExtendedStatusRequest($statusExtendedRequest);

cancelRequest

取消请求的目的是强制支付系统不再接受任何给定订单的支付操作。在一个购物者在网络商店取消订单的情况下，取消请求用于同步网络商店和支付系统的管理，以确保支付系统不会对订单进行支付处理。

<?php
$cancelRequest = $client->createCancelRequest(<PaymentOrderKey>);
$cancelResponse = $client->executeCancelRequest($cancelRequest);

refundRequest

在商家想要在支付订单上退还一定金额的情况下，可以使用退款请求。退款请求允许在网店和支付系统之间控制并自动化端到端退款流程。

@Todo 实现完整的退款选项，而不是简单版本。

<?php
$refundRequest = $client->createRefundRequest(<payment_id>);
$refundRequest->addAmount(CMPayments\OrderApi\Requests\Elements\Amount::EUR(21.20))
->setItemCode(9781741791570)
->setDescription('Wrong dvd');
$refundResponse = $client->executeRefundRequest($refundRequest);