API Reference

Complete documentation for integrating with the E-Merchant payment gateway

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.

Base URL

https://api.e-merchant.com/v1

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

API Versions

The current version of the API is v1. We recommend explicitly versioning all API requests.

Stable API

We maintain backward compatibility and provide deprecation notices.

Versioned Changes

Major changes are released as new API versions.

Authentication

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

Authentication should only be performed server-side

Your API keys carry many privileges, so be sure to keep them secure. Do not share your secret API keys in publicly accessible areas.

Bearer Authentication

Authenticate your API requests by including your API key in the Authorization header:

Authorization: Bearer sk_live_51Hb9...

Replace sk_live_51Hb9... with your actual API key.

HMAC Authentication

For enhanced security, you can use HMAC-based authentication. Generate a signature using your secret key and include it in the request header:

X-E-Merchant-Signature: sha256=computed_signature

HMAC authentication is recommended for webhook verification and high-security endpoints.

Payments

POST

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

/v1/payments POST

Create a new payment

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"
}'
{
  "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",
  "created": 1629323000
}

Request Parameters

Parameter Type Required Description
amount integer Yes Amount in cents to be charged
currency string Yes Three-letter ISO currency code
payment_method string Yes ID of the payment method to be used
customer string No ID of the customer this payment belongs to
description string No Description of the payment

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.

Code Description
200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
402 - Request Failed The parameters were valid but the request failed.
403 - Forbidden The API key doesn't have permissions to perform the request.
404 - Not Found The requested resource doesn't exist.
429 - Too Many Requests Too many requests hit the API too quickly.
500 - Server Errors Something went wrong on E-Merchant's end.

Error Response Format

{
  "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.

Default Rate Limits

  • Standard tier: 100 requests per minute
  • Premium tier: 500 requests per minute
  • Enterprise tier: Custom limits based on your needs

Rate Limit Headers

All API responses include headers that provide information about your current rate limit status:

Header Description
X-RateLimit-Limit The maximum number of requests you're permitted to make per minute.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.

Versioning

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

Current Versions

Current v1 Released January 2023
Legacy v0 Deprecated, support ends December 2024

Specifying API Version

You can specify the API version in one of three ways:

  1. URL path prefix (recommended):
    https://api.e-merchant.com/v1/payments
  2. Accept header:
    Accept: application/json; version=1
  3. Custom header:
    X-E-Merchant-Version: 1

Customers

POST GET

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.

/v1/customers POST

Create a new customer

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"
  }
}'
{
  "id": "cus_JfGRSfLSWg3Yqy",
  "object": "customer",
  "email": "[email protected]",
  "name": "Jenny Rosen",
  "phone": "+14155550123",
  "metadata": {
    "order_id": "6735"
  },
  "created": 1629323000
}

Request Parameters

Parameter Type Required Description
email string No Customer's email address
name string No Customer's full name
phone string No Customer's phone number
metadata object No Set of key-value pairs for storing additional information

Payment Methods

POST

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

/v1/payment_methods POST

Create a new payment method

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"
    }
  }
}'
{
  "id": "pm_1JKbgU2eZvKYlo2C",
  "object": "payment_method",
  "type": "card",
  "card": {
    "brand": "visa",
    "last4": "4242",
    "exp_month": 8,
    "exp_year": 2025
  },
  "billing_details": {
    "name": "Jenny Rosen",
    "email": "[email protected]"
  },
  "created": 1629323000
}

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.

Common Webhook Events

  • payment.succeeded: A payment was successfully processed
  • payment.failed: A payment attempt failed
  • customer.created: A new customer was created
  • customer.updated: Customer information was updated
  • refund.created: A refund was issued
  • dispute.created: A payment was disputed by the customer
Example Webhook Payload

This is an example of a payment.succeeded webhook event

{
  "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"
}

Securing Webhooks

For security, you should verify that the webhook was sent by E-Merchant by checking the signature. We include a signature in the X-E-Merchant-Signature header of each webhook.

// 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.

Using Idempotency Keys

To perform an idempotent request, provide an additional Idempotency-Key header with a unique key value.

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"
}'

Idempotency Key Guidelines

Use UUIDs

We recommend using UUID v4 for idempotency keys.

Key Expiration

Idempotency keys expire after 24 hours.

Key per Request

Use a unique key for each distinct request/intent, not just each API call.

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.

Using Metadata

Metadata is useful for storing additional, structured information on an object. For example, you could store your user's full name and their corresponding unique identifier from your system on a Customer object.

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"
  }
}'

Metadata Limitations

  • You can specify up to 50 keys, with key names up to 40 characters long.
  • Each metadata value can be up to 500 characters long.
  • Metadata is not searchable via the API—it's for your own use only.
  • Only use strings, numbers, and booleans in metadata. Nested objects are not supported.