Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.polymarket.us/llms.txt

Use this file to discover all available pages before exploring further.

Aeropay enables users to link their bank accounts and make ACH transfers for deposits and withdrawals.

​
Authentication

Authentication Required - All Aeropay endpoints require authentication. Include your access token in the Authorization header.
Authorization: Bearer YOUR_ACCESS_TOKEN
See Authentication Setup for instructions on obtaining tokens.

​
Endpoints Overview

MethodEndpointDescription
POST/v1/aeropay/initializeStart bank linking - handles user creation and MFA automatically
POST/v1/aeropay/validate-mfaSubmit MFA code if required
GET/v1/aeropay/methodsList payment methods with limits
POST/v1/aeropay/depositsCreate ACH deposit
POST/v1/aeropay/withdrawalsCreate ACH withdrawal

​
Primitive Endpoints (Advanced)

MethodEndpointDescription
POST/v1/aeropay/usersCreate Aeropay user
POST/v1/aeropay/users/confirmConfirm user with OTP
POST/v1/aeropay/aggregator/credentialsGet bank aggregator credentials
POST/v1/aeropay/aggregator/linkLink bank account
POST/v1/aeropay/funding-sources/enableEnable funding source
The orchestrated flow handles user creation, MFA, and state management automatically. This is the recommended integration path for most use cases.

​
Integration Flow

​
Step 1: Initialize Aeropay

Start the integration by calling initialize. This endpoint handles user creation and MFA triggering automatically.

​
Request

POST /v1/aeropay/initialize

{
  "fundingAccountId": "fa_123",
  "userProfile": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phoneNumber": "+15551234567"
  }
}

​
Response Types

The response contains one of three possible outcomes: 1. MFA Required (existing user needs verification) 
{
  "fundingAccountId": "fa_123",
  "aeropayMfaRequired": {
    "aeropayUserId": "aero_user_123",
    "phone": "+1***1234",
    "email": "j***@example.com",
    "displayMessage": "Please enter the verification code sent to your phone."
  }
}
When you receive aeropayMfaRequired:
  • Display the displayMessage to the user
  • Collect the 6-digit OTP code
  • Call /v1/aeropay/validate-mfa
2. SDK Credentials (new user ready to link bank) 
{
  "fundingAccountId": "fa_123",
  "aeropaySDKCredentials": {
    "fastLinkUrl": "https://fastlink.yodlee.com/...",
    "token": "jwt_token_xyz",
    "username": "aeropay_user_123"
  }
}
When you receive aeropaySDKCredentials:
  • Launch the Yodlee FastLink SDK with these credentials
  • After user links their bank, call /v1/aeropay/aggregator/link
3. Accounts Linked (confirmed user with existing banks) 
{
  "fundingAccountId": "fa_123",
  "aeropayAccountsLinked": {
    "aeropayUserId": "aero_user_123",
    "paymentMethods": [
      {
        "id": "pm_123",
        "bankName": "Chase Bank",
        "accountLast4": "4567",
        "accountType": "checking",
        "status": "active",
        "isDefault": true
      }
    ]
  }
}
When you receive aeropayAccountsLinked:
  • User is ready to make deposits/withdrawals
  • Display their linked accounts
  • Proceed to deposit/withdrawal flow

​
Step 2: Validate MFA (if required)

If initialize returned aeropayMfaRequired, submit the OTP code.

​
Request

POST /v1/aeropay/validate-mfa

{
  "fundingAccountId": "fa_123",
  "aeropayUserId": "aero_user_123",
  "mfaCode": "123456"
}

​
Response

Returns either aeropaySDKCredentials (if user needs to link bank) or aeropayAccountsLinked (if user has existing banks): 
{
  "fundingAccountId": "fa_123",
  "aeropaySDKCredentials": {
    "fastLinkUrl": "https://fastlink.yodlee.com/...",
    "token": "jwt_token_xyz",
    "username": "aeropay_user_123"
  }
}
After receiving SDK credentials, launch the Yodlee FastLink UI. When the user completes bank linking, call the link endpoint.

​
Request

POST /v1/aeropay/aggregator/link

{
  "aeropayUserId": "aero_user_123",
  "aggregatorUserId": "yodlee_user_id",
  "aggregatorUserPassword": "yodlee_token",
  "fundingAccountId": "fa_123"
}

​
Response

{
  "userBankInfo": {
    "bankAccountId": "ba_123",
    "userId": "aero_user_123",
    "bankName": "Chase Bank",
    "accountLast4": "4567",
    "name": "John's Checking",
    "accountType": "checking",
    "status": "active",
    "createdDate": "2024-01-15T10:35:00Z"
  }
}

​
Step 4: Get Payment Methods

Retrieve linked payment methods with deposit limits and withdrawal requirements.

​
Request

GET /v1/aeropay/methods?fundingAccountId=fa_123

​
Response

{
  "paymentMethods": [
    {
      "id": "pm_123",
      "bankName": "Chase Bank",
      "accountLast4": "4567",
      "accountType": "checking",
      "status": "active",
      "isDefault": true,
      "depositLimits": {
        "currency": "USD",
        "maxPerTransaction": "10000.00",
        "maxDaily": "25000.00",
        "max60Day": "100000.00"
      },
      "withdrawalRequirements": [
        {
          "amount": "500.00",
          "currency": "USD",
          "fundingSourceId": "fs_abc123",
          "description": "Must withdraw to original deposit source"
        }
      ]
    }
  ]
}

​
Step 5: Create Deposit

Initiate an ACH deposit from a linked bank account.

​
Request

POST /v1/aeropay/deposits

{
  "userId": "aero_user_123",
  "bankAccountId": "ba_123",
  "amount": "100.00",
  "currency": "USD",
  "description": "Account funding",
  "fundingAccountId": "fa_123",
  "fundingSourceId": "fs_abc123"
}

​
Response

{
  "fundingTransactionId": "ft_deposit_123",
  "aeropayUuid": "aero_txn_abc"
}

​
Step 6: Create Withdrawal

Initiate an ACH withdrawal to the user’s bank account.

​
Request

POST /v1/aeropay/withdrawals

{
  "userId": "aero_user_123",
  "bankAccountId": "ba_123",
  "amount": "50.00",
  "currency": "USD",
  "description": "Withdrawal to bank",
  "fundingAccountId": "fa_123",
  "fundingSourceId": "fs_abc123"
}

​
Response

{
  "fundingTransactionId": "ft_withdraw_456",
  "aeropayUuid": "aero_txn_def"
}

​
ACH Processing Times

Transaction TypeProcessing Time
Deposit1-3 business days
Withdrawal1-3 business days

​
Error Handling

ErrorDescriptionResolution
INSUFFICIENT_FUNDSBank account has insufficient balanceUser needs to add funds to bank
ACCOUNT_NOT_VERIFIEDBank account verification incompleteComplete micro-deposit verification
USER_NOT_CONFIRMEDAeropay user not confirmedComplete MFA verification
INVALID_MFA_CODEIncorrect OTP enteredUser should re-enter or request new OTP
MFA_EXPIREDOTP has expiredRestart the flow with initialize
RATE_LIMIT_EXCEEDEDToo many requestsImplement backoff and retry
LIMIT_EXCEEDEDDeposit/withdrawal exceeds limitsCheck limits via GetAeropayMethods

​
Advanced: Primitive Endpoints

For fine-grained control over the Aeropay integration, you can use the primitive endpoints directly instead of the orchestrated flow.

​
Create Aeropay User

Register the user with Aeropay.
POST /v1/aeropay/users

{
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+15551234567",
  "email": "john.doe@example.com",
  "fundingAccountId": "fa_123"
}
Response:
{
  "user": {
    "userId": "aero_user_123",
    "aeroPassUserUuid": "uuid_abc",
    "firstName": "John",
    "lastName": "Doe",
    "type": "individual",
    "email": "john.doe@example.com",
    "phone": "+15551234567",
    "bankAccounts": [],
    "createdDate": "2024-01-15T10:30:00Z"
  },
  "requiresConfirmation": true,
  "displayMessage": "Please enter the verification code sent to your phone."
}

​
Confirm Aeropay User

If requiresConfirmation is true, submit the OTP.
POST /v1/aeropay/users/confirm

{
  "userId": "aero_user_123",
  "code": "123456",
  "fundingAccountId": "fa_123"
}
Response:
{
  "user": {
    "userId": "aero_user_123",
    ...
  },
  "fundingSourceIds": ["fs_abc123"]
}

​
Get Aggregator Credentials

Get credentials for the bank linking UI.
POST /v1/aeropay/aggregator/credentials

{
  "userId": "aero_user_123",
  "fundingAccountId": "fa_123"
}
Response:
{
  "fastLinkUrl": "https://fastlink.yodlee.com/...",
  "username": "user_abc",
  "token": "jwt_token_xyz"
}

​
Enable Funding Source

Re-enable a disabled funding source.
POST /v1/aeropay/funding-sources/enable

{
  "userId": "aero_user_123",
  "fundingSourceId": "fs_abc123",
  "fundingAccountId": "fa_123"
}