Modification APIs

The SmartPay modification APIs provide you with tools to modify your checkout transaction, as required by your flows.

Use of modificationId

Each message sent via API is a request and should include a unique modificationId as request identifier for the purpose of detecting duplicate requests.

There may be times when your system does not receive a response due to a timeout or other exception case. You have the option to retry the request. In this scenario, send the exact same message using same modificationId. This allows us to ensure the message is not processed multiple times.

In the event that original request was processed, the original response message content will be returned.

Updates to APIs

SmartPay APIs are periodically updated to introduce new features,simplyfy the integration or to ensure they are up-to-date with changes in downstream system. We invest great efforts to ensure that these changes are backward compatible and will not break your implementation.

To ensure that you take advantage of any new features SmartPay offers, please plan on periodically revisiting our APIs and release notes. Advance notice will be provided via our status page, when publishing new versions of the API that may not be backward compatible or if any previous versions are deprecated.

Updates to SmartPay APIs can include:

• Add additional fields to the request / response objects.
• Change the order of the response object.
• Remove or rename optional fields in the response.

SmartPay Capture API  allows you to manually capture funds from your consumer's funding source. This allows you to implement a twostep payment process where the consumer would first commit to your checkout transaction by completing the authorization, but funds would be only transferred to your merchant account after calling the capture API. This might be of use if you e.g., sell physical goods and only want to receive funds after order execution and prior shipment.

Please note:

• You can capture any amount > 0 and < / = the amount requested in checkout transaction.
• If the captured amount is < authorized amount, the remaining funds will be released back to your consumers funding source.
• To use capture API, please make sure that SmartPay auto-capture is disabled for your merchant key.
• Authorizations expire automatically after a time periods (typically 5 days, please check with your Payment Solutions Specialist values applicable to you), which lets your checkout expire. Expired transactions cannot be captured.
• Payment options like online bank transfers do not support authorize / capture flows as the consumer is confirming the payment during the process.

SmartPay cancel API allows you to cancel an authorized transaction. This will release the full authorized amount, e.g. in case you don't want to fulfil the consumer's order.

Please note:

• Cancel only works for transaction in state "AUTHORIZED", if the transaction status is already "CAPTURED" or "SETTLED" please use refund or CancelOrRefund API.

As suggested by its name, our cancelOrRefund API will cancel or fully refund your checkout transaction. This is usefully, if you have delayed auto-capture enabled and you need to reverse a checkout transaction in "AUTHORIZED", "CAPTURED" or "SETTLED" state - without need to know the exact state.

Please note:

• This API is designed to reduce complexity of your integration. Instead of cancelOrRefund you could also check the current transaction status and call cancel or refund API.
• Partial refunds / cancels are not possible it will always return the full amount.

The refund API allows you to refund funds partially or fully to your consumer.

Please note:

• You can request as many refunds as required, until the previously captured amount is refunded.
• Refunds can be requested for "CAPTURED" or "SETTLED" transactions

Document version 1.1 - 2022-05-20 - "Considerations while using our APIs" - section added