README

Example for a RatePAY checkout

You need to send at least the following gateway operations:

PAYMENT_INIT -> PAYMENT_REQUEST -> PAYMENT_CONFIRM

use Doctrine\Common\Annotations\AnnotationRegistry;
use GuzzleHttp\Client;
use PHPCommerce\Vendor\RatePAY\Service\Payment\Exception\RatePAYException;
use PHPCommerce\Vendor\RatePAY\Service\Payment\GatewayClientImpl;
use PHPCommerce\Vendor\RatePAY\Service\Payment\RatepayBrokerImpl;
use PHPCommerce\Vendor\RatePAY\Service\Payment\RatepayConfiguration;
use PHPCommerce\Vendor\RatePAY\Service\Payment\RatepayCredential;
use PHPCommerce\Vendor\RatePAY\Service\Payment\Type\AddressType;
use PHPCommerce\Vendor\RatePAY\Service\Payment\Type\ContactsType;
use PHPCommerce\Vendor\RatePAY\Service\Payment\Type\CustomerType;
use PHPCommerce\Vendor\RatePAY\Service\Payment\Type\ExternalType;
use PHPCommerce\Vendor\RatePAY\Service\Payment\Type\PaymentType;
use PHPCommerce\Vendor\RatePAY\Service\Payment\Type\RequestHeadType;
use PHPCommerce\Vendor\RatePAY\Service\Payment\Type\PhoneType;
use PHPCommerce\Vendor\RatePAY\Service\Payment\Type\RequestType;
use PHPCommerce\Vendor\RatePAY\Service\Payment\Type\ShoppingBasketItemType;
use PHPCommerce\Vendor\RatePAY\Service\Payment\Type\ShoppingBasketType;
use PHPCommerce\Vendor\RatePAY\Service\Payment\DeviceFingerprintSnippetGenerator;

require_once('vendor/autoload.php');

AnnotationRegistry::registerAutoloadNamespace(
    'JMS\Serializer\Annotation',
    __DIR__ . "/vendor/jms/serializer/src");
    
//Client := Guzzle 6.x compatible client
$client = new GatewayClientImpl(new Client(), 'https://gateway-int.ratepay.com/api/xml/1_0');

// you can optionally define a logger which will receice debug log messages from the GatewayClient
//$client->setLogger(new Logger());

$ratepayConfiguration = (new RatepayConfiguration())
    ->setGatewayRequestCredentialProfileId("you-profile-id")
    ->setGatewayRequestCredentialSecuritycode("your-security-code")
    ->setGatewayRequestSystemId("systemId");

$ratepayBroker = new RatepayBrokerImpl($ratepayConfiguration, $client);

try {
    $fingerprinter = new DeviceFingerprintSnippetGenerator("4R8Pay");

    $transactionId = $ratepayBroker->paymentInit();

    $paymentRequest = $ratepayBroker->getRequestBuilder()
        ->external(
            (new ExternalType())
                ->setMerchantConsumerId("D1234567890")
                ->setOrderId("50001234")
        )
        ->customer((new CustomerType())
            ->setFirstName("Max")
            ->setLastName("Mustermann")
            ->setGender(CustomerType::GENDER_MALE)
            ->setDateOfBirth(new DateTime("1985-01-01"))
            ->setIpAddress("123.123.123.123")
            ->setCustomerAllowCreditInquiry(true)
            ->setContacts(
                (new ContactsType())
                    ->setEmail("max.mustermann@test.de")
                    ->setPhone(
                        (new PhoneType ())
                            ->setAreaCode("040")
                            ->setDirectDial("1234567890")
                    )
            )
            ->setAddresses([
                (new AddressType())
                    ->setType(AddressType::ADDRESS_TYPE_BILLING)
                    ->setFirstName("Max")
                    ->setLastName("Mustermann")
                    ->setStreet("Musterstraße")
                    ->setStreetNumber("77")
                    ->setZipCode("12345")
                    ->setCity("Musterstadt")
                    ->setCountryCode('DE')
            ])
        )
        ->shoppingBasket(
            (new ShoppingBasketType())
                ->setAmount(100)
                ->setCurrency('EUR')
                ->setItems([
                    (new ShoppingBasketItemType())
                        ->setArticleNumber("123")
                        ->setQuantity("1")
                        ->setUnitPriceGross(100)
                        ->setItem("Artcile 1")
                ])
        )
        ->payment(
            (new PaymentType())
                ->setMethod(PaymentType::METHOD_INVOICE)
                ->setCurrency(PaymentType::CURRENCY_EUR)
                ->setAmount(100)
        )
        ->build();

    $res = $ratepayBroker->paymentRequest($transactionId, $paymentRequest);

    /** @var PaymentRequestResponseType $paymentRequestResponse */
    $paymentRequestResponse = $res->getContent();

    $descriptor = $paymentRequestResponse->getPayment()->getDescriptor();
    
    // save $descriptor for your reference
			
    $ratepayBroker->paymentConfirm($transactionId);

} catch (RatePAYException $e) {
    $message = ($e->getCustomerMessage() != "") ?
        $e->getCustomerMessage() : "The RatePAY transaction could not be processed";

    echo $message;
}

Triggering a payment change request

    $paymentChange = $ratepayBroker->getRequestBuilder()
        ->shoppingBasket(
            (new ShoppingBasketType())
                ->setAmount(1000)
                ->setCurrency('EUR')
                ->setItems([
                    (new ShoppingBasketItemType())
                        ->setArticleNumber("123")
                        ->setQuantity("10")
                        ->setUnitPriceGross(100)
                        ->setItem("Article 1")
                ])
        )
        ->build();

    $res = $ratepayBroker->paymentChange($transactionId, OperationType::OPERATION_SUBTYPE_CHANGE_ORDER, $paymentChange);

Triggering a confirmation deliver request

    $confirmationDeliver = $ratepayBroker->getRequestBuilder()
        ->shoppingBasket(
            (new ShoppingBasketType())
                ->setAmount(1000)
                ->setCurrency('EUR')
                ->setItems([
                    (new ShoppingBasketItemType())
                        ->setArticleNumber("123")
                        ->setQuantity("10")
                        ->setUnitPriceGross(100)
                        ->setItem("Article 1")
                ])
        )
        ->build();

    $res = $ratepayBroker->confirmationDeliver($transactionId, $confirmationDeliver);

RatePAY Gateway Endpoints

The RatePAY Gateway system is implemented as a XML over HTTP webservice. It can be accessed via SSL:

Test: https://gateway-int.ratepay.com/api/xml/1_0
Production: https://gateway.ratepay.com/api/xml/1_0

RatePAY gateway operations

Gateway operation	Mandatory / Optional	Purpose
PAYMENT_INIT	M	Initialize the transaction and get a valid transaction-id.
PAYMENT_QUERY full	O	Check the customer and order details, perform a configurable risk scoring, retrieve the payment products permitted in the given context. The PAYMENT_QUERY full can be booked with a guaranteed acceptance. This means that all products given back will be accepted by a following PAYMENT_REQUEST.
PAYMENT_REQUEST	M	Check the customer and order details, perform risk scoring, return either customer acceptance or rejection.
PAYMENT_CONFIRM	M (if response of the PAYMENT_REQUEST is positive)	Finalize the payment process.
CONFIRMATION_DELIVER (“CD”)	M (if order has not been cancelled)	Immediately after the ordered goods have been delivered to the customer, the merchant must send a Confirmation Deliver message to the RatePAY Gateway.
PAYMENT_CHANGE cancellation	O	Merchant cancels some or all items of the order
PAYMENT_CHANGE return	O	Merchant returns some or all items of the order
PAYMENT_CHANGE change-order	O	Merchant or customer adds items to the order
PAYMENT_CHANGE credit	O	Merchant adds a credit (discount) or debit (adjustment charge) to the order
CONFIGURATION_REQUEST	O	Retrieve the stored configuration parameters for a certain merchant profile.
CALCULATION_REQUEST	O	Provides an installment plan depending on the request parameters and stored parameters of the merchant profile.

Please note: The gateway operations are exposed through the RatepayBroker object.

JMS Serializer Library Usage Note

This library makes heavy use of the JMS-Serializer library which itself makes heavy ues of the doctrine annotation features.

To use the library in a standalone environment make sure to register the serializer source directory in the doctrine annotation registry.

AnnotationRegistry::registerAutoloadNamespace(
    'JMS\Serializer\Annotation',
    __DIR__ . "/vendor/jms/serializer/src");

Appendix: Result Codes

The following result codes are only for internal reference in the library and are exposed via the the RejectionException, TechnicalException and WarningException if you use the RatepayBroker object.

Operation	Success	Rejection	Technical Error	Warning	Additional Information
PAYMENT_INIT	350	-	150	-	-
PAYMENT_QUERY	402	401	150	405	The PAYMENT_QUERY needs a different evaluation. To determine if a following PAYMENT_REQUEST will be successful, the corresponding product has to be available.
PAYMENT_REQUEST	402	401	150	405	-
PAYMENT_CONFIRM	400	401	150	405	-
PAYMENT_CHANGE	403	401	150	405	-
CONFIRMATION_DELIVER	404	401	150	405	-
CALCULATION_REQUEST	502	503	150	-	Note when a 503 is triggered: Although sending the same CALCULATION_REQUEST again is possible, the result will always be the same. This result indicates a request with wrong parameters.
CONFIGURATION_REQUEST	500	-	150	-	-

phpcommerce / ratepay

Maintainers

Details