Corporate Cards in Sandbox

Corporate cards let your business issue spend cards to its employees. Each employee is the cardholder: they have one balance, and every card they hold is denominated in it and spends from it. You fund the employee’s balance from your USDC balance and can withdraw it back at any time. Corporate cards are available by invitation only. Yativo enables them for invited businesses, in sandbox and in production. There’s no way to request access through the API or the dashboard. Without an invitation, every corporate card request returns 403. If you’ve been invited, use the sandbox to build and test your integration, then switch the base URL and API key when your production account is enabled.

Sandbox behaves like production for corporate cards. Account approval, customer requirements, fees and the USDC reserve all apply. Fees are charged to your sandbox USDC balance, which holds test funds only.

Before you start

Requirement	How to meet it in sandbox
Sandbox API key	Create one in the sandbox dashboard under Developers → API Keys. See Sandbox Environment
Verified sandbox account	`kyc_status` is `approved` and `is_kyc_submitted` is true. See Sandbox KYC
An invitation	Yativo enables corporate cards on invited accounts only. Until yours is enabled, every corporate card request returns `403`
A business customer	Create it with `customer_type: "business"` and submit its KYB. Corporate cards are issued to business customers
`cobo_pobo` endorsement	The customer needs an approved `cobo_pobo` endorsement. Requests for a customer without it return `403`
USDC balance	Enough to cover card funding, fees and the reserve

All requests go to the sandbox base URL with your sandbox key:

BASE=https://smtp.yativo.com/api/v1

curl "$BASE/corporate-card/employees" \
  -H "X-Api-Key: $YATIVO_API_KEY" \
  -H "X-Api-Secret: $YATIVO_API_SECRET"

Every request below has a reference page with a “Try it” playground under Corporate Cards and Corporate Card Transactions. customer_id and employee_id are never part of a POST path. Send them in the request body, or in the query string on GET. Every customer_id must be one of your customers and every employee_id must belong to that customer, or the request returns 404.

Test in the dashboard

The sandbox dashboard has the same Corporate Card screens as production. Open Issuing → Corporate Card, pick a customer, then add employees, issue cards, fund balances and review memos. Use it to see the flow before you call the API.

Test flow

Check your USDC balance

GET /corporate-card/wallet?customer_id=... returns the customer’s funding address and your USDC balance:

curl "$BASE/corporate-card/wallet?customer_id=cus_123" \
  -H "X-Api-Key: $YATIVO_API_KEY" -H "X-Api-Secret: $YATIVO_API_SECRET"

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "wallet": {
      "customer_id": "cus_123",
      "wallet_address": "7xKX...9fQe",
      "wallet_currency": "USDC_SOL",
      "wallet_status": "active"
    },
    "usdc_balance": 3500.00,
    "usdc_reserved_balance": 2000.00,
    "usdc_available_balance": 1500.00
  }
}

The three balances are in USD. Spend only from usdc_available_balance. The first request for a customer creates its funding address and returns wallet: null, so call it again to read the address. Address creation counts towards the wallet address limits.

Never send real USDC to a sandbox funding address. If your sandbox USDC balance is empty, swap from your USD balance or contact Yativo support.

Create an employee

curl -X POST "$BASE/corporate-card/employees" \
  -H "X-Api-Key: $YATIVO_API_KEY" -H "X-Api-Secret: $YATIVO_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "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" }
  }'

Only customer_id and full_name are required. To attach a selfie, send selfie_image as a multipart/form-data file (jpeg, jpg, png or webp, up to 10 MB) or selfie_image_url as a hosted URL. The response includes the new employee_id.

Submit employee KYC

curl -X POST "$BASE/corporate-card/employees/kyc" \
  -H "X-Api-Key: $YATIVO_API_KEY" -H "X-Api-Secret: $YATIVO_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "emp_456",
    "full_name": "Jane Doe",
    "id_type": "passport",
    "id_number": "X1234567",
    "dob": "1990-04-12",
    "street": "100 Main St",
    "city": "Miami",
    "postal_code": "33101",
    "country_id": "US",
    "nationality": "US",
    "gov_id_type": "passport",
    "gov_id_number": "X1234567",
    "gov_id_image_url": "https://example.com/id.jpg"
  }'

country_id and nationality are ISO2 codes. state_id is optional and is the numeric id from GET /locations/states/{country_id}, where {country_id} is the numeric id from GET /locations/countries. Documents (gov_id_image, payslip, proof_of_address) are optional and accept a file or a *_url field.You can submit an employee’s KYC but not read it back. Follow kyc_status on GET /corporate-card/employees/{employee_id} instead. In sandbox, a submission is approved straight away and kyc_status becomes approved. The first submission for each employee charges the employee_kyc fee. Resubmissions are free.

Issue a card

curl -X POST "$BASE/corporate-card/employees/cards" \
  -H "X-Api-Key: $YATIVO_API_KEY" -H "X-Api-Secret: $YATIVO_API_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "customer_id": "cus_123", "employee_id": "emp_456", "card_type": "Virtual" }'

card_type is Virtual (default) or Physical. Omit employee_id and the card goes to the customer’s employee, created automatically the first time. The employee is the cardholder: every card they hold is denominated in, and spends from, the employee’s balance. An employee can hold any number of cards. The response contains the card under data.card, including its card_id, status, masked_pan and expiration_date.An employee’s first virtual card is free. Further virtual cards and physical cards are charged as listed in Fees. If a fee can’t be charged the request returns 402 and no card is issued.

Fund the employee

curl -X POST "$BASE/corporate-card/employees/balance" \
  -H "X-Api-Key: $YATIVO_API_KEY" -H "X-Api-Secret: $YATIVO_API_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "employee_id": "emp_456", "action": "fund", "amount": 500.00 }'

action is fund or withdraw, and amount is in USD (minimum 0.01). Funding debits your USDC balance and can’t use the reserve. Withdrawing returns money to your USDC balance, charges the card_withdrawal fee, and fails with 422 if it exceeds the employee’s available balance. An employee with no card yet returns 404.Check the employee’s balance with GET /corporate-card/employees/{employee_id}/balance:

{
  "employee_id": "emp_456",
  "currency": "USD",
  "has_cardholder": true,
  "available_balance": 500.00,
  "ledger_balance": 500.00,
  "balance_unavailable": false,
  "accounts": [
    { "account_id": "8f0c...", "primary": true, "available_balance": 500.00, "ledger_balance": 500.00, "card_count": 1 }
  ]
}

Manage the card

Request	Body
`GET /corporate-card/employees/cards?customer_id=...`	Optional `employee_id` and `status` filters
`GET /corporate-card/employees/cards/{card_id}`	—
`POST /corporate-card/employees/cards/status`	`customer_id`, `card_id`, `action`: `activate`, `suspend` or `terminate`
`PUT /corporate-card/employees/cards/limits`	`customer_id`, `card_id`, `limits` array
`GET /corporate-card/employees/cards/{card_id}/link`	—

Only the employee sees the full card number, expiry, CVV and PIN, on the card’s card link. Share the link or embed it in your app. The employee confirms their email the first time, sets up a passkey or authenticator app, and sets their PIN there.

Test memos

Employees attach notes and invoices to card activity, and you approve or reject them:

POST /corporate-card/employees/memos                    employee_id, note, invoice or invoice_url, optional card_id
GET  /corporate-card/employees/{employee_id}/memos
POST /corporate-card/employees/memos/{memo_id}/approve
POST /corporate-card/employees/memos/{memo_id}/reject   reject_reason

Test suspension and termination

PUT /corporate-card/employees/{employee_id} with "status": "suspended" blocks every corporate card request for that employee with 403. Set it back to active to restore access.DELETE /corporate-card/employees/{employee_id} terminates the employee and suspends all of their cards. It can’t be undone, so create a fresh employee for each test run.

Card transactions

Card authorizations are recorded in your spend card transaction history, and Yativo sends business_spend_card.transaction.* webhooks for them. The transaction_id in those webhooks is the id used below.

GET    /business/spend-card/transactions                 optional status, card_id
GET    /business/spend-card/transactions/{id}
POST   /business/spend-card/transactions/{id}/dispute    reason (max 500 characters)
POST   /business/spend-card/transactions/{id}/notes      note
POST   /business/spend-card/transactions/{id}/invoices   multipart invoice (jpg, jpeg, png or pdf, max 10 MB)

Raising a dispute charges the dispute fee. A second dispute on the same transaction returns 409.

Sandbox has no endpoint to simulate a card authorization. Test the transaction and dispute flows with transactions that appear on your sandbox cards, and test your webhook handling with the payloads in Webhooks.

Reserve

While Business Spend Cards are enabled, a minimum amount must stay in your USDC balance. The default is 2,000 USD. Card funding stops at the reserve. Fees can still use it. A debit that would go below it returns an error that states the reserve and how much is available to spend.

USDC balance

Your USDC balance is only for corporate cards. Card funding and corporate card fees are the only debits from it. Payouts, transfers between Yativo accounts and swaps out of USDC fail with Invalid wallet selected. You can add to it in two ways:

Deposit USDC to the funding address from GET /corporate-card/wallet
Swap from your USD wallet with POST /wallet/swap. USD is the only currency you can swap into USDC

Fees

Every corporate card fee is charged to your USDC balance, in sandbox as in production. Amounts come from your pricing agreement. GET /fees returns them under employee_card. See Fees.

Fee	Charged
`monthly_subscription`	Once per calendar month while enabled
`customer_kyb`	Once per business customer, when its first card is issued
`employee_kyc`	Once per employee, on the first KYC submission
`virtual_card_create`	Each virtual card after an employee’s first. Terminated cards still count
`physical_card_create`, `physical_card_shipping`	Each physical card
`authorization_domestic`, `authorization_cross_border`	Each approved authorization
`cross_border_transaction`	A percentage of each approved cross-border authorization
`reversal`	Each reversed authorization
`dispute`	Each dispute you raise
`card_withdrawal`	Each withdrawal from an employee’s balance

Errors

Errors use the standard envelope:

{
  "status": "failed",
  "status_code": 403,
  "message": "Your account is not yet approved for Business Spend Cards. Please contact support.",
  "data": { "error": "Your account is not yet approved for Business Spend Cards. Please contact support." }
}

Status	Common sandbox cause
`402`	Your USDC balance can’t cover a fee, or a debit would go below the reserve
`403`	Your account hasn’t been invited to corporate cards, the customer has no approved `cobo_pobo` endorsement, the customer hasn’t submitted full KYC, the customer isn’t a business, the employee is suspended or terminated, or you requested a funding address more than 3 times in a minute
`404`	A `customer_id`, `employee_id` or `card_id` isn’t yours, or the employee has no card yet when funding
`409`	The transaction has already been disputed
`422`	Validation error, an unknown `state_id`, a rejected upload, or a withdrawal larger than the available balance
`502`	A file upload failed, or the card service couldn’t complete the request. Retry the request

When the card service rejects a request, data.error explains why, for example an invalid date of birth. When it can’t complete the request at all, you get 502 with The card service could not complete this request right now. Please try again later.

Going live

Change the base URL to https://api.yativo.com/api/v1 and use your production API key.
Wait for Yativo to enable corporate cards on your production account. This is part of your invitation.
Make sure each customer has an approved cobo_pobo endorsement in production.
Fund your production USDC balance above the reserve.
Point your webhook URL at your production endpoint.

Get Started

Payments

Wallets

Customers & Compliance

Transactions

Products

Developer Tools

SDKs

Regional Guides

Platform guides

Corporate Cards in Sandbox

Before you start

Test in the dashboard

Test flow

Card transactions

Reserve

USDC balance

Fees

Errors

Going live

​Before you start

​Test in the dashboard

​Test flow

​Card transactions

​Reserve

​USDC balance

​Fees

​Errors

​Going live

Before you start

Test in the dashboard

Test flow

Card transactions

Reserve

USDC balance

Fees

Errors

Going live