Farmlands POS Integration Guide

Centrapay and Farmlands have entered a partnership to enable a digital way for Farmlands Card Partners to accept Farmlands Card as payment at the point of sale. This solution will position Card Partners to be able to also accept a digital form of the Farmlands Card in the future.

Farmlands Card Partners need to be approved by Farmlands prior to enabling Farmlands Card as a payment option through the Centrapay integration. Contact your Card Portfolio Manager or the Card Specialist team at card.specialist@farmlands.co.nz to work through the onboarding process.

Centrapay Integration Benefits

Integrating with Centrapay streamlines the process for authorising and invoicing Farmlands Card Payments. The integration provides:

Ability to complete real-time, industry standard card checks
Reduced exposure to card fraud.

Secure and instant means of sending full invoice details to Farmlands. Improved staff & customer experiences through ease of facilitating a Farmlands payment. Merchants can opt-in to accept other assets as payment methods with Centrapay.

Payment Flow Overview

Farmlands integrations use Centrapay’s Quick Pay Barcode Flow For Merchants to connect to Cardholders and accept Farmlands transactions.

See also: Requesting Payment

Farmlands Card Partners must pass line items when using standard payment flow.

Loading Diagram...

The Farmlands Cardholder presents their Farmlands Card for payment. The cashier at the point of sale will scan the Barcode or manually enter the 9-digit Farmlands Card number.

The Card number is under the Cardholder’s name on the front of the card; and under the barcode on the back of the card.

The back of an example Farmlands card, displaying a barcode and a 9-digit card number

The POS creates a Payment Request with the Farmlands Card barcode.

curl -X POST https://service.centrapay.com/api/payment-requests \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "barcode": "123456789",
    "conditionsEnabled": true,
    "configId": "5ee168e8597be5002af7b454",
    "invoiceRef": "sy8CRmo3sp3ArOpnfmb423",
    "lineItems": [
      {
        "name": "Hard Hat",
        "sku": "GH1234",
        "qty": "1",
        "price": "4000",
        "tax": "15",
        "discount": "400"
      },
      {
        "name": "Tool Belt",
        "sku": "GH1234",
        "qty": "1",
        "price": "6000",
        "tax": "15",
        "discount": "600"
      }
    ],
    "purchaseOrderRef": "oF6kj1QlH5gK0y9rjRHFh2",
    "value": {
      "amount": "10000",
      "currency": "NZD"
    }
  }'

{
  "barcode": "123456789",
  "conditionsEnabled": true,
  "configId": "5ee168e8597be5002af7b454",
  "createdAt": "2021-06-08T04:04:27.426Z",
  "expiresAt": "2021-06-08T04:06:27.426Z",
  "expirySeconds": 120,
  "id": "MhocUmpxxmgdHjr7DgKoKw",
  "invoiceRef": "sy8CRmo3sp3ArOpnfmb423",
  "lineItems": [
    {
      "name": "Hard Hat",
      "sku": "GH1234",
      "qty": "1",
      "price": "4000",
      "tax": "15",
      "discount": "400"
    },
    {
      "name": "Tool Belt",
      "sku": "GH1234",
      "qty": "1",
      "price": "6000",
      "tax": "15",
      "discount": "600"
    }
  ],
  "merchantConditions": [
    {
      "id": "1",
      "name": "photo-id-check",
      "message": "Please check ID",
      "status": "awaiting-merchant"
    }
  ],
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantName": "Farmlands Card Partner",
  "patronCodeId": "V17FByEP9gm1shSG6a1Zzx",
  "paymentOptions": [
    {
      "amount": "10000",
      "assetType": "farmlands.nzd.main"
    }
  ],
  "purchaseOrderRef": "oF6kj1QlH5gK0y9rjRHFh2",
  "shortCode": "CP-C7F-ZS5",
  "status": "new",
  "updatedAt": "2021-06-08T04:04:27.426Z",
  "url": "https://app.centrapay.com/pay/MhocUmpxxmgdHjr7DgKoKw",
  "value": {
    "currency": "NZD",
    "amount": "10000"
  }
}

The POS polls the Payment Request every second for status changes.

curl https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw \
  -H "Authorization: $jwt"

{
  "barcode": "123456789",
  "conditionsEnabled": true,
  "configId": "5ee168e8597be5002af7b454",
  "createdAt": "2021-06-08T04:04:27.426Z",
  "expiresAt": "2021-06-08T04:06:27.426Z",
  "expirySeconds": 120,
  "id": "MhocUmpxxmgdHjr7DgKoKw",
  "invoiceRef": "sy8CRmo3sp3ArOpnfmb423",
  "lineItems": [
    {
      "name": "Hard Hat",
      "sku": "GH1234",
      "qty": "1",
      "price": "4000",
      "tax": "15",
      "discount": "400"
    },
    {
      "name": "Tool Belt",
      "sku": "GH1234",
      "qty": "1",
      "price": "6000",
      "tax": "15",
      "discount": "600"
    }
  ],
  "merchantConditions": [
    {
      "id": "1",
      "name": "photo-id-check",
      "message": "Please check ID",
      "status": "awaiting-merchant"
    }
  ],
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantName": "Farmlands Card Partner",
  "patronCodeId": "V17FByEP9gm1shSG6a1Zzx",
  "paymentOptions": [
    {
      "amount": "10000",
      "assetType": "farmlands.nzd.main"
    }
  ],
  "purchaseOrderRef": "oF6kj1QlH5gK0y9rjRHFh2",
  "shortCode": "CP-C7F-ZS5",
  "status": "new",
  "updatedAt": "2021-06-08T04:04:27.426Z",
  "url": "https://app.centrapay.com/pay/MhocUmpxxmgdHjr7DgKoKw",
  "value": {
    "currency": "NZD",
    "amount": "10000"
  }
}

Polling the Payment Request returns a list of pending merchantConditions in the response. The POS must prompt the cashier to accept or decline each Payment Condition in order to successfully complete a payment.

curl -X POST https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/conditions/1/accept \
  -H "X-Api-Key: $api_key"

{
  "activityNumber": "2",
  "conditionId": "1",
  "createdAt": "2022-05-12T01:17:00.000Z",
  "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
  "merchantConfigId": "5ee168e8597be5002af7b454",
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantName": "Farmlands Card Partner",
  "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
  "type": "accept-condition",
  "value": {
    "currency": "NZD",
    "amount": 100
  }
}

A successful payment is identified when all Payment Conditions have an accepted status and the Payment Request status is paid. Here, the POS must stop polling and display confirmation of the successful payment.

curl https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw \
  -H "Authorization: $jwt"

{
  "barcode": "123456789",
  "conditionsEnabled": true,
  "configId": "5ee168e8597be5002af7b454",
  "createdAt": "2021-06-08T04:04:27.426Z",
  "expiresAt": "2021-06-08T04:06:27.426Z",
  "expirySeconds": 120,
  "id": "MhocUmpxxmgdHjr7DgKoKw",
  "invoiceRef": "sy8CRmo3sp3ArOpnfmb423",
  "lineItems": [
    {
      "name": "Hard Hat",
      "sku": "GH1234",
      "qty": "1",
      "price": "4000",
      "tax": "15",
      "discount": "400"
    },
    {
      "name": "Tool Belt",
      "sku": "GH1234",
      "qty": "1",
      "price": "6000",
      "tax": "15",
      "discount": "600"
    }
  ],
  "merchantConditions": [
    {
      "id": "1",
      "name": "photo-id-check",
      "message": "Please check ID",
      "status": "accepted"
    }
  ],
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantName": "Farmlands Card Partner",
  "patronCodeId": "V17FByEP9gm1shSG6a1Zzx",
  "paymentOptions": [
    {
      "amount": "10000",
      "assetType": "farmlands.nzd.main"
    }
  ],
  "purchaseOrderRef": "oF6kj1QlH5gK0y9rjRHFh2",
  "shortCode": "CP-C7F-ZS5",
  "status": "paid",
  "updatedAt": "2021-06-08T04:04:27.426Z",
  "url": "https://app.centrapay.com/pay/MhocUmpxxmgdHjr7DgKoKw",
  "value": {
    "currency": "NZD",
    "amount": "10000"
  }
}

Payment Flow Implementation

The Payment Flow can only be used by existing Farmlands Card Partners. Card Partners must complete the following steps to accept Farmlands transactions.

Each Card Partner site must be correctly set up as a Merchant in Centrapay’s system.
Centrapay needs to supply Card Partners with API keys to allow them to authenticate their API requests.
Card Partners must meet basic payment requirements, including supporting Payment Conditions and Refunds in order to implement the Barcode Payment Flow.
Card Partners should extend the Barcode payment Flow to meet any additional requirements, these optional extensions include:
- Pre Auth payments when there is no invoice number available at the point of sale, or the purchase cannot be fulfilled immediately
- Supporting payments when the Cardholder is not physically present.
- Validating Farmlands barcodes before a transaction is initiated

Merchant Configuration

Each Card Partner site that needs to accept Farmlands Card payments must be set up as a separate Centrapay Merchant with its own Merchant Config. The Merchant Config contains a Farmlands Payment Option that allows the site to accept Farmlands Payments.

The POS needs to provide the unique Merchant Config ID for the Merchant when creating Payment Requests on their behalf.

Merchants and Merchant Configs are managed by Centrapay. Farmlands will provide Card Partners with these details.

Authentication

Requests to Centrapay’s APIs are authenticated by providing an API key in the X-Api-Key header. API Keys provide enduring access to a single Centrapay account.

curl https://service.centrapay.com/api/account-memberships \
  -H "X-Api-Key: $api_key"

Contact integrations@centrapay.com to be issued with your API keys.

Basic Requirements

The Payment Flow needs the following requirements to be met.

Card Partners MUST use the unique Merchant Config ID that was set up for the site that is accepting the payment when creating a Payment Request.
Card Partners MUST support Payment Conditions.
The POS MUST display a message to prompt the cashier to accept or decline any pending Payment Conditions.
The POS MUST include full details for all Line Items and an invoice number when creating a Payment Request where the purchase is being fulfilled immediately.

See the Pre Auth extension to accept payments when there is no invoice number available at the point of sale or the purchase cannot be fulfilled immediately.
The POS MUST stop polling the Payment Request when its status is no longer new.

Payment Conditions

Farmlands Card Partners must support this extension.

This extension enables the POS to enforce requiring an ID check for high-risk transactions.

Card Partners must extend the Barcode Flow to support this by creating Payment Requests with the conditionsEnabled flag set to true. The response will include the merchantConditions that must be accepted, and each condition will include a message field that the POS can display to the cashier.

The Payment Request must always be polled after accepting or declining a condition.

See also: Payment Conditions

Pre Auth

Farmlands Card Partners must support this extension when there is not an invoice number available at the point of sale or the purchase cannot be fulfilled immediately. This might happen if your stock is not on hand or you have a separate fulfilment process.

This extension enables the POS to create an authorisation that ensures funds are available and places a hold on them.

Card Partners can extend the Barcode Flow to support this by creating Payment Requests with the preAuth flag set to true.

Pre Auth Sequence

Loading Diagram...

The Cardholder presents their Farmlands Card for the POS to scan.
The POS authorises a Pre Auth payment by creating a Payment Request with the barcode on the Farmlands Card and the preauth flag. Creating a Payment Request must also enable the Payment Conditions extension and include full details for all Line Items.

curl -X POST https://service.centrapay.com/api/payment-requests \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "barcode": "123456789",
    "conditionsEnabled": true,
    "configId": "5ee168e8597be5002af7b454",
    "lineItems": [
      {
        "name": "Hard Hat",
        "sku": "GH1234",
        "qty": "1",
        "price": "4000",
        "tax": "15",
        "discount": "400"
      },
      {
        "name": "Tool Belt",
        "sku": "GH1234",
        "qty": "1",
        "price": "6000",
        "tax": "15",
        "discount": "600"
      }
    ],
    "preAuth": true,
    "value": {
      "amount": "10000",
      "currency": "NZD"
    }
  }'

{
  "barcode": "123456789",
  "conditionsEnabled": true,
  "configId": "5efbe2fb96c08357bb2b9242",
  "createdAt": "2021-06-08T04:04:27.426Z",
  "expiresAt": "2021-06-08T04:06:27.426Z",
  "expirySeconds": 120,
  "id": "MhocUmpxxmgdHjr7DgKoKw",
  "invoiceRef": "sy8CRmo3sp3ArOpnfmb423",
  "lineItems": [
    {
      "name": "Hard Hat",
      "sku": "GH1234",
      "qty": "1",
      "price": "4000",
      "tax": "15",
      "discount": "400"
    },
    {
      "name": "Tool Belt",
      "sku": "GH1234",
      "qty": "1",
      "price": "6000",
      "tax": "15",
      "discount": "600"
    }
  ],
  "merchantConditions": [
    {
      "id": "1",
      "name": "photo-id-check",
      "message": "Please check ID",
      "status": "awaiting-merchant"
    }
  ],
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantName": "Farmlands Card Partner",
  "paymentOptions": [
    {
      "amount": "10000",
      "assetType": "farmlands.nzd.main"
    }
  ],
  "patronCodeId": "V17FByEP9gm1shSG6a1Zzx",
  "purchaseOrderRef": "oF6kj1QlH5gK0y9rjRHFh2",
  "shortCode": "CP-C7F-ZS5",
  "status": "new",
  "updatedAt": "2021-06-08T04:04:27.426Z",
  "url": "https://app.centrapay.com/pay/MhocUmpxxmgdHjr7DgKoKw",
  "value": {
    "currency": "NZD",
    "amount": "10000"
  }
}

The POS polls the Payment Request every second for status changes.

curl https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw \
  -H "Authorization: $jwt"

{
  "barcode": "123456789",
  "conditionsEnabled": true,
  "configId": "5ee168e8597be5002af7b454",
  "createdAt": "2021-06-08T04:04:27.426Z",
  "expiresAt": "2021-06-08T04:06:27.426Z",
  "expirySeconds": 120,
  "id": "MhocUmpxxmgdHjr7DgKoKw",
  "invoiceRef": "sy8CRmo3sp3ArOpnfmb423",
  "lineItems": [
    {
      "name": "Hard Hat",
      "sku": "GH1234",
      "qty": "1",
      "price": "4000",
      "tax": "15",
      "discount": "400"
    },
    {
      "name": "Tool Belt",
      "sku": "GH1234",
      "qty": "1",
      "price": "6000",
      "tax": "15",
      "discount": "600"
    }
  ],
  "merchantConditions": [
    {
      "id": "1",
      "name": "photo-id-check",
      "message": "Please check ID",
      "status": "awaiting-merchant"
    }
  ],
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantName": "Farmlands Card Partner",
  "patronCodeId": "V17FByEP9gm1shSG6a1Zzx",
  "paymentOptions": [
    {
      "amount": "10000",
      "assetType": "farmlands.nzd.main"
    }
  ],
  "purchaseOrderRef": "oF6kj1QlH5gK0y9rjRHFh2",
  "shortCode": "CP-C7F-ZS5",
  "status": "new",
  "updatedAt": "2021-06-08T04:04:27.426Z",
  "url": "https://app.centrapay.com/pay/MhocUmpxxmgdHjr7DgKoKw",
  "value": {
    "currency": "NZD",
    "amount": "10000"
  }
}

Polling the Payment Request returns a list of pending merchantConditions in the response. The POS must prompt the cashier to accept or decline each Payment Condition in order to successfully authorise a Pre Auth payment.

curl -X POST https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/conditions/1/accept \
  -H "X-Api-Key: $api_key"

{
  "activityNumber": "2",
  "conditionId": "1",
  "createdAt": "2022-05-12T01:17:00.000Z",
  "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
  "merchantConfigId": "5ee168e8597be5002af7b454",
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantName": "Farmlands Card Partner",
  "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
  "type": "accept-condition",
  "value": {
    "currency": "NZD",
    "amount": 100
  }
}

A successful authorisation is identified when all Payment Conditions have an accepted status, the Payment Request status is paid and the preAuthStatus is authorized. Here, the POS must stop polling and display confirmation of the successful authorisation.

curl https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw \
  -H "Authorization: $jwt"

{
  "barcode": "123456789",
  "conditionsEnabled": true,
  "configId": "5ee168e8597be5002af7b454",
  "createdAt": "2021-06-08T04:04:27.426Z",
  "expiresAt": "2021-06-08T04:06:27.426Z",
  "expirySeconds": 120,
  "id": "MhocUmpxxmgdHjr7DgKoKw",
  "invoiceRef": "sy8CRmo3sp3ArOpnfmb423",
  "lineItems": [
    {
      "name": "Hard Hat",
      "sku": "GH1234",
      "qty": "1",
      "price": "4000",
      "tax": "15",
      "discount": "400"
    },
    {
      "name": "Tool Belt",
      "sku": "GH1234",
      "qty": "1",
      "price": "6000",
      "tax": "15",
      "discount": "600"
    }
  ],
  "merchantConditions": [
    {
      "id": "1",
      "name": "photo-id-check",
      "message": "Please check ID",
      "status": "accepted"
    }
  ],
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantName": "Farmlands Card Partner",
  "patronCodeId": "V17FByEP9gm1shSG6a1Zzx",
  "paymentOptions": [
    {
      "amount": "10000",
      "assetType": "farmlands.nzd.main"
    }
  ],
  "preAuthStatus": "authorized",
  "purchaseOrderRef": "oF6kj1QlH5gK0y9rjRHFh2",
  "shortCode": "CP-C7F-ZS5",
  "status": "paid",
  "updatedAt": "2021-06-08T04:04:27.426Z",
  "url": "https://app.centrapay.com/pay/MhocUmpxxmgdHjr7DgKoKw",
  "value": {
    "currency": "NZD",
    "amount": "10000"
  }
}

When the purchase is ready to be fulfilled, the POS makes a Pre Auth confirmation against the Payment Request. Multiple confirmations can be performed against an authorisation but the total value cannot exceed the original authorised value.

curl -X POST https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/confirm \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "e8df06e2-13a5-48b4-b670-3fd6d815fe0a",
    "invoiceRef": "sy8CRmo3sp3ArOpnfmb423",
    "lineItems": [
      {
        "name": "Hard Hat",
        "sku": "GH1234",
        "qty": "1",
        "price": "4000",
        "tax": "15",
        "discount": "400"
      }
    ],
    "value": {
      "amount": "4000",
      "currency": "NZD"
    },
  }'

{
  "activityNumber": "3",
  "createdAt": "2021-06-08T04:04:27.426Z",
  "createdByAccountId": "Jaim1Cu1Q55uooxSens6yk",
  "createdByAccountName": "Farmlands Card Partner",
  "idempotencyKey": "e8df06e2-13a5-48b4-b670-3fd6d815fe0a",
  "invoiceRef": "sy8CRmo3sp3ArOpnfmb423",
  "lineItems": [
    {
      "name": "Hard Hat",
      "sku": "GH1234",
      "qty": "1",
      "price": "4000",
      "tax": "15",
      "discount": "400"
    }
  ],
  "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
  "preAuth": true,
  "shortCode": "CP-C7F-ZS5-03",
  "type": "confirmation",
  "updatedAt": "2021-06-08T04:04:27.426Z",
  "value": {
    "amount": "4000",
    "currency": "NZD"
  }
}

The POS releases any remaining authorised funds against the Payment Request back to the Cardholder. To confirm if there are funds requiring release you can list payment activities and sum the confirmation payment activities.

Only call release if there are funds requiring release.

curl -X POST https://service.centrapay.com/api/payment-requests/MhocUmpxxmgdHjr7DgKoKw/release \
  -H "X-Api-Key: $api_key"

{
  "activityNumber": "4",
  "assetType": "farmlands.nzd.main",
  "createdAt": "2021-06-12T01:17:00.000Z",
  "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
  "merchantConfigId": "5ee168e8597be5002af7b454",
  "merchantId": "26d3Cp3rJmbMHnuNJmks2N",
  "merchantName": "Farmlands Card Partner",
  "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
  "preAuth": true,
  "shortCode": "CP-C7F-ZS5-05",
  "type": "release",
  "value": {
    "currency": "NZD",
    "amount": "6000"
  }
}

See also: Requesting Pre Auth

Cardholder Not Present

Farmlands Card Partners must support this extension if they accept payments when the Cardholder is not physically present when a payment is authorised. For example, to accept phone-based orders or orders where the Farmlands barcode is already known.

Please refer to your Farmlands Card Partner Acceptance Terms and Conditions to understand the risks involved with these transactions.

Card Partners can extend the Barcode Flow to support this by creating Payment Requests with the patronNotPresent flag set to true.

curl -X POST https://service.centrapay.com/api/payment-requests \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "barcode": "123456789",
    "conditionsEnabled": true,
    "configId": "5ee168e8597be5002af7b454",
    "invoiceRef": "sy8CRmo3sp3ArOpnfmb423",
    "lineItems": [
      {
        "name": "Hard Hat",
        "sku": "GH1234",
        "qty": "1",
        "price": "4000",
        "tax": "15",
        "discount": "400"
      },
      {
        "name": "Tool Belt",
        "sku": "GH1234",
        "qty": "1",
        "price": "6000",
        "tax": "15",
        "discount": "600"
      }
    ],
    "patronNotPresent": true,
    "purchaseOrderRef": "oF6kj1QlH5gK0y9rjRHFh2",
    "value": {
      "amount": "10000",
      "currency": "NZD"
    }
  }'

See also: Patron Not Present

Validating Farmlands Barcodes

Farmlands Card Partners may optionally decode a scanned Farmlands Barcode to confirm that it is valid and apply Farmlands discounts before creating a Payment Request.

curl -X POST https://service.centrapay.com/api/decode \
  -H "Authorization: $jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "123456789",
    "merchantConfigId": "5ee168e8597be5002af7b454",
    "scannedBy": "merchant"
  }'

{
  "code": "123456789",
  "displayName": "Farmlands Card",
  "merchantConfigId": "5ee168e8597be5002af7b454",
  "provider": "farmlands",
  "scannedBy": "merchant"
}

Handling Payment Errors

The POS must follow Centrapay’s guidelines on handling errors when dealing with inconsistencies in Payment Request statuses due to network issues or race conditions.

See also: Merchant Integration Error Handling

Refunds

Farmlands Card Partners must support refunds.

Cardholder purchases are refunded by refunding the Payment Request.

When the Cardholder presents a transaction reference (e.g. a Payment Request short code or externalRef) on their paper receipt, the POS should use this reference to look up the Payment Request ID and initiate the refund.

Loading Diagram...

The Cardholder presents a transaction reference on their paper receipt. The POS looks up the Payment Request ID using the transaction reference.
The POS refunds the Payment Request using its ID.

curl -X POST https://service.centrapay.com/api/payment-requests/{paymentRequestId}/refund \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalRef": "e8df06e2-13a5-48b4-b670-3fd6d815fe0a",
    "merchantConfigId": "5ee168e8597be5002af7b454",
    "lineItems": [
      {
        "name": "Tool Belt",
        "sku": "GH1234",
        "qty": "1",
        "price": "6000",
        "tax": "15",
        "discount": "600"
      }
    ],
    "value": {
      "amount": "6000",
      "currency": "NZD"
    }
  }'

{
  "activityNumber": "4",
  "assetType": "farmlands.nzd.main",
  "createdAt": "2021-06-12T01:17:00.000Z",
  "createdBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "invoiceRef": "sy8CRmo3sp3ArOpnfmb423",
  "merchantAccountId": "C4QnjXvj8At6SMsEN4LRi9",
  "merchantConfigId": "5ee168e8597be5002af7b454",
  "merchantId": "5ee0c486308f590260d9a07f",
  "merchantName": "Farmlands Card Partner",
  "paymentRequestCreatedBy": "crn::user:0af834c8-1110-11ec-9072-3e22fb52e878",
  "paymentRequestId": "MhocUmpxxmgdHjr7DgKoKw",
  "shortCode": "CP-C7F-ZS5-04",
  "type": "refund",
  "value": {
    "currency": "NZD",
    "amount": "100"
  }
}

See also: Initiating Refunds

Short Codes

Payment Requests have a short code field that is human- and OCR-friendly. When combined with the date or merchant id, short codes can unambiguously identify the correct Payment Request.

Short codes can be used for initiating refunds by making them available to the Cardholder on a paper printout.

Card Partners should store the short code for each transaction. This helps with reconciliation if a transaction query occurs.

Some Payment Activities are repeatable (e.g. Pre Auth Confirmations and Refunds) so these have their own unique short code in order to disambiguate them. The short codes for these activities are different from the original Payment Request short code.

Testing Your Integration

Merchant Integrators need to work with Farmlands and Centrapay to get set up to test payments. Please contact Farmlands to organise full end-to-end testing.

You need to go through the following steps in order to test your integration in a test environment:

Centrapay must set you up with a test merchant and merchant config ID, and issue you with an API key before you can make API requests.
Integrators can use the Farmlands test barcodes below to test different scenarios.

Test Scenario Farmlands Card Barcode
Active Card with available balance 424242424
Active Card with no available balance 434343434
Expired Card 454545454
Inactive Card 464646464
Centrapay can set you up with a Centrapay Portal account and a test Merchant to allow you to verify that transactions are being processed correctly.

Test Scenario	Farmlands Card Barcode
Active Card with available balance	`424242424`
Active Card with no available balance	`434343434`
Expired Card	`454545454`
Inactive Card	`464646464`

Certification Requirements

For Centrapay to allow integrations to have production assets turned on, we require partners to complete a Certification Process.

The Certification Process includes checking that Farmlands POS integrators are meeting Centrapay’s Point Of Sale requirements, and the following additional requirements.

POS Requirements

The POS MUST support manual barcode entry.
The POS scanner SHOULD be capable of scanning the barcode on the back of a Farmlands Card.

Barcode Flow Requirements

The POS MUST use the unique Merchant Config ID corresponding to the site accepting the Farmlands Card payment when creating a Payment Request.
The POS MUST provide an invoice number and full details for all Line Items when creating a Payment Request if the purchase is being fulfilled immediately.
Payment Conditions MUST be supported when creating a Payment Request. This is to enforce requiring an ID check for high-risk transactions and any future security enhancements.
The POS MUST always poll the Payment Request after accepting or declining a condition.

Line Item Requirements

Full details for Line Items MUST include the description, SKU, quantity, price, tax and the discount provided to the Cardholder.
The price of a Line Item MUST represent the amount that a Cardholder will pay for that Line Item, including tax and any discounts applied.
The total for all Line Item prices MUST sum to the Payment Request amount.
The price and discount for each Line Item MUST be provided in cents.
The currency for each Line Item MUST be consistent with the Payment Request value.

Patron Not Present Requirements

The Patron Not Present extension SHOULD be supported. This is required when the Cardholder is not physically present (e.g. over the phone) or when the Farmlands Barcode is already known.

Pre Auth Requirements

The Pre Auth extension MUST be supported when invoice numbers are not available at the time of purchase.
Payment Request short codes MUST be included when completion is performed through existing reconciliation channels.
Pre Auth Confirmations MUST be made with an idempotencyKey in order to prevent merchants from drawing down on authorised funds twice.
Pre Auth Confirmations MUST include an invoice number and full details for all Line Items.
Authorised funds that will not be confirmed MUST be released in order to return the funds to the Cardholder (e.g. orders that are cancelled before fulfilment).
Confirmed funds MUST be refunded in order to return them to the Cardholder. They cannot be released.

Refund Requirements

Refunds can be partial or full. Partial refunds can be performed multiple times but the total refunded amount cannot exceed the paid amount.
You MUST include an externalRef field, unique to each refund transaction, in order to ensure that a refund request can be retried safely.
At least one of externalRef and shortCode MUST be available to the patron (eg, on paper print-out).
You MUST include an invoice number and full details for all Line Items.
Short codes for refunds MUST be included when sending a PDF invoice or EDI file to Farmlands for settlement.

Refunds have their own short code that is different to the Payment Request short code.
Refunds made against a Pre Auth Confirmation MUST include the confirmationIdempotencyKey field used for original confirmation.

Next Steps

Processing Farmlands Card transactions through the Centrapay platform is only available to existing Farmlands Card Partners. Existing Card Partners who are interested in integrating with Centrapay should contact their Card Partnership Manager or the Card Specialist team at card.specialist@farmlands.co.nz to work through the onboarding process.
Reach out to integrations@centrapay.com to get your API keys and a copy of Centrapay’s Certification Process.