API Version 2026.1 changes over 2020.1

At Pinch, we have tried to keep our API changes backwards compatible as much as possible but sometimes we just need to make a breaking change.

Below are the changes made to the API when using the 2026.1 version header.

Idempotency updates for payments and refunds

• Payments: POST /payments and POST /payments/realtime accept idempotencyKey in the request body (replacing nonce for 2026.1).
• Refunds: POST /refunds accepts idempotencyKey in the request body (replacing nonce for 2026.1).
• New endpoints for idempotency checks:
  • POST /payments/idempotency-check
  • POST /refunds/idempotency-check
• Idempotency check requests expect idempotencyKey in the request body.
• Read responses for 2026.1 return idempotencyKey on payment and refund resources (for GET /payments/{id}, GET /payments/payer/{payerId}, and refund create responses).
• For 2020.1 integrations, continue using nonce and the /nonce endpoints.

Pagination changes

These list endpoints now return a paged response object instead of a bare array:

• GET /payments/payer/{payerId}
• GET /subscriptions/payer/{payerId}
• GET /transfers

Paged response fields:

• page
• pageSize
• totalPages
• totalItems
• data (the list of items)

Webhooks: API versioning and source events

• Webhook create/update accepts apiVersion in the request body or derives it from the pinch-version header. Responses now include apiVersion.
• New event types available to 2026.1 webhooks:
  • source-created
  • source-deleted
• Source event metadata includes payerName, sourceId, and sourceType.
• Webhook deliveries use the event envelope (id, type, eventDate, metadata, data, merchantId) without delivery metadata.

Managed merchant search

• New endpoint: GET /merchants/search-managed
• Supports filter, status[], page, and pageSize query parameters for searching managed merchants.

Update Merchant and Contacts endpoint changes

• Removing ability to update Contacts via the POST /merchants/update request.
• The response will also not contain Contacts.
• The Contacts API should be used instead.

Deprecated v2017.2 and v2019.1

• These older API versions are no longer being supported and will be removed soon.