> ## Documentation Index > Fetch the complete documentation index at: https://docs.yativo.com/llms.txt > Use this file to discover all available pages before exploring further. # Corporate Card Integration > Corporate Card Integration — integration guide for the Yativo API. The Corporate Card API lets a business issue and manage spend cards for its own employees. An **Employee** is the true card holder — created once per person, KYC'd, funded from a balance the business assigns to them, and then able to hold any number of cards with no artificial limit. All endpoints below require the same authenticated, per-business request context used across the rest of the API (API key + bearer token). Routes carry no `customer_id`/`employee_id` in the URL — both are passed as request fields (query string on `GET`, request body on `POST`). Every `customer_id` must belong to the authenticated business account, and every `employee_id` must belong to that same `customer_id` — requests for data outside your own business return `404`. ## Access requirements Business Spend Cards must be enabled for your account before any of these endpoints can be used. Two checks apply to every Corporate Card request, and to the employee portal and `/api/v1/spend/*` and `/api/v1/business/spend-card/*` endpoints: 1. **Your account is approved for Business Spend Cards.** Approval is granted by Yativo — contact support to request it. Until then every request returns `403`: `Your account is not yet approved for Business Spend Cards. Please contact support.` 2. **The customer holds an approved `faster_payments` endorsement.** Checked for whichever customer the request targets — directly via `customer_id`, or through an `employee_id` or `card_id` that belongs to it. Otherwise: `This customer does not have an approved Faster Payments endorsement.` (`403`) Requests that don't name a customer (for example, an unfiltered card list) only need check 1. Access is also blocked (`403`) while the employee is `suspended` or `terminated`, the customer is banned, or your user account is suspended. ## Concepts * **Customer** — the business's own registered customer record (already used elsewhere in the API for KYC, virtual accounts, etc). Corporate Card is layered on top of an existing, fully-KYC'd customer. * **Employee** — the card holder. One employee can hold multiple cards. Created explicitly via the Employees endpoints below, or automatically the first time a card is requested for a customer that has none yet. * **Employee KYC** — a lightweight KYC record captured per employee (identity, address, government ID, payslip/work contract, proof of address) required before a card can be fully activated for spend. * **Memo / Invoice** — a note and/or invoice an employee attaches to their card activity, which the business then approves or rejects. * **USDC balance** — the business's own funding wallet. Funding an employee's card balance debits this wallet; withdrawing credits it back. Every [fee](#fees) is also charged to this balance. * **Employee card balance** — the money an employee can spend. It belongs to the employee, and every card they hold spends from it. You fund and withdraw it; the employee can only view it (see the [Employee Portal](https://docs.yativo.com/yativo-platform/business/employee-portal.md)). It exists once the employee's first card is issued. * **Reserve** — a minimum amount that must stay in your USDC balance at all times while your account is approved for Business Spend Cards. See [Reserve](#reserve). * **Corporate Card wallet** — a dedicated USDC (Solana) deposit address a business can provision once to fund its USDC balance by depositing crypto directly, separate from any other wallets on the account. ## Customers ### Create a customer ``` POST /api/v1/customer ``` Required fields: `customer_name`, `customer_email`, `customer_phone`, `customer_type` (`individual` or `business`), `customer_country`. Before the customer can be used for Corporate Cards it also needs an approved `faster_payments` endorsement — see [Access requirements](#access-requirements). *** ## Employees ### Create an employee ``` POST /api/v1/corporate-card/employees ``` ```json theme={null} { "customer_id": "cus_123", "full_name": "Jane Doe", "email": "jane@example.com", "dob": "1990-04-12", "occupation": "Operations Manager", "metadata": { "department": "Finance", "employee_number": "EMP-0042" } } ``` **Fields** | Field | Required | Description | | - | - | - | | `customer_id` | Yes | The customer this employee belongs to. | | `full_name` | Yes | Display name (max 191 chars). | | `email` | No | Contact email. | | `dob` | No | Date of birth (`YYYY-MM-DD`). | | `occupation` | No | Job title / occupation (max 191 chars). | | `metadata` | No | Arbitrary JSON object for extra fields (department, employee number, etc.). | **Selfie image (optional)** — supply one of: | Field | How to send | Notes | | - | - | - | | `selfie_image` | `multipart/form-data` file, or a base64 string (`data:image/png;base64,...` or raw base64) | jpeg / jpg / png / webp, max 10 MB | | `selfie_image_url` | JSON string | Pre-hosted URL stored as-is | When both are present the uploaded file takes precedence. Omit both to skip. Uploaded selfies are stored privately; see [Private document links](#private-document-links). The upload happens before the employee is created: if it fails, the request returns `502` (`Unable to upload the selfie image. Please try again.`) and no employee is created, so it is safe to retry. ### Update an employee ``` PUT /api/v1/corporate-card/employees/{employee_id} PATCH /api/v1/corporate-card/employees/{employee_id} ``` All fields are optional — send only the ones you want to change: ```json theme={null} { "full_name": "Jane Smith", "email": "jane.smith@example.com", "dob": "1990-04-12", "occupation": "Senior Manager", "status": "active", "metadata": { "department": "Finance", "cost_center": "CC-007" } } ``` **Updatable fields** | Field | Values / format | | - | - | | `full_name` | string, max 191 | | `email` | valid email, max 191 | | `dob` | `YYYY-MM-DD` | | `occupation` | string, max 191 | | `status` | `active`, `suspended`, or `terminated` | | `metadata` | JSON object — replaces the existing value entirely | | `selfie_image` | `multipart/form-data` file or base64 string (jpeg/jpg/png/webp, max 10 MB) | | `selfie_image_url` | Pre-hosted URL string — ignored if `selfie_image` file is also sent | A failed selfie upload returns `502` and leaves the employee unchanged. ### List employees ``` GET /api/v1/corporate-card/employees ``` Returns every employee across all of your customers, newest first. Each employee includes its `customer` (`customer_id`, `customer_name`, `customer_email`) and `cards_count`. Optional query filters: | Parameter | Description | | - | - | | `customer_id` | Only this customer's employees | | `status` | `active`, `suspended` or `terminated` | | `kyc_status` | `not_started`, `submitted`, `approved` or `rejected` | | `search` | Matches full name or email | | `has_cards` | `1` for employees with at least one card, `0` for none | | `with_balance` | `1` to add each employee's live `card_balance` (see [Employee card balance](#employee-card-balance)). This makes the request slower, so use it only on pages that show balances. | ### Get an employee ``` GET /api/v1/corporate-card/employees/{employee_id} ``` Returns the employee record including its `metadata` and current `kyc` sub-object. ### Terminate an employee ``` DELETE /api/v1/corporate-card/employees/{employee_id} ``` Sets `status` to `terminated`, suspends all cards held by that employee, and soft-deletes the record. This action is not reversible via the API. ## Employee KYC ### Submit or update KYC ``` POST /api/v1/corporate-card/employees/kyc ``` `employee_id` is a required field in the request body (multipart or JSON), alongside the KYC data. Accepts either `multipart/form-data` with file fields, or JSON with hosted URLs — both are supported for each document: | Field | File field | URL field | Required | | - | - | - | - | | Government ID | `gov_id_image` | `gov_id_image_url` | No | | Payslip / work contract | `payslip` | `payslip_url` | No | | Proof of address | `proof_of_address` | `proof_of_address_url` | No | All three document fields are optional — supply at least the file or the URL for any document you want to attach; omit both to skip it. A file field also accepts a base64 string (`data:;base64,...` or raw base64) instead of a multipart file. Accepted types: images (jpg, png, webp, gif, heic), PDF, Word, Excel, CSV and plain text; max 10 MB. The type is detected from the file's content, not its name. If a file upload fails, the request returns `422` naming the field (e.g. `Unable to upload gov_id_image. Please try again.`). ### Private document links Uploaded selfies and KYC documents are stored privately. The URL saved on the employee is a Yativo link (`https:///files/private/...`) that only opens for your account (bearer token) or Yativo staff. To display one in a browser (``, new tab), exchange it for a 15-minute signed link: ``` POST /api/v1/files/sign { "url": "https:///files/private/..." } ``` The response is `{ "url": "", "expires_in": 900 }`. Only your own files can be signed; anything else returns `404`. Required identity/address fields: `employee_id`, `full_name`, `id_type`, `id_number`, `dob`, `street`, `city`, `postal_code`, `gov_id_type`, `gov_id_number`. Optional identity/address fields: `state_id`, `country_id`, `nationality`, `occupation`. * `country_id` — the country's ISO2 code (e.g. `US`), taken from the `iso2` field of the countries list below. Despite its name, this is **not** the numeric country `id`. * `nationality` — also an ISO2 code (e.g. `NG`). * `state_id` — the numeric `id` of a state from the states list below. An unknown `state_id` is rejected with `422 Invalid state_id.` **KYC fee.** The first KYC submission for each employee charges the `employee_kyc` fee to your **USDC balance** (Business Spend Card wallet only — this wallet is not used for payouts, swaps, or other products). Resubmissions and updates for the same employee are free. If the fee can't be charged the request returns `402`, the KYC is not saved, and the error explains that you need sufficient USDC to pay the employee KYC fee (for example: `Insufficient USDC balance to pay the employee KYC fee (0.50 USD). Fund your Business Spend Card wallet and try again.`). ### Looking up countries and states Use these endpoints to populate country and state pickers and to resolve the values sent in the KYC request. They are public, need no authentication, and return cached reference data. ``` GET /api/v1/locations/countries GET /api/v1/locations/states/{country_id} ``` `{country_id}` here is the numeric `id` from the countries list (e.g. `101`), not the ISO2 code. `GET /api/v1/locations/states` without a country returns every state and is not recommended, as the response is large. Example — list countries: ```json theme={null} { "status": "success", "status_code": 200, "message": "Request successful", "data": [ { "id": 1, "name": "afghanistan", "iso2": "AF", "iso3": "AFG", "calling_code": "+93", "currency_code": "AFN", "postal_code_format": "\\A\\d{4}\\Z", "status": "active" } ] } ``` Example — list states for a country: ```json theme={null} { "status": "success", "status_code": 200, "message": "Request successful", "data": [ { "id": 1, "country_id": 101, "name": "andaman and nicobar islands", "status": "active", "country": { "id": 101, "name": "india", "iso2": "IN", "iso3": "IND" } } ] } ``` Typical flow: fetch countries, and from the one the employee picks send its `iso2` as `country_id` in the KYC request. Then fetch `/states/{id}` with that country's numeric `id`, and send the chosen state's `id` as `state_id`. ### Get KYC status ``` GET /api/v1/corporate-card/employees/{employee_id}/kyc ``` Returns `status` (`pending`, `approved`, `rejected`) and, when rejected, a `reject_reason`. KYC approval/rejection itself is performed internally after review — it is not a customer-facing action. ## Memos / Invoices Employees (or the business, on an employee's behalf) can attach a memo and/or invoice to card activity, which the business then approves or rejects. ``` POST /api/v1/corporate-card/employees/memos GET /api/v1/corporate-card/employees/{employee_id}/memos POST /api/v1/corporate-card/employees/memos/{memo_id}/approve POST /api/v1/corporate-card/employees/memos/{memo_id}/reject ``` `POST .../memos` requires `employee_id` in the body, plus `note` (text), and either an `invoice` file upload or an `invoice_url`, plus an optional `card_id` to tie the memo to a specific card. Rejecting a memo requires a `reject_reason`. A failed invoice upload returns `502` (`Unable to upload the invoice. Please try again.`) and no memo is created. ## Employee card balance Each employee has one card balance that all of their cards spend from. You manage it; employees can view theirs in the employee portal but can't move it. ### Get an employee's card balance ``` GET /api/v1/corporate-card/employees/{employee_id}/balance ``` ```json theme={null} { "employee_id": "emp_456", "currency": "USD", "has_cardholder": true, "available_balance": 420.50, "ledger_balance": 450.00, "balance_unavailable": false, "accounts": [ { "account_id": "8f0c...", "primary": true, "available_balance": 420.50, "ledger_balance": 450.00, "card_count": 2 } ] } ``` * `available_balance` is what the employee can spend right now. `ledger_balance` also includes authorizations that haven't settled yet. * `has_cardholder` is `false` until the employee's first card is issued. Until then the balance is zero and can't be funded. * `balance_unavailable` is `true` if the balance couldn't be read in full right now. Retry later. * `accounts` usually has a single entry. Employees whose cards were issued before employee card balances existed can have more than one; the totals above cover all of them. ### Fund or withdraw ``` POST /api/v1/corporate-card/employees/balance ``` ```json theme={null} { "employee_id": "emp_456", "action": "fund", "amount": 500.00 } ``` | Field | Description | | - | - | | `employee_id` | Required. Must belong to one of your customers. | | `action` | Required. `fund` or `withdraw`. | | `amount` | Required. At least `0.01`. | | `account_id` | Optional. One of the employee's `accounts[].account_id`. Defaults to the primary account. | * **Fund** debits your USDC balance and credits the employee's card balance. It can't use the [reserve](#reserve). * **Withdraw** moves money from the employee's card balance back to your USDC balance and charges the `card_withdrawal` fee. It is refused with `422` if it exceeds the employee's available balance. Withdrawing everything doesn't close any cards. * An employee with no card yet returns `404`. * Send an `Idempotency-Key` header to make retries safe. The response is the employee's updated card balance, in the same shape as `GET .../balance`. ## Cards ``` POST /api/v1/corporate-card/employees/cards GET /api/v1/corporate-card/employees/cards?customer_id=cus_123 ``` `POST .../cards` requires `customer_id` in the body. `employee_id` is optional: pass it to issue the card to a specific employee (it must already belong to that `customer_id`); omit it and the API resolves — or, the first time, creates — that customer's employee automatically. Either way, an employee can hold any number of cards, with no per-employee limit. **Issuance fees** are charged to your USDC balance before the card is requested, and refunded automatically if the card can't be issued: | Card | Fees charged | | - | - | | An employee's **first** virtual card | None — free | | Any further virtual card for that employee | `virtual_card_create` | | Physical card | `physical_card_create` + `physical_card_shipping` | | First card for a **business**-type customer | `customer_kyb` as well, once per customer | Terminated or deleted virtual cards still count towards "first", so terminating and reissuing a card is not free. If a fee can't be charged the request returns `402` and no card is issued. Cards an employee creates for themselves in the employee portal follow the same rules and are charged to your balance. `GET .../cards` returns every card you own: cards issued by your account, and any card belonging to one of your customers or to an employee of one of your customers. It accepts optional `customer_id` and `employee_id` query filters, plus `status`. ### Managing an employee's cards You can see and manage every card that belongs to your customers and their employees (you → customer → employee → card), including cards an employee created for themselves in the employee portal. Cards are referenced by `card_id` (the opaque id returned in card responses). ``` GET /api/v1/corporate-card/employees/cards/{card_id} POST /api/v1/corporate-card/employees/cards/status POST /api/v1/corporate-card/employees/cards/pin PUT /api/v1/corporate-card/employees/cards/limits ``` * `.../{card_id}` returns a single card. * To view full card details, call `GET /api/v1/spend/cards/{card_id}/widget-token`. It returns `{"iframe": ""}`, a short-lived link to a secure page showing the full card number, expiry and CVV. Embed it as an `