> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paytring.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transformation Layer

> Preview changes locally to update your docs

# Transformation Layer API's

The Transformation Layer enables merchants to integrate with Paytring using API formats they're already familiar with from other payment gateways. This eliminates the need for code changes when migrating from Razorpay, PayU, Pinelabs, Cashfree, or Worldline.

## Overview

| Gateway                 | Authentication                    | Endpoints                        | Features                      |
| ----------------------- | --------------------------------- | -------------------------------- | ----------------------------- |
| [Razorpay](#razorpay)   | Hash-based (V1) / Basic Auth (V2) | Create, Fetch                    | Order creation & status       |
| [PayU](#payu)           | Hash-based (V1) / Basic Auth (V2) | Create, Fetch                    | Order creation & status       |
| [Pinelabs](#pinelabs)   | Hash-based (V1) / Basic Auth (V2) | Create, Fetch                    | Order creation & status       |
| [Cashfree](#cashfree)   | Header-based (x-client-id/secret) | Create, Fetch, Payments, Refunds | Full order & refund lifecycle |
| [Worldline](#worldline) | None (V1) / Basic Auth (V2)       | Create                           | Order creation                |

***

## Authentication Methods

### V1 - Hash-based Authentication

Used by: Razorpay, PayU, Pinelabs

Include in request body:

```json theme={null}
{
  "key": "your_paytring_api_key",
  "hash": "sha512_hash_of_params"
}
```

**Hash Calculation:**

1. Sort all request parameters alphabetically by key
2. Concatenate values with `|` separator
3. Append `|` + API secret
4. Generate SHA512 hash

See [Hash Documentation](./hash.md) for details.

### V2 - Basic Authentication

Used by: Razorpay, PayU, Pinelabs, Worldline

Include HTTP header:

```
Authorization: Basic base64(api_key:api_secret)
```

### Cashfree-style Header Authentication

Used by: Cashfree

Include HTTP headers:

```
x-client-id: your_paytring_api_key
x-client-secret: your_paytring_api_secret
x-api-version: 2023-08-01 (optional)
```

***

## Razorpay

Emulates Razorpay's order API format.

### Create Order

**V2 Endpoint:** `POST /api/v2/order/via/rzp/create`

#### Request

```json theme={null}
{
  "amount": 50000,
  "currency": "INR",
  "receipt": "receipt_123",
  "notes": {
    "key1": "value1"
  }
}
```

| Field      | Type    | Required | Description                          |
| ---------- | ------- | -------- | ------------------------------------ |
| `amount`   | integer | Yes      | Amount in paise (e.g., 50000 = ₹500) |
| `currency` | string  | Yes      | Currency code (INR)                  |
| `receipt`  | string  | Yes      | Unique receipt/order identifier      |
| `notes`    | object  | No       | Additional metadata                  |

#### Response

```json theme={null}
{
  "id": "order_ABC123",
  "entity": "order",
  "amount": 50000,
  "currency": "INR",
  "receipt": "receipt_123",
  "status": "created",
  "created_at": 1234567890
}
```

### Fetch Order

**V2 Endpoint:** `POST /api/v2/order/via/rzp/fetch`

#### Request

```json theme={null}
{
  "order_id": "order_ABC123"
}
```

#### Response

```json theme={null}
{
  "id": "order_ABC123",
  "entity": "order",
  "amount": 50000,
  "amount_paid": 50000,
  "amount_due": 0,
  "currency": "INR",
  "receipt": "receipt_123",
  "status": "paid",
  "created_at": 1234567890
}
```

***

## PayU

Emulates PayU's order API format.

### Create Order

**V2 Endpoint:** `POST /api/v2/order/via/payu/create`

#### Request

```json theme={null}
{
  "txnid": "TXN123456",
  "amount": "500.00",
  "productinfo": "Product Description",
  "firstname": "John",
  "email": "john@example.com",
  "phone": "9876543210",
  "surl": "https://merchant.com/success",
  "furl": "https://merchant.com/failure"
}
```

| Field         | Type   | Required | Description                       |
| ------------- | ------ | -------- | --------------------------------- |
| `txnid`       | string | Yes      | Unique transaction ID             |
| `amount`      | string | Yes      | Amount in rupees (e.g., "500.00") |
| `productinfo` | string | Yes      | Product/order description         |
| `firstname`   | string | Yes      | Customer first name               |
| `email`       | string | Yes      | Customer email                    |
| `phone`       | string | Yes      | Customer phone                    |
| `surl`        | string | Yes      | Success callback URL              |
| `furl`        | string | Yes      | Failure callback URL              |

#### Response

```json theme={null}
{
  "status": 1,
  "msg": "Order Created",
  "result": {
    "txnid": "TXN123456",
    "order_id": "order_ABC123",
    "payment_url": "https://paytring.com/pay/..."
  }
}
```

### Fetch Order

**V2 Endpoint:** `POST /api/v2/order/via/payu/fetch`

#### Request

```json theme={null}
{
  "txnid": "TXN123456"
}
```

#### Response

```json theme={null}
{
  "status": 1,
  "result": {
    "txnid": "TXN123456",
    "amount": "500.00",
    "status": "success",
    "mode": "CC",
    "bank_ref_num": "123456789"
  }
}
```

***

## Pinelabs

Emulates Pinelabs' order API format.

### Create Order

**V2 Endpoint:** `POST /api/v2/order/via/pinelabs/create`

#### Request

```json theme={null}
{
  "merchant_txn_id": "PINE123456",
  "amount": 50000,
  "currency": "INR",
  "customer_name": "John Doe",
  "customer_email": "john@example.com",
  "customer_mobile": "9876543210",
  "callback_url": "https://merchant.com/callback"
}
```

| Field             | Type    | Required | Description           |
| ----------------- | ------- | -------- | --------------------- |
| `merchant_txn_id` | string  | Yes      | Unique transaction ID |
| `amount`          | integer | Yes      | Amount in paise       |
| `currency`        | string  | Yes      | Currency code         |
| `customer_name`   | string  | No       | Customer name         |
| `customer_email`  | string  | No       | Customer email        |
| `customer_mobile` | string  | No       | Customer phone        |
| `callback_url`    | string  | Yes      | Webhook callback URL  |

#### Response

```json theme={null}
{
  "response_code": 1,
  "response_message": "SUCCESS",
  "ppc_MerchantTxnId": "PINE123456",
  "ppc_PinelabsTxnId": "order_ABC123",
  "redirect_url": "https://paytring.com/pay/..."
}
```

### Fetch Order

**V2 Endpoint:** `POST /api/v2/order/via/pinelabs/fetch`

#### Request

```json theme={null}
{
  "merchant_txn_id": "PINE123456"
}
```

#### Response

```json theme={null}
{
  "response_code": 1,
  "response_message": "SUCCESS",
  "ppc_MerchantTxnId": "PINE123456",
  "ppc_Amount": 50000,
  "ppc_TxnStatus": "SUCCESS",
  "ppc_PaymentMode": "CREDIT_CARD"
}
```

***

## Cashfree

Emulates Cashfree's PG API format with full order and refund lifecycle support.

### Create Order

**V2 Endpoint:** `POST /api/v2/pg/via/cashfree/orders`

#### Request

```json theme={null}
{
  "order_id": "CF_ORDER_123",
  "order_amount": 500.50,
  "order_currency": "INR",
  "customer_details": {
    "customer_id": "cust_123",
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "customer_phone": "9876543210"
  },
  "order_meta": {
    "return_url": "https://merchant.com/return?order_id={order_id}",
    "notify_url": "https://merchant.com/webhook"
  },
  "order_note": "Test order"
}
```

| Field                             | Type   | Required | Description                              |
| --------------------------------- | ------ | -------- | ---------------------------------------- |
| `order_id`                        | string | Yes      | Unique order identifier                  |
| `order_amount`                    | number | Yes      | Amount in rupees (decimal, e.g., 500.50) |
| `order_currency`                  | string | Yes      | Currency code (INR)                      |
| `customer_details.customer_id`    | string | Yes      | Customer identifier                      |
| `customer_details.customer_name`  | string | No       | Customer name                            |
| `customer_details.customer_email` | string | Yes      | Customer email                           |
| `customer_details.customer_phone` | string | Yes      | Customer phone (10 digits)               |
| `order_meta.return_url`           | string | No       | Return URL after payment                 |
| `order_meta.notify_url`           | string | No       | Webhook notification URL                 |
| `order_note`                      | string | No       | Order description                        |

#### Response

```json theme={null}
{
  "cf_order_id": "order_ABC123",
  "order_id": "CF_ORDER_123",
  "order_status": "ACTIVE",
  "order_token": "token_xyz",
  "order_amount": 500.50,
  "order_currency": "INR",
  "payment_session_id": "session_abc",
  "payments": {
    "url": "https://api.paytring.com/api/v1/pg/via/cashfree/orders/order_ABC123/payments"
  },
  "refunds": {
    "url": "https://api.paytring.com/api/v1/pg/via/cashfree/orders/order_ABC123/refunds"
  }
}
```

### Fetch Order

**V2 Endpoint:** `GET /api/v2/pg/via/cashfree/orders/{order_id}`

#### Response

```json theme={null}
{
  "cf_order_id": "order_ABC123",
  "order_id": "CF_ORDER_123",
  "order_status": "PAID",
  "order_amount": 500.50,
  "order_currency": "INR",
  "customer_details": {
    "customer_id": "cust_123",
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "customer_phone": "9876543210"
  },
  "created_at": "2024-01-15T10:30:00+05:30"
}
```

**Order Status Values:**

| Status    | Description                     |
| --------- | ------------------------------- |
| `ACTIVE`  | Order created, awaiting payment |
| `PAID`    | Payment successful              |
| `EXPIRED` | Order expired or payment failed |

### Get Order Payments

**V2 Endpoint:** `GET /api/v2/pg/via/cashfree/orders/{order_id}/payments`

#### Response

```json theme={null}
[
  {
    "cf_payment_id": "pay_123",
    "order_id": "CF_ORDER_123",
    "payment_status": "SUCCESS",
    "payment_amount": 500.50,
    "payment_currency": "INR",
    "payment_method": {
      "card": {
        "card_network": "VISA",
        "card_type": "CREDIT_CARD",
        "card_last4": "1234"
      }
    },
    "payment_time": "2024-01-15T10:35:00+05:30",
    "bank_reference": "123456789"
  }
]
```

### Create Refund

**V2 Endpoint:** `POST /api/v2/pg/via/cashfree/orders/{order_id}/refunds`

#### Request

```json theme={null}
{
  "refund_id": "refund_123",
  "refund_amount": 100.00,
  "refund_note": "Customer requested refund"
}
```

| Field           | Type   | Required | Description              |
| --------------- | ------ | -------- | ------------------------ |
| `refund_id`     | string | Yes      | Unique refund identifier |
| `refund_amount` | number | Yes      | Refund amount in rupees  |
| `refund_note`   | string | No       | Reason for refund        |

#### Response

```json theme={null}
{
  "cf_refund_id": "rf_ABC123",
  "refund_id": "refund_123",
  "order_id": "CF_ORDER_123",
  "refund_status": "PENDING",
  "refund_amount": 100.00,
  "refund_currency": "INR",
  "created_at": "2024-01-15T11:00:00+05:30"
}
```

### List Refunds

**V2 Endpoint:** `GET /api/v2/pg/via/cashfree/orders/{order_id}/refunds`

#### Response

```json theme={null}
[
  {
    "cf_refund_id": "rf_ABC123",
    "refund_id": "refund_123",
    "refund_status": "SUCCESS",
    "refund_amount": 100.00,
    "created_at": "2024-01-15T11:00:00+05:30"
  }
]
```

### Fetch Refund

**V2 Endpoint:** `GET /api/v2/pg/via/cashfree/orders/{order_id}/refunds/{refund_id}`

#### Response

```json theme={null}
{
  "cf_refund_id": "rf_ABC123",
  "refund_id": "refund_123",
  "order_id": "CF_ORDER_123",
  "refund_status": "SUCCESS",
  "refund_amount": 100.00,
  "refund_currency": "INR",
  "refund_note": "Customer requested refund",
  "created_at": "2024-01-15T11:00:00+05:30",
  "processed_at": "2024-01-15T11:05:00+05:30"
}
```

**Refund Status Values:**

| Status      | Description                   |
| ----------- | ----------------------------- |
| `PENDING`   | Refund initiated              |
| `SUCCESS`   | Refund processed successfully |
| `CANCELLED` | Refund cancelled              |

***

## Worldline

Emulates Worldline's order creation API.

### Create Order

**V2 Endpoint:** `POST /api/v2/order/via/worldline/create` (Basic Auth)

#### Request

```json theme={null}
{
  "merchant_id": "MID123",
  "order_id": "WL_ORDER_123",
  "amount": "500.00",
  "currency": "INR",
  "customer_name": "John Doe",
  "customer_email": "john@example.com",
  "customer_phone": "9876543210",
  "return_url": "https://merchant.com/return"
}
```

| Field            | Type   | Required | Description              |
| ---------------- | ------ | -------- | ------------------------ |
| `merchant_id`    | string | Yes      | Merchant identifier      |
| `order_id`       | string | Yes      | Unique order ID          |
| `amount`         | string | Yes      | Amount in rupees         |
| `currency`       | string | Yes      | Currency code            |
| `customer_name`  | string | No       | Customer name            |
| `customer_email` | string | No       | Customer email           |
| `customer_phone` | string | No       | Customer phone           |
| `return_url`     | string | Yes      | Return URL after payment |

#### Response

```json theme={null}
{
  "status": "SUCCESS",
  "order_id": "WL_ORDER_123",
  "paytring_order_id": "order_ABC123",
  "payment_url": "https://paytring.com/pay/..."
}
```

***

## Error Responses

All endpoints return consistent error responses:

### Validation Error (400)

```json theme={null}
{
  "status": "ERROR",
  "code": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "errors": {
    "amount": ["Amount is required"],
    "email": ["Invalid email format"]
  }
}
```

### Authentication Error (401)

```json theme={null}
{
  "status": "ERROR",
  "code": "AUTHENTICATION_FAILED",
  "message": "Invalid API credentials"
}
```

### Not Found (404)

```json theme={null}
{
  "status": "ERROR",
  "code": "ORDER_NOT_FOUND",
  "message": "Order not found"
}
```

### Server Error (500)

```json theme={null}
{
  "status": "ERROR",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred"
}
```

***

## Migration Guide

### From Razorpay

1. Replace base URL: `https://api.razorpay.com/v1` → `https://api.paytring.com/api/v2/order/via/rzp`
2. Update authentication to use Paytring API credentials
3. No changes needed to request/response handling

### From PayU

1. Replace endpoint: PayU's endpoint → `https://api.paytring.com/api/v2/order/via/payu`
2. Update `key` and `salt` to Paytring credentials
3. Hash calculation remains the same

### From Pinelabs

1. Replace base URL → `https://api.paytring.com/api/v2/order/via/pinelabs`
2. Use Paytring API credentials
3. Response format remains compatible

### From Cashfree

1. Replace base URL: `https://api.cashfree.com/pg` → `https://api.paytring.com/api/v2/pg/via/cashfree`
2. Update `x-client-id` and `x-client-secret` headers with Paytring credentials
3. All endpoints and response formats remain compatible

***

## Rate Limits

| Endpoint Type     | Limit               |
| ----------------- | ------------------- |
| Create Order      | 100 requests/minute |
| Fetch Order       | 300 requests/minute |
| Refund Operations | 50 requests/minute  |

***

## Support

For integration support or issues:

* Email: [support@paytring.com](mailto:support@paytring.com)
* Documentation: [https://docs.paytring.com](https://docs.paytring.com)