Purchase Class

The Purchase class processes the IPCPurchase method, which initiates a **redirect-based payment flow. **It collects customer, cart, and configuration details and sends them securely to myPOS for payment processing.

Class Details

Namespace: Mypos\IPC
Located at: Purchase.php
Extends: Mypos\IPC\Base
Purpose: Build and initiate a standard myPOS payment session using a hosted payment page.

Method Summary

Method	Return Type	Description
`__construct(Config $cnf)`	-	Initializes the purchase with a config object.
`setOrderID(string $orderID)`	Purchase	Sets a unique ID for the transaction.
`getOrderID()`	string	Retrieves the order ID.
`setCurrency(string $currency)`	Purchase	Sets the 3-letter ISO currency code.
`getCurrency()`	string	Retrieves the currency code.
`setNote(string $note)`	Purchase	Optional note attached to the transaction.
`getNote()`	string	Returns the transaction note.
`setCart(Cart $cart)`	Purchase	Attaches a purchase cart with items.
`getCart()`	Cart	Retrieves the cart object.
`setCustomer(Customer $customer)`	Purchase	Attaches a customer object with billing/shipping info.
`getCustomer()`	Customer	Retrieves the customer object.
`setUrlOk(string $url)`	Purchase	Redirect URL after successful payment.
`getUrlOk()`	string	Returns the success URL.
`setUrlCancel(string $url)`	Purchase	Redirect URL after failed or canceled payment.
`getUrlCancel()`	string	Returns the cancel URL.
`setUrlNotify(string $url)`	Purchase	Server-to-server webhook for payment status.
`getUrlNotify()`	string	Returns the notify URL.
`setCardTokenRequest(int $flag)`	Purchase	Enables card tokenization (for future use).
`getCardTokenRequest()`	int	Returns card token request mode.
`setPaymentParametersRequired(int $flag)`	Purchase	Sets required customer/payment info level.
`getPaymentParametersRequired()`	int	Returns payment parameter mode.
`setPaymentMethod(mixed $method)`	Purchase	Sets preferred payment method.
`getPaymentMethod()`	mixed	Returns current payment method setting.
`validate()`	bool	Validates that all required fields are set.
`process()`	bool	Sends the request and redirects the customer to the payment page.

Constants Summary

Purchase Type

Constant	Value	Description
`PURCHASE_TYPE_FULL`	1	Full redirect flow with customer and cart info.
`PURCHASE_TYPE_SIMPLIFIED_CALL`	2	Simplified API call.
`PURCHASE_TYPE_SIMPLIFIED_PAYMENT_PAGE`	3	Lightweight hosted page without extra input.

Card Tokenization Options

Constant	Value	Description
`CARD_TOKEN_REQUEST_NONE`	0	No card token is returned.
`CARD_TOKEN_REQUEST_ONLY_STORE`	1	Only store the card without a payment.
`CARD_TOKEN_REQUEST_PAY_AND_STORE`	2	Process payment and store the card.

Payment Method Options

Constant	Value	Description
`PAYMENT_METHOD_STANDARD`	1	Use standard card payment methods.
`PAYMENT_METHOD_IDEAL`	2	Use iDEAL (Netherlands only).
`PAYMENT_METHOD_BOTH`	3	Show both options if available.

Example Usage

<?php

namespace Mypos\IPC;

/**
 * Process IPC method: IPCPurchase.
 * Collect, validate and send API params
 */
class Purchase extends Base
{
    const PURCHASE_TYPE_FULL = 1;
    const PURCHASE_TYPE_SIMPLIFIED_CALL = 2;
    const PURCHASE_TYPE_SIMPLIFIED_PAYMENT_PAGE = 3;

    const CARD_TOKEN_REQUEST_NONE = 0;
    const CARD_TOKEN_REQUEST_ONLY_STORE = 1;
    const CARD_TOKEN_REQUEST_PAY_AND_STORE = 2;

    const PAYMENT_METHOD_STANDARD = 1;
    const PAYMENT_METHOD_IDEAL = 2;
    const PAYMENT_METHOD_BOTH = 3;
    /**
     * @var Cart
     */
    private $cart;
    /**
     * @var Customer
     */
    private $customer;
    private $url_ok, $url_cancel, $url_notify;
    private $currency = 'EUR', $note, $orderID, $cardTokenRequest, $paymentParametersRequired;
    private $paymentMethod;

    /**
     * Return purchase object
     *
     * @param Config $cnf
     */
    public function __construct(Config $cnf)
    {
        $this->setCnf($cnf);
    }

    /**
     * Purchase identifier - must be unique
     *
     * @param string $orderID
     *
     * @return Purchase
     */
    public function setOrderID($orderID)
    {
        $this->orderID = $orderID;

        return $this;
    }

    /**
     * Optional note to purchase
     *
     * @param string $note
     *
     * @return Purchase
     */
    public function setNote($note)
    {
        $this->note = $note;

        return $this;
    }

    /**
     * Merchant Site URL where client comes after unsuccessful payment
     *
     * @param string $urlCancel
     *
     * @return Purchase
     */
    public function setUrlCancel($urlCancel)
    {
        $this->url_cancel = $urlCancel;

        return $this;
    }

    /**
     * Merchant Site URL where IPC posts Purchase Notify requests
     *
     * @param string $urlNotify
     *
     * @return Purchase
     */
    public function setUrlNotify($urlNotify)
    {
        $this->url_notify = $urlNotify;

        return $this;
    }

    /**
     * Whether to return Card Token for current client card
     *
     * @param integer $cardTokenRequest
     */
    public function setCardTokenRequest($cardTokenRequest)
    {
        $this->cardTokenRequest = $cardTokenRequest;
    }

    /**
     * Defines the packet of details needed from merchant and client to make payment
     *
     * @param integer $paymentParametersRequired
     */
    public function setPaymentParametersRequired($paymentParametersRequired)
    {
        $this->paymentParametersRequired = $paymentParametersRequired;
    }

    /**
     * Initiate API request
     *
     * @return boolean
     */
    public function process()
    {
        $this->validate();

        $this->_addPostParam('IPCmethod', 'IPCPurchase');
        $this->_addPostParam('IPCVersion', $this->getCnf()->getVersion());
        $this->_addPostParam('IPCLanguage', $this->getCnf()->getLang());
        $this->_addPostParam('SID', $this->getCnf()->getSid());
        $this->_addPostParam('WalletNumber', $this->getCnf()->getWallet());
        $this->_addPostParam('KeyIndex', $this->getCnf()->getKeyIndex());
        $this->_addPostParam('Source', $this->getCnf()->getSource());

        $this->_addPostParam('Currency', $this->getCurrency());
        if (!$this->isNoCartPurchase()) {
            $this->_addPostParam('Amount', $this->cart->getTotal());
        }

        $this->_addPostParam('OrderID', $this->getOrderID());
        $this->_addPostParam('URL_OK', $this->getUrlOk());
        $this->_addPostParam('URL_Cancel', $this->getUrlCancel());
        $this->_addPostParam('URL_Notify', $this->getUrlNotify());

        $this->_addPostParam('Note', $this->getNote());

        if ($this->getPaymentParametersRequired() != self::PURCHASE_TYPE_SIMPLIFIED_PAYMENT_PAGE) {
            $this->_addPostParam('customeremail', $this->getCustomer()->getEmail());
            $this->_addPostParam('customerphone', $this->getCustomer()->getPhone());
            $this->_addPostParam('customerfirstnames', $this->getCustomer()->getFirstName());
            $this->_addPostParam('customerfamilyname', $this->getCustomer()->getLastName());
            $this->_addPostParam('customercountry', $this->getCustomer()->getCountry());
            $this->_addPostParam('customercity', $this->getCustomer()->getCity());
            $this->_addPostParam('customerzipcode', $this->getCustomer()->getZip());
            $this->_addPostParam('customeraddress', $this->getCustomer()->getAddress());
        }

        if (!$this->isNoCartPurchase()) {
            $this->_addPostParam('CartItems', $this->cart->getItemsCount());
            $items = $this->cart->getCart();
            $i = 1;
            foreach ($items as $v) {
                $this->_addPostParam('Article_' . $i, $v['name']);
                $this->_addPostParam('Quantity_' . $i, $v['quantity']);
                $this->_addPostParam('Price_' . $i, $v['price']);
                $this->_addPostParam('Amount_' . $i, $v['price'] * $v['quantity']);
                $this->_addPostParam('Currency_' . $i, $this->getCurrency());
                $i++;
            }
        }

        $this->_addPostParam('CardTokenRequest', $this->getCardTokenRequest());
        $this->_addPostParam('PaymentParametersRequired', $this->getPaymentParametersRequired());
        $this->_addPostParam('PaymentMethod', $this->getPaymentMethod());

        $this->_processHtmlPost();

        return true;
    }

    /**
     * Validate all set purchase details
     *
     * @return boolean
     * @throws IPC_Exception
     */
    public function validate()
    {

        if ($this->getUrlCancel() === null || !Helper::isValidURL($this->getUrlCancel())) {
            throw new IPC_Exception('Invalid Cancel URL');
        }

        if ($this->getUrlNotify() === null || !Helper::isValidURL($this->getUrlNotify())) {
            throw new IPC_Exception('Invalid Notify URL');
        }

        if ($this->getUrlOk() === null || !Helper::isValidURL($this->getUrlOk())) {
            throw new IPC_Exception('Invalid Success URL');
        }

        if ($this->getCardTokenRequest() === null || !in_array($this->getCardTokenRequest(), [
                self::CARD_TOKEN_REQUEST_NONE,
                self::CARD_TOKEN_REQUEST_ONLY_STORE,
                self::CARD_TOKEN_REQUEST_PAY_AND_STORE,
            ])) {
            throw new IPC_Exception('Invalid value provided for CardTokenRequest params');
        }

        if ($this->getPaymentParametersRequired() === null || !in_array($this->getPaymentParametersRequired(), [
                self::PURCHASE_TYPE_FULL,
                self::PURCHASE_TYPE_SIMPLIFIED_CALL,
                self::PURCHASE_TYPE_SIMPLIFIED_PAYMENT_PAGE,
            ])) {
            throw new IPC_Exception('Invalid value provided for PaymentParametersRequired params');
        }

        if ($this->getCurrency() === null) {
            throw new IPC_Exception('Invalid currency');
        }

        try {
            $this->getCnf()->validate();
        } catch (\Exception $ex) {
            throw new IPC_Exception('Invalid Config details: ' . $ex->getMessage());
        }

        if (!$this->isNoCartPurchase()) {
            try {
                $this->getCart()->validate();
            } catch (\Exception $ex) {
                throw new IPC_Exception('Invalid Cart details: ' . $ex->getMessage());
            }
        }

        if ($this->getPaymentParametersRequired() == self::PURCHASE_TYPE_FULL) {
            try {
                if (!$this->getCustomer()) {
                    throw new IPC_Exception('Customer details not set!');
                }
                $this->getCustomer()->validate($this->getPaymentParametersRequired());
            } catch (\Exception $ex) {
                throw new IPC_Exception('Invalid Customer details: ' . $ex->getMessage());
            }
        }

        return true;
    }

    /**
     * Merchant Site URL where client comes after unsuccessful payment
     *
     * @return string
     */
    public function getUrlCancel()
    {
        return $this->url_cancel;
    }

    /**
     * Merchant Site URL where IPC posts Purchase Notify requests
     *
     * @var string
     */
    public function getUrlNotify()
    {
        return $this->url_notify;
    }

    /**
     * Merchant Site URL where client comes after successful payment
     *
     * @return string
     */
    public function getUrlOk()
    {
        return $this->url_ok;
    }

    /**
     * Merchant Site URL where client comes after successful payment
     *
     * @param string $urlOk
     *
     * @return Purchase
     */
    public function setUrlOk($urlOk)
    {
        $this->url_ok = $urlOk;

        return $this;
    }

    /**
     * Whether to return Card Token for current client card
     *
     * @return integer
     */
    public function getCardTokenRequest()
    {
        return $this->cardTokenRequest;
    }

    /**
     * Defines the packet of details needed from merchant and client to make payment
     *
     * @return integer
     */
    public function getPaymentParametersRequired()
    {
        return $this->paymentParametersRequired;
    }

    /**
     * ISO-4217 Three letter currency code
     *
     * @return string
     */
    public function getCurrency()
    {
        return $this->currency;
    }

    /**
     * ISO-4217 Three letter currency code
     *
     * @param string $currency
     *
     * @return Purchase
     */
    public function setCurrency($currency)
    {
        $this->currency = $currency;

        return $this;
    }

    /**
     * If request is only for card token request without payment, the Amount and Cart params are not required
     *
     * @return bool
     */
    private function isNoCartPurchase()
    {
        return $this->getCardTokenRequest() == self::CARD_TOKEN_REQUEST_ONLY_STORE;
    }

    /**
     * Cart object
     *
     * @return Cart
     */
    public function getCart()
    {
        return $this->cart;
    }

    /**
     * Cart object
     *
     * @param Cart $cart
     *
     * @return Purchase
     */
    public function setCart(Cart $cart)
    {
        $this->cart = $cart;

        return $this;
    }

    /**
     * @return Customer
     */
    public function getCustomer()
    {
        return $this->customer;
    }

    /**
     * Customer object
     *
     * @param Customer $customer
     *
     * @return Purchase
     */
    public function setCustomer(Customer $customer)
    {
        $this->customer = $customer;

        return $this;
    }

    /**
     * Purchase identifier
     *
     * @return string
     */
    public function getOrderID()
    {
        return $this->orderID;
    }

    /**
     * Optional note to purchase
     *
     * @return string
     */
    public function getNote()
    {
        return $this->note;
    }

    /**
     * @return mixed
     */
    public function getPaymentMethod()
    {
        return $this->paymentMethod;
    }

    /**
     * @param mixed $paymentMethod
     */
    public function setPaymentMethod($paymentMethod)
    {
        $this->paymentMethod = $paymentMethod;
    }


}

Use Cases

Use the Purchase class when:

You want to use hosted payment pages for PCI compliance
You’re integrating redirect-based payments
You need optional card tokenization
You want to support standard and iDEAL payment flows