commercetools / commercetools-payone-integration

Integration between commercetools eCommerce API and Payone payment service provider API.
https://dev.commercetools.com/
MIT License
7 stars 8 forks source link
commercetools hacktoberfest payments payone

commercetools <-> PAYONE Integration Service

Build Status codecov Docker Pulls

This software provides an integration between the commercetools eCommerce platform API and the PAYONE payment service provider (server API).

It is a standalone Microservice that connects the two platforms and provides a small own helper API to force immediate handling of a payment.

Supported payment methods

The PAYONE Integration Service currently supports the following payment methods:

Running service and configuration

Required Configuration in the commercetools project

Domain Constraints

If the PAYONE invoice generation feature or the Klarna payment methods are to be supported, the checkout has to make sure that amountPlanned = Sum over all Line Items ( round ( totalPrice.centAmount / quantity ) * quantity )) and handle deviations accordingly.
Deviations can especially occur if absolute discounts are applied and there are Line Items with quantity > 1.
On deviations the Line Item Data will not be transferred to PAYONE.

Required Configuration in PAYONE

https://pmi.pay1.de/

Do not use a merchant account across commercetools projects, you may end up mixing customer accounts (debitorenkonten).

Configuration of the Integration Service

The integration service requires - unless otherwise stated - the following environment variables or Java runtime arguments. Note, Java runtime arguments, e.g. those supplied with -D prefix, have precedence over environment variables with the same name.

Mandatory common properties

Name Content
TENANTS comma or semicolon separated list of alphanumeric unique tenant names. At least one name is required. Whitespaces are ignored. Besides underscore no special characters are allowed. Note: provided tenant names will be used as part of handle/notification URLs.

Note: the tenant names are used as a part of URI, thus use only characters allowed for path part of an URI. We strongly recommend not to use special or Unicode characters and limit the set with [a-Z0-9_-]

Mandatory commercetools API client credentials

All these properties must be set for every tenant name described in TENANTS property above.

Name Content
TENANT1_CT_PROJECT_KEY the project key
TENANT1_CT_CLIENT_ID the client id
TENANT1_CT_CLIENT_SECRET the client secret

Can be found in commercetools Admin Center.

PAYONE API client credentials

All these properties must be set for every tenant name described in TENANTS property above.

Name Content Required
TENANT1_PAYONE_PORTAL_ID Payment portal ID Yes
TENANT1_PAYONE_KEY Payment portal key Yes
TENANT1_PAYONE_MERCHANT_ID Merchant account ID Yes
TENANT1_PAYONE_SUBACC_ID Subaccount ID Yes
TENANT1_PAYONE_MODE Payment mode No

These values can be found in the PAYONE Merchant Interface.

Optional service configuration parameters
Name Is tenant specific Content Default
TENANT1_PAYONE_MODE Yes the mode of operation with PAYONE
  • "live" for production mode, (i.e. actual payments) or
  • "test" for test mode
"test"
TENANT1_CT_START_FROM_SCRATCH Yes WARNING Handle with care! If and only if equal, ignoring case, to "true" the service will create the custom types it needs. Therefor it first deletes all Order, Cart, Payment and Type entities. If not yet in the project, the Custom Types are created independently of this parameter (but only deleted and recreated if this parameter is set). Related: issue #34. "false"
TENANT1_SECURE_KEY Yes if provided and not empty, the value is used as the key for decrypting data from fields "IBAN" and "BIC" for payments with CustomType "PAYMENT_BANK_TRANSFER". The data must be the result of a Blowfish ECB encryption with said key and encoded in HEX. "" (empty String)
TENANT1_UPDATE_ORDER_PAYMENT_STATE Yes if true - Order#paymentState will be updated when payment status notification is received from Payone. By default the order's state remains unchanged. See Order Payment Status Mapping for more details. "false"
TENANT1_CT_AUTH_URL Yes if set, this value will be used for authentication by the sphere client. "https://auth.europe-west1.gcp.commercetools.com"
TENANT1_CT_API_URL Yes if set, this value will be used as the API endpoint by the sphere client. "https://api.europe-west1.gcp.commercetools.com"
HIDE_CUSTOMER_PERSONAL_DATA No if true - all customer related personal data will be replaced by <HIDDEN> placeholder in all logs. If false - all customer related personal data will be visible in logs. "true"
LOG_LEVEL No log-level for service logging "INFO"

Docker run

docker run \
    -e TENANTS=TENANT1
    -e TENANT1_CT_CLIENT_ID=xxx \
    -e TENANT1_CT_CLIENT_SECRET=xxx \
    -e TENANT1_CT_PROJECT_KEY=xxx \
    -e TENANT1_PAYONE_KEY=xxx \
    -e TENANT1_PAYONE_MERCHANT_ID=xxx \
    -e TENANT1_PAYONE_MODE=test|live \
    -e TENANT1_PAYONE_PORTAL_ID=xxx \
    -e TENANT1_PAYONE_SUBACC_ID=xxx \
commercetools/commercetools-payone-integration

Shop integration guide

List of actions which needs to be covered by front end integration.

Multitenancy

Starting from version 2 a single service instance may be used for multiple tenants, e.g. same service for different shop, merchants or suppliers. The next configuration properties are required for this:

When the service is started it initializes separate URL handlers for all specified tenants:

Other resources

For developers and contributors

Read Project lifecycle documentation for full information.