Skip to content
/
Cards API (Tokenization &...
Last updated

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.

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

FieldTypeRequiredDescription
langstringYesLanguage for the flow. Example: en
datastring (JWT)YesA 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

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

Example: Signing the Payload

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

Final Request Payload

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

Response (201)

Returns a CardRequest object.

{
  "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

{
  "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)

{
  "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.

FieldTypeDescription
tokenstringUnique identifier for the card request (e.g., cr_...).
reference_idstringId reference initially sent in the card request.
expiredbooleanWhether 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_expirystringMasked expiry in MM/YY.
card_schemestringCard scheme (Visa, Mastercard, etc.).
last_four_digitsstringLast four digits.
verification_attemptsnumberNumber of verification tries.

Card

Returned after successful verification; represents the saved card token.

FieldTypeDescription
tokenstringUnique token of the saved card (use for future charges).
card_request_tokenstringUnique identifier for the card request (e.g., cr_...).
reference_idstringId reference initially sent in the card request.
status"STARTED" | "VERIFICATION" | "FAILED" | "SUCCESS"Final status.
currencyenumCurrency associated with the card.
card_expirystringMM/YY.
card_schemestringVisa, Mastercard, etc.
last_four_digitsstringCard last four.
expiredbooleanWhether the card token is expired.
verification_attemptsnumberNumber 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.

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

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

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();

📘 Getting Started

Orders