# First API request

Now that your Sandbox API credentials are ready, you can make your first authenticated request using the KwikPaisa Payment Gateway APIs.

In this guide, you will:

* Create your first payment order
* Generate authentication headers
* Send an authenticated API request
* Receive a hosted checkout payment link

Before continuing, ensure you have already completed:

* Account onboarding
* Sandbox credential generation
* Authentication setup

Recommended prerequisites:

➡️ [Generate API Credentials](/v3-guide/quick-start/generate-api-keys.md)\
➡️ [Authentication → Headers](/v3-guide/authentication/headers.md)\
➡️ [Authentication → Timestamp](/v3-guide/authentication/timestamp.md)\
➡️ [Authentication → Signature](/v3-guide/authentication/signature.md)

***

## Create Your First Payment Order

The Create Order API generates a hosted checkout session and returns a secure payment link that can be shared with customers.

Example request payload:

```json
{
  "order_id": 6116229263036,
  "order_amount": 105,
  "order_currency": "INR",
  "order_note": "Additional order info",
  "service_type": "DIGITAL",
  "customer": {
    "name": "Ajay",
    "email": "developer@jangras.co",
    "phone": "9816512345",
    "address": {
      "line1": "Capital Office, Kemp House",
      "line2": "152 - 160 City Road",
      "city": "London",
      "state": "London",
      "country": "UK",
      "postal_code": "EC1V 2NX"
    }
  },
  "return_url": "https://merchant.in/process_return.php?order_id=order_1626945143520"
}
```

## Generate Authentication Headers

Before sending the request:

1. Generate a UNIX timestamp
2. Generate the HMAC SHA256 signature
3. Attach authentication headers

Required authentication headers:

➡️ [Authentication → Headers](/v3-guide/authentication/headers.md)\
➡️ [Authentication → Timestamp](/v3-guide/authentication/timestamp.md)\
➡️ [Authentication → Signature](/v3-guide/authentication/signature.md)

## Send Your First API Request

Example cURL request:

```json
curl --request POST \
--url https://sandbox.kwikpaisa.com/api/v3/pg/order/create \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-API-KEY: YOUR_API_KEY" \
--header "X-SIGNATURE: GENERATED_SIGNATURE" \
--header "X-TIMESTAMP: GENERATED_TIMESTAMP" \
--data '{
  "order_id": 6116229263036,
  "order_amount": 105,
  "order_currency": "INR",
  "order_note": "Additional order info",
  "service_type": "DIGITAL",
  "customer": {
    "name": "Ajay",
    "email": "developer@jangras.co",
    "phone": "9816512345"
  },
  "return_url": "https://merchant.in/process_return.php?order_id=order_1626945143520"
}'
```

***

## Example Success Response

```json
{
  "code": "200",
  "status": "success",
  "message": "API authentication successful!",
  "return_data": {
    "kwikX_order_id": "kp_40dec464-7155-43a3-855d-c95c5ab1be71",
    "created_at": "13-05-2026 08:34 AM",
    "order_id": 3501946751751,
    "order_status": "UN_PAID",
    "payment_link": "https://sandbox.kwikpaisa.com/payment/pay_TSN7ASUDmzcZNyH8qLeG8PrR4CWB9pwFQOuDPYia0fd5k2fMzN"
  }
}
```

***

## Redirect Customer to Hosted Checkout

Use the returned:

```
payment_link
```

to redirect customers to the KwikPaisa Hosted Checkout page.

Example:

```
window.location.href = payment_link;
```

Customers can then complete payment securely using the hosted payment interface.

***

## Verify Payment Status

After payment completion:

* Verify payment status server-side
* Use the Order Status API
* Validate webhook notifications
* Reconcile transaction records

Recommended references:

➡️ [Payment Gateway → Order Status API](/v3-guide/payment-gateway-integration/create-order.md)\
➡️ [Webhooks → Webhook Setup](/v3-guide/webhooks/webhook-setup.md)\
➡️ [Webhooks → Signature Verification](/v3-guide/webhooks/signature-verification.md)

***

## Recommended Integration Flow

1. [Generate API credentials](/v3-guide/quick-start/generate-api-keys.md)
2. [Configure authentication](/v3-guide/authentication/headers.md)
3. [Create payment order](/v3-guide/payment-gateway-integration/create-order.md)
4. [Redirect customer to hosted checkout](/v3-guide/payment-gateway-integration/redirect-user.md)
5. [Verify payment status](/v3-guide/payment-gateway-integration/check-status.md)
6. [Process webhook events](/v3-guide/webhooks/webhook-setup.md)
7. Reconcile transaction

***

## Common Integration Errors

| Error                 | Possible Reason                |
| --------------------- | ------------------------------ |
| Invalid Signature     | Incorrect signature generation |
| Expired Timestamp     | Reused or old timestamp        |
| Authentication Failed | Invalid API credentials        |
| Invalid Payload       | Incorrect request structure    |

***

## Production Recommendations

Before moving to production:

* Complete Sandbox testing
* Validate webhook verification
* Implement retry handling
* Enable secure backend signature generation
* Verify transaction reconciliation workflows

Recommended references:

➡️ Sandbox Testing\
➡️ [Retry Logic](/v3-guide/error-handling/retry-logic.md)\
➡️ [Security Checks](/v3-guide/going-live/security-checks.md)\
➡️ [Production Checklist](/v3-guide/going-live/production-checklist.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.kwikpaisa.com/v3-guide/quick-start/first-api-request.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.