Cards & Wallets · Your payment page · Advanced features

Custom Fields

Send custom fields with your payment requests to capture information that is specific to your business, such as a discount code or customer account reference.

For an overview of custom fields, including how they work when using Your Payment Page, see Custom fields.

When you build the payment flow yourself, add a customFields object at the top level of the request. It contains an array of fieldState objects:

Field	Type	Description
`name`	string	The name of the custom field.
`value`	string	The value of the custom field.
`transient`	boolean	If `true`, the value is not stored as part of the transaction.

You can also include custom fields on other requests, such as refunds, payouts and account verification.

Payment request with custom fields

The example below shows a payment request that includes custom fields alongside the transaction and payment method. We return the values you sent in the response under customFields.fieldState.

Payment with custom fields

EndpointDefinition

POST /acceptor/rest/transactions/{instId}/payment

Request body

{
  "transaction": {
    "currency": "GBP",
    "amount": 10.00,
    "description": "Sample Transaction",
    "merchantRef": "TXN-CF-0001",
    "commerceType": "ECOM"
  },
  "customFields": {
    "fieldState": [
      {
        "name": "discountCode",
        "value": "SUMMER2025",
        "transient": false
      },
      {
        "name": "customerAccountRef",
        "value": "CUST-1234",
        "transient": false
      },
      {
        "name": "termsAccepted",
        "value": "true",
        "transient": true
      }
    ]
  },
  "paymentMethod": {
    "card": {
      "pan": "9902000000000018",
      "cv2": "456",
      "expiryDate": "1229",
      "cardHolderName": "John Smith"
    }
  }
}

cURL

curl -X POST "{targetEnvironmentPath}/acceptor/rest/transactions/{instId}/payment" \
  -u "{apiUser}:{apiPassword}" \
  -H "Content-Type: application/json" \
  -d '{
  "transaction": {
    "currency": "GBP",
    "amount": 10.00,
    "description": "Sample Transaction",
    "merchantRef": "TXN-CF-0001",
    "commerceType": "ECOM"
  },
  "customFields": {
    "fieldState": [
      {
        "name": "discountCode",
        "value": "SUMMER2025",
        "transient": false
      },
      {
        "name": "customerAccountRef",
        "value": "CUST-1234",
        "transient": false
      },
      {
        "name": "termsAccepted",
        "value": "true",
        "transient": true
      }
    ]
  },
  "paymentMethod": {
    "card": {
      "pan": "9902000000000018",
      "cv2": "456",
      "expiryDate": "1229",
      "cardHolderName": "John Smith"
    }
  }
}'

Response

HTTP/1.1 201 Created

{
  "processing": {
    "model": "MANAGE",
    "authResponse": {
      "statusCode": "00",
      "acquirerName": "Barclays Merchant Services",
      "message": "AUTH CODE:394755",
      "authCode": "394755",
      "gatewayReference": "6e1d975cab391d47b42b97444f62c50b",
      "gatewayMessage": "AUTH CODE:394755",
      "avsAddressCheck": "NOT_CHECKED",
      "avsPostcodeCheck": "NOT_CHECKED",
      "cv2Check": "MATCHED",
      "status": "AUTHORISED"
    },
    "route": "CPE"
  },
  "paymentMethod": {
    "registered": false,
    "card": {
      "cardFingerprint": "l313hfHapXJiLXyROD3X6P75k9E=",
      "new": true,
      "cardType": "VISA_DEBIT",
      "cardUsageType": "DEBIT",
      "cardScheme": "VISA",
      "cardCategory": "DEBIT",
      "maskedPan": "990200******0018",
      "expiryDate": "1229",
      "issuer": "PAY360 TESTING",
      "issuerCountry": "GBR",
      "cardHolderName": "John Smith"
    },
    "billingAddress": {},
    "paymentClass": "CARD",
    "reuse": {
      "storage": "NONE"
    }
  },
  "customFields": {
    "fieldState": [
      {
        "name": "discountCode",
        "value": "SUMMER2025",
        "transient": false
      },
      {
        "name": "customerAccountRef",
        "value": "CUST-1234",
        "transient": false
      },
      {
        "name": "termsAccepted",
        "value": "true",
        "transient": true
      }
    ]
  },
  "threeDSecure": {
    "versionsAttempted": [
      {
        "version": 2,
        "availability": "ISSUER_NO_3DS"
      }
    ]
  },
  "transaction": {
    "transactionId": "10254743577",
    "merchantRef": "TXN-CF-0001",
    "merchantDescription": "Sample Transaction",
    "status": "SUCCESS",
    "stage": "COMPLETE",
    "type": "PAYMENT",
    "amount": 10.0,
    "consumerSpend": 10.0,
    "currency": "GBP",
    "transactionTime": "2026-09-09T15:10:55.478+01:00",
    "receivedTime": "2026-09-09T15:10:55.478+01:00",
    "customerInitiated": true
  },
  "outcome": {
    "status": "SUCCESS",
    "reasonCode": "S100",
    "reasonMessage": "Authorised"
  },
  "strongCustomerAuthentication": {
    "transactionType": "GOODS_OR_SERVICES"
  },
  "trace": "Tyz6OAWw82a7CfL1Z5l2ajA",
  "link": [
    {
      "href": "https://api.mite.pay360.com/acceptor/rest/transactions/5315271/10254743577",
      "rel": "transaction"
    }
  ]
}