Skip to content
This repository has been archived by the owner on May 24, 2023. It is now read-only.

Latest commit

 

History

History
149 lines (104 loc) · 9.12 KB

IntegrationGuide.md

File metadata and controls

149 lines (104 loc) · 9.12 KB
Raw

commercetools Paypal Plus Service Integration Guide

This documentation describes how to setup, start and use commercetools-paypal-plus-integtration-java service.

Setup docker container

Preparing Paypal Plus accounts

Preparing commercetools Platform accounts

Configuration

Application on startup will try to load the required configuration as environment variable named "SPRING_APPLICATION_JSON" :

SPRING_APPLICATION_JSON={"tenantConfig":{"tenants":{"my-commercetools-projectkey1":{"ctp":{"projectKey":"my-commercetools-projectkey1","clientId":"xxx","clientSecret":"xxx"},"paypalPlus":{"id":<your-paypal-plus-id>,"secret": <your-paypal-plus-secret>,"mode": "sandbox"}},"my-commercetools-projectkey2":{"ctp":{"projectKey":"my-commercetools-projectkey2","clientId":"xxx","clientSecret": "xxx"},"paypalPlus":{"id": <your-paypal-plus-id>,"secret":<your-paypal-plus-secret>,"mode":"sandbox"}}}},"ctp.paypal.plus.integration.server.url":<The URL of this deployed paypal integration application>}
  • The JSON string should NOT be formatted.
  • Be careful that variables like project key, paypal plus account ID and so on are within the above JSON string. Please change it appropriately before the usage.

CTP custom types synchronization on startup

The service itself expects some required CTP Types configured on the tenants' projects. Since version 0.2.0 it is possible to perform automatic custom types creating/updating if some values are missing.

The expected types configurations are stored in the project resources directory /src/main/resources/ctp/types/

When the service is starting, it validates the actual custom types of every tenant:

  • if at least one custom type of at least one tenant is misconfigured and can't be updated automatically — the service will log the error message and exit
  • if some tenants/types could be automatically updated — update them and continue the service

In case of Unrecoverable errors (which cause service exit) the respective CTP project must be re-configured manually according to expected types configuration described above.

Unrecoverable errors are:

If the projects don't have any unrecoverable errors - try to find and fix recoverable mismatches.

Recoverable mismatches of the types configurations are:

  • some types are completely missing — create them from scratch
  • some field definitions in a Type are missing — add missing fields to respective Types
  • EnumType/LocalizedEnumType fields have some missing values (key names) - add missing enum entries.

All redundant/superfluous Types/Field Definitions/Enum Values are ignored and remain unchanged.

Also, note, some Type and FieldDefinition values are not important for the server, so they are never verified/updated (for example, Type name, Type description; Field Definition labels, input hints and so on).

If all the types synced successfully or already up-to-date - the service continues starting up.

Prevent shipping (delivery) address change in Paypal Payment Dialog

There is still not clear what is correct/recommended/document way to prevent buyer's address change on the approval page (when the buyer is redirected). As discussed with support (Kristian Büsch) there are 2 possible solutions:

  1. (Recommended, but not documented yet): using Payment#application_context#shipping_preference value. The field should be set to SET_PROVIDED_ADDRESS value.

    Note:

  2. (Documented, but not recommended way since it could be deprecated soon): using payments experience profile.

    1. Create payment experience profile in the Paypal Merchant account with input_fields#address_override=1 (Note, our commercetools-paypalplus-integration service does not expose such endpoint, it should be created directly using Paypal API)

    2. Set the id of created web profile to experienceProfileId custom field of every payment handled by our service.

    3. The shipping address must be set before user is redirected to the approval page. If this is a default payment type - patch endpoint should be used after payment is created, but before buyer is redirected to the approval page.

Right now our commercetools-paypalplus-integration service support both ways, so any of properties described above will be sent to PayPal Plus API if it is specified in a CTP Payment custom field.

Create default payments

Defaults payments are Credit Card, Paypal, Invoice.

Create installment (Ratenzahlung) payments

Installment payment type requires different workflow because of especial security requirements from Paypal Plus.

  1. CTP (PaymentMethodInfo#method) must be installment, see CtpPaymentMethods#INSTALLMENT

  2. The respective cart (connected to the payment) must have customer's real billing and shipping addresses - they will be verified by Installment (Ratenzahlung) system.

    • Billing Address is send during create payment, it is not recommended to send during patch (e.g. don't patch address after success redirect)
    • Shipping address is under seller’s protection, so this should NOT be changed (e.g. not patched at all)

  3. After redirect to success page - look up the payment (get payment by ID) and if there are inconsistencies (different amount, address, line items etc) - reinitialize the whole payment process.

  4. If user accepts the conditions of the payment and clicks approval button - execute payment like in normal workflow.

  5. See more in Integration Requirements for Installments Germany internal document.