Server-to-server payments
Use direct payment operations only from your authenticated server. Prefer a saved card collected with secure card fields rather than handling card numbers yourself. Direct card-data processing changes your PCI obligations.
Payment operations
| Action | Method and path | Meaning |
|---|---|---|
| Sale | POST /api/v1/transactions/sale | Authorize and capture a payment |
| Authorization | POST /api/v1/transactions/auth | Reserve a card amount for later capture |
| Capture | POST /api/v1/transactions/{transactionId}/capture | Capture an existing authorization |
| Void | POST /api/v1/transactions/{transactionId}/void | Cancel an eligible transaction |
| Refund | POST /api/v1/transactions/{transactionId}/refund | Return an eligible captured amount |
Sale and authorization use the payment base (https://pay.peakgateway.co, or https://staging-pay.peakgateway.co in sandbox). Follow each operation's server in the downloadable OpenAPI document; the SDK selects it automatically.
For card on file, supply savedPaymentMethodId, the authorized location and customer context, amount in minor units and currency. Use an active saved method belonging to that customer. Follow the operation's request schema for required references and stored-credential information. A refund uses amount and externalReferenceId; an optional capture amount selects the amount to capture. Do not assume every transaction can be voided or refunded.
ACH debits use the sale operation, not card authorization/capture. Use a saved bank payment method or the documented ACH request fields with customer authorization. An approved ACH debit is pending settlement, not irrevocably paid. Do not retry a returned debit without a separately authorized business decision.
Persist the payment identity before sending
Send Idempotency-Key on supported money-moving writes. Before dispatch, persist the key, exact request, location and business reference; retain the returned transaction ID when available. For capture, void and refund, the original operation identity is the write's Idempotency-Key; void/refund also require the body's externalReferenceId to equal that key. Keep each follow-on operation's key separately from the original sale/auth key. A retry of the same authorized attempt must preserve that identity; a new key represents a new attempt, not recovery.
Handle approved, declined and unknown outcomes separately. A timeout, lost response or HTTP error does not prove no payment happened. Read GET /api/v1/transactions/{id} for current transaction status. For a recorded follow-on request such as capture, void or refund, read GET /api/v1/transactions/{id}/operations?operationId={originalOperationId}, URL-encoding the persisted original operation key. Include the authorized locationId query parameter when required by your credential context. This returns evidence for one exact operation, not a list of all operations; the transaction ID alone is insufficient.
An absent operation record does not prove non-execution or a decline. If no transaction ID was received, retain the original business reference/key and contact support rather than submit another payment with a new identity.
Never turn an uncertain result into a second charge. Use webhooks to update your own records, and reconcile missing deliveries with authenticated status reads.