Linked Gateway Integration Guide

API Endpoint

Overview

Below you’ll find information on how to integrate with various functions provided by Linked Gateway. For any assistance with this integration, or if there is anything you’d like to see added, please contact Paymark on lgv2@paymark.co.nz.

Card on File

Overview

If you or your merchants collect payment details from cardholders, store them, and use them to process future payments, then you must correctly identify these transactions in order to comply with card scheme mandates for Credential on File (COF) transactions. Including the correct indicators can provide:

  • better understanding of risk levels for issuers

  • higher authorization approval rates and completed sales

  • improved customer experience

Cardholder-initiated Payments

A cardholder-initiated transaction is a transaction that is performed with the active participation of the cardholder e.g. eCommerce or MOTO transactions.

To indicate that the transaction was initiated by the cardholder, you must set transaction.source to “Web Site” or “MOTO”. Throughout this guide, we use an eCommerce payment (transaction.source=“Web Site”) to illustrate a cardholder-initiated transaction.

A cardholder-initiated transaction may be a one-off transaction where the payment details will not be stored. However, your merchants can enter an agreement with the cardholder to store their payment details for future use (usually as part of a customer registration or account creation process) and perform subsequent cardholder-initiated transactions using the stored payment details.

At the time the cardholder agrees for their payment details to be stored, you need to provide the following fields in the initial transaction:

field value
transaction.source “Web Site” or “MOTO”
transaction.storedCredentials “new”

For subsequent payments initiated by the cardholder (not by you or your merchant) and where the cardholder’s stored payment details are used, you must provide:

field value
transaction.source “Web Site” or “MOTO”
transaction.storedCredentials “stored”

Merchant-initiated Payments

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 Linked Gateway with each transaction under the agreement.

At the time the cardholder agrees for their payment details to be stored, you need to provide the following fields in the initial transaction:

field value
transaction.source “Web Site” or “MOTO”
transaction.storedCredentials “new”
transaction.frequency “Recurring” or “Unscheduled”
transaction.agreementId a unique identifier for the agreement e.g. uuid

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

field value
transaction.source “Merchant”
transaction.storedCredentials “stored”
transaction.frequency “Recurring” or “Unscheduled”
transaction.agreementId matching the agreementId in inital request

transaction.agreementId is a string of up to 100 characters long consisting of any characters.

If the merchant does not have a unique identifier for their agreement with the cardholder, they (or you) can:

  • Generate an ID. It must be stored and sumbitted to Linked Gateway with each transaction under the agreement.

  • Use an existing identifier, e.g. an order ID, subscription ID, account ID or another similar unique identifier.

If at the time of establishing a payment agreement with the cardholder, the merchant does not intend to charge the cardholder, e.g. if it’s a magazine subscription where the first payment is scheduled on a particular date of the month (other than today), you must submit a status check transaction with the relevant agreement details. This becomes the first transaction in the agreement and should include the same information as listed above where a payment transaction was used to initiate the 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), the merchant 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. Depending on the merchant’s business model, they may choose to create a new agreement.

If using a scheme token, the card number stored against the scheme token may automatically be updated by the scheme.

Payment

POST /transaction/payment
RequestsCustomer-Initiated, storing payment details for later useCustomer-Initiated, using stored payment detailsCustomer-Initiated, first payment under agreementMerchant-Initiated, using payment details strored under agreement
Headers
Authorization: Bearer uOABwqy14kv010MnLxI4dmb80xlR
Accept: application/vnd.paymark_api+json;version=2.0
Content-Type: application/vnd.paymark_api+json;version=2.0
Body
{
  "card": {
    "cardNumber": "5123456789012346",
    "expiryDate": "2022-07",
    "cardSecurityCodePresence": "Present",
    "cardSecurityCode": "111"
  },
  "merchant": {
    "cardAcceptorIdCode": "854321",
    "transactionReference": "Test Reference",
    "transactionInformation": "Test Info",
    "timeStamp": "2015-04-14T11:55:04Z"
  },
  "transaction": {
    "amount": 5649,
    "source": "Web Site",
    "storedCredentials": "new",
    "frequency": "Single"
  }
}
Responses201
Headers
Content-Type: application/vnd.paymark_api+json;version=2.0
Body
{
  "links": [
    {
      "href": "https://lgapi.uat.paymark.nz/transaction/payment/ec2b8e9d-2b88-4460-9257-11d7a629b43b",
      "rel": "self"
    }
  ],
  "id": "ec2b8e9d-2b88-4460-9257-11d7a629b43b",
  "status": "complete",
  "creationTime": "2015-04-14T11:55:04.946Z",
  "modificationTime": "2015-04-14T11:55:04.946Z",
  "card": {
    "token": "4ff817be-e6ce-4b66-a797-1a3dce362b3a",
    "maskedNumber": "512345..2346",
    "expiryDate": "2022-12",
    "cardSecurityCodePresence": "Present",
    "cardSecurityCodeResponse": "Not Processed"
  },
  "merchant": {
    "cardAcceptorIdCode": "854321",
    "transactionReference": "Test Reference",
    "transactionInformation": "Test Info",
    "street": "123 The Avenue",
    "suburb": "Auckland Heights",
    "city": "Auckland",
    "postalCode": "1000",
    "country": "NZ",
    "cardAcceptorName": "Mirandas Marvellous Muffins",
    "acquiringInstitutionId": "503513",
    "mcc": "1234",
    "terminal": "98765432101",
    "timeStamp": "2015-04-14T11:55:04.946Z"
  },
  "transaction": {
    "amount": 5649,
    "currency": "NZD",
    "source": "Web Site",
    "frequency": "single",
    "processorResponseCode": "00",
    "settlementDate": "2015-04-15",
    "authorisationCode": "123456",
    "retrievalReferenceNumber": "123456789012",
    "systemTraceAuditNumber": "061610",
    "storedCredentials": "new"
  }
}
Headers
Authorization: Bearer uOABwqy14kv010MnLxI4dmb80xlR
Accept: application/vnd.paymark_api+json;version=2.0
Content-Type: application/vnd.paymark_api+json;version=2.0
Body
{
  "card": {
    "cardNumber": "5123456789012346",
    "expiryDate": "2022-07",
    "cardSecurityCodePresence": "Present",
    "cardSecurityCode": "111"
  },
  "merchant": {
    "cardAcceptorIdCode": "854321",
    "transactionReference": "Test Reference",
    "transactionInformation": "Test Info",
    "timeStamp": "2015-04-14T11:55:04Z"
  },
  "transaction": {
    "amount": 5649,
    "source": "Web Site",
    "storedCredentials": "stored",
    "frequency": "Single"
  }
}
Responses201
Headers
Content-Type: application/vnd.paymark_api+json;version=2.0
Body
{
  "links": [
    {
      "href": "https://lgapi.uat.paymark.nz/transaction/payment/ec2b8e9d-2b88-4460-9257-11d7a629b43b",
      "rel": "self"
    }
  ],
  "id": "ec2b8e9d-2b88-4460-9257-11d7a629b43b",
  "status": "complete",
  "creationTime": "2015-04-14T11:55:04.946Z",
  "modificationTime": "2015-04-14T11:55:04.946Z",
  "card": {
    "token": "4ff817be-e6ce-4b66-a797-1a3dce362b3a",
    "maskedNumber": "512345..2346",
    "expiryDate": "2022-12",
    "cardSecurityCodePresence": "Not Present",
    "cardSecurityCodeResponse": "Not Processed"
  },
  "merchant": {
    "cardAcceptorIdCode": "854321",
    "transactionReference": "Test Reference",
    "transactionInformation": "Test Info",
    "street": "123 The Avenue",
    "suburb": "Auckland Heights",
    "city": "Auckland",
    "postalCode": "1000",
    "country": "NZ",
    "cardAcceptorName": "Mirandas Marvellous Muffins",
    "acquiringInstitutionId": "503513",
    "mcc": "1234",
    "terminal": "98765432101",
    "timeStamp": "2015-04-14T11:55:04.946Z"
  },
  "transaction": {
    "amount": 5649,
    "currency": "NZD",
    "source": "Web Site",
    "frequency": "single",
    "processorResponseCode": "00",
    "settlementDate": "2015-04-15",
    "authorisationCode": "123456",
    "retrievalReferenceNumber": "123456789012",
    "systemTraceAuditNumber": "061610",
    "storedCredentials": "stored"
  }
}
Headers
Authorization: Bearer uOABwqy14kv010MnLxI4dmb80xlR
Accept: application/vnd.paymark_api+json;version=2.0
Content-Type: application/vnd.paymark_api+json;version=2.0
Body
{
  "card": {
    "cardNumber": "5123456789012346",
    "expiryDate": "2022-07",
    "cardSecurityCodePresence": "Present",
    "cardSecurityCode": "111"
  },
  "merchant": {
    "cardAcceptorIdCode": "854321",
    "transactionReference": "Test Reference",
    "transactionInformation": "Test Info",
    "timeStamp": "2015-04-14T11:55:04Z"
  },
  "transaction": {
    "amount": 5649,
    "source": "Web Site",
    "storedCredentials": "new",
    "frequency": "Single",
    "agreementId": "5b29c055-6e8b-4213-a320-834490f747d8"
  }
}
Responses201
Headers
Content-Type: application/vnd.paymark_api+json;version=2.0
Body
{
  "links": [
    {
      "href": "https://lgapi.uat.paymark.nz/transaction/payment/ec2b8e9d-2b88-4460-9257-11d7a629b43b",
      "rel": "self"
    }
  ],
  "id": "ec2b8e9d-2b88-4460-9257-11d7a629b43b",
  "status": "complete",
  "creationTime": "2015-04-14T11:55:04.946Z",
  "modificationTime": "2015-04-14T11:55:04.946Z",
  "card": {
    "token": "4ff817be-e6ce-4b66-a797-1a3dce362b3a",
    "maskedNumber": "512345..2346",
    "expiryDate": "2022-12",
    "cardSecurityCodePresence": "Present",
    "cardSecurityCodeResponse": "Not Processed"
  },
  "merchant": {
    "cardAcceptorIdCode": "854321",
    "transactionReference": "Test Reference",
    "transactionInformation": "Test Info",
    "street": "123 The Avenue",
    "suburb": "Auckland Heights",
    "city": "Auckland",
    "postalCode": "1000",
    "country": "NZ",
    "cardAcceptorName": "Mirandas Marvellous Muffins",
    "acquiringInstitutionId": "503513",
    "mcc": "1234",
    "terminal": "98765432101",
    "timeStamp": "2015-04-14T11:55:04.946Z"
  },
  "transaction": {
    "amount": 5649,
    "currency": "NZD",
    "source": "Web Site",
    "frequency": "single",
    "processorResponseCode": "00",
    "settlementDate": "2015-04-15",
    "authorisationCode": "123456",
    "retrievalReferenceNumber": "123456789012",
    "systemTraceAuditNumber": "061610",
    "storedCredentials": "new",
    "agreementId": "5b29c055-6e8b-4213-a320-834490f747d8"
  }
}
Headers
Authorization: Bearer uOABwqy14kv010MnLxI4dmb80xlR
Accept: application/vnd.paymark_api+json;version=2.0
Content-Type: application/vnd.paymark_api+json;version=2.0
Body
{
  "card": {
    "cardNumber": "5123456789012346",
    "expiryDate": "2022-07",
    "cardSecurityCodePresence": "Not Present"
  },
  "merchant": {
    "cardAcceptorIdCode": "854321",
    "transactionReference": "Test Reference",
    "transactionInformation": "Test Info",
    "timeStamp": "2015-04-14T11:55:04Z"
  },
  "transaction": {
    "amount": 5649,
    "source": "Merchant",
    "storedCredentials": "stored",
    "frequency": "recurring",
    "agreementId": "5b29c055-6e8b-4213-a320-834490f747d8"
  }
}
Responses201
Headers
Content-Type: application/vnd.paymark_api+json;version=2.0
Body
{
  "links": [
    {
      "href": "https://lgapi.uat.paymark.nz/transaction/payment/ec2b8e9d-2b88-4460-9257-11d7a629b43b",
      "rel": "self"
    }
  ],
  "id": "ec2b8e9d-2b88-4460-9257-11d7a629b43b",
  "status": "complete",
  "creationTime": "2015-04-14T11:55:04.946Z",
  "modificationTime": "2015-04-14T11:55:04.946Z",
  "card": {
    "token": "4ff817be-e6ce-4b66-a797-1a3dce362b3a",
    "maskedNumber": "512345..2346",
    "expiryDate": "2022-12",
    "cardSecurityCodePresence": "Not Present",
    "cardSecurityCodeResponse": "Not Processed"
  },
  "merchant": {
    "cardAcceptorIdCode": "854321",
    "transactionReference": "Test Reference",
    "transactionInformation": "Test Info",
    "street": "123 The Avenue",
    "suburb": "Auckland Heights",
    "city": "Auckland",
    "postalCode": "1000",
    "country": "NZ",
    "cardAcceptorName": "Mirandas Marvellous Muffins",
    "acquiringInstitutionId": "503513",
    "mcc": "1234",
    "terminal": "98765432101",
    "timeStamp": "2015-04-14T11:55:04.946Z"
  },
  "transaction": {
    "amount": 5649,
    "currency": "NZD",
    "source": "Merchant",
    "frequency": "recurring",
    "processorResponseCode": "00",
    "settlementDate": "2015-04-15",
    "authorisationCode": "123456",
    "retrievalReferenceNumber": "123456789012",
    "systemTraceAuditNumber": "061610",
    "storedCredentials": "stored",
    "agreementId": "5b29c055-6e8b-4213-a320-834490f747d8"
  }
}

Payment
POST/transaction/payment

Status Check

POST /transaction/statuscheck
RequestsMaintain agreement, or set up agreement for later payment
Headers
Authorization: Bearer uOABwqy14kv010MnLxI4dmb80xlR
Accept: application/vnd.paymark_api+json;version=2.0
Content-Type: application/vnd.paymark_api+json;version=2.0
Body
{
    "card":{
        "cardNumber":"5123456789012346",
        "expiryDate":"2022-07",
        "cardSecurityCodePresence":"Present",
        "cardSecurityCode":"111"
    },
    "merchant":{
        "cardAcceptorIdCode":"854321",
        "transactionReference":"Test Reference",
        "transactionInformation":"Test Info",
        "timeStamp":"2015-04-14T11:55:04Z"
    },
    "transaction":{
        "amount":0,
        "source":"Web Site",
        "frequency":"Recurring",
        "storedCredentials": "new"
        "agreementId":"5b29c055-6e8b-4213-a320-834490f747d8"
    }
}
Responses201
Headers
Content-Type: application/vnd.paymark_api+json;version=2.0
Body
{
  "links": [
    {
      "href": "https://lgapi.uat.paymark.nz/transaction/payment/ec2b8e9d-2b88-4460-9257-11d7a629b43b",
      "rel": "self"
    }
  ],
  "id": "ec2b8e9d-2b88-4460-9257-11d7a629b43b",
  "status": "complete",
  "creationTime": "2015-04-14T11:55:04.946Z",
  "modificationTime": "2015-04-14T11:55:04.946Z",
  "card": {
    "token": "4ff817be-e6ce-4b66-a797-1a3dce362b3a",
    "maskedNumber": "512345..2346",
    "expiryDate": "2022-12",
    "cardSecurityCodePresence": "Present",
    "cardSecurityCodeResponse": "Not Processed"
  },
  "merchant": {
    "cardAcceptorIdCode": "854321",
    "transactionReference": "Test Reference",
    "transactionInformation": "Test Info",
    "street": "123 The Avenue",
    "suburb": "Auckland Heights",
    "city": "Auckland",
    "postalCode": "1000",
    "country": "NZ",
    "cardAcceptorName": "Mirandas Marvellous Muffins",
    "acquiringInstitutionId": "503513",
    "mcc": "1234",
    "terminal": "98765432101",
    "timeStamp": "2015-04-14T11:55:04.946Z"
  },
  "transaction": {
    "amount": 5649,
    "currency": "NZD",
    "source": "Web Site",
    "frequency": "recurring",
    "processorResponseCode": "00",
    "settlementDate": "2015-04-15",
    "authorisationCode": "123456",
    "retrievalReferenceNumber": "123456789012",
    "systemTraceAuditNumber": "061610",
    "storedCredentials": "new",
    "agreementId": "5b29c055-6e8b-4213-a320-834490f747d8"
  }
}

Status Check
POST/transaction/statuscheck

3DS

Overview

Detailed information on 3DS 1 and 2 flows and data are available in the main API documentation pages.

Generated by aglio on 11 Apr 2024