ifthenpay

https://www.ifthenpay.com/docs/en
Admin
ifthenpay is a payment processing API that enables merchants to generate payment references, receive...
Tokens:15,430
Snippets:136
Trust Score:9
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example Simple Checkout Link

Source: https://www.ifthenpay.com/docs/en/guides/simple-checkout

An example of a fully constructed Simple Checkout Link with all required parameters and some optional ones filled in.

```URL
https://gateway.ifthenpay.com/?token=GATEWAY_KEY&id=10501&amount=10.50&description=Order No. 2010501&expire=20291029&lang=PT
```

--------------------------------

### Install PHP SDK via Composer

Source: https://www.ifthenpay.com/docs/en/index.html

Install the ifthenpay PHP SDK using Composer. This package provides integration for various ifthenpay payment methods.

```bash
composer require ifthenpay/payment-gateway-sdk
```

--------------------------------

### Install JavaScript SDK via NPM

Source: https://www.ifthenpay.com/docs/en/index.html

Install the ifthenpay JavaScript SDK using NPM. This package enables integration with multiple ifthenpay payment methods in JavaScript applications.

```bash
npm install @ifthenpay/js-sdk
```

--------------------------------

### Refund API Response Example (JSON)

Source: https://www.ifthenpay.com/docs/en/api/refund

This is an example of a successful operation response from the Refund API, indicating the status of the refund request.

```json
{
  "Code": 0,
  "Message": "Payment could not be refunded"
}
```

--------------------------------

### Simple Checkout Button Example

Source: https://www.ifthenpay.com/docs/en/guides/simple-checkout

Use this snippet to create a 'Pay Now' button that redirects users to the payment page in a new tab. It requires the gateway URL with specific parameters.

```html
<a href="https://gateway.ifthenpay.com/?token=GATEWAY_KEY&id=10501&amount=10.50&description=Order+No.+2010501&expire=20251029&lang=EN" target="_blank">
<button style="padding: 10px 20px; font-size: 16px; cursor: pointer;">Pay Now</button>
</a>
```

--------------------------------

### Simple Checkout Link Example

Source: https://www.ifthenpay.com/docs/en/guides/simple-checkout

Implement this snippet to create a clickable 'Pay Now' text link that directs users to the payment page. It uses the same Simple Checkout URL structure with necessary payment details.

```html
<a href="https://gateway.ifthenpay.com/?token=NXXX-999999&id=10501&amount=10.50&description=Order+No.+2010501&expire=20251029&lang=EN" target="_blank">Pay Now</a>
```

--------------------------------

### MBWay API Request Example

Source: https://www.ifthenpay.com/docs/en/api/mbway

This snippet demonstrates a typical cURL request to the MBWay API. It includes headers and the request body.

```Shell
curl \
  --request GET \
  --url https://api.ifthenpay.com/v1/mbway/transactions \
  --header "accept: application/json" \
  --header "authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Shell Curl Request Example

Source: https://www.ifthenpay.com/docs/en/api/callback

This snippet demonstrates how to send a request using curl. It's useful for testing API endpoints directly from the command line.

```shell
curl \
  --request GET \
  --url 'https://api.ifthenpay.com/v1/countries' \
  --header 'accept: application/json'
```

--------------------------------

### Shell Curl Request Example

Source: https://www.ifthenpay.com/docs/en/api/list-of-payments-rest

This snippet shows how to make a request to the List of Payments API using curl. It includes common headers and parameters for retrieving payment data.

```Shell
curl -X GET \
  'https://api.ifthenpay.com/v1/payments?page=1&limit=20' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

--------------------------------

### Google Pay Callback URL Example

Source: https://www.ifthenpay.com/docs/en/guides/callback

This URL is triggered after a Google Pay payment is confirmed. It includes parameters for transaction verification and details.

```url
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
```

--------------------------------

### Successful Response for List of Payments

Source: https://www.ifthenpay.com/docs/en/api/list-of-payments-rest

This is an example of a successful JSON response when retrieving a list of payments. It includes details for each payment found.

```JSON
{
  "message": "OK",
  "status": 200,
  "payments": [
    {
      "amount": 22750,
      "entity": "MB",
      "fee": 0.86,
      "netAmount": 22749.14,
      "orderId": "000017273",
      "paymentDate": "21-10-2024 15:41:00",
      "procDate": "20241021",
      "reference": "007875810",
      "requestId": "wIh3HzFByfmj75Adl98x",
      "subEntity": "XXX-000000",
      "terminal": "5-0000000000-CAIXA GERAL DE "
    }
  ]
}
```

--------------------------------

### Direct Debit Callback URL Example

Source: https://www.ifthenpay.com/docs/en/guides/callback

This URL is triggered after a Direct Debit payment is confirmed. It includes parameters for transaction verification and details, with specific parameters for mandate and transaction IDs.

```url
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
```

--------------------------------

### Successful Operation Response (200 OK)

Source: https://www.ifthenpay.com/docs/en/api/multibanco

This is an example of a successful response when a MULTIBANCO payment reference is generated. It includes details like the generated reference, order ID, and expiration date.

```json
{
  "Amount": 10.99,
  "Entity": 11990,
  "ExpiryDate": "30-10-2021",
  "Message": "Success",
  "OrderId": 1887,
  "Reference": "000000291",
  "RequestId": "5Qd8gtWLAEUJ6n0lkS5g",
  "Status": "0"
}
```

--------------------------------

### Request Body Example

Source: https://www.ifthenpay.com/docs/en/api/multibanco

This JSON object represents the request body for a Multibanco payment. It includes essential details like merchant key, order ID, amount, description, and client information.

```json
{ "mbKey": "MB_KEY", "orderId": "1887", "amount": "10.99", "description": "order 1 payment", "url": "https://www.empresa.com", "clientCode": 123, "clientName": "John Doe", "clientEmail": "empresa@empresa.com", "clientUsername": "johndoe", "clientPhone": 351976543210, "expiryDays": "0"}
```

--------------------------------

### Activate Callback

Source: https://www.ifthenpay.com/docs/en/api/callback

This endpoint activates the payment callback for the account associated with the provided payment method and key. Upon a successful payment, ifthenpay will send a GET request to the provided callback URL (`urlCb`), replacing the placeholders with the actual transaction values.

```APIDOC
## POST /v2/callback/activation

### Description
Activates the payment callback for the account associated with the provided payment method and key.

### Method
POST

### Endpoint
/v2/callback/activation

### Parameters
#### Request Body
- **backofficeKey** (string) - Required - The BACKOFFICE KEY provided by ifthenpay.
- **paymentMethodKey** (string) - Required - The key of the payment method for which to activate the callback.
- **urlCb** (string) - Required - The callback URL to receive payment notifications.

### Request Example
```json
{
  "backofficeKey": "YOUR_BACKOFFICE_KEY",
  "paymentMethodKey": "YOUR_PAYMENT_METHOD_KEY",
  "urlCb": "https://yourdomain.com/callback"
}
```

### Response
#### Success Response (200)
- **message** (string) - A success message indicating the callback has been activated.

#### Response Example
```json
{
  "message": "Callback activated successfully."
}
```
```

--------------------------------

### Direct Debit Notification URL Example

Source: https://www.ifthenpay.com/docs/en/guides/callback

This URL receives the status of individual Direct Debit collection attempts (confirmed or refused). It includes parameters detailing the transaction status and outcome.

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

--------------------------------

### JWT Bearer Token Response (JSON)

Source: https://www.ifthenpay.com/docs/en/api/directdebit

This is an example of a successful response when generating a JWT bearer token. The response includes the token type, the access token, and its expiry date.

```json
{
  "data": {
    "token_type": "Bearer",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiry_date": "2024-11-05 13:49:58"
  }
}
```

--------------------------------

### Successful MB WAY Payment Response

Source: https://www.ifthenpay.com/docs/en/api/mbway

This is an example of a successful response when a new MB WAY payment is initiated. It includes the amount, a pending message, order ID, request ID, and status code.

```json
{
  "Amount": 10.99,
  "Message": "Pending",
  "orderId": 1887,
  "RequestId": "i2szvoUfPYBMWdSxqO3n",
  "Status": "000"
}
```

--------------------------------

### List Payments with Query Parameters (Shell)

Source: https://www.ifthenpay.com/docs/en/api/list-of-payments

Use this snippet to list payments by providing necessary query parameters such as BACKOFFICE_KEY, entidade, subentidade, and date ranges. Ensure all required fields are populated.

```shell
curl -X GET \
  'https://sandbox.ifthenpay.com/api/payments?entidade=11604&subentidade=999&dtHrInicio=23-05-2012%2000:00:00&dtHrFim=23-05-2012%2023:59:59&referencia=&Valor=&sandbox=0' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json'
```

--------------------------------

### Request New Payment Reference (POST /init)

Source: https://www.ifthenpay.com/docs/en/api/multibanco

Use this endpoint to generate a new MULTIBANCO payment reference for a transaction. Ensure you include all required fields such as 'mbKey', 'orderId', and 'amount'.

```shell
curl https://api.ifthenpay.com/multibanco/reference/init \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{ 
  "mbKey": "MB_KEY",
  "orderId": "1887",
  "amount": "10.99",
  "description": "order 1 payment",
  "url": "https://www.empresa.com",
  "clientCode": 123,
  "clientName": "John Doe",
  "clientEmail": "empresa@empresa.com",
  "clientUsername": "johndoe",
  "clientPhone": 351976543210,
  "expiryDays": "0"
}'
```

--------------------------------

### Initiate New Payment (Shell Curl)

Source: https://www.ifthenpay.com/docs/en/api/pix

Use this snippet to send a POST request to initiate a new PIX payment. Ensure you replace {PIX_KEY} with your actual PIX KEY and provide the necessary details in the request body.

```Shell
curl -X POST https://api.ifthenpay.com/pix/init/{PIX_KEY} \
-H "accept: application/json" \
-H "content-type: application/json" \
-d '{ "orderId": "order_45678", "amount": "11.55", "redirectUrl": "https://youraddress.com/status.php", "description": "Order 45678", "customerName": "John Doe", "customerCpf": "74026594025", "customerEmail": "johndoe@example.com", "customerPhone": "+351256245560", "customerAddress": "Main Street", "customerStreetNumber": "123", "customerZipCode": "12345", "customerCity": "New York", "customerState": "New York"}'
```

--------------------------------

### POST /init

Source: https://www.ifthenpay.com/docs/en/api/multibanco

Requests a new MULTIBANCO payment reference. This is the primary method for generating payment references for live transactions.

```APIDOC
## POST /init

### Description
Requests a new MULTIBANCO payment reference for live transactions.

### Method
POST

### Endpoint
https://api.ifthenpay.com/multibanco/reference/init

### Parameters
#### Request Body
- **mbKey** (string) - Required - Assigned by ifthenpay.
- **orderId** (string) - Required - Order/invoice number, with a maximum length of 25 characters.
- **amount** (string) - Required - Must contain exactly two decimal places using "." as the decimal separator.
- **description** (string) - Optional - Maximum length of 200 characters.
- **url** (string) - Optional - URL address, with a maximum length of 200 characters.
- **clientCode** (string) - Optional - Client's code, with a maximum length of 200 characters.
- **clientEmail** (string) - Optional - Client's email address, with a maximum length of 200 characters.
- **clientName** (string) - Optional - Client's name, with a maximum length of 200 characters.
- **clientPhone** (string) - Optional - Client's cell phone or phone number, with a maximum length of 200 characters.
- **clientUsername** (string) - Optional - Client's username, with a maximum length of 200 characters.
- **expiryDays** (number) - Optional - Specifies the number of days until the reference expires. If omitted, the reference may not have an expiration date. Values range from 0 (expires at midnight same day) up to 31 days. If a value outside this range is provided, the closest available duration will be assigned.

### Request Example
```json
{
  "mbKey": "MB_KEY",
  "orderId": "1887",
  "amount": "10.99",
  "description": "order 1 payment",
  "url": "https://www.empresa.com",
  "clientCode": "123",
  "clientName": "John Doe",
  "clientEmail": "empresa@empresa.com",
  "clientUsername": "johndoe",
  "clientPhone": "351976543210",
  "expiryDays": "0"
}
```

### Response
#### Success Response (200)
- **Amount** (number) - The amount of the payment.
- **Entity** (number) - The entity code associated with the payment.
- **ExpiryDate** (string) - The expiration date of the reference.
- **Message** (string) - A success message.
- **OrderId** (number) - The order ID associated with the payment.
- **Reference** (string) - The generated MULTIBANCO reference.
- **RequestId** (string) - The unique ID for the request.
- **Status** (string) - The status code of the operation (e.g., "0" for success).

### Response Example
```json
{
  "Amount": 10.99,
  "Entity": 11990,
  "ExpiryDate": "30-10-2021",
  "Message": "Success",
  "OrderId": 1887,
  "Reference": "000000291",
  "RequestId": "5Qd8gtWLAEUJ6n0lkS5g",
  "Status": "0"
}
```
```

--------------------------------

### POST /sandbox

Source: https://www.ifthenpay.com/docs/en/api/multibanco

Requests a new MULTIBANCO payment reference in sandbox mode, useful for testing integrations without affecting live data.

```APIDOC
## POST /sandbox

### Description
Requests a new MULTIBANCO payment reference in sandbox mode for testing purposes.

### Method
POST

### Endpoint
https://api.ifthenpay.com/multibanco/reference/sandbox

### Parameters
#### Request Body
- **mbKey** (string) - Required - Assigned by ifthenpay.
- **orderId** (string) - Required - Order/invoice number, with a maximum length of 25 characters.
- **amount** (string) - Required - Must contain exactly two decimal places using "." as the decimal separator.
- **description** (string) - Optional - Maximum length of 200 characters.
- **url** (string) - Optional - URL address, with a maximum length of 200 characters.
- **clientCode** (string) - Optional - Client's code, with a maximum length of 200 characters.
- **clientEmail** (string) - Optional - Client's email address, with a maximum length of 200 characters.
- **clientName** (string) - Optional - Client's name, with a maximum length of 200 characters.
- **clientPhone** (string) - Optional - Client's cell phone or phone number, with a maximum length of 200 characters.
- **clientUsername** (string) - Optional - Client's username, with a maximum length of 200 characters.
- **expiryDays** (number) - Optional - Specifies the number of days until the reference expires. If omitted, the reference may not have an expiration date. Values range from 0 (expires at midnight same day) up to 31 days. If a value outside this range is provided, the closest available duration will be assigned.

### Request Example
```json
{
  "mbKey": "MB_KEY",
  "orderId": "1887",
  "amount": "10.99",
  "description": "order 1 payment",
  "url": "https://www.empresa.com",
  "clientCode": "123",
  "clientName": "John Doe",
  "clientEmail": "empresa@empresa.com",
  "clientUsername": "johndoe",
  "clientPhone": "351976543210",
  "expiryDays": "0"
}
```

### Response
#### Success Response (200)
- **Amount** (number) - The amount of the payment.
- **Entity** (number) - The entity code associated with the payment.
- **ExpiryDate** (string) - The expiration date of the reference.
- **Message** (string) - A success message.
- **OrderId** (number) - The order ID associated with the payment.
- **Reference** (string) - The generated MULTIBANCO reference.
- **RequestId** (string) - The unique ID for the request.
- **Status** (string) - The status code of the operation (e.g., "0" for success).

### Response Example
```json
{
  "Amount": 10.99,
  "Entity": 11990,
  "ExpiryDate": "30-10-2021",
  "Message": "Success",
  "OrderId": 1887,
  "Reference": "000000291",
  "RequestId": "5Qd8gtWLAEUJ6n0lkS5g",
  "Status": "0"
}
```
```

--------------------------------

### Initiate New Payment

Source: https://www.ifthenpay.com/docs/en/api/pix

Initiates a new PIX payment request. Requires a PIX KEY and payment details in the request body.

```APIDOC
## POST /init/{PIX_KEY}

### Description
Initiates a new PIX payment request. Requires a PIX KEY and payment details in the request body.

### Method
POST

### Endpoint
https://api.ifthenpay.com/pix/init/{PIX_KEY}

### Parameters
#### Path Parameters
- **PIX_KEY** (string) - Required - The PIX KEY provided by ifthenpay.

#### Request Body
- **orderId** (string) - Required - The unique identifier for the order.
- **amount** (string) - Required - The payment amount.
- **redirectUrl** (string) - Required - The URL to redirect the user after payment.
- **description** (string) - Optional - A description for the payment.
- **customerName** (string) - Optional - The name of the customer.
- **customerCpf** (string) - Optional - The CPF (Cadastro de Pessoas Físicas) of the customer.
- **customerEmail** (string) - Optional - The email of the customer.
- **customerPhone** (string) - Optional - The phone number of the customer.
- **customerAddress** (string) - Optional - The address of the customer.
- **customerStreetNumber** (string) - Optional - The street number of the customer's address.
- **customerZipCode** (string) - Optional - The zip code of the customer's address.
- **customerCity** (string) - Optional - The city of the customer's address.
- **customerState** (string) - Optional - The state of the customer's address.

### Request Example
```json
{
  "orderId": "order_45678",
  "amount": "11.55",
  "redirectUrl": "https://youraddress.com/status.php",
  "description": "Order 45678",
  "customerName": "John Doe",
  "customerCpf": "74026594025",
  "customerEmail": "johndoe@example.com",
  "customerPhone": "+351256245560",
  "customerAddress": "Main Street",
  "customerStreetNumber": "123",
  "customerZipCode": "12345",
  "customerCity": "New York",
  "customerState": "New York"
}
```
```

--------------------------------

### Activate Payment Callback Request

Source: https://www.ifthenpay.com/docs/en/api/callback

This cURL command demonstrates how to activate a payment callback by sending a POST request to the /v2/callback/activation endpoint with the required JSON payload.

```Shell
curl https://api.ifthenpay.com/v2/callback/activation \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{ \
  "boKey": "BACKOFFICE_KEY", \
  "paymentMethod": "MB", \
  "paymentKey": "MB_KEY", \
  "apKey": "654fds46dsf4sjmc6565", \
  "urlCb": "https://www.yoursite.com/callback.php?key=[ANTI_PHISHING_KEY]&id=[ID]&amount=[AMOUNT]&payment_datetime=[PAYMENT_DATETIME]&payment_method=[PAYMENT_METHOD]" \
}'
```

--------------------------------

### Refund a Payment using cURL

Source: https://www.ifthenpay.com/docs/en/api/refund

Use this cURL command to initiate a refund for a payment. Ensure you replace placeholders with your actual backoffice key, request ID, and the refund amount.

```shell
curl https://api.ifthenpay.com/v2/payments/refund \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "backofficekey": "BACKOFFICE_KEY",
  "requestId": "36jvlEhUYeknQ8PHKprR",
  "amount": "11.55"
}'
```

--------------------------------

### List Payments (Shell Curl)

Source: https://www.ifthenpay.com/docs/en/api/list-of-payments-rest

This snippet demonstrates how to list payments using a shell curl command. It shows a basic request structure and expected response format.

```APIDOC
## List Payments

### Description
Retrieves a list of all payments made through the system. This endpoint is useful for auditing and tracking payment transactions.

### Method
GET

### Endpoint
/payments

### Parameters
This endpoint does not accept any path or query parameters.

### Request Body
This endpoint does not accept a request body.

### Request Example
```shell
curl -X GET "https://api.example.com/payments"
```

### Response
#### Success Response (200)
Returns a JSON array containing payment objects. Each object includes details such as payment ID, amount, status, and timestamp.

```json
[
  {
    "paymentId": "pay_123abc",
    "amount": 100.50,
    "status": "completed",
    "timestamp": "2023-10-27T10:00:00Z"
  },
  {
    "paymentId": "pay_456def",
    "amount": 75.20,
    "status": "pending",
    "timestamp": "2023-10-27T10:05:00Z"
  }
]
```
```

--------------------------------

### Retrieve List of Payments using cURL

Source: https://www.ifthenpay.com/docs/en/api/list-of-payments-rest

Use this cURL command to make a POST request to the /read endpoint to retrieve a list of payments. Include your backoffice key and optional parameters for filtering.

```Shell
curl https://api.ifthenpay.com/v2/payments/read \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{ \
  "boKey": "BACKOFFICE_KEY", \
  "entity": null, \
  "subEntity": null, \
  "reference": null, \
  "orderId": null, \
  "amount": null, \
  "requestId": null, \
  "dateStart": "21-10-2024 00:00:00", \
  "dateEnd": "21-10-2024 00:00:00" \
}'
```

--------------------------------

### Send Request using cURL

Source: https://www.ifthenpay.com/docs/en/api/multibanco

This cURL command demonstrates how to send a request to the Multibanco API. Ensure all necessary headers and the request body are correctly configured.

```shell
curl \
  --request GET \
  --header "accept: application/json" \
  --header "content-type: application/json" \
  --url 'https://api.ifthenpay.com/multibanco/v2/payment/1887/10.99/order%201%20payment/https://www.empresa.com/callback/123/John%20Doe/empresa@empresa.com/johndoe/351976543210/0/MB_KEY' \
  --data '{ "mbKey": "MB_KEY", "orderId": "1887", "amount": "10.99", "description": "order 1 payment", "url": "https://www.empresa.com", "clientCode": 123, "clientName": "John Doe", "clientEmail": "empresa@empresa.com", "clientUsername": "johndoe", "clientPhone": 351976543210, "expiryDays": "0"}'
```

--------------------------------

### Simple Checkout Link URL Structure

Source: https://www.ifthenpay.com/docs/en/guides/simple-checkout

This is the base URL structure for creating a Simple Checkout Link. Replace the bracketed placeholders with your specific order details and gateway key.

```URL
https://gateway.ifthenpay.com/?token=[TOKEN]&id=[ID]&amount=[AMOUNT]&description=[DESCRIPTION]&expire=[EXPIRE]&lang=[LANG]
```

--------------------------------

### Request New MB WAY Payment with cURL

Source: https://www.ifthenpay.com/docs/en/api/mbway

Use this cURL command to send a POST request to initiate a new MB WAY payment. Ensure all required fields in the JSON body are correctly populated.

```shell
curl https://api.ifthenpay.com/spg/payment/mbway \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{ 
  "mbWayKey": "MBWAY_KEY",
  "orderId": "1887",
  "amount": "10.99",
  "mobileNumber": "351#912345678",
  "email": "empresa@empresa.com",
  "description": "order 1 payment"
}'
```

--------------------------------

### Request New Payment Link and PINPAY Code (Shell Curl)

Source: https://www.ifthenpay.com/docs/en/api/pbl

Use this cURL command to send a POST request to generate a new payment link and PINPAY code. Ensure you replace {GATEWAY_KEY} with your actual key and provide the necessary JSON payload with payment details.

```shell
curl -X POST https://api.ifthenpay.com/gateway/pinpay/{GATEWAY_KEY} \
-H "accept: application/json" \
-H "content-type: application/json" \
-d "{
  "id": "1234",
  "amount": "21.50",
  "description": "Order 1234",
  "accounts": "MBWAY|XXX-000000;11686|000;MB|BEM-700700;...",
  "expiredate": 20301231,
  "success_url": "https://youraddress.com/sucess.php",
  "error_url": "https://youraddress.com/error.php",
  "cancel_url": "https://youraddress.com/cancel.php",
  "btnCloseUrl": "https://youraddress.com",
  "btnCloseLabel": "Close",
  "otp": "true",
  "lang": "pt",
  "selected_method": "1"
}"
```

--------------------------------

### Request New Payment

Source: https://www.ifthenpay.com/docs/en/api/mbway

Initiates a new MB WAY payment request. Requires payment details including amount, merchant key, customer's mobile number, order ID, and an optional description and email.

```APIDOC
## POST /mbway

### Description
Request a new MB WAY payment.

### Method
POST

### Endpoint
https://api.ifthenpay.com/spg/payment/mbway

### Parameters
#### Request Body
- **amount** (string) - Required - The payment amount. Example: 10.99
- **mbWayKey** (string) - Required - The MBWAY KEY assigned by ifthenpay.
- **mobileNumber** (string) - Required - The customer's mobile number, including country code separated by '#'. Example: 351#912345678
- **orderId** (string) - Required - Maximum length 15. Payment identifier defined by the client. Example: 1887
- **description** (string) - Optional - Maximum length 100. Description of the payment. Example: order 1 payment
- **email** (string) - Optional - Maximum length 100. Customer's email. Example: empresa@empresa.com

### Request Example
```json
{
  "mbWayKey": "MBWAY_KEY",
  "orderId": "1887",
  "amount": "10.99",
  "mobileNumber": "351#912345678",
  "email": "empresa@empresa.com",
  "description": "order 1 payment"
}
```

### Response
#### Success Response (200)
- **Amount** (number) - The amount of the payment.
- **Message** (string) - The status message of the payment. Example: Pending
- **orderId** (number) - The order identifier.
- **RequestId** (string) - A unique identifier for the request.
- **Status** (string) - The status code of the operation. Example: 000

#### Response Example
```json
{
  "Amount": 10.99,
  "Message": "Pending",
  "orderId": 1887,
  "RequestId": "i2szvoUfPYBMWdSxqO3n",
  "Status": "000"
}
```
```

--------------------------------

### Enable or Disable Pay by Link and Pinpay

Source: https://www.ifthenpay.com/docs/en/api/pbl

This endpoint allows you to enable or disable the Pay by Link and Pinpay services for your account. You need to provide your GATEWAY KEY and the desired status ('enable' or 'disable').

```APIDOC
## POST /pinpay/{GATEWAY_KEY}/{REQUEST_STATUS}

### Description
Enables or disables the Pay by Link and Pinpay services.

### Method
POST

### Endpoint
https://api.ifthenpay.com/gateway/pinpay/{GATEWAY_KEY}/{REQUEST_STATUS}

### Parameters
#### Path Parameters
- **GATEWAY_KEY** (string) - Required - Your unique GATEWAY KEY provided by ifthenpay.
- **REQUEST_STATUS** (string) - Required - The status to set, either 'enable' or 'disable'.

### Response
#### Success Response (200)
- **Message** (string) - Confirmation message indicating the status change.

#### Response Example
```json
{
  "Message": "Pay by Link and Pinpay enabled successfully."
}
```
```

--------------------------------

### Request New Payment Link and PINPAY Code

Source: https://www.ifthenpay.com/docs/en/api/pbl

This endpoint allows you to request a new payment link and a PINPAY code. You need to provide your GATEWAY KEY and details about the payment such as amount, description, and expiration date.

```APIDOC
## POST /pinpay/{GATEWAY_KEY}

### Description
Requests a new payment link and a PINPAY code.

### Method
POST

### Endpoint
https://api.ifthenpay.com/gateway/pinpay/{GATEWAY_KEY}

### Parameters
#### Path Parameters
- **GATEWAY_KEY** (string) - Required - Your unique GATEWAY KEY provided by ifthenpay.

#### Request Body
- **id** (string) - Required - Unique identifier for the transaction.
- **amount** (string) - Required - The amount to be paid.
- **description** (string) - Required - A description of the order or transaction.
- **accounts** (string) - Optional - Payment methods available, e.g., "MBWAY|XXX-000000;11686|000;MB|BEM-700700;..."
- **expiredate** (integer) - Optional - Expiration date in YYYYMMDD format.
- **success_url** (string) - Optional - URL to redirect to upon successful payment.
- **error_url** (string) - Optional - URL to redirect to upon payment error.
- **cancel_url** (string) - Optional - URL to redirect to upon payment cancellation.
- **btnCloseUrl** (string) - Optional - URL for a close button.
- **btnCloseLabel** (string) - Optional - Label for the close button.
- **otp** (string) - Optional - Set to "true" to enable OTP.
- **lang** (string) - Optional - Language code for the payment interface (e.g., "pt").
- **selected_method** (string) - Optional - Pre-selected payment method.

### Request Example
```json
{
  "id": "1234",
  "amount": "21.50",
  "description": "Order 1234",
  "accounts": "MBWAY|XXX-000000;11686|000;MB|BEM-700700;...",
  "expiredate": 20301231,
  "success_url": "https://youraddress.com/sucess.php",
  "error_url": "https://youraddress.com/error.php",
  "cancel_url": "https://youraddress.com/cancel.php",
  "btnCloseUrl": "https://youraddress.com",
  "btnCloseLabel": "Close",
  "otp": "true",
  "lang": "pt",
  "selected_method": "1"
}
```

### Response
#### Success Response (200)
- **PIN** (string) - The generated PIN code.
- **URL** (string) - The generated payment link.

#### Response Example
```json
{
  "PIN": "PINCODE123",
  "URL": "https://pay.ifthenpay.com/PINCODE123"
}
```
```

--------------------------------

### Retrieve List of Payments - JSON (cURL)

Source: https://www.ifthenpay.com/docs/en/api/list-of-payments

Use this cURL command to retrieve a list of all payments matching specified criteria in JSON format. Ensure the Content-Type header is removed if you encounter errors.

```shell
curl 'https://ifthenpay.com/ifmbws/ifmbws.asmx/getPaymentsJsonV2?chavebackoffice=BACKOFFICE_KEY&entidade=11604&subentidade=999&dtHrInicio=23-05-2012%2000%3A00%3A00&dtHrFim=23-05-2012%2023%3A59%3A59&referencia=%20&Valor=%20&sandbox=0' \
  --header 'Content-Type: '
```

--------------------------------

### Generate JWT Bearer Token (Shell Curl)

Source: https://www.ifthenpay.com/docs/en/api/directdebit

Use this cURL command to generate a JWT bearer token for authenticating subsequent API calls. Ensure you replace 'BACKOFFICE_KEY' with your actual ifthenpay backoffice key.

```shell
curl https://services.ifthenpay.com/directdebit/api/v1/auth/token \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{ 
  "backofficeKey": "BACKOFFICE_KEY"
}'
```

--------------------------------

### Activate Payment Callback

Source: https://www.ifthenpay.com/docs/en/api/callback

Activates the payment callback for the account associated with the specified payment method and key. This allows ifthenpay to notify your system about payment events.

```APIDOC
## POST /v2/callback/activation

### Description
Activates the payment callback for the account associated with the specified payment method and key.

### Method
POST

### Endpoint
https://api.ifthenpay.com/v2/callback/activation

### Parameters
#### Request Body
- **apKey** (string) - Required - Anti-phishing key used to validate the authenticity of the callback request. This value will replace the [ANTI_PHISHING_KEY] placeholder in the callback URL.
- **boKey** (string) - Required - Backoffice key that identifies the merchant account, provided by ifthenpay.
- **paymentKey** (string) - Required - The key associated with the payment method account provided by ifthenpay. For Offline Multibanco, this field must contain the Subentity value.
- **paymentMethod** (string) - Required - Payment method for which the callback is being activated. Use one of the following values: `MB`, `MBWAY`, `PAYSHOP`, `CCARD`, `GOOGLE`, `APPLE`, `PIX`, `DD`, `{ENTITY}` (for Offline Multibanco).
- **urlCb** (string) - Required - The callback URL that ifthenpay will call upon a successful payment. The available placeholders vary depending on the payment method used.

### Request Example
```json
{
  "boKey": "BACKOFFICE_KEY",
  "paymentMethod": "MB",
  "paymentKey": "MB_KEY",
  "apKey": "654fds46dsf4sjmc6565",
  "urlCb": "https://www.yoursite.com/callback.php?key=[ANTI_PHISHING_KEY]&id=[ID]&amount=[AMOUNT]&payment_datetime=[PAYMENT_DATETIME]&payment_method=[PAYMENT_METHOD]"
}
```

### Response
#### Success Response (200)
- **text/plain**: OK: Callback is activated with success
```

--------------------------------

### Retrieve List of Payments - JSON

Source: https://www.ifthenpay.com/docs/en/api/list-of-payments

Retrieve a List of All Payments Matching the Specified Criteria in JSON format. This endpoint allows you to fetch payment data in JSON format, which is useful for programmatic processing.

```APIDOC
## GET /getPaymentsJsonV2

### Description
Retrieve a list of all payments matching the specified criteria in JSON format.

### Method
GET

### Endpoint
https://ifthenpay.com/ifmbws/ifmbws.asmx/getPaymentsJsonV2

### Parameters
#### Query Parameters
- **chavebackoffice** (string) - Required - key provided by ifthenpay when signing the contract
- **entidade** (string) - Optional - entity (5 digits) or MB or MBWAY or PAYSHOP or CCARD or COFIDIS or GOOGLE or APPLE or PIX or TPA
- **subentidade** (string) - Optional - subentity (3 digits) or MB KEY or MBWAY Key or PAYSHOP KEY or CCARD KEY or COFIDIS KEY or GOOGLE KEY or APPLE KEY or PIX KEY or TPA KEY
- **dtHrInicio** (string) - Optional - start date/time of the desired payments in the format dd-MM-yyyy HH:mm
- **dtHrFim** (string) - Optional - end date/time of the desired payments in the format dd-MM-yyyy HH:mm
- **referencia** (string) - Optional - unique payment reference for Multibanco and Payshop; for other methods, it matches the orderId
- **Valor** (string) - Optional - amount in euros, decimal separator "."
- **sandbox** (string) - Optional - should indicate 1 or 0 depending on whether or not the test platform is used

### Request Example
```curl
curl 'https://ifthenpay.com/ifmbws/ifmbws.asmx/getPaymentsJsonV2?chavebackoffice=BACKOFFICE_KEY&entidade=11604&subentidade=999&dtHrInicio=23-05-2012%2000%3A00%3A00&dtHrFim=23-05-2012%2023%3A59%3A59&referencia=%20&Valor=%20&sandbox=0'
```

### Response
#### Success Response (200)
- **Entidade** (integer) - Entity of the payment
- **SubEntidade** (integer) - Subentity of the payment
- **Referencia** (integer) - Payment reference
- **Valor** (string) - Payment amount
- **Id** (integer) - Payment ID
- **DtHrPagamento** (string) - Date and time of payment
- **Processamento** (integer) - Processing information
- **Terminal** (string) - Terminal used for payment
- **Tarifa** (string) - Fee associated with the payment
- **ValorLiquido** (string) - Net amount after fees
- **CodigoErro** (string) - Error code, if any
- **MensagemErro** (string) - Error message, if any
- **Imagem** (null) - Image associated with the payment (if applicable)

#### Response Example
```json
[
  {
    "Entidade": 11604,
    "SubEntidade": 999,
    "Referencia": 0,
    "Valor": "63,35",
    "Id": 1234,
    "DtHrPagamento": "23-05-2012 09:31:13",
    "Processamento": 201205231,
    "Terminal": "5-0000000000-CAIXA GERAL DE DEPOSITOS",
    "Tarifa": "0,62",
    "ValorLiquido": "62,73",
    "CodigoErro": "0",
    "MensagemErro": "",
    "Imagem": null
  }
]
```
```

--------------------------------

### Refund a Payment

Source: https://www.ifthenpay.com/docs/en/api/refund

Refund a Payment made via MB WAY, Credit Card, Google Pay or Apple Pay. Supports partial refunds.

```APIDOC
## POST /refund

### Description
Refund a Payment made via MB WAY, Credit Card, Google Pay or Apple Pay.

### Method
POST

### Endpoint
https://api.ifthenpay.com/v2/payments/refund

### Parameters
#### Request Body
- **backofficekey** (string) - Required - key provided by ifthenpay when signing the contract
- **requestId** (string) - Required - token associated with the payment request transaction
- **amount** (string) - Required - amount to refund, decimal separator "."

### Request Example
```json
{
  "backofficekey": "BACKOFFICE_KEY",
  "requestId": "36jvlEhUYeknQ8PHKprR",
  "amount": "11.55"
}
```

### Response
#### Success Response (200)
- **Code** (integer) - Operation status code.
- **Message** (string) - Operation status message.

#### Response Example
```json
{
  "Code": 0,
  "Message": "Payment could not be refunded"
}
```
```

--------------------------------

### Check Payment Status

Source: https://www.ifthenpay.com/docs/en/api/pix

Checks the status of a previously initiated PIX payment request.

```APIDOC
## GET /payment/status/

### Description
Checks the status of a previously initiated PIX payment request.

### Method
GET

### Endpoint
https://api.ifthenpay.com/pix/payment/status/

### Parameters
#### Query Parameters
- **pix_key** (string) - Required - The PIX KEY associated with the payment.
- **order_id** (string) - Required - The order ID of the payment to check.

### Response
#### Success Response (200)
- **status** (string) - The status of the payment (e.g., "PAID", "PENDING", "CANCELLED").
- **message** (string) - A message describing the payment status.
```

--------------------------------

### Check Payment Status

Source: https://www.ifthenpay.com/docs/en/api/mbway

Checks the status of an existing MB WAY payment using the order ID.

```APIDOC
## GET /mbway/status

### Description
Check the status of a payment.

### Method
GET

### Endpoint
https://api.ifthenpay.com/spg/payment/mbway/status

### Parameters
#### Query Parameters
- **orderId** (string) - Required - The order identifier for which to check the status.

### Response
#### Success Response (200)
- **Amount** (number) - The amount of the payment.
- **Message** (string) - The status message of the payment.
- **orderId** (number) - The order identifier.
- **RequestId** (string) - A unique identifier for the request.
- **Status** (string) - The status code of the operation.
```

--------------------------------

### Generate JWT Bearer Token

Source: https://www.ifthenpay.com/docs/en/api/directdebit

Generates a JSON Web Token (JWT) for authenticating subsequent API calls. Requires your ifthenpay 'DD KEY'.

```APIDOC
## POST /api/v1/auth/token

### Description
Allows the user to generate a JSON Web Token (JWT) that serves as secure authentication for the remaining API methods. All subsequent API calls require this bearer token in the header.

### Method
POST

### Endpoint
https://services.ifthenpay.com/directdebit/api/v1/auth/token

### Parameters
#### Request Body
- **backofficeKey** (string) - Required - The ifthenpay backoffice key provided to the user for authentication.

### Request Example
```json
{
  "backofficeKey": "BACKOFFICE_KEY"
}
```

### Response
#### Success Response (201)
- **token_type** (string) - The type of token, typically 'Bearer'.
- **access_token** (string) - The generated JWT.
- **expiry_date** (string) - The expiration date and time of the token.

#### Response Example
```json
{
  "data": {
    "token_type": "Bearer",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiry_date": "2024-11-05 13:49:58"
  }
}
```
```
Tokens:
Raw