Dime API Documentation - Card Routes

Dime API Documentation - Card Routes (1.0.0)

This API supports various functionalities for cards within the Dime payment system.

Download OpenAPI description
openapi-card.json
openapi-card.yaml
Languages
Servers
Mock server
https://docs.dimepay.net/_mock/openapi-card/
Production server
https://api.dimepay.app/dapi/v1/
Sandbox server for testing
https://sandbox.api.dimepay.app/dapi/v1/

Create a new card

Request

Headers
client_keystringrequired
Example: abcd1234
Bodyapplication/jsonrequired
langstringrequired

The language that should be used

Example: "en"
datastringrequired

A signed JWT containing the card input details. Fields to include in the JWT payload:

  • currency: The currency of the card (e.g., USD).
  • cardholder_first_name: First name of the cardholder.
  • cardholder_last_name: Last name of the cardholder.
  • cardholder_email: Email address of the cardholder.
  • card_number: Card number in plain format (e.g., 5100270000000023).
  • card_cvv: CVV of the card (e.g., 123).
  • card_expiry: Expiry date of the card (MMYY format).
  • card_address: Billing address of the card.
  • card_city: City of the billing address.
  • card_country: Country of the billing address.
  • card_postal_code: Postal code of the billing address.

Example of unsigned payload:

{
  "currency": "USD",
  "cardholder_first_name": "John",
  "cardholder_last_name": "Doe",
  "cardholder_email": "john.doe@example.com",
  "card_number": "5100270000000023",
  "card_cvv": "123",
  "card_expiry": "1225",
  "card_address": "123 Main Street",
  "card_city": "New York",
  "card_country": "US",
  "card_postal_code": "10001"
}

Example of 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>"
}
Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXJyZW5jeSI6IlVTRCIsImNhcmRob2xkZXJfZmlyc3RfbmFtZSI6IkpvaG4iLCJjYXJkaG9sZGVyX2xhc3RfbmFtZSI6IkRvZSIsImNhcmRob2xkZXJfZW1haWwiOiJqb2huLmRvZUBleGFtcGxlLmNvbSIsImNhcmRfbnVtYmVyIjoiNTEwMDI3MDAwMDAwMDIzIiwiY2FyZF9jdnYiOiIxMjMiLCJjYXJkX2V4cGlyeSI6IjEyMjUiLCJjYXJkX2FkZHJlc3MiOiIxMjMgTWFpbiBTdHJlZXQiLCJjYXJkX2NpdHkiOiJOZXcgWW9yayIsImNhcmRfY291bnRyeSI6IlVTIiwiY2FyZF9wb3N0YWxfY29kZSI6IjEwMDAxIn0.qT0a8IHtdI-fUVTZAFnLMx79rmmbAtR0h4G9GhT2nmM"
curl -i -X POST \
  https://docs.dimepay.net/_mock/openapi-card/cards \
  -H 'Content-Type: application/json' \
  -H 'client_key: YOUR_API_KEY_HERE' \
  -d '{
    "lang": "en",
    "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXJyZW5jeSI6IlVTRCIsImNhcmRob2xkZXJfZmlyc3RfbmFtZSI6IkpvaG4iLCJjYXJkaG9sZGVyX2xhc3RfbmFtZSI6IkRvZSIsImNhcmRob2xkZXJfZW1haWwiOiJqb2huLmRvZUBleGFtcGxlLmNvbSIsImNhcmRfbnVtYmVyIjoiNTEwMDI3MDAwMDAwMDIzIiwiY2FyZF9jdnYiOiIxMjMiLCJjYXJkX2V4cGlyeSI6IjEyMjUiLCJjYXJkX2FkZHJlc3MiOiIxMjMgTWFpbiBTdHJlZXQiLCJjYXJkX2NpdHkiOiJOZXcgWW9yayIsImNhcmRfY291bnRyeSI6IlVTIiwiY2FyZF9wb3N0YWxfY29kZSI6IjEwMDAxIn0.qT0a8IHtdI-fUVTZAFnLMx79rmmbAtR0h4G9GhT2nmM"
  }'

Responses

Card created successfully

Bodyapplication/json
idstring(uuid)required

Unique identifier for the card request

Example: "550e8400-e29b-41d4-a716-446655440000"
expiredbooleanrequired

Indicates whether the card request is expired

Example: false
statusstringrequired

The current status of the card request

Enum"STARTED""VERIFICATION""FAILED""SUCCESS"
Example: "SUCCESS"
currencystringrequired

The currency associated with the card request

Enum"USD""JMD""GBP""EUR""TTD""BBD""XCD"
Example: "USD"
cardholder_namestringrequired

The full name of the cardholder

Example: "John Doe"
cardholder_first_namestringrequired

The first name of the cardholder

Example: "John"
cardholder_last_namestringrequired

The last name of the cardholder

Example: "Doe"
cardholder_emailstring(email)required

The email address of the cardholder

Example: "john.doe@example.com"
card_expirystringrequired

The expiration date of the card in MM/YY format

Example: "12/25"
card_typestringrequired

The type of the card (e.g., Credit, Debit)

Example: "Credit"
card_schemestringrequired

The scheme of the card (e.g., Visa, Mastercard)

Example: "Visa"
card_addressstringrequired

The billing address of the card

Example: "123 Main Street"
card_citystringrequired

The city of the billing address

Example: "New York"
card_countrystringrequired

The country of the billing address

Example: "US"
card_postal_codestringrequired

The postal code of the billing address

Example: "10001"
card_bankstring or null

The bank associated with the card

Example: "Bank of America"
last_four_digitsstringrequired

The last four digits of the card number

Example: "1234"
metadataobject

Optional metadata for the card request

Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "expired": false,
  "status": "SUCCESS",
  "currency": "USD",
  "cardholder_name": "John Doe",
  "cardholder_first_name": "John",
  "cardholder_last_name": "Doe",
  "cardholder_email": "john.doe@example.com",
  "card_expiry": "12/25",
  "card_type": "Credit",
  "card_scheme": "Visa",
  "card_address": "123 Main Street",
  "card_city": "New York",
  "card_country": "US",
  "card_postal_code": "10001",
  "card_bank": "Bank of America",
  "last_four_digits": "1234",
  "metadata": {}
}

Verify a card

Request

Headers
client_keystringrequired
Example: abcd1234
Bodyapplication/jsonrequired
langstringrequired

The language that should be used

Example: "en"
datastringrequired

A signed JWT containing the card verification input details. Fields to include in the JWT payload:

  • card_request_id: Unique identifier for the card request.
  • value: The verification value.

Example of unsigned payload:

{
  "card_request_id": "550e8400-e29b-41d4-a716-446655440000",
  "value": 10.25
}

Example of 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>"
}
Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkX3JlcXVlc3RfaWQiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJ2YWx1ZSI6MTAuMjV9.JkLNdq8kgMyslN_nupGnEzXrBMmu2_hAaiGpMe42-AE"
curl -i -X POST \
  https://docs.dimepay.net/_mock/openapi-card/cards/verify \
  -H 'Content-Type: application/json' \
  -H 'client_key: YOUR_API_KEY_HERE' \
  -d '{
    "lang": "en",
    "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkX3JlcXVlc3RfaWQiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJ2YWx1ZSI6MTAuMjV9.JkLNdq8kgMyslN_nupGnEzXrBMmu2_hAaiGpMe42-AE"
  }'

Responses

Card verification successful

Bodyapplication/json
entity_idstring(uuid)read-onlyrequired

Unique identifier for the entity associated with the card

Example: "550e8400-e29b-41d4-a716-446655440000"
entity_typestringread-onlyrequired

Type of the entity associated with the card

Enum"MERCHANT""PERSONAL"
Example: "MERCHANT"
tokenstringrequired

Unique token for the card

Example: "card_abcd12345"
card_tokenstringrequired

Token representing the card

Example: "tok_abcdef12345"
currencystringrequired

Currency associated with the card

Enum"USD""JMD""GBP""EUR""TTD""BBD""XCD"
Example: "USD"
cardholder_namestringrequired

Full name of the cardholder

Example: "John Doe"
cardholder_first_namestringrequired

First name of the cardholder

Example: "John"
cardholder_last_namestringrequired

Last name of the cardholder

Example: "Doe"
cardholder_emailstring(email)required

Email address of the cardholder

Example: "john.doe@example.com"
card_expirystringrequired

Expiration date of the card in MM/YY format

Example: "12/25"
card_schemestringrequired

Scheme of the card (e.g., Visa, Mastercard)

Example: "Visa"
card_addressstringrequired

Billing address of the card

Example: "123 Main Street"
card_citystringrequired

City of the billing address

Example: "New York"
card_countrystringrequired

Country of the billing address

Example: "US"
card_postal_codestringrequired

Postal code of the billing address

Example: "10001"
card_bankstring or null

Bank associated with the card

Example: "Bank of America"
last_four_digitsstringrequired

Last four digits of the card number

Example: "1234"
metadataobject

Optional metadata for the card

card_typestringrequired

Type of the card (e.g., Credit, Debit)

Example: "Credit"
token_expiration_datestring(date-time)required

Expiration date of the card token

Example: "2025-12-31T23:59:59Z"
Response
application/json
{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "entity_type": "MERCHANT",
  "token": "card_abcd12345",
  "card_token": "tok_abcdef12345",
  "currency": "USD",
  "cardholder_name": "John Doe",
  "cardholder_first_name": "John",
  "cardholder_last_name": "Doe",
  "cardholder_email": "john.doe@example.com",
  "card_expiry": "12/25",
  "card_scheme": "Visa",
  "card_address": "123 Main Street",
  "card_city": "New York",
  "card_country": "US",
  "card_postal_code": "10001",
  "card_bank": "Bank of America",
  "last_four_digits": "1234",
  "metadata": {},
  "card_type": "Credit",
  "token_expiration_date": "2025-12-31T23:59:59Z"
}

Get card details

Request

Path
tokenstringrequired

Unique token for the card

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6ImNhcmRfMTIzYWJjNDU2eHl6In0.7W3ISpqFnINqpm6QX-8oOn-d5M6ixJHiTTk6W0U_e94
Headers
client_keystringrequired
Example: abcd1234
curl -i -X GET \
  https://docs.dimepay.net/_mock/openapi-card/cards/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6ImNhcmRfMTIzYWJjNDU2eHl6In0.7W3ISpqFnINqpm6QX-8oOn-d5M6ixJHiTTk6W0U_e94 \
  -H 'client_key: YOUR_API_KEY_HERE'

Responses

Card details

Bodyapplication/json
entity_idstring(uuid)read-onlyrequired

Unique identifier for the entity associated with the card

Example: "550e8400-e29b-41d4-a716-446655440000"
entity_typestringread-onlyrequired

Type of the entity associated with the card

Enum"MERCHANT""PERSONAL"
Example: "MERCHANT"
tokenstringrequired

Unique token for the card

Example: "card_abcd12345"
card_tokenstringrequired

Token representing the card

Example: "tok_abcdef12345"
currencystringrequired

Currency associated with the card

Enum"USD""JMD""GBP""EUR""TTD""BBD""XCD"
Example: "USD"
cardholder_namestringrequired

Full name of the cardholder

Example: "John Doe"
cardholder_first_namestringrequired

First name of the cardholder

Example: "John"
cardholder_last_namestringrequired

Last name of the cardholder

Example: "Doe"
cardholder_emailstring(email)required

Email address of the cardholder

Example: "john.doe@example.com"
card_expirystringrequired

Expiration date of the card in MM/YY format

Example: "12/25"
card_schemestringrequired

Scheme of the card (e.g., Visa, Mastercard)

Example: "Visa"
card_addressstringrequired

Billing address of the card

Example: "123 Main Street"
card_citystringrequired

City of the billing address

Example: "New York"
card_countrystringrequired

Country of the billing address

Example: "US"
card_postal_codestringrequired

Postal code of the billing address

Example: "10001"
card_bankstring or null

Bank associated with the card

Example: "Bank of America"
last_four_digitsstringrequired

Last four digits of the card number

Example: "1234"
metadataobject

Optional metadata for the card

card_typestringrequired

Type of the card (e.g., Credit, Debit)

Example: "Credit"
token_expiration_datestring(date-time)required

Expiration date of the card token

Example: "2025-12-31T23:59:59Z"
Response
application/json
{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "entity_type": "MERCHANT",
  "token": "card_abcd12345",
  "card_token": "tok_abcdef12345",
  "currency": "USD",
  "cardholder_name": "John Doe",
  "cardholder_first_name": "John",
  "cardholder_last_name": "Doe",
  "cardholder_email": "john.doe@example.com",
  "card_expiry": "12/25",
  "card_scheme": "Visa",
  "card_address": "123 Main Street",
  "card_city": "New York",
  "card_country": "US",
  "card_postal_code": "10001",
  "card_bank": "Bank of America",
  "last_four_digits": "1234",
  "metadata": {},
  "card_type": "Credit",
  "token_expiration_date": "2025-12-31T23:59:59Z"
}