Apple Pay

Apple Pay is a popular mobile payment and digital wallet service provided by Apple.

About Apple Pay

Apple Pay is a simple and secure payment solution, compatible with devices and technologies provided by Apple.

With Apple Pay, your customers can pay:

  • In iOS apps
  • In the Safari browser
  • Using contactless POS terminals

The payment, shipping and contact information is secured with Face ID, Touch ID or a passcode.

For the up-to-date list of Apple devices that support Apple Pay, go here.

Requirements

Before you integrate Apple Pay into your website, you need to:

  1. Generate a Payment Processing Certificate
  2. Upload the Payment Processing Certificate CSR to Apple
  3. Download the Apple-signed Payment Processing Certificate
  4. Convert the certificate to a text file
  5. Convert your ECC private key to a non-encrypted PKCS #8 private key
  6. Upload your PKCS #8 private key and your Payment Processing Certificate to Unzer

After that, you can accept an Apple Pay payment.

Step 1: Generate a Payment Processing Certificate

To generate a Payment Processing Certificate, you need to:

  1. Generate an ECC private key.
  2. From the ECC private key, generate a Cerfiticate Signing Request (CSR).

Generate an ECC private key

ECC keys
In Elliptic-curve cryptography (ECC), an ECC private key is a variable used to decrypt code that was encrypted with a public key.

You need to generate an ECC private key in a .key file.

In your command line tool, run the following OpenSSL command:

openssl ecparam -genkey -name prime256v1 -out ecckey.key

This command creates an ECC private key and saves it to a file named ecckey.key.

Generate a Certificate Signing Request

Now, use your new ECC private key to generate a Certificate Signing Request (CSR).

In your command line tool, run the following OpenSSL command:

openssl req -new -sha256 -key ecckey.key -out ecccertreq.csr -subj /CN=www.mydomain.com

Step 2: Upload the Payment Processing Certificate CSR to Apple

Upload the newly created Payment Processing Certificate CSR to your Apple developer account.

For more information on configuring your Apple developer account, see the Apple Developer Account Help.

Step 3: Download the Apple-signed Payment Processing Certificate

Download and back up the Apple-signed Payment Processing Certificate (apple_pay.cer).

Step 4: Convert the certificate to a text file

In your command line tool, convert the Apple-signed Payment Processing Certificate to a text file in the .pem format:

openssl x509 -inform der -in apple-pay.cer -out apple-pay.pem

Step 5: Convert your ECC private key to a non-encrypted PKCS 8 private key

PKCS #8
In cryptography, PKCS #8 is a standard syntax for storing private key information.

To use your ECC private key for decrypting, you need to convert it to a non-encrypted PKCS #8 private key, like this:

openssl pkcs8 -topk8 -nocrypt -in ecckey.key -out privatekey.key

Step 6: Upload your private key and your Payment Processing Certificate to Unzer

Now you need to upload both your Apple-signed Payment Processing Certificate and your PKCS #8 private key to Unzer.

Upload your PKCS #8 private key to Unzer

To upload your PKCS #8 private key to Unzer, make a POST call to /keypair/applepay/privatekeys, with the following parameters in the request body:

Parameter Required Type Default Description Example
format Yes String / The file type extension. PEM
type Yes String / The type of the key. private-key
certificate Yes String / Your non-encrypted PKCS #8 private key. See the example request below.
POST https://api.unzer.com/v1/keypair/applepay/privatekeys

Body:
{
   "format": "PEM",
   "type": "private-key",
   "certificate": "MHcCAQEEIKTAL4TwcY9Upc/9XdIlxRBvU0fuaFA2BhGkqDNxiBkgoAoGCCqGSM49AwEHoUQDQgAEZVFjAqVtO/2vgaIGJFA7n7WUqewS6lbHcQwK7sCAMmDgKHcikCY5FOl7euO3sEBKtKprrnh/u7nlace+0lPYeg=="
}
Body:
{
    "id": "s-key-1",
    "paymentType": "applepay"
}
Property Type Description
id String The ID of your private key resource.
paymentType String Your payment type.

Upload the Apple-signed Payment Processing Certificate to Unzer

To upload your certificate to Unzer, make a POST call to /keypair/applepay/certificates with the following parameters in the request body:

Parameter Required Type Default Description Example
format Yes String / The file type extension. PEM
type Yes String / The type of a key. certificate
private-key Yes String / The private key resource you received after uploading your private key. s-key-1
certificate Yes String / Your non-encrypted PKCS #8 private key. See the example request below.
POST https://api.unzer.com/v1/keypair/applepay/certificates

Body:
{
    "format": "PEM",
    "type": "certificate",
    "private-key": "s-key-1",
    "certificate": "MIIEcDCCBBagAwIBAgIIHrTLsxpoEO8wCgYIKoZIzj0EAwIwgYAxNDAyBgNVBAMMK0FwcGxlIFdvcmxkd2lkZSBEZXZlbG9wZXIgUmVsYXRpb25zIENBIC0gRzIxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xOTAxMDIwMzM5NDBaFw0yMTAxMzEwMzM5NDBaMIGhMSYwJAYKCZImiZPyLGQBAQwWbWVyY2hhbnQuY29tLmhlaWRlbHBheTE8MDoGA1UEAwwzQXBwbGUgUGF5IFBheW1lbnQgUHJvY2Vzc2luZzptZXJjaGFudC5jb20uaGVpZGVscGF5MRMwEQYDVQQLDAo2ODQ5TjM0SEQ5MRcwFQYDVQQKDA5oZWlkZWxwYXkgR21iSDELMAkGA1UEBhMCREUwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAARkwLPV/pDAL6Wt2KjsJcPZMJ8bovAV8NMucaH+V7zpzzcrKtDgHDmX2DnF1eTgbmP9uRJiBr94QeLRkfdFeRSGo4ICVTCCAlEwDAYDVR0TAQH/BAIwADAfBgNVHSMEGDAWgBSEtoTMOoZichZZlOgao71I3zrfCzBHBggrBgEFBQcBAQQ7MDkwNwYIKwYBBQUHMAGGK2h0dHA6Ly9vY3NwLmFwcGxlLmNvbS9vY3NwMDQtYXBwbGV3d2RyY2EyMDEwggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDYGA1UdHwQvMC0wK6ApoCeGJWh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxld3dkcmNhMi5jcmwwHQYDVR0OBBYEFNoG0VJGMZXqat1BPVqm2bX6YmpJMA4GA1UdDwEB/wQEAwIDKDBPBgkqhkiG92NkBiAEQgxANjM5NjBGRUJEOUFFQ0RDRjgyM0U5MTlDMkM4ODgzQTUwQTk4OUUwMUU2RUFDOTlBQjZCODM1QzlFNTUxRTdGMTAKBggqhkjOPQQDAgNIADBFAiBvWJd2AgxURTjh+wZdy22coQGAIaLTMPJhfQKIzpJj1wIhAIsoThZcqKEPIQKsGt+6P+h5ZtoYBKhV2nIZVUjGp8SU"
}
Body:
{
    "id": "s-crt-1",
    "paymentType": "applepay"
}
Property Type Description
id String The ID of your certificate resource.
paymentType String Your payment type.

Optional: Update the certificate

If you have more certificates and want to switch to a new certificate before the old one runs out, you need to update the certificate.

Make a POST call with the ID of your certificate resource in the request path:

POST https://api.unzer.com/v1/keypair/applepay/certificates/{certificate_ID}/activate

Body:
{
    "id": "s-crt-2",
    "active": true
}
Property Type Description
id String The ID of your certificate resource.
active Boolean Indicates if the certificate is active or not.

Accept an Apple Pay payment

After uploading your private key and certificate to Unzer, you’re ready to accept Apple Pay payments.

Step 1: Create an applepay resource

Requirements
Before creating an applepay resource, make sure you fulfilled the requirements.

To do create an applepay resource, make a POST call to /types/applepay with the following parameters in the request body:

Parameter Required Type Default Description Example
version Yes String / Version information about the payment token.

The token uses EC_v1 for ECC-encrypted data,
and RSA_v1 for RSA-encrypted data.
EC_v1
data Yes String / Encrypted payment data. See the sample below.
signature Yes String / Signature of the payment and header data.

The signature includes the signing certificate,
its intermediate CA certificate,
and information about the signing algorithm.
See the sample below.
ephemeralPublicKey Yes String / Ephemeral public key bytes. EC_v1 only. See the sample below.
publicKeyHash Yes String / Hash of the X.509 encoded public key bytes of the merchant’s certificate. See the sample below.
transactionId No String / Transaction identifier generated on the device. See the sample below.

You can extract all necessary parameters, like data, signature or transactionId, from the iOS application and the specific device.

POST https://api.unzer.com/v1/types/applepay

Body:
{
        "version":"EC_v1",
        "data":"32wNUOV/SirrVHNV/IyEMrVE733qzFhGLwlcgFfG4QDBTytusn/Ie1DbnoIlOm6iGeCvxHxicoH1c2yuvQPKuyCRWvz35KTu8GQCQ6+l8CJ4dSPsn/8IM/I8rq/LyFzsWRrxfZkP6FwRd+bOB81pKYugr90HECo2SBlW6j0T2pjZLNw7rGTFCq2hllgasCVsyAAcoHA4TOZ1lDYx2g8NAD0krD/CxrSPixekCKUagTqCeA2Al3zvhc8CiTkHvTJcz62g2FgmLq2sDR1+2b000QPGr69tzYaUUgCRcvHJVh+9AuesjlOeM53637alriGYsJ+ZD0r5cW8T9EptE4cE38EWC+d7jjXg4iKFYYfu1n5RggYHf+p19ydvQ24wS8miJcOmnhgQDsz/4nXv1uYlyzgZTdGqAUl2FIWMXwmjHbE=",
        "signature":"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",
        "header":{
            "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEaGe+L4FIP3kSN+GEKWT/6Yh0quxKKyUahQO2SW+0xNKqB0ocC1DKbclbGq2RQg7n1PBM1OuYDxvwDcPBnpfnkw==",
            "publicKeyHash":"M2yzlpBsH3GwH5jTV9GgKC7bAUdeIOIfjwQhoKjg5+s=",
            "transactionId":"b9e1338924cca43341152525553e9b97d3fb94e2e5ce3a84d4456255082444bb"
        } 
}
{
    "id": "s-apl-faucbirhd6yy",
    "method": "apple-pay",
    "recurring": false,
    "geoLocation": {
        "clientIp": "115.77.189.143",
        "countryCode": ""
    },
    "applicationPrimaryAccountNumber": "370295******922",
    "applicationExpirationDate": "07/2020",
    "currencyCode": "EUR",
    "transactionAmount": "1.5000"
}
Property Type Description
id String The ID of the applepay resource that you just created.
method String The payment method.
recurring Boolean Indicates whether this is a recurring payment.
clientIp String The IP address of the device used for the payment.
countryCode String The country associated with clientIp, displayed in the ISO 3166-1 alpha-2 format.
applicationPrimaryAccountNumber String Defines the primary account number associated with the application.
applicationExpirationDate Date in the format YYMMDD The card expiration date.
currencyCode String The transaction currency, in the ISO 4217 alpha-3 format.
transactionAmount Number The transaction amount.

Step 2: Make a charges call

To charge the applepay resource, make a payments/charges call with the following parameters in the request body:

Parameter Required Type Default Description Example
amount Yes Number / The amount to be charged. 50
currency Yes String / The transaction currency, in the ISO 4217 alpha-3 format. EUR
returnUrl No String / After the customer confirms
the payment on the payment page, returnUrl is called to redirect customer to the shop’s website.
https://www.unzer.com
typeId Yes String / The newly-created payment type ID that you received
in response to creating an applepay resource (Step 1).
s-apl-faucbirhd6yy
metadataId No String / The ID of the metadata resource to be used. s-mtd-1
customerId No String / The ID of the customers resource to be used. s-cst-1
POST https://api.unzer.com/v1/payments/charges

Body:
{
  "amount" : "50",
  "currency" : "EUR",
  "returnUrl" : "https://www.unzer.com",
  "orderId": "", 
  "resources" : {
    "typeId" : "s-apl-faucbirhd6yy",
    "metadataId": "",
    "customerId": ""
  }
}