Skip to content

Apple Pay

During a conventional checkout process, customers typically need to provide various personal details, including card information, billing and shipping addresses, email, or phone number. However, Apple Pay streamlines this process significantly by easy enabling customers to make credit card payments with a seamless and secure process using Touch ID or Face ID authentication.

Upon selecting Apple Pay button:

  1. The customer is presented with a user-friendly payment sheet.
  2. Customers choose their preferred payment card from the available options.
  3. For added security, customers confirm their identity using a biometric authentication, such as Face ID or Touch ID, before finalizing the payment.
Payment optionCategoryCountriesCurrenciesFeaturesIntegrations
Apple PayDigital WalletCzech Republic, France, Germany, Poland, Portugal, Romania, Slovakia, SloveniaCZK, EUR, PLN, RONPre-authorized Capture
One-Time Purchase
Partial captures
Partial refund
Recurring
Refunds
Cancellation
API
Payment Form
Prestashop Plugin
WooCommerce Plugin
Magento Plugin

Before you start

Prior to being able to receive Apple Pay payments, it is necessary to set up and configure your Apple Pay integration, which also involves using a certificate.

Info

Apple Pay can be utilized on designated devices and supported browsers.
For more information, please refer to Apple Pay compatibility page.

Ensure your server is properly prepared for secure communication with Apple Pay by meeting these prerequisites.

  • An operational domain with a valid SSL certificate
  • Availability of a Secure Shell (SSH) terminal for your usage.
  • Appropriate permissions granted to access your server’s files, facilitating the uploading of essential files to your server.

For more information, please refer to Setting up your Server.

How to configure Apple Pay

In order to configure and enable Apple Pay for payments, the initial step involves obtaining an Apple Development Account and applying for the Apple Developer Program or Enterprise. Please anticipate a potential wait of several days for the approval process.

This process requires being signed in with an Apple Developer account and it encompasses six main steps:

Step 1: Create a merchant identifier
Step 2: Generate a certificate signing request (CSR)
Step 3: Create a payment processing certificate
Step 4: Upload the payment processing certificate
Step 5: Register your domain
Step 6: Create a merchant identity certificate and Upload it onto your server
Step 1: Create a merchant identifier

A merchant identifier serves as a unique identification for your Apple Pay integration, allowing you to accept payments as a recognized merchant. It maintains its validity indefinitely and can be utilized across multiple applications.

Please adhere to the ApplePay guidelines to generate a merchant identifier.

Notification

For your merchant identifier name we suggest employing a descriptive name that denotes both the domain and the intended environment, such as merchant.com.sibs.merchantwebsite.test.

 

We recommend creating distinct merchant identifiers for your test environment and live  environment.

Step 2: Generate a certificate signing request (CSR)

You should provide your merchant ID to your account manager, who will then use it to generate the .csr file. Once generated, you will receive the .csr file, which will be used in the next step.

Step 3: Create a payment processing certificate

A payment processing certificate is intricately linked to your unique merchant identifier and serves as a safeguard for encrypting sensitive payment details. The validity of the payment processing certificate spans 25 months from its issuance, requiring renewal thereafter. In the event of a certificate revocation, the option to regenerate it remains available to you, ensuring uninterrupted payment processing security.

Please adhere to ApplePay guidelines to generate a payment processing certificate and pay attention to the following:

  • Skip the step for creating a certificate signing request.
  • Choose No for the China processing question.
  • Upload the .csr file from the prior step and proceed.
  • Download your payment processing certificate (.cer file).
Step 4: Upload the payment processing certificate

You should send the .cer file downloaded on the previous step to your account manager, who will then upload and associate it to your merchant ID.

Step 5: Register your domain

In this step, a valid SSL certificate for your domain (commencing with https) is required. Please adhere to the guidelines to register a merchant domain.

Step 6: Create a merchant identity certificate and Upload it onto your server

This certificate serves the purpose of authenticating communication with the Apple Pay servers. In this step, your account manager will provide you with a CSR file that you’ll need to use. Please make sure to follow the provided guidelines to generate a merchant identity certificate.

Keep in mind that upon clicking on “Create Certificate” option, you should:

  1. Upload the .csr file that has been shared with you by your account manager; and
  2. Download the resulting certificate.

Once you’ve followed Apple’s instructions and downloaded the Apple Pay Merchant Identity Certificate you should send the certificate to your account manager, who will then upload and associate it to your merchant ID. After the completion of this process, you will be able to start a payment.

Make a payment

Step 1: Create the Order
Step 2: Get the Payment Session
Step 3: Make the payment request
Step 4: Check the Payment Status
Step 1: Create the Order

First, you should initiate the creation of the order.

Upon generating the order request, make sure to include “XPAY” as a payment method.

Step 2: Get the Payment Session

Following that step, you’ll be required to initiate a synchronous call to set up an ApplePay Session.

GET {version-id}/{id}/xpay/payment/applepay-session

Path and Header Parameters:

LocationData ElementTypeConditionDescription
PathIdStringConditionalUsed to query transaction status by Transaction Id
Request HeaderContent-TypeStringMandatoryapplication/json 
Request HeaderAuthorizationStringMandatoryAuthorization Digest

A successful technical response is indicated by an HTTP-200 status along with a returnStatus.statusCode value of “000”.

Step 3: Make the payment request

Following this, proceed to make the payment request as per the following detailed message.

EnvironmentURLOperation Method & EndpointOperation Description
PRODapi.sibsgateway.comPOST version-id/{id}/xpay/paymentRequests the payment registered by the previous checkout using xpay payment details inserted by the customer.
TESTstargate-cer.qly.site[1|2].sibs.ptPOST version-id/{id}/xpay/paymentRequests the payment registered by the previous checkout using xpay payment details inserted by the customer.

The message below represents the Apple Pay Payment Request:

LocationData ElementTypeConditionDescription
PathidStringConditionalTransaction Id

Header Parameters:

LocationData ElementTypeConditionDescription
Request HeaderContent-TypeStringMandatoryapplication/json
Request HeaderauthorizationStringMandatoryBearer Token. Based on OAuth2 authentication performed in a pre-step.
Request Headerx-ibm-client-idStringMandatoryToken that identifies a client organization. It is provided during onboarding process and must be used in every call.

Request Parameters:

LocationData ElementTypeConditionDescription
Request BodytokenInfoTokenInfoConditionalPayment Tokens
Request Body.tokenInfotokenNameStringOptionalToken Name
Request Body.tokenInfotokenTypeStringMandatoryToken Type.
Possible values are (“ApplePay”, “GooglePay”).
Request Body.tokenInfovalueStringMandatoryToken Value
Request BodyinfoInfoMandatoryObject that defines the transaction additional information.
Request Body.infodeviceInfoDeviceInfoMandatoryObject that defines the customer device information.
Request Body.info.deviceInfobrowserAcceptHeaderStringOptionalBrowser Accept Header
Request Body.info.deviceInfobrowserJavaEnabledStringOptionalBrowser Java Enabled
Request Body.info.deviceInfobrowserJavascriptEnabledStringOptionalBrowser Javascript Enabled
Request Body.info.deviceInfobrowserLanguageStringOptionalbrowser Language
Request Body.info.deviceInfobrowserColorDepthStringOptionalbrowser Color Depth
Request Body.info.deviceInfobrowserScreenHeightStringOptionalbrowser Screen Height
Request Body.info.deviceInfobrowserScreenWidthStringOptionalbrowser Screen Width
Request Body.info.deviceInfobrowserTZStringOptionalBrowser Time Zone
Request Body.info.deviceInfobrowserUserAgentStringOptionalBrowser User Agent
Request Body.info.deviceInfosystemFamilyStringOptionalSystem Family
Request Body.info.deviceInfosystemVersionStringOptionalSystem Version
Request Body.info.deviceInfosystemArchitectureStringOptionalSystem Architecture
Request Body.info.deviceInfodeviceManufacturerStringOptionalSystem Manufacturer
Request Body.info.deviceInfodeviceModelStringOptionalDevice Model
Request Body.info.deviceInfodeviceIDStringOptionalDevice Unique Identification
Request Body.info.deviceInfoapplicationNameStringOptionalApplication Name
Request Body.info.deviceInfoapplicationVersionStringOptionalApplication Version
Request Body.info.deviceInfogeoLocalizationStringOptionalGeolocation
Request Body.info.deviceInfoipAddressStringOptionalIP Address
Request Body.infocustomerInfoCustomerInfoMandatoryKey Value tuple array.
Request Body.info.customerInfokeyStringOptional
Request Body.info.customerInfovalueStringOptional

Below is an example of an Apple Pay payment:

{
 "info": {
 "deviceInfo": {
 "browserAcceptHeader": "application/json, text/plain, */*",
 "browserJavaEnabled": "false",
 "browserJavascriptEnabled": "false",
 "browserLanguage": "en",
 "browserColorDepth": "24",
 "browserScreenHeight": "1080",
 "browserScreenWidth": "1920",
 "browserTZ": "-60",
 "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
 "geoLocalization": "Lat: 38.7350528 | Long: -9.2143616",
 "systemFamily": "Windows",
 "systemVersion": "Windows",
 "deviceID": "498bfd4c3a3645b38667a7037b616c18",
 "applicationName": "Chrome",
 "applicationVersion": "106"
 },
 "customerInfo": [
 {
 "key": "customerName",
 "value": "Test Name"
 },
 {
 "key": "customerEmail",
 "value": "email@provider.com"
 }
 ]
 },
 "tokenInfo": {
 "tokenType": "applePay",
 "value": "{{appleTokenValue}}"
 }
}

After the payment is processed, you will receive a response indicating the transaction status. Additionally, you can perform a “Get Status” operation to check the status at any time.

Step 4: Check the Payment Status

For this step, the Authorization HTTP header is set to the Bearer token as it was used in the initial Checkout.

GET {transactionID}/status

Request URL:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status

Request Headers:

Authorization: ‘Bearer <AuthToken>’
X-IBM-Client-Id: ‘<ClientId>’
Content-Type: application/json

A successful technical response comprises of an HTTP-200 status and a returnStatus.statusCode=”000″.

Here are some examples of the possible result codes:

Result CodestatusMsgDescriptionAction
HTTP-200SuccessSuccess responseN/A
HTTP-400Bad RequestThe JSON payload is not matching the API definition or some mandatory HTTP headers are missing.Please check in API Market for the correct syntax.
HTTP-401UnauthorizedOn the Authorization, Bearer token is invalid/expired or not associated with the Terminal used.Please check in SIBS Backoffice under the Credentials if the token is valid and create a new one if needed.
HTTP-403ForbiddenThe ClientID set on the X-IBM-Client-Id HTTP header is not valid or does not possess a valid subscription to the API.Please check in SIBS Backoffice under the SPG APP 2.0 if the ClientID is correct. If the problem persists contact SIBS Gateway support for a ClientID reset.
HTTP-405Method Not AllowedThe HTTP Method used is not matching any of the API definitions available.Please check in API Market for the correct HTTP Method.
HTTP-429Too Many RequestsThe API calls rate limit has been exceeded.Please check in API Market for information on the rate limits that apply to the API.
HTTP-500Internal Server ErrorThe API call has failed… and its most likely on our side.You should retry the operation, and if the problem persists contact SIBS Gateway support for assistance.
HTTP-503Service UnavailableThe API call is not currently available. Usually we are always on, but short availability issues may occur during scheduled maintenance.You should wait and try again later.