Payment Tokens

Tokens create an additional layer of security for sensitive customer information, such as bank accounts, allowing them to be stored securely within Monoovas system and referenced using a token.

The tokenization system is designed so that the generated token has no mathematical or algorithmic link to the original data. Instead, the token is a randomly generated GUID.

Currently, the system supports two types of payloads:

Australian bank account numbers

BPAY CRN and biller code

Securely Generating a Token

Tokens are most secure when the underlying payment information never passes through your server. To enable this, Monoova allows you to generate Security Tokens that can be embedded in a web form, allowing you to call our API without exposing your sign-in account credentials.

This flow can be used for capturing new payment details using the Create bank account Token endpoint, or for maintaining an existing token using the Update Bank Account Token endpoint.

Create a new OneShot Security Token

Display a form to capture BPAY or account details on your application

Call the Create bank account Token endpoint using the security token instead of your sign-in account credentials

Using Tokens for Payment

Bank account tokens can be used for direct debit transactions by specifying the paymentSource as "token", and for BPAY or direct credit by specifying the disbursementMethod as "token".

By passing the token ID in the token object, the system will retrieve the payment details and transact to or from the target account.

Sample Direct Credit Payment to a Token

{
  "totalAmount": 100,
  "paymentSource": "token",
  "token": "00000000-1111-0000-0000-000000000000",
  "disbursements": [
    {
      "disbursementMethod": "token",
      "toToken": "11111111-0000-0000-0000-000000000000",
      "lodgementReference": "monoova-123",
      "amount": 100,
      "description": "Direct credit to beneficiary using tokenized system"
    }
  ],
  "description": "Token-based credit transfer for service payment"
}

Retrieving Token Details

To retrieve the details of a single existing token you can call the Get Token Details endpoint, which returns the token ID, hint, description, and token type. The underlying payment details are not exposed.

If you require the details for all tokens under your account you can call the List Tokens by mAccount endpoint, which returns the same information in an array.

Deleting a Token

Tokens can be deleted by calling the Delete Token endpoint with the token ID. If you are exposing tokens as a saved payment method for users of your application, it's recommended to also provide this as an option to allow users to self-service their payment options.

Validating a Token

If you want to validate that the token ID you have stored exists in our system you can call the Validate Token endpoint. This is a lightweight endpoint that returns either a 200 response if the token exists, or a 404 response if the token can't be found. This can be used to verify a token has been deleted.