Unzer Docs

    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": ""
  }
}