Appearance

Quick Start ​

1. Base URL & Auth ​

Send HTTPS requests to the sandbox or production base URL with an Authorization header using an API key (api_***), and Content-Type: application/json.

TIP

Public keys (pub_***) are client-side only.

http
Authorization: api_xxx...
Content-Type: application/json

💡 Every response includes x-correlation-id for tracing/debugging.

2. Your First Charge (Sale) ​

Endpoint: POST /api/transaction
Minimum useful fields: type, amount (in cents), and one payment_method (e.g., card). Amounts like $12.99 must be sent as 1299.

Request:

3. Idempotency (Duplicate Protection) ​

Add idempotency_key (UUID) to safely retry a request; TTL defaults to 5 minutes unless you pass idempotency_time (seconds) or have a merchant default.

4. Common Flows ​

Sale ​

Authorize and Capture in single call:

Auth → Capture ​

Authorize now, capture later:

Capture when you’re ready:

http
POST /api/transaction/{transactionId}/capture

You can optionally pass amount, tax_amount, etc. in the body.

Void / Auth Reversal ​

Void a transaction that’s pending settlement:

http
POST /api/transaction/{transactionId}/void

Refund ​

Refund a settled transaction (supports multiple partial refunds up to the settled total):

http
POST /api/transaction/{transactionId}/refund

Body supports amount and optional surcharge.

5. Reading & Searching ​

  • Get by ID:
http
GET /api/transaction/{transactionId}

Returns full transaction details including response codes, AVS/CVV, and addresses.

  • Search:
http
POST /api/transaction/search

Use filters such as date ranges, amount, processor. If no created_at range is provided, the default is the prior four months.

6. Handling Responses & Errors ​

  • Errors
json
{ "status": "failed", "msg": "bad request error: invalid Postal Code" }

Common “Unauthorized” causes:

  • Missing/incorrect Authorization header
  • Wrong key type (public vs private)
  • Key restrictions
  • Wrong environment

Every response includes x-correlation-id for support.

  • Gateway/Processor Codes
    • 100–199: Approved / Partial Approval
    • 200–299: Issuer Decline
    • 300–399: Gateway Decline
    • 400–499: Processor Error