Handling payment

When the payment is completed, a transaction is created with info about the payment method used, card details, and success status. order.shipping_option from the session will be moved to an item in the transaction.

The session will contain a transaction_id referencing the transaction. There will only be one transaction for any one session.

Transaction statuses

The possible states the transaction can be in after completion are:

• AUTHORIZED - successful payment
• ON_HOLD - further controls are necessary, will change to AUTHORIZED or FAILED later
• CAPTURED - auto-capture is turned on, and the money was withdrawn from the customer's account. auto-capture could have been turned on in the payment profile, or at the payment provider. Might also be captured if someone was really, really fast at capturing it manually.
• FAILED - payment failed
• DECLINED - customer declined the payment while it was processing

Getting notified about the transaction status

The website should implement url.return_url and url.callback_url.

The integration must handle parallel execution of both return_url and callback_url handlers.

return_url can be used for marking the order as paid and showing a success page to the customer, but we can never guarantee that the customer will actually be redirected there. The customer might have connection issues, navigate to another website before being redirected, or turn off their device.

callback_url

The callback_url will be invoked when a payment is complete and the transaction has been authorized. Unlike return_url the callback_url is machine-to-machine which means delivery is guaranteed. The callback_url must be public available and be a HTTPS URL.

Once the payment is complete the callback_url is invoked as a GET request to notify the system that the payment has been approved.

It's possible to customize the behaviour of the callback by setting different query parameters on the callback_url.

For example, if you want to receive callbacks on errors, set the query parameter report_error=true.

See url.callback_url in the API docs for more customization options.

A successful delivery to an HTTPS callback_url sometimes requires more than one attempt. This can be the case, for example, if the server hosting the callback_url is down for maintenance or is experiencing heavy traffic.

Dintero attempts a retry only after a failed delivery attempt, following situations is considered as failed delivery

• HTTP status code 100 to 101 and 500 to 599 (inclusive) (HTTP status code 400 to 499 is considered as permanent failure)
• A request timeout (10 seconds)
• Any connection error such as connection timeout, bad certificate, etc

Failed deliveries will be retried 20 times.

The service receiving the request for the callback_url must verify the request by checking the status of the transaction_id before the order payment status is updated.

Following query parameters will be included in the callback request

query	type	required
transaction_id	string	true
session_id	string	true
merchant_reference	string	true
time	string	true

return_url

Once payment is complete or canceled the user is redirected to the return_url via a GET request.

Following query parameters will be included in the return_url request

query	type	required
transaction_id	string	false
error	string	false
merchant_reference	string	false

• If a transaction was completed successfully, a transaction_id will be appended to the return_url
• If the user decides to cancel the payment, an error with value cancelled will be appended to the return_url
• See [the full list of return_url errors]

Building logic relying on the order of return_url is not recommended. It is not guaranteed that they will be invoked, since the user might interfere with it. There could various reason for the urls not to be invoked like computer closing the browser, entering a new page, etc.

See more details about callback_url and return_url in the API docs.

return_url for non website users

If you do not have a custom return_url you can use the default return_url used by our own Digital Terminal:

 https://checkout.dintero.com/result/

Redirect / Callback with transaction status ON_HOLD

A transaction can in some cases end up in an ON_HOLD status when the redirect/callback is done. Transactions with this status require additional async controls before the transaction can be AUTHORIZED.

Transactions with status ON_HOLD should be handled as payment pending and you can expect an aditional callback when the transaction changes status from ON_HOLD.

It is recommended that callback is supported to receive the additional update when the transaction changes status from ON_HOLD to AUTHORIZED or FAILED.

The alternative is to poll the transaction every hour until it changes status from ON_HOLD.

Errors

error	Description
cancelled	Customer cancelled the checkout payment
authorization	Customer failed to authorize the payment
failed	The transaction has been rejected by us, or an error has occurred during transaction processing
capture	The transaction capture operation failed during auto-capture

Updating transaction with merchant_reference_2

If the order has any new references that needs to be available on the transaction, it can be updated. To do this, see here.