# Orders

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

**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: abcd12345
```

## Endpoints

### 1. Create a New Order

**POST** `/orders`

#### Headers

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


#### Request Body

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `lang` | string | Yes | The language to use. Example: `en` |
| `data` | string (JWT) | Yes | A signed JWT containing order input details. |


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

- `webhookUrl`: Backend URL to receive payment payload.
- `redirectUrl`: URL to redirect user after successful payment.
- `checkoutUrl`: Checkout page URL.
- `currency`: Currency code.
- `id`: Unique order identifier.
- `subtotal`: Order subtotal.
- `total`: Total order amount.
- `email`: Customer email.
- `tax`: Tax applied.
- `ipAddress`: Customer IP.
- `fulfilled`: Fulfillment status.
- `orderComments`: Comments about the order.
- `discount`: Discount applied.
- `items`: Array of items.
- `billingPerson`: Billing address details.
- `shippingPerson`: Shipping address details.
- `referenceTransactionId`: Reference transaction ID.
- `taxes`: Array of tax details.
- `tokenize`: Enable card tokenization.


#### Example Unsigned Payload

```json
{
  "webhookUrl": "https://webhookurl",
  "redirectUrl": "https://redirectUrl",
  "checkoutUrl": "https://checkoutUrl",
  "tokenize": false,
  "currency": "USD",
  "id": "XJ12H",
  "subtotal": 1076.64,
  "total": 2014.97,
  "email": "mscott@gmail.com",
  "tax": 488.48,
  "ipAddress": "195.151.247.241",
  "fulfilled": true,
  "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",
    "street": "555 Lackawanna Ave",
    "city": "Scranton",
    "countryCode": "US",
    "countryName": "United States",
    "postalCode": "18508",
    "stateOrProvinceCode": "PA",
    "stateOrProvinceName": "Pennsylvania"
  },
  "shippingPerson": {
    "name": "Michael Scott",
    "street": "555 Lackawanna Ave",
    "city": "Scranton",
    "countryCode": "US",
    "countryName": "United States",
    "postalCode": "18508",
    "stateOrProvinceCode": "PA",
    "stateOrProvinceName": "Pennsylvania"
  },
  "referenceTransactionId": "transaction_65306446",
  "taxes": [
    {
      "name": "New Tax 2",
      "value": 12,
      "total": 57.1
    }
  ]
}
```

#### 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)

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

### 2. Retrieve an Order by Token

**GET** `/orders/{token}`

#### Headers

- `client_key` (string, required)


#### Path Parameters

- `token` (string, required, JWT) – Signed JWT containing the order token.


**Unsigned payload example:**

```
order_123abc456xyz
```

**Signed payload example:**

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

**Final request URL:**

```
/orders/<signed_jwt_token>
```

#### Response (200)

```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": [
    {
      "id": "prod_12345",
      "name": "Laptop",
      "price": 1200.50,
      "quantity": 1
    }
  ],
  "payment_source": {
    "method": "CARD",
    "last4": "4242",
    "brand": "Visa",
    "card_token": "card_FJe234Ajasd"
  },
  "fees": {
    "transaction_fee": 15.00,
    "service_fee": 5.00
  },
  "total": 1250.50,
  "subtotal": 1200.50,
  "shipping": 50.00,
  "tax": 30.00,
  "taxValue": 25.00,
  "consumer_fee": 5.00,
  "enable_notes": true,
  "fulfilled": false,
  "notes": "Please deliver by Friday.",
  "metadata": {
    "custom_field": "Custom data here"
  }
}
```

For tokenization on sale card_token will be available on the payment_source.

```
"card_token": "card_FJe234Ajasd"
```

## Security

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

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

## Node.js Examples

### Create a New Order

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

const clientKey = 'abcd12345';
const payload = {
  webhookUrl: 'https://webhookurl',
  redirectUrl: 'https://redirectUrl',
  checkoutUrl: 'https://checkoutUrl',
  currency: 'USD',
  id: 'XJ12H',
  subtotal: 1076.64,
  total: 2014.97,
  email: 'mscott@gmail.com'
  // ... other fields
};

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

async function createOrder() {
  try {
    const response = await axios.post('https://sandbox.api.dimepay.app/dapi/v1/orders', {
      lang: 'en',
      data: signedData
    }, {
      headers: { client_key: clientKey }
    });

    console.log('Order URL:', response.data.order_url);
  } catch (error) {
    console.error('Error creating order:', error.response?.data || error.message);
  }
}

createOrder();
```

### Retrieve an Order by Token

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

const clientKey = 'abcd12345';
const tokenPayload = 'order_123abc456xyz';

// Sign the token payload
const signedToken = jwt.sign({ token: tokenPayload }, 'your_secret_key');

async function getOrder() {
  try {
    const response = await axios.get(`https://sandbox.api.dimepay.app/dapi/v1/orders/${signedToken}`, {
      headers: { client_key: clientKey }
    });

    console.log('Order Data:', response.data);
  } catch (error) {
    console.error('Error retrieving order:', error.response?.data || error.message);
  }
}

getOrder();
```