Custom Checkout

Introduction

Custom Checkout is designed to give merchants control over the payment experience. There’s no need to redirect customers to Worldline NZ’s servers for processing. As we use iFrames containing hosted payment fields there is less PCI burden than doing a deep merchant-hosted API integration.

JavaScript plugin used to create custom payment elements on your website. Worldline NZ handles all of the processing, but provides merchants ways to customise the look and feel of the payment elements and the user experience of the payment flow.

Transaction flow

High level flow of a transaction process:

  1. Acquire a bearer token to access APIs

  2. Create a payment, with information about the transaction

  3. Initialise Custom Checkout on your website, via the JavaScript plugin

  4. Handle events (if desired)

  5. Receive a transaction result

  6. Complete order processing

Payment methods

Card payments (VISA, MasterCard, AMEX) and Online EFTPOS payments. Card payments can benefit from 3DSecure and Worldline NZ’s fraud tools.

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

Value Description
Organisation ID Provided in the welcome letter after signing up for a demo/UAT account and later when you’ve been onboarded by Worldline NZ in production. aka Client ID. Used in the payment request.
Account ID Provided in the welcome letter after signing up for a demo/UAT account and later when you’ve been onboarded by Worldline NZ in production. aka Client ID. Used in the payment request.
ConsumerKey Supplied to merchant’s authorised person (who signed up for demo). Used for Authentication.
ConsumerSecret Supplied to merchant’s authorised person (who signed up for demo). Used for Authentication.

Authentication

Create Bearer Token

POST custom-checkout.paymarkclick.co.nz/bearer/
Requestsexample 1
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Q29uc3VtZXJLZXk6Q29uc3VtZXJTZWNyZXQ=
Body
+ grant_type:client_credentials
Responses200
Headers
Content-Type: application/json
Body
{
  "issued_at": "1464126466974",
  "application_name": "111111-2c4e-42cc-b613-fe974111111a",
  "scope": "",
  "status": "approved",
  "expires_in": "3599",
  "token_type": "BearerToken",
  "client_id": "axxxxxxxxxxx",
  "access_token": "bxxxxxxx"
}

Create Bearer Token
POST/bearer/

Environment Endpoint
UAT https://apitest.uat.paymark.nz/bearer
Production https://api.paymark.nz/bearer

To create or query a Custom Checkout session, you must obtain a bearer token using the Consumer Key and Consumer Secret. The bearer token returned must be provided in the Authorization header of all requests to Custom Checkout endpoints.

The bearer token has a limited lifetime. You will need to obtain a new token once it has expired.

The bearer token request header should contain authorisation that is Base64 encoded.

The format is ConsumerKey:ConsumerSecret


Create Payment

Create Payment

POST custom-checkout.paymarkclick.co.nz/paymark/hosted-fields/payment
RequestsPurchaseAuthorisation with 3DS2Statuscheck
Headers
Content-Type: application/json
Authorization: Bearer (bearer token)
Body
{
  "merchant": {
    "url": "https://icecreamshop.paymark.co.nz",
    "accountId": "678910",
    "organisationId": "12345"
  },
  "callbackUrl": "https://icecreamshop.paymark.co.nz/payment/summary",
  "redirectUrl": "https://icecreamshop.paymark.co.nz/payment/summary",
  "transactionType": "purchase",
  "showPaymentMethods": [
    "card",
    "oe"
  ],
  "transaction": {
    "amount": 10,
    "currency": "NZD",
    "reference": "TestReference",
    "particulars": "TestParticular",
    "skipSurcharge": false
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
    "id": "acbe4fa4-57c6-42d5-92cf-7db898a5003f",
    "merchant": {
        "url": "https://icecreamshop.paymark.co.nz",
        "accountId": "678910"
    },
    "callbackUrl": "https://icecreamshop.paymark.co.nz/payment/summary",
    "transaction": {    
        "amount": 10.00,
        "surcharge": 0.00,
        "currency": "NZD",
        "reference": "TestReference",
        "particulars": "TestParticular"
    }
    "transactionType": "purchase",
    "surchargePerCardType": {
        "visa": {
            "surcharge":0.20, 
            "rate": 2.00 ,
            "amountInclusive": 10.20
        },
        "mc": {
            "surcharge":0.15, 
            "rate": 1.50,
            "amountInclusive": 10.15
        },
        "amex": {
            "surcharge":0.35, 
            "rate": 3.50,
            "amountInclusive": 10.35
        }
    },
    "showPaymentMethods": [
        "card",
        "oe"
    ],
    "status": "created",
    "created": "2022-09-19T21:23:39.0022588Z",
    "modified": "2022-09-19T21:23:39.002259Z"
}
Headers
Content-Type: application/json
Authorization: Bearer (bearer token)
Body
{
  "merchant": {
    "url": "https://icecreamshop.paymark.co.nz",
    "accountId": "678910",
    "organisationId": "12345"
  },
  "callbackUrl": "https://icecreamshop.paymark.co.nz/payment/summary",
  "redirectUrl": "https://icecreamshop.paymark.co.nz/payment/summary",
  "transactionType": "Authorisation",
  "showPaymentMethods": [
    "card"
  ],
  "transaction": {
    "amount": 10,
    "currency": "NZD",
    "reference": "PaymentReference",
    "particulars": "PaymentParticulars",
    "skipSurcharge": true
  },
  "threeDS2": {
    "challengeIndicator": "NoPreference",
    "cardholderInformation": {
      "name": "string",
      "email": "string",
      "homePhone": {
        "country": "str",
        "subscriber": "string"
      },
      "mobilePhone": {
        "country": "str",
        "subscriber": "string"
      },
      "workPhone": {
        "country": "str",
        "subscriber": "string"
      }
    },
    "accountInformation": {
      "accountId": "string",
      "authenticationInformation": {
        "method": "No3DSRequestorAuthenticationOccurred",
        "timestamp": "2021-12-07T21:30:12.332Z"
      },
      "priorAuthenticationInfo": {
        "method": "FrictionlessAuthenticationOccurredByAcs",
        "reference": "string",
        "timestamp": "2021-12-07T21:30:12.332Z"
      },
      "accountAgeIndicator": "NoAccount",
      "accountDate": "2021-12-07",
      "accountChangeIndicator": "ChangedDuringThisTransaction",
      "accountChange": "2021-12-07",
      "accountPasswordChangeIndicator": "Nochange",
      "accountPasswordChange": "2021-12-07",
      "shippingAddressWasFirstUsed": "ThisTransaction",
      "shippingAddressUsage": "2021-12-07",
      "transactionActivityInTheLast24Hours": 999,
      "transactionActivityLastYear": 999,
      "provisionAttemptsInTheLast24Hours": 999,
      "numberOfPurchaseWithAccountInTheLastSixMonths": 9999,
      "suspiciousAccountActivityDetected": true,
      "shippingNameAndCardholderNameAreIdentical": true,
      "paymentAccountIndicator": "NoAccount",
      "paymentAccountAge": "2021-12-07"
    },
    "orderInformation": {
      "billingAddress": {
        "addressLine1": "string",
        "addressLine2": "string",
        "addressLine3": "string",
        "postalCode": "string",
        "city": "string",
        "state": "string",
        "country": "st"
      },
      "shippingAddress": {
        "addressLine1": "string",
        "addressLine2": "string",
        "addressLine3": "string",
        "postalCode": "string",
        "city": "string",
        "state": "string",
        "country": "st"
      },
      "shippingIndicator": "ShipToCardholdersBillingAddress",
      "deliveryTimeframe": "ElectronicDelivery",
      "deliveryEmailAddress": "string",
      "reorderItemsIndicator": "FirstTime",
      "preOrderPurchaseIndicator": "MerchandiseAvailable",
      "preOrderDate": "2021-12-07",
      "purchaseInstalmentData": 999,
      "recurringExpiry": "2021-12-07",
      "recurringFrequency": 9999
    }
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": "acbe4fa4-57c6-42d5-92cf-7db898a5003f",
  "merchant": {
    "url": "https://icecreamshop.paymark.co.nz",
    "accountId": "678910"
  },
  "CallbackUrl": "https://icecreamshop.paymark.co.nz/payment/summary",
  "transaction": {
    "amount": 10,
    "surcharge": 0,
    "currency": "NZD",
    "reference": "TestReference",
    "particulars": "TestParticular"
  },
  "transactionType": "authorisation",
  "showPaymentMethods": [
    "card"
  ],
  "status": "requires_payment_method",
  "created": "2021-12-12T08:09:23.693Z",
  "modified": "2021-12-12T08:09:23.693Z"
}
Headers
Content-Type: application/json
Authorization: Bearer (bearer token)
Body
{
  "merchant": {
    "url": "https://icecreamshop.paymark.co.nz",
    "accountId": "678910",
    "organisationId": "12345"
  },
  "callbackUrl": "https://icecreamshop.paymark.co.nz/payment/summary",
  "redirectUrl": "https://icecreamshop.paymark.co.nz/payment/summary",
  "transactionType": "statuscheck",
  "showPaymentMethods": [
    "card"
  ],
  "transaction": {
    "amount": 0,
    "currency": "NZD",
    "reference": "TestReference",
    "particulars": "TestParticular"
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": "acbe4fa4-57c6-42d5-92cf-7db898a5003f",
  "merchant": {
    "url": "https://icecreamshop.paymark.co.nz",
    "accountId": "678910"
  },
  "callbackUrl": "https://icecreamshop.paymark.co.nz/payment/summary",
  "transaction": {
    "amount": 0,
    "surcharge": 0,
    "currency": "NZD",
    "reference": "TestReference",
    "particulars": "TestParticular"
  },
  "transactionType": "purchase",
  "showPaymentMethods": [
    "card"
  ],
  "status": "created",
  "created": "2022-09-19T21:23:39.0022588Z",
  "modified": "2022-09-19T21:23:39.002259Z"
}

Create Payment
POST/paymark/hosted-fields/payment

Each order in the merchant’s system should have a single payment request. When creating the request you can define the payment types you want to be available, information about the transaction (and cardholder if 3DS is enabled), and request us to store the card for future use.

The following transaction types are available:

  • Purchase (card and Online Eftpos) - money is taken from the customer’s account.

  • Authorisation (card only) - money is held on the customer’s account but is not taken. Can be cancelled or captured.

  • Status Check (card only) - checks that a card is valid and active, without holding or taking funds.

Environment Endpoint
UAT https://apitest.uat.paymark.nz/paymark/hosted-fields/payment
Production https://api.paymark.nz/paymark/hosted-fields/payment

Field Glossary

Please pay particular attention to the required fields in the Inclusion column. Your Worldline NZ contact should be consulted too.

Name Type Constraints Inclusion Description
merchant.url string Required Merchant website’s domain name. Used to verify fields are being added to the merchant’s real website.
merchant.accountId integer Required Worldline NZ Account ID. Portal.
merchant.organisationId integer Required Worldline NZ Client ID. Portal.
redirectUrl string Optional URL to which you’d like the custom checkout iframe to redirect, on completion of transaction. URL must be publicly accessible.
callbackUrl string Required API endpoint you’d like us to send a server-to-server notification to, on completion of transaction. URL must be publicly accessible.
transactionType string enum Required Type of transaction: ‘purchase’, ‘authorisation’ or ‘statuscheck’
showPaymentMethods string array enum Required Payment methods you’d like to display. 'card" and/or ‘oe’.
transaction.amount integer money Required Amount you’d like to charge or authorise your customer’s account. E.g. 12.99
transaction.currency string enum Required Currency to charge or authorise. NZD only.
transaction.reference string Required A unique identifier for the transaction in your systems.
transaction.particular string Optional Information about the transaction. e.g. order#.
transaction.skipSurcharge string boolean Optional This allows you to control the application of surcharge on a per-transaction basis, if you have surcharge enabled. To enable surcharge, contact Worldline.
transaction.agreementid string Conditional If you are storing the payment method during this transaction so you can process transactions without customer intervention (e.g. a monthly subscription) then you must provide a unique agreement ID.
transaction.frequency string enum Conditional Required if storing the payment method for future use without customer intervention. The type of agreement you have with your customer to process transactions on their behalf. Options: ‘recurring’, ‘instalment’, ‘unscheduled’. Your acquiring bank must approve.

If you would like to use 3DSecure, please speak to your acquiring bank. Once they’ve enrolled you, you’ll be able to send extra information about the transaction to us. This will be used by the customer’s bank to authenticate the transaction.

HTTP Response

Value Description
200 Return CardPaymentResponse when payment method is card.
Return OePaymentResponse when payment method is OE.
201 Return CardPaymentResponse when payment method is card.
Return OePaymentResponse when payment method is OE.
400 Bad Request.
404 Not Found.
401 Unauthorised.

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:

Environment URL
Demo/UAT https://clickcustompay.uat.paymark.nz/paymarkPlugin.js
Production https://clickcustompay.paymark.co.nz/paymarkPlugin.js

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

Field Description Default value Required
targetElementId Div element id where card elements has to render No. Yes
paymentId Id that will returned in payment initiation call No. Yes
genericErrorMessage Customer will be seeing this error message when system throws an exception that is not handled Unexpected error occured. Please try again later. No
storeCardMethod STORE_CARD - tokenise the card used by the cardholder without presenting the checkbox in the plugin.
CUSTOMER_SELECTION - cardholder can choose whether they want to store their card or not. The Plugin will show a checkbox. DO_NOT_STORE_CARD.
DO_NOT_STORE_CARD. No

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.

Test Cards

Frictionless flow

Test Case MasterCard Visa American Express Expiry CVV Outcome
Cardholder successfully authenticated 5123450000000008 4508750015741019 01/39 100 Success
Cardholder failed authentication 5114395216041620 4589998437591445 3379462724081554 05/39 101 Declined
3DS Status unavailable 5186158875610488 4927874264333790 375439384971666 01/40 102 Blocked
Cardholder authentication rejected 5162323223461467 4635691262664247 375392300827514 01/40 102 Blocked

Challenge flow

Test Case MasterCard Visa American Express Expiry CVV Outcome
Cardholder successfully authenticated 2223000000000007 345678901234564 01/39 100 Success
Cardholder failed authentication 5199768787888942 4874970686672022 05/39 101 Declined

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)

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 Code Transaction Response Message
101 In Progress
200 Successful
273 Declined - Transaction Declined
399 Transaction Failed
361 Online EFTPOS Transaction Expired

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

Transaction Amount Response Description Response Type
Any amount less than $2.00 or more than $3.00 Consumer has authorised the payment Consumer response

Declined Scenarios

Transaction Amount Response Description Response Type
$2.00 User declined the payment from app or they don’t have access to the app System response

EXPIRED Scenarios

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

ERROR Scenarios

Transaction Amount Response Description Response Type
$2.20 Online EFTPOS system issue System response

ANZ Refunds

Transaction Amount Response Description Response Type
Any amount Refund has been successfully processed System response

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

Transaction Amount Response Description Response Type
Any amount less than $1.00 or more than $2.00 Consumer has authorised the payment Consumer response

Declined Scenarios

Transaction Amount Response Description Response Type
$1.01 Consumer does not have Bank mobile app registered for this payerId (mobile number for ASB) System response
$1.02 Consumer does not have Bank mobile app registered (app not set up for use) System response
$1.03 Consumer has Online EFTPOS disabled (PayHere turned off for ASB) System response
$1.05 Consumer is over their account limit System response
$1.17 Payment has been declined by the Consumer Consumer response

EXPIRED Scenarios

Transaction Amount Response Description Response Type
$1.20 Customer did not action the payment request within four minutes (expiry timeout has been passed) (Lack of) Customer response
$1.30 Customer did not action the payment request within four minutes and response has been delayed, Sandbox response is received after 6 minutes (Lack of) Customer response

ERROR Scenarios

Transaction Amount Response Description Response Type
$1.39 Error occurred and response has been delayed, Sandbox response is received after 6 minutes System response
$1.40 Error occurred System response

ASB Refunds

Authorised Scenarios

Transaction Amount Response Description Response Type
Any amount more than $2.00 Refund has been successfully processed System response

Declined Scenarios

Transaction Amount Response Description Response Type
$1.06 Payment not found System response

EXPIRED Scenarios

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

ERROR Scenarios

Transaction Amount Response Description Response Type
$1.14 Refund transaction failed System response

BNZ Payments

Authorised Scenarios

Transaction Amount Response Description Response Type
Any amount more than $2.30 Consumer has authorised the payment Consumer response

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

Transaction Amount Response Description Response Type
$2.00 Bank Declined Transaction System response

EXPIRED Scenarios

Transaction Amount Response Description Response Type
$2.00 Bank Declined Transaction System response

ERROR Scenarios

Transaction Amount Response Description Response Type
$2.10 Error occurred System response

BNZ Refunds

Authorised Scenarios

Transaction Amount Response Description Response Type
Any amount less than $1.30 or more than $1.53 Refund has been successfully processed System response

Declined Scenarios

Transaction Amount Response Description Response Type
$1.30 Bank has declined the transaction for some reason System response

EXPIRED Scenarios

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

ERROR Scenarios

Transaction Amount Response Description Response Type
$1.31 Online Eftpos system issue System response
$1.40 Refund transaction failed System response

Westpac Payments

Authorised Scenarios

Transaction Amount Response Description Response Type
Any amount more than $1.20 Consumer has authorised the payment Consumer response

Declined Scenarios

Transaction Amount Response Description Response Type
$1.05 Consumer is over their account limit System response
$1.06 Payer ID is not registered to a Westpac customer System response
$1.17 Payment has been declined by the Consumer Consumer response
$1.18 Consumer is not registered with Westpac System response

EXPIRED Scenarios

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

ERROR Scenarios

Transaction Amount Response Description Response Type
$1.08 Online EFTPOS system issue System response

Westpac Refunds

Authorised Scenarios

Transaction Amount Response Description Response Type
Any amount less than $1.00 or more than $1.20 Refund has been successfully processed System response

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

Transaction Amount Response Description Response Type
$1.08 Online Eftpos system issue System response

The Cooperative Bank Payments

Authorised Scenarios

Transaction Amount Response Description Response Type
Any amount more than $1.20 Consumer has authorised the payment Consumer response

Declined Scenarios

Transaction Amount Response Description Response Type
$1.02 Bank has declined the transaction for some reason, for example, the Consumer’s account is closed System response
$1.17 Bank Declined Transaction System response

EXPIRED Scenarios

Transaction Amount Response Description Response Type
$1.18 Customer did not action the payment request within four minutes (expiry timeout has been passed) (Lack of) Customer response

ERROR Scenarios

Transaction Amount Response Description Response Type
$1.04 Online EFTPOS system issue System response

The Cooperative Bank Refunds

Authorised Scenarios

Transaction Amount Response Description Response Type
Any amount more than $1.20 Refund has been successfully processed System response

Declined Scenarios

Transaction Amount Response Description Response Type
$1.02 Bank has declined the transaction for some reason System response

EXPIRED Scenarios

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

ERROR Scenarios

Transaction Amount Response Description Response Type
$1.04 Online Eftpos system issue System response

Storing a Payment / Storing Cards

Store Payment

There are two ways to store. When initialising the plugin you can select options for storeCardMethod field.

Option Description
STORE_CARD tokenise the card used by the cardholder without presenting the checkbox in the plugin
CUSTOMER_SELECTION cardholder can choose whether they want to store their card or not. The Plugin will show a checkbox

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

Field Name Description
storeCardMethod returns the method used for the storing card/payment
storeCardSelection will return TRUE if customer has ticked the box; will return FALSE otherwise. This field is only applicable when your storeCardMethod is CUSTOMER_SELECTION
cardStored will return TRUE if card/payment is stored; will return FALSE otherwise
cardToken token ID to be used for future purchases

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.

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

event status
payment_submitted -
payment_challenged -
payment_challenge_response success or failure
payment_submission_response approved or declined
payment_input true or false
payment_card -
payment_expired -
payment_id_invalid -

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
      }
      
    });

Post to redirectUrl

POST custom-checkout.paymarkclick.co.nz/merchants/redirecturl?paymentDetails=
Responses200
Headers
Content-Type: application/json
Body
{
  "id": "acbe4fa4-57c6-42d5-92cf-7db898a5003f",
  "merchant": {
    "url": "https://icecreamshop.paymark.co.nz",
    "accountId": 54321
  },
  "callbackUrl": "https://icecreamshop.paymark.co.nz/payment/summary",
  "transaction": {
    "amount": 1000,
    "currency": "NZD"
  },
  "transactionType": "purchase",
  "paymentMethodDetails": {
    "paymentMethod": "card",
    "cardNumber": "512345******2346",
    "cardExpiry": "0722",
    "cardHolder": "John Smith",
    "cardType": "MASTERCARD"
  },
  "status": "approved",
  "clickDetails": {
    "transactionId": "P220210015594404",
    "receiptNumber": 40711265,
    "batchNumber": "20220219",
    "status": "SUCCESSFUL",
    "acquirerResponseCode": "00"
  },
  "created_at": "2022-02-19T16:22:57",
  "modified_at": "2022-02-19T16:24:57"
}

Post to redirectUrl
POST/merchants/redirecturl?paymentDetails=

Custom Checkout will create a JSON object with the transaction result, stringify it and base64 encode it. Then we create a signature of the base64 encoded data using our private key and append the signature and base64 encoded string to the redirectUrl as a query parameter.

The merchant should then verify the signature using the public key by:

  • (a) decrypting the signature by reading the value from the signature query param

  • (b) generating a hash of the given paymentDetails query param

  • comparing (a) and (b) to confirm they match

Then you can retrieve the payment details by:

  • base64 decoding the paymentDetails query param

  • JSON.parse the result to get the JSON object

Public Key (Sandbox/UAT)

`LS0tLS1CRUdJTiBSU0EgUFVCTElDIEtFWS0tLS0tDQpNSUlDQ2dLQ0FnRUF0bnZKeUxlMy9vN2FKODZZdUNZSWxZbEtRT1YvdFNhTGZhTVU0c3VCQTBXM3Awd0t5VzZaDQo3clVHOUY0RnA2VWdGNmtad1orYzVhNmUyVEY5WVhEK2tFL21VM2EvaG5FUlgvMCtWTVpRaU83NFh0K2p1cXpKDQpFVHA4QkgvbTVkTGprL1MxZUgycHFKS3RXZGVSenFxcmFzUXJaVk12OUx1aHRhVlhOVWtNeDR1Yno3SnFxdUsrDQpLSzhjRjUyN3gybnRjem9vWlFFR0ZWWXdXNEhhRXdmbSsvSGFmWFYrZFNWWWdNM3RXVlBRKzVxWGt1QXJqUExzDQpIWDNVc1lVSlJCUDkwSzRaUGdiZUlZaWhzOFFseXU1dlJYbmh5SkdmZ1haVVhEZjU4ZXlpNDZ4VlNNdFQ4UDM2DQpPMnVRT25BR0d0OFpTOWdZVERoc1NvVXE5a2xsK2ZseTlGVjVjdTY3SDV3SnRrYmNZOW1WcmxWZGt4MThURlpmDQpBZVgrTUpKZEloc2d2TXJTV0JpWjFuckJYNXc0OHVvb21lY2JWcnBYclBMM2d1OEtPQTdheDNoUkU5cTl0dExiDQpOcEsrdUpzb0dnMjZWaWRKZkJRYXV4WTRLR3hyZFl4bUs3d1ZDSXRkaC9VWU0xTU5XNHV0Yk5tRjBLWHNRa1NkDQpKQWxqRVI1YjBHTEZNNlViQjQ4U1E4ZXJwbGI1WnI1RVRkZFloQUNoMFJpZjl2RElWT25jeUxDVmNGN2VFU0NHDQo2MlM0Yllyci85YWZGSnUxWXVlTDhVNUgvVGlnZGxkRWxsR25PWW9FUVJCWUhRUTM5cERpV21pbGgxdFh2dXdODQo0eGhNdjNYTkMvYzJjaUU2NHlENUJmRTlCdlBSZms1ZGJQcWJVanFEYjg3RVBwbEc5SFZXK0dVQ0F3RUFBUT09DQotLS0tLUVORCBSU0EgUFVCTElDIEtFWS0tLS0tDQo=`

Public Key (Production)

`LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQ0lqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FnOEFNSUlDQ2dLQ0FnRUFzT0gwL25BaXhicEFvZzlqdWFXNAp3OEpYeGp0TmhNLytmZkJBSUllVTZHcVp4SUtBdktsdmZSSTNtME5SUGJMRHFZaWFOUXVlT04zMXhjQjNNZi9YClBsdURGWkh0UFZkR0U0RzRtZklPL1BqbGVCMVFpZ2NCSTZuSkZHREtFUS82M1I4aElOVmMwbkN6VnFhRFNOTDkKeXUwcVJQd0d5VXNPcmNaaHZuRGcxckVSQjh1SVd5clg1TnlVaVNSSjU1eGN3SjBObFlJR2Jld1FKT25DTHdaSApXMU1MUTdYN2dMOTd4em8yc2xIclVSOTFuVHNOR1ltK085cWNEMTViY2NGZFNqQ0U2SVJlckxFYm4xbUNLQ3RvCnMzczRLNnRmVXlvSjNrQnFxWWpoY3BEL3V4N2QvVktlTlZJbjJPMUdNOEwxNUJkTjZnWGwrUjlTRWRVYlNlcVAKVFhMcTRwb24rdVNZcmJ0VnJuUEV6dDRBdEE3SlFJeUg3RHhQbkJDeVJsclJMWWlqQXpUS1plSk1lamVVY1hUawoyRkpRT0thb0JuVHV0bmFTSFF6ck5Ockwxb3BYWExaMmlBZWhWOFpHSEcvR3ROdGRESmgxYTBGbGFmU1lEZXNCCnNMMHZwQ1hJVGRmTmVxQXY3SWw4M0pJUVNDVVVzVHY1OGI5M1pYKyt0WEk1UjdYamN3aWRIWWl6SExtZXVITDIKd05SWkhFOFQ1anoxdXFUcFR1NEF3d0RXSnhpN2FkbWRGZUorSmQzYXpUc2ZVK3dMaGZtMVBGODU0eU5wQnNNLwo2aER2SnEzR095QjBUZkRiRlFvYVE5U0dZVFI1VG1iaUZPUy8zRUlublBQdVZXZU5taE9sYXJlWnVhamFmN2NFCjVMSDd6MG1FUEYrZkFLMDNlMGg2dlVVQ0F3RUFBUT09Ci0tLS0tRU5EIFBVQkxJQyBLRVktLS0tLQo=`
  • Example code snippet in C#:

    using var rsa = RSA.Create();
    
    byte[] bytes = Convert.FromBase64String(publickey);
    var nn = Encoding.UTF8.GetString(bytes);
    
    rsa.ImportFromPem(nn);
    
    byte[] dataToVerify = Encoding.UTF8.GetBytes(data);
    byte[] signatureData = Convert.FromBase64String(signature);
    
    var isVeryfied = rsa.VerifyData(dataToVerify, signatureData, HashAlgorithmName.SHA512, RSASignaturePadding.Pkcs1);
    
    Console.WriteLine($"Verified: {isVeryfied}");
    Console.ReadLine();
  • to redirectUrl

    • Headers

      Accept: application/json

    • Parameters

      • paymentdetails: eyJpZCI6ImFjYmU0ZmE0LTU3YzYtNDJkNS05MmNmLTdkYjg5OGE1MDAzZiIsIm1lcmNoYW50Ijp7InVybCI6Imh0dHBzOi8vaWNlY3JlYW1zaG9wLnBheW1hcmsuY28ubnoiLCJhY2NvdW50SWQiOjYzMjY3N30sImNhbGxiYWNrVXJsIjoiaHR0cHM6Ly9pY2VjcmVhbXNob3AucGF5bWFyay5jby5uei9wYXltZW50L3N1bW1hcnkiLCJ0cmFuc2FjdGlvbiI6eyJhbW91bnQiOjEwMDAsImN1cnJlbmN5IjoiTlpEIn0sInRyYW5zYWN0aW9uVHlwZSI6InB1cmNoYXNlIiwicGF5bWVudE1ldGhvZERldGFpbHMiOnsicGF5bWVudE1ldGhvZCI6ImNhcmQiLCJjYXJkTnVtYmVyIjoiNTEyMzQ1KioqKioqMjM0NiIsImNhcmRFeHBpcnkiOiIwNzIyIiwiY2FyZEhvbGRlciI6IkpvaG4gU21pdGgiLCJjYXJkVHlwZSI6Ik1BU1RFUkNBUkQifSwic3RhdHVzIjoiYXBwcm92ZWQiLCJjbGlja0RldGFpbHMiOnsidHJhbnNhY3Rpb25JZCI6IlAyMjAyMTAwMTU1OTQ0MDQiLCJyZWNlaXB0TnVtYmVyIjo0MDcxMTI2NSwiYmF0Y2hOdW1iZXIiOiIyMDIyMDIxOSIsInN0YXR1cyI6IlNVQ0NFU1NGVUwiLCJhY3F1aXJlclJlc3BvbnNlQ29kZSI6IjAwIn0sImNyZWF0ZWRfYXQiOiIyMDIyLTAyLTE5VDE2OjIyOjU3IiwibW9kaWZpZWRfYXQiOiIyMDIyLTAyLTE5VDE2OjI0OjU3In0K&signature=oXAhJyh3ilEY694zAVhPPX0Htpdklo4KfEWr0+duqAQAGsNZDTx6Iv9USpvjZk0ke08j+ipUpsDNFiD1wEE8ocy94eWO8o1JWUPXa4EMGRGRzcc1ulGqy4CVz9Tkd3vbKDJn2P6fH9l5pnhE38JWdxV1G7muG2rXRvy3tvhZFgTUrwZ77Zp/O6yRNx3ModOYcKQ6e0J1JUmSr1xUeutXNuvK7uof2LDMpvtnwEbaUalPNOy4lR2vN1p1HTgqVnZnA2FHYaeqK0s6TumgWDk2NiFv/DAPZ6fmRLPJR16jXMbeF3ybYj1PBONReDLYLBzM3vwhGSK3jLYD27lfLzY6ZQ== (required, string)

Post to callbackUrl

POST custom-checkout.paymarkclick.co.nz/callbackurl/
Responses200
Body
{
  "id": "ee426163-30b8-400b-ae4c-aa6df60402a3",
  "status": "approved",
  "paymentDetails": "eyJ0cmFuc2FjdGlvbiI6eyJjbGlja1RyYW5zYWN0aW9uSWQiOiJQMjIxMDEwMDA3MjUxNDIwIiwicmVzdWx0Ijp7InBheW1lbnRNZXRob2REZXRhaWxzIjp7ImNhcmRUeXBlIjoiTUFTVEVSQ0FSRCIsImNhcmROdW1iZXIiOiI1MTIzNDUqKioqKiowMDA4IiwiY2FyZEV4cGlyeSI6IjAxMzkiLCJjYXJkSG9sZGVyIjoiS2FybCJ9LCJyZXNwb25zZUNvZGUiOiIwMCIsImF1dGhDb2RlIjoiMDMwOTE4IiwiYmF0Y2hOdW1iZXIiOiIyMDIyMTAxNiIsInJlY2VpcHROdW1iZXIiOjE0NzEyNDk0LCJwYXltZW50TWV0aG9kIjoiY2FyZCIsInRocmVlZURTIjp7fX0sImFtb3VudCI6MTAuMDAsImN1cnJlbmN5IjoiTlpEIiwicmVmZXJlbmNlIjoiS2FybFJlZmVyZW5jZSIsInBhcnRpY3VsYXIiOiJLYXJsUGFydGljdWxhciIsImZyZXF1ZW5jeSI6InNpbmdsZSJ9LCJjYWxsYmFja1VybCI6Imh0dHBzOi8vaDFtbXY2ZTZ4OS5leGVjdXRlLWFwaS5hcC1zb3V0aGVhc3QtMi5hbWF6b25hd3MuY29tL2FkbWluL2h0dHBfc2xhY2tfZm9yd2FyZGVyIiwibWVyY2hhbnQiOnsidXJsIjoiaHR0cHM6Ly9pY2VjcmVhbXNob3AucGF5bWFyay5jby5uei8ifSwiaWQiOiJlZTQyNjE2My0zMGI4LTQwMGItYWU0Yy1hYTZkZjYwNDAyYTMiLCJ0cmFuc2FjdGlvblR5cGUiOiJwdXJjaGFzZSIsInNob3dQYXltZW50TWV0aG9kcyI6WyJjYXJkIiwib2UiXSwic3RhdHVzIjoiYXBwcm92ZWQiLCJjcmVhdGVkX2F0IjoiMjAyMi0xMC0xNlQyMzo0MToxNS40NjNaIiwibW9kaWZpZWRfYXQiOiIyMDIyLTEwLTE2VDIzOjQxOjQxLjU3MTI2ODFaIn0=",
  "signature": "ZjGVpOeJZQFiKDpiGRFRXflSmBpZHbjfQbKpz9dqo+EVxgvIerPkITKcsrnZNPuFE/L3iktZIeZCAEYAzhLGIiEMYPgJCu5yErVkW09HQtVx/OON4rPas8yQUuM3KvZGottsQ/cGPWYNtoEzk7WbZ9NawKLSw77PH3fIEHE9NxY2BE3I0EFv7sv73+/ESUGuvreqm2hvy2N0yHIU2yo49/0bYr5Z7JQGWSn0ycwUQIcVcW0DCILPaSt0xHRlNfJnndKIMXEDGMx8za4m/hmC30RtiK71+H3JU7J2Vb7hAoKSCPx0x+o+JGhYBOyFLYTnsK7HLmcAC3E2R+2RLqO4O222Xxb7hT9ySMO9i1yxWttLrOSOOCMbut/BlWK5LDs4OoDnH4cCGaFSqjEOevmxZrzJiDRVMP4joeAE0AJBXiI9+lQWXhXzZgAO3+M0AHQ+Hep5/N8pHq+2FO65lujKtE6uCTljai6r0GzIhe3gPbLSrOlnkZhERGU3mdGLaYc0jGutWHF3Q0EcpkoVh5j6I73JaVmOnFPJvJYPd59TFuqF7hepiU9975cdWEWCtaqV9wbXVJv8OR8v+Fp98pgA6iTBmMyr0wfEerz0ThbRrG4NknfDQuXtIpvzca2lHKT5yBZANISfkgBLsru7gipFv52czo+gwrkgZL+PHpeMq6k="
}

Post to callbackUrl
POST/callbackurl/

Custom Checkout will POST the transaction result to the callbackUrl you provided in /payment request with queryparams containing the transaction response. This callback will be triggered on completion of the transaction. Should we get a non-200 response, Worldline NZ will do 3 attempts in an interval of 1 minute each.

The merchant would still need to verify the signature using the public key by:

  • decrypting the signature by reading the value from the signature query param

  • generating a hash of the given paymentDetails query param

  • comparing (a) and (b) to confirm they match

Then you can retrieve the payment details by:

  • base64 decoding the paymentDetails query param

  • JSON.parse the result to get the JSON object

  • Post to callbackUrl

    • Headers

      Content-Type: application/json


Retrieve payment

GET custom-checkout.paymarkclick.co.nz/merchant/payment/
Responses200
Headers
Content-Type: application/json
Body
{
  "transaction": {
    "clickTransactionId": "P2209O0016863058",
    "result": {
      "paymentMethod": "oe"
    },
    "amount": 10,
    "currency": "NZD",
    "reference": "PaymentReference",
    "particular": "PaymentParticular"
  },
  "merchant": {
    "url": "https://icecreamshop.paymark.co.nz"
  },
  "id": "69a55d7d-2743-40bf-8ea6-d27439459d12",
  "redirectUrl": "https://icecreamshop.paymark.co.nz/payment/summary",
  "callbackUrl": "https://api.merchant.co.nz/payment-callback",
  "transactionType": "purchase",
  "showPaymentMethods": [
    "card",
    "oe"
  ],
  "status": "approved",
  "created_at": "2022-09-16T02:33:10.957Z",
  "modified_at": "2022-09-16T02:33:10.957Z"
}

Retrieve payment
GET/merchant/payment/

Environment Endpoint
UAT https://apitest.uat.paymark.nz/paymark/hosted-fields/merchant/payment/{paymentId}
Production https://api.paymark.nz/paymark/hosted-fields/merchant/payment/{paymentId}
URI Parameters
HideShow
id
string (required) Example: 69a55d7d-2743-40bf-8ea6-d27439459d12

The UUID of the payment id.


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;

Generated by aglio on 14 Oct 2024