Apple Pay

Start seamlessly accepting credit card payments and eliminate the need for your customers to type card and shipping details manually. Apple Pay payments are authorized through Touch ID and Face ID.

POST https://pay.solidgate.com/api/v1/apple-pay

The merchant must obtain its own Apple Pay certificate. The merchant must pay for and have an active Apple account, and an Apple merchant ID must be created. 
 

Below are the required actions to be completed in order to obtain the Apple pay certificates from Apple:

Apple Pay Certification

Login to https://developer.apple.com/

  1. Click on the Certificates, IDs & Profiles option.
  2. From the newly opened screen select Merchant IDs and click on the (+) button.
  3. Select an ID and enter a short description.
  4. Once the ID is created, a confirmation screen appears. It is recommended that the merchant ensures that the entered data is valid.
  5. Click the Register button. If the registration is successful a screen showing ‘Registration complete’ appears.
  6. Click on the row with the newly created ID and choose the Edit button and the options to create Identity and Payment Processing Certificates are shown. On this page, the process of adding/verifying domains can be started.


Creating a Payment Processing Certificate

  1. From the Edit screen of the Merchant IDs panel choose the "Create Certificate" button.
  2. Answer “No” to the question “Will payments associated with this Merchant ID be processed exclusively in China?” and click “Continue”. The next screen contains the instruction on how to create the CSR (and the accompanying it public and private keys).
  3. Get certificate by signing request (.csr) file from Solid Support. This is the file that needs to be uploaded to Apple’s web page.
  4. From the Browse dialogue choose the file by clicking on the “Choose File” button and click “Continue”. If the certificate is successfully created, a screen will appear allowing the signed .cer file to be downloaded. Click on the “Download” button and save the file to the disk.
  5. The Payment Processing Certificate (with a .cer extension) must be sent to Solid Support.
     

Creating an Identity Certificate
The identity certificate is needed when merchants want to process Apple Pay payments that originate from within a web page since Apple needs to verify the ownership of the domain from which the payment is initialized. One identity certificate may be used to identify multiple domains.

  1. From Merchant IDs select the desired ID for creating the identity certificate. Choose the Create Certificate button found in the Merchant Identity Certificate box.
  2. The steps for creating and exporting the certificates are the same as for Payment Processing Certificates with the only difference being that the following type should be chosen: Key Size – 2048 bits; Algorithm: RSA.

Adding Domains to the Apple Merchant ID
To use the “Apple Pay on the Web” each of the domains from which the payment request will be made should be verified. The verification is done by uploading a file on a specified location on the merchant’s website.

  1. Select the Add Domain button from the Merchant IDs screen and the Register Merchant Domain window appears
    NOTE: There are a few requirements to the server on which the domain runs (e.g. the merchant server must support the TLS 1.2 protocol and the pages must be served via https). More information can be found here:https://developer.apple.com/reference/applepayjs. The above link also contains a complete guide on how to verify the domain.
  2. From the Register, Merchant Domain window enter the desired domain to be verified and should press Continue.
  3. Download the file generated by Apple and upload it to the path shown on the screen.
  4. Once the file is uploaded the client must click on the Verify button. The uploaded file must be publicly accessible via https.

Integrate with Apple Pay

To process Apple Pay payments, you must configure your Apple Developer account, complete the certification process, and enhance your iOS app or website to have the capability to access Apple Pay payments.

For Apple Pay configuration resources, please refer to the following:

Devices that work with apple pay

Liability shift

Apple Pay transactions using Mastercard and American Express enjoy a liability shift to the card issuer — similar to 3-D secure transactions. Please be aware that although this is a known practice, the issuers are not bound by these terms and can change the liability agreement at any time.

Request Parameters for Apple Pay

 

ParameterMandatoryTypeDescriptionExample
order_idyesstring(100)Order ID specified in the merchant system.1526915864
amountyesintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2000
currencyyesstring(3)Order currency. 3 letter currency code under ISO-4217.USD
order_descriptionyesstring(255)Order description in UTF-8 code.Example description
customer_emailyesstring(100)Customer email.example.test@test.com
ip_addressyesstring(50)Customer IP (only public ones).8.8.8.8
platformyesstring(6)Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application.WEB
geo_countryyesstring(3)Customer country subject to ISO 3166-1 alpha-3.GBR
order_datenostring(50)Date of order creation in format YYYY-MM-DD-HH-MM-SS.2015-12-21 11:21:30
order_itemsnostring(255)Order description in UTF-8 code.item 1, item 2
customer_account_idnostring(100)Сustomer ID specified in the merchant system.4dad42f808
customer_first_namenostring(100)Customer first name.John
customer_last_namenostring(100)Customer last name.Snow
customer_phonenostring(50)Customer phone number.380111111111
customer_date_of_birthnostring(50)Birthdate in YYYY-MM-DD format.2000-11-21
geo_citynostring(100)Customer City.New Castle
languagenostring(2)Customer language settings. Available values: RU - Russian, EN - English.en
fraudulentnobooleanA customer is detected by the merchant system to be suspicious one. The payment will be effected via 3DS.true
callback_urlnostring(255)URL of merchant page, where response with payment result will be sent via the host-to-host connection.http://merchant.example/callback
chargeback_notification_urlnostring(255)URL of merchant page, where the notification of chargeback will be sent.http://merchant.example/chargeback
verifiednobooleanThe user was verified on the shop side.true
retry_attemptnointegerA number of retry payment.1
traffic_sourcenostring(255)Source of traffic.facebook
transaction_sourcenostring(255)Source of transactions on site.main_menu
user_agentnostringUser-agent of the customer.Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36
order_numbernointegerA number of payments by the user.1
versionyesstringVersion information about the payment token.EC_v1
datayesstringEncrypted payment data.qIEHeSmLKw3C5...ZIuf2oPeLhQ1DCaQj
signatureyesstringSignature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm.1UdDwEB/wQEAwIHgDAPBgkqh...92ICIAR2
networknostringCard brand VISA, MASTERCARD
headeryesobjectAn object with header information. 
header : transactionIdyesstringTransaction identifier, generated on the device.7126df4ff8ac61dc60278b5cd549cc98d16b8f41
header: publicKeyHashyesstringHash of the X.509 encoded public key bytes of the merchant’s certificate.mQaQhyhrXX3ZDSQv...ByX0iii0MVHthSQiXQ=
header: ephemeralPublicKeyyes/nostringEphemeral public key bytes. (Mandatory if the version is EC_v1 only)wXtTDj1Cc....5sOXCi7FoVgay
header: applicationDatanostringHash of the applicationData property of the original PKPaymentRequest object. 
header: wrappedKeyyes/nostringThe symmetric key wrapped using your RSA public key. ( Mandatory if the version is RSA_v1 only) 
deviceNostringDevice of customeriPhone 8 iOS 12.0

Request Sample

{
	"amount": 2000,
	"version": "EC_v1",
	"data": "ZJmKTt/Etfpu4zdOc02L6kTBAkUVUqKTsygYX3+sJVYJ1z0YW4i+c14gqSTcqIEHeSmLKw3C5...ZIuf2oPeLhQ1DCaQjw2j0F+56NoCxRjhwQ45HK7lGVy3jOS6ntMhR8=",
	"signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDZiB1tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB/wQEAwIHgDAPBgkqh...92ICIAR2zklUTV63nd8KYl/ZAleY/9HRrrq2m9G30eYy6pj1AAAAAAAA",
	"header": {
		"ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwXtTDj1Cc....5sOXCi7FoVgayKwF+dMNAc6rF2m57yZg6HS841je82NRrGN7exAAuVmJg==",
		"publicKeyHash": "mQaQhyhrXX3ZDSQv...ByX0iii0MVHthSQiXQ=",
		"transactionId": "727126df4ff8ac61dc60278b5cd549cc98d16b8f41b0466e5e330178d14fdf38"
	},
	"currency": "USD",
	"order_id": 1526915864,
	"network": "MASTERCARD",
	"platform": "WEB",
	"geo_country": "GBR",
	"customer_email": "example.test@test.com",
	"ip_address": "8.8.8.8",
	"order_description": "Example description",
	"customer_first_name": "First Name",
	"customer_last_name": "Last Name",
	"customer_phone": "2124141241",
	"callback_url": "http://merchant.example/callback",
	"language": "en",
	"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"
}

Parameters of the successful response

ParameterTypeDescriptionExample
transactionsobjectAn object with information of transactions. 
transactions:<transaction_id>objectTransaction identification within the order. It contains an object with detailed information about the specified transaction. The order can have several transactions.15269093845b02c9c89391d
transactions:<transaction_id>:idstringTransactions identification within the order.15269093845b02c9c89391d
transactions:<transaction_id>:operationstringTransaction type. Transaction types are described in the respective directory.apple-pay
transactions:<transaction_id>:statusstringTransaction status within the order. Transaction statuses are described in the respective directory.created
transactions:<transaction_id>:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2000
transactions:<transaction_id>:currencystringTransaction currencyUSD
orderobjectAn object with order information. 
order:order_idstringOrder ID specified in the merchant system.123443334
order:amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.2575
order:refunded_amountintegerAmount of refund0
order:currencystringOrder currency (3 letter code under ISO 4217).USD
order:fraudulentbooleanThe customer was detected on the merchant side to be suspicious one.true
order:marketing_amountintegerOrder amount converted in USD (or any other currency agreed) under open FX sources at the moment of transaction. This can be applied only for marketing forecasting.2000
order:marketing_currencystringThe currency of the order amount for marketing analytics.USD
order:statusstringStatus of payment processed. Types of order statuses are described in the respective directory.created
order:total_fee_amountintegerAmount of refund0
order:fee_currencystringTotal fee by order transaction 0
transactionobjectAn object with information of the transaction. 
transaction:idstringTransaction identification within the order. The order can have several transactions.15269093845b02c9c89391d
transaction:operationstringTransaction type. Available values - pay.apple-pay
transaction:statusstringTransaction status within the order.created
transaction:amountintegerTransaction amount.20
transaction:currencystringTransaction currency.USD
payment_adviserobject  
transaction:advisestringRecommendation for the next paymentpay / resign / recurring

Example of the successful response

{
	"transactions": {
		"15269093845b02c9c89391d": {
			"id": "15269093845b02c9c89391d",
			"operation": "apple-pay",
			"status": "created",
			"amount": 20,
			"currency": "USD"
		}
	},
	"order": {
		"order_id": 1526909384,
		"status": "processing",
		"amount": 20,
		"refunded_amount": 0,
		"currency": "USD",
		"marketing_amount": 20,
		"marketing_currency": "USD",
		"fraudulent": false,
		"total_fee_amount": 0
	},
	"transaction": {
		"id": "15269093845b02c9c89391d",
		"operation": "apple-pay",
		"status": "created",
		"amount": 20,
		"currency": "USD"
	},
	"payment_adviser": {
		"advise": "pay"
	}
}