---
title: Payment Tokens
slug: payment-tokens
createdAt: 2024-12-09T04:39:14.416Z
---

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](docId:0NC5_xF7D6Vx6MJZTIVli) 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](docId\:X_jgOJQB6lBUzcpmg3HbD) endpoint, or for maintaining an existing token using the [Update Bank Account Token](docId:44gJ_MW9XUC1Ve33Lo5Mo)  endpoint. 

::::WorkflowBlock
:::WorkflowBlockItem
[Create a new OneShot Security Token](docId:6i8ccG4pwm7lU_35JKHkL) 
:::

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

:::WorkflowBlockItem
Call the [Create bank account Token](docId\:X_jgOJQB6lBUzcpmg3HbD) 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

::::CodeDrawer{title="Sample Direct Credit Payment to a Token" isResponseExpanded="true" autoGeneratedAnchorSlug="sample-direct-credit-payment-to-a-token-1" legacyHash="uNS6rVadE1Rsqj4TJt6BA"}
:::CodeblockTabsExamples
```json
{
  "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"
}
```
:::

:::CodeblockTabsResponses
```javascript
{
  "durationMs": 28,
  "status": "Ok",
  "statusDescription": "Operation completed successfully",
  "transactionId": 1022,
  "feeAmountExcludingGst": 0.08,
  "feeAmountGstComponent": 0.008,
  "feeAmountIncludingGst": 0.088,
  "callerUniqueReference": "dctoken123",
  "feeBreakdown": {
    "transactionFee": {
      "feeAmountExcludingGst": 0.08,
      "feeAmountGstComponent": 0.008,
      "feeAmountIncludingGst": 0.088
    }
  }
}
```
:::
::::

## Retrieving Token Details

To retrieve the details of a single existing token you can call the [Get Token Details](docId\:ItwD9f0VpUBk01Iyu3GJE) 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](docId\:FpQUay47Bb-lUhyaJqd9X) endpoint, which returns the same information in an array.

## Deleting a Token

Tokens can be deleted by calling the [Delete Token](docId\:M0nTkYhGbo5hP3nWgtPKG) 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](docId\:iMV1JBcHx59t7vHmejLq0) 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.

###