No momento, esta página não está disponível em português
Default icon

Solution flows

Secure communications, key loading, and transaction flows.

This chapter gives an overview of data flows that take place within our mobile payments solution.

Mutual authentication

This section describes the mutual authentication step that establishes a secure communications channel between our SDK and the Adyen servers. For context, see Communication flow.

The authentication process is a prerequisite for any direct communication between the SDK and the Adyen backend. The process provides the SDK with a temporary session token, which is used to assure mutual authentication between the SDK and the Adyen servers for all direct communications.

The following diagram and steps give an overview of the authentication process.

Check if the next diagram is OK to use for iOS

  1. Generate a setup token.
    The SDK gathers the following information about itself and the COTS device:

    • App ID: package name
    • Installation ID: generated UUID
    • SDK and version: SDK package and version
    • Device info: iOS SDK version, device model, and name
    • Device public key: add description

    The first time that this information is gathered, the SDK generates and stores a UUID to identify this installation, and a key pair which can be used to later validate that the information is still coming from the same device. how is the key pair generated?

  2. Sign the setup token.
    The gathered information is signed using the SDK key that is embedded into our SDK and obfuscated by the white-box cryptography solution that we use what is the name of the white box? . The SDK key can be rotated for every release of the SDK and indicates that the information is coming from a legitimate source.

  3. Send the setup token to the merchant’s server.
    The merchant retrieves the signed setup token from the SDK and sends the token to their own server.

  4. Make an authentication request.
    Using their API key and setup token, the merchant sends an API request for a session to the /checkout/possdk/vxx/sessions endpoint on our Checkout server (where vxx indicates the API version number). The server uses the gathered information and the merchant’s API key to validate both the merchant and the SDK, and to identify the COTS device being used.

  5. Return a session token.
    If the validations succeed, the Checkout server generates a session token that contains a public key that the SDK can use to later authenticate responses from our server. The Checkout server returns the session token in the API response to the merchant, as the sdkData parameter value.

  6. Get the session token.
    The merchant sends the sdkData to their app and into the SDK, so that the SDK can start communicating directly with the Adyen servers.

Remote key loading

COTS devices as used in mobile payments solutions do not get loaded with an IPEK in a secure facility, as is the case with traditional payment terminals. Therefore, we load the IPEK to the COTS device remotely.

There are two endpoints that the SDK can send a key loading request to:

  • /checkoutpos/keys/pin/load for loading keys to encrypt PIN blocks
  • /checkoutpos/keys/data/load for loading keys to encrypt card data

Both these key loading endpoints work in the same way. We load separate IPEKs for card holder data and for PIN, in two independent TR-34 blocks.

The following diagram and steps give an overview of the remote key loading process:

Check if the next diagram is OK to use for iOS

  1. The SDK sends a KeyLoadingRequest containing an RSA-2048 TR-34 encryption public key (KKRD) to the relevant key loading endpoint. The request is signed by the Device key from the Keystore on the COTS device, and the RSA public key is signed with the SDK key.

  2. Information about the SDK installation (from the mutual authentication session token) is used to generate a Key Serial Number (KSN). The KSN is sent to the HSM and used to derive the IPEK from one of Adyen's Base Derivation Keys (BDK). Information on which BDK is used is embedded in the KSN.

  3. checkoutpos uses the RSA-2048 TR-34 encryption public key to generate a certificate, and sends the certificate and the public key to the HSM.
    The certificate is required by the HSM. The TR-34 specification requires certificate headers to be set, even though we currently do not perform any certificate validation in the SDK.

  4. The HSM uses the TR-34 encryption public key to encrypt the Ephemeral key (KE), which in turn is used to encrypt the IPEK.

  5. checkoutpos returns a KeyLoadingResponse, which contains both the TR-34 block with the encrypted IPEK as well as the initial KSN.

  6. On the SDK side, the TR-34 block is decrypted in the white-box environment using the SDK private key (that matches KKRD). The IPEK and KSN are used together to initialize the DUKPT state. For each transaction, the DUKPT state generates a new working key and increments the KSN. The DUKPT state is stored securely on the device.

For details about the keys mentioned here, see Cryptographic keys.

Payment flow

The Adyen backend where payments are processed, is certified under several security standards like PCI-DSS, PCI-PIN, and PCI-P2PE.

The payment flow when using Adyen's mobile payments solution is as follows:

  1. The merchant starts a payment using Tap to Pay or card reader as the payment interface.
  2. The SDK checks if there is a valid session token. If not, it re-authenticates to get a new session token.
  3. The SDK checks the configuration files, and if necessary downloads the latest configuration.
  4. The SDK checks if there are working DUKPT states for card data and PIN encryption stored locally. If not, it performs remote key loading.
  5. The SDK sends a payment request to checkoutpos and receives a list of commands to execute.
  6. The SDK loads the latest configuration into the kernel and starts the payment screen.
  7. The kernel reads the card data using the mobile device's NFC reader or the card reader, and uses the white-box cryptography library inside the SDK to encrypt the card data.
  8. The kernel returns the result of the payment, and the SDK sends the result to checkoutpos for processing.
  9. checkoutpos checks the data that was sent and if necessary initializes the PIN flow.
    If the PIN flow is initialized:
    1. The SDK receives commands to show the PIN UI. These commands contain a tokenized PAN that will be used to construct the final ISO-format 4 PIN block.
    2. The SDK sets the working DUKPT state for PIN encryption stored locally.
    3. The SDK shows the PIN UI on the mobile device, and uses the white-box cryptography library inside the SDK to encrypt the PIN data.
    4. The SDK sends the result to checkoutpos for processing.
  10. checkoutpos responds if additional processing is needed, if there is any error, or if the payment was successful.
  11. The SDK shows the outcome to the user on the screen of the mobile device.
  12. If the payment was successful, the SDK make a final capture call to checkoutpos.
  13. The SDK receives the final payment response from checkoutpos and returns it to the merchant app.

See also

Public integration documentation for external developers: