Recurring Credit Card Payments


Recurring credit card payments extend the regular credit card payments, so please walk it through first.

When the dialog is used for recurring payment it is returning a payment_token that can be used multiple times. The token is associated with the specific credit card and with this specific Shop only. The shop can store the token and use it later on to take payments according to its own business logic.


Flow:
  1. Customer reaches to the check-out page on e-shop site. The shop states clearly, that customer is about subscribing to a periodic payments.
  2. Customer proceeds with payment.
  3. E-shop registers a new Transaction in MK-API. Recurring Credit Card Payments Shop should specify in the transaction request recurring_required = true.
  4. E-shop prepares parameters and invokes checkout.js, including the recurring specific attributes which builds a card data collection and launches Credit Card Dialog as a semi-transparent iFrame layer on top of shop checkout page. Inside the checkout.js is enrollment checkbox where customer can confirm enrollment.The sensitive card data is submitted directly within this iFrame to Maksekeskus backend. If applicable the user is redirected through 3DS dialog. E-shop must trigger checkout.js.
  5. In the dialog the customer fills in credit card data and submits the data to MK backend, to perform the payment in the selected channel.
  6. MK backend returns payment_token.
  7. Checkout.js passes payment token back to E-shop. On 3D Secure payment the browser is redirected to return_url with token_return message instead. The shop should verify the message and state in returned data and that payment_token was received correctly. Shop has to store the multi-use token in database. E-shop creates first payment with the token in API on step 6/7.
  8. In case of success, payment confirmation page is displayed; otherwise customer goes back to payment method selection step. MK servers will send additional async message about the transaction status change to the shop server’ notification_url.
  9. Payout is made to Merchant account from MK System.
  • The first transaction should use the standard checkout.js card form. All next payments are initiated by Merchant with reusable token. When it's time to take next payment for the subscription renewal, e-shop should do following:
    • Create a new transaction over API
    • Use the stored payment token to make payment for the transaction
    • Examine the response, if the payment failed (card expired etc) e-shop needs ask customer to make the payment through the dialog again.

2. Let's create a transaction (we use settings from the session context)

Create a transaction

<?php

$request_body = array(
    'transaction' => array(
        'amount' => $context->transaction->amount,
        'currency' => $context->transaction->currency,
        'reference' => $context->transaction->reference
    ),
    'customer' => array(
        'email' => $context->customer->email,
        'ip' => $context->customer->ip,
        'country' => $context->customer->country,
        'locale' => $context->customer->locale
    )
);

$transaction = $MK->createTransaction($request_body);

?>
Request
Content type
Headers
Body
Response
Content type
Headers
Body

    So we have now Transaction ID:


x. Select a Test card for use in the dialog (copy to clipboard)

      5191631234000016    | expiration date: 06/24 | CVC: 123 | (expand for more cards..)

3 prepare parameters and trigger the checkout.js

We use here js callback function to receive the data back from the credit card dialog
We have placed such js script to the page:

    <script src="<?php echo $context->creditcard->url; ?>/checkout/dist/checkout.js"></script>
    
    <script>
        window.cc_callback = function(data)
        {   
            alert( 'The CC dialog returned: \r\n \r\n'+ JSON.stringify(data) ); 
        }

        window.Maksekeskus.Checkout.initialize(
        {   'key' : '<?php echo $context->shop->publishableKey; ?>', 
            'transaction' : '<?php echo $transaction->id; ?>',
            'amount' : '<?php echo $transaction->amount; ?>', 
            'currency' : '<?php echo $transaction->currency; ?>', 
            'email' : 'john@diehard.ly', 
            'clientName' : 'John McLane', 
            'locale' : 'en', 
            'name' : 'MyService.com', 
            'description' : 'Order no. 123abc', 
            'recurringRequired' : 'true',
            'recurringTitle' : 'MyService.com subscription',
            'recurringDescription' : 'membership fee is 10€ monthly',
            'recurringConfirmation' : 'i agree that the fee will be taken from my credit card each month automatically',
            'completed' : 'cc_callback', 
            'cancelled' : 'cc_callback' }
        );
    </script>


<button type="button" class="btn btn-primary" aria-label="Open Recurring CC Payment dialog" onclick="window.Maksekeskus.Checkout.open();">Open CC Payment dialog</button>



See all the dialog parameters ... (expand)

6. Examine returned data


7. Create Payment

The payment token you got is just an authorization to take the money. To actually take it you have to create now the Payment with it: