Custom Checkout

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 ¶

Example initialisation ¶

<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 ¶

3DSecure ¶

By default, Worldline is gathering the mandatory fields required to process 3DSecure.

Here are three optional field groups 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 ¶

Frictionless flow ¶

Challenge flow ¶

Transaction Response Codes for Cards ¶

Please refer to these Transaction Codes.

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.

Customers are then redirected to BNZ’s secure login page. After entering their access number and password, customers are prompted to authorize this login from their BNZ bank app. Once authorized they can approve payment on BNZ’s secure page.

Online EFTPOS Transaction Flow through Custom Checkout. ¶

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

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)

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 ¶

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.

ANZ Payments ¶

Authorised Scenarios ¶

Declined Scenarios ¶

EXPIRED Scenarios ¶

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

ERROR Scenarios ¶

ANZ Refunds ¶

Declined and Error Scenarios ¶

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.

ASB Payments ¶

Authorised Scenarios ¶

Declined Scenarios ¶

EXPIRED Scenarios ¶

ERROR Scenarios ¶

ASB 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 ¶

BNZ 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 ¶

Westpac 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 ¶

The Cooperative Bank 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 ¶

There are two ways to store. 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 and transacting with 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,
            "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,
            "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,
            "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 discuss with your Worldline NZ contact.

Recommended practice to confirm transaction result ¶

Four ways to implement a push notification and polling mechanism:

• ‘Post to redirectUrl’ with ‘Retrieve payment’

• ‘Post to callbackUrl’ with ‘Retrieve payment’

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

• ‘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_card") {
        // handle event here
      }
      
      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 ¶

You can perform refunds, captures, or cancel authorisations through the CLICK merchant portal.

You can also integrate to our Refund, Capture and Cancel APIs.

These APIs use basic authentication rather than an oAuth2 Bearer Token.

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

Reporting API ¶

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

Support ¶

Contact us ¶

Please contact your Worldline NZ contact directly.

Alternatively for;

• Card integrations please email click@paymark.co.nz.

• Online EFTPOS integrations please email oesupport@paymark.co.nz