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.

bash
curl -X POST "<BASE_URL>/api/transaction"   -H "Authorization: api_<YOUR_PRIVATE_KEY>"   -H "Content-Type: application/json"   -d '{
    "type": "sale",
    "amount": 1299,
    "payment_method": {
      "card": {
        "number": "4111111111111111",
        "expiration_date": "12/30",
        "cvc": "123"
      }
    },
    "description": "Test charge $12.99"
  }'
js
await fetch(`${BASE_URL}/api/transaction`, {
  method: "POST",
  headers: {
    Authorization: "api_<YOUR_PRIVATE_KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    type: "sale",
    amount: 1299,
    payment_method: { card: { number: "4111111111111111", expiration_date: "12/30", cvc: "123" } },
    description: "Test charge $12.99"
  })
});
python
import requests

resp = requests.post(
    f"{BASE_URL}/api/transaction",
    headers={"Authorization": "api_<YOUR_PRIVATE_KEY>", "Content-Type": "application/json"},
    json={
        "type": "sale",
        "amount": 1299,
        "payment_method": {"card": {"number": "4111111111111111", "expiration_date": "12/30", "cvc": "123"}},
        "description": "Test charge $12.99",
    },
)
print(resp.json())
go
body := `{
  "type":"sale",
  "amount":1299,
  "payment_method":{"card":{"number":"4111111111111111","expiration_date":"12/30","cvc":"123"}},
  "description":"Test charge $12.99"
}`

req, _ := http.NewRequest("POST", BASE_URL+"/api/transaction", strings.NewReader(body))
req.Header.Set("Authorization", "api_<YOUR_PRIVATE_KEY>")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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.

json
{
  "type": "sale",
  "amount": 17500,
  "idempotency_key": "7df4d862-1a3d-44c4-b3df-536aadf307b0",
  "payment_method": {
    "card": { "number": "4111111111111111", "expiration_date": "12/30", "cvc": "123" }
  }
}

4. Common Flows ​

Sale ​

Authorize and Capture in single call:

json
POST /api/transaction
{
  "type": "sale",
  "amount": 5000,
  "payment_method": { "card": { ... } }
}

Auth → Capture ​

Authorize now, capture later:

json
POST /api/transaction
{
  "type": "authorize",
  "amount": 5000,
  "payment_method": { "card": { ... } }
}

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