Payments / Payment Types / Apple Pay / Direct Api

Direct API with Apple Pay

Apple Pay on the Web lets you access the payment data that your customers have stored in their Wallet. While clicking on the "Buy with Apple Pay" button in Safari on their iPhone, iPad, or Mac device, Novalnet will show the Apple Pay payment sheet. Upon authorization, the details about the transaction will be posted to the browser. Please note that if they are using Safari on their older Mac with Touch ID and having an iOS device in range, they'll be prompted on their device to authorize the payment.

Setting up the Apple Sandbox environment

Set up your Apple Pay sandbox account for the development and testing in either of the two ways below:

If you have an Apple Developer account already, perform the following steps,
- Sign in to Apple Developer account.
- Click on the link Users and Access, under App Store Connect and then navigate to the Sandbox Testers tab.
- Click on the "+" icon to set up a new test account. After filling in the form, click Create.
- Sign out of your Apple ID on all testing devices if logged in. And then log in with the new test credentials.
- Navigate to the Settings -> Wallet & Apple Pay
- Tap Add Credit/Debit Card and add the test Credit Card. You can find the test Credit Card numbers in the Apple Pay Sandbox Guide.
If you have an Apple Developer account already, perform the following steps,

Step 1: Add the components to your site

Begin with adding a container in your webshop where you want to load the payment method button. You can render a variety of Apple Pay buttons on your website using the customization of the payment button request. For example, you can specify which button type to display and edit its appearance and size to fit your webpage. The payment method button will be mounted on the container based on the customization request.

HTML

<div id="applepay_container"></div>

Next, ensure that Novalnet payment JS library is included on your page.

HTML

<script src="https://cdn.novalnet.de/js/v3/payment-1.1.1.js" integrity="sha384-vt6KnwX2uuXsPgIuclE6QFU3gkYk17opZ1xUHUHewCwa7wkN9oTqtq2kWA9aSf4J" crossorigin="anonymous"></script>

Step 2: Load the payment instances

Since the Novalnet payment JS library is equipped with various payment methods, it is possible that you can render multiple payment method buttons. Therefore, creating separate instances for processing each payment method button would be best.

Prepare a clone of the Novalnet payment JS library, which contains the methods to handle payment method button processing and utility handling.

JAVASCRIPT

var NovalnetPaymentInstance = NovalnetPayment();

For each of the payment method buttons that are required to be mounted and processed distinctively, prepare a payment method instance from the local clone created.

JAVASCRIPT

var applepayNovalnetPaymentObj = NovalnetPaymentInstance.createPaymentObject();

Step 3: Setup the payment intent in your object

Every client-side request associated with Novalnet is fulfilled by validating the Client Key. The Client Key is a unique public key linked with your project, which includes allowing the domain where you want to display the payment method button. Set this Client Key in the payment intent and the other objects required for payment button processing.

You can find your client key in your Novalnet admin portal in the following path Projects -> [SELECT YOUR DESIRED PROJECT] -> API credentials -> Client Key.

Each parameter is marked with attributes Mandatory, Conditional , Optional . Based on your necessity, you can use these parameters accordingly.

countryCode

String
Mandatory
DE

A two-letter ISO 3166-1 alpha-2 country code indicates the country where the transaction is processed.

`amount` Integer Mandatory 100	The total amount to be charged from the customer includes the line items, tax, shipping and additional costs (in minor units), e.g., Euro in Eurocents (5,22€ = 522).
`currency` String Mandatory EUR	The three-character currency code as defined in ISO-4217.
`paymentMethod` String Mandatory APPLEPAY	Payment type as defined in Novalnet, and based on this specification, Novalnet payment JS library will process the corresponding payment method button. Therefore, refer to this section for the payment type details.
`environment` String Optional PRODUCTION	Denotes the processing mode of the transaction. The following values are permitted: PRODUCTION for "Processing the transaction in the LIVE mode, where the chargeable token is created." SANDBOX for "Processing the transaction in the test mode. No real cash flow happens here." By default, the value PRODUCTION will be set.

JAVASCRIPT

var merchantInformation = {
	countryCode: "DE",
};

var transactionInformation = {
	amount: 100,
	currency: "EUR",
	environment: "SANDBOX",
	paymentMethod: "APPLEPAY",
};

var paymentIntent = {
	clientKey: ###YOUR_CLIENT_KEY###,
	paymentIntent: {
		merchant: merchantInformation,
		transaction: transactionInformation,
	}
};

applepayNovalnetPaymentObj.setPaymentIntent(paymentIntent);

Step 4: Check for the payment method availability

As Apple Pay is available only to specific devices and browsers, check for Apple Pay availability before processing the payment method. After you set up your payment intent request, you can use the isPaymentMethodAvailable function to determine whether or not to show an Apple Pay button.

Note that this method executes asynchronously; you must pass it a callback function.

Based on the availability of the payment method, mount the payment method button to the container set up initially by calling addPaymentButton function.

JAVASCRIPT

// Checking for the Payment Method availability
applepayNovalnetPaymentObj.isPaymentMethodAvailable(function(displayApplePayButton) {

  // Initiating the Payment Request for the Wallet Payment
  applepayNovalnetPaymentObj.addPaymentButton("#applepay-container");

});

Step 5: Complete the payment

When the end customer authorizes the payment in the Apple Pay payment sheet, Novalnet generates a unique so-called wallet token. Only the customer's authorization is complete until this point, and the generated wallet token has to be passed back to the Novalnet server for the booking. You will only receive the authorization response data once you register the onProcessCompletion callback inside the callbacks property of your payment intent request. Novalnet posts the wallet token to your registered onProcessCompletion callback. You should pass this token to your server and call the /payment API (or /authorize API) to charge the customer.

Pass the wallet token transaction.payment_data.wallet_token in the payment request. You can view more about the samples, parameters in this >>link<<.

The callback function should have two arguments, the first to receive the authorization result and the second to return the booking result to the payment sheet.

JAVASCRIPT

callbacks: {
	"onProcessCompletion": function(payLoad, bookingResult) {
	
		// Handle response here and setup the processedStatus
		if (payLoad.result && payLoad.result.status) {
	
			// Only on success, we proceed further with the booking   
			if (payLoad.result.status == 'SUCCESS') {
	
				// Sending the token and amount to Novalnet server for the booking
				
				### SEND WALLET TOKEN TO YOUR SERVER TO CHARGE THE CUSTOMER	
				$.post('send_server_request.php', {token: payLoad.transaction.token, amount: payLoad.transaction.amount}).done(function(processedResult) {
					
					var parsedResult = processedResult.split('script>\n')[11];
					parsedResult = $.parseJSON(parsedResult);
						
					// "SUCCESS" value will dismiss with the payment sheet with "Done" message
			        // "FAILURE" value will dismiss the payment sheet with the error message
			        ### RETURN THE BOOKING RESULT BACK TO THE PAYMENT SHEET
			        let result = {};
			        result.status = payLoad.result.status;
			        result.statusText = payLoad.result.status_text;
			        bookingResult(result);										
	
				});
	
			} else {
	
				// Upon failure, displaying the error text 
				if (payLoad.result.status_text) {
					alert(payLoad.result.status_text);
				}
			}
		}
	}
}

The payment sheet's authorization response details are listed in the table below.

Each parameter is marked with attributes Mandatory, Conditional , Optional . Based on your necessity, you can use these parameters accordingly.

`status` String Mandatory SUCCESS	Status about the API for the transaction
`statusText` String Mandatory Successful	Developer-facing message that describes the error encountered and possible steps to correct it.

token

String
Mandatory

The wallet token is generated at Novalnet after the authorization by the customer in the payment sheet. This token replaces the customer's payment data and facilitates the further booking of the customer using the /payment API (or /authorize API).

doRedirect

String
Mandatory
https://www.demoshop.de/success

If the customer used a card that requires 3D Secure authentication before the payment can be completed, you need to redirect the customer to another website where they complete the 3D authentication. To learn how to handle the redirect, follow our Handle Redirection guide.

Note: The parameter and handling is applicable only for the payment method Google Pay.

amount

String
Mandatory

The total amount to be charged from the customer includes the line items, tax, shipping and additional costs (in minor units), e.g., Euro in Eurocents (5,22€ = 522).

paymentData

Object
Mandatory

`cardBrand` String Conditional Visa	The payment card network of the selected payment.
`lastFour` String Conditional 4567	The details about the card. This value is commonly the last four digits of the selected payment account number.

You should also wrap the entire code in a try-catch block for handling validation.

JAVASCRIPT

// Setting up the Payment Intent for authentication and payment button processing						
var merchantInformation = {
	countryCode: "DE",
};

var transactionInformation = {
	amount: 100,
	currency: "EUR",	
	paymentMethod: "APPLEPAY",
	environment: "SANDBOX"
};

var paymentIntent = {
	clientKey: ###YOUR_CLIENT_KEY###,
	paymentIntent: {
		merchant: merchantInformation,
		transaction: transactionInformation,
		callbacks: {
			"onProcessCompletion": function(payLoad, bookingResult) {

				// Handle response here and setup the bookingresult
				if (payLoad.result && payLoad.result.status) {

					// Only on success, we proceed further with the booking   
					if (payLoad.result.status == 'SUCCESS') {

						// Sending the token and amount to Novalnet server for the booking
						$.post('send_server_request.php', {token: payLoad.transaction.token, amount: payLoad.transaction.amount}).done(function(processedResult) {
							
							var parsedResult = $.parseJSON(processedResult);
							
							// "SUCCESS" or "FAILURE" 							
							let result = {};
							result.status = payLoad.result.status;
							result.statusText = payLoad.result.status_text;
							bookingResult(result);							
							
						});

					} else {

						// Upon failure, displaying the error text 
						if (payLoad.result.status_text) {
							alert(payLoad.result.status_text);
						}
					}
				}
			}
		}
	}
};

try {
	// Loading the payment instances
	var NovalnetPaymentInstance = NovalnetPayment();
	var applepayNovalnetPaymentObj = NovalnetPaymentInstance.createPaymentObject();

    // Setting up the payment intent in your object 
	applepayNovalnetPaymentObj.setPaymentIntent(paymentIntent);

	// Checking for the payment method availability
	applepayNovalnetPaymentObj.isPaymentMethodAvailable(function(displayApplePayButton) {
		// Initiating the Payment Request for the Wallet Payment
		applepayNovalnetPaymentObj.addPaymentButton("#applepay-container");
	});

} catch (e) {
	// Handling the errors from the payment intent setup
	console.log(e.message);
}

PHP

<?php

// Need to enter your payment access key value here
$payment_access_key  = '###YOUR_PAYMENT_ACCESS_KEY###';

// Need to enter your signature value here
$signature           = '###YOUR_API_SIGNATURE###';

// Need to enter your tariff id here
$tariff_id           = '###YOUR_TARIFF_ID###';

// Need to enter your hook url here
$hook_url            = '###YOUR_HOOK_URL###';

// Now, have to encode the $payment_access_key value with the base64 encode
$encoded_data        = base64_encode($payment_access_key);

// Action Endpoint 
$endpoint            = 'https://payport.novalnet.de/v2/payment';

// Build the Headers array
$headers = [
	// The Content-Type should be "application/json"
    'Content-Type:application/json',
     
    // The charset should be "utf-8"
    'Charset:utf-8', 
    
    // Optional
    'Accept:application/json', 
    
    // The formed authenticate value (case-sensitive)
    'X-NN-Access-Key:' . $encoded_data, 
];

$data = [];

// Build Merchant Data
$data['merchant'] = [

	// Your API signature value
    'signature' => $signature, 
    
    // Your corresponding tariff ID
    'tariff'    => $tariff_id, 
];

// Build Customer Data
$data['customer'] = [

    // Shopper's first name
    'first_name'  => 'Max',
    
     // Shopper's last name
    'last_name'   => 'Mustermann', 
    
    // Shopper's email
    'email'       => '###YOUR_MAIL###', 
    
     // Shopper's Ip address
    'customer_ip' => '127.0.0.1',
    
    // Shopper's billing address
    'billing'     => [
    
        // House number
        'house_no'     => '2',
        
        // Street
        'street'       => 'Musterstr',
        
        // City
        'city'         => 'Musterhausen',
        
        // zip
        'zip'          => '12345',
        
        // Country's ISO code
        'country_code' => 'DE'
    ]    
];

// Build Transaction Data
$data['transaction'] = [

    // The Payment type of the transaction
    'payment_type'     => 'APPLEPAY',
    
    // The transaction Amount in smaller currency unit
    'amount'           => '###TRANSACTION_AMOUNT###',
    
    // The transaction currency's ISO code
    'currency'         => 'EUR',
    
    // The mode of the transaction
    'test_mode'        => 1,
    
    // The mode of the transaction
    'order_no'         => 6789,
    
    // The Hook URL value for this particular transaction
    'hook_url'         => $hook_url,
    
     // The flag to create the token for the payment data - Decomment it based on your usage
    'create_token'     => 1,
    
    // Build Payment Data
    'payment_data'     => [        
        'wallet_token' => '###WALLET_TOKEN###' 
    ]   
];

// Custom Data
$data['custom'] = [
      
    // Shopper's selected language in shop
    'lang'      => 'EN',
    
    // Custom parameter's key - Optional object - Decomment it based on your usage
	// 'input1'    => 'your internal reference parameter name',
	
	// Custom parameter's value - Optional object - Decomment it based on your usage
	// 'inputval1' => 'your internal reference parameter value'
];

// Convert the array to JSON string
$json_data = json_encode($data);

// Handle Response
$response = send_request($json_data, $endpoint, $headers);

function send_request($data, $url, $headers) {

    // Initiate cURL
    $curl = curl_init();
    
    // Set the url
    curl_setopt($curl, CURLOPT_URL, $url);
    
    // Set the result output to be a string
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    
    // Set the POST value to true (mandatory)
    curl_setopt($curl, CURLOPT_POST, true);
    
    // Set the post fields
    curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
    
    // Set the headers
    curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

    // Execute cURL
    $result = curl_exec($curl);

    // Handle cURL error
    if (curl_errno($curl)) {
        echo 'Request Error:' . curl_error($curl);
        return $result;
    }
    
    // Close cURL
    curl_close($curl);  
    
    // Decode the JSON string
    $result = json_decode($result);

    return $result;
}

?>

Your browser does not support Apple Pay on the web.
To try this demo, open this page in Safari.
(See Requirements.)

Direct API with Apple Pay

Setting up the Apple Sandbox environment

Step 1: Add the components to your site

Step 2: Load the payment instances

Step 3: Setup the payment intent in your object

merchant Object

transaction Object

Step 4: Check for the payment method availability

Step 5: Complete the payment

result Object

transaction Object

Transaction Result

Related Topics