# Cardyfie API Integration Setup

## Overview

This is a simplified implementation of the Cardyfie customer creation API. It provides easy-to-use endpoints for creating and retrieving customers.

## Configuration

Add these variables to your `.env` file (or environment configuration):

```env
# Cardyfie API Configuration
cardyfie.api_base_url = https://core.cardyfie.com/api
cardyfie.environment = sandbox
cardyfie.api_key = YOUR_API_KEY_HERE
cardyfie.verify_ssl = true

# Cardyfie Webhook Configuration (Optional)
cardyfie.webhook_secret = YOUR_WEBHOOK_SECRET_KEY
cardyfie.webhook_urls = https://your-app.com/webhook,https://another-app.com/webhook
```

### Configuration Options

- **`cardyfie.api_base_url`** - Base URL for Cardyfie API (default: `https://core.cardyfie.com/api`)
- **`cardyfie.environment`** - Environment: `sandbox` or `production` (default: `sandbox`)
- **`cardyfie.api_key`** - Your Cardyfie API Bearer token (required)
- **`cardyfie.verify_ssl`** - Verify SSL certificates (default: `true`)
- **`cardyfie.webhook_secret`** - Webhook secret key from Cardyfie dashboard (optional, for signature verification)
- **`cardyfie.webhook_urls`** - Comma-separated list of URLs to forward webhooks to (optional)

## API Endpoints

### Base URL
```
https://debit.gmpayapp.site/public/api/cardyfie
```

### 1. Create Customer
**Endpoint:** `POST /api/cardyfie/customer/create`

**Full URL:** `https://debit.gmpayapp.site/public/api/cardyfie/customer/create`

**Request Body:**
```json
{
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "date_of_birth": "1990-12-10",
    "id_type": "passport",
    "id_number": "GBR123456789",
    "id_front_image": "https://example.com/id_front.jpg",
    "user_image": "https://example.com/user.jpg",
    "house_number": "221B",
    "address_line_1": "Baker Street",
    "city": "London",
    "zip_code": "NW1 6XE",
    "country": "UK"
}
```

**Required Fields:**
- `first_name` - Customer's first name
- `last_name` - Customer's last name
- `email` - Valid email address
- `date_of_birth` - Date in format `YYYY-MM-DD` or `DD/MM/YYYY`
- `id_type` - One of: `passport`, `nid`, `bvn`
- `id_number` - ID document number
- `id_front_image` - URL to front of ID image
- `user_image` - URL to customer photo
- `house_number` - House/building number
- `address_line_1` - Street address
- `city` - City name
- `zip_code` - Postal/ZIP code
- `country` - Country code (e.g., "UK", "UG")

**Optional Fields:**
- `id_back_image` - URL to back of ID image
- `state` - State/Province name
- `reference_id` - Your custom reference (auto-generated if not provided)
- `user_id` - Your internal user ID (stored in meta)

**Success Response:**
```json
{
    "success": true,
    "message": "Customer created successfully!",
    "customer": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "ulid": "01K44CWWXSAAHPSCQK8TP4W7D0",
        "status": "PENDING",
        "reference_id": "CF_1234567890_abcd1234",
        "created_at": "2025-09-02T05:02:51.000000Z"
    },
    "ulid": "01K44CWWXSAAHPSCQK8TP4W7D0",
    "reference_id": "CF_1234567890_abcd1234"
}
```

**Error Response:**
```json
{
    "success": false,
    "message": "Missing required field: email",
    "error_code": 400
}
```

### 2. Get Customer
**Endpoint:** `GET /api/cardyfie/customer/get/{ulid}`

**Full URL:** `https://debit.gmpayapp.site/public/api/cardyfie/customer/get/{ulid}`

**Path Parameter:**
- `ulid` - Customer ULID from Cardyfie (required)

**Alternative (Query Parameter):**
- `GET /api/cardyfie/customer/get?ulid={ulid}` (also supported for flexibility)

**Example:**
```
GET /api/cardyfie/customer/get/01K44CWWXSAAHPSCQK8TP4W7D0
GET /api/cardyfie/customer/get?ulid=01K44CWWXSAAHPSCQK8TP4W7D0
```

**Success Response:**
```json
{
    "success": true,
    "message": "Data fetch successfully!",
    "customer": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "date_of_birth": "10/12/1990",
        "id_type": "passport",
        "id_number": "GBR123456789",
        "ulid": "01K44CWWXSAAHPSCQK8TP4W7D0",
        "status": "PENDING",
        "created_at": "2025-09-02T05:02:51.000000Z",
        "reference_id": "ref-1124",
        "meta": {
            "user_id": "1212421"
        }
    }
}
```

### 3. Update Customer
**Endpoint:** `PUT /api/cardyfie/customer/update/{ulid}`

**Full URL:** `https://debit.gmpayapp.site/public/api/cardyfie/customer/update/{ulid}`

**Path Parameter:**
- `ulid` - Customer ULID from Cardyfie (required)

**Note:** Email is NOT included in update endpoint (unlike create). Image fields can be omitted to keep existing images.

**Request Body:**
```json
{
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-12-10",
    "id_type": "passport",
    "id_number": "GBR123456789",
    "id_front_image": "https://example.com/id_front.jpg",
    "user_image": "https://example.com/user.jpg",
    "house_number": "221B",
    "address_line_1": "Baker Street",
    "city": "London",
    "zip_code": "NW1 6XE"
}
```

**Required Fields:**
- `first_name` - Customer's first name
- `last_name` - Customer's last name
- `date_of_birth` - Date in format `YYYY-MM-DD` or `DD/MM/YYYY`
- `id_type` - One of: `passport`, `nid`, `bvn`
- `id_number` - ID document number
- `id_front_image` - URL to front of ID image (or omit to keep existing)
- `user_image` - URL to customer photo (or omit to keep existing)
- `house_number` - House/building number
- `address_line_1` - Street address
- `city` - City name
- `zip_code` - Postal/ZIP code

**Optional Fields:**
- `id_back_image` - URL to back of ID image (or omit to keep existing)
- `state` - State/Province name
- `meta` - Object with custom metadata (e.g., `{"user_id": "123"}`)
- `user_id` - Direct user ID field (convenience, stored in meta)

**Success Response:**
```json
{
    "success": true,
    "message": "Update information submitted successfully, please wait for confirmation.",
    "customer": {
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "10/12/1990",
        "id_type": "passport",
        "id_number": "GBR123456789",
        "ulid": "01K44CWWXSAAHPSCQK8TP4W7D0",
        "status": "PENDING",
        "created_at": "2025-09-02T05:02:51.000000Z",
        "reference_id": "ref-1124",
        "meta": {
            "user_id": "1212421"
        }
    },
    "ulid": "01K44CWWXSAAHPSCQK8TP4W7D0"
}
```

**Error Response:**
```json
{
    "success": false,
    "message": "Missing required field: first_name",
    "error_code": 400
}
```

### 4. Get Card Currencies
**Endpoint:** `GET /api/cardyfie/card/currencies`

**Full URL:** `https://debit.gmpayapp.site/public/api/cardyfie/card/currencies`

**Description:** Returns list of currencies available for card issuance.

**Success Response:**
```json
{
    "success": true,
    "message": "Data fetch successfully!",
    "currencies": [
        {
            "id": 2,
            "provider_id": 3,
            "currency_id": 2,
            "status": "ACTIVE",
            "created_at": "2025-09-26T10:03:45.000000Z",
            "currency": {
                "id": 2,
                "code": "USD",
                "name": "United States dollar",
                "symbol": "$"
            }
        }
    ],
    "count": 1
}
```

**Error Response:**
```json
{
    "success": false,
    "message": "Failed to retrieve currencies",
    "error_code": 404
}
```

### 5. Issue Card
**Endpoint:** `POST /api/cardyfie/card/issue`

**Full URL:** `https://debit.gmpayapp.site/public/api/cardyfie/card/issue`

**Description:** Issues a virtual card for a customer. You need to get available currencies from the card currencies endpoint first.

**Request Body:**
```json
{
    "customer_ulid": "01K44CWWXSAAHPSCQK8TP4W7D0",
    "card_name": "John Doe",
    "card_currency": "USD",
    "card_type": "universal",
    "card_provider": "visa",
    "reference_id": "CARD_REF_12345"
}
```

**Required Fields:**
- `customer_ulid` - Customer ULID from Cardyfie (from create customer response)
- `card_name` - Name to be printed on the card
- `card_currency` - Currency code (e.g., "USD", "EUR") - Get from `/card/currencies` endpoint
- `card_type` - Card type: `universal` or `platinum`
- `card_provider` - Card provider: `visa` or `mastercard`

**Optional Fields:**
- `reference_id` - Your custom reference ID for tracking
- `meta.reference_id` - Alternative way to pass reference_id

**Success Response:**
```json
{
    "success": true,
    "message": "Card Issued Successfully!",
    "card": {
        "id": 2,
        "ulid": "01K62R43VAMPRMBDNT2W76RNDV",
        "card_name": "John Doe",
        "card_balance": "0.000000000000000000",
        "card_currency_code": "USD",
        "card_type": "universal",
        "card_provider": "visa",
        "card_exp_time": "09/2027",
        "masked_pan": "4334 51****** 4713",
        "address": "2381 Zanker Rd Ste 110, San Jose, CA, 95131, US",
        "status": "ENABLED",
        "env": "SANDBOX",
        "created_at": "2025-09-26T10:11:57.000000Z"
    },
    "card_ulid": "01K62R43VAMPRMBDNT2W76RNDV"
}
```

**Error Response:**
```json
{
    "success": false,
    "message": "Missing required field: customer_ulid",
    "error_code": 400
}
```

**Card Type Options:**
- `universal` - Universal card type
- `platinum` - Platinum card type

**Card Provider Options:**
- `visa` - Visa card
- `mastercard` - Mastercard

### 6. Get All Cards
**Endpoint:** `GET /api/cardyfie/card/get-all`

**Full URL:** `https://debit.gmpayapp.site/public/api/cardyfie/card/get-all`

**Description:** Returns paginated list of all cards. Supports pagination via query parameters.

**Query Parameters (Optional):**
- `page` - Page number (default: 1)
- `per_page` - Items per page (default: 10, max: 100)

**Example URLs:**
```
GET /api/cardyfie/card/get-all
GET /api/cardyfie/card/get-all?page=1
GET /api/cardyfie/card/get-all?page=2&per_page=20
```

**Success Response:**
```json
{
    "success": true,
    "message": "Data fetch successfully!",
    "cards": [
        {
            "id": 1,
            "ulid": "01K5V21E7ENVH0MV04E20SAMAA",
            "card_name": "John Doe",
            "card_balance": "0.000000000000000000",
            "card_currency_code": "USD",
            "card_type": "universal",
            "card_provider": "visa",
            "card_exp_time": "09/2027",
            "masked_pan": "4040 38****** 0299",
            "address": "2381 Zanker Rd Ste 110, San Jose, CA, 95131, US",
            "status": "ENABLED",
            "env": "SANDBOX",
            "created_at": "2025-09-23T10:31:20.000000Z"
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 10,
        "total": 3,
        "last_page": 1,
        "from": 1,
        "to": 3,
        "first_page_url": "https://core.cardyfie.com/api/sandbox/v1/card/get-all?page=1",
        "last_page_url": "https://core.cardyfie.com/api/sandbox/v1/card/get-all?page=1",
        "next_page_url": null,
        "prev_page_url": null,
        "path": "https://core.cardyfie.com/api/sandbox/v1/card/get-all",
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "active": false
            },
            {
                "url": "https://core.cardyfie.com/api/sandbox/v1/card/get-all?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "active": false
            }
        ]
    },
    "count": 3
}
```

**Error Response:**
```json
{
    "success": false,
    "message": "Failed to retrieve cards",
    "error_code": 404
}
```

### 7. Get Card Details
**Endpoint:** `GET /api/cardyfie/card/details/{ulid}`

**Full URL:** `https://debit.gmpayapp.site/public/api/cardyfie/card/details/{ulid}`

**Path Parameter:**
- `ulid` - Card ULID from Cardyfie (required)

**Alternative (Query Parameter):**
- `GET /api/cardyfie/card/details?ulid={ulid}` (also supported for flexibility)

**Description:** Returns detailed information about a specific card. This endpoint includes sensitive information like CVV and real PAN number that are not included in the get-all cards response.

**Example:**
```
GET /api/cardyfie/card/details/01K5GXP0RQ5KYECGBJE7Z4AJNG
GET /api/cardyfie/card/details?ulid=01K5GXP0RQ5KYECGBJE7Z4AJNG
```

**Success Response:**
```json
{
    "success": true,
    "message": "Virtual Card Details Fetch Successfully!",
    "card": {
        "id": 7,
        "ulid": "01K5GXP0RQ5KYECGBJE7Z4AJNG",
        "card_name": "John Doe",
        "card_balance": "0.000000000000000000",
        "card_currency_code": "USD",
        "card_type": "universal",
        "card_provider": "visa",
        "card_exp_time": "09/2027",
        "masked_pan": "4334 51****** 1140",
        "address": "2381 Zanker Rd Ste 110, San Jose, CA, 95131, US",
        "status": "ENABLED",
        "env": "SANDBOX",
        "created_at": "2025-09-19T12:02:47.000000Z",
        "cvv": "450",
        "real_pan": "4334 5139 4939 1140",
        "api_credential_id": 1
    }
}
```

**⚠️ Security Note:** This endpoint returns sensitive information:
- `cvv` - Card CVV code
- `real_pan` - Full card number (not masked)

**Error Response:**
```json
{
    "success": false,
    "message": "Card not found",
    "error_code": 404
}
```

### 8. Deposit to Card
**Endpoint:** `POST /api/cardyfie/card/deposit/{ulid}`

**Full URL:** `https://debit.gmpayapp.site/public/api/cardyfie/card/deposit/{ulid}`

**Path Parameter:**
- `ulid` - Card ULID from Cardyfie (required)

**Description:** Deposits funds to a card, increasing the card balance.

**Request Body:**
```json
{
    "amount": 100.50
}
```

**Required Fields:**
- `amount` - Amount to deposit (positive number or string, greater than zero)

**Note**: You can send the amount as a number (e.g., `100.50`) or string (e.g., `"100.50"`). The API automatically converts it to the string format required by Cardyfie.

**Success Response:**
```json
{
    "success": true,
    "message": "Card Deposited Successfully!",
    "card_ulid": "01K5GXP0RQ5KYECGBJE7Z4AJNG",
    "amount": 100.50
}
```

**Error Response:**
```json
{
    "success": false,
    "message": "Amount must be greater than zero",
    "error_code": 400
}
```

**⚠️ Important:** This endpoint adds real funds to the card. Use with caution in production.

### 9. Withdraw from Card
**Endpoint:** `POST /api/cardyfie/card/withdraw/{ulid}`

**Full URL:** `https://debit.gmpayapp.site/public/api/cardyfie/card/withdraw/{ulid}`

**Path Parameter:**
- `ulid` - Card ULID from Cardyfie (required)

**Description:** Withdraws funds from a card, decreasing the card balance.

**Request Body:**
```json
{
    "amount": 50.25
}
```

**Required Fields:**
- `amount` - Amount to withdraw (positive number or string, greater than zero)

**Note**: You can send the amount as a number (e.g., `50.25`) or string (e.g., `"50.25"`). The API automatically converts it to the string format required by Cardyfie.

**Success Response:**
```json
{
    "success": true,
    "message": "Withdrawal completed successfully.",
    "card_ulid": "01K5GXP0RQ5KYECGBJE7Z4AJNG",
    "amount": 50.25
}
```

**Error Response:**
```json
{
    "success": false,
    "message": "Amount must be greater than zero",
    "error_code": 400
}
```

**⚠️ Important:** This endpoint removes real funds from the card. Ensure sufficient balance before withdrawal.

### 10. Get Card Transactions
**Endpoint:** `GET /api/cardyfie/card/transactions`

**Full URL:** `https://debit.gmpayapp.site/public/api/cardyfie/card/transactions`

**Query Parameter (Optional):**
- `card_ulid` - Card ULID to filter transactions for a specific card. If omitted, returns all card transactions.

**Description:** Returns a list of card transactions. If `card_ulid` is provided, returns transactions for that specific card only. If omitted, returns all card transactions.

**Example URLs:**
```
GET /api/cardyfie/card/transactions
GET /api/cardyfie/card/transactions?card_ulid=01K5V21E7MED7EG2K9612XPEK4
```

**Success Response:**
```json
{
    "success": true,
    "message": "Data fetch successfully!",
    "transactions": [
        {
            "ulid": "01K5V21E7MED7EG2K9612XPEK4",
            "trx_type": "CARD-ISSUE",
            "trx_id": "VCI-rxgNBWCWln5FH1",
            "card_currency": "USD",
            "wallet_currency": "USD",
            "enter_amount": "0.000000000000000000",
            "total_payable": "3.000000000000000000",
            "created_at": "2025-09-23T10:31:20.000000Z",
            "exchange_rate": "1.000000000000000000",
            "fees": "3.000000000000000000",
            "fees_currency": "USD",
            "amount_type": "CREDIT",
            "status": "SUCCESS"
        },
        {
            "ulid": "01K5V8GBBMF2CBTBBW4GKG0371",
            "trx_type": "CARD-DEPOSIT",
            "trx_id": "VCD-O9FaBpwF5nFg2w",
            "card_currency": "USD",
            "wallet_currency": "USD",
            "enter_amount": "10.000000000000000000",
            "total_payable": "0.000000000000000000",
            "created_at": "2025-09-23T12:24:20.000000Z",
            "exchange_rate": "0.000000000000000000",
            "fees": "0.000000000000000000",
            "fees_currency": "USD",
            "amount_type": "CREDIT",
            "status": "SUCCESS"
        }
    ],
    "count": 2,
    "card_ulid": "01K5V21E7MED7EG2K9612XPEK4"
}
```

**Transaction Fields:**
- `ulid` - Transaction ULID
- `trx_type` - Transaction type (e.g., "CARD-ISSUE", "CARD-DEPOSIT", "CARD-WITHDRAW")
- `trx_id` - Transaction ID
- `card_currency` - Currency of the card
- `wallet_currency` - Currency of the wallet
- `enter_amount` - Amount entered
- `total_payable` - Total amount payable
- `created_at` - Transaction creation timestamp
- `exchange_rate` - Exchange rate applied
- `fees` - Transaction fees
- `fees_currency` - Currency of the fees
- `amount_type` - Type: "CREDIT" or "DEBIT"
- `status` - Transaction status (e.g., "SUCCESS", "PENDING", "FAILED")

**Error Response:**
```json
{
    "success": false,
    "message": "Failed to retrieve transactions",
    "error_code": 404
}
```

### 11. Freeze Card
**Endpoint:** `POST /api/cardyfie/card/freeze/{ulid}`

**Full URL:** `https://debit.gmpayapp.site/public/api/cardyfie/card/freeze/{ulid}`

**Path Parameter:**
- `ulid` - Card ULID from Cardyfie (required)

**Description:** Freezes a card, preventing it from being used for transactions. The card can be unfrozen later using the unfreeze endpoint.

**Request Body:** Empty (no body required)

**Success Response:**
```json
{
    "success": true,
    "message": "Card freeze successfully!",
    "card_ulid": "01K5GXP0RQ5KYECGBJE7Z4AJNG"
}
```

**Error Response:**
```json
{
    "success": false,
    "message": "Card freeze failed",
    "error_code": 400
}
```

**⚠️ Important:** Freezing a card will prevent all transactions. The card must be unfrozen before it can be used again.

### 12. Unfreeze Card
**Endpoint:** `POST /api/cardyfie/card/unfreeze/{ulid}`

**Full URL:** `https://debit.gmpayapp.site/public/api/cardyfie/card/unfreeze/{ulid}`

**Path Parameter:**
- `ulid` - Card ULID from Cardyfie (required)

**Description:** Unfreezes a card, allowing it to be used for transactions again. This reverses the freeze action.

**Request Body:** Empty (no body required)

**Success Response:**
```json
{
    "success": true,
    "message": "Card unfreeze successfully!",
    "card_ulid": "01K5GXP0RQ5KYECGBJE7Z4AJNG"
}
```

**Error Response:**
```json
{
    "success": false,
    "message": "Card unfreeze failed",
    "error_code": 400
}
```

**Note:** This endpoint restores a frozen card to normal operation. The card can be used for transactions immediately after unfreezing.

### 13. Close Card
**Endpoint:** `POST /api/cardyfie/card/close/{ulid}`

**Full URL:** `https://debit.gmpayapp.site/public/api/cardyfie/card/close/{ulid}`

**Path Parameter:**
- `ulid` - Card ULID from Cardyfie (required)

**Description:** Permanently closes a card. This action is irreversible and the card cannot be reopened or used for transactions after closing.

**Request Body:** Empty (no body required)

**Success Response:**
```json
{
    "success": true,
    "message": "Card closed successfully!",
    "card_ulid": "01K5GXP0RQ5KYECGBJE7Z4AJNG"
}
```

**Error Response:**
```json
{
    "success": false,
    "message": "Card close failed",
    "error_code": 400
}
```

**⚠️ Critical Warning:** Closing a card is a permanent action that cannot be undone. The card will be permanently disabled and cannot be reopened. Ensure you want to permanently close the card before using this endpoint.

**Note:** Consider using the freeze endpoint if you only need to temporarily disable a card, as frozen cards can be unfrozen later.

### 14. Health Check
**Endpoint:** `GET /api/cardyfie/health`

**Full URL:** `https://debit.gmpayapp.site/public/api/cardyfie/health`

**Response:**
```json
{
    "success": true,
    "message": "Cardyfie service is running",
    "environment": "sandbox",
    "timestamp": "2025-10-10 12:00:00"
}
```

## cURL Examples

### Create Customer
```bash
curl -X POST "https://debit.gmpayapp.site/public/api/cardyfie/customer/create" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "date_of_birth": "1990-12-10",
    "id_type": "passport",
    "id_number": "GBR123456789",
    "id_front_image": "https://example.com/id_front.jpg",
    "user_image": "https://example.com/user.jpg",
    "house_number": "221B",
    "address_line_1": "Baker Street",
    "city": "London",
    "zip_code": "NW1 6XE",
    "country": "UK"
  }'
```

### Get Customer by ULID (Path Parameter)
```bash
curl "https://debit.gmpayapp.site/public/api/cardyfie/customer/get/01K44CWWXSAAHPSCQK8TP4W7D0"
```

### Get Customer by ULID (Query Parameter - Alternative)
```bash
curl "https://debit.gmpayapp.site/public/api/cardyfie/customer/get?ulid=01K44CWWXSAAHPSCQK8TP4W7D0"
```

### Update Customer (Path Parameter)
```bash
curl -X PUT "https://debit.gmpayapp.site/public/api/cardyfie/customer/update/01K44CWWXSAAHPSCQK8TP4W7D0" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-12-10",
    "id_type": "passport",
    "id_number": "GBR123456789",
    "id_front_image": "https://example.com/id_front.jpg",
    "user_image": "https://example.com/user.jpg",
    "house_number": "221B",
    "address_line_1": "Baker Street",
    "city": "London",
    "zip_code": "NW1 6XE"
  }'
```

### Update Customer (ULID in Body - Alternative)
```bash
curl -X PUT "https://debit.gmpayapp.site/public/api/cardyfie/customer/update" \
  -H "Content-Type: application/json" \
  -d '{
    "ulid": "01K44CWWXSAAHPSCQK8TP4W7D0",
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-12-10",
    "id_type": "passport",
    "id_number": "GBR123456789",
    "id_front_image": "https://example.com/id_front.jpg",
    "user_image": "https://example.com/user.jpg",
    "house_number": "221B",
    "address_line_1": "Baker Street",
    "city": "London",
    "zip_code": "NW1 6XE"
  }'
```

### Get Card Currencies
```bash
curl "https://debit.gmpayapp.site/public/api/cardyfie/card/currencies"
```

### Issue Card
```bash
curl -X POST "https://debit.gmpayapp.site/public/api/cardyfie/card/issue" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_ulid": "01K44CWWXSAAHPSCQK8TP4W7D0",
    "card_name": "John Doe",
    "card_currency": "USD",
    "card_type": "universal",
    "card_provider": "visa",
    "reference_id": "CARD_REF_12345"
  }'
```

### Get All Cards
```bash
# Get first page (default)
curl "https://debit.gmpayapp.site/public/api/cardyfie/card/get-all"

# Get specific page
curl "https://debit.gmpayapp.site/public/api/cardyfie/card/get-all?page=2"

# Get with custom page size
curl "https://debit.gmpayapp.site/public/api/cardyfie/card/get-all?page=1&per_page=20"
```

### Get Card Details (Path Parameter)
```bash
curl "https://debit.gmpayapp.site/public/api/cardyfie/card/details/01K5GXP0RQ5KYECGBJE7Z4AJNG"
```

### Get Card Details (Query Parameter - Alternative)
```bash
curl "https://debit.gmpayapp.site/public/api/cardyfie/card/details?ulid=01K5GXP0RQ5KYECGBJE7Z4AJNG"
```

### Deposit to Card (Path Parameter)
```bash
curl -X POST "https://debit.gmpayapp.site/public/api/cardyfie/card/deposit/01K5GXP0RQ5KYECGBJE7Z4AJNG" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.50
  }'
```

### Deposit to Card (ULID in Body - Alternative)
```bash
curl -X POST "https://debit.gmpayapp.site/public/api/cardyfie/card/deposit" \
  -H "Content-Type: application/json" \
  -d '{
    "ulid": "01K5GXP0RQ5KYECGBJE7Z4AJNG",
    "amount": 100.50
  }'
```

### Withdraw from Card (Path Parameter)
```bash
curl -X POST "https://debit.gmpayapp.site/public/api/cardyfie/card/withdraw/01K5GXP0RQ5KYECGBJE7Z4AJNG" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.25
  }'
```

### Withdraw from Card (ULID in Body - Alternative)
```bash
curl -X POST "https://debit.gmpayapp.site/public/api/cardyfie/card/withdraw" \
  -H "Content-Type: application/json" \
  -d '{
    "ulid": "01K5GXP0RQ5KYECGBJE7Z4AJNG",
    "amount": 50.25
  }'
```

### Get Card Transactions (All Cards)
```bash
curl "https://debit.gmpayapp.site/public/api/cardyfie/card/transactions"
```

### Get Card Transactions (Specific Card)
```bash
curl "https://debit.gmpayapp.site/public/api/cardyfie/card/transactions?card_ulid=01K5V21E7MED7EG2K9612XPEK4"
```

### Freeze Card (Path Parameter)
```bash
curl -X POST "https://debit.gmpayapp.site/public/api/cardyfie/card/freeze/01K5GXP0RQ5KYECGBJE7Z4AJNG" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Freeze Card (ULID in Body - Alternative)
```bash
curl -X POST "https://debit.gmpayapp.site/public/api/cardyfie/card/freeze" \
  -H "Content-Type: application/json" \
  -d '{
    "ulid": "01K5GXP0RQ5KYECGBJE7Z4AJNG"
  }'
```

### Unfreeze Card (Path Parameter)
```bash
curl -X POST "https://debit.gmpayapp.site/public/api/cardyfie/card/unfreeze/01K5GXP0RQ5KYECGBJE7Z4AJNG" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Unfreeze Card (ULID in Body - Alternative)
```bash
curl -X POST "https://debit.gmpayapp.site/public/api/cardyfie/card/unfreeze" \
  -H "Content-Type: application/json" \
  -d '{
    "ulid": "01K5GXP0RQ5KYECGBJE7Z4AJNG"
  }'
```

### Close Card (Path Parameter)
```bash
curl -X POST "https://debit.gmpayapp.site/public/api/cardyfie/card/close/01K5GXP0RQ5KYECGBJE7Z4AJNG" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Close Card (ULID in Body - Alternative)
```bash
curl -X POST "https://debit.gmpayapp.site/public/api/cardyfie/card/close" \
  -H "Content-Type: application/json" \
  -d '{
    "ulid": "01K5GXP0RQ5KYECGBJE7Z4AJNG"
  }'
```

## Date Format Support

The API accepts multiple date formats and automatically converts them:
- `YYYY-MM-DD` (e.g., `1990-12-10`)
- `DD/MM/YYYY` (e.g., `10/12/1990`)
- `DD-MM-YYYY` (e.g., `10-12-1990`)

All dates are normalized to `DD/MM/YYYY` format for Cardyfie API.

## ID Types

Accepted ID types:
- `passport` - Passport
- `nid` - National ID
- `bvn` - Bank Verification Number

## Error Handling

The API returns standardized error responses:
- **400** - Bad Request (missing/invalid fields)
- **404** - Not Found (customer not found)
- **500** - Internal Server Error

All errors include a `message` field describing the issue.

## Security Notes

- API keys are encrypted when stored
- SSL verification is enabled by default
- All personal data should be handled according to data protection regulations
- Image URLs must be publicly accessible HTTPS URLs

## Implementation Details

- **Service Class:** `App\Libraries\CardyfieService`
- **Controller:** `App\Controllers\Cardyfie`
- **Routes:** Defined in `app/Config/Routes.php`

## Next Steps

1. Add your Cardyfie API key to `.env` file
2. Set the environment (`sandbox` or `production`)
3. Test with the health check endpoint
4. Create a test customer
5. Retrieve the customer using the returned ULID or reference_id