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

Important

Every response includes x-correlation-id in the response headers. This ID is essential for support and log lookups - save it when troubleshooting issues. See the Correlation ID section for details.

2. Your First Charge (Sale) ​

Endpoint: POST https://sandbox.approvely.net/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) [Optional] ​

Optionally 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:

You can optionally pass tax_amount, shipping_amount, order_id, etc. in the body.

Void / Auth Reversal ​

Void a transaction that's pending settlement (where applicable, processed as an auth reversal):

Refund ​

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

Body supports amount (required for partial refunds, optional for full refund) and optional surcharge.

5. Getting & Searching Transactions ​

  • Get by ID:
http
GET https://sandbox.approvely.net/api/transaction/{transactionId}

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

  • Search:
http
POST https://sandbox.approvely.net/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" }

For common issues and troubleshooting:

  • Unauthorized errors: See Unauthorized section in the Requests documentation for details on missing Authorization headers, API key types, restrictions, and environment issues.
  • Gateway/Processor Codes: See Response Codes section in the Transactions documentation for complete information on response code ranges and meanings.

Correlation ID for Support

Every response includes x-correlation-id in the response headers. This unique identifier is used to look up transaction logs and troubleshoot issues. Always include this ID when contacting support. See the Correlation ID documentation for more information.