Payment API – Functional Documentation

Overview

The Payment API allows merchants to:

• Create and manage payment charges

• Perform captures, increments, voids, and releases

• Issue and manage refunds

• Perform card verifications

It supports multiple payment methods including cards, terminals, cash, wallets (Apple Pay / Google Pay), and stored payment tokens.

Environments

Security

• Authentication: HTTP Basic Authentication

• All endpoints require valid credentials

• Idempotency is supported on creation endpoints (charges, refunds, verifications)

Core Concepts

Charge

A charge represents a payment transaction.
A charge can be:

• Captured immediately

• Authorized first and captured later

• Incremented (pre-authorization increase)

• Released (remaining uncaptured amount)

• Voided (if captured and unbatched)

• Refunded (fully or partially)

Refund

A refund returns funds from a completed charge back to the customer.

Verification

A verification validates a payment card without charging it.

Charge Lifecycle

Typical charge flow:

1. Create Charge

2. (Optional) Increment amount (pre-auth only)

3. (Optional) Capture authorized amount

4. (Optional) Void captured charge (before batching)

5. (Optional) Release uncaptured amount

6. (Optional) Refund captured charge

Charges API

Create a Charge

POST /charges

Creates a new payment transaction.

Supports:

• Card payments

• Terminal payments

• Cash

• Wallets (Apple Pay, Google Pay)

• 3-D Secure authentication

• Stored credentials

Key behavior:

• If capture = true (default): charge is immediately captured

• If capture = false: charge is authorized and must be captured later

Responses:

• 201 – Charge created

• 200 – Charge already created (same idempotency key)

• 402 – Charge declined

• 400 / 500 – Error

Query Charges

GET /charges

Returns a paginated list of charges, sorted by most recent.

Filters include:

• Terminal ID

• Authorization code

• Idempotency key

• Invoice number

• Card last four digits

• Date range

• Pagination (offset, limit)

Get a Charge

GET /charges/{chargeId}

Retrieves a single charge by its unique identifier.

Capture a Charge

POST /charges/{chargeId}/captures

Captures an existing authorized (uncaptured) charge.

Rules:

• Charge must exist

• Charge must not already be fully captured

• Partial capture is supported

Increment a Charge

POST /charges/{chargeId}/increments

Increases the authorized amount on a pre-authorized charge.

Used for:

• Hospitality

• Car rentals

• Variable-amount transactions

Void a Captured Charge

POST /charges/{chargeId}/voids

Voids a captured charge before it is batched.

Release a Charge

POST /charges/{chargeId}/releases

Releases the remaining uncaptured portion of a charge.

Refunds API

Create a Refund

POST /refunds

Issues a refund against a completed charge.

Features:

• Full or partial refunds

• Idempotent creation

• Reason required

Query Refunds

GET /refunds

Returns a list of refunds, sorted by most recent.

Supports the same filtering and pagination logic as charges.

Get a Refund

GET /refunds/{refundId}

Retrieves a specific refund.

Void a Refund

POST /refunds/{refundId}/voids

Voids an unbatched refund.

Verifications API

Create Verification

POST /verifications

Verifies a credit card without charging it.

Use cases:

• Card validation

• Storing payment methods

Get Verification

GET /verifications/{verificationId}

Retrieves the result of a verification request.

Payment Methods Supported

• CARD – Manual entry, EMV, magstripe

• TERMINAL – POS-based payments

• CASH

• PAYMENT_TOKEN – Stored credentials

• WALLETS

  • Apple Pay

  • Google Pay

Statuses & Results

Transaction Status

• RECEIVED

• PENDING

• SUCCEEDED

• FAILED

• VOIDED

• RELEASED

• CANCELLED

• ERROR

Result Object

Provides:

• Authorization codes

• Decline reasons

• Processor and issuer response codes

• Batch information

Error Handling

Errors include:

• Type (CARD_ERROR, INVALID_REQUEST_ERROR, etc.)

• Error code

• Human-readable message

• Field-level validation errors

• Documentation reference URL

Key Functional Notes

• Idempotency prevents duplicate charges/refunds

• Partial capture and refund are supported

• Stored credentials comply with recurring payment standards

• Terminal transactions include EMV and track data

• 3-D Secure and wallet authentication are supported
  

GET /transactions?limit=20&offset=40

GET /transactions?startDate=2025-01-01T00:00:00Z&endDate=2025-01-31T23:59:59Z

GET /transactions?limit=50&offset=0&startDate=2025-01-01T00:00:00Z&endDate=2025-01-15T00:00:00Z

Global Parameters Table (All Endpoints)

Path Parameters

Query Parameters (Search & Pagination)

Charge – Request Body Parameters

Capture Parameters

Increment Parameters

Void Charge Parameters

Release Charge Parameters

Refund – Request Body Parameters

Void Refund Parameters

Verification Parameters

Bonus Notes

• Terminal object appears in capture, increment, void, release, refund void

• Amount fields always use smallest currency unit (e.g. cents)