Skip to content

CloudDeviceApi.md

Latest commit

 

History

History
198 lines (144 loc) · 7.1 KB

CloudDeviceApi.md

File metadata and controls

198 lines (144 loc) · 7.1 KB
Raw

Cloud device API

The Cloud device API is our solution to create best-in-class in-person payments integrations.

With the Cloud device API you can:

  • send Terminal API requests to a cloud endpoint. You can use this communication method when it is not an option to send Terminal API requests over your local network directly to a payment terminal.
  • check the cloud connection of a payment terminal or of a device used in a Mobile solution for in-person payments.

Benefits of the Cloud device API

The Cloud device API offers the following benefits:

  • access to API logs in the Customer Area for troubleshooting errors
  • using a version strategy for the API endpoints for controlled and safer rollouts
  • improved reliability and security (OAuth support)

New features and products will be released exclusively on the Cloud device API

Use the Cloud device API

Setup

First you must initialise the Client (see an example on TEST):

// Import the required classes
import com.adyen.Client;
import com.adyen.enums.Environment;
import com.adyen.service.clouddevice.CloudDeviceApi;
import com.adyen.model.clouddevice.*;
import com.adyen.model.tapi.*;
import java.math.BigDecimal;
import java.time.OffsetDateTime;
import java.time.ZoneOffset;

// Setup Client on TEST
Client client = new Client(new Config().apiKey("test").environment(Environment.TEST));

CloudDeviceApi cloudDeviceApi = new CloudDeviceApi(client);

On LIVE environment you must set the closest Region

// Import the required classes
import com.adyen.Client;
import com.adyen.enums.Environment;
import com.adyen.service.clouddevice.CloudDeviceApi;
import com.adyen.model.clouddevice.*;
import com.adyen.model.tapi.*;
import java.math.BigDecimal;
import java.time.OffsetDateTime;
import java.time.ZoneOffset;

// Setup Client on LIVE (Region is required)
Client client = new Client(new Config().apiKey("test").environment(Environment.LIVE).terminalApiRegion(Region.US));

CloudDeviceApi cloudDeviceApi = new CloudDeviceApi(client);

Send a payment SYNC request

SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();

MessageHeader messageHeader = new MessageHeader();
    messageHeader.setProtocolVersion("3.0");
    messageHeader.setMessageClass(MessageClass.SERVICE);
    messageHeader.setMessageCategory(MessageCategory.PAYMENT);
    messageHeader.setMessageType(MessageType.REQUEST);
    messageHeader.setSaleID("001");
    messageHeader.setServiceID("001");
    // POIID is set automatically from the deviceId parameter
    saleToPOIRequest.setMessageHeader(messageHeader);

PaymentRequest paymentRequest = new PaymentRequest();

SaleData saleData = new SaleData();
TransactionIDType transactionIDType = new TransactionIDType();
    transactionIDType.setTransactionID("001");
OffsetDateTime timestamp = OffsetDateTime.now(ZoneOffset.UTC);
    transactionIDType.setTimeStamp(timestamp);
    saleData.setSaleTransactionID(transactionIDType);

PaymentTransaction paymentTransaction = new PaymentTransaction();
AmountsReq amountsReq = new AmountsReq();
    amountsReq.setCurrency("EUR");
    amountsReq.setRequestedAmount(BigDecimal.ONE);
    paymentTransaction.setAmountsReq(amountsReq);

    paymentRequest.setSaleData(saleData);
    paymentRequest.setPaymentTransaction(paymentTransaction);

    saleToPOIRequest.setPaymentRequest(paymentRequest);

CloudDeviceApiRequest cloudDeviceApiRequest = new CloudDeviceApiRequest();
    cloudDeviceApiRequest.setSaleToPOIRequest(saleToPOIRequest);

CloudDeviceApiResponse response = cloudDeviceApi.sync("myMerchant", "P400Plus-123456789", cloudDeviceApiRequest);

Send a payment ASYNC request

If you choose to receive the response asynchronously, you only need to use a different method (async). Don't forget to set up event notifications in the CA to be able to receive the Cloud device API responses.

...

// define the request (same as per sync)
CloudDeviceApiRequest cloudDeviceApiRequest = new CloudDeviceApiRequest();
cloudDeviceApiRequest.setSaleToPOIRequest(saleToPOIRequest);

CloudDeviceApiAsyncResponse response = cloudDeviceApi.async("myMerchant", "P400Plus-123456789", cloudDeviceApiRequest);

if ("ok".equals(response.getResult())) {
    // success	
} else {
    // request failed: see details in the EventNotification object
    EventNotification eventNotification = response.getSaleToPOIRequest().getEventNotification();
}

Verify the status of the terminals

The Cloud device API allows your integration to check the status of the terminals.

// list of payment terminals or SDK mobile installation IDs
ConnectedDevicesResponse connectedDevices = cloudDeviceApi.getConnectedDevices("myMerchant");
System.out.println(connectedDevices.getUniqueDeviceIds());
// [P400Plus-123456789, AMS1-000168242800763]

// check the payment terminal or SDK mobile installation ID 
DeviceStatusResponse deviceStatus = cloudDeviceApi.getDeviceStatus("myMerchant", "AMS1-000168242800763");
System.out.println(deviceStatus.getStatus());
// ONLINE

Helper classes

You can use PredefinedContentHelper to parse Display notification types which you find in PredefinedContent->ReferenceID

import com.adyen.util.tapi.PredefinedContentHelper;

// Parse ReferenceID (i.e. key1=value1&key2=value2)
PredefinedContentHelper helper = new PredefinedContentHelper(predefinedContent.getReferenceID());

// Safely extract and use the event type with Optional
helper.getEvent().ifPresent(event -> {
        System.out.println("Received event: " + event);
    if (event == PredefinedContentHelper.DisplayNotificationEvent.PIN_ENTERED) {
        // Handle PIN entry event
        System.out.println("The user has entered their PIN.");
    }
});

Protect cloud communication

The Adyen Java library supports encrypting request and response payloads, allowing you to secure communication between your integration and the cloud.

//  Encryption credentials from the Terminal configuration on CA
EncryptionCredentialDetails encryptionCredentialDetails =
    new EncryptionCredentialDetails()
        .adyenCryptoVersion(1)
        .keyIdentifier("CryptoKeyIdentifier12345")
        .keyVersion(1)
        .passphrase("p@ssw0rd123456");

// Use EncryptedCloudDeviceApi instead of CloudDeviceApi
EncryptedCloudDeviceApi encryptedCloudDeviceApi =
    new EncryptedCloudDeviceApi(client, encryptionCredentialDetails);

CloudDeviceApiResponse response =
    encryptedCloudDeviceApi.sync(
        "TestMerchantAccount",
        "V400m-123456789",
        cloudDeviceApiRequest);

System.out.println(response);

In case of asynchronous integration, you can decrypt the payload of the event notifications using decryptNotification() method.

// JSON with encrypted SaleToPOIResponse (for async responses) or SaleToPOIRequest (for event notifications) 
var payload = "...";

var decryptedPayload = encryptedCloudDeviceApi.decryptNotification(payload);
System.out.println(decryptedPayload);