Skip to main content
Withdrawals move funds out of a Global Account to a supported destination, such as a bank account or another supported Grid destination. Unlike incoming funds, outbound movement requires customer authorization.
Global Account withdrawals use the quotes flow. Create a quote, have the customer authorize the returned payloadToSign, then execute the quote with Grid-Wallet-Signature.

​
Withdrawal flow

  1. Create or select a destination account.
  2. Create a quote with the Global Account as the source.
  3. Read the payloadToSign returned in the quote’s payment instructions.
  4. Authenticate the customer and create a session.
  5. Sign the payload with the session signing key.
  6. Execute the quote with the Grid-Wallet-Signature header.
  7. Reconcile status with account and transaction webhooks.

​
Create a quote

curl -X POST "$GRID_BASE_URL/quotes" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
    },
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
    },
    "lockedCurrencySide": "SENDING",
    "lockedCurrencyAmount": 10000,
    "description": "Withdrawal to checking"
  }'
The quote response includes the payment instructions for the withdrawal. When the source account is EMBEDDED_WALLET, the response includes a payloadToSign value under paymentInstructions[].accountOrWalletInfo.

​
Execute with a signature

The signature covers the exact paymentInstructions[].accountOrWalletInfo.payloadToSign value returned by the quote. 
curl -X POST "$GRID_BASE_URL/quotes/Quote:019542f5-b3e7-1d02-0000-000000000006/execute" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21" \
  -H "Grid-Wallet-Signature: sandbox-valid-signature"
In production, sign the exact payloadToSign bytes returned by Grid. Do not parse, reserialize, trim, or normalize the payload before signing.

​
Same-currency and cross-currency withdrawals

If the source and destination use the same currency, the quote can represent a same-currency withdrawal. If the destination uses a different currency, the quote locks the conversion details before execution. In both cases, the customer signature requirement comes from the source account type, not from the currency pair. If the source is an EMBEDDED_WALLET, execute the quote with Grid-Wallet-Signature.

​
Reconciliation

After execution, track the withdrawal through transaction and account webhooks:
  • OUTGOING_PAYMENT.* events track the payment lifecycle.
  • INTERNAL_ACCOUNT.BALANCE_UPDATED events track balance changes on the Global Account.
  • Transaction reads provide a backstop for webhook delivery gaps.