Skip to main content

​
Payments API

The Payments API provides multiple funding options for deposits and withdrawals. Users can fund their accounts via bank transfers (ACH) through Aeropay or card payments through Checkout.com.
Authentication Required - All payment endpoints require a valid access token. See Authentication Setup for setup instructions.

​
Payment Methods

MethodProviderTypeSpeed
Bank Transfer (ACH)AeropayBank account linking1-3 business days
Debit/Credit CardCheckout.comCard paymentsInstant
Apple PayCheckout.comMobile walletInstant

​
APIs

​
Aeropay API

Bank account linking and ACH transfers. Orchestrated Endpoints (Recommended):
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 and FIFO rules
POST/v1/aeropay/depositsCreate ACH deposit
POST/v1/aeropay/withdrawalsCreate ACH withdrawal
Aeropay Integration Guide

​
Checkout API

Card payment processing:
MethodEndpointDescription
POST/v1/checkout/payment-sessionsRequest payment session for card tokenization
POST/v1/checkout/instrumentsSave tokenized card as instrument
POST/v1/checkout/depositsProcess card or Apple Pay deposit
POST/v1/checkout/withdrawalsProcess card or Apple Pay withdrawal
Checkout Integration Guide

​
Funding API

Manage funding sources and transactions:
MethodEndpointDescription
GET/v1/funding/sourcesList funding sources
GET/v1/funding/accountsList funding accounts
PATCH/v1/funding/accounts/{id}Update funding account
GET/v1/funding/transactionsView transaction history
GET/v1/funding/transaction-requirementsCheck FIFO withdrawal requirements
Funding Management

​
Typical Integration Flow

​
New User Onboarding

​
Deposit Flow

  1. Select funding source - User chooses linked bank/card
  2. Check limits - Validate amount against transaction limits
  3. Enter amount - Collect deposit amount
  4. Confirm - Process the deposit
  5. Track status - Monitor transaction completion

​
Withdrawal Flow

  1. Check FIFO requirements - Get withdrawal requirements from funding source
  2. Select destination - User chooses where to send funds (must follow FIFO)
  3. Enter amount - Validate against available balance and requirements
  4. Confirm - Process the withdrawal
  5. Track status - Monitor transaction completion

​
FIFO Withdrawal Requirements

Withdrawals must follow FIFO (First-In-First-Out) rules. Funds must be returned to their original deposit source before they can be withdrawn elsewhere.

​
Example

  1. User deposits $1,000 from Bank A
  2. User deposits $500 from Bank B
  3. User wants to withdraw $1,200
Required withdrawal split:
  • $500 to Bank B (most recent deposit)
  • $700 to Bank A (remaining amount)

​
Checking Requirements

Use the /v1/funding/transaction-requirements endpoint or check the withdrawalRequirements field in Aeropay’s GetAeropayMethods response. 
{
  "withdrawalRequirements": [
    {
      "amount": "500.00",
      "currency": "USD",
      "fundingSourceId": "fs_bank_b",
      "description": "Must withdraw to original deposit source"
    }
  ]
}

​
Funding Source Types

The FundingSourceType enum identifies the payment method:
TypeDescription
FUNDING_SOURCE_TYPE_BANK_ACCOUNTTraditional bank account
FUNDING_SOURCE_TYPE_AEROPAY_BANK_ACCOUNTAeropay-linked bank account
FUNDING_SOURCE_TYPE_CHECKOUT_CARDTokenized payment card
FUNDING_SOURCE_TYPE_APPLE_PAYApple Pay

​
Transaction States

StateDescription
TRANSACTION_STATE_ACKNOWLEDGEDTransaction received
TRANSACTION_STATE_PROCESSINGBeing processed
TRANSACTION_STATE_COMPLETEDSuccessfully completed
TRANSACTION_STATE_CANCELLEDCancelled
TRANSACTION_STATE_ALLOCATEDFunds allocated
TRANSACTION_STATE_REFUNDEDFully refunded
TRANSACTION_STATE_PARTIALLY_REFUNDEDPartially refunded

​
Transaction Types

TypeDescription
TRANSACTION_TYPE_DEPOSITFunds deposited
TRANSACTION_TYPE_WITHDRAWALFunds withdrawn
TRANSACTION_TYPE_TRANSFERInternal transfer
TRANSACTION_TYPE_EXECUTION_FEETrading fee
TRANSACTION_TYPE_SETTLEMENT_FEESettlement fee

​
Best Practices

  1. Use orchestrated endpoints - For Aeropay, use /v1/aeropay/initialize instead of primitive endpoints
  2. Check limits before transactions - Use the Aeropay methods or funding transaction requirements APIs
  3. Respect FIFO rules - Always check withdrawal requirements before processing
  4. Handle all states - Implement UI for pending, success, and failure
  5. Implement webhooks - Don’t rely solely on polling for status updates
  6. Validate amounts client-side - Reduce failed API calls
  7. Store payment method IDs - Cache linked payment methods for faster checkout