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:
- The customer is presented with a user-friendly payment sheet.
- Customers choose their preferred payment card from the available options.
- For added security, customers confirm their identity using a biometric authentication, such as Face ID or Touch ID, before finalizing the payment.
| Payment option | Category | Countries | Currencies | Features | Integrations |
|---|---|---|---|---|---|
| Apple Pay | Digital Wallet | Czech Republic, France, Germany, Portugal, Poland, Romania, Slovakia, Slovenia | CZK, EUR, PLN, RON | Pre-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.
For your web integration, there is no need to create your own Apple Pay certificate as you can process payments through our Apple Pay certificate.
Using our Apple Pay certificate ensures faster integration, reduced configuration requirements, and eliminates concerns about expiring certificates by handling the renewal process for you.
Apple Pay can be utilized on designated devices and supported browsers.
For more information, please refer to Apple Pay compatibility page.
How to set up Apple Pay
- Tab 1
- Tab 2
- Tab 3
If you use our Apple Pay certificate you will only need to prepare your server for secure communication with Apple Pay:
- Configure your server to support HTTPS for all pages that include Apple Pay. This guarantees encrypted and protected data transmission.
- Ensure your domain has a valid SSL certificate, which is essential for establishing a secure connection between your server and Apple Pay.
Prior to accepting payments through Apple Pay, it is crucial to set up and configure Apple Pay.
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.
- Tab 1
- Tab 2
- Tab 3
If you use our Apple Pay certificate you will only need to prepare your server for secure communication with Apple Pay:
- Configure your server to support HTTPS for all pages that include Apple Pay. This guarantees encrypted and protected data transmission.
- Ensure your domain has a valid SSL certificate, which is essential for establishing a secure connection between your server and Apple Pay.
The option to use SIBS’ Apple Pay certificate is only available for web integration. For mobile integration, you will need to use your own Apple Pay certificate.
Prior to accepting payments through Apple Pay, it is crucial to set up and configure Apple Pay.
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 theApplePay guidelines to generate a merchant identifier.
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:
- Upload the .csr file that has been shared with you by your account manager; and
- 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.
Make a payment
First, you should initiate the creation of the order.
Upon generating the order request, make sure to include “XPAY” as a payment method.
Following this, proceed to make the payment request as per the following detailed message.
| Environment | URL | Operation Method & Endpoint | Operation Description |
|---|---|---|---|
| PROD | api.sibsgateway.com | POST version-id/{id}/xpay/payment | Requests the payment registered by the previous checkout using xpay payment details inserted by the customer. |
| TEST | stargate-cer.qly.site[1|2].sibs.pt | POST version-id/{id}/xpay/payment | Requests the payment registered by the previous checkout using xpay payment details inserted by the customer. |
The message below represents the Apple Pay Payment Request:
| Location | Data Element | Type | Condition | Description |
|---|---|---|---|---|
| Path | id | String | Conditional | Transaction Id |
Header Parameters:
| Location | Data Element | Type | Condition | Description |
|---|---|---|---|---|
| Request Header | Content-Type | String | Mandatory | application/json |
| Request Header | authorization | String | Mandatory | Bearer Token. Based on OAuth2 authentication performed in a pre-step. |
| Request Header | x-ibm-client-id | String | Mandatory | Token that identifies a client organization. It is provided during onboarding process and must be used in every call. |
Request Parameters:
| Location | Data Element | Type | Condition | Description |
|---|---|---|---|---|
| Request Body | tokenInfo | TokenInfo | Conditional | Payment Tokens |
| Request Body.tokenInfo | tokenName | String | Optional | Token Name |
| Request Body.tokenInfo | tokenType | String | Mandatory | Token Type. Possible values are (“ApplePay”, “GooglePay”). |
| Request Body.tokenInfo | value | String | Mandatory | Token Value |
| Request Body | info | Info | Mandatory | Object that defines the transaction additional information. |
| Request Body.info | deviceInfo | DeviceInfo | Mandatory | Object that defines the customer device information. |
| Request Body.info.deviceInfo | browserAcceptHeader | String | Optional | Browser Accept Header |
| Request Body.info.deviceInfo | browserJavaEnabled | String | Optional | Browser Java Enabled |
| Request Body.info.deviceInfo | browserJavascriptEnabled | String | Optional | Browser Javascript Enabled |
| Request Body.info.deviceInfo | browserLanguage | String | Optional | browser Language |
| Request Body.info.deviceInfo | browserColorDepth | String | Optional | browser Color Depth |
| Request Body.info.deviceInfo | browserScreenHeight | String | Optional | browser Screen Height |
| Request Body.info.deviceInfo | browserScreenWidth | String | Optional | browser Screen Width |
| Request Body.info.deviceInfo | browserTZ | String | Optional | Browser Time Zone |
| Request Body.info.deviceInfo | browserUserAgent | String | Optional | Browser User Agent |
| Request Body.info.deviceInfo | systemFamily | String | Optional | System Family |
| Request Body.info.deviceInfo | systemVersion | String | Optional | System Version |
| Request Body.info.deviceInfo | systemArchitecture | String | Optional | System Architecture |
| Request Body.info.deviceInfo | deviceManufacturer | String | Optional | System Manufacturer |
| Request Body.info.deviceInfo | deviceModel | String | Optional | Device Model |
| Request Body.info.deviceInfo | deviceID | String | Optional | Device Unique Identification |
| Request Body.info.deviceInfo | applicationName | String | Optional | Application Name |
| Request Body.info.deviceInfo | applicationVersion | String | Optional | Application Version |
| Request Body.info.deviceInfo | geoLocalization | String | Optional | Geolocation |
| Request Body.info.deviceInfo | ipAddress | String | Optional | IP Address |
| Request Body.info | customerInfo | CustomerInfo | Mandatory | Key Value tuple array. |
| Request Body.info.customerInfo | key | String | Optional | |
| Request Body.info.customerInfo | value | String | Optional |
After the payment is processed, you will receive a response with transaction status. 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 Code | statusMsg | Description | Action |
|---|---|---|---|
| HTTP-200 | Success | Success response | N/A |
| HTTP-400 | Bad Request | The 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-401 | Unauthorized | On 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-403 | Forbidden | The 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-405 | Method Not Allowed | The HTTP Method used is not matching any of the API definitions available. | Please check in API Market for the correct HTTP Method. |
| HTTP-429 | Too Many Requests | The API calls rate limit has been exceeded. | Please check in API Market for information on the rate limits that apply to the API. |
| HTTP-500 | Internal Server Error | The 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-503 | Service Unavailable | The 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. |
