Payment API Migration

This document is a migration playbook for moving server-side payment submissions from the Classic API endpoint (/api/transact.php) to the modern JSON-encoded endpoints (/api/v5/payments/...).

Overview of changes

What doesn't change

• If you already use Payment Component or Collect.js, that client-side token creation flow doesn't need to change.
• No need to generate new API keys or alter permissions, both are inherited by the new endpoints.

Operation mapping

Online Payments

Replace type=<operation> on transact.php with the matching new endpoint, for example:

• sale POST /api/v5/payments/sale
• capture POST /api/v5/payments/{transaction_id}/capture
• Single-transaction lookup GET /api/v5/payments/{transaction_id}

Use the transaction identifier returned within the JSON response (id) as {transaction_id} in follow-on URLs. See our API Reference for the full list of endpoints.

In-Person Payments

If a payment is initiated on a registered device (for example, cloud terminal or PIN pad workflows), use the asynchronous device endpoints:

• sale POST /api/v5/devices/{device_id}/payment-requests/sale
• validate POST /api/v5/devices/{device_id}/payment-requests/validate

These requests return a payment request identifier when successful. To check the status and retrieve transaction details, poll:

• GET /api/v5/devices/{device_id}/payment-requests/{request_id}

Once complete, the response includes summary transaction information. For additional device management and operations endpoints, see the full API Reference.

Payload reshaping

1. Open the Code Examples for representative Classic API vs JSON body comparisons.
2. Use the API Reference for the complete field catalog, optional fields, and processor-specific parameters.

Some changes to expect:

• Introduction of the payment_details object containing Credit Card, Check, or Token data.
• New billing_address and shipping_address objects to more easily pass and parse customer data.

Response handling changes

Classic API response pattern

• Query-string style (response=...&responsetext=...)

JSON response pattern

• Standard transaction shape includes:
  • Resource name in the object field with a unique id
  • Maintained response, response_text, response_code
  • Nested objects matching requests (ex: payment_details, billing_address, etc.)

Error handling

Use the response's HTTP status code (ex: 409, 404, etc.) alongside the error body together:

• Basic error identifiers provided in type, error_code, and message
• While details will elaborate more on things like validation errors

What's next?

FAQ