Cards & Wallets · Common features

Shipping address and order details

Send us the shipping address and the individual items that make up a payment, and we will keep them with the transaction.

You can submit order details and a shipping address on primary transaction requests, whether you build the payment yourself or use the PaySuite payment page. We copy the order details onto any secondary transaction that follows, such as a refund, a capture or a repeat.

Everything you send is shown against the transaction in the Merchant Portal, and is included in any email receipts we send.

We also pass the details on to downstream authorisation systems that make use of them, such as PayPal.

What you can send

Add an order object at the top level of the request:

Field	Type	Description
`orderRef`	string	Your reference for the order.
`taxAmount`	float	The tax included in the order.
`taxRate`	float	The tax rate applied to the order.
`shippingAddress`	object	Where the order is being shipped to. Takes the same fields as a billing address.
`items`	array	The individual items in the order.

Each entry in items describes one line of the order:

Field	Type	Description
`name`	string	The name of the item. Mandatory.
`description`	string	A longer description of the item.
`itemRef`	string	Your reference for the item.
`lineRef`	string	Your reference for this line of the order.
`itemAmount`	float	The price of a single item. Mandatory.
`quantity`	integer	How many of the item were ordered. Defaults to 1.
`totalAmount`	float	The price of the line. Defaults to `itemAmount` × `quantity`.
`itemTaxAmount`, `taxRate`, `totalTaxAmount`	float	The tax on the line.
`customFields`	array	Your own `name` and `value` pairs for the item.

The full definitions are on the Cards API endpoints reference.

When using your payment page

Send the order object alongside the transaction and payment method on your payment request. We return it on the response.

Payment with order details

EndpointDefinition

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

Request body

{
  "transaction": {
    "currency": "GBP",
    "amount": 22.18,
    "description": "Sample Transaction",
    "merchantRef": "TXN-ORD-0001",
    "commerceType": "ECOM"
  },
  "order": {
    "orderRef": "order_123abc",
    "shippingAddress": {
      "line1": "10 Street Road",
      "line2": "Town",
      "postcode": "AA1 2BB"
    },
    "items": [
      {
        "name": "red shoe",
        "description": "Some red shoes",
        "itemRef": "red001",
        "itemAmount": 5.0,
        "quantity": 2,
        "totalAmount": 10.0,
        "customFields": [
          {
            "name": "style",
            "value": "boot"
          },
          {
            "name": "height",
            "value": "ankle"
          }
        ]
      },
      {
        "name": "blue shoe",
        "itemRef": "blue003",
        "itemAmount": 4.06,
        "quantity": 3,
        "totalAmount": 12.18
      }
    ]
  },
  "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": 22.18,
    "description": "Sample Transaction",
    "merchantRef": "TXN-ORD-0001",
    "commerceType": "ECOM"
  },
  "order": {
    "orderRef": "order_123abc",
    "shippingAddress": {
      "line1": "10 Street Road",
      "line2": "Town",
      "postcode": "AA1 2BB"
    },
    "items": [
      {
        "name": "red shoe",
        "description": "Some red shoes",
        "itemRef": "red001",
        "itemAmount": 5.0,
        "quantity": 2,
        "totalAmount": 10.0,
        "customFields": [
          {
            "name": "style",
            "value": "boot"
          },
          {
            "name": "height",
            "value": "ankle"
          }
        ]
      },
      {
        "name": "blue shoe",
        "itemRef": "blue003",
        "itemAmount": 4.06,
        "quantity": 3,
        "totalAmount": 12.18
      }
    ]
  },
  "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:335056",
      "authCode": "335056",
      "gatewayReference": "32bd376abdf625e595432d21e5f83163",
      "gatewayMessage": "AUTH CODE:335056",
      "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": []
  },
  "threeDSecure": {
    "versionsAttempted": [
      {
        "version": 2,
        "availability": "ISSUER_NO_3DS"
      }
    ]
  },
  "transaction": {
    "transactionId": "10254736318",
    "merchantRef": "TXN-ORD-0001",
    "merchantDescription": "Sample Transaction",
    "status": "SUCCESS",
    "stage": "COMPLETE",
    "type": "PAYMENT",
    "amount": 22.18,
    "consumerSpend": 22.18,
    "currency": "GBP",
    "transactionTime": "2026-09-04T01:54:38.425+01:00",
    "receivedTime": "2026-09-04T01:54:38.425+01:00",
    "customerInitiated": true
  },
  "order": {
    "orderRef": "order_123abc",
    "shippingAddress": {
      "line1": "10 Street Road",
      "line2": "Town",
      "postcode": "AA1 2BB"
    },
    "items": [
      {
        "name": "red shoe",
        "description": "Some red shoes",
        "itemRef": "red001",
        "itemAmount": 5.0,
        "quantity": 2,
        "totalAmount": 10.0,
        "customFields": [
          {
            "name": "style",
            "value": "boot"
          },
          {
            "name": "height",
            "value": "ankle"
          }
        ]
      },
      {
        "name": "blue shoe",
        "itemRef": "blue003",
        "itemAmount": 4.06,
        "quantity": 3,
        "totalAmount": 12.18
      }
    ]
  },
  "outcome": {
    "status": "SUCCESS",
    "reasonCode": "S100",
    "reasonMessage": "Authorised"
  },
  "strongCustomerAuthentication": {
    "transactionType": "GOODS_OR_SERVICES"
  },
  "trace": "TTw7_rAMxWKMKf35SZ-QGrQ",
  "link": [
    {
      "href": "https://api.mite.pay360.com/acceptor/rest/transactions/5315271/10254736318",
      "rel": "transaction"
    }
  ]
}

When using the PaySuite payment page

Send the order object when you create the session. It stays with the transaction the session goes on to create, so you do not need to send it again.

Create a payment session with order details

EndpointDefinition

POST /hosted/rest/sessions/{instId}/payments

Request body

{
  "session": {
    "returnUrl": {
      "url": "https://www.example.com/return"
    }
  },
  "transaction": {
    "money": {
      "currency": "GBP",
      "amount": {
        "fixed": 22.18
      }
    },
    "merchantReference": "aReference"
  },
  "order": {
    "orderRef": "order_123abc",
    "shippingAddress": {
      "line1": "10 Street Road",
      "line2": "Town",
      "postcode": "AA1 2BB"
    },
    "items": [
      {
        "name": "red shoe",
        "description": "Some red shoes",
        "itemRef": "red001",
        "itemAmount": 5.0,
        "quantity": 2,
        "totalAmount": 10.0,
        "customFields": [
          {
            "name": "style",
            "value": "boot"
          },
          {
            "name": "height",
            "value": "ankle"
          }
        ]
      },
      {
        "name": "blue shoe",
        "itemRef": "blue003",
        "itemAmount": 4.06,
        "quantity": 3,
        "totalAmount": 12.18
      }
    ]
  }
}

cURL

curl -X POST "{targetEnvironmentPath}/hosted/rest/sessions/{instId}/payments" \
  -u "{apiUser}:{apiPassword}" \
  -H "Content-Type: application/json" \
  -d '{
  "session": {
    "returnUrl": {
      "url": "https://www.example.com/return"
    }
  },
  "transaction": {
    "money": {
      "currency": "GBP",
      "amount": {
        "fixed": 22.18
      }
    },
    "merchantReference": "aReference"
  },
  "order": {
    "orderRef": "order_123abc",
    "shippingAddress": {
      "line1": "10 Street Road",
      "line2": "Town",
      "postcode": "AA1 2BB"
    },
    "items": [
      {
        "name": "red shoe",
        "description": "Some red shoes",
        "itemRef": "red001",
        "itemAmount": 5.0,
        "quantity": 2,
        "totalAmount": 10.0,
        "customFields": [
          {
            "name": "style",
            "value": "boot"
          },
          {
            "name": "height",
            "value": "ankle"
          }
        ]
      },
      {
        "name": "blue shoe",
        "itemRef": "blue003",
        "itemAmount": 4.06,
        "quantity": 3,
        "totalAmount": 12.18
      }
    ]
  }
}'

Response

HTTP/1.1 201 Created

{
  "sessionId": "SMjqESSX_WgVOopmzJrwBjUUK",
  "redirectUrl": "https://secure.mite.pay360.com/hosted/SMjqESSX_WgVOopmzJrwBjUUK/begin/SMjqESSX_WgVOopmzJrwBjUUK",
  "status": "SUCCESS"
}