Click Integration Guide - Card on File transactions

Cardholder-initiated Payments ¶

A cardholder-initiated CoF transaction is a transaction that is performed with the active participation of the cardholder. The two most common use cases for this are:

1. a digital wallet in your app or website, where the cardholder selects previously stored payment details for the current one-off transaction

2. a Mail Order or Telephone transaction where a cardholder indicates you should use previously stored card details to carry out a transaction

To indicate that the transaction was initiated by the cardholder, you must indicate that the source of the transaction is “Internet” or “MOTO”.

At the time the cardholder agrees for their payment details to be stored, you must indicate that the payment details will be stored. For subsequent payments initiated by the cardholder and where the cardholder’s stored payment details are used, you must indicate that the payment details were previously stored.

Examples ¶

Hosted Payment Page - cardholder enters details ¶

POST https://secure.paymarkclick.co.nz/api/webpayments/paymentservice/rest/WPRequest HTTP/1.1

Content-Type: application/x-www-form-urlencoded

account_id=700152&
username=90127&
password=Paymark123&
cmd=_xclick&
type=purchase&
amount=10.00&
reference=Reference&
particular=Particular&
return_url=https%3A%2F%2Fyour-site.com%2FMy-Return-URL%3FRef%3DReference&
transaction_frequency=single&
store_payment_token=2

Merchant Hosted APIs - cardholder enters details ¶

POST https://secure.paymarkclick.co.nz/api/transaction/purchase/ HTTP/1.1

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Content-Type: application/json

{
  "accountId":700152,
  "amount":10.00,
  "reference":"Reference",
  "particular":"Particular",
  "cardNumber":"4987654321098769",
  "cardType":"VISA",
  "cardExpiry":"0517",
  "cardHolder":"Mr John Smith",
  "cardCSC":"111",
  "storeCard":1,
  "tokenReference":"TokenReference",
  "transactionFrequency": "single",
  "transactionSource": "internet"
}

Cardholder selects stored card details to make a purchase ¶

POST https://secure.paymarkclick.co.nz/api/transaction/purchase/6971410 HTTP/1.1

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Content-Type: application/json

{
  "accountId":700152,
  "amount":10.00,
  "reference":"Reference",
  "particular":"Particular",
  "transactionFrequency": "single",
  "transactionSource": "internet"
}

Custom Checkout - cardholder enters details ¶

With Custom Checkout your server creates the payment, then loads the hosted card fields into your own checkout page using the returned payment id. The cardholder enters their details directly into those fields. The transaction source is always Internet - Custom Checkout does not need (and does not accept) a transaction source field.

POST https://api.paymark.nz/paymark/hosted-fields/payment HTTP/1.1

Authorization: Bearer (bearer token)

Content-Type: application/json

{
  "merchant": {
    "url": "https://your-site.com",
    "accountId": "700152",
    "organisationId": "90127"
  },
  "transactionType": "purchase",
  "showPaymentMethods": ["card"],
  "transaction": {
    "amount": 10.00,
    "currency": "NZD",
    "reference": "Reference",
    "particular": "Particular",
    "frequency": "single"
  },
  "redirectUrl": "https://your-site.com/My-Return-URL?Ref=Reference",
  "callbackUrl": "https://your-site.com/webhooks/custom-checkout"
}

Custom Checkout uses an OAuth bearer token, not the Basic credentials used by the other Click APIs. Obtain one from https://api.paymark.nz/bearer (UAT: https://apitest.uat.paymark.nz/bearer) using the Consumer Key and Consumer Secret generated in the Click Portal. The UAT host for the payment call is https://apitest.uat.paymark.nz.

The indicator that the payment details will be stored is not part of the call above. You set storeCardMethod when you initialise the plugin in your checkout page, and the hosted fields send it with the card details when the cardholder submits the payment. The options are:

• STORE_CARD - tokenise the card without asking the cardholder

• CUSTOMER_SELECTION - show the cardholder a checkbox and let them choose

• DO_NOT_STORE_CARD - never store the card. This is the default, so it applies if you do not set the option at all

Omit agreementId when frequency is single - it is rejected if supplied.

Merchant-initiated Payments ¶

Overview ¶

A merchant-initiated transaction is a transaction that is performed using stored payment details but without the active participation of the cardholder. Common use cases include:

• products or services that require you to charge a cardholder using a predefined schedule, e.g., magazine subscription, gym membership (Recurring transactions)

• offer the cardholder a service to charge them on demand for services, e.g., account top-ups when the amount available falls below a defined threshold (Unscheduled transactions.

In such cases, the cardholder must agree for you store their payment details for this purpose and allow you to subsequently initiate payments with the stored payment details without their active participation. You must send information about this agreement to Paymark with each transaction under the agreement.

Starting an agreement ¶

Depending on your business model there are two ways to start an agreement. If you will take the first payment under the agreement at the time the cardholder agrees for their payment details to be stored, you should send a payment transaction with the information below.

If, however, you intend to take the first payment at a future date, you should send a status check transaction with the information below.

Hosted Payment Page - cardholder enters details ¶

POST https://secure.paymarkclick.co.nz/api/webpayments/paymentservice/rest/WPRequest HTTP/1.1

Content-Type: application/x-www-form-urlencoded

account_id=700152&
username=90127&
password=Paymark123&
cmd=_xclick&
type=purchase&
amount=10.00&
reference=Reference&
particular=Particular&
return_url=https%3A%2F%2Fyour-site.com%2FMy-Return-URL%3FRef%3DReference&
transaction_frequency=recurring&
agreement_id=87a09a2a-3cf2-43e7-8e54-8efc020c4f6c&
store_payment_token=2

Merchant Hosted APIs - cardholder enters details ¶

POST https://secure.paymarkclick.co.nz/api/transaction/purchase/ HTTP/1.1

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Content-Type: application/json

{
  "accountId":700152,
  "amount":10.00,
  "reference":"Reference",
  "particular":"Particular",
  "cardNumber":"4987654321098769",
  "cardType":"VISA",
  "cardExpiry":"0517",
  "cardHolder":"Mr John Smith",
  "cardCSC":"111",
  "storeCard":1,
  "tokenReference":"TokenReference",
  "transactionFrequency":"recurring",
  "transactionSource": "internet",
  "agreementId":"87a09a2a-3cf2-43e7-8e54-8efc020c4f6c"
}

Custom Checkout - first payment taken now ¶

POST https://api.paymark.nz/paymark/hosted-fields/payment HTTP/1.1

Authorization: Bearer (bearer token)

Content-Type: application/json

{
  "merchant": {
    "url": "https://your-site.com",
    "accountId": "700152",
    "organisationId": "90127"
  },
  "transactionType": "purchase",
  "showPaymentMethods": ["card"],
  "transaction": {
    "amount": 10.00,
    "currency": "NZD",
    "reference": "Reference",
    "particular": "Particular",
    "frequency": "recurring",
    "agreementId": "87a09a2a-3cf2-43e7-8e54-8efc020c4f6c"
  },
  "redirectUrl": "https://your-site.com/My-Return-URL?Ref=Reference",
  "callbackUrl": "https://your-site.com/webhooks/custom-checkout"
}

agreementId is mandatory for every frequency other than single. Initialise the plugin with storeCardMethod set to STORE_CARD, as described under Cardholder-initiated Payments above.

Custom Checkout - no payment taken yet ¶

Use transactionType statuscheck with a zero amount. The card is always stored on a status check, so storeCardMethod does not need to be STORE_CARD to force it.

POST https://api.paymark.nz/paymark/hosted-fields/payment HTTP/1.1

Authorization: Bearer (bearer token)

Content-Type: application/json

{
  "merchant": {
    "url": "https://your-site.com",
    "accountId": "700152",
    "organisationId": "90127"
  },
  "transactionType": "statuscheck",
  "showPaymentMethods": ["card"],
  "transaction": {
    "amount": 0,
    "currency": "NZD",
    "reference": "Reference",
    "particular": "Particular",
    "frequency": "recurring",
    "agreementId": "87a09a2a-3cf2-43e7-8e54-8efc020c4f6c"
  },
  "redirectUrl": "https://your-site.com/My-Return-URL?Ref=Reference",
  "callbackUrl": "https://your-site.com/webhooks/custom-checkout"
}

Subsequent transactions under an agreement ¶

For subsequent payments initiated by the merchant and where the cardholder’s stored payment details are used, you must provide the information below.

Purchase using stored card, triggered by merchant ¶

POST https://secure.paymarkclick.co.nz/api/transaction/purchase/6971410 HTTP/1.1

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Content-Type: application/json

{
  "accountId":700152,
  "amount":10.00,
  "reference":"Reference",
  "particular":"Particular",
  "transactionSource": "merchant",
  "transactionFrequency":"recurring",
  "agreementId":"87a09a2a-3cf2-43e7-8e54-8efc020c4f6c"
}

Maintaining an agreement ¶

The payment details used under an agreement may change in some circumstances, e.g.

• the cardholder lost their card and was issued a new card

• the cardholder changed bank

• the card had insufficient funds and the cardholder provided alternative payment details

If card details have changed (except in case of reissue of expired card and card scheme tokens), you must perform a cardholder-initiated transaction using the same Agreement ID to update the payment details before performing a merchant-initiated transaction with the new card number.

Hosted Payment Page ¶

POST https://secure.paymarkclick.co.nz/api/webpayments/paymentservice/rest/WPRequest HTTP/1.1

Content-Type: application/x-www-form-urlencoded

account_id=700152&
username=90127&
password=Paymark123&
cmd=_xclick&
type=statuscheck&
amount=0&
reference=Reference&
particular=Particular&
return_url=https%3A%2F%2Fyour-site.com%2FMy-Return-URL%3FRef%3DReference&
transaction_frequency=recurring&
agreement_id=87a09a2a-3cf2-43e7-8e54-8efc020c4f6c&
store_payment_token=2

All other REST APIs ¶

POST https://secure.paymarkclick.co.nz/api/transaction/statuscheck/ HTTP/1.1

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Content-Type: application/json

{
  "accountId":700152,
  "reference":"Reference",
  "particular":"Particular",
  "cardNumber":"4987654321098769",
  "cardType":"VISA",
  "cardExpiry":"0517",
  "cardHolder":"Mr John Smith",
  "cardCSC":"111",
  "storeCard":1,
  "tokenReference":"TokenReference",
  "transactionSource": "internet",
  "transactionFrequency":"recurring",
  "agreementId":"87a09a2a-3cf2-43e7-8e54-8efc020c4f6c"
}

Custom Checkout ¶

Create a new payment with transactionType statuscheck and the same Agreement ID, then load the hosted fields as usual. The cardholder enters their new card details; the new card is stored against the existing agreement.

POST https://api.paymark.nz/paymark/hosted-fields/payment HTTP/1.1

Authorization: Bearer (bearer token)

Content-Type: application/json

{
  "merchant": {
    "url": "https://your-site.com",
    "accountId": "700152",
    "organisationId": "90127"
  },
  "transactionType": "statuscheck",
  "showPaymentMethods": ["card"],
  "transaction": {
    "amount": 0,
    "currency": "NZD",
    "reference": "Reference",
    "particular": "Particular",
    "frequency": "recurring",
    "agreementId": "87a09a2a-3cf2-43e7-8e54-8efc020c4f6c"
  },
  "redirectUrl": "https://your-site.com/My-Return-URL?Ref=Reference",
  "callbackUrl": "https://your-site.com/webhooks/custom-checkout"
}