> ## Documentation Index > Fetch the complete documentation index at: https://docs.dintero.com/llms.txt > Use this file to discover all available pages before exploring further. ## Submitting Feedback If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback: POST https://docs.dintero.com/feedback ```json { "path": "/docs/checkout/after-payment", "feedback": "Description of the issue" } ``` Only submit feedback when you have something specific and actionable to report. # Handling payment > Handle Dintero Checkout transactions after payment with return_url and callback_url, transaction statuses, and idempotent post-payment processing. 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 publicly 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](/payments-api.html#operation/checkout_session_profile_post) 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, the following situations are 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. The 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. The 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 be various reasons 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](/payments-api.html#operation/checkout_session_profile_post). #### 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 additional 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](/payments-api.html#operation/transactions_id_put).