# 📘 Getting Started

Welcome to **DIME PAY**, your comprehensive payment processing solution! This guide will help you quickly integrate and start using DIME PAY’s powerful APIs to manage orders, payments, cards, transactions, and more. Follow the steps below to get started.

## Table of Contents

1. [Overview](#overview)
2. [Authentication](#authentication)
3. [Integration Steps](#integration-steps)
4. [Core Features](#core-features)
5. [Sandbox Environment](#sandbox-environment)
6. [Error Handling](#error-handling)
7. [Support](#support)


## Overview

DIME PAY provides robust APIs for payment facilitation, enabling you to:

* Process payments securely.
* Manage cards and customer details.
* Handle orders, refunds, and transactions.
* Generate and monitor reports in real time.


### API Base URLs

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


Ensure that you use the appropriate base URL for your environment.

## Authentication

All requests to DIME PAY APIs must include an **API Key** for authentication. Obtain your API Key from the DIME PAY dashboard.

### How to Authenticate

Use the `client_key` header in your requests:


```bash
curl -X GET https://sandbox.api.dimepay.app/dapi/v1/orders \
-H "client_key: your-client-key"
```

# Integration Steps

## 1. Register and Get API Credentials

1. Sign up for a **DIME PAY** account.
2. Navigate to the **Developer** section in the dashboard.
3. Generate your **API Key** and **Sandbox credentials**.


## 2. Test in Sandbox

The sandbox environment allows you to simulate real-world scenarios without affecting production data. Use your **Sandbox API Key** and endpoint `https://sandbox.api.dimepay.com` to safely test all API functionalities.

## 3. Go Live

When you’re ready to move to production:

1. Update your endpoint to `https://api.dimepay.app/dapi/v1`.
2. Replace your **Sandbox API Key** with the **Production API Key**.


# Core Features

## Orders API

**Manage and retrieve order details.**

- **Create an Order**
**Endpoint**: `/orders`
**Method**: `POST`
**Description**: Create a new order with detailed payload including items, billing, and shipping information.
- **Retrieve an Order by Token**
**Endpoint**: `/orders/{token}`
**Method**: `GET`
**Description**: Retrieve details of a specific order using its unique token.


## Cards API

**Store, verify, and retrieve card details.**

- **Vault a Card**
**Endpoint**: `/cards`
**Method**: `POST`
**Description**: Vault a customer’s card securely for future payments.
- **Verify a Card**
**Endpoint**: `/cards/verify`
**Method**: `POST`
**Description**: Verify a card to confirm it’s valid and active.
- **Retrieve Card by Token**
**Endpoint**: `/cards/{token}`
**Method**: `GET`
**Description**: Retrieve details of a specific vaulted card using its token.


## Payments API

**Process payments securely and efficiently.**

- **Create Hosted Payment Page**
**Endpoint**: `/payments/hosted-page`
**Method**: `POST`
**Description**: Create a hosted payment page for customers to complete payments securely.
- **Authorize Payment**
**Endpoint**: `/payments/auth`
**Method**: `POST`
**Description**: Authorize a payment for later capture.
- **Process Payment Sale**
**Endpoint**: `/payments/sale`
**Method**: `POST`
**Description**: Process a payment sale instantly.
- **Capture Authorized Payment**
**Endpoint**: `/payments/capture`
**Method**: `PUT`
**Description**: Capture funds for an authorized payment.
- **Void a Payment**
**Endpoint**: `/payments/void`
**Method**: `PUT`
**Description**: Void a payment that has not been captured.
- **Refund a Payment**
**Endpoint**: `/payments/refund`
**Method**: `PUT`
**Description**: Refund a completed payment.


# Sandbox Environment

The **sandbox environment** simulates real-world payment processing scenarios for development and testing. It’s completely isolated from production, ensuring safe testing.

## Sandbox Base URL

`https://sandbox.api.dimepay.app/dapi/v1`

## Test Credentials

- **Card Number**: `4111 1111 1111 1111`
- **Expiry Date**: `12/25`
- **CVV**: `123`


Use these credentials to simulate successful transactions. For error scenarios, refer to the [Error Handling](#error-handling) section.

# Error Handling

DIME PAY APIs return descriptive error responses to help you debug issues quickly. Below is a list of common error codes and their meanings:

| Error Code | Description |
|  --- | --- |
| 401 | Unauthorized request. Check your API Key. |
| 404 | Resource not found. Verify the endpoint or resource ID. |
| 400 | Bad request. Ensure your payload is correct. |
| 500 | Internal server error. Try again later. |


## Error Response Structure

Every error response includes the following fields:


```json
{
  "code": "error_code",
  "message": "A detailed error message explaining the issue",
  "details": {
    // Additional context for debugging
  }
}
```

# Support

If you need help with integration or encounter issues, reach out to the **DIME PAY Support Team**.

- **Email**: [support@dimepay.net](mailto:support@dimepay.net)
- **Dashboard**: Submit a support request directly through the Developer Dashboard.


Our support team is here to ensure your integration is smooth and successful!