> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dintero.com/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.dintero.com/feedback

```json
{
  "path": "/docs/checkout/apple-pay/apple-pay-native-app",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Native app integration

> Integrate Apple Pay in your iOS app using PassKit and Dintero PSP for full control over the in-app payment sheet and merchant onboarding.

Native app integration provides you with complete control over the Apple Pay user experience within your iOS application. While Dintero handles the payment processing, you implement the Apple Pay user interface directly using Apple's frameworks (like PassKit), providing a seamless and highly customized experience for your customers.

<Info>
  Native app integration with Apple Pay is supported only via `dintero_psp.applepay`. If you are using Worldline (`bambora.applepay` in the API), native app integration is not available.
</Info>

### Prerequisites

#### Apple Pay Merchant Onboarding

Before you can implement Apple Pay in your app, you must complete Apple's merchant onboarding process through your Apple Developer Account. This process involves several key steps:

* Create a Merchant Identifier: This is a unique identifier that registers your business with Apple as a merchant capable of accepting payments. A single merchant identifier can be used for multiple apps and websites.

* Create a Payment Processing Certificate: This certificate is associated with your merchant ID and is used to encrypt payment data. Contact [integration@dintero.com](mailto:integration@dintero.com) and request a Certificate Signing Request (CSR) from Dintero and use the CSR to create this certificate with Apple. After the certificate has been created you have to download the certificate and get in touch with [integration@dintero.com](mailto:integration@dintero.com) for instructions on how to send us your certificate.

* Enable Apple Pay in Xcode: You need to enable the Apple Pay capability within your Xcode project settings and link it to the merchant identifier you created.

Note: This process requires an active Apple Developer Program account and can take some time, so it's best to plan accordingly.

<Info>
  For Apple Pay integration, you must create and use **two separate merchant identifiers** and **two separate Apple Pay Payment Processing Certificates**—one set for your test (sandbox) environment and one set for your production environment. Each certificate must be created using the corresponding merchant identifier and environment selection in the Apple Developer portal.
</Info>

#### Enable Apple Pay on Your Dintero Account

During your onboarding you will be able to select Apple Pay as a payment method. If it's not enabled, you can go to settings and payment methods. From there, you can enable Apple Pay as a payment method for your account. If you use payment profiles, ensure that Apple Pay is added to the relevant profiles.

### Integration with Dintero

The native payment flow with Apple Pay and Dintero is a collaborative process between your app and Dintero's API. The general flow is as follows:

1. The user taps the Apple Pay button in your app to begin the checkout process.

2. Your app requests a payment session from Dintero's API.

3. Your app fetches payment operations for the session.

4. Your app uses the PassKit framework to present the Apple Pay payment sheet to the user.

5. After the user authenticates the payment with Face ID, Touch ID, or their passcode, Apple Pay returns an encrypted PKPaymentToken.

6. Your app sends the encrypted payment token to Dintero using the endpoint returned in step 3.

7. Your app initiates the checkout Payment using the `transaction_id` returned in step 6 and Dintero creates an authorized transaction

```mermaid theme={null}
sequenceDiagram
    actor C as Customer
    participant A as Your app
    participant AP as Apple Pay
    participant DC as Dintero Checkout
    participant DPS as Dintero PSP Service

    C->>A: 1. User starts payment  (taps Apple Pay button)
    A->>DC: 2. Request Payment Session (to Dintero API)
    DC-->>A: Payment Session ID / Response

    A->>DC: 3. Fetch Payment operation for session
    DC-->>A: Payment operations for apple pay

    A->>AP: 4. Request Payment Data (Presents Apple Pay sheet via PassKit)
    AP-->>C: Presents Apple Pay Sheet
    C->>AP: Authenticates payment (Face ID/Touch ID)

    AP-->>A: 5. Returns Encrypted Payment Data (PKPaymentToken)
    Note over A: Token is encrypted

    A->>DPS: 6. Post Payment Data to Dintero PSP
    DPS->>DPS: Decrypts token and communicates with Card Network
    DPS-->>A: PSP result

    A->>DC: 7. Initiating checkout payment with PSP result
    DC-->>A: Payment Session Result

    Note over A: Update UI/Complete checkout
```

This integration gives you full control over the user experience while leveraging Dintero's secure and reliable payment processing backend.

> Note that only the Visa and Mastercard payment networks are supported.

#### Creating an Apple Pay payment session (step 2)

Example payment session request body, note that the return\_url must match the app url namespace and that `initial_recipient=merchant` must be set if the link in the session payment response should be followed.

```json theme={null}
{
  "url": {
    "return_url": "yourapp://redirect?initial_recipient=merchant",
    "callback_url": "https://your-backend-callback-handler.com/endpoint"
  },
  "order": {
    "amount": 20100,
    "currency": "NOK",
    "merchant_reference": "<unique-reference>",
    "items": [
      {
        "id": "<item-id>",
        "line_id": "<unique-id-per-line>",
        "description": "Item to be paid for",
        "amount": 20100,
        "quantity": 1,
        "vat_amount": 4020,
        "vat": 25
      }
    ]
  },
  "configuration": {
    "channel": "in_app",
    "dintero_psp": {
      "applepay": {
        "enabled": true
      }
    }
  },
  "expires_at": "2099-12-31T23:23:59.999Z"
}
```

#### Fetching payment operations for the session (step 3)

The payment operations describe how to post payment data from Apple Pay to Dintero. For a native app integration only the operation with `rel` set to `submit-dintero-psp-applepay` is used.

Example request (note, there is no body or content type in this POST request):

```
POST https://checkout.dintero.com/v1/view/{session_id}/payments/dintero_psp.applepay
```

Example response body:

```json theme={null}
{
    "operations": [
        {
            "href": "https://payments.psp.dintero.com/apple-pay/v1/{account_id}/payments/{payment_id}/transactions?access_token={access_token}",
            "method": "POST",
            "rel": "submit-dintero-psp-applepay",
            "content_type": "application/json",
            "supported_networks": [
                "VISA",
                "MASTERCARD"
            ],
            "merchant_country": "NO"
        },
        {
            "href": "https://payments.psp.dintero.com/apple-pay/v1/{account_id}/payments/{payment_id}/validate-merchant?access_token={access_token}",
            "method": "POST",
            "rel": "validate-dintero-psp-applepay-merchant",
            "content_type": "application/json"
        }
    ]
}
```

#### Posting payment data from Apple Pay (step 6)

Post the encrypted payment data from Apple Pay to Dintero. For this you use the `submit-dintero-psp-applepay` payment operation.

Extract the `access_token` query parameter from the operation `href` and post the payment data. Please remove the `access_token` query param from the URL before posting payment data.  Ensure you send the `payment_data` as a JSON string.

##### Transforming the Apple Pay payment token

The `PKPaymentToken` from Apple Pay cannot be sent directly — it must be transformed into the following JSON structure before being stringified as `payment_data`:

```json theme={null}
{
    "payment": {
        "token": {
            "paymentData": {
                "data": "<encrypted payment data from PKPaymentToken.paymentData>",
                "signature": "<signature>",
                "header": {
                    "publicKeyHash": "<hash>",
                    "ephemeralPublicKey": "<key>",
                    "transactionId": "<id>"
                },
                "version": "<payment_data_version>" // eg. "EC_v1"
            },
            "paymentMethod": {
                "displayName": <token.paymentMethod.displayName> // "Visa 1234",
                "network": "token.paymentMethod.network?.rawValue" // "Visa",
                "type": "token.paymentMethod.type.stringValue" // "debit"
            },
            "transactionIdentifier": "<transaction identifier from PKPaymentToken>"
        }
    }
}
```

The fields map from `PKPayment` as follows:

| JSON field                  | Source                                                                          |
| --------------------------- | ------------------------------------------------------------------------------- |
| `paymentData`               | Decode `PKPaymentToken.paymentData` (raw `Data`) as JSON                        |
| `paymentMethod.displayName` | `PKPaymentToken.paymentMethod.displayName`                                      |
| `paymentMethod.network`     | `PKPaymentToken.paymentMethod.network.rawValue` (e.g. `"Visa"`, `"MasterCard"`) |
| `paymentMethod.type`        | `PKPaymentToken.paymentMethod.type` as string (e.g. `"debit"`, `"credit"`)      |
| `transactionIdentifier`     | `PKPaymentToken.transactionIdentifier`                                          |

See the [reference implementation](https://github.com/Dintero/dintero-ios-native-example) for a complete Swift example of this transformation.

Example request

```
POST https://payments.psp.dintero.com/apple-pay/v1/{account_id}/payments/{payment_id}/transactions
Authorization: {access_token}
Content-Type: application/json
Body:
{
    "payment_data": "{JSON stringified object with the structure described above}",
    "reference": "{unique id}"
}
```

Example response body

```json theme={null}
{
   "payment_id": "{payment_id}",
   "transaction_id": "{transaction_id}",
   "type": "APPLE_PAY_AUTHENTICATION"
}
```

#### Initiating checkout payment (step 7)

Initiating the checkout payment using the `transaction_id` returned when posting the payment data.

```
POST https://checkout.dintero.com/v1/sessions/{session_id}/pay
Content-Type: application/json
Body:
{
    "payment_product_type": "dintero_psp.applepay",
    "psp_transaction_id": "{transaction_id}"
}
```

After posting to the initiate checkout payment endpoint the payment session is completed and has created an authorized transaction. The payment response will contain a `return_url` but there is no
need to follow or call it.

### Best Practices

Make sure you follow the following best practices.

* Never log or store Apple Pay tokens
* Implement proper error handling to avoid exposing sensitive information
* Validate all payment responses on your server

### Example application

See [https://github.com/Dintero/dintero-ios-native-example](https://github.com/Dintero/dintero-ios-native-example) for an example application on how to accept Apple Pay payments.

### Further reading

* [Apple Pay Developer Documentation](https://developer.apple.com/documentation/PassKit/apple-pay)
* [Apple Pay Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/apple-pay)
* [Apple Pay Marketing Guidelines](https://developer.apple.com/apple-pay/marketing/)
* [Apple Pay
  Merchant Integration Guide ](https://developer.apple.com/apple-pay/Apple-Pay-Merchant-Integration-Guide.pdf)