1.) Account configuration
Step 1: Register an account
Create your free payever account here, or login in case you already have one.
Step 2: Configure payment options
In order to configure your payment options, first open the Checkout app. To do this, either click on the Checkout symbol under Business Apps or click on the Manage or Open button on the Checkout section.
You can find the payment methods tab in the navigation bar on the left.
Then click on + Add.
Now a list of different payment methods appears, from which you can select as needed. To do this, click on install.
Once you have installed the payment channel, click on Open and a new page will open, the structure of which will vary depending on the payment method chosen.
With the payment methods credit card, direct debit, Sofortüberweisung and Paypal just click the Connect button and you will be forwarded to the respective payment provider. There you connect your existing account or create a new one.
For the payment methods Installments, invoice, Factoring and Direct Bank Transfer you have to enter the access data that you have received from Santander and then click on Connect (if you have not been in touch with Santander before, please contact support@payever.de).
Regardless of the payment method, please make sure that you always enter your access data in the Default tab.
After you have connected the payment methods, you can make changes to the settings of the specific payment method. Please refer to our documentation for the specific payment method for more information, which you can find here.
Step 3: Configure channels
Select the Channels tab in the Checkout App.
Click + Add.
Select Commercetools from the list that now appears and click on Install.
Now you need to click Open so that you can generate the API keys in the next step.
Select API keys and click on + Add. Enter a name of your choice and click on Generate. Afterwards, click on the plus icon (+) and you see the credentials that you have to insert into the added connection that you use for your online business (i.e., Client Id, Client secret, Business UUID). Please copy these to your clipboard.
Select Credentials and click on Add Connection. Enter a name of your choice and fill out your Commercetools Project Key, Client Id and Secret. The copied Client Id, Secret and Business UUID from the previous step, can be inserted in the payever related fields. Choose your callback URLs to decide the customer landing pages for specific payment scenarios and select when to create an order Commercetools. Afterwards, click on Connect and you see your added connection.
2.) Technical integration guide
In order to use the payever gateway integration with commercetools, please follow this integration guide to make sure your implementation and process works as needed.
Terms used in this guide:
- Shopper - a person that's using the shop
- Browser - frontend part of the checkout UI (webshop)
- Merchant server - backend part of the checkout
Roughly summarised, this manual will guide you through the following steps:
- Step 1: commercetools checkout validations
- Validate cart state
- Recalculate cart
- Validate payment
- Validate payment transaction
- Step 2: Create a commercetools payment
- Step 3 (optional): Get available payment methods
- Step 4: Create a payever payment
- Step 5: Order actions (capture, cancel, refund)
- Step 6: Implement error handling
- Extension module errors
- Shopper tries to pay a different amount than the actual order amount
Step 1: commercetools checkout validations
The merchant server should execute the following validations:
- On each checkout step: #validate-cart-state
- Only before starting a new payment process (to make sure there are no paid payments on the cart already):
- #recalculate-cart
- #validate-payment
- #validate-payment-transaction
Validate cart state - Check if current cart has been ordered already/ if the cart already has status "ordered" (Cart.cartState = Ordered). This might happen if the cart has been already ordered in a different tab (edge case) or by an optional asynchronous process like commercetools-payment-to-order-processor job.
Recalculate Cart -Execute cart recalculate to ensure that cart totals are always up-to-date, and that time-limited discounts are eventually removed from the cart (discounts are validated on re-calculate and order creation only).
Validate Payment - There must be at least one commercetools payment object of type payever (`Payment.paymentMethodInfo.paymentInterface = ctp-payever-integration`).
Validate Payment Transaction - Cart's payment counts as successful if there is at least one payment object with successful transaction state (Payment.Transaction.state=Success) and transaction type Authorization or Charge.
Step 2: Create a commercetools payment
Before the actual payment process, commercetools payment resource needs to be created by the merchant server.
In the commercetools platform, the payment merely represents a container of the current state of receiving and/or refunding money. The actual financial process is performed behind the scenes by the extension module which processes commercetools payment payload supplied by the merchant server and exchanges it with payever API.
The commercetools payment does not contain all the required payever specific fields by default, so those have to be set up as custom fields via a payment method-specific payment type.
The following fields will need to be set up for using payever payment options:
Field name | Value |
amountPlanned | Amount that this payment intends to receive from the customer. Usually this would be the total cart value/ the gross order total. |
paymentMethodInfo.paymentInterface | ctp-payever-integration |
custom.type.key | ctp-payever-integration-payment-type |
custom.fields.payeverBusinessUuid | Your payever Business UUID as a custom field called payeverBusinessUUID |
custom.fields.commercetoolsProjectKey | Your commercetools project key as a custom field called commercetoolsProjectKey |
If the required fields above are missing, the payment creation will be rejected.
This is an example of how you would create a commercetools payment draft from scratch:
{
"countryCode":"DE",
"currencyCode":"EUR",
"amount":10000
}
Please refer to the List Payment Options section in our general API documentation in order to see a response code example.
This is an example of the commercetools payment representation with getPaymentMethodsRequest: