Issuin icon

Reveal a PIN using secured sessions

Allow your cardholders to reveal a PIN using secured sessions with end-to-end encryption.

See our SDK

  View the repository for our SDK on Github:

Adyen Issuing SDK for iOS

You can allow your cardholders to access the PIN of their Adyen-issued card within your app. Secured sessions use end-to-end encryption between your client and Adyen, without exposing sensitive card data to your server.

This page explains how to use secured sessions and the Adyen Issuing SDK for iOS to securely reveal PINs in your user interface.

Requirements

Before you begin, take into account the requirements, preparations, and limitations for iOS applications.

Requirement Description
Integration type Your integration must support Adyen Issuing.
API credentials Make sure that you have an API credential for the Session authentication API. Your API credential must have the following role:
  • PaymentInstrument: Pin Reveal
Setup steps
  1. Check the latest iOS, Swift, and Xcode version requirements for using the Adyen Issuing SDK.
  2. Get an application certificate from Adyen.
  3. Integrate the Adyen Issuing SDK for iOS applications.
  4. Follow the prerequisites specified in the starting guide.

Secured sessions with Adyen

With secured sessions, your server creates a session with specific permissions and scope. Your client uses this session to communicate directly with Adyen through the SDK.

The Adyen Issuing SDK for iOS allows you to retrieve the PIN from Adyen. Additionally, it automatically handles all cryptographic operations, such as exchanging keys, encrypting, and decrypting the PIN.

Secured sessions with the SDK offer the following benefits:

  • Your server never handles sensitive PIN data.
  • Sessions are scoped to a specific card and operation.
  • Sessions are single-use, which prevents replay attacks.
  • End-to-end encryption between the SDK and Adyen protects data in transit.

How it works

The following diagram illustrates the PIN reveal flow using sessions.

Sequence diagram for revealing PIN with sessions

As shown in the diagram, the steps for revealing the PIN are:

  1. Load the application certificate when your application starts.
  2. Create a session instance.
  3. Reveal the PIN.
  4. Show the PIN in your user interface.

1. Load the application certificate

Adyen provides you with an application certificate that you need to initialize the Adyen Issuing SDK. The SDK uses this certificate to establish a secure session with Adyen.

When your application starts, load the application certificate into your application.

2. Create a session instance

When a cardholder using your application selects the option to reveal the PIN, you must initialize the SDK. During initialization, you configure all objects and logic that handle your secure session with Adyen.

To initialize a card session using the Adyen Issuing SDK:

  1. Create an instance of CardSessions.Configuration. Include the following parameters:

    • appCertificate: The certificate that you loaded when your application started.
    • environment: The target environment, either .test or .live.
  2. Define a token provider that retrieves the session token from Adyen, and then passes it from your backend to your client application.

  3. Initialize an instance of CardSession that creates a secure session with Adyen and retrieves a session token. Include the following:

    • In the parameters field, pass the CardSessions.Configuration object that you created.
    • In the tokenProvider field, pass an instance of the token provider that you defined.

3. Reveal the PIN

After you initialize the SDK, you can create a secured session. Start the flow for a secured session by calling the CardSession.revealPin SDK method. This method instructs the backend to make a request to our Session authentication API. Then, the SDK method retrieves the session data from the backend and returns it to your application.

To create a secured session:

  1. From your client application, call the session instance that you created. Pass the payment instrument ID of the card as the paymentInstrumentId parameter.
    This method instructs the backend to make a request for a session.

  2. From your backend, make a POST /sessions request with the following parameters:

    Parameter Required Description
    product Required Set to platform.
    policy.resources.type Required Set to paymentInstrument.
    policy.resources.paymentInstrumentId Required The unique identifier of the payment instrument that the session applies to.
    policy.roles Required An array of roles that define the allowed operations. Include the PaymentInstrument: Pin Reveal role.
  3. Verify that the response contains a session token.

  4. Pass the token from your backend to the SDK. Use the token provider that you defined when you initialized the SDK.

If the request is successful, the SDK uses the token to establish a secure session with Adyen. The SDK uses the secure session to get the encrypted PIN from Adyen. Then, the SDK decrypts the PIN automatically. You do not need to make additional calls.

4. Show the PIN in your user interface

After the SDK receives the session token from the backend, the CardSession.revealPin method returns a string that includes the decrypted PIN.

To reveal the decrypted PIN in your user interface:

  1. Pass the decrypted PIN to your app.
  2. Reveal the PIN to your cardholder in your user interface.

After you reveal the PIN, delete it from your app's memory.

Troubleshooting

The following table describes errors that the SDK can return and how to solve them.

Error Description Solution
Session expired The session token has expired. Create a new session from your server.
Unauthorized The session does not have the required role for the requested operation.
Forbidden The payment instrument ID does not match the ID provided in the POST /sessions request. Verify that the payment instrument ID matches the ID provided in the POST /sessions request.

See also