Dime API Documentation - Orders

Dime API Documentation - Orders (1.0.0)

This API supports functionalities for managing orders within the Dime payment system.

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

Create a new order

Request

Headers
client_keystringrequired
Example: abcd12345
Bodyapplication/jsonrequired
langstringrequired

The language that should be used

Example: "en"
datastringrequired

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

  • currency: Currency of the order.
  • id: Unique order identifier.
  • subtotal: Subtotal of the order.
  • total: Total amount of the order.
  • email: Customer's email.
  • tax: Tax applied to the order.
  • ipAddress: IP address of the customer.
  • fulfillmentStatus: Order's fulfillment status.
  • orderComments: Any comments about the order.
  • discount: Discount applied to the order.
  • items: Array of items in the order.
  • billingPerson: Billing address details.
  • shippingPerson: Shipping address details.
  • referenceTransactionId: Reference to a transaction ID.
  • taxes: Array of tax details.

Example of unsigned payload:

{
  "currency": "USD",
  "id": "XJ12H",
  "subtotal": 1076.64,
  "total": 2014.97,
  "email": "mscott@gmail.com",
  "tax": 488.48,
  "ipAddress": "195.151.247.241",
  "fulfillmentStatus": "AWAITING_PROCESSING",
  "orderComments": "555",
  "discount": 4,
  "items": [
    {
      "id": "xxxx-xxxx-xxxx-xxxx",
      "price": 1060,
      "sku": "ABCA-IAC",
      "quantity": 1,
      "shortDescription": "",
      "name": "iMac",
      "imageUrl": "https://example.com/images/xxxxxx.jpg",
      "selectedOptions": [
        {
          "name": "Color",
          "value": "red",
          "type": "CHOICE"
        }
      ]
    }
  ],
  "billingPerson": {
    "name": "Michael Scott",
    "companyName": "",
    "street": "555 Lackawanna Ave",
    "city": "Scranton",
    "countryCode": "US",
    "countryName": "United States",
    "postalCode": "18508",
    "stateOrProvinceCode": "PA",
    "stateOrProvinceName": "Pennsylvania",
    "phone": ""
  },
  "shippingPerson": {
    "name": "Michael Scott",
    "companyName": "",
    "street": "555 Lackawanna Ave",
    "city": "Scranton",
    "countryCode": "US",
    "countryName": "United States",
    "postalCode": "18508",
    "stateOrProvinceCode": "PA",
    "stateOrProvinceName": "Pennsylvania",
    "phone": ""
  },
  "referenceTransactionId": "transaction_65306446",
  "taxes": [
    {
      "name": "New Tax 2",
      "value": 12,
      "total": 57.1
    }
  ]
}

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.eyJjdXJyZW5jeSI6IlVTRCIsImlkIjoiWEoxMkgifQ.nR2Gh18rL9E7E"
curl -i -X POST \
  https://docs.dimepay.net/_mock/openapi-order/orders \
  -H 'Content-Type: application/json' \
  -H 'client_key: YOUR_API_KEY_HERE' \
  -d '{
    "lang": "en",
    "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXJyZW5jeSI6IlVTRCIsImlkIjoiWEoxMkgifQ.nR2Gh18rL9E7E"
  }'

Responses

Order created successfully

Bodyapplication/json
order_urlstring

URL of the created order

Example: "https://sandbox.dimepay.app/e-order/abcd1234"
Response
application/json
{
  "order_url": "https://sandbox.dimepay.app/e-order/abcd1234"
}

Retrieve an order by token

Request

Path
tokenstringrequired

A signed JWT containing the order token. Fields to include in the JWT payload:

  • token: The order's unique token.

Example of unsigned payload: "order_123abc456xyz" Example of signing the payload:

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

Final request URL: /orders/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6ImNhcmRfMTIzYWJjNDU2eHl6In0.7W3ISpqFnINqpm6QX-8oOn-d5M6ixJHiTTk6W0U_e94

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

Responses

Order retrieved successfully

Bodyapplication/json
idstring(uuid)

Primary key, unique ID for the order

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

Unique token for the order

Example: "order_123abc456xyz"
customer_idstring or null(uuid)

Customer ID associated with the order

Example: "7db04ed8-cffc-4577-8b50-d3e4c95692aa"
customerobject

Customer details as JSON

Example: {"name":"John Doe","email":"johndoe@example.com","phone":"+1234567890"}
statusstring

Current status of the order

Enum"COMPLETE""PENDING""FAILED""REFUNDED""VOIDED"
Example: "COMPLETE"
origin_typestring

Origin of the order

Value"API"
Example: "API"
origin_idstring or null

ID of the origin

Example: "orig_987xyz654abc"
currencystring

Currency for the order

Example: "USD"
productsArray of objects

Products in the order

Example: [{"id":"prod_12345","name":"Laptop","price":1200.5,"quantity":1}]
payment_sourceobject

Payment source details

Example: {"method":"CARD","last4":"4242","brand":"Visa"}
feesobject

Fee details

Example: {"transaction_fee":15,"service_fee":5}
totalnumber(double)

Total amount of the order

Example: 1250.5
subtotalnumber(double)

Subtotal amount of the order

Example: 1200.5
shippingnumber or null(double)

Shipping cost for the order

Example: 50
taxnumber or null(double)

Tax amount for the order

Example: 30
taxValuenumber or null(double)

Tax value for the order

Example: 25
consumer_feenumber or null(double)

Consumer fee for the order

Example: 5
enable_notesboolean

Whether notes are enabled for the order

Example: true
fulfilledboolean

Whether the order has been fulfilled

Example: false
notesstring or null

Notes about the order

Example: "Please deliver by Friday."
metadataobject

Metadata for the order

Example: {"custom_field":"Custom data here"}
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "order_123abc456xyz",
  "customer_id": "7db04ed8-cffc-4577-8b50-d3e4c95692aa",
  "customer": {
    "name": "John Doe",
    "email": "johndoe@example.com",
    "phone": "+1234567890"
  },
  "status": "COMPLETE",
  "origin_type": "API",
  "origin_id": "orig_987xyz654abc",
  "currency": "USD",
  "products": [
    { … }
  ],
  "payment_source": {
    "method": "CARD",
    "last4": "4242",
    "brand": "Visa"
  },
  "fees": {
    "transaction_fee": 15,
    "service_fee": 5
  },
  "total": 1250.5,
  "subtotal": 1200.5,
  "shipping": 50,
  "tax": 30,
  "taxValue": 25,
  "consumer_fee": 5,
  "enable_notes": true,
  "fulfilled": false,
  "notes": "Please deliver by Friday.",
  "metadata": {
    "custom_field": "Custom data here"
  }
}