Migration plan to v5.1-WL1.0.0

Follow this migration process to update your integration to Terminal API v5.1-WL1.0.0.

This release introduces updated endpoints, enhanced request and response schemas, improved error handling, and support for synchronous and asynchronous processing. Update your integration to maintain compatibility with future enhancements and platform updates.

Review the API changes

The v5.1-WL1.0.0 specification introduces the following changes:

• Updated Header object requiring ProtocolVersion: "5.1-WL1.0.0".
• New endpoints for synchronous and asynchronous request models.
• New asynchronous request fields:
  • NumberOfRetries
  • WebhookUrl
• Enhanced request and response schemas.
• Improved response and error handling through:
  • Response
  • ResponseReason
  • AdditionalResponseInformation

Deprecation or replacement of legacy request types.

Update the header object

Current:

• ProtocolVersion: "5.0"

Required Change:

• ProtocolVersion: "5.1-WL1.0.0"

For asynchronous requests, configure the following fields:

Field	Description
NumberOfRetries	Integer value greater than or equal to 1. Used only for asynchronous requests.
WebhookUrl	Valid URL used to receive asynchronous callback updates.

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

Adjust the ServiceContent property

Previously, ServiceContent used acronyms to indicate transaction types or request contexts.

Use explicit request names that match the transaction scenario:

• FinancialPaymentRequest
• ReversalRequest
• ReconciliationRequest

Example for payment:

• "ServiceContent": "FinancialPaymentRequest"

Update request handling

a. Async requests

Configure:

• Header.NumberOfRetries
• Header.WebhookUrl

Behavior:

• Returns HTTP 202 Accepted.
• Delivers transaction results and status updates through the configured webhook.

Use the post_async_payment operation.

b. Sync requests

Do not include:

• NumberOfRetries
• WebhookUrl

Behavior:

• Returns an immediate HTTP 200 OK response containing the transaction result.

Use the post_sync_payment operation.

Parse and update response handling

Responses now include enhanced diagnostic information:

• Response
• ResponseReason
• AdditionalResponseInformation

Process AdditionalResponseInformation when handling failures or warnings to assist with troubleshooting and debugging.

Test your integration

Use the provided examples, such as:

• SimplePaymentRequest
• RefundReferencedRequest

Verify the following:

• Synchronous request processing.
• Asynchronous request processing.
• Webhook callback delivery.
• Response and error handling behavior.

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