Although caching of the authentication token can improve performance it is important to check for potential caching related rejections of requests. This may result from expired tokens being served from your cache for requests, particularly during initial sprints focused on integration.
Integration Journey
Last changes: 10-26-2022
The services are provided by J.P. Morgan Mobility Payments Solutions S.A., an Electronic Money Institute (EMI) and a Joint Venture of J.P. Morgan and Volkswagen Financial Services AG.
Together with its subsidiary, J.P. Morgan Mobility Payments Systems GmbH (MPS), the company develops and coordinates payment solutions for the Volkswagen Group brands and thus manages the global payment activities of Volkswagen Financial Services. MPS provide the innovative technical solutions enabling digital payments.
After first contact and relationship is established with the EMI, MPS assigns a Payment Solutions Specialist (PSS) to your integration project. As your principal point of contact for the project, he/she coordinates the integration and regularly schedules meetings to guarantee a consistent and successful implementation.
A well prepared business use-case often advances the subsequent technical integration significantly. Therefore, we recommend to define your business use-case as precise as possible. This also serves as the general basis for the decision on one of our payment solutions:
Typical information regarding your business use-case is:
- Business model (e.g. B2B or B2C)
- Customer profile (e.g. regular or guest)
- Objective (e.g. improve customer checkout experience)
Furthermore, it is important to explicitly specify your business requirements, e.g.
- Supported currencies (e.g. Euro)
- Supported payment methods (e.g. credit card)
- Number of merchant accounts
- Additional services (see Ancillary services)
In the Project Meeting we will discuss your business case and arrange a schedule concerning the following steps, e.g. technical kick-off meeting.
Our sandbox is an essential tool to test your integration, which mimics the live production environment. After you received the credentials, the sandbox environment allows you to call API methods and simulate payment scenarios without performing any real transaction or touching live accounts. We recommend to request a sandbox account before starting with the actual integration.
Our JSON RESTful API uses HTTP methods to transmit data and access resources via URLs. Furthermore, REST is language-independent and can be implemented in any programming language which can make web-based requests using HTTP.
Technical details and questions regarding the integration will be addressed in the Technical Kick-off Meeting.
Implement the payment process for each payment option (e.g. credit card) accordingly to the documentation (e.g. Guest Payment). A detailed description of all API methods can be found in the API Reference.
A web client integration must include an authentication token as part of the HTTP header for all but a few anonymous API methods. Use the provided credentials when requesting an authentication token via the API method 1.45 Issue Token.
The response will include the JWT authentication token under the return parameter "token" which you include in the HTTP header when calling other API methods via the custom header field "X-Auth-Token".
Please note, that authentication tokens have a limited validity period - their expiration time (UTC) is communicated to you via the return parameter "validUntil". The token can be used until the expiration time and should be replaced by a new one shortly before the expiration. By persisting the token alongside the expiration time, it is possible to call multiple API methods with the same token until it expires. It is recommended that tokens are reused instead of requested for each API method call in order to avoid a perception of a performance issue in web applications.
If applicable, use the credits cards provided in the section Test Cards.
Please note, that these cards are solely intended for testing purposes. Do not use them outside of test systems!
Especially in the early stages of an integration, systems can be prone to bugs and errors. The parameter “partnerReference” is part of every API method and serves debugging purposes by identifying individual API requests. Therefore, we highly recommend to choose varying and meaningful values to make full use of this parameter.
To easily distinguish your API calls from other requests, we will assign a unique PID to your test and production environment. Hence, a possible “partnerReference” could look as follows:
PID-001DE_CUSTID-KD97TH2FP6_CARTID-PYQRTGMCMQ_VGT284FYXV
To further assist with troubleshooting of any potential issues, all API Responses (excluding some HTTP 500 Errors) will return an "additionalInformation" object, containing the below information:
- "requestId" - Globally Unite Identifier created for each API Request accepted by KontoCloud.
This value must be provided, along with the "partnerReference", when contacting support. - "unrecognizedFields" - Array of all API Request Parameters that have not been recognized.
After you integrated all necessary API methods and tested your implementation, our technical support will analyze the integration and ascertain if it meets all requirements. The results of this analysis and possible gaps will be addressed in the Go-Live Assessment. All closed gaps are subsequently verified in a Go-Live Reassessment.
Following this, you can request a production environment and set a Go-Live Readiness Date.
In contrast to the sandbox, the production environment only allows API calls from a specific list of IPs, thus ensure IP-Whitelisting of your production server.
Switch the API and SDKs to production:
- Identifiers: Update Merchant Account, Program Account and Program Code.
- API Base URL: Change the base URL in your API requests to the corresponding URL of the production environment.
- API Authentication: Replace username and password of the sandbox account with the production environment credentials.
- SDKs: Switch the “paymentProviderMode” from “test” to “live”.
- SDKs: Switch to using the Minified JavaScript Library (Recommended).
In the case of no complication during this process, the Go-Live can take place on the Go-Live Readiness Date.