Authorisation

This page identifies and defines the resources and operations available to authenticate customers and authorise transactions.

/auth-ib

POST

Initialise an in-band customer authorisation session.

Request

{
  // A code to identify the requested authorisation.
  "authCode": {
    required: no,
    type: string
  },

  // The type of payment card being used to perform the authorisation, e.g.
  // "Visa", "MasterCard". Determines the card icon displayed in the
  // Authenticator app.
  "cardType": {
    required: yes,
    type: string
  },

  // The mode of authentication; one of the permitted values ("pin" or "bio").
  "mode": {
    required: yes,
    type: string
  },

  // The primary account number of the payment card being used to perform the
  // authorisation.
  "pan": {
    required: yes,
    type: string
  },

  // Transaction data.
  "transactionData": {
    required: yes,
    type: {
      // The beneficiary, e.g. "ACME AirCon"; displayed to the customer.
      "beneficiary": {
        required: yes,
        type: string
      },

      // The Unicode sequence of the symbol of the currency of the value being
      // authorised, e.g "\xu00A3"; displayed to the customer
      "currencySymbol": {
        required: yes,
        type: string
      },

      // A description of the authorisation request,
      // e.g "Enter your PIN to access account details."; displayed to the
      // customer.
      "description": {
        required: yes,
        type: string
      },

      // A PNG image to be displayed to the customer.
      "image": {
        required: yes,
        type: byteArray
      },

      // The name of the payor, e.g. "John Silver"; displayed to the customer.
      "payor": {
        required: yes,
        type: string
      },

      // The type of payment instrument used, e.g. "Card"; determines text
      // displayed to the customer.
      "paymentType": {
        required: yes,
        type: string
      },

      // The value being authorised; displayed to the customer.
      "transactionValue": {
        required: yes,
        type: double
      }
    }
  }
}

Response On Success

200

{
  // An identifier for correlating data activities belonging to the
  // authorisation session.
  "correlationId": {
    presence: always,
    type: guid
  }
}

Response When The Authorisation Has Already Been Requested

498

{
  // A code to identify the requested authorisation.
  "authCode": {
    presence: always,
    type: string
  },

  // An identifier for the failed request.
  "code": {
    presence: always,
    type: guid
  }

  // A message describing the failure.
  "message": {
    presence: always,
    type: string
  }
}

Response When Invalid input

400

Response When Not Authorised

401

Response When The Requested Operation Failed

499

{
  // A code to identify the requested authorisation.
  "authCode": {
    presence: always,
    type: string
  },

  // An identifier for the failed request.
  "code": {
    presence: always,
    type: guid
  }

  // A message describing the failure.
  "message": {
    presence: always,
    type: string
  }
}

/auth-oob

POST

Initialise an out-of-band customer authorisation session.

Request

{
  // A code to identify the requested authorisation.
  "authCode": {
    required: no,
    type: string
  },

  // The type of payment card being used to perform the authorisation, e.g.
  // "Visa", "MasterCard". Determines the card icon displayed in the
  // Authenticator app.
  "cardType": {
    required: yes,
    type: string
  },

  // A URL, reserved by the partner, visited when the authentication process
  // finished on the Authenticator app.
  "callback": {
    required: yes,
    type: string
  },

  // The mode of authentication; one of the permitted values.
  "mode": {
    required: yes,
    type: set,
    permittedValues: [
      // Authenticate the customer using biometrics.
      "bio",
      // Authenticate the customer using their payment card PIN.
      "pin"
    ]
  },

  // The primary account number of the payment card being used to perform the
  // authorisation.
  "pan": {
    required: yes,
    type: string
  },

  // Transaction data.
  "transactionData": {
    required: yes,
    type: {
      // The beneficiary, e.g. "ACME AirCon"; displayed to the customer.
      "beneficiary": {
        required: yes,
        type: string
      },

      // The Unicode sequence of the symbol of the currency of the value being
      // authorised, e.g "\xu00A3"; displayed to the customer
      "currencySymbol": {
        required: yes,
        type: string
      },

      // A description of the authorisation request,
      // e.g "Enter your PIN to access account details."; displayed to the
      // customer.
      "description": {
        required: yes,
        type: string
      },

      // A Base-64 representation of an PNG image to be displayed to the
      // customer.
      "image": {
        required: yes,
        type: byteArray
      },

      // The name of the payor, e.g. "John Silver"; displayed to the customer.
      "payor": {
        required: yes,
        type: string
      },

      // The type of payment instrument used, e.g. "Card"; determines text
      // displayed to the customer.
      "paymentType": {
        required: yes,
        type: string
      },

      // The value being authorised; displayed to the customer.
      "transactionValue": {
        required: yes,
        type: double
      }
    }
  }
}

Response On Success

200

{
  // An identifier for correlating data activities belonging to the
  // authorisation session.
  "correlationId": {
    presence: always,
    type: guid
  },

  // A QR Code PNG image to be displayed to the customer by the partner.
  "qrCode": {
    presence: always,
    type: byteArray
  }
}

Response When Invalid input

400

Response When Not Authorised

401

Response When The Authorisation Has Already Been Requested

498

{
  // A code to identify the requested authorisation.
  "authCode": {
    presence: always,
    type: string
  },

  // An identifier for the failed request.
  "code": {
    presence: always,
    type: guid
  }

  // A message describing the failure.
  "message": {
    presence: always,
    type: string
  }
}

Response When Invalid input

400

Response When Not Authorised

401

Response When The Requested Operation Failed

499

{
  // A code to identify the requested authorisation.
  "authCode": {
    presence: always,
    type: string
  },

  // An identifier for the failed request.
  "code": {
    presence: always,
    type: guid
  }

  // A message describing the failure.
  "message": {
    presence: always,
    type: string
  }
}

/result

POST

Retrieve the result of the identified authorisation request.

Request

{
  // The correlation identifier for the authorisation request.
  "correlationId": {
    required: yes,
    type: guid
  }
}

Response On Success

200

{
  // A code to identify the requested authorisation.
  "authCode": {
    presence: always,
    type: string
  },

  // A descriptor indicating why the requested authorisation failed. Present if
  // the requested authorisation failed.
  "errorDescriptor": {
    presence: conditional,
    type: string
  },

  // The status of the requested authorisation.
  "status": {
    presence: always,
    type: boolean
  },

  //Results of a biometric face scan. Only present if mode == bio and a face scan was performed.
  "scores": {
    required: conditional,
    type: {
      "liveliness": {
          presence: always,
          type: double
        },

      "score": {
          presence: always,
          type: double
        },
    }
  }
}

Response When Invalid input

400

Response When Not Authorised

401

Response When The Authorisation Is Still In Progress

498

{
  // A code to identify the requested authorisation.
  "authCode": {
    presence: always,
    type: string
  },

  // An identifier for the failed request.
  "code": {
    presence: always,
    type: guid
  }

  // A message describing the failure.
  "message": {
    presence: always,
    type: string
  }
}

Response When Invalid input

400

Response When Not Authorised

401

Response When The Requested Operation Failed

499

{
  // A code to identify the requested authorisation.
  "authCode": {
    presence: always,
    type: string
  },

  // An identifier for the failed request.
  "code": {
    presence: always,
    type: guid
  }

  // A message describing the failure.
  "message": {
    presence: always,
    type: string
  }
}