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
                  

Notification URL

In addition to the callback URL, which is only triggered when a payment is successful, you can send the optional notificationUrl parameter when requesting an MB WAY payment to receive the final status of each individual MB WAY request. Unlike the callback, you are also notified when the customer declines the payment or when the request expires.

The notification is sent as a POST request with a JSON body to the notificationUrl you provided. Unlike the callback, each notification is sent only once.

Notification request body (JSON)

                    {
  "RequestId": "9iCipyBZ2crhtL4QH8Yv",
  "CreatedAt": "13-10-2026 18:13:02",
  "UpdateAt": "13-10-2026 18:13:15",
  "Status": "020",
  "Message": "Declined by user"
}
                  

The body contains the following fields:

RequestId: The MB WAY request ID returned when the payment was created.
CreatedAt: The date and time when the MB WAY request was created (dd-MM-yyyy HH:mm:ss).
UpdateAt: The date and time of the last status change (dd-MM-yyyy HH:mm:ss).
Status: The status code of the request (e.g., 000 paid, 020 declined by the user, 101 expired).
Message: A description of the status (e.g., Declined by user).

The request includes the following headers:

Content-Type: Always application/json.
X-Ifthenpay-Event-Id: A unique identifier for the notification event.
X-Ifthenpay-Signature: A signature, generated with your MB WAY Key as the secret, that you can use to verify that the request was sent by ifthenpay.

Notification request headers

                    Content-Type: application/json
X-Ifthenpay-Event-Id: event_almsywu8w4bdozg2tv17
X-Ifthenpay-Signature: b16d24ac111efd7310af99e8644718341b68b9714c3378c0ce6c97ccde67e73e
                  

What you need to implement

An endpoint at your notificationUrl that accepts POST requests with a JSON body.
Validate the X-Ifthenpay-Signature header before trusting the notification:
- Concatenate orderId, amount and requestId of the payment, with no separators.
- Compute an HMAC SHA-256 hash of that string, using your MB WAY Key as the secret.
- Compare the result with the header value and reject the request if they do not match.
Use the RequestId to find the corresponding order and update it according to the Status.

Signature calculation example

                    Signed string (orderId + amount + requestId): order_4567811.5536jvlEhUYeknQ8PHKprR
Secret (MB WAY Key, test value):             AAA-000000
Resulting X-Ifthenpay-Signature:             d7d2fd272233f0102e6dd0e50969025481cdfe3abb87cc3f135f74cfb47b2561
                  

Alternatively, you can add the ifthenpay server IP address to your whitelist, so that your notification URL only accepts requests from our servers.

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
                  