Apple Pay withdrawal via the REST API

This guide covers paying out from a user’s account to Apple Pay using the REST API together with the Payment Widget. Every withdrawal runs through the widget’s Authorize flow, where the user authorizes with Apple Pay. Your backend only creates the quote and the widget session.

Prerequisites

The user has completed onboarding.
The apple-pay-withdrawals capability is enabled.
A funded account to debit the funds from.
The Payment Widget is set up in your frontend and Apple Pay’s additional setup requirements are met. See Installation and setup.

Walkthrough

The diagram shows an Apple Pay transaction authorization.

Check available rails

Call List rails to verify Apple Pay withdrawal is available.

GET /core/rails?type=apm

{
  "rails": [
    {
      "type": "apm",
      "network": "apple-pay",
      "method": "apple-pay",
      "asset": "USD",
      "decimals": 2,
      "features": ["deposit", "withdraw"]
    }
  ]
}

Check capabilities

Call List capabilities to confirm the user has the apple-pay-withdrawals capability enabled with no unmet requirements.

GET /core/capabilities

{
  "capabilities": [
    {
      "code": "apple-pay-withdrawals",
      "name": "Withdraw to apple pay",
      "enabled": true,
      "requirements": [],
      "restrictions": []
    }
  ]
}

Select source account

withdrawals can be sourced from any account. If the selected account is not in the account’s currency, the balance will be converted at the time of the transaction using Uphold’s prevailing rate. Make sure the origin asset has the necessary features enabled. Call List accounts to retrieve the user’s accounts and let them pick the one to withdraw from.

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 quote

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

POST /core/transactions/quote
{
  "origin": {
    "type": "account",
    "id": "b8618cd1-ccb0-4a72-985f-3bb0d268dabd"
  },
  "destination": {
    "type": "apm",
    "method": "apple-pay"
  },
  "denomination": {
    "asset": "USD",
    "amount": "15",
    "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": "15.00",
      "asset": "USD",
      "node": {
        "type": "account",
        "id": "b8618cd1-ccb0-4a72-985f-3bb0d268dabd",
        "ownerId": "48e40cb2-6c34-44ce-b2f1-6adac459bb37"
      },
      "rate": "1"
    },
    "destination": {
      "amount": "14.00",
      "asset": "USD",
      "node": {
        "type": "apm",
        "method": "apple-pay"
      },
      "rate": "1"
    },
    "denomination": {
      "asset": "USD",
      "amount": "15.00",
      "target": "origin",
      "rate": "1"
    },
    "fees": [
      {
        "type": "withdrawal",
        "code": "alternative-payment-method-withdrawals",
        "asset": "USD",
        "amount": "1.00",
        "percentage": "1.75"
      }
    ],
    "expiresAt": "2025-06-18T01:55:39Z",
    "requirements": [
      "authorize:apple-pay"
    ]
  }
}

Present the order summary

Before creating the transaction, display an order summary of the quote — the amount, fees, and the origin and destination — so the user can review it. Here’s an example:

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 with flow: "authorize", the quoteId and with the requirements array containing authorize:apple-pay. For web apps, also include the top-page domain.

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

{
  "session": {
    "flow": "authorize",
    "url": "https://payment.enterprise.uphold.com/",
    "token": "GEbRxBN...edjnXbL",
    "data": {
      "quoteId": "<quoteId>",
      "requirements": [
        "authorize:apple-pay"
      ],
      "domain": "<top-page-domain>" // For web apps only, required for Apple Pay
    }
  }
}

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';

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':
        iframe.contentWindow.postMessage({ ...session, 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);
}

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 SDK for the SDK’s native-bundling pattern, or Setup with JavaScript for the no-SDK approach that loads the session url directly as the WebView’s top-level page.

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.

const widget = new PaymentWidget<'authorize'>(session, {
  debug: true,
  authorize: {
    mode: 'headless'
  }
});

iframe.contentWindow.postMessage({ ...session, options: { authorize: { mode: 'headless' } }, type: 'init' }, sessionOrigin);

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-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. It is your decision whether to unmount the widget and show a user-facing error message, or leave it mounted so the user can try again.

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

  if (code === 'authorize_transaction_failed') {
    // Retryable — keep the widget mounted so the user can try again
    return;
  }

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

// Inside the onMessage switch from Set up the widget
case 'error': {
  const { code, details } = event.data.error;
  console.error('Widget error:', code, details);

  if (code !== 'authorize_transaction_failed') {
    teardown();
    // Show a user-friendly error message
  }
  // authorize_transaction_failed is retryable — keep the iframe/WebView mounted so the user can try again

  break;
}

Error codes in event.detail.error.code:

Code	Description
`authorize_transaction_failed`	The Apple Pay authorization failed — retryable, unlike the other codes below
`entity_not_found`	The quote was not found or has expired
`insufficient_balance`	The origin has insufficient balance
`operation_not_allowed`	The operation is not permitted
`user_capability_failure`	The user lacks the required capability for this operation

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.

Monitor for settlement

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 withdrawal, the origin is the user’s account and the destination is an apm node with the method as apple-pay. The transaction status is initially processing and updates to completed once the transfer settles.

{
  "transaction": {
    "id": "9b2f4a17-5e3c-4d77-a8e1-9bcdef2c0a42",
    "origin": {
      "asset": "USD",
      "amount": "15.00",
      "node": {
        "type": "account",
        "id": "b8618cd1-ccb0-4a72-985f-3bb0d268dabd",
        "ownerId": "48e40cb2-6c34-44ce-b2f1-6adac459bb37"
      }
    },
    "destination": {
      "asset": "USD",
      "amount": "15.00",
      "node": {
        "type": "apm",
        "method": "apple-pay"
      }
    },
    "status": "completed",
    "quotedAt": "2025-06-18T00:55:39Z",
    "createdAt": "2025-06-18T00:56:39Z",
    "updatedAt": "2025-06-18T00:57:08Z",
    "denomination": {
      "asset": "USD",
      "amount": "15.00",
      "target": "origin"
    }
  }
}

Notify the user

After the transaction completes, display the transaction details to the user so they can confirm the withdrawal 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 withdrawals via the REST API together with the Payment Widget.

User onboarding

Bank transfers

Card transfers

APM transfers

Buy and Sell

Crypto transfers

Travel Rule

Trade & Send

Statements

Resources

Apple Pay withdrawal via the REST API

Prerequisites

Walkthrough

Check available rails

Check capabilities

Select source account

Create a quote

Present the order summary

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

​Check available rails

​Check capabilities

​Select source account

​Create a quote

​Present the order summary

​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

Check available rails

Check capabilities

Select source account

Create a quote

Present the order summary

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