Apple Pay deposit via the Payment Widget

The Payment Widget handles Apple Pay selection for deposits via the Select for Deposit flow, where users can select Apple Pay as the payment method. After the user confirms an Apple Pay deposit quote, the Payment Widget completes the Apple Pay authorization and creates the transaction via the Authorize flow.

Prerequisites

The user has completed onboarding.
The apple-pay capability is enabled.
The Payment Widget is set up in your frontend.
Apple Pay’s additional setup requirements are met.
The target browser or platform supports Apple Pay.

Walkthrough

Select deposit method

The Payment Widget’s Select for Deposit flow presents the available payment methods, letting the user select Apple Pay when it’s available. It performs selection only: it does not create the quote or the transaction. Call Create widget session to start the select-for-deposit flow. To customize the theme and layout, see the example here.

POST /widgets/payment/sessions
{
  "flow": "select-for-deposit"
}

The response contains a session object with a url field that loads the widget. Return response.session to your frontend as is.

{
  "session": {
    "url": "https://payment-widget.enterprise.uphold.com/?sessionToken=..."
  }
}

import { PaymentWidget } from '@uphold/enterprise-payment-widget-web-sdk';

// session is `response.session` from your backend
const initializeDepositWidget = async (session) => {
  const widget = new PaymentWidget<'select-for-deposit'>(session, { debug: true });

  widget.on('complete', (event) => {
    console.log('Complete', JSON.stringify(event.detail.value));
    widget.unmount();
  });

  widget.on('cancel', () => {
    console.log('Cancelled');
    widget.unmount();
  });

  widget.on('error', (event) => {
    console.error('Error', event.detail.error);
    widget.unmount();
  });

  widget.mountIframe(document.getElementById('payment-container'));
};

<div id="payment-container"></div>

<script>
  // session is `response.session` from your backend
  async function initializeDepositWidget(session) {
    const container = document.getElementById('payment-container');
    const sessionOrigin = new URL(session.url).origin;

    const iframe = document.createElement('iframe');
    iframe.src = session.url;
    iframe.setAttribute('allow', "clipboard-write 'src'; clipboard-read 'src'; payment 'src';");
    iframe.style.width = '100%';
    iframe.style.height = '100%';
    iframe.style.border = 'none';

    function teardown() {
      window.removeEventListener('message', onMessage);
      iframe.remove();
    }

    function onMessage(event) {
      if (event.origin !== sessionOrigin) return;

      switch (event.data?.type) {
        case 'load':
          // Optional: repeat theme or layout from Create session to avoid a brief flash of defaults
          iframe.contentWindow.postMessage({ options: {}, type: 'init' }, sessionOrigin);
          break;
        case 'ready':
          break;
        case 'complete':
          console.log('Complete', JSON.stringify(event.data.value));
          teardown();
          break;
        case 'cancel':
          console.log('Cancelled');
          teardown();
          break;
        case 'error':
          console.error('Error', event.data.error);
          teardown();
          break;
      }
    }

    window.addEventListener('message', onMessage);
    container.appendChild(iframe);
  }
</script>

Both examples above are for web applications — either creating the iframe yourself or letting the SDK do it. For native apps using a WebView, see Native apps with the Web SDK for the SDK’s native-bundling pattern, or Setup without the SDK for the no-SDK approach that loads the session url directly as the WebView’s top-level page.

Handle the complete event

The complete event fires after the user selects Apple Pay.

widget.on('complete', (event) => {
  const { via, selection } = event.detail.value;

  // If via is 'apm', you can check the selected method through the property `selection.method`, which will be 'apple-pay' in this case.
  if (via === 'apm' && selection.method === 'apple-pay') {
    handleApplePaySelected();
  }

  widget.unmount();
});

// Inside the onMessage switch from Set up the widget
case 'complete': {
  const { via, selection } = event.data.value;

  // If via is 'apm', you can check the selected method through the property `selection.method`, which will be 'apple-pay' in this case.
  if (via === 'apm' && selection.method === 'apple-pay') {
    handleApplePaySelected();
  }

  teardown();
  break;
}

Once you have the selection, prompt the user to choose a destination account, then create a quote.

Handle cancellations

widget.on('cancel', () => {
  widget.unmount();
  // Return the user to the previous screen
});

// Inside the onMessage switch from Set up the widget
case 'cancel':
  teardown();
  // Return the user to the previous screen
  break;

Handle errors

The error event fires for critical unrecoverable errors.

widget.on('error', (event) => {
  console.error('Widget error:', event.detail.error);
  widget.unmount();
  // Show a user-friendly error message
});

// Inside the onMessage switch from Set up the widget
case 'error':
  console.error('Widget error:', event.data.error);
  teardown();
  // Show a user-friendly error message
  break;

The Payment Widget handles most errors internally. For unrecoverable errors, the widget fires an error event. It is the host application’s responsibility to handle these events, present an error message to the user, and unmount the widget.

Select destination account

Apple Pay deposits can target any account. If the selected account is not in the Apple Pay account’s currency, the amount will be converted at settlement using Uphold’s prevailing rate. Make sure the destination asset has the necessary features enabled.

Find an existing account

Call List accounts to retrieve the user’s accounts and let them pick the one they want to fund.

GET /core/accounts

{
  "accounts": [
    {
      "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8",
      "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a",
      "label": "My USD account",
      "asset": "USD",
      "balance": {
        "total": "500.00",
        "available": "500.00"
      }
    }
  ]
}

Create a new account

If the user has no accounts, create one with Create account before proceeding.

POST /core/accounts
{
  "label": "My USD account",
  "asset": "USD"
}

{
  "account": {
    "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8",
    "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a",
    "label": "My USD account",
    "asset": "USD",
    "balance": {
      "total": "0",
      "available": "0"
    }
  }
}

Once the user selects Apple Pay and their account, proceed to Create a quote.

Create a quote

Call Create quote with Apple Pay as the origin and the user’s account as the destination. Specify Apple Pay as the origin with type: "apm" and method: "apple-pay".

POST /core/transactions/quote
{
  "origin": {
    "type": "apm",
    "method": "apple-pay"
  },
  "destination": {
    "type": "account",
    "id": "71e9fd4b-dfcd-4643-a5b0-51fd33e50a8d"
  },
  "denomination": {
    "asset": "USD",
    "amount": "50",
    "target": "origin"
  }
}

A successful response includes the quote details and a requirements array. For Apple Pay, it contains authorize:apple-pay, which indicates that the user must authorize Apple Pay before the transaction can be created.

{
  "quote": {
    "id": "c3e8d2f7-9a41-4b75-b8e3-1d6f4a9c2e57",
    "origin": {
      "amount": "50.00",
      "asset": "USD",
      "node": {
        "type": "apm",
        "method": "apple-pay"
      },
      "rate": "1"
    },
    "destination": {
      "amount": "50.00",
      "asset": "USD",
      "node": {
        "type": "account",
        "id": "71e9fd4b-dfcd-4643-a5b0-51fd33e50a8d",
        "ownerId": "48e40cb2-6c34-44ce-b2f1-6adac459bb37"
      },
      "rate": "1"
    },
    "denomination": {
      "asset": "USD",
      "amount": "50.00",
      "target": "origin",
      "rate": "1"
    },
    "fees": [],
    "expiresAt": "2025-06-18T01:55:39Z",
    "requirements": [
      "authorize:apple-pay"
    ]
  }
}

Authorize and create the transaction

After the user confirms the Apple Pay quote, hand off to the Payment Widget Authorize flow. It presents the Apple Pay sheet, creates the transaction, and polls until a terminal status is reached. Apple Pay authorizes per transaction on the user’s device — there is no stored authorization to reuse, so the user confirms with Face ID, Touch ID, or their passcode every time. By default, the widget renders a full walkthrough around the authorization; in headless mode, it renders only the Apple Pay button so you can embed it directly into your own UI — see Headless mode below.

Create an authorize session

Call Create widget session to start the authorize flow, passing the quoteId and adding authorize:apple-pay to the requirements array. For web apps, also include the top-page domain. To enable headless mode, set authorize.mode to headless in options. To customize the theme and layout, see the example here.

The top-page domain is the domain shown in the browser’s URL bar — the very top-level page hosting the widget iframe. For web apps, it must match the domain you registered with Apple Pay for your merchant ID.

POST /widgets/payment/sessions
{
  "flow": "authorize",
  "data": {
    "quoteId": "<quoteId>",
    "requirements": [
      "authorize:apple-pay"
    ],
    "domain": "<top-page-domain>" // For web apps only, required for Apple Pay
  }
}

The response contains a session object with a url field that loads the widget. Return response.session to your frontend as is.

{
  "session": {
    "url": "https://payment-widget.enterprise.uphold.com/?sessionToken=..."
  }
}

Initialize the widget with the session. The widget presents the Apple Pay sheet, collects device data, creates the transaction, and polls until a terminal status is reached.

import { PaymentWidget } from '@uphold/enterprise-payment-widget-web-sdk';

// session is `response.session` from your backend
const initializeAuthorizeWidget = async (session) => {
  const widget = new PaymentWidget<'authorize'>(session, { debug: true });

  widget.on('complete', (event) => {
    const { transaction, trigger } = event.detail.value;
    console.log('Complete', transaction.status, trigger.reason);
    widget.unmount();
  });

  widget.on('cancel', () => {
    console.log('Cancelled');
    widget.unmount();
  });

  widget.on('error', (event) => {
    console.error('Error', event.detail.error);
    widget.unmount();
  });

  widget.mountIframe(document.getElementById('payment-container'));
};

// session is `response.session` from your backend
async function initializeAuthorizeWidget(session) {
  const container = document.getElementById('payment-container');
  const sessionOrigin = new URL(session.url).origin;

  const iframe = document.createElement('iframe');
  iframe.src = session.url;
  iframe.setAttribute('allow', "clipboard-write 'src'; clipboard-read 'src'; payment 'src';");
  iframe.style.width = '100%';
  iframe.style.height = '100%';
  iframe.style.border = 'none';

  function teardown() {
    window.removeEventListener('message', onMessage);
    iframe.remove();
  }

  function onMessage(event) {
    if (event.origin !== sessionOrigin) return;

    switch (event.data?.type) {
      case 'load':
        // Optional: repeat theme, layout, or authorize.mode from Create session to avoid a brief flash of defaults
        iframe.contentWindow.postMessage({ options: {}, type: 'init' }, sessionOrigin);
        break;
      case 'complete': {
        const { transaction, trigger } = event.data.value;
        console.log('Complete', transaction.status, trigger.reason);
        teardown();
        break;
      }
      case 'cancel':
        console.log('Cancelled');
        teardown();
        break;
      case 'error':
        console.error('Error', event.data.error);
        teardown();
        break;
    }
  }

  window.addEventListener('message', onMessage);
  container.appendChild(iframe);
}

Headless mode

By default, the widget renders a full authorization experience — a short walkthrough, the Apple Pay button, and a processing screen while the transaction is confirmed. In headless mode, it renders only the Apple Pay button, with no surrounding UI, so you can embed it directly into your own layout. Your app then owns the surrounding context and the post-authorization experience — progress and success feedback, and a way to cancel. To enable it, set authorize.mode to headless in the options of the Create widget session request:

POST /widgets/payment/sessions
{
  "flow": "authorize",
  "data": { ... }, // Same data as in Create an authorize session
  "options": {
    "authorize": {
      "mode": "headless"
    }
  }
}

See AuthorizeFlowOptions in the SDK reference for the full type definition.

Handle the complete event

The complete event does not guarantee success. Always check transaction.status and trigger.reason.

widget.on('complete', (event) => {
  const { transaction, trigger } = event.detail.value;

  if (trigger.reason === 'transaction-status-changed') {
    if (transaction.status === 'completed') {
      // Show success — the transfer settled
    } else if (transaction.status === 'failed') {
      // Map transaction.statusDetails.reason to a user-facing message
    }
  } else if (trigger.reason === 'max-retries-reached') {
    // Widget stopped polling — continue monitoring via webhooks or polling
  }

  widget.unmount();
});

// Inside the onMessage switch from Set up the widget
case 'complete': {
  const { transaction, trigger } = event.data.value;

  if (trigger.reason === 'transaction-status-changed') {
    if (transaction.status === 'completed') {
      // Show success — the transfer settled
    } else if (transaction.status === 'failed') {
      // Map transaction.statusDetails.reason to a user-facing message
    }
  } else if (trigger.reason === 'max-retries-reached') {
    // Widget stopped polling — continue monitoring via webhooks or polling
  }

  teardown();
  break;
}

Failure reasons in transaction.statusDetails.reason:

Reason	Description
`apm-authorization-failed`	The Apple Pay authorization could not be completed
`card-declined`	The card was declined
`card-declined-by-bank`	The card was declined by the issuing bank
`card-expired`	The card has expired
`card-permanently-declined-by-bank`	The card was permanently declined
`card-unauthorized`	The card authorization was not completed
`card-unsupported`	The card is not supported for this operation
`insufficient-funds`	The origin account has insufficient funds
`provider-maximum-limit-exceeded`	The transaction exceeds provider limits
`velocity`	The transaction was blocked by velocity rules
`unspecified-error`	The transaction failed for an unspecified reason

Handle cancellations

The cancel event fires when the user dismisses the Apple Pay sheet or navigates back without completing authorization.

widget.on('cancel', () => {
  widget.unmount();
  // Return the user to the previous screen
});

// Inside the onMessage switch from Set up the widget
case 'cancel':
  teardown();
  // Return the user to the previous screen
  break;

Handle errors

The error event fires for critical unrecoverable errors — except authorize_transaction_failed, which is retryable in headless mode: the widget resets itself back to its ready state, so the Apple Pay button works again if you leave the widget mounted. In default mode there is no in-place retry for this code — the button does not become usable again, so unmount and create a new authorize session if you want the user to try again. authorize_transaction_failed is the retryable code for Apple Pay authorization and transaction-creation failures. event.detail.error.details.reason narrows down where it happened:

Reason	Description
`unable-to-create-payment-request`	The browser could not build the Apple Pay payment request
`unable-to-make-payment`	The device or browser reported it cannot make this payment
`unable-to-show-payment-request`	The Apple Pay sheet could not be shown
`invalid-payment-response`	The Apple Pay sheet returned a response without the expected payment token
`unable-to-create-transaction`	Apple Pay authorization succeeded, but the transaction itself could not be created — see `event.detail.error.cause` below for the underlying reason

Other failures in this flow — such as a missing or expired quote, or the SDK being unavailable — surface with their own code and are not retryable; handle those with a generic fallback. As with any Widget error, the original failure is preserved in event.detail.error.cause. When details.reason is unable-to-create-transaction, event.detail.error.cause.code is one of:

Code	Description
`entity_not_found`	The quote was not found or has expired
`insufficient_balance`	The origin account has insufficient balance
`operation_not_allowed`	The operation is not permitted
`user_capability_failure`	The user lacks the required capability for this operation

// Set this to match how you configured the widget — see Headless mode above
const isAuthorizeHeadless = false;

widget.on('error', (event) => {
  const { code, cause, details } = event.detail.error;
  console.error('Widget error:', code, details, cause);

  if (code === 'authorize_transaction_failed') {
    if (details.reason === 'unable-to-create-transaction') {
      // The real reason is nested here, not in the top-level `code`
      console.error('Create transaction failed:', cause?.code);
    }

    if (isAuthorizeHeadless) {
      // Retryable in headless mode — keep the widget mounted if you want the user to try again
      return;
    }
    // In default mode there is no in-place retry for this code — fall through and unmount
  }

  widget.unmount();
  // Show a user-friendly error message
});

// Inside the onMessage switch from Set up the widget. `isAuthorizeHeadless` is declared once
// outside the handler (alongside `sessionOrigin`), matching how you configured the widget.
case 'error': {
  const { code, cause, details } = event.data.error;
  console.error('Widget error:', code, details, cause);

  if (code === 'authorize_transaction_failed') {
    if (details.reason === 'unable-to-create-transaction') {
      console.error('Create transaction failed:', cause?.code);
    }

    if (isAuthorizeHeadless) {
      // Retryable in headless mode — keep the iframe/WebView mounted so the user can try again
      break;
    }
    // In default mode there is no in-place retry for this code — fall through and teardown
  }

  teardown();
  // Show a user-friendly error message
  break;
}

Monitor for settlement

Apple Pay deposit transactions remain in processing while the payment settles. Monitor until the transaction reaches a terminal state.

Webhook events (recommended):
- core.transaction.created — status: processing → transaction created, pending settlement
- core.transaction.status-changed — status: completed → funds settled; status: failed → irrecoverable error
Polling (fallback): Get transaction

Sample transaction

In a successful Apple Pay deposit, the origin is represented as an apm node with the method as {apmMethod}. The destination is the user’s account.

{
  "transaction": {
    "id": "9b2f4a17-5e3c-4d77-a8e1-9bcdef2c0a42",
    "origin": {
      "asset": "USD",
      "amount": "50.00",
      "node": {
        "type": "apm",
        "method": "apple-pay"
      }
    },
    "destination": {
      "asset": "USD",
      "amount": "50.00",
      "node": {
        "type": "account",
        "id": "71e9fd4b-dfcd-4643-a5b0-51fd33e50a8d",
        "ownerId": "48e40cb2-6c34-44ce-b2f1-6adac459bb37"
      }
    },
    "status": "completed",
    "quotedAt": "2025-06-18T00:55:39Z",
    "createdAt": "2025-06-18T00:56:39Z",
    "updatedAt": "2025-06-18T00:57:08Z",
    "denomination": {
      "asset": "USD",
      "amount": "50.00",
      "target": "origin"
    }
  }
}

Notify the user

After the transaction completes, display the transaction details to the user so they can confirm the deposit succeeded. Here’s an example:

Apple Pay transaction completed confirmation

Troubleshooting

Having issues rendering Apple Pay? See Troubleshooting in the Payment Widget installation guide.

You now support Apple Pay deposits via the Payment Widget.

User onboarding

Bank transfers

Card transfers

APM transfers

Buy and Sell

Crypto transfers

Travel Rule

Trade & Send

Statements

Resources

Apple Pay deposit via the Payment Widget

Prerequisites

Walkthrough

Select deposit method

Create a widget session

Set up the widget

Handle the complete event

Handle cancellations

Handle errors

Select destination account

Find an existing account

Create a new account

Create a quote

Authorize and create the transaction

Create an authorize session

Set up the widget

Headless mode

Handle the complete event

Handle cancellations

Handle errors

Monitor for settlement

Sample transaction

Notify the user

Troubleshooting

​Prerequisites

​Walkthrough

​Select deposit method

​Create a widget session

​Set up the widget

​Handle the complete event

​Handle cancellations

​Handle errors

​Select destination account

​Find an existing account

​Create a new account

​Create a quote

​Authorize and create the transaction

​Create an authorize session

​Set up the widget

​Headless mode

​Handle the complete event

​Handle cancellations

​Handle errors

​Monitor for settlement

​Sample transaction

​Notify the user

​Troubleshooting

Prerequisites

Walkthrough

Select deposit method

Create a widget session

Set up the widget

Handle the complete event

Handle cancellations

Handle errors

Select destination account

Find an existing account

Create a new account

Create a quote

Authorize and create the transaction

Create an authorize session

Set up the widget

Headless mode

Handle the complete event

Handle cancellations

Handle errors

Monitor for settlement

Sample transaction

Notify the user

Troubleshooting