Connect - Direct SDK PHP migration
While the Direct PHP SDK is similar to the Connect PHP SDK, there are some key differences. The Packagist project has been changed, classes have been renamed and got moved around.
The biggest difference is that all fields of classes in the "Domain" namespace have been made private and getters and setters have been added for them.
In addition, some functionality that was available for Connect is not yet available on Direct, and other functionality will not become available for Direct. These functionalities have been left out of the Direct SDK.
The only difference in installing and updating the Direct PHP SDK is that the Packagist package name is changed from “ingenico-epayments/connect-sdk-php” to “wl-online-payments-direct/sdk-php”.
Configuration
If you use a property file for initializing a Client, Communicator or CommunicatorConfiguration then you will have to update the property names.
The “connect” prefix in the property names has been changed to “onlinePayments”, and several fields have gotten a default value.
The Direct PHP SDK supports the following properties:
|
Connect property |
Direct property |
Default value (new) |
|
connect.api.endpoint.host |
onlinePayments.api.endpoint.host |
<none, required> |
|
connect.api.endpoint.scheme |
onlinePayments.api.endpoint.scheme |
https |
|
connect.api.endpoint.port |
onlinePayments.api.endpoint.port |
-1 |
|
connect.api.authorizationType |
onlinePayments.api.authorizationType |
v1HMAC |
|
connect.api.connectTimeout |
onlinePayments.api.connectTimeout |
10000 (ms) |
|
connect.api.socketTimeout |
onlinePayments.api.socketTimeout |
10000 (ms) |
|
connect.api.maxConnections |
onlinePayments.api.maxConnections |
10 |
|
connect.api.integrator |
onlinePayments.api.integrator |
<none> |
| connect.api.https.protocols | onlinePayments.api.https.protocols | TLSv1.2 |
|
connect.api.proxy.uri |
onlinePayments.api.proxy.uri |
<none, optional> |
|
connect.api.proxy.username |
onlinePayments.api.proxy.username |
<none, optional> |
|
connect.api.proxy.password |
onlinePayments.api.proxy.password |
<none, optional> |
|
connect.api.shoppingCartExtension.creator |
onlinePayments.api.shoppingCartExtension.creator |
<none, optional> |
|
connect.api.shoppingCartExtension.name |
onlinePayments.api.shoppingCartExtension.name |
<none, optional> |
|
connect.api.shoppingCartExtension.version |
onlinePayments.api.shoppingCartExtension.version |
<none, optional> |
|
connect.api.shoppingCartExtension.extensionId |
onlinePayments.api.shoppingCartExtension.extensionId |
<none, optional> |
PHP classes
The Direct SDK follows the OpenAPI specification of Direct. Due to this several classes and API methods have gotten a new name and the structure has been changed. The Direct API is documented here.
Namespace move
With the migration to Direct all classes have been moved to a new namespace. This affects all imports of the SDK. The "Ingenico\Connect\Sdk" part has been changed to "OnlinePayments\Sdk", the structure in the "Domain" namespace has been flattened, and the API clients in the Ingenico\Connect\Sdk\Merchant namespace have been moved to their respective subnamespaces and their names now have the "Client" postifx.
Examples:
| Connect | Direct |
|---|---|
| Ingenico\Connect\Sdk\Communicator | OnlinePayments\Sdk\Communicator |
| Ingenico\Connect\Sdk\Merchant\Products | OnlinePayments\Sdk\Merchant\Products\ProductsClient |
| Ingenico\Connect\Sdk\Domain\Payment\CreatePaymentRequest | OnlinePayments\Sdk\Domain\CreatePaymentRequest |
| Ingenico\Connect\Sdk\Domain\Payment\Definitions\CardPaymentMethodSpecificInput | OnlinePayments\Sdk\Domain\CardPaymentMethodSpecificInput |
| Ingenico\Connect\Sdk\Domain\Definitions\Card | OnlinePayments\Sdk\Domain\Card |
The following regular expressions (in the given order) can be used to update all imports of Connect namespaces to Direct:
| RegEx for finding | RegEx for replacing |
|---|---|
| "^use Ingenico\\Connect\\Sdk\\Domain\\.*\\([a-zA-Z]+);" | "use OnlinePayments\\Sdk\\Domain\\$1;" |
| "^use Ingenico\\Connect\\Sdk" | "use OnlinePayments\\Sdk" |
Note that updating namespaces will not fix all issues. Some classes and methods have been renamed, and some functionality is not (yet) available. Other chapters list these changes.
Abstraction
For the domain classes all shared base classes have been removed.
For the client classes interfaces have been introduced (mostly for testing purposes).
Clients
Renames
The table below lists all renamed classes in the "OnlinePayments\Sdk\Merchant" namespace and the renamed Merchant class. An 'x' preceding the Direct class indicates the namespace hasn't changed.
| Connect merchant class | Direct merchant class |
|---|---|
| Merchant | Merchant\MerchantClient |
| Merchant\Hostedcheckouts | Merchant\HostedCheckout\HostedCheckoutClient |
| Merchant\Payments | Merchant\Payments\PaymentsClient |
| Merchant\Payouts | Merchant\Payouts\PayoutsClient |
| Merchant\Productgroups | Merchant\ProductGroups\ProductGroupsClient |
| Merchant\Productgroups\FindProductgroupsParams | Merchant\ProductGroups\GetProductGroupsParams |
| Merchant\Productgroups\GetProductgroupParams | Merchant\ProductGroups\GetProductGroupParams |
| Merchant\Products | Merchant\Products\ProductsClient |
| Merchant\Products\DirectoryParams | x\GetProductDirectoryParams |
| Merchant\Products\FindProductsParams | x\GetPaymentProductsPrams |
| Merchant\Products\GetProductParams | x\GetPaymentProductParams |
| Merchant\Products\NetworkParams | x\GetPaymentProductNetworksParams |
| Merchant\Services | Merchant\Services\ServicesClient |
| Merchant\Sessions | Merchant\Sessions\SessionsClient |
| Merchant\Tokens | Merchant\Tokens\TokensClient |
Most of the client methods have been renamed. Please be aware that some method are available only in Connect SDK and they are not present in the Direct SDK (Ex. PaymentsClient → find, PaymentsClient → thirdPartyStatus, PaymentsClient → processchallenged etc.). On the other hand, there are methods that are present only in the Direct SDK (Ex. PaymentsClient → getPaymentDetails, PaymentsClient → subsequentPayment etc.)
| Connect client method | Direct client method |
|---|---|
| HostedCheckoutClient | |
| create | createHostedCheckout |
| get | getHostedCheckout |
| PaymentsClient | |
| create | createPayment |
| get | getPayment |
| complete | completePayment |
| cancel | cancelPayment |
| refund | refundPayment |
| capture | capturePayment |
| captures | getCaptures |
| refunds | getRefunds |
| PayoutsClient | |
| create | createPayout |
| get | getPayout |
| ProductGroupsClient | |
| find | getProductGroups |
| get | getProductGroup |
| ProductsClient | |
| find | getPaymentProducts |
| get | getPaymentProduct |
| directory | getProductDirectory |
| networks | getPaymentProductNetworks |
| SessionsClient | |
| create | createSession |
| TokensClient | |
| create | createToken |
| get | getToken |
| delete | deleteToken |
Changed APIs
Unavailable payment methods
The following payment / refund / payout methods are not (yet) supported by Direct:
Bank transfer- Cash
- EInvoice
- Invoice
Direct Debit (Both SEPA and non-SEPA)
All related fields and classes have been removed accordingly (eg. BankTransferPaymentMethodSpecificInput, BankAccount, CashPaymentProduct1503SpecificInput, and EInvoicePaymentMethodSpecificOutput).
Changed request and response payloads
Some changes have been made to the request and response fields of specific API methods. Most notably most deprecated Connect fields have been removed and some fields are not yet or no longer available.
In this table most of the fields removed in the SDK have been gathered. The table only lists fields that were documented on the Worldline version of the Connect API reference. Fields marked yellow are deprecated in the Connect API.
| Containing class | Removed field | Class of removed field | Note |
|---|---|---|---|
| AdditionalOrderInput | level3SummaryData | Level3SummaryData | Deprecated |
| AirlineData | isRegisteredCustomer | Deprecated | |
| AirlineFlightLeg | serviceClass | Deprecated | |
| BrowserData |
innerHeight | ||
| innerWidth | |||
| javaScriptEnabled | |||
| CancelPaymentResponse | cardPaymentMethodSpecificOutput | CancelPaymentCardPaymentMethodSpecificOutput | |
| CardPaymentMethodSpecificInput | recurringPaymentSequenceIndicator | Deprecated | |
| requiresApproval | |||
| CardPaymentMethodSpecificInputBase | recurringPaymentSequenceIndicator | Deprecated | |
| requiresApproval | |||
| skipAuthentication | Deprecated | ||
| CreateHostedCheckoutRequest | sepaDirectDebitPaymentMethodSpecificInput | SepaDirectDebitPaymentMethodSpecificInputBase | |
| CreatePaymentRequest | sepaDirectDebitPaymentMethodSpecificInput | SepaDirectDebitPaymentMethodSpecificInput | |
| CreatedPaymentOutput | displayedData | DisplayedData | |
| paymentCreationReferences | PaymentCreationReferences | ||
| tokenizationSucceeded | |||
| tokens | |||
| Customer | shippingAddress | AddressPersonal | Deprecated |
| CustomerToken | merchantCustomerId | ||
| vatNumber | Deprecated | ||
| FraudFields | addressesAreIdentical | Deprecated | |
| cardOwnerAddress | Address | Deprecated | |
| deviceFingerprintActivated | Deprecated | ||
| shippingDetails | FraudFieldsShippingDetails | Deprecated | |
| HostedCheckoutSpecificInput | returnCancelState | ||
| validateShoppingCart | |||
| LineItem | level3InterchangeInformation | LineItemLevel3InterchangeInformation | Deprecated |
| LineItemInvoiceData | merchantLinenumber | ||
| merchantPagenumber | |||
| nrOfItems | |||
| pricePerItem | |||
| MerchantAction | formFields | List<PaymentProductField> | |
| renderingData | |||
| showData | List<KeyValuePair> | ||
| Order | items | List<LineItem> | Deprecated |
| OrderLineDetails | lineAmountTotal | ||
| productCategory | |||
| PaymentProduct | autoTokenized | ||
| canBeIframed | |||
| deviceFingerprintEnabled | |||
| fieldsWarning | |||
| isJavaScriptRequired | |||
| mobileIntegrationLevel | |||
| PaymentProduct771SpecificOutput | mandateReference | ||
| PaymentProduct840CustomerAccount | billingAgreementId | ||
| contactPhone | |||
| PaymentProductFiltersHostedCheckout | tokensOnly | ||
| PaymentProductGroup | accountsOnFile | List<AccountOnFile> | |
| deviceFingerprintEnabled | |||
| fields | List<PaymentProductField> | ||
| PaymentReferences | referenceOrigPayment | ||
| PersonalName | surnamePrefix | ||
| PersonalNameToken | surnamePrefix | ||
| RedirectPaymentMethodSpecificInput | expirationPeriod | ||
| isRecurring | |||
| recurringPaymentSequenceIndicator | |||
| returnUrl | Deprecated | ||
| RedirectPaymentMethodSpecificOutput | paymentProduct3201SpecificOutput | PaymentProduct3201SpecificOutput | |
| RedirectPaymentProduct809SpecificInput | expirationPeriod | Deprecated | |
| RedirectPaymentProduct840SpecificInput | custom | Deprecated | |
| isShortcut | |||
| RedirectionData | variant | ||
| SessionRequest | paymentProductFilters | PaymentProductFiltersClientSession | |
| SessionResponse | region | Deprecated | |
| ThreeDSecure | authenticationAmount | AmountOfMoney | |
| authenticationFlow | |||
| ThreeDSecureBase | authenticationAmount | AmountOfMoney | |
| ThreeDSecureResults | acsTransactionId | ||
| appliedExemption | |||
| authenticationAmount | AmountOfMoney | ||
| schemeRiskScore | |||
| ValueMappingElement | displayName | Deprecated |
Removed APIs
Not all APIs and API methods of Connect are supported by Direct at the moment. Their corresponding clients and client methods have been removed from the Direct PHP SDK.
When an API or API method becomes supported by Direct its corresponding Client or client method will be re-introduced to the SDK.
The tables below lists all Connect clients and client methods that have been removed from the Direct PHP SDK. For each removed class its corresponding Merchant method and all corresponding request and response classes have also been removed.
Not all Connect APIs and API methods were available for Connect merchants on the Worldline platform. These have been underlinded and marked yellow. it is unlikely that these are used by your platform.
| Unavailable API | Removed Connect class | Removed Merchant method |
|---|---|---|
| Captures | Captures | Merchant.captures() |
| Disputes | Disputes | Merchant.disputes() |
| Files | Files | Merchant.files() |
| Hosted Mandate Management | Hostedmandatemanagements | Merchant.hostedmandatemanagements() |
| Mandates | Mandates | Merchant.mandates() |
| Refunds | Refunds | Merchant.refunds() |
| Risk assessments | Riskassessments | Merchant.riskassessments() |
Removed API methods
| Unavailable API method | Corresponding client method |
|---|---|
| Payments > Approve payment | PaymentsClient.approve |
| Payments > Undo capture payment | PaymentsClient.cancelapproval |
| Payments > Create dispute | PaymentsClient.dispute |
| Payments > Get disputes | PaymentsClient.disputes |
| Payments > Get device fingerprint details | PaymentsClient.devicefingerprint |
| Payments > Find payments | PaymentsClient.find |
| Payments > Approves challenged payment | PaymentsClient.processchallenged |
| Payments > Third party status | PaymentsClient.thirdPartyStatus |
| Payments > Create a token from payment | PaymentsClient.tokenize |
| Payouts > Find payouts | PayoutsClient.find |
| Payouts > Approve payout | PayoutsClient.approve |
| Payouts > Cancel payout | PayoutsClient.cancel |
| Payouts > Undo approve payment | PayoutsClient.cancelapproval |
| Product Groups > Get device fingerprint | ProductGroupsClient.deviceFingerprint |
| Product > Get customer details | ProductsClient.customerDetails |
| Product > Get device fingerprint | ProductsClient.deviceFingerprint |
| Product > Create payment product session | ProductsClient.sessions |
| Services > Convert amount | ServicesClient.convertamount |
| Services > Convert bankaccount | ServicesClient.bankaccount |
| Services > Get IIN details | ServicesClient.getIINdetails |
| Services > Get Privacy Policy | ServicesClient.privacypolicy |
| Tokens > Approve SEPA DD mandate | TokensClient.approvesepadirectdebit |
| Tokens > Update token | TokensClient.update |
Domain
Below are the classes in the OnlinePayments\Sdk\domain namespace that have been renamed. Note that the namespace changes mentioned in the "Namespace move" chapter are omitted here.
| Connect domain class | Direct domain class |
|---|---|
| CreateTokenResponse | CreatedTokenResponse |
| Directory | ProductDirectory |
| PaymentProductGroups | GetPaymentProductGroupsResponse |
| PaymentProducts | GetPaymentProductsResponse |
Other renames
Excluding the domain and merchant namespaces only one class has been renamed.
| Connect class | Direct class |
|---|---|
| GlobalCollectException | PaymentPlatformException |