ifthenpay Payments MCP

Creates a Multibanco payment reference that the customer can use to pay at any ATM or via online banking in Portugal.

{
  "type": "object",
  "properties": {
    "mb_key": {
      "type": "string",
      "description": "ifthenpay Multibanco key."
    },
    "order_id": {
      "type": "string",
      "description": "Unique order identifier in your system."
    },
    "amount": {
      "type": "number",
      "description": "Payment amount in EUR (e.g. 10.50)."
    },
    "expiry_days": {
      "type": "integer",
      "description": "Number of days until the reference expires. Defaults to no expiry if omitted."
    }
  },
  "required": [
    "mb_key",
    "order_id",
    "amount"
  ]
}

Sends an MB WAY payment request to the customer's mobile phone. The customer approves the payment in the MB WAY app. Use mbway_check_status to check the result.

{
  "type": "object",
  "properties": {
    "mbway_key": {
      "type": "string",
      "description": "ifthenpay MB WAY key."
    },
    "order_id": {
      "type": "string",
      "description": "Unique order identifier in your system (max 15 characters)."
    },
    "amount": {
      "type": "number",
      "description": "Payment amount in EUR (e.g. 10.50)."
    },
    "phone": {
      "type": "string",
      "description": "Customer mobile number in format \"351#912345678\" (country code # number)."
    },
    "description": {
      "type": "string",
      "description": "Short payment description shown in the MB WAY app."
    }
  },
  "required": [
    "mbway_key",
    "order_id",
    "amount",
    "phone"
  ]
}

Checks the status of a previously requested MB WAY payment. Returns pending, paid, declined, timeout, or cancelled.

{
  "type": "object",
  "properties": {
    "mbway_key": {
      "type": "string",
      "description": "ifthenpay MB WAY key."
    },
    "request_id": {
      "type": "string",
      "description": "Request ID returned by mbway_request_payment."
    }
  },
  "required": [
    "mbway_key",
    "request_id"
  ]
}

Creates a Payshop payment reference that the customer can use to pay at any Payshop agent or CTT (postal service) in Portugal.

{
  "type": "object",
  "properties": {
    "payshop_key": {
      "type": "string",
      "description": "ifthenpay Payshop key."
    },
    "order_id": {
      "type": "string",
      "description": "Unique order identifier in your system (max 25 characters)."
    },
    "amount": {
      "type": "number",
      "description": "Payment amount in EUR (e.g. 10.50)."
    },
    "expiry_date": {
      "type": "string",
      "description": "Expiry date in YYYYMMDD format (e.g. 20301231). Leave blank for no expiry."
    }
  },
  "required": [
    "payshop_key",
    "order_id",
    "amount"
  ]
}

Creates a credit/debit card payment session and returns a payment URL. The customer is redirected to a hosted checkout page to complete payment with their card.

{
  "type": "object",
  "properties": {
    "ccard_key": {
      "type": "string",
      "description": "ifthenpay Credit Card key."
    },
    "order_id": {
      "type": "string",
      "description": "Unique order identifier in your system (max 15 characters)."
    },
    "amount": {
      "type": "number",
      "description": "Payment amount in EUR (e.g. 10.50)."
    },
    "success_url": {
      "type": "string",
      "description": "URL to redirect the customer after a successful payment."
    },
    "error_url": {
      "type": "string",
      "description": "URL to redirect the customer if the payment fails."
    },
    "cancel_url": {
      "type": "string",
      "description": "URL to redirect the customer if they cancel the payment."
    },
    "language": {
      "type": "string",
      "description": "Language for the checkout page (e.g. \"pt\", \"en\"). Defaults to \"pt\"."
    }
  },
  "required": [
    "ccard_key",
    "order_id",
    "amount",
    "success_url",
    "error_url",
    "cancel_url"
  ]
}

Creates a Pay by Link / PINPAY payment. Returns a shareable payment URL and a PIN code. The hosted checkout supports multiple payment methods including Credit Card, Google Pay, and Apple Pay.

{
  "type": "object",
  "properties": {
    "gateway_key": {
      "type": "string",
      "description": "ifthenpay Gateway key for Pay by Link / PINPAY."
    },
    "order_id": {
      "type": "string",
      "description": "Unique order identifier in your system (max 15 characters)."
    },
    "amount": {
      "type": "number",
      "description": "Payment amount in EUR (e.g. 10.50)."
    },
    "description": {
      "type": "string",
      "description": "Short description shown on the payment page (max 200 characters)."
    },
    "success_url": {
      "type": "string",
      "description": "URL to redirect the customer after a successful payment."
    },
    "error_url": {
      "type": "string",
      "description": "URL to redirect the customer if the payment fails."
    },
    "cancel_url": {
      "type": "string",
      "description": "URL to redirect the customer if they cancel."
    },
    "expiry_date": {
      "type": "string",
      "description": "Link expiry date in YYYYMMDD format (e.g. 20301231). Leave blank for no expiry."
    },
    "lang": {
      "type": "string",
      "description": "Language for the payment page: pt, en, es, fr. Defaults to pt."
    },
    "accounts": {
      "type": "string",
      "description": "Payment methods to show in the gateway, separated by semicolons. Format: METHOD|KEY (e.g. \"MBWAY|MBWAY-KEY;MB|MB-KEY;PAYSHOP|PAYSHOP-KEY;CCARD|CCARD-KEY\"). Leave blank to use gateway defaults."
    },
    "selected_method": {
      "type": "string",
      "enum": [
        "1",
        "2",
        "3",
        "4",
        "7",
        "8"
      ],
      "description": "Pre-select a payment method: 1=Multibanco, 2=MB WAY, 3=Payshop, 4=Credit Card, 8=Pix."
    },
    "otp": {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "description": "One-time payment: \"true\" makes the link expire after a single payment."
    },
    "btn_close_url": {
      "type": "string",
      "description": "URL for the close/back button on the payment page."
    },
    "btn_close_label": {
      "type": "string",
      "description": "Label text for the close/back button."
    }
  },
  "required": [
    "gateway_key",
    "order_id",
    "amount"
  ]
}

Creates a PIX payment for Brazilian customers. Returns a payment URL and a QR code value. Customer must have a CPF number (Brazilian tax ID).

{
  "type": "object",
  "properties": {
    "pix_key": {
      "type": "string",
      "description": "ifthenpay PIX key."
    },
    "order_id": {
      "type": "string",
      "description": "Unique order identifier in your system (max 25 characters)."
    },
    "amount": {
      "type": "number",
      "description": "Payment amount in BRL (e.g. 50.00)."
    },
    "redirect_url": {
      "type": "string",
      "description": "URL to redirect the customer after payment. Check payment status via the status API after redirect."
    },
    "customer_name": {
      "type": "string",
      "description": "Full name of the customer (max 150 characters)."
    },
    "customer_cpf": {
      "type": "string",
      "description": "Customer CPF number (Brazilian tax ID), digits only (e.g. 74026594025)."
    },
    "customer_email": {
      "type": "string",
      "description": "Customer email address."
    },
    "customer_phone": {
      "type": "string",
      "description": "Customer phone number including country code (e.g. +5585912345678)."
    },
    "description": {
      "type": "string",
      "description": "Short description or reference for the payment (max 200 characters)."
    },
    "customer_address": {
      "type": "string",
      "description": "Customer street address."
    },
    "customer_city": {
      "type": "string",
      "description": "Customer city."
    },
    "customer_state": {
      "type": "string",
      "description": "Customer state (e.g. CE, SP)."
    },
    "customer_zip_code": {
      "type": "string",
      "description": "Customer postal/ZIP code."
    }
  },
  "required": [
    "pix_key",
    "order_id",
    "amount",
    "redirect_url",
    "customer_name",
    "customer_cpf",
    "customer_email",
    "customer_phone"
  ]
}

Lists completed payments using the ifthenpay Backoffice Key. Filter by payment method, date range, order ID, reference or request ID. Returns up to 1000 most recent payments if no filters are applied.

{
  "type": "object",
  "properties": {
    "bo_key": {
      "type": "string",
      "description": "ifthenpay Backoffice Key (provided when signing the contract)."
    },
    "entity": {
      "type": "string",
      "description": "Payment method entity filter. Use: MB, MBWAY, PAYSHOP, CCARD, GOOGLE, APPLE, PIX, or a 5-digit Multibanco entity number. Leave blank for all methods."
    },
    "sub_entity": {
      "type": "string",
      "description": "Payment method key or sub-entity (e.g. MB KEY, MBWAY KEY, PAYSHOP KEY). Leave blank to match all."
    },
    "order_id": {
      "type": "string",
      "description": "Filter by order identifier."
    },
    "reference": {
      "type": "string",
      "description": "Filter by payment reference (Multibanco/Payshop reference or orderId for other methods)."
    },
    "request_id": {
      "type": "string",
      "description": "Filter by the unique request token returned at payment creation."
    },
    "amount": {
      "type": "string",
      "description": "Filter by exact payment amount."
    },
    "date_start": {
      "type": "string",
      "description": "Start date/time in format dd-MM-yyyy HH:mm:ss (e.g. 01-01-2024 00:00:00)."
    },
    "date_end": {
      "type": "string",
      "description": "End date/time in format dd-MM-yyyy HH:mm:ss (e.g. 31-01-2024 23:59:59)."
    }
  },
  "required": [
    "bo_key"
  ]
}