# Cards API (Tokenization & Verification)

This API supports various card-related functionalities within the Dime payment system: creating a card tokenization request, verifying a microcharge (or verification value), and fetching saved card details.

Verification first happens by 3DS and then falls back to verifying an authorized amount if the card issuing bank does not support 3DS. You'll

**Version:** 1.0.0

## Servers

- **Production:** `https://api.dimepay.app/dapi/v1`
- **Sandbox:** `https://sandbox.api.dimepay.app/dapi/v1`


## Authentication

All endpoints require the `client_key` header.


```http
client_key: abcd1234
```

## Endpoints

### 1) Create a New Card Request

**POST** `/card-request`

Initiates the card tokenization flow and returns a **card request token** that the customer can complete.

#### Headers

- `client_key` (string, required) – API key provided by Dime.


#### Request Body

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `lang` | string | Yes | Language for the flow. Example: `en` |
| `data` | string (JWT) | Yes | A **signed JWT** with input fields below. |


**Fields to include in the JWT payload:**

- `id`: Your internal ID for the card request (e.g., `"123456789"`). In the response this will be the reference_id
- `webhookUrl`: Your backend URL to receive payment/tokenization events.
- `redirectUrl`: Where to redirect the customer after completion.


#### Example Unsigned Payload


```json
{
  "id": "123456789",
  "webhookUrl": "https://webhookurl",
  "redirectUrl": "https://redirectUrl"
}
```

#### Example: Signing the Payload


```javascript
const jwt = require('jsonwebtoken');
const payload = { /* fields above */ };
const signedData = jwt.sign(payload, 'your_secret_key');
```

#### Final Request Payload


```json
{
  "lang": "en",
  "data": "<signed_jwt_token>"
}
```

#### Response (201)

Returns a `CardRequest` object.


```json
{
  "card_url": "https://sandbox.dimepay.app/e-card/mTadnj13sna/cr_UqT9YwgGG-sqA",
  "token": "cr_UqT9YwgGG-sqA",
  "reference_id": "123456789",
  "expired": false,
  "status": "SUCCESS",
  "currency": "USD",
  "card_expiry": "12/25",
  "card_scheme": "Visa",
  "last_four_digits": "1234",
  "verification_attempts": 0
}
```

### 2) Send the user to verify the card

The user can verify their card via card_url from the initial request.

a) Redirect the user to the card_url
b) Embed using an iframe

The webhook will be triggered when the verification is complete and the result sent to your server.

**Webhook Response**


```json
{
  "token": "card_abcd12345",
  "card_request_token": "cr_abcd12345",
  "reference_id": "123456789",
  "status": "SUCCESS",
  "currency": "USD",
  "card_expiry": "12/25",
  "card_scheme": "Visa",
  "last_four_digits": "1234",
  "expired": false
}
```

### 2) Get Card Details

**GET** `/cards/{card_request_token}`

Fetches details for a saved card by its card **token** (from the verification step).

#### Headers

- `client_key` (string, required)


#### Path Parameters

- `token` (string, required) – The saved card token (e.g., `card_abcd12345`).


#### Response (200)


```json
{
  "token": "card_abcd12345",
  "card_request_token": "cr_abcd12345",
  "reference_id": "123456789",
  "status": "SUCCESS",
  "currency": "USD",
  "card_expiry": "12/25",
  "card_scheme": "Visa",
  "last_four_digits": "1234",
  "expired": false
}
```

## Schemas

### CardRequest

Represents the state of a card tokenization **request**.

| Field | Type | Description |
|  --- | --- | --- |
| `token` | string | Unique identifier for the card request (e.g., `cr_...`). |
| `reference_id` | string | Id reference initially sent in the card request. |
| `expired` | boolean | Whether the request has expired. |
| `status` | `"STARTED" | "VERIFICATION" | "FAILED" | "SUCCESS"` | Current status of the request. |
| `currency` | `"USD" | "JMD" | "GBP" | "EUR" | "TTD" | "BBD" | "XCD"` | Currency used for verification. |
| `card_expiry` | string | Masked expiry in `MM/YY`. |
| `card_scheme` | string | Card scheme (Visa, Mastercard, etc.). |
| `last_four_digits` | string | Last four digits. |
| `verification_attempts` | number | Number of verification tries. |


### Card

Returned after successful verification; represents the **saved card token**.

| Field | Type | Description |
|  --- | --- | --- |
| `token` | string | Unique token of the saved card (use for future charges). |
| `card_request_token` | string | Unique identifier for the card request (e.g., `cr_...`). |
| `reference_id` | string | Id reference initially sent in the card request. |
| `status` | `"STARTED" | "VERIFICATION" | "FAILED" | "SUCCESS"` | Final status. |
| `currency` | enum | Currency associated with the card. |
| `card_expiry` | string | `MM/YY`. |
| `card_scheme` | string | Visa, Mastercard, etc. |
| `last_four_digits` | string | Card last four. |
| `expired` | boolean | Whether the card token is expired. |
| `verification_attempts` | number | Number of attempts used to verify. |


### CardDetails

Same view as `Card`, fetched via `GET /cards/{card_request_token}`.

## Security

This API uses an **API Key** for authentication.


```http
client_key: <your_api_key>
```

## Node.js Examples

> These examples use **axios** and **jsonwebtoken**. Replace `your_secret_key`, `client_key`, and URLs with your values.


### 1) Create Card Request


```javascript
const axios = require('axios');
const jwt = require('jsonwebtoken');

const CLIENT_KEY = 'abcd1234';
const API = 'https://sandbox.api.dimepay.app/dapi/v1';

async function createCardRequest() {
  const payload = {
    id: '123456789',
    webhookUrl: 'https://webhookurl',
    redirectUrl: 'https://redirectUrl'
  };

  const signedData = jwt.sign(payload, 'your_secret_key');

  try {
    const res = await axios.post(`${API}/card-request`, {
      lang: 'en',
      data: signedData
    }, {
      headers: { client_key: CLIENT_KEY }
    });

    console.log('Card Request:', res.data);
    // Save res.data.token (e.g., cr_UqT9YwgGG-sqA) for verification
  } catch (err) {
    console.error('Create card request error:', err.response?.data || err.message);
  }
}

createCardRequest();
```

### 2) Get Card Details


```javascript
const axios = require('axios');

const CLIENT_KEY = 'abcd1234';
const API = 'https://sandbox.api.dimepay.app/dapi/v1';

async function getCardDetails() {
  // Replace with the saved card request token from verification
  const savedCardRequestToken = 'cr_abcd12345';

  try {
    const res = await axios.get(`${API}/cards/${savedCardRequestToken}`, {
      headers: { client_key: CLIENT_KEY }
    });

    console.log('Card Details:', res.data);
  } catch (err) {
    console.error('Get card details error:', err.response?.data || err.message);
  }
}

getCardDetails();
```