If your systems have the customer details available (such as through a customer registering with your site) then you should include the customer’s name, address and email information as part of the request.

This improves the payment experience for the customer, as it removes the need for them to re-enter details that they have already supplied.

You can send these details by including the following fields with the transaction request:

{
  "method": "create",
  "store": 1234,
  "authkey": "mykey1234",
  "order": {
    "cartid": "12324",
    "test": "1",
    "amount": "10.50",
    "currency": "AED",
    "description": "My purchase"
  },
  "return": {
    "authorised": "https://www.mysite.com/authorised",
    "declined": "https://www.mysite.com/declined",
    "cancelled": "https://www.mysite.com/cancelled"
  },
  "customer": {
    "ref": "xxx",//unique customer identification
    "email": "xxx",
    "name": {
      "title": "xxx",
      "forenames": "xxx",
      "surname": "xxx"
    },
    "address": {
      "line1": "xxx",
      "line2": "xxx",
      "line3": "xxx",
      "city": "xxx",
      "state": "xxx",
      "country": "xxx",
      "areacode": "xxx"
    },
    "phone": "xxxxx"
      }
}

If any part of the customer details are not supplied, or if they are not valid, then the payment pages will prompt for the correct details. For example, if you have supplied name and email but not their address, then the payment pages will only ask for the address.

For the name to be accepted, both the bill_fname and bill_sname values must be set and valid.

For the address to be accepted, bill_addr1, bill_city and bill_country must be set and valid.

Country field accepts a 2 letter ISO country code. List of country codes can be found at https://www.iban.com/country-codes.

It is always best to send this information with the request whenever possible, as that improves the customer experience of completing the transaction and reduces cart abandonment. However, it is important that only valid information collected from the customer is used – pre-set values to try and avoid collecting the data will cause transaction processing problems, and is against card processing rules.