Getting Started ¶

Before you begin ¶

To get you started on the right track, we suggest you:

1. Speak to your bank about PCI requirements for this integration.

2. Create a test account in UAT so you can build and test your integration without any money changing hands.

   • follow this link to create.

Building your integration ¶

Custom Checkout integrations will need to support the following functions:

• Authentication: create 0Auth bearer token to access the API.

• Create a payment: with information about the transaction.

• Render the UI: where customers enter their payment details.

• Handle transaction results: to complete order processing.

Depending on your requirements, you may also wish to support:

• Handle events to give your customers a more bespoke experience.

• Process captures and refunds via API.

Content Security Policy where your Custom Checkout payment page is embedded, will need a Content Security Policy with frame-src: *. This allows 3DS challenges and first time BNZ Online EFTPOS users to authenticate their transcations.

Before you go live ¶

Please arrange a review of your integration - we’ll help you make sure it’s efficient and working for you, and your customers.

Credentials Checklist ¶

Authentication ¶

Create Payment ¶

User Interface ¶

Render UI ¶

Once you have a payment ID, you can render the UI. To do this you must follow four steps.

1. Update your Content Security Policy ¶

Your payment page, where Custom Checkout is embedded, will need to have a Content Security Policy with frame-src: *. This is to allow 3DS challenges and first time BNZ Online EFTPOS users to authenticate their transcations.

2. Add containers to your webpage ¶

Add empty containers with unique IDs for each payment method you’d like to display. For example:

<div class="accordion" id="paymentMethods">
    <div class="accordion-item">
        <h2 class="accordion-header" id="cardHeading">
            <button class="accordion-button" type="button" data-bs-toggle="collapse" data-bs-target="#collapseOne" aria-expanded="true" aria-controls="collapseOne">
            Credit Card
            </button>
        </h2>
        <div id="collapseOne" class="accordion-collapse collapse show" aria-labelledby="headingOne" data-bs-parent="#paymentMethods">
            <div class="accordion-body">
                <div id="card-container"></div>
            </div>
        </div>
    </div>
    <div class="accordion-item">
        <h2 class="accordion-header" id="oeHeading">
            <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseTwo" aria-expanded="false" aria-controls="collapseTwo">
            Online EFTPOS
            </button>
        </h2>
        <div id="collapseTwo" class="accordion-collapse collapse" aria-labelledby="headingTwo" data-bs-parent="#paymentMethods">
            <div class="accordion-body">
                <div id="oe-container"></div>
            </div>
        </div>
    </div>
    
</div>

3. Load Custom Checkout plugin ¶

The key component is the Worldline-hosted Custom Checkout JavaScript plugin. Add this file to your page:

4. Initialise the plugin ¶

Next you must pass in the payment ID - the target containers where you’d like iframes to be loaded. This will allow the payment request to be initialised.

Parameters to be passed to initialise ¶

<script src="https://clickcustompay.paymark.nz/paymarkPlugin.js"></script>

window.paymarkPlugin.initialise({
  redirect: true, /** specifying this would enable the plugin to redirect to merchant order summary page **/
  targetElementId: "<card-container>", /*div id that holds the card or OE Elements*/
  paymentId: "<paymentId>", /*id returned after POSTing payment /payment */
  genericErrorMessage: "<unexpected error occured, please try again later>",
  storeCardMethod: “DO_NOT_STORE_CARD”,
  onError: () => {
    /* callback when an error occurs*/
  },
});

//render OE
window.paymarkPlugin.renderOE();

//render Card Elements
window.paymarkPlugin.renderCard();

//update paymentId in case of transaction amount changes after initialisation of plugin 
window.paymarkPlugin.updatePaymentId(paymentId);

//submit Payment
window.paymarkPlugin.submitPayment(event);

“Purchase/Submit” button. ¶

You may customise font style and background colour for the “Purchase/Submit” button.

Card Integration ¶

3DS Enablement ¶

By default, the plugin is gathering the mandatory fields required to process 3DS.

These are the set of optional fields which are strongly recommended by EMVco. These have the highest impact in reducing the number of challenges cardholders receive.

• Merchant Risk Info, Cardholder Account Info

• Transaction & Checkout Page Info

• Authentication Info

Test Cards ¶

Non-Challenge flow ¶

Challenge flow ¶

Online EFTPOS ¶

Payment Flow ¶

Online EFTPOS is an asyncrhonous payment flow as your customer needs to approve the payment in their mobile banking app.

You initiate a payment request. Your customer selects their bank and enters their mobile number (or banking customer identifier). Your customer then approves the payment in their bank app, and you are able to retrieve the status of the completed payment. Once approved, the payment is irrevocable. Your bank account is then credited during the overnight settlement process.

Payment Flow for BNZ ¶

If your customer banks with BNZ their first Online EFTPOS payment request is slightly different. They will be redirected to a secure BNZ page, login using their BNZ access number and password, and then approve the payment. This flow is termed “redirect flow”. Subsequent payment requests are approved through the BNZ bank app only. This flow is termed “decoupled flow”.

In a redirect flow BNZ customers will be presented with the screen below to inform them of the procedure for their first Online EFTPOS transaction.

Online EFTPOS Transaction Flow through Custom Checkout Plugin. ¶

Online EFTPOS Transaction Flow for First time BNZ users through Custom Checkout Plugin. ¶

Payment State Transition ¶

• requires_payment_method -> Cancelled (cancelled transaction)

• requires_payment_method -> Payment authorised -> Processing -> Expired (did not authorise on time)

• requires_payment_method -> Payment authorised -> Processing -> Declined (transaction declined)

• requires_payment_method -> Payment authorised -> Processing -> Approved (transaction approved)
  | Values | Description| | ------ | ------ | | requires_payment_method| The user has just initiated and is waiting for payment method; card or Online EFTPOS. | | requires_action | Waiting for the user to respond to the 3DS challenge.| | processing | When the Card transaction is successfully authorized by 3DS and waiting for the payment to be approved by the bank. When OE Payment is waiting to approve by the user and the bank.| | cancelled | When the card payment is canceled by the user. | | declined | When the Payment is declined by the bank e.g. insufficient funds. | | approved | Payment is successfully processed and the transaction has been approved. | | expired | When an OE payment is not successfully submitted to the bank. | | requires_capture | NOT IMPLEMENTED. |

Refund Flow ¶

Online EFTPOS refunds are synchronous. The customer does not need to approve the refund.

• You initiate a refund

• The bank approves the refund

• The bank moves the money back to your customer’s account immediately.

• The Online EFTPOS API responds with the outcome.

• Your account is debited during overnight settlement.

Transaction Response Codes for Online EFTPOS ¶

Transaction Response Codes for Cards ¶

Please refer to these Transaction Codes.

Online EFTPOS Sandbox ¶

When making a purchase using Online EFTPOS, you can simulate different responses from each bank by specifying different transaction amounts for both payments and refunds.

Authorised Scenarios

Expired scenarios are not available in the Online EFTPOS Sandbox for ANZ payment transactions.

Declined scenarios are not available in the Online EFTPOS Sandbox for ANZ refund transactions.

EXPIRED Scenarios

The expired scenario does not apply to refunds as these require no Customer action.

Authorised Scenarios

EXPIRED Scenarios

ERROR Scenarios

Refunds

Authorised Scenarios

Declined Scenarios

EXPIRED Scenarios The expired scenario does not apply to refunds as these require no Customer action.

ERROR Scenarios

BNZ

Payments

Authorised Scenarios

Please use the number 0277833544 to test the decoupled flow for BNZ. If you wish to test the redirect flow please contact us at oesupport@paymark.co.nz

Declined Scenarios

EXPIRED Scenarios

ERROR Scenarios

Refunds

Authorised Scenarios

Declined Scenarios

EXPIRED Scenarios

The expired scenario does not apply to refunds as these require no Customer action.

ERROR Scenarios

Westpac

Payments

Authorised Scenarios

Declined Scenarios

EXPIRED Scenarios

Expired scenarios are not available in the Online EFTPOS Sandbox for Westpac transactions.

ERROR Scenarios

Refunds

Authorised Scenarios

Declined Scenarios

Declined scenarios are not available in the Online EFTPOS Sandbox for Westpac refund transactions.

EXPIRED Scenarios

The expired scenario does not apply to refunds as these require no Customer action.

ERROR Scenarios

The Cooperative Bank

Payments

Authorised Scenarios

Declined Scenarios

EXPIRED Scenarios

ERROR Scenarios

Refunds

Authorised Scenarios

Declined Scenarios

EXPIRED Scenarios

The expired scenario does not apply to refunds as these require no Customer action.

ERROR Scenarios

Storing a Payment / Storing Cards ¶

Store Payment ¶

This method is only applicable for card payments at the moment. There are two ways that you can store card / store payment when using the plugin. When initialising the plugin you can select options for storeCardMethod field.

There are indicators in the response body of the method used and if the card / payment has been successfully stored.

NOTE: when a payment gets declined that the card will not get stored.

More about managing tokens here and transacting via tokens here

Response From CustomerSelection

• Body

  {
    "transaction": {
    "clickTransactionId": "P230110018485168",
    "result": {
        "paymentMethodDetails": {
            "cardType": "VISA",
            "cardNumber": "411111******1111",
            "cardExpiry": "0333",
            "cardHolder": "George D"
        },
        "storeCardMethod": "CUSTOMER_SELECTION",
        "storeCardSelection": true,
        "cardStored": true,
        "responseCode": "00",
        "authCode": "052998",
        "batchNumber": "20230113",
        "receiptNumber": 43489297,
        "paymentMethod": "card",
        "cardToken": "9378553531604",
        "paymentToken": "9378553531604",
        "threeeDS": {
            "status": "Y",
            "eci": "05",
            "statusReason": "",
            "authenticationReference": ""
        }
    },
    "amount": 1000.00,
    "currency": "NZD",
    "reference": "3edfdb9f-f630-4cc1-a065-a4c562781078",
    "frequency": "single"
    },
    "callbackUrl": "https://callbackurl",
    "merchant": {
    "url": "https://demo.uat.paymark.nz/"
    },
    "id": "0d7c54a0-9439-4e5e-af88-b126a83fac56",
    "redirectUrl": "https://demo.uat.paymark.nz/summary",
    "transactionType": "purchase",
    "showPaymentMethods": ["card", "oe"],
    "status": "approved",
    "created_at": "2023-01-13T02:56:18.877Z",
    "modified_at": "2023-01-13T02:56:34.4Z"
    }

Response from DoNotStoreCard

• Body

  {
    "transaction": {
    "clickTransactionId": "P230110019885168",
    "result": {
        "paymentMethodDetails": {
            "cardType": "VISA",
            "cardNumber": "411111******1111",
            "cardExpiry": "0333",
            "cardHolder": "George D"
        },
        "storeCardMethod": "DO_NOT_STORE_CARD",
        "cardStored": false,
        "responseCode": "00",
        "authCode": "052998",
        "batchNumber": "20230113",
        "receiptNumber": 43489297,
        "paymentMethod": "card",
        "threeeDS": {
            "status": "Y",
            "eci": "05",
            "statusReason": "",
            "authenticationReference": ""
        }
    },
    "amount": 1000.00,
    "currency": "NZD",
    "reference": "3edfdb9f-f630-4cc1-a065-a4c562781078",
    "frequency": "single"
    },
    "callbackUrl": "https://callbackurl",
    "merchant": {
    "url": "https://demo.uat.paymark.nz/"
    },
    "id": "0d7c54a0-9439-4e5e-af88-b126a83fac56",
    "redirectUrl": "https://demo.uat.paymark.nz/summary",
    "transactionType": "purchase",
    "showPaymentMethods": ["card", "oe"],
    "status": "approved",
    "created_at": "2023-01-13T02:56:18.877Z",
    "modified_at": "2023-01-13T02:56:34.4Z"
    }

Response StoreCard

• Body

  {
    "transaction": {
    "clickTransactionId": "P23011001855318",
    "result": {
        "paymentMethodDetails": {
            "cardType": "VISA",
            "cardNumber": "411111******1111",
            "cardExpiry": "0333",
            "cardHolder": "George D"
        },
        "storeCardMethod": "STORE_CARD",
        "cardStored": true,
        "responseCode": "00",
        "authCode": "052998",
        "batchNumber": "20230113",
        "receiptNumber": 43489297,
        "paymentMethod": "card",
        "cardToken": "9378553531604",
        "paymentToken": "9378553531604",
        "threeeDS": {
            "status": "Y",
            "eci": "05",
            "statusReason": "",
            "authenticationReference": ""
        }
    },
    "amount": 1000.00,
    "currency": "NZD",
    "reference": "3edfdb9f-f630-4cc1-a065-a4c562781078",
    "frequency": "single"
    },
    "callbackUrl": "https://callbackurl",
    "merchant": {
    "url": "https://demo.uat.paymark.nz/"
    },
    "id": "0d7c54a0-9439-4e5e-af88-b126a83fac56",
    "redirectUrl": "https://demo.uat.paymark.nz/summary",
    "transactionType": "purchase",
    "showPaymentMethods": ["card", "oe"],
    "status": "approved",
    "created_at": "2023-01-13T02:56:18.877Z",
    "modified_at": "2023-01-13T02:56:34.4Z"
    }

Handling Transaction Results ¶

Custom Checkout has a variety of ways to provide a transaction status. This allows you to customise UI elements or customise flows.

There are four ways you can receive the payment result. If you are implementing a push notification it must be followed by a polling mechanism. Please do discuss with your Worldline NZ contact.

Recommended practice to confirm transaction result ¶

Ways to implement a push notification and polling mechanism, for example:

• Use ‘Post to redirectUrl’ with ‘Retrieve payment’

• Or use ‘Post to callbackUrl’ with ‘Retrieve payment’

• Or use ‘Post to redirectUrl’ with ‘Add JavaScript Event Listener’

• Or use ‘Post to callbackUrl’ with ‘Add JavaScript Event Listener’

Requirements ¶

• JavaScript Events Notification

• Merchant Notification redirectUrl

• Merchant Notification callbackUrl - must be server to server (not browser)

• Retrieve Payment

JavaScript Events Notification ¶

JSPlugin sends events to the Merchant on below actions. On completion of a transaction, a JavaScript event will be fired.

Event Types ¶

Example of events below:

• Customer provides Payment details and submits the payment

{
  "message": {
    "event": "payment_submitted",
    "data": {
      "paymentMethod": "oe"
    }
  }
}

• Customer is challenged

{
  "message": {
    "event": "payment_challenged",
    "data": {
      "paymentMethod": "oe"
    }
  }
}

• Bank provided Challenge response (3DS Transactions CARD ONLY)

{
  "message": {
    "event": "payment_challenge_response",
    "data": {
      "paymentMethod": "card",
      "challengeResponse": {
        "status": "success" #success or failure
      }
    }
  }
}

• Payment processing has completed

{
  "message": {
    "event": "payment_submission_response",
    "data": {
      "paymentMethod": "oe",
      "status": "approved" #approved or declined
    }
  }
}

• Returns credit card type entered by customer (visa, amex or mastercard)

{
  "message": {
    "event": "payment_card",
    "data": {
      "type": "visa",
    }
  }
}

• Returns state of validation of input fields

{
  "message": {
    "event": "payment_input",
    "data": {
      "paymentMethod": "oe",
      "valid": true or false
    }
  }
}

• Payment timer has expired

{
  "message": {
    "event": "payment_expired",
    "data": {
      "paymentMethod": "oe"
    }
  }
}

• Payment details submitted contained an invalid payment id

{
  "message": {
    "event": "payment_id_invalid",
    "data": {
      "paymentMethod": "oe"
    }
  }
}

Add JavaScript Event Listener ¶

window.addEventListener("message", (event) => {
      const message = event.data;
      const { event: paymentEventType, data } = message;

      if (paymentEventType === "payment_submitted") {
        // handle event here
      }

      if (paymentEventType === "payment_challenged") {
        // handle event here
      }
      
      if (paymentEventType === "payment_challenge_response") {
        // handle event here
      }

      if (paymentEventType === "payment_submission_response") {
        // handle event here
      }

      if (paymentEventType === "payment_input") {
        // handle event here
      }

      if (paymentEventType === "payment_expired") {
        // handle event here
      }

      if (paymentEventType === "payment_id_invalid") {
        // handle event here
      }

      if (paymentEventType === "payment_id_updated") {
        // handle event here
      }
      
    });

Extend your integration ¶

Captures, cancellations and refunds ¶

If you need to refund a transaction, or if you want to capture or cancel authorised funds, you can do so through the Click merchant portal.

To do this via API you can integrate to our Refund, Capture and Cancel APIs.

These APIs use basic authentication rather than an oAuth2 Bearer Token. Instructions on what to include are given on the linked pages.

As these APIs do not accept card data, your PCI compliance burden should not be impacted by using the APIs. As always, speak to your acquiring bank to confirm before integrating.

Reporting API ¶

If the Click Portal’s reporting functionality isn’t flexible enough for your needs, you can integrate with our Reporting API. This contains information only about the transaction, rather than the entire payment session, but is useful for creating bespoke and scheduled reports.

Support ¶

Contact us ¶

If you have any issues with this integration please email click@paymark.co.nz.