> ## 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.

# Card Issuer Program

> Issue Yativo Cards to your own customers under your platform — B2B card issuer documentation

## Overview

The Yativo Card Issuer Program lets businesses issue virtual and physical payment cards to their own customers under their platform. As an issuer you manage the full card lifecycle — from customer onboarding to card creation, balance funding, and transaction monitoring — through a single API.

**Typical use cases:**

* Fintech apps offering spending cards to users
* Corporate expense management platforms
* Digital banking services for underserved markets
* Wallets that want to add a card spending layer

<Note>
  Access to the Card Issuer Program is by invitation only. Contact your Yativo account manager or [support@yativo.com](mailto:support@yativo.com) to request access. The program section will not appear in your dashboard until your account manager enables it for your account.
</Note>

***

## How It Works

<Steps>
  <Step title="Your account manager grants eligibility">
    Yativo's team reviews your use case and enables the Card Issuer Program on your account. Nothing is visible in your dashboard until this step is complete.
  </Step>

  <Step title="You submit an application">
    Once eligible, the Card Issuer section appears in your dashboard. Choose your funding structure (`master_wallet` or `non_master`) and an optional IBAN add-on, then submit.
  </Step>

  <Step title="Yativo approves your program">
    Our compliance team reviews and approves the application, typically within 2–5 business days. On approval, your settlement wallets are auto-provisioned.
  </Step>

  <Step title="Fund your master wallet and issue cards">
    Deposit USDC to your SOL address to top up your USD balance, swap to EUR or GBP as needed, onboard customers, issue cards, and fund them by customer email, ID, or your own external reference.
  </Step>
</Steps>

***

## Funding Structures

Choose your funding structure at application time. It cannot be changed after approval.

| Structure       | Source Chain        | Best For                                                                                 |
| --------------- | ------------------- | ---------------------------------------------------------------------------------------- |
| `master_wallet` | Solana (SOL) or XDC | You hold the source funds and push them to customer cards on demand                      |
| `non_master`    | Per-customer        | Each customer deposits to their own collateral wallet — you do not hold a shared balance |

***

## Apply for the Program

Once your account manager has granted eligibility, submit your application.

```bash theme={null}
curl -X POST 'https://crypto-api.yativo.com/api/v1/card-issuer/apply' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "funding_structure": "master_wallet",
    "iban_enabled": false
  }'
```

| Field               | Required | Description                                                                                        |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------- |
| `funding_structure` | Yes      | `master_wallet` or `non_master`                                                                    |
| `iban_enabled`      | No       | Set to `true` to enable EUR IBAN issuance. Requires additional regulatory review. Default: `false` |

```json Response theme={null}
{
  "success": true,
  "message": "Application submitted. An admin will review your request.",
  "data": {
    "id": "6634abc...",
    "status": "pending",
    "funding_structure": "master_wallet",
    "iban_enabled": false
  }
}
```

***

## Check Program Status

```bash theme={null}
curl 'https://crypto-api.yativo.com/api/v1/card-issuer/status' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

```json Response (approved, master_wallet) theme={null}
{
  "success": true,
  "data": {
    "enrolled": true,
    "status": "approved",
    "funding_structure": "master_wallet",
    "enabled_chains": ["SOL"],
    "iban_enabled": false,
    "card_reissue_enabled": false,
    "master_wallets": {
      "sol": {
        "address": "9gHp7qLmKv3xFjNw4aBcYhUeT8sGkZoP2iMnDuWr5Cx",
        "balance": 0.012
      },
      "usdc": { "balance": 5420.00 },
      "eur": { "balance": 3100.00 },
      "gbp": { "balance": 800.00 }
    },
    "stats": {
      "total_cards_issued": 47,
      "total_funded_amount": 12840.00,
      "total_fees_paid": 12.40
    },
    "limits": {
      "max_cards": 1000,
      "daily_funding_limit": 50000,
      "monthly_funding_limit": 500000
    }
  }
}
```

***

## Master Wallet & Balances

Master wallet issuers (`funding_structure: master_wallet`) have two types of wallets:

### Source wallets (SOL and/or XDC)

These are the wallets you deposit USDC into. SOL deposits are settled automatically to your master wallet balance. XDC deposits are settled manually on your own schedule (XDC deposits accrue yield while held).

| Chain | Token deposited | Settlement | Time      |
| ----- | --------------- | ---------- | --------- |
| SOL   | USDC\_SOL       | Automatic  | \~2–5 min |
| XDC   | USDC\_XDC       | Manual     | \~20 min  |

### Settlement wallets

These are auto-provisioned on approval. All three currency balances share the same underlying on-chain address.

| Balance | Funded by                  | Used for                     |
| ------- | -------------------------- | ---------------------------- |
| USD     | USDC deposited via SOL/XDC | Funding cards in USD regions |
| EUR     | Swap from USD              | Funding cards in EUR regions |
| GBP     | Swap from USD              | Funding cards in GBP regions |

<Note>
  All three balances are managed internally by Yativo. To move from USD balance to EUR balance, use the swap endpoint below.
</Note>

### Get master wallet balances

```bash theme={null}
curl 'https://crypto-api.yativo.com/api/v1/card-issuer/master-wallets' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "wallets": {
      "sol": {
        "address": "9gHp7qLmKv3xFjNw4aBcYhUeT8sGkZoP2iMnDuWr5Cx",
        "balance": 0.012
      },
      "xdc": null,
      "usdc": { "balance": 5420.00, "last_balance_check": "2026-04-22T09:00:00Z" },
      "eur": { "balance": 3100.00, "last_balance_check": "2026-04-22T09:00:00Z" },
      "gbp": { "balance": 800.00, "last_balance_check": "2026-04-22T09:00:00Z" }
    }
  }
}
```

`xdc` is `null` if XDC is not enabled for your program.

### Get funding deposit addresses

```bash theme={null}
curl 'https://crypto-api.yativo.com/api/v1/card-issuer/funding-addresses' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

Returns your SOL and XDC deposit addresses to send USDC to. For `non_master` programs, pass `?customer_id=...` to get the per-customer address.

***

## Swap Between Currency Balances

Swap USD ↔ EUR ↔ GBP within your master wallet balances.

```bash theme={null}
curl -X POST 'https://crypto-api.yativo.com/api/v1/card-issuer/master-wallets/swap' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "from_token": "USDC",
    "to_token": "EUR",
    "amount": 1000
  }'
```

| Field        | Required | Description                                             |
| ------------ | -------- | ------------------------------------------------------- |
| `from_token` | Yes      | `USDC`, `EUR`, or `GBP`                                 |
| `to_token`   | Yes      | `USDC`, `EUR`, or `GBP` (must differ from `from_token`) |
| `amount`     | Yes      | Amount to sell, in the `from_token` currency            |

```json Response theme={null}
{
  "success": true,
  "message": "Swap initiated: 1000 USD → EUR",
  "data": {
    "swap_id": "0x7abc...",
    "status": "submitted",
    "from_token": "USD",
    "to_token": "EUR",
    "amount": 1000,
    "expected_output": "923.45",
    "fee_amount": "1.20",
    "estimated_time": "1-3 minutes"
  }
}
```

***

## Fund a Customer's Card

Transfer from your master wallet to a customer's card wallet. The destination currency is automatically detected from the customer's card region (e.g. UK customers receive GBP, EU customers receive EUR).

```bash theme={null}
curl -X POST 'https://crypto-api.yativo.com/api/v1/card-issuer/fund-customer' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "cust_abc123",
    "amount": 100,
    "source_chain": "SOL",
    "pricing_mode": "receive_x"
  }'
```

| Field               | Required | Description                                                                                                          |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `customer_id`       | One of   | Customer's Yativo customer ID                                                                                        |
| `card_id`           | One of   | Card's unique ID                                                                                                     |
| `external_id`       | One of   | Your own external reference                                                                                          |
| `email`             | One of   | Customer's email address                                                                                             |
| `amount`            | Yes      | Amount to send (interpretation depends on `pricing_mode`)                                                            |
| `source_chain`      | Yes      | `SOL` or `XDC` — which master wallet to send from                                                                    |
| `pricing_mode`      | No       | `send_x` (default) or `receive_x` — see below                                                                        |
| `destination_token` | No       | Override the auto-detected destination token. Must match the customer's card region currency or an error is returned |

### Pricing modes

| Mode        | You specify                                 | Customer receives                                                    |
| ----------- | ------------------------------------------- | -------------------------------------------------------------------- |
| `send_x`    | The amount you send from your master wallet | Less than `amount` (transfer fees deducted)                          |
| `receive_x` | The amount the customer should receive      | More than `amount` is sent from your master wallet (you absorb fees) |

<Note>
  The currency mismatch check is enforced at the API level. For example, if a customer's card is in a EUR region, you cannot fund them with a USD destination — the API returns `TOKEN_MISMATCH` and tells you the required currency. Swap your USD balance to EUR first, then fund.
</Note>

```json Response theme={null}
{
  "success": true,
  "data": {
    "transfer_id": "tx_1745123456_abc123",
    "status": "pending",
    "source": { "chain": "SOL", "amount": 102.50, "wallet": "9gHp7q..." },
    "destination": { "token": "EUR" },
    "pricing_mode": "receive_x",
    "estimated_output": "100.00",
    "estimated_time": "2-5 minutes"
  }
}
```

***

## Look Up a Customer

Find a customer by any of their identifiers. The underlying wallet address is never returned.

```bash theme={null}
curl 'https://crypto-api.yativo.com/api/v1/card-issuer/lookup-customer?email=customer@example.com' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

Query parameters (one required): `customer_id`, `card_id`, `external_id`, or `email`.

```json Response theme={null}
{
  "success": true,
  "data": {
    "customer_id": "cust_abc123",
    "external_id": "user_9821",
    "email": "customer@example.com",
    "currency": "GBP",
    "token": "GBP",
    "safe_deployed": true,
    "cards_count": 1,
    "created_at": "2026-03-15T10:00:00Z"
  }
}
```

***

## List & Manage Customers

```bash theme={null}
# List all customers
GET /card-issuer/customers?page=1&limit=20

# List customers filtered by KYC stage
GET /card-issuer/customers?status=kyc_approved
```

***

## Deposit History (XDC)

XDC deposits are tracked individually so you can choose when to settle each one.

```bash theme={null}
# List deposits
curl 'https://crypto-api.yativo.com/api/v1/card-issuer/deposits' \
  -H 'Authorization: Bearer YOUR_TOKEN'

# Manually trigger settlement for a specific XDC deposit
curl -X POST 'https://crypto-api.yativo.com/api/v1/card-issuer/deposits/{depositId}/fund' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "destination_token": "USDC" }'
```

Deposits in `awaiting_manual` status can be manually triggered. SOL deposits are settled automatically.

***

## Funding History

```bash theme={null}
curl 'https://crypto-api.yativo.com/api/v1/card-issuer/funding-history?page=1&limit=20' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

Returns all funding transfers initiated from your master wallet, with status, amounts, and chain details.

***

## Card Reissue

When card reissue is enabled for your program (admin-toggled), your customers can request a card reissue from the card management screen. This feature is off by default and is enabled per-program by Yativo's compliance team.

Check whether it's enabled:

```bash theme={null}
curl 'https://crypto-api.yativo.com/api/v1/card-issuer/status' \
  -H 'Authorization: Bearer YOUR_TOKEN'
# → data.card_reissue_enabled: true/false
```

***

## Rate Limits & Program Limits

| Resource              | Default   | Adjustable                           |
| --------------------- | --------- | ------------------------------------ |
| Max customer accounts | 1,000     | Yes — contact your account manager   |
| Daily funding cap     | \$50,000  | Yes — admin-configurable per program |
| Monthly funding cap   | \$500,000 | Yes — admin-configurable per program |

Your current limits are always visible in `GET /card-issuer/status` under `limits`.

***

## PIN Management

Every card — virtual and physical — starts with `pin_set: false`. The customer must set a PIN before chip-and-PIN or ATM transactions will work. Online card-not-present transactions do not require a PIN.

If a card is active but has no PIN set, the `next_action` field in `GET /v1/card-issuer/customers/{customerId}` will read:

> `"Card is active — customer must set card PIN before in-store (PSE) payments will work"`

<CardGroup cols={2}>
  <Card title="Setting a Card PIN" icon="lock" href="/yativo-crypto/cards/set-pin">
    Full guide — PSE-hosted flow, iframe embed, brand theming, `pin_set` monitoring, and webhook confirmation.
  </Card>

  <Card title="API Reference — Secure View" icon="key" href="/api-reference/cards/customer-secure-view">
    Full parameter reference for the view-token endpoint.
  </Card>
</CardGroup>

***

## Webhooks

Subscribe to issuer events via `POST /v1/webhook/create-webhook`. See [Webhook Events](/api-reference/issuer/webhooks) for the full event reference, payload examples, and signature verification.

Key events to subscribe to:

| Event                     | Description                           |
| ------------------------- | ------------------------------------- |
| `customer.funded`         | A customer's card wallet was credited |
| `customer.funding.failed` | A funding transfer failed             |
| `master_wallet.deposit`   | Funds arrived in your master wallet   |
| `card.created`            | A card was issued to a customer       |
| `transaction.authorized`  | A card transaction was authorized     |
| `transaction.declined`    | A card transaction was declined       |

***

## Related

* [Card overview](/yativo-crypto/cards/overview)
* [Customer onboarding](/yativo-crypto/cards/onboarding)
* [Webhook Events](/api-reference/issuer/webhooks)
* [Supported chains](/yativo-crypto/supported-chains)