> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swervpay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Swerv Card API allows businesses to create card for their customer to pay anywhere global

This API provides a powerful, secure, and easy-to-use set of endpoints for card management, including creation, retrieval, freezing, and termination of cards. This guide will cover essential operations to help you manage card transactions within your applications

## Card Details Encryption

All card details are encrypted follows the AES standard with the following parameters:

* Algorithm: AES (RijndaelManaged)

* Mode: CBC (Cipher Block Chaining)

* Padding: PKCS7

* Block Size: 128-bit

* Key & IV: Derived from your registered Business ID:

* Key: The first 16 characters of your Business ID

* IV (Initialization Vector): The last 16 characters of your Business ID

```json Encrypted Card Details Payload theme={null}
{
    "card_number": "1234567890123456",
    "cvv": "123",
    "expiry": "12/34",
    "masked_pan": "424242******4242"
}
```

<CodeGroup>
  ```javascript NodeJS theme={null}
  const crypto = require('crypto');

  function decryptStringAES(cipherText, clientId) {
      const iv = Buffer.from(clientId.slice(0, 16), 'utf8');
      const key = Buffer.from(clientId.slice(-16), 'utf8');
      const encrypted = Buffer.from(cipherText, 'base64');
      try {
          const decipher = crypto.createDecipheriv('aes-128-cbc', key, iv);
          let decrypted = decipher.update(encrypted);
          decrypted = Buffer.concat([decrypted, decipher.final()]);
          return JSON.parse(decrypted.toString());
      } catch (err) {
          return "keyError";
      }
  }
  ```

  ```go Go theme={null}
  type CardInformation struct {
  	CardNumber string `json:"card_number"`
  	CardCvv    string `json:"cvv"`
  	CardExpiry string `json:"expiry"`
  	MaskedPan  string `json:"masked_pan"`
  }


  func decryptCardInformation(clientId, cipherText string) CardInformation {

  	iv := []byte(clientId[:16])
  	key := []byte(clientId[len(clientId)-16:])
  	encrypted, _ := base64.StdEncoding.DecodeString(cipherText)

  	block, err := aes.NewCipher(key)
  	if err != nil {
  		panic(err)
  	}

  	if len(encrypted)%aes.BlockSize != 0 {
  		panic("ciphertext not a multiple of block size")
  	}

  	mode := cipher.NewCBCDecrypter(block, iv)
  	decrypted := make([]byte, len(encrypted))
  	mode.CryptBlocks(decrypted, encrypted)

  	// remove PKCS7 padding
  	padLen := int(decrypted[len(decrypted)-1])
  	decrypted = decrypted[:len(decrypted)-padLen]

  	var details CardInformation
  	err = json.Unmarshal([]byte(decrypted), &details)
  	if err != nil {
  		panic(err)
  	}

  	return details
  }
  ```

  ```php PHP theme={null}
  function decryptStringAES($cipherText, $clientId) {
      $iv = substr($clientId, 0, 16);
      $key = substr($clientId, -16);
      $cipherBytes = base64_decode($cipherText);
      $decrypted = openssl_decrypt($cipherBytes, 'AES-128-CBC', $key, OPENSSL_RAW_DATA, $iv);
      if ($decrypted === false) {
          return "keyError";
      }
      return json_decode($decrypted, true);
  }
  ```
</CodeGroup>

### 📇 Create a Card

Initiate the creation of a virtual or physical card by sending a request to the [create](/api-reference/cards/create) card endpoint.

**Parameters**

<ParamField body="customer_id" type="string">
  The unique identifier for the customer to whom the card will be issued.
</ParamField>

<ParamField body="currency" type="string" required>
  The three-letter ISO currency code in uppercase.
</ParamField>

<ParamField body="name_on_card" type="string">
  The cardholder name that may appear on the card.
</ParamField>

<ParamField body="provider" type="string" required>
  card provider e.g MASTERCARD, VISA
</ParamField>

<ParamField body="type" type="string" required>
  card type e.g DEFAULT, LITE or COOPERATE
</ParamField>

<ParamField body="amount" type="integer">
  amount to pre-fund the card
</ParamField>

<ParamField body="expiry_date" type="string">
  The expiry date of the card in the format YYYY-MM-DD.
</ParamField>

<ParamField body="phone_number" type="string">
  Phone number of the cardholder (for cooperate & lite card type only)
</ParamField>

<ParamField body="rc_number" type="string">
  RC Number of the company (for cooperate card type only)
</ParamField>

<ParamField body="director_bvn" type="string">
  BVN of the director of the company (for cooperate card type only)
</ParamField>

<ParamField body="business_email" type="string">
  Business email of the company (for cooperate card type only)
</ParamField>

<ParamField body="document.document_number" type="string">
  Document number of the company (for lite card type only)
</ParamField>

<ParamField body="document.document_type" type="string">
  Document type of the company (for lite card type only)
</ParamField>

<Note>
  Note: `customer_id` is required for DEFAULT card type
</Note>

**Request Body**

Provide necessary details to set up a new card.

```json theme={null}
{
    "customer_id": "user",
    "currency": "USD",
    "issuer": "MASTERCARD",
    "name_on_card": "Swerv",
    "expiry_date": "2025-01-01",
    "amount": 10,
    "type": "DEFAULT"
}
```

### 💳➕ Fund Card

Add funds to an existing card using the [fund](/api-reference/cards/fund) endpoint. This operation is essential for increasing the card's available balance for use.

**Parameters**

<ParamField path="id" type="string" required>
  The unique identifier of the card to fund.
</ParamField>

**Body**

<ParamField body="amount" type="integer">
  The amount to fund in the smallest currency unit.
</ParamField>

### 🔍 Get a Card

Retrieve information about a specific card with its unique identifier using the [get](/api-reference/cards/get) card endpoint.

**Parameters**

<ParamField path="id" type="string" required>
  The unique identifier of the card to retrieve.
</ParamField>

### ❄️ Freeze a Card

Temporarily disable a card to prevent new transactions by using the [freeze](/api-reference/cards/freeze) card endpoint.

**Path Parameters**

<ParamField path="id" type="string" required>
  The unique identifier of the card to freeze/unfreeze.
</ParamField>

### 🚫 Terminate a Card

Permanently disable a card and remove it from your account with the [terminate](/api-reference/cards/terminate) card endpoint.

**Path Parameters**

<ParamField path="id" type="string" required>
  The unique identifier of the card to terminate.
</ParamField>

### 💸  Withdraw from Card

Withdraw funds from the card back to your business account using the [withdraw-from-card](/api-reference/cards/withdraw-from-card) endpoint.

**Path Parameters**

<ParamField path="id" type="string" required>
  The unique identifier of the card to withdraw from.
</ParamField>

**Body**

<ParamField body="amount" type="integer">
  The amount to fund in the smallest currency unit.
</ParamField>

### 🗂️ Get All Cards

To retrieve a comprehensive list of all the cards, use the [get all](/api-reference/cards/get-all-cards) cards endpoint. This method provides a paginated list of cards, complete with details for each card, allowing for effective oversight and management.

**Query Parameters**

<ParamField query="page" type="string" default={1} required>
  The page to return.
</ParamField>

<ParamField query="limit" type="string" default={10} required>
  The maximum number of results to return.
</ParamField>

**Response Example**

The response returns an array of card objects with their respective details.

```json theme={null}
[
  {
    "id": "card_123456789",
    "type": "virtual",
    "status": "active",
    "card_number": "4242424242424242",
    "expiry": "12/34",
    "cvv": "123",
    "name_on_card": "John Doe",
    "balance": 500000, // Balance in the smallest currency unit
    "total_funded": 1500000, // Total funded in the smallest currency unit
    "freeze": false,
    "address_street": "123 Swyft Street",
    "address_city": "Paytown",
    "address_state": "Paystate",
    "address_country": "NG",
    "address_postal_code": "123456",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-02T00:00:00Z",
    "masked_pan": "424242******4242"
  }
  // ...other cards
]

```