API Reference

Introduction

The E-Merchant API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the E-Merchant API to accept payments, manage customers, handle subscriptions, and more. The API is designed to be flexible and powerful, allowing you to build custom payment experiences for your customers.

Authentication

The E-Merchant API uses API keys to authenticate requests. You can view and manage your API keys in the E-Merchant Dashboard.

The Payments API allows you to create, retrieve, update, and list payments. Payments represent a charge on a customer's payment method.

curl -X POST https://api.e-merchant.com/v1/payments \
-H "Authorization: Bearer sk_live_51Hb9..." \
-H "Content-Type: application/json" \
-d '{
"amount": 2000,
"currency": "usd",
"payment_method": "pm_card_visa",
"customer": "cus_JfGRSfLSWg3Yqy",
"description": "Payment for order #1234"
}'

Request Parameters

Errors

E-Merchant uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided, and codes in the 5xx range indicate an error with E-Merchant's servers.

{
"error": {
"code": "resource_missing",
"message": "The requested resource does not exist",
"param": "id",
"type": "invalid_request_error"
}
}

Rate Limits

The E-Merchant API implements rate limiting to protect against abuse and ensure a consistent experience for all users. Rate limits vary based on the endpoint and your account tier.

Versioning

The E-Merchant API uses versioning to ensure backward compatibility while introducing new features and improvements.

The Customers API allows you to create, retrieve, update, and delete customer records. A customer object stores information about your customer such as their name, email, and payment methods.

curl -X POST https://api.e-merchant.com/v1/customers \
-H "Authorization: Bearer sk_live_51Hb9..." \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"name": "Jenny Rosen",
"phone": "+14155550123",
"metadata": {
  "order_id": "6735"
}
}'

Request Parameters

Payment Methods represent your customer's payment instruments. They can be used with a Customer to make recurring payments or with direct charges.

curl -X POST https://api.e-merchant.com/v1/payment_methods \
-H "Authorization: Bearer sk_live_51Hb9..." \
-H "Content-Type: application/json" \
-d '{
"type": "card",
"card": {
  "number": "4242424242424242",
  "exp_month": 8,
  "exp_year": 2025,
  "cvc": "314"
},
"billing_details": {
  "name": "Jenny Rosen",
  "email": "[email protected]",
  "address": {
    "line1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94111",
    "country": "US"
  }
}
}'

Webhooks

Webhooks allow you to build or set up integrations that subscribe to certain events on your E-Merchant account. When one of those events occurs, we'll send a HTTP POST payload to the webhook's configured URL.

{
"id": "evt_1JKcgU2eZvKYlo2CABCxyz",
"object": "event",
"api_version": "2023-01-01",
"created": 1629323000,
"data": {
"object": {
  "id": "py_1JKbgU2eZvKYlo2CJOBhMxnD",
  "object": "payment",
  "amount": 2000,
  "amount_received": 2000,
  "currency": "usd",
  "customer": "cus_JfGRSfLSWg3Yqy",
  "description": "Payment for order #1234",
  "payment_method": "pm_card_visa",
  "status": "succeeded"
}
},
"type": "payment.succeeded"
}

// Example signature verification in Node.js
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');

return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}

Idempotency

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response.

curl -X POST https://api.e-merchant.com/v1/payments \
-H "Authorization: Bearer sk_live_51Hb9..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 12345678-1234-1234-1234-123456789012" \
-d '{
"amount": 2000,
"currency": "usd",
"payment_method": "pm_card_visa",
"customer": "cus_JfGRSfLSWg3Yqy"
}'

Metadata

Most E-Merchant resources allow you to attach custom key-value data called metadata. You can use metadata to store additional information about a resource in a structured format.

curl -X POST https://api.e-merchant.com/v1/customers \
-H "Authorization: Bearer sk_live_51Hb9..." \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"metadata": {
  "internal_id": "12345",
  "referred_by": "partner_abc",
  "user_segment": "high_value"
}
}'