Google Pay deposit via the REST API

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

Prerequisites

The user has completed onboarding.
The google-pay capability is enabled.
The Payment Widget is set up in your frontend.
Google Pay’s additional setup requirements are met.

Walkthrough

The diagram shows a Google Pay transaction authorization.

Check available rails

Call List rails to verify Google Pay deposit is available.

GET /core/rails?type=apm

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

Check capabilities

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

GET /core/capabilities

{
  "capabilities": [
    {
      "code": "google-pay",
      "name": "Google Pay",
      "enabled": true,
      "requirements": [],
      "restrictions": []
    }
  ]
}

Select destination account

deposits can target any account. If the selected account is not in the 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"
    }
  }
}

Create a quote

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

POST /core/transactions/quote
{
  "origin": {
    "type": "apm",
    "method": "google-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 Google Pay, it contains authorize:google-pay, which indicates that the user must authorize Google Pay before the transaction can be created.

{
  "quote": {
    "id": "c3e8d2f7-9a41-4b75-b8e3-1d6f4a9c2e57",
    "origin": {
      "amount": "50.00",
      "asset": "USD",
      "node": {
        "type": "apm",
        "method": "google-pay"
      },
      "rate": "1"
    },
    "destination": {
      "amount": "48.75",
      "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": [
      {
        "type": "deposit",
        "code": "alternative-payment-method-deposit",
        "asset": "USD",
        "amount": "1.25",
        "percentage": "2.50"
      }
    ],
    "expiresAt": "2025-06-18T01:55:39Z",
    "requirements": [
      "authorize:google-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 Google Pay quote, hand off to the Payment Widget Authorize flow. It presents the Google Pay sheet, creates the transaction, and polls until a terminal status is reached. Google Pay authorizes per transaction — there is no stored authorization to reuse, so the user confirms via the Google Pay sheet every time. By default, the widget renders a full walkthrough around the authorization; in headless mode, it renders only the Google Pay button so you can embed it directly into your own UI — see Headless mode below.

Authorization challenges

Some deposits take one more step after the user confirms the Google Pay sheet: the card backing the wallet may also need to be authorized, through a challenge such as 3DS. The card’s issuer decides this per transaction, so it isn’t known until the transaction is created. The Authorize flow covers this: when a challenge is required, the widget presents it to the user, and only polls for a terminal status once it’s resolved. The same integration works whether or not a challenge comes up — there is nothing extra to handle on your side, beyond expecting those deposits to take longer to complete.

Headless mode is only supported on Android devices and cards that support CRYPTOGRAM_3DS. Cards requiring 3D Secure (3DS) authentication are not supported in headless mode — see Headless mode below.

Create an authorize session

Call Create widget session with flow: "authorize", the quoteId and with the requirements array containing authorize:google-pay.

POST /widgets/payment/sessions
{
  "flow": "authorize",
  "data": {
    "quoteId": "<quoteId>",
    "requirements": [
      "authorize:google-pay"
    ]
  }
}

{
  "session": {
    "flow": "authorize",
    "url": "https://payment.enterprise.uphold.com/",
    "token": "GEbRxBN...edjnXbL",
    "data": {
      "quoteId": "<quoteId>",
      "requirements": [
        "authorize:google-pay"
      ]
    }
  }
}

Initialize the widget with the session. The widget presents the 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 button, and a processing screen while the transaction is confirmed. In headless mode, it renders only the 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 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 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 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 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": "google-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:

Google Pay transaction completed confirmation

Troubleshooting

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

You now support Google Pay deposits 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

Google Pay deposit via the REST API

Prerequisites

Walkthrough

Check available rails

Check capabilities

Select destination account

Find an existing account

Create a new account

Create a quote

Present the order summary

Authorize and create the transaction

Authorization challenges

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 destination account

​Find an existing account

​Create a new account

​Create a quote

​Present the order summary

​Authorize and create the transaction

​Authorization challenges

​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 destination account

Find an existing account

Create a new account

Create a quote

Present the order summary

Authorize and create the transaction

Authorization challenges

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