# Apple Pay™ on iOS Accept Apple Pay™ in your iOS application using Finix. This guide details how to get started accepting Apple Pay in an iOS application using the Finix API. Dues and Assessments We recommend that you pass the address field listed in the steps below. If the address is not passed, you will be charged additional dues and assessments per transaction from the card network. ## Step 1: Onboard with Apple Start by familiarizing yourself with [the prerequisites](/guides/online-payments/digital-wallets/apple-pay) for using Apple Pay™ with Finix. Core Customers If you are a Core customer, instead of Steps 1 or 2 please go to the Application you want to accept Apple Pay. ## Step 2: Register on the Finix Dashboard Before you can begin accepting Apple Pay, you need to first verify and register your application with Apple. You can complete this step with the Finix Dashboard. To register on the Finix Dashboard: 1. Login to your [Finix Dashboard](https://finix.payments-dashboard.com/Login) and click **Developer.** 2. Click **Alt Payment Methods** tab. 3. Click **Add iOS Application** and follow the on-screen instructions. 4. For detailed steps on downloading the certificate file, see Apple's article on [creating a payment processing certificate](https://developer.apple.com/documentation/passkit/apple_pay/setting_up_apple_pay#3735192). ![Apple Pay Finix Dashboard](/assets/apple-pay-finix-dashboard_v2.388316a9eed978839b0ec13c3f85072289990b10455191be13953d3cbe9ae334.08ff7529.png) ## Step 3: Create a Payment with Apple Once registered, your app is authorized to accept Apple Pay payments. At this point, you can also choose to include an [Apple Pay button](https://developer.apple.com/documentation/passkit/apple_pay/offering_apple_pay_in_your_app#:~:text=Add%20the%20Apple%20Pay%20Button) in your iOS app's checkout experience. **Apple Payments Flow:** 1. When buyer makes request to make Apple Pay payment: - Ensure your iOS app creates payment by calling the `startPayment` method of Apple's `PaymentHandler` - For implementation details, see [Apple's PassKit documentation](https://developer.apple.com/documentation/passkit/apple_pay/offering_apple_pay_in_your_app#:~:text=calling%20the%20startPayment) - Ensure to include `requiredBillingContactFields` of `name` and `postalAddress` to collect billing information Collecting Address If address is not collected, fees will apply. 1. When a buyer authorizes a payment: - Apple's completion handler reports the **success** or **failure** of the payment - **Successful** payments return a payment token that you need to include in your request to Finix to create a `Payment Instrument` - Details on how to create a payment with Apple can be found in [Apple's PassKit documentation](https://developer.apple.com/documentation/passkit/apple_pay/offering_apple_pay_in_your_app#:~:text=Send%20the%20payment%20token) ## Step 4: Get Buyer Identity A buyer identity is required before you can proceed with the next steps. You can either create a new buyer identity through the Finix Dashboard or the API, or use an existing one if you’ve already created it. Buyer Identity Data All buyer Identity fields are optional. However, Finix recommends including basic information (name, email, address, and phone) to make payment operations easier. details summary Use an existing buyer 1. Log in to your [Finix Dashboard](https://finix.payments-dashboard.com/Login). 2. In the left sidebar, select **Data Resources** → **Identities**. 3. Search for the buyer identity you want to use. - Confirm the Role is **Buyer**. - Option to use filters to quickly narrow down results. 4. Copy the Buyer Identity - Example: `IDjWktr7BPDGhz4amrPJZoXg` details summary Create a new buyer ```shell Buyer Identity Request curl -i -X POST \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ https://finix.sandbox-payments-api.com/identities \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -d '{ "entity": { "phone": "7145677613", "first_name": "John", "last_name": "Smith", "email": "finix_example@finix.com", "personal_address": { "city": "San Mateo", "country": "USA", "region": "CA", "line2": "Apartment 7", "line1": "741 Douglass St", "postal_code": "94114" } }, "identity_roles": [ "BUYER" ], "tags": { "key": "value" }, "type": "PERSONAL" }' ``` ```json Buyer Identity Response { "id": "IDmkDvJfxZWMEK56FDFtbozo", "created_at": "2024-08-09T09:34:36.87Z", "updated_at": "2024-08-09T09:34:36.87Z", "application": "APgPDQrLD52TYvqazjHJJchM", "entity": { "ach_max_transaction_amount": 0, "amex_mid": null, "annual_card_volume": 0, "business_address": null, "business_name": null, "business_phone": null, "business_tax_id_provided": false, "business_type": null, "default_statement_descriptor": null, "discover_mid": null, "dob": null, "doing_business_as": null, "email": "finix_example@finix.com", "first_name": "John", "has_accepted_credit_cards_previously": false, "incorporation_date": null, "last_name": "Smith", "max_transaction_amount": 0, "mcc": null, "ownership_type": null, "personal_address": { "line1": "741 Douglass St", "line2": "Apartment 7", "city": "San Mateo", "region": "CA", "postal_code": "94114", "country": "USA" }, "phone": "7145677613", "principal_percentage_ownership": null, "short_business_name": null, "tax_authority": null, "tax_id_provided": false, "title": null, "url": null }, "identity_roles": [], "tags": { "key": "value" }, "type": "PERSONAL", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/verifications" }, "merchants": { "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/merchants" }, "settlements": { "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/settlements" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/transfers" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/payment_instruments" }, "associated_identities": { "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/associated_identities" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/identities/IDmkDvJfxZWMEK56FDFtbozo/disputes" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" } } } ``` ## Step 5: Create a Payment Instrument with Finix After creating a payment with Apple, use the payment token that's returned to create a `Payment Instrument` with Finix. Your app needs to [send the payment token](https://developer.apple.com/documentation/passkit/apple_pay/offering_apple_pay_in_your_app#3846471) and [billing address](https://developer.apple.com/documentation/passkit/pkpayment) (returned from Apple's completion handler) to Finix as the `third_party_token`, `name`, and `address` fields when creating the [`Payment Instrument`](/api/payment-instruments). #### Request Arguments | Field | Type | Description | | --- | --- | --- | | `identity` | *string*, **required** | ID of the `Identity` that the card should be associated with. | | `merchant_identity` | *string*, **required** | The `merchant_identity_id` used when registering the business with Apple Pay through our registration API. Log in to dashboard → developer → finix integration → merchant identity ID (e.g. `IDpYDM7J9n57q849o9E9yNrG`) | | `name` | *string*, **required** | Full name of the registered card holder. | | `third_party_token` | *string*, **required** | Stringified token provided by Apple. Required to process Apple Pay transactions. | | `type` | *string*, **required** | Type of Payment Instrument. Use **APPLE_PAY** for transactions using Apple Pay. | | `address` | *object*, **optional** | Object containing address data. If address is not passed, fees will apply. | #### API Request & Response ```shell Payment Instrument Request curl https://finix.sandbox-payments-api.com/payment_instruments \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -d '{ "identity": "IDgWxBhfGYLLdkhxx2ddYf9K", "merchant_identity": "IDpYDM7J9n57q849o9E9yNrG", "name": "John Smith", "third_party_token": "{\"token\":{\"paymentMethod\":{\"network\":\"barcode\",\"type\":\"credit\",\"displayName\":\"\"},\"transactionIdentifier\":\"AE514ADAA44E9C3A0A862C7E4EDEE43C422556FA4748B045F1764860557E8EE6\",\"paymentData\":{\"data\":\"IOg9H5\\/hdpccvHZ03ESJwlJXFlmcnI18WXTSOHOPA82ewYoWVyEMiy63HCsdejXsHIR8a+N\\/5aR24OeJrkxheck2AAl5o1LLJ7jL+75scnf7Z55uQmtVyKITTkH22LrC6E6SgMnXaefJYOTUcG1Veqb\\/dXtpPzqaKACEKDkbVivpDk+A2iX5PLROFTMRgmb9a0HYwHOnVGQzXwiHkX1g6f1R4rILUyMaQ5qLxCplE1t\\/guEYmkGBtOb\\/v8+GRDTl8YrC1tOe\\/cs4aQm4cAKJktFQUTbfAApNFBnKI06mtCM7e7qRna\\/YON3gyci035jA7Zq4kBMo7rQB8puGH6dDqB\\/KsPS6Ps+w688+rqEKz16YUJ\\/LMCOzzBM6bCTOS6eouB1eCh3SJdm\\/lmY=\",\"signature\":\"MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID4zCCA4igAwIBAgIITDBBSVGdVDYwCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE5MDUxODAxMzI1N1oXDTI0MDUxNjAxMzI1N1owXzElMCMGA1UEAwwcZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtUFJPRDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwhV37evWx7Ihj2jdcJChIY3HsL1vLCg9hGCV2Ur0pUEbg0IO2BHzQH6DMx8cVMP36zIg1rrV1O\\/0komJPnwPE6OCAhEwggINMAwGA1UdEwEB\\/wQCMAAwHwYDVR0jBBgwFoAUI\\/JJxE+T5O8n5sT2KGw\\/orv9LkswRQYIKwYBBQUHAQEEOTA3MDUGCCsGAQUFBzABhilodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxlYWljYTMwMjCCAR0GA1UdIASCARQwggEQMIIBDAYJKoZIhvdjZAUBMIH+MIHDBggrBgEFBQcCAjCBtgyBs1JlbGlhbmNlIG9uIHRoaXMgY2VydGlmaWNhdGUgYnkgYW55IHBhcnR5IGFzc3VtZXMgYWNjZXB0YW5jZSBvZiB0aGUgdGhlbiBhcHBsaWNhYmxlIHN0YW5kYXJkIHRlcm1zIGFuZCBjb25kaXRpb25zIG9mIHVzZSwgY2VydGlmaWNhdGUgcG9saWN5IGFuZCBjZXJ0aWZpY2F0aW9uIHByYWN0aWNlIHN0YXRlbWVudHMuMDYGCCsGAQUFBwIBFipodHRwOi8vd3d3LmFwcGxlLmNvbS9jZXJ0aWZpY2F0ZWF1dGhvcml0eS8wNAYDVR0fBC0wKzApoCegJYYjaHR0cDovL2NybC5hcHBsZS5jb20vYXBwbGVhaWNhMy5jcmwwHQYDVR0OBBYEFJRX22\\/VdIGGiYl2L35XhQfnm1gkMA4GA1UdDwEB\\/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0kAMEYCIQC+CVcf5x4ec1tV5a+stMcv60RfMBhSIsclEAK2Hr1vVQIhANGLNQpd1t1usXRgNbEess6Hz6Pmr2y9g4CJDcgs3apjMIIC7jCCAnWgAwIBAgIISW0vvzqY2pcwCgYIKoZIzj0EAwIwZzEbMBkGA1UEAwwSQXBwbGUgUm9vdCBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwHhcNMTQwNTA2MjM0NjMwWhcNMjkwNTA2MjM0NjMwWjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwFxGEGddkhdUaXiWBB3bogKLv3nuuTeCN\\/EuT4TNW1WZbNa4i0Jd2DSJOe7oI\\/XYXzojLdrtmcL7I6CmE\\/1RFo4H3MIH0MEYGCCsGAQUFBwEBBDowODA2BggrBgEFBQcwAYYqaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZXJvb3RjYWczMB0GA1UdDgQWBBQj8knET5Pk7yfmxPYobD+iu\\/0uSzAPBgNVHRMBAf8EBTADAQH\\/MB8GA1UdIwQYMBaAFLuw3qFYM4iapIqZ3r6966\\/ayySrMDcGA1UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB\\/wQEAwIBBjAQBgoqhkiG92NkBgIOBAIFADAKBggqhkjOPQQDAgNnADBkAjA6z3KDURaZsYb7NcNWymK\\/9Bft2Q91TaKOvvGcgV5Ct4n4mPebWZ+Y1UENj53pwv4CMDIt1UQhsKMFd2xd8zg7kGf9F3wsIW2WT8ZyaYISb1T4en0bmcubCYkhYQaZDwmSHQAAMYIBjDCCAYgCAQEwgYYwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTAghMMEFJUZ1UNjANBglghkgBZQMEAgEFAKCBlTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0yMjA0MDExODE2MjJaMCoGCSqGSIb3DQEJNDEdMBswDQYJYIZIAWUDBAIBBQChCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEINpyGxYyGbl1Kj57wU\\/3PijxngHUcidFy9jukG9sccOHMAoGCCqGSM49BAMCBEcwRQIhAPHvbeAIDmJKf2YGS5xcCoySSeCeFf6ThUsKE3UIPWBJAiBQIZZu4wTlZn7R16N+2iTfvuvzJKgeSv8rAs3YM6z56AAAAAAAAA==\",\"header\":{\"publicKeyHash\":\"eOvce9ya55opFC5EXVWlLwzZRVDEY3Hgakf3+C+0zkc=\",\"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE3VnkF5JR9cWuYoeT68dUNp\\/2\\/jGaOiid19UfCV9rEkcPomrzFWEZw\\/dN1uU9RTblnrIQPajFj4R2ZKIpYIlkgA==\",\"transactionId\":\"ae514adaa44e9c3a0a862c7e4edee43c422556fa4748b045f1764860557e8ee6\"},\"version\":\"EC_v1\"}}}", "type": "APPLE_PAY", "address": { "country": "USA", "postal_code": "12345" } }' ``` ```json Payment Instrument Response { "id": "PImE5ZhGZJNFy14DtX8wX6f6", "created_at": "2022-10-10T05:36:55.27Z", "updated_at": "2022-10-10T05:36:55.27Z", "address": { "city": null, "country": "USA", "line1": null, "line2": null, "postal_code": 12345, "region": null }, "application": "APgPDQrLD52TYvqazjHJJchM", "created_via": "API", "currency": "USD", "enabled": true, "fingerprint": "FPR88YBDbK4TqYMUNU8t8fbeQ", "identity": "IDgWxBhfGYLLdkhxx2ddYf9K", "instrument_type": "APPLE_PAY", "bin": "370382", "brand": "AMERICAN_EXPRESS", "card_type": "UNKNOWN", "expiration_month": 11, "expiration_year": 2024, "issuer_country": "UNKNOWN", "last_four": "8576", "name": "John Smith", "tags": {}, "type": "APPLE_PAY", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImE5ZhGZJNFy14DtX8wX6f6" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImE5ZhGZJNFy14DtX8wX6f6/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImE5ZhGZJNFy14DtX8wX6f6/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PImE5ZhGZJNFy14DtX8wX6f6/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K" } } } ``` ## Step 6: Create a Payment Similar to other Finix transactions, after the `Payment Instrument` is created, you can use the instrument and create a [`transfer`](/api/transfers) or an [`authorization`](/api/authorizations/createauthorization) to process transactions. #### Sale - Set the `source` to your Buyer's Payment Instrument ID - Set the `merchant` to an `APPROVED` Merchant account - Set the `amount` in cents ```shell Example Transfer Request curl https://finix.sandbox-payments-api.com/transfers \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -d '{ "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "currency": "USD", "amount": 662154, "source": "PImE5ZhGZJNFy14DtX8wX6f6", }' ``` ```json Example Transfer Response { "id": "TR29av3LN1TAGPbXscsup1tt", "amount": 662154, "tags": {}, "state": "SUCCEEDED", "trace_id": "34f40e87-2599-414b-874b-f472790ff521", "currency": "USD", "application": "APgPDQrLD52TYvqazjHJJchM", "source": "PImE5ZhGZJNFy14DtX8wX6f6", "destination": null, "ready_to_settle_at": null, "externally_funded": "UNKNOWN", "fee": 0, "statement_descriptor": "FNX*FINIX FLOWERS", "type": "DEBIT", "messages": [], "raw": null, "created_at": "2022-08-25T20:39:37.59Z", "updated_at": "2022-08-25T20:39:38.17Z", "idempotency_id": null, "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDpYDM7J9n57q849o9E9yNrG", "subtype": "API", "failure_code": null, "failure_message": null, "additional_buyer_charges": null, "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt/fees" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TR29av3LN1TAGPbXscsup1tt/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8" } } } ``` #### Authorization You can create an Authorization and capture it later using two separate API calls. This approach is useful if you need to first verify the payment details and then capture a specific amount at a later time. For more details, see [Creating and Capturing an Authorization](/guides/online-payments/payment-features/auth-and-captures).