Migration plan to v5.1-WL1.0.0

To align with the updated Terminal API (version 5.1-WL1.0.0 ), please follow this step-by-step migration process.

This ensures continued functionality, improved security and compatibility with the latest features. We encourage you to make these improvements since future changes will rely on it.

1. Review the updated API specification

The new specification introduces significant updates, notably:

• Updated Header object requiring: ProtocolVersion: "5.1-WL1.0.0."
• New endpoints supporting asynchronous (async) and synchronous (sync) request models.
• Additional fields: “NumberOfRetries”, “WebhookUrl”(for async requests) and improved request/response schemas.
• Updated response and error handling, with “new Response”, “ResponseReason”, and “AdditionalResponseInformation” fields.
• Deprecated or replaced older request types.

2. Update the header object

Current:

• ProtocolVersion: "5.0"

Required Change:

• ProtocolVersion: "5.1-WL1.0.0"

Additional fields:

• Set “NumberOfRetries” (integer ≥ 1). Used only in async requests.
• Set “WebhookUrl” (valid URL). Used for async requests to receive callback updates.

3. Use correct endpoints & request types

Old Endpoint	Request Type	New Endpoint
/api/v1/merchants/{umid}/terminals/{utid}/tapi	Synchronous (old)	/api/v1/merchants/{umid}/terminals/{utid}/payments/sync
No explicit old URL for async	Asynchronous	/api/v1/merchants/{umid}/terminals/{utid}/payments

4. Adjust the ServiceContent property

• Before: ServiceContent uses acronyms to indicate specific transaction types or request contexts.
• Now:
  • Use the value: e.g. “FinancialPaymentRequest”, “ReversalRequest”, “ReconciliationRequest”as per the relevant scenario.
  • Example for payment:
    • "ServiceContent": "FinancialPaymentRequest"

5. Handling asynchronous vs. synchronous requests

a. Async requests:

• Set “Header.NumberOfRetries” and” Header.WebhookUrl”.
• The API will respond with “202 Accepted” and will deliver status updates or results via the webhook URL.
• Use the post_async_payment operation.

b. Sync requests:

• Send request without “NumberOfRetries” and “WebhookUrl”.
• Expect an immediate “200 response” with the transaction result.
• Use the post_sync_payment operation.

6. Parse and handle responses

• Responses now include “detailed Response”, “ResponseReason”, “AdditionalResponseInformation”.
• For failures or warnings, process “AdditionalResponseInformation” for debugging.

7. Test extensively

• Use the provided examples like: e.g. “SimplePaymentRequest” and “RefundReferencedRequest” as starting points for your integration.
• Verify both sync and async flows.
• Confirm webhook callbacks are received for async requests.

8. Summary of changes

Old Model	New Model	Key Change
ProtocolVersion: "5.0"	ProtocolVersion: "5.1-WL1.0.0"	Upgraded protocol version.
No “NumberOfRetries” or “WebhookUrl” in requests	“NumberOfRetries” and “ WebhookUrl” required in async requests	Enable reliable async callbacks.
“ /tapi” endpoint deprecated	Use “/payments/sync” & “/payments” endpoints	Different sync/async flows.
Less detailed schemas	Broad, detailed request/response schemas with optional: “AdditionalService” “ResponseReason” “PaymentReceipt”	Improved diagnostics and flexibility.

Need Help?

If you require assistance during the migration or testing phases, contact our support team at terminalapi@worldline.com .