When the payment is completed, a
transaction is created with info about the payment method used, card details, and success status.
The session will contain a
transaction_id referencing the transaction. There will only be one transaction for any one session.
The possible states the transaction can be in after completion are:
AUTHORIZED- successful payment
ON_HOLD- further controls are necessary, will change to
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
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.
machine-to-machine, and delivery is therefore
callback_url must be public available and be and HTTPS URL.
The integration must handle parallel execution of both
The callback_url will be invoked when a payment is complete and the transaction has been authorized. Unlike return_url the callback_url is system-to-system which means delivery is guaranteed.
Once the payment is complete the callback_url is invoked as an
GET request to
notify the system that the payment has been approved.
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_urlmust 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
Once payment is complete or canceled the user is redirected to the return_url
Following query parameters will be included in the return_url request
- 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
cancelledwill 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:
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
Transactions with status
ON_HOLD should be handled as payment pending
and you can expect an aditional callback when the transaction changes
It is recommended that callback is supported to receive the additional update when the transaction changes status from
The alternative is to poll the transaction every hour until it changes status from
|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.