Payouts

frameOS supports payouts to cards and bank accounts. Payouts are enabled through the card_receive and bank_account_receive capabilities — each has its own set of requirements that must be satisfied before the capability becomes active and funds can be disbursed.

Both payout types require a verified KYC record on the account. Identity verification is the foundation of payout eligibility — without a verified individual, neither capability can be activated.

ENDPOINTS

POST/v1/accounts

Payout types

Capability	Payout method	Requirements
`card_receive`	Debit card	KYC verified, payment method type, card number, expiration, CVC
`bank_account_receive`	ACH bank transfer	KYC verified, payment method type, routing number, account number, account type

Requirements

Before a payout capability becomes active, frameOS validates that the account has a verified identity and a payment method with the required fields populated. If any fields are missing, the capability remains in a pending state until all requirements are met.

KYC

Both card_receive and bank_account_receive require KYC to have passed on the account. Requesting either capability automatically includes KYC in the onboarding flow. See the KYC documentation for details on what information is collected.

Payment method type

All payment methods require a method_type to be explicitly set. This tells frameOS which set of field requirements to validate against. Valid values are card and ach.

Card requirements

For card_receive, the payment method must have the following fields present and valid:

Field	Description
Method type	Must be set to `card`
Card number	The full card PAN, tokenized
Expiration month	Two-digit expiration month
Expiration year	Two-digit expiration year
CVC	Card verification code

Bank account requirements

For bank_account_receive, the payment method must have the following fields present and valid:

Field	Description
Method type	Must be set to `ach`
Routing number	The bank's ABA routing number
Account number	The bank account number, tokenized
Account type	`checking` or `savings`

We recommend also requesting bank_account_verification alongside bank_account_receive. Bank account verification confirms the account holder owns and controls the bank account before payouts are disbursed, reducing the risk of misdirected payments and fraud. See the bank account verification documentation for details.

Card payouts

Create an individual account with the card_receive capability to enable card payouts. KYC is automatically included. The account holder will add and verify their debit card during the onboarding session.

Parameters

typestringrequired

Must be individual.

capabilitiesarrayrequired

Include card_receive to enable card payouts. KYC is included automatically.

profile.individual.emailstringoptional

The account holder's email address.

profile.individual.name.first_namestringoptional

The account holder's first name.

profile.individual.name.last_namestringoptional

The account holder's last name.

profile.individual.phoneobjectoptional

Object containing number and country_code for the account holder's phone.

POST/v1/accounts

curl --request POST \
  --url https://api.framepayments.com/v1/accounts \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "individual",
  "capabilities": ["card_receive"],
  "profile": {
    "individual": {
      "email": "marcia@example.com",
      "name": {
        "first_name": "Marcia",
        "last_name": "Longo"
      },
      "phone": {
        "number": "3107484186",
        "country_code": "1"
      }
    }
  }
}'

RESPONSE

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "object": "account",
  "type": "individual",
  "status": "pending",
  "external_id": null,
  "capabilities": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891",
      "object": "capability",
      "name": "kyc",
      "status": "pending",
      "disabled_reason": null,
      "currently_due": [],
      "disabled": null
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567892",
      "object": "capability",
      "name": "card_receive",
      "status": "pending",
      "disabled_reason": null,
      "currently_due": [],
      "disabled": null
    }
  ],
  "profile": {
    "individual": {
      "email": "marcia@example.com",
      "ssn_last_four": null,
      "name": {
        "first_name": "Marcia",
        "middle_name": null,
        "last_name": "Longo",
        "suffix": null
      },
      "phone": {
        "number": "3107484186",
        "country_code": "1"
      },
      "birthdate": null,
      "address": null
    }
  },
  "terms_of_service": null,
  "metadata": {},
  "livemode": false,
  "created": 1721010605
}

Bank account payouts

Create an individual account with the bank_account_receive capability to enable ACH payouts. KYC is automatically included. The account holder will connect and verify their bank account during the onboarding session.

Parameters

typestringrequired

Must be individual.

capabilitiesarrayrequired

Include bank_account_receive to enable bank account payouts. KYC is included automatically.

profile.individual.emailstringoptional

The account holder's email address.

profile.individual.name.first_namestringoptional

The account holder's first name.

profile.individual.name.last_namestringoptional

The account holder's last name.

profile.individual.phoneobjectoptional

Object containing number and country_code for the account holder's phone.

POST/v1/accounts

curl --request POST \
  --url https://api.framepayments.com/v1/accounts \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "individual",
  "capabilities": ["bank_account_receive"],
  "profile": {
    "individual": {
      "email": "marcia@example.com",
      "name": {
        "first_name": "Marcia",
        "last_name": "Longo"
      },
      "phone": {
        "number": "3107484186",
        "country_code": "1"
      }
    }
  }
}'

RESPONSE

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "object": "account",
  "type": "individual",
  "status": "pending",
  "external_id": null,
  "capabilities": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891",
      "object": "capability",
      "name": "kyc",
      "status": "pending",
      "disabled_reason": null,
      "currently_due": [],
      "disabled": null
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567892",
      "object": "capability",
      "name": "bank_account_receive",
      "status": "pending",
      "disabled_reason": null,
      "currently_due": [],
      "disabled": null
    }
  ],
  "profile": {
    "individual": {
      "email": "marcia@example.com",
      "ssn_last_four": null,
      "name": {
        "first_name": "Marcia",
        "middle_name": null,
        "last_name": "Longo",
        "suffix": null
      },
      "phone": {
        "number": "3107484186",
        "country_code": "1"
      },
      "birthdate": null,
      "address": null
    }
  },
  "terms_of_service": null,
  "metadata": {},
  "livemode": false,
  "created": 1721010605
}

Complete onboarding

Create an onboarding session after the account is created. frameOS guides the account holder through KYC and payment method setup in a single hosted flow. Once all requirements are met and KYC passes, the payout capability transitions to active.

REQUEST

curl --request POST \
  --url https://api.framepayments.com/v1/onboarding_sessions \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "return_url": "https://example.com/onboarding/complete"
}'

After the session completes, retrieve the account to confirm the capability status has transitioned to active. If any required payment method fields are still missing, the capability will remain pending until they are provided.