In-app quick integration

In-app quick integration

Full functionality for in-app payments
Adyen provides you with the mobile solution to simplify the way you integrate your mobile app with our payment platform. Use our SDKs for iOS and Android to benefit from the client-side encryption of sensitive payment data and significantly reduce your scope of  PCI-compliance. With Adyen, you can accept both card payments (like Visa, Mastercard, American Express) and local payments (PayPal, ACH Direct Debit, iDEAL, SEPA, and others) in your mobile applications.

Before starting with this integration, make sure that you created a test account, as described in the Getting started tutorial.

Cards

To start accepting card payments, you must first create a web service user to connect to the Adyen platform. For this:

  1. Go to Adyen Customer Area (CA), open SettingsUsersws@Company.YourCompany, and click Generate Password. Save this password for future use in a secure place.
  2. To get the public key and URL to your encryption library, locate the Easy Encryption pane and click Generate.

Then you are able to set up your mobile app and the server. The diagram below briefly explains the flow of a payment made with a card.

Client side

To enrich your mobile application with the Adyen payment API, include our SDK into your project. These steps are different for iOS and Android platforms.

For iOS, this can be done using CocoaPods, which you need to have installed on your machine.

If you already have CocoaPods, do the following:

  1. In your existing Xcode project, add this line to your Podfile:

    pod "AdyenCSE"
  2. To complete the installation, execute the following in your terminal:

    pod install
  3. To update, execute the following in your terminal:

    pod update "AdyenCSE"

For Android, you can use the de.undercouch.download plugin for downloading the binaries of the Adyen Mobile SDK.

  1. To enable this plugin, add the following code to the root directory's build.gradle file:

    buildscript {
        repositories {
            ...
        }
        dependencies {
            ...
            classpath 'de.undercouch:gradle-download-task:2.1.0'
        }
    }
  2. In the app module's build.gradle file, add the following task:

    import de.undercouch.gradle.tasks.download.Download
    
    ...
    
    task downloadAdyenLibrary(type: Download) {
        src 'https://raw.githubusercontent.com/Adyen/AdyenCSE-Android/master/adyencse/adyencse-1.0.0.aar'
        dest('libs');
    }
  3. Run this task using ./gradlew downloadAdyenLibrary command to download the adyenuisdk.aar and adyenpaysdk.aar files to you libs folder.

  4. Finally, add the following snippet in your build.gradle of the app module:

    repositories {
        flatDir {
            dirs 'libs'
        }
    }

For the Checkout screen in your mobile application, add this code that should be triggered when a shopper presses the Pay button.

#import "AdyenCSE/AdyenCSE.h"

// Set the payment authorisation URL on your server.
static NSString *merchantPaymentAuthoriseUrl = @"";

// Set the public key. To obtain this key, go to
// Customer Area -> Settings -> Users -> ws@Company.YourCompany
static NSString *publicKey = @"10001|B243E873CB9220BAFE71...";

// Create a card object.
ADYCard *card = [ADYCard new];
card.number = @"55551...";
card.cvc = @"737";
card.holderName = @"John A...";
card.expiryMonth = @"08";
card.expiryYear = @"2018";
card.generationtime = [NSDate new];

// Encrypt card data.
NSData *cardData = [card encode];
NSString *encryptedCard = 
    [ADYEncrypter encrypt:cardData publicKeyInHex:publicKey];
import adyen.com.adyencse.encrypter.exception.EncrypterException;
import adyen.com.adyencse.pojo.Card;
                        
// Set the public key. To obtain this key, go to
// Customer Area -> Settings -> Users -> ws@Company.YourCompany
String publicKey = @"10001|B243E873CB9220BAFE71...";

// Create a card object.
Card card = new Card();
card.setNumber("55551...");
card.setCvc("737");
card.setCardHolderName("John A...");
card.setExpiryMonth("08");
card.setExpiryYear("2018");
card.setGenerationTime(new Date());

// Encrypt card data.
String encryptedCard = card.serialize(publicKey);

Make sure to URL-encode the encryptedCard value before sending it from the app to your server, as the encryptedCard is generated by the CSE library and must be exactly the same as you send it from the server to the Adyen API.

Server side

For your mobile application to be able to communicate with the Adyen platform, your server must provide an interface to accept encrypted data from your mobile application and send it to the Adyen platform. Below is the example of the URLs that should be exposed by your server:

  • http://www.YourServer.com/api.php?method=authoriseCard

For security reasons you have to make sure the app (user) is authenticated on your server. For example, we advise using OAuth 2.0 for authentication.

To see the sample implementation of this functionality, refer to https://github.com/Adyen/adyen-php-api-library.

Authorise request

After the encrypted payment data reaches your server, you should pass it to our test endpoint to authorize a payment. For this, make sure to include your valid web service credentials when making the request.

The following example shows a basic authorize request with data passed in JSON format.

The amount is specified in minor units (in this case, 20000 is 200 euros), the number of decimal points per currency can be found in the currency codes topic.

  You can use one of our test credit cards to make the request.

curl -u "ws@Company.YourCompany":"YourWsPassword" \
   -H "Content-Type: application/json" \
   -X POST \
   --data \
   '{
       "additionalData": {
           "card.encrypted.json":"adyenjs_0_1_4p1$..."
       },
     
       "amount" : {
           "value" : 20000,
           "currency" : "EUR"
       },
     
       "reference" : ["Your Reference Here"],
       "merchantAccount" : ["TestMerchant"]
   }'\
   https://pal-test.adyen.com/pal/servlet/Payment/v25/authorise

To know more about making authorize requests for card payments, refer to API reference.

Authorise response

After the request from your server passes initial validation, the Adyen platform performs a risk analysis. If the calculated risk score for the submitted payment satisfies your current risk settings, Adyen attempts to authorize this payment.

As an outcome, you receive a payment response, which includes a PSP reference to uniquely identify each payment. You can store this reference in your server database and use it later to refer to this specific transaction (for instance, to cancel or refund it, if needed).


{
  "pspReference": "8814689190961342",
  "resultCode": "Authorised",
  "authCode": "83152"
} 

For other possible response codes and fields of the payment response, refer to API Reference.







Local payment methods

Local payment methods can vary per country or region. Some examples of local payment methods are direct bank transfer, eWallets, or mobile payments. To know which methods can be enabled for you, contact Adyen Support Team.

In mobile applications, you can support local payment methods in a browser. Since some payment methods restrict WebView in mobile apps for security reasons, we recommend using the following approaches in your app:

The flow of a payment using a local payment method is illustrated in the diagram below.

To process local payment methods:

  1. Create a new skin and style the form to let your shopper select a payment method. Go to Adyen Customer Area (CA) → Skins → Create a new skin
.
  2. Add the skin description.
  3. Generate the HMAC keys for the test and live platforms (remember to take a note of this key) and click Save.
  4. Select the skin from the list and click Test from the menu bar to verify that Currently on Test displays the version information in green.

Request local payment methods

To retrieve a list of available local payment methods make a lookup request to the directory endpoint with the fields in the code example. For Adyen to verify the authenticity of the request calculate the signature of the request and include this in the merchantSig field.

The example below shows how to make such a request. For additional fields and more details for the payment methods request refer to the API Reference.

 

curl https://test.adyen.com/hpp/directory.shtml \
 -d countryCode=DE \
 -d currencyCode=EUR \
 -d merchantAccount=TestMerchant \
 -d merchantReference=Test_directory_lookup \
 -d paymentAmount=2000 \
 -d sessionValidity=2017-12-25T10%3A31%3A06Z \
 -d skinCode=sH9qpMyS \
 -d merchantSig=94AwPXSxs0ECicXi1UDdKEmdzHQ6rf7EF9CC%2FzUO5Tg%3D

Display local payment methods

A response returns a JSON object containing a list of applicable payment methods. Each payment method has a namebrandCodelogo, and optionally, a list of issuers (depending on the payment method). In this case, the issuerId identifies a specific issuer and can be used to direct a shopper to the related method's webpage.



When parsing this response, you can format and display the methods according to your design if you like.

{
   "paymentMethods":[
      {
         "brandCode":"ideal",
         "name":"iDEAL",
         "issuers":[
            {
               "issuerId":"1121",
               "name":"Test Issuer"
            },
            {
               "issuerId":"1152",
               "name":"Test Issuer 3"
            },
            {
               "issuerId":"1151",
               "name":"Test Issuer 2"
            }
         ]
      },
      {
         "brandCode":"sepadirectdebit",
         "name":"SEPA Direct Debit"
      },
      {
         "brandCode":"moneybookers",
         "name":"Moneybookers"
      },
      {
         "brandCode":"klarna",
         "name":"Klarna Invoice"
      },
      {
         "brandCode":"afterpay_default",
         "name":"AfterPay Invoice"
      },
      {
         "brandCode":"boku",
         "name":"Boku"
      },
      {
         "brandCode":"paysafecard",
         "name":"Paysafecard"
      },
      {
         "brandCode":"paypal",
         "name":"PayPal"
      }
   ]
}

Submit a payment request

After your shopper selects the local payment method, make a GET request including the brandCode and issuerId (if available) of the selected payment method.

 Recalculate the signature of your payment request with the brandCode and issuerId as extra fields and post the request to the skipDetails.shtml endpoint. Your shopper is then redirected to the selected local method to finalize the payment.




https://test.adyen.com/hpp/skipDetails.shtml?sessionValidity=2016-09-17T11%3A38%3A55Z&shopperLocale=en_GB&merchantAccount=TestMerchant&paymentAmount=8650&currencyCode=EUR&skinCode=aF563qQs&merchantReference=TMRef1234&brandCode=ideal&issuerId= 1121&merchantSig=62unnLF...ubZc%3D-

Payment response

After shoppers have completed the payment, they are redirected to a result page of your choice. You can set a custom result URL in the Customer Area on the skin configuration page. Another option is to include the result URL in the resURL field in the payment request.



Adyen appends parameters to this result URL to inform you about the payment status. If the status is already determined (either authorised or refused), you can use this information to display a payment successful or payment failed page. In a case when the current status is pending, use payment notifications to get the outcome of a payment request and store this result in your back office, if necessary.

An example of a redirect URL to your app:

app://yourAppName

An example of a corresponding resultURL:

http://yourSite.com/pRes.jsp?merchantReference=Internet%20order%2012345&skinCode=4aD37dJA&shopperLocale=en_GB&authResult=AUTHORISED&pspReference=1211992213193029&merchantSig=CPb2cObMxmIIE0khO8WhEYyKDJs%3D

<!-- Appended URL parameters:
* merchantReference = Internet order 12345
* skinCode = 4aD37dJA
* shopperLocale = en_GB
* authResult = AUTHORISED
* pspReference = 1211992213193029
* merchantSig = CPb2cObMxmIIE0khO8WhEYyKDJs%3D
 -->

To ensure that the response is not tampered with validate the response by calculating the signature of the returned fields, except the merchantSig field. Adyen uses your secret HMAC key to sign the data, so the calculated signature should be the same as the merchantSig included in the response.

 For more information on additional response fields, visit the API Reference.

Complete the payment

You can opt for automatic or manual capture - for instance, if you are processing more than a handful of payments on a daily basis we recommend that you automate this process. The Adyen Customer Area (CA) offers an option to configure an automated capture process to automatically capture payments after a specified number of days, ranging from no delay, 1 day, 2 days, 3 days, 4 days, 5 days, 6 days, 7 days, and manual. To define a capture delay, go to CA → Settings → Merchant Setting → Capture Delay

To manually capture an authorized payment, send a request to the capture endpoint passing the fields as in the example below.  To uniquely identify the payment to be captured, pass the PSP reference (e.g. 9914430855683260) that is returned to you in the authorise payment response.

 curl -u "ws@Company.YourCompany":"YourWsPassword" \
     -H "Content-Type: application/json" \
     -X POST --data \
     '{
         "merchantAccount" : ["TestMerchant"],
         "modificationAmount" : {
              "value" : [20000],
              "currency" : ["EUR"]
           },
         
           "originalReference" : ["9914430855683260"],
           "reference" : ["YourModificationReference"]
      }' \
      https://pal-test.adyen.com/pal/servlet/Payment/v25/capture

Receive notifications

Besides synchronous responses, Adyen uses notifications to keep you updated about actions and their result (e.g. a payment authorization). In addition, notifications help you synchronize your back-office system to always have up-to-date information on payment statuses.

It is mandatory for you to integrate with Adyen notifications when testing your integration. For more information, refer to Notifications.

Cancel and/or refund

Sometimes you may need to cancel or refund a payment. To know how this can be done with the Adyen platform, refer to Cancel or refund.

Enable recurring payments

If your business model requires billing your customers on a recurring basis, you may enable recurring payments using the Adyen platform. In this case, Adyen securely stores payment details when you make the first authorisation call, so that you no longer need to provide this data in the future.

To do this, add the recurring field to the payment request you make from your server to the Adyen platform. For example, if you want to enable both shopper-not-present and one-click recurring modes for a specific payment, add the following field to the API call above:

"recurring" : {
   "contract" : "RECURRING,ONECLICK"
}

For more information on recurring payments, refer to the Recurring payments.

Questions

Can't find something you are looking for? Look at our FAQ for answers or send an email to support.