Tachles Pay Documentation

Complete API reference for integrating payment processing with your application. Tachles Pay provides a unified hub for managing payment flows, webhooks, and transaction data.

🎯

Simple Integration

Just 3 API calls to process a payment end-to-end.

🔄

Real-time Webhooks

Get instant notifications on your server.

🚀 Quick Start

Get started with Tachles Pay in 5 minutes. Here's the complete payment flow:

Create an App

Go to your dashboard and create a new app. You'll receive an API key and webhook secret.

Create a Payment (Payup)

When a user wants to pay, create a payment session:

bash

curl -X POST https://your-domain.com/api/payups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2999,
    "currency": "USD",
    "description": "Premium Plan",
    "customerId": "user_123",
    "returnUrl": "https://yoursite.com/success",
    "cancelUrl": "https://yoursite.com/cancel"
  }'

Redirect User

Use the returned paymentUrl to redirect your user to complete the payment.

Receive Webhook

Your server receives a webhook notification when payment completes. Verify the signature!

Finalize & Deliver

Finalize the payment and deliver your product/service to the customer.

🔐 Authentication

All API requests require authentication using your API key in the Authorization header.

bash

Authorization: Bearer pk_live_abc123xyz789...

⚠️

Keep your API key secure! Never expose it in client-side code. Use environment variables and server-side requests only.

API Keys

Type	Format	Usage
`API Key`	pk_live_...	Server-to-server authentication
`Webhook Secret`	whsec_...	Verify webhook signatures

💳 Create Payment

Create a new payment session (called a "Payup") to collect payment from a customer.

POST/api/payups

Request Body

Parameter	Type	Required	Description
`amount`	integer	Yes	Amount in cents (e.g., 2999 = $29.99)
`currency`	string	Yes	Currency code: USD, EUR, GBP, ILS
`description`	string	No	Payment description shown to user
`customerId`	string	No	Your internal customer ID
`customerEmail`	string	No	Customer email for receipts
`customerName`	string	No	Customer display name
`returnUrl`	string	No	Redirect URL after success
`cancelUrl`	string	No	Redirect URL on cancel
`metadata`	object	No	Custom key-value data

Example Request

json

{
  "amount": 2999,
  "currency": "USD",
  "description": "Premium Subscription",
  "customerId": "user_abc123",
  "customerEmail": "customer@example.com",
  "returnUrl": "https://yourapp.com/payment/success",
  "cancelUrl": "https://yourapp.com/payment/cancel",
  "metadata": {
    "planId": "premium",
    "orderId": "ord_123"
  }
}

Response

json

{
  "payupId": "pay_abc123xyz789",
  "paymentUrl": "https://your-domain.com/checkout/pay_abc123xyz789",
  "expiresAt": "2025-12-02T15:30:00.000Z"
}

📊 Payment Status

Check the current status of a payment session.

GET/api/sessions/{id}

Status Values

Status	Description
`pending`	Payment created, waiting for customer
`processing`	Customer initiated payment, processing
`completed`	Payment successful
`failed`	Payment failed or declined
`cancelled`	Customer cancelled the payment
`expired`	Payment session expired (24h default)

Example Response

json

{
  "id": "pay_abc123xyz789",
  "status": "completed",
  "amount": 2999,
  "currency": "USD",
  "customerEmail": "customer@example.com",
  "description": "Premium Subscription",
  "createdAt": "2025-12-02T14:30:00.000Z",
  "completedAt": "2025-12-02T14:35:00.000Z",
  "metadata": {
    "planId": "premium",
    "orderId": "ord_123"
  }
}

🔔 Webhooks

Webhooks notify your server in real-time when payment events occur. Always verify webhook signatures before processing.

💡

Configure your webhook URL in the dashboard under Apps → Webhook Configuration. Your server must respond with a 200 status within 30 seconds.

Signature Verification

Every webhook includes a signature in the X-Tachles-Signature header.

typescript

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler:
app.post('/webhooks/tachles', (req, res) => {
  const signature = req.headers['x-tachles-signature'];
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook...
  const { event, data } = req.body;
  
  switch (event) {
    case 'payment.completed':
      // Fulfill the order
      break;
    case 'payment.failed':
      // Handle failure
      break;
  }
  
  res.status(200).send('OK');
});

Webhook Events

Event	Description
`payment.completed`	Payment was successful
`payment.failed`	Payment failed or was declined
`payment.cancelled`	Customer cancelled the payment
`payment.expired`	Payment session expired
`payment.refunded`	Payment was refunded

Webhook Payload

json

{
  "event": "payment.completed",
  "timestamp": "2025-12-02T14:35:00.000Z",
  "data": {
    "payupId": "pay_abc123xyz789",
    "transactionId": "txn_def456uvw012",
    "amount": 2999,
    "currency": "USD",
    "status": "completed",
    "customerEmail": "customer@example.com",
    "customerId": "user_abc123",
    "metadata": {
      "planId": "premium",
      "orderId": "ord_123"
    }
  }
}

✅ Finalize Payment

After receiving a successful webhook, finalize the payment to confirm completion and create a permanent transaction record.

POST/api/sessions/{id}/finalize

✅

Finalizing a payment is idempotent - you can safely call it multiple times. This creates a Transaction record from the Payup and returns the final details.

Example Response

json

{
  "success": true,
  "transaction": {
    "id": "txn_def456uvw012",
    "payupId": "pay_abc123xyz789",
    "amount": 2999,
    "currency": "USD",
    "status": "completed",
    "customerEmail": "customer@example.com",
    "customerId": "user_abc123",
    "fees": 87,
    "netAmount": 2912,
    "createdAt": "2025-12-02T14:35:00.000Z"
  }
}

⚠️ Error Handling

All errors follow a consistent format with an error code and message.

json

{
  "error": "ValidationError",
  "message": "Amount must be a positive integer"
}

HTTP Status Codes

Code	Description
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`404`	Not Found - Resource doesn't exist
`422`	Unprocessable - Validation failed
`429`	Too Many Requests - Rate limited
`500`	Server Error - Something went wrong

Error Types

Error	Description
`AuthenticationError`	Invalid or missing API key
`ValidationError`	Request validation failed
`NotFoundError`	Resource not found
`PayupExpiredError`	Payment session has expired
`PayupAlreadyCompletedError`	Payment already processed
`InternalError`	Server error (retry safe)

Need help? Contact us at support@tachlespay.com

Live Demo Home