Callback & Notifications

Overview

Once the order has been placed and payment has been confirmed, you will be notified by ifthenpay via the usual channels, i.e. by push notification, if you have our app installed and have this option activated, by email, or you can check directly in our backoffice.

If you wish to be notified by callback, you must first ask ifthenpay to activate your callback (webhook).

In simpler terms: The callback URL is like a template. When a payment happens, the template is filled in with real information about that payment, and then the information is sent to your website.

ifthenpay offers free technical support to all customers through the following channels:

« go to index

Explanation

The following is an explanation of what a callback is and its purpose.

Callback example URL

                    http://www.yoursite.com/callback.php?key=[ANTI_PHISHING_KEY]&orderId=[ORDER_ID]&amount=[AMOUNT]&requestId=[REQUEST_ID]&payment_datetime=[PAYMENT_DATETIME]
                  

Constraints

Callback URL: Maximum 300 characters
Anti-Phishing Key: Maximum 50 characters

URL Breakdown:

http://www.yoursite.com/callback.php: This is the basic address of a PHP script on your website. It's where the information from the payment gateway will be sent.
?key=[ANTI_PHISHING_KEY]&orderId=[ORDER_ID]&amount=[AMOUNT]&requestId=[REQUEST_ID]&payment_datetime=[PAYMENT_DATETIME]: This part is called a query string. It contains key-value pairs that provide additional information.

The Square Brackets []:

The parts within the square brackets are placeholders. They will be replaced with actual values when the payment is processed.
For example, [ANTI_PHISHING_KEY] will be replaced with a unique security key to prevent fraudulent transactions.
[ORDER_ID] will be replaced with the specific order number.
[AMOUNT] will be replaced with the total amount of the purchase.
And so on.

What Happens During a Callback:

Customer Completes Purchase: When a customer finishes buying something on your website, the payment gateway processes the transaction.
Gateway Sends Request: The payment gateway sends a request to the URL you provided.
Placeholders are Replaced: The gateway replaces the placeholders in the URL with the specific details of the transaction.
Your Server Receives Data: Your server receives the request and processes the data, updating your database, sending emails, or performing other actions.

Why use a callback URL?

Automation: It allows you to automate processes like updating order status or sending receipts.
Security: The [ANTI_PHISHING_KEY] helps prevent fraudulent transactions.
Flexibility: You can customize the information you receive for each transaction.

Common Use Cases:

E-commerce: Updating order status, sending shipping notifications.
Subscriptions: Managing recurring payments and cancellations.
Donations: Processing donations and issuing receipts.

Response Codes and Retry Policy

Your URL is not required to return any content. The success of our request is determined solely by the HTTP status code returned: if an HTTP 200 status code is received, ifthenpay considers the call successful. If any other status code is returned (HTTP 400, 500, or others), the call is considered unsuccessful and will be retried automatically.

A maximum of 13 attempts will be made: the first 8 at 5-minute intervals, and the remaining attempts at 1-hour intervals. If, after these 13 attempts, a successful response (HTTP 200) is still not obtained, no further retries will be made.

Additionally, if the failure is identified as permanent, the system will stop retrying after the 3rd attempt.

Multibanco

Callback example URL

                    https://www.yoursite.com/callback.php?key=[ANTI_PHISHING_KEY]&orderId=[ORDER_ID]&amount=[AMOUNT]&requestId=[REQUEST_ID]&entity=[entity]&reference=[REFERENCE]&payment_datetime=[PAYMENT_DATETIME]
                  

The description of the replacements is as follows:

[ANTI_PHISHING_KEY]: Will be replaced with the anti-phishing key that validates the authenticity of the transaction.
[ORDER_ID]: Will be replaced with the unique order ID associated with the transaction.
[AMOUNT]: Will be replaced with the total amount of the transaction.
[REQUEST_ID]: Will be replaced with the request ID that initiated the payment.
[ENTITY]: Will be replaced with the multibanco entity that was used to process the payment.
[REFERENCE]: Will be replaced with the multibanco that was used to process the payment.
[PAYMENT_DATETIME]: Will be replaced with the date and time when the payment was made.

Example of a Callback URL triggered after payment confirmation

                    https://www.yoursite.com/callback.php?key=my_anti_phishing_key&orderId=order-1234&amount=1234.56&requestId=5Qd8gtWLAEUJ6n0lkS5g&entity=99999&reference=123456789&payment_datetime=28-10-2021 10:55:21
                  

MB WAY

Callback example URL

                    https://www.yoursite.com/callback.php?key=[ANTI_PHISHING_KEY]&orderId=[ORDER_ID]&amount=[AMOUNT]&requestId=[REQUEST_ID]&payment_datetime=[PAYMENT_DATETIME]
                  

The description of the replacements is as follows:

[ANTI_PHISHING_KEY]: Will be replaced with the anti-phishing key that validates the authenticity of the transaction.
[ORDER_ID]: Will be replaced with the unique order ID associated with the transaction.
[AMOUNT]: Will be replaced with the total amount of the transaction.
[REQUEST_ID]: Will be replaced with the request ID that initiated the payment.
[PAYMENT_DATETIME]: Will be replaced with the date and time when the payment was made.

Example of a Callback URL triggered after payment confirmation

                    https://www.yoursite.com/callback.php?key=your_anti_phishing_key&orderId=1887&amount=33.61&requestId=i2szvoUfPYBMWdSxqO3n&payment_datetime=03-01-2024 15:15:16
                  

Payshop

Callback example URL

                    https://www.yoursite.com/callback.php?anti_phishing_key=[ANTI_PHISHING_KEY]&order_id=[ORDER_ID]&reference=[REFERENCE]&amount=[AMOUNT]&payment_datetime=[PAYMENT_DATETIME]
                  

The description of the replacements is as follows:

[ANTI_PHISHING_KEY]: Will be replaced with the anti-phishing key that validates the authenticity of the transaction.
[ORDER_ID]: Will be replaced with the unique order ID associated with the transaction.
[AMOUNT]: Will be replaced with the total amount of the transaction.
[REFERENCE]: Will be replaced with the payshop reference that was used to process the payment.
[PAYMENT_DATETIME]: Will be replaced with the date and time when the payment was made.

Example of a Callback URL triggered after payment confirmation

                    https://www.yoursite.com/callback.php?anti_phishing_key=my_anti_phishing_key&order_id=12345&reference=1021600051424&amount=5.00&payment_datetime=28-10-2021 10:55:21
                  

Credit Card

Callback example URL

                    https://www.yoursite.com/callback.php?key=[ANTI_PHISHING_KEY]&id=[ORDER_ID]&amount=[AMOUNT]&payment_datetime=[PAYMENT_DATETIME]&payment_method=[PAYMENT_METHOD]
                  

The description of the replacements is as follows:

[ANTI_PHISHING_KEY]: Will be replaced with the anti-phishing key that validates the authenticity of the transaction.
[ORDER_ID]: Will be replaced with the order ID associated with the transaction.
[AMOUNT]: Will be replaced with the total amount of the transaction.
[PAYMENT_METHOD]: Will be replaced with the payment method that was used to process the payment.
[PAYMENT_DATETIME]: Will be replaced with the date and time when the payment was made.

Example of a Callback URL triggered after payment confirmation

                    https://www.yoursite.com/callback.php?key=my_anti_phishing_key&id=1234&amount=21.50&payment_datetime=28-10-2021 10:55:21&payment_method=CCARD
                  

Google Pay

Callback example URL

                    https://www.yoursite.com/callback.php?key=[ANTI_PHISHING_KEY]&id=[ORDER_ID]&amount=[AMOUNT]&payment_datetime=[PAYMENT_DATETIME]&payment_method=[PAYMENT_METHOD]
                  

The description of the replacements is as follows:

[ANTI_PHISHING_KEY]: Will be replaced with the anti-phishing key that validates the authenticity of the transaction.
[ORDER_ID]: Will be replaced with the order ID associated with the transaction.
[AMOUNT]: Will be replaced with the total amount of the transaction.
[PAYMENT_METHOD]: Will be replaced with the payment method that was used to process the payment.
[PAYMENT_DATETIME]: Will be replaced with the date and time when the payment was made.

Example of a Callback URL triggered after payment confirmation

                    https://www.yoursite.com/callback.php?key=my_anti_phishing_key&id=1234&amount=21.50&payment_datetime=28-10-2021 10:55:21&payment_method=GOOGLE
                  

Apple Pay

Callback example URL

                    https://www.yoursite.com/callback.php?key=[ANTI_PHISHING_KEY]&id=[ORDER_ID]&amount=[AMOUNT]&payment_datetime=[PAYMENT_DATETIME]&payment_method=[PAYMENT_METHOD]
                  

The description of the replacements is as follows:

[ANTI_PHISHING_KEY]: Will be replaced with the anti-phishing key that validates the authenticity of the transaction.
[ORDER_ID]: Will be replaced with the order ID associated with the transaction.
[AMOUNT]: Will be replaced with the total amount of the transaction.
[PAYMENT_METHOD]: Will be replaced with the payment method that was used to process the payment.
[PAYMENT_DATETIME]: Will be replaced with the date and time when the payment was made.

Example of a Callback URL triggered after payment confirmation

                    https://www.yoursite.com/callback.php?key=my_anti_phishing_key&id=1234&amount=21.50&payment_datetime=28-10-2021 10:55:21&payment_method=GOOGLE
                  

Direct Debit

Callback example URL

                    https://www.yoursite.com/callback.php?anti_phishing_key=[ANTI_PHISHING_KEY]&mandate_id=[ORDER_ID]&transaction_id=[REQUEST_ID]&amount=[AMOUNT]&payment_datetime=[PAYMENT_DATETIME]
                  

The description of the replacements is as follows:

[ANTI_PHISHING_KEY]: Will be replaced with the anti-phishing key that validates the authenticity of the transaction.
[ORDER_ID]: Will be replaced with the Mandate ID and the identifier, separated by a hyphen, associated with the transaction.
Note: In the order ID example 06866684094-0000, the first part before the hyphen (06866684094) corresponds to the Mandate ID, and the second part (0000) corresponds to the transaction identifier.
[AMOUNT]: Will be replaced with the total amount of the transaction.
[REFERENCE]: Will be replaced with the direct debit reference that was used to process the payment.
[REQUEST_ID]: Will be replaced with the transaction ID that initiated the direct debit payment.
[PAYMENT_DATETIME]: Will be replaced with the date and time when the payment was made.

Example of a Callback URL triggered after payment confirmation

                    https://www.yoursite.com/callback.php?anti_phishing_key=my_anti_phishing_key&mandate_id=12345&reference=1021600051424&transaction_id=00065411-98&amount=5.00&payment_datetime=28-10-2021 10:55:21
                  

In addition to the callback URL, which only confirms when a payment is successfully collected, you can also use the notification URL to receive the status of each individual collection attempt as it is processed.

Notification example URL

                    https://www.yoursite.com/notification.php 
(This URL will be called using the GET method, and parameters will be appended when a payment is confirmed or refused.)
                  

The following parameters are included in the direct debit notification URL when a payment is either confirmed or refused:

mandateId: The Mandate ID (e.g., 09039807130).
transactionId: The Transaction ID (e.g., KL83NVuf0fy8GYkpohVo).
amount: The total amount of the transaction (e.g., 0.01).
currency: The transaction currency (e.g., EUR).
collectionDate: The scheduled collection date (e.g., 2025-04-17).
reference: The transaction reference (e.g., 6CCEA46379).
status: The status of the transaction (e.g., PROCESSING).
- PENDING
- PROCESSING
- ACTIVE
- COMPLETED
- ERROR
- CANCELED
code: The status code returned (e.g., 0000).
- 0000 - SUCCESS
- Download List of all status codes

Example of a Notification URL triggered after payment confirmation

                    https://www.yoursite.com/notification.php?mandateId=09039807130&transactionId=KL83NVuf0fy8GYkpohVo&amount=0.01¤cy=EUR&collectionDate=2025-04-17&reference=6CCEA46379&status=PROCESSING&code=0000
                  

PIX

Callback example URL

                    https://www.yoursite.com/callback.php?anti_phishing_key=[ANTI_PHISHING_KEY]&order_id=[ORDER_ID]&amount=[AMOUNT]&payment_datetime=[PAYMENT_DATETIME]
                  

The description of the replacements is as follows:

[ANTI_PHISHING_KEY]: Will be replaced with the anti-phishing key that validates the authenticity of the transaction.
[ORDER_ID]: Will be replaced with the unique order ID associated with the transaction.
[AMOUNT]: Will be replaced with the total amount of the transaction.
[PAYMENT_DATETIME]: Will be replaced with the date and time when the payment was made.

Example of a Callback URL triggered after payment confirmation

                    https://www.yoursite.com/callback.php?anti_phishing_key=my_anti_phishing_key&order_id=12345&amount=5.00&payment_datetime=28-10-2021 10:55:21
                  

PAY BY LINK & PINPAY

Callback example URL

                    https://www.yoursite.com/callback.php?key=[ANTI_PHISHING_KEY]&id=[ID]&amount=[AMOUNT]&payment_datetime=[PAYMENT_DATETIME]&payment_method=[PAYMENT_METHOD]
                  

The description of the replacements is as follows:

[ANTI_PHISHING_KEY]: Will be replaced with the anti-phishing key that validates the authenticity of the transaction.
[ID]: Will be replaced with the order ID associated with the transaction.
[AMOUNT]: Will be replaced with the total amount of the transaction.
[PAYMENT_METHOD]: Will be replaced with the payment method that was used to process the payment.
[PAYMENT_DATETIME]: Will be replaced with the date and time when the payment was made.

Example of a Callback URL triggered after payment confirmation

                    https://www.yoursite.com/callback.php?key=my_anti_phishing_key&id=1234&amount=21.50&payment_datetime=28-10-2021 10:55:21&payment_method=CCARD
                  