Native app

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.

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

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:

The user taps the Apple Pay button in your app to begin the checkout process.
Your app requests a payment session from Dintero's API.
Your app fetches payment operations for the session.
Your app uses the PassKit framework to present the Apple Pay payment sheet to the user.
After the user authenticates the payment with Face ID, Touch ID, or their passcode, Apple Pay returns an encrypted PKPaymentToken.
Your app sends the encrypted payment token to Dintero using the endpoint returned in step 3.
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.

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 of the event from the onpaymentauthorized callback from apple pay}",
    "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.

Prerequisites​

Apple Pay Merchant Onboarding​

Enable Apple Pay on Your Dintero Account​

Integration with Dintero​

Creating an Apple Pay payment session (step 2)​

Fetching payment operations for the session (step 3)​

Posting payment data from Apple Pay (step 6)​

Initiating checkout payment (step 7)​

Best Practices​

Example application​

Further reading​