Skip to main content

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.

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.
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.

​
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 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 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.
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.

​
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
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. 
{
  "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: 
{
    "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: 
{
    "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 fieldSource
paymentDataDecode PKPaymentToken.paymentData (raw Data) as JSON
paymentMethod.displayNamePKPaymentToken.paymentMethod.displayName
paymentMethod.networkPKPaymentToken.paymentMethod.network.rawValue (e.g. "Visa", "MasterCard")
paymentMethod.typePKPaymentToken.paymentMethod.type as string (e.g. "debit", "credit")
transactionIdentifierPKPaymentToken.transactionIdentifier
See the reference implementation 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 
{
   "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 for an example application on how to accept Apple Pay payments.

​
Further reading

Last modified on May 7, 2026