Skip to main content

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.

​
Overview

Physical Yativo Cards are plastic payment cards delivered to a shipping address. They work anywhere the payment network is accepted — in-store, at ATMs, and for contactless payments. Physical card orders go through a fulfillment process before the card is shipped.
Physical card issuance requires a fully onboarded account with KYC approved, terms accepted, and wallet deployed. See the Onboarding Guide.
interface PhysicalCardOrder {
  order_id: string;
  status: "pending" | "processing" | "shipped" | "delivered" | "cancelled";
  shipping_address: ShippingAddress;
  tracking_number?: string;
  estimated_delivery?: string;
  created_at: string;
}

interface ShippingAddress {
  line1: string;
  line2?: string;
  city: string;
  state?: string;
  postal_code: string;
  country: string; // ISO 3166-1 alpha-2
}

interface CreatePhysicalOrderRequest {
  shipping_address: ShippingAddress;
  personalization?: {
    name_on_card?: string;
  };
}

​
Order a Physical Card

Submit an order for a physical card. A shipping address is required. 
POST /yativo-card/{yativoCardId}/cards/physical/order
​
yativoCardId
string
required
Your Yativo Card account ID.
​
shipping_address
object
required
The delivery address for the physical card.
​
shipping_address.line1
string
required
Street address line 1.
​
shipping_address.line2
string
Street address line 2 (apartment, suite, unit, etc.).
​
shipping_address.city
string
required
City name.
​
shipping_address.state
string
State or province code. Required for applicable countries.
​
shipping_address.postal_code
string
required
Postal or ZIP code.
​
shipping_address.country
string
required
ISO 3166-1 alpha-2 country code (e.g., "DE", "GB", "US").
​
display_name
string
A label for this card (e.g., “Personal Card”). Defaults to the account holder name.
curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/cards/physical/order' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "display_name": "Jane'\''s Personal Card",
    "shipping_address": {
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "Berlin",
      "postal_code": "10115",
      "country": "DE"
    }
  }'

{
  "status": "success",
  "data": {
    "order_id": "ord_01HX9KZMB3F7VNQP8R2WDGT4F6",
    "status": "pending_payment",
    "display_name": "Jane's Personal Card",
    "shipping_address": {
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "Berlin",
      "postal_code": "10115",
      "country": "DE"
    },
    "created_at": "2026-03-25T12:00:00Z"
  }
}

​
Attach Payment to Order

After creating an order, submit payment to initiate card fulfillment. 
POST /yativo-card/{yativoCardId}/cards/physical/order/{orderId}/payment
​
yativoCardId
string
required
Your Yativo Card account ID.
​
orderId
string
required
The order ID returned when the order was created.
​
payment_method
string
required
Payment method. Accepted values: "card_balance", "crypto".
curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/cards/physical/order/ord_01HX9KZMB3F7VNQP8R2WDGT4F6/payment' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "payment_method": "card_balance"
  }'

{
  "status": "success",
  "data": {
    "order_id": "ord_01HX9KZMB3F7VNQP8R2WDGT4F6",
    "payment_status": "paid",
    "order_status": "processing",
    "amount_charged": 9.99,
    "currency": "USD"
  }
}

​
Get Order Status

Check the current status of a physical card order. 
GET /yativo-card/{yativoCardId}/cards/physical/order/{orderId}/status
​
yativoCardId
string
required
Your Yativo Card account ID.
​
orderId
string
required
The order ID to check.
curl -X GET 'https://crypto-api.yativo.com/api/v1/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/cards/physical/order/ord_01HX9KZMB3F7VNQP8R2WDGT4F6/status' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "status": "success",
  "data": {
    "order_id": "ord_01HX9KZMB3F7VNQP8R2WDGT4F6",
    "order_status": "shipped",
    "tracking_number": "1Z999AA10123456784",
    "carrier": "DHL",
    "estimated_delivery": "2026-04-02",
    "shipped_at": "2026-03-27T08:00:00Z"
  }
}

​
Order Status Values

StatusDescription
pending_paymentOrder created, awaiting payment.
processingPayment received. Card is being manufactured and personalized.
shippedCard has been dispatched. Tracking number available.
deliveredCard confirmed delivered to the shipping address.
cancelledOrder was cancelled before shipment.
failedOrder could not be fulfilled. Contact support.

​
List All Orders

Retrieve all physical card orders for a Yativo Card account. 
GET /yativo-card/{yativoCardId}/cards/physical/orders
​
yativoCardId
string
required
Your Yativo Card account ID.
curl -X GET 'https://crypto-api.yativo.com/api/v1/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/cards/physical/orders' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "status": "success",
  "data": [
    {
      "order_id": "ord_01HX9KZMB3F7VNQP8R2WDGT4F6",
      "order_status": "shipped",
      "display_name": "Jane's Personal Card",
      "created_at": "2026-03-25T12:00:00Z",
      "shipped_at": "2026-03-27T08:00:00Z"
    }
  ],
  "total": 1
}

​
Cancel an Order

Cancel a physical card order. Cancellation is only possible while the order is in pending_payment or processing status. Once shipped, orders cannot be cancelled. 
POST /yativo-card/{yativoCardId}/cards/physical/order/{orderId}/cancel
​
yativoCardId
string
required
Your Yativo Card account ID.
​
orderId
string
required
The order ID to cancel.
curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/cards/physical/order/ord_01HX9KZMB3F7VNQP8R2WDGT4F6/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

{
  "status": "success",
  "data": {
    "order_id": "ord_01HX9KZMB3F7VNQP8R2WDGT4F6",
    "order_status": "cancelled",
    "cancelled_at": "2026-03-25T13:00:00Z",
    "refund_status": "pending"
  }
}

​
Set Physical Card PIN

The pin_set field in the view-token response tells you whether Yativo has received a physical.card.pin.changed webhook for this card. Use it to prompt the cardholder to set a PIN before their first chip-and-PIN or ATM transaction. The same view also handles PIN changes.
Physical card PINs are set and changed through Yativo’s hosted secure page, powered by Gnosis Pay’s Partner Secure Elements (PSE). The cardholder types their PIN directly inside a sandboxed iframe — your backend never receives or processes the PIN value. Flow:
  1. Your backend calls POST /v1/yativo-card/{yativoCardId}/cards/{cardId}/view-token with enabled_views: ["pin"]
  2. You receive a secure_view_url
  3. Open it in an <iframe> or WebView — the cardholder enters and confirms their 4-digit PIN
  4. Gnosis Pay fires a physical.card.pin.changed webhook → pin_set becomes true on the card record
  5. Card details can now be displayed
curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/cards/card_phys_01HX9KZMB3F7VNQP8R2WDGT4F6/view-token' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "enabled_views": ["pin"] }'
Response
{
  "success": true,
  "data": {
    "secure_view_url": "https://crypto-api.yativo.com/api/v1/yativo-card/view/eyJhbGci...",
    "pin_set": false,
    "enabled_views": ["pin"],
    "expires_at": "2026-05-18T12:05:00.000Z"
  }
}
Embed the URL in your frontend: 
<iframe
  src="https://crypto-api.yativo.com/api/v1/yativo-card/view/eyJhbGci..."
  title="Set Card PIN"
  width="420" height="520"
  style="border:0; border-radius:16px;"
  allow="clipboard-read; clipboard-write">
</iframe>
The PIN updates the online PIN stored by the card network. The chip’s offline PIN syncs automatically on the first ATM transaction.

Setting a Card PIN

Complete flow for virtual and physical cards — PSE iframe, brand theming, pin_set monitoring, and webhook confirmation.

​
Delivery Timeframes

Delivery times are estimates and may vary based on destination country and carrier conditions.
RegionEstimated Delivery
Europe (EU)5–10 business days
United Kingdom5–10 business days
North America7–14 business days
Rest of World10–21 business days
After your card is shipped, you will receive a tracking number via the order status endpoint and via email notification.

​
Physical Card Activation

Before a physical card can be activated, a 12.00 USDC one-time activation fee must be paid. Send 12 USDC (SPL) on Solana to your card wallet address. The fee is detected automatically — once confirmed, you can call the activation endpoint with your activation code.
Activation fees are subject to review and may change. The current fee will always be returned in the 402 response if payment is still outstanding.
If the fee has not been paid, the activation endpoint returns HTTP 402 with the payment address: 
{
  "success": false,
  "error_code": "ACTIVATION_FEE_REQUIRED",
  "message": "A 12.00 USDC activation fee is required...",
  "data": {
    "fee_amount": "12.00",
    "fee_currency": "USDC",
    "payment_address": "SoLFundingWalletAddressXXX",
    "network": "solana",
    "fees_subject_to_review": true
  }
}
Once the payment is detected your activation call will succeed normally.
Set your PIN as soon as your card arrives. Chip-and-PIN and ATM transactions will fail until a PIN is set. Use the PIN setup flow to let the cardholder set theirs immediately after activation, and use the same flow to change it later.