NAME
    Finance::Bank::SuomenVerkkomaksut - Process payments through JSON API of
    Suomen Verkkomaksut in Finland. Payments from all Finnish Banks online:
    Nordea, Osuuspankki, Sampo, Tapiola, Aktia, Nooa, Paikallisosuuspankit,
    Säästöpankit, Handelsbanken, S-Pankki, Ålandsbanken, also from Visa,
    Visa Electron, MasterCard credit cards through Luottokunta, and PayPal,
    billing through Collector and Klarna.

SYNOPSIS
        use Finance::Bank::SuomenVerkkomaksut;

        # Creating a new payment
        my $tx = Finance::Bank::SuomenVerkkomaksut->new({merchant_id => 'XXX', merchant_secret => 'YYY'});
        # All content in accordance to http://docs.verkkomaksut.fi/ field specs
        $tx->content({
                orderNumber => 1,
                referenceNumber => 13,
                description => 'Order 1',
                currency => 'EUR',
                locale => 'fi_FI',
                urlSet => {success => $c->uri_for('/payment/success').'/',
                           failure => $c->uri_for('/payment/failure').'/',
                           pending => $c->uri_for('/payment/pending').'/',
                           notification => $c->uri_for('/payment/notification').'/',
                },
                orderDetails => {
                    includeVat => 1,
                    contact => {
                        firstName => 'First',
                        lastName => 'Last',
                        email => 'first@example.com',
                        telephone => '555123',
                        address => {
                            street => 'Street 123',
                            postalCode => '00100',
                            postalOffice => 'Helsinki',
                            country => 'FI',
                        }
                    },
                    products => [
                        {
                            "title" => 'Product title',
                            "amount" => "1.00",
                            "price" => 123,
                            "vat" => "0.00",
                            "discount" => "0.00",
                            "type" => "1", # 1=normal product row
                        },
                        ],
                },

        });

        # set to 1 when you are developing, 0 in production
        $tx->test_transaction(1);

        my $submit_result = $tx->submit();
        if ($submit_result) {
            print "Please go to ". $tx->url() ." $url to pay your order number ". $tx->order_number().', see you soon.';
        } else {
            die 'Failed to generate payment';
        }

        # Verifying the payment when the user returns or when the notify address receives a request
        my $tx = Finance::Bank::SuomenVerkkomaksut->new({merchant_id => 'XXX', merchant_secret => 'YYY'});
        my $checksum_matches = $tx->verify_return({
                ORDER_NUMBER => $c->req->params->{ORDER_NUMBER},
                TIMESTAMP => $c->req->params->{TIMESTAMP},
                PAID => $c->req->params->{PAID},
                METHOD => $c->req->params->{METHOD},
                RETURN_AUTHCODE => $c->req->params->{RETURN_AUTHCODE}
        });
        if ($checksum_matches) {
            # depending on the return address, mark payment as paid (if returned to RETURN_ADDRESS),
            # as pending (if returned to PENDING_ADDRESS) or as canceled (if returned to CANCEL_ADDRESS).
            if ($url eq $return_url) {
                # &ship_products();
            }
        } else {
            print "Checksum mismatch, returning not processed. Please contact our customer service if you believe this to be an error.";
        }

  merchant_id
    The merchant id given to you by Suomen Verkkomaksut when you make the
    contract. Defaults to the test merchant account.

  merchant_secret
    The merchant secret given to you by Suomen Verkkomaksut. Defaults to the
    test merchant account.

  test_transaction
    Set to 1 to mark the mode as a test. In that case the test merchant
    account of Suomen Verkkomaksut is used and no real money is transferred.
    Intended for testing.

  debug
    Set to 1 to get debug warnings. Defaults to 0, no debug.

  content
    Set the content to be sent to Suomen Verkkomaksut API. All content must
    be in accordance to http://docs.verkkomaksut.fi/ field specs, as a Perl
    data structure.

  submit
    Submits the content to Suomen Verkkomaksut API. Populates is_success,
    url, server_response_json, server_response, result_code, error_message,
    token and order_number.

  is_success
    Populated when you call submit. Status of the submission.

  url
    Populated when you call submit. This is the URL the user should go to to
    make the payment.

  token
    (Nice-to-have) Populated when you call submit and the submission is
    succesful.

  order_number
    (Nice-to-have) Populated when you call submit and the submission is
    succesful.

  server_response_json
    (Nice-to-have) Populated when you call submit and the submission is
    succesful.

  server_response
    (Nice-to-have) Populated when you call submit. The entire unprocessed
    response content.

  result_code
    (Nice-to-have) Populated when you call submit. The HTTP status code of
    the reply.

  error_message
    Populated when you call submit and the submission is not succesful.
    Contains the error message from Suomen Verkkomaksut.

  verify_return
    When the end-user has completed the payment he will return to your
    specified RETURN_ADDRESS, CANCEL_ADDRESS or PENDING_ADDRESS. Before you
    process the returning any further you must check that the parameters
    given to this address have the correct checksum.

    This method verifies the checksum and returns true or false stating if
    the checksum matched or did not.

    After you know that the checksum matched you can mark the payment as
    paid (if returned to RETURN_ADDRESS), as pending (if returned to
    PENDING_ADDRESS) or canceled (if returned to CANCEL_ADDRESS).

    Also your NOTIFY_ADDRESS should call verify_return first to verify the
    checksum and only if the verification is passed proceed with the
    information received.

  port
    The port where the submission is sent to. Defaults to 443.

  server
    The server host name where the submission is sent to. Defaults to
    payment.verkkomaksut.fi.

  path
    The URL path where the submission is sent to. Defaults to
    /api-payment/create.

  api_version
    The API version of Suomen Verkkomaksut. Defaults to 1.

SECURITY
    Don't allow user to set the test_transaction to true! If the user can
    set it to true when returning he will get his payment registered as
    processed.

    Don't allow user to set the 'type' parameter of verify_return.

SEE ALSO
    http://verkkomaksut.fi/ http://docs.verkkomaksut.fi/
    http://www.verkkomaksut.fi/palvelut/palveluiden-kayttoonotto

AUTHOR
    Oskari Okko Ojala <okko@cpan.org>, Frantic Oy http://www.frantic.com/

COPYRIGHT AND LICENSE
    Copyright (C) Oskari Ojala 2011.

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself, either Perl version 5.8.8 or, at
    your option, any later version of Perl you may have available.