# Pay Advantage Documentation > Welcome to the Pay Advantage developer hub. You'll find comprehensive guides and documentation to help you start working with Pay Advantage as quickly as possible, as well as support if you get stuck. Let's jump right in! Append .md to any documentation page URL to get its markdown version. ## Guides - [Getting Started with the Pay Advantage API](https://docs.payadvantage.com.au/docs/getting-started-with-the-pay-advantage-api.md): This is a guide to help you get up and running with the Pay Advantage API quickly. - [API Authentication](https://docs.payadvantage.com.au/docs/api-authentication.md): To utilise the Pay Advantage API you first need to authenticate - [Registering an App (Enabling OAuth)](https://docs.payadvantage.com.au/docs/registering-an-app.md) - [Connecting/Disconnecting to your Pay Advantage App](https://docs.payadvantage.com.au/docs/connectingdisconnecting-to-your-pay-advantage-app.md) - [Getting Refresh & Access Tokens](https://docs.payadvantage.com.au/docs/getting-refresh-access-tokens.md) - [Payment Types](https://docs.payadvantage.com.au/docs/payment-types.md) - [Payment Statuses](https://docs.payadvantage.com.au/docs/payment-statuses.md) - [PayID Payments](https://docs.payadvantage.com.au/docs/payid-payments.md) - [Customer Custom Fields](https://docs.payadvantage.com.au/docs/customer-custom-fields.md): PayAdvantage now completely supports custom fields via the API for customer records. This update includes both API functionality and web application enhancements to provide a improved custom fields support. - [Charging Credit Cards using an iFrame (Payment IFrame)](https://docs.payadvantage.com.au/docs/charging-using-an-iframe.md): PCI Compliance is the security implemented for the credit card industry. Use Pay Advantages iFrame to ensure you remain PCI compliant. - [Apple / Google Payments](https://docs.payadvantage.com.au/docs/apple-google-payments.md) - [Webhook Events](https://docs.payadvantage.com.au/docs/webhook-events.md): Webhooks serve as a mechanism that enables real-time communication between different your application and Pay Advantage - [Registering a new Endpoint](https://docs.payadvantage.com.au/docs/registering-a-new-endpoint.md): Register an endpoint to begin listening for Pay Advantage events. A maximum of 5 endpoints can be registered. - [Arming an endpoint](https://docs.payadvantage.com.au/docs/arming-an-endpoint.md): You must arm your endpoint before you are able to receive webhook events - [Testing Environment (Sandbox)](https://docs.payadvantage.com.au/docs/sandbox-environment.md): A complete replica of our live system is available for testing. - [Charge Credit Cards in Sandbox](https://docs.payadvantage.com.au/docs/charge-credit-cards-in-sandbox.md): To charge a credit card use the Pay Advantage iframe for complete PCI compliance - [Pay Advantage MCP Server](https://docs.payadvantage.com.au/docs/mcp.md) ## API Reference - [Create a new Authentication](https://docs.payadvantage.com.au/reference/authentications_post-1.md): All requests to the Pay Advantage API need to be authenticated.
The Authentication API's are used to authenticate to Pay Advantage using either your API credentials or via Oauth2 protocol.

Your API credentials can be found in the Integration Section of your Pay Advantage portal. Use our helpful guide for step by step instructions in the guide section.

This endpoint supports two types of requests: - Credential-based authentication (username and password) - OAuth2 PKCE authentication

**Credential-based authentication**

To authenticate and authorise your API requests an initial call is made to the `/token` endpoint with credentials passed as JSON in the request body.

Your username and password credentials should be passed as JSON in the request body. A successful response will return an access token that must be included in any subsequent requests as an authorisation header of type Bearer. e.g. `'Authorization':'Bearer '`.

The bearer token obtained from this call has an expiry. The seconds until expiry is populated in the expires_in field in the response message, after this time any request to the Pay Advantage API using an expired token will return a `STATUS 401` unauthorised response. It is good practice keep using the same access token and monitor the expiry; if another API request is required once the current access token is expired, call the `/token` endpoint to request a new token.
Please ensure these requests are made from a server and not from a browser. Exposing these tokens on a browser can result in security compromises.
NOTE: When utilizing credential-based authentication, a refresh token will not be provided.

**OAuth2 PKCE authentication**

With OAuth2 authentication, you have the advantage of using refresh tokens to refresh your access token. By utilizing the refresh token, you can easily obtain a new access token without having to go through the entire authentication process again.

To re-authenticate with a refresh token, simply call this endpoint again with a valid refresh token.
To utilize our OAuth2 service, kindly get in touch with our support team. The support team guide you through the process of registering your application into the PayAdvantage system and granting the necessary authorization for OAuth2. For more information view the example of OAuth2 PKCE authentication on the [https://www.oauth.com/playground](https://www.oauth.com/playground) - [Delete a Authentication](https://docs.payadvantage.com.au/reference/authentications_delete-1.md): All requests to the Pay Advantage API need to be authenticated.
The Authentication API's are used to authenticate to Pay Advantage using either your API credentials or via Oauth2 protocol.

Your API credentials can be found in the Integration Section of your Pay Advantage portal. Use our [helpful guide for step by step instructions.](https://docs.payadvantage.com.au/docs/api-authentication)

This endpoint disconnects a merchant from your app. This will delete their active refresh token. This is useful if you want to force users to reconnect via the OAuth2 flow.
`NOTE: Merchant users can disconnect from your application at any time from within Pay Advantage portal.`
Once they have disconnected, you will no longer be able to obtain new access tokens. You will not receive any notification regarding the merchant's choice to disconnect.

On a successful delete, an empty body `200` API response is returned. - [Delete a BSB Authentication](https://docs.payadvantage.com.au/reference/authentication_revoke_grant.md): All requests to the Pay Advantage API need to be authenticated.
The Authentication API's are used to authenticate to Pay Advantage using either your API credentials or via Oauth2 protocol.

Your API credentials can be found in the Integration Section of your Pay Advantage portal. Use our [helpful guide for step by step instructions.](https://docs.payadvantage.com.au/docs/api-authentication)

This endpoint disconnects a merchant from your app by revoking the specified authorization grant. This will delete their active refresh token. This is useful if you want to force users to reconnect via the OAuth2 flow.
`NOTE: Merchant users can disconnect from your application at any time from within Pay Advantage portal.`
Once they have disconnected, you will no longer be able to obtain new access tokens. You will not receive any notification regarding the merchant's choice to disconnect.

On a successful delete, an empty body `200` API response is returned. - [Create a new B2B Authentication](https://docs.payadvantage.com.au/reference/authentication_issue_grant.md): Issues an authorization grant to the specified registered app. - [Calculate Fee with Amount](https://docs.payadvantage.com.au/reference/realtime_fees_calculate-1.md): To provide a good customer experience you can calculate and show the customer their fees before a transaction occurs. This is especially helpful when you are on-charging fees to your customers.
**This endpoint has been replaced by [Payment Authorization Fees](https://docs.payadvantage.com.au/reference/payment_authorization_fees_calculate-1)**

To provide a breakdown of the fee the customer will be charged for this type of transaction enter an amount as the input. - [Retrieves a Credit Card Charge by code](https://docs.payadvantage.com.au/reference/credit_card_charges_get-1.md): Returns a list of credit card charges against a tokenised card which is ordered by the charge date. The list is paged and will always return the first page of records.
If there are no records that match the search criteria you will be returned an empty list. NOTE: This API does not work for PayTo transactions.
To create a payto or credit card charge refer to the [Payment Authorization endpoint](https://docs.payadvantage.com.au/reference/payment_authorizations_post-1). - [Retrieves a Credit Card Charge By external id](https://docs.payadvantage.com.au/reference/credit_card_charges_get_by_external_id-1.md): Returns a list of charges against based on an external identifier. Results are ordered by the charge date. The list is paged and will always return the first page of records. If there are no records that match your search you will be returned an empty list.
Please note that PayAdvantage does not prevent duplicate ExternalID entries so you will receive an array of charges that used the provided ExternalID. It is your responsibility to manage payment external IDs.

Please be cautious, as using the same external ID may be challenging to reconcile payments if you do not use a unique external identification number for each transaction. However, external IDs are useful for connecting Direct Debit Requests (DDRs) to their respective payments, this is achieved by providing the external ID during DDR creation. - [Create a new Credit Card IFrame](https://docs.payadvantage.com.au/reference/credit_card_iframes_post-1.md): This endpoint is the recommended way to obtain credit card information from customers. It ensures a PCI compliant IFrame is presented in your application.

PCI-DSS is a security standard from the payment card industry and ensures that all credit card numbers are safely managed.
**The Pay Advantage IFrame is the safest way to complete the payment process in your application.**
The IFrame also handles all HTML and CSS styling for obtaining credit card information.

Using the IFrame provides immediate access to 3DS security which protects you and your customers against fraud.

**This endpoint has been replaced by the Payment IFrame endpoint.**
This creates a url that is used to initialise an iframe for capturing credit card information.
- [Create a new Payment IFrame](https://docs.payadvantage.com.au/reference/payment_iframes.md): This endpoint is the recommended way to obtain credit card information from customers. It ensures a PCI compliant IFrame is presented in your application.

PCI-DSS is a security standard from the payment card industry and ensures that all credit card numbers are safely managed.
**The Pay Advantage IFrame is the safest way to complete the payment process in your application.**
The IFrame also handles all HTML and CSS styling for obtaining credit card information.

Using the IFrame provides immediate access to 3DS security which protects you and your customers against fraud.

This creates a url that is used to initialise an iframe for capturing payment information.
See the guide about capturing cards with iframe for more information. - [Retrieves Customer Payment Accounts](https://docs.payadvantage.com.au/reference/customer_payment_accounts_search-1.md): Customer payment accounts are designed to help store a reference to a payment type in Pay Advantage.
You can then use the code (when the type is credit card) to charge the account for that payment type.

A customer payment account code could refer to a credit card payment account or bsb and account number payment account.

This endpoint returns a list of payment accounts from all your customers.
The response includes a customer payment account code which is used as a reference to the account. Either the credit card, bank account or payID section will be present in the response.
Search criteria allows filtering on the returned results. - [Create a new Customer Payment Account](https://docs.payadvantage.com.au/reference/customer_payment_accounts_post-1.md): Customer payment accounts are designed to help store a reference to a payment type in Pay Advantage.
You can then use the code (when the type is credit card) to charge the account for that payment type.

A customer payment account code could refer to a credit card payment account or bsb and account number payment account.

Create a customer payment account.
This endpoint requires bank account information to be supplied. If you are looking to create a customer payment account of type credit card use the [Credit Card iFrame API](https://docs.payadvantage.com.au/reference/credit_card_iframes_post-1) - [Retrieve a Customer Payment Account](https://docs.payadvantage.com.au/reference/customer_payment_accounts_get-1.md): Customer payment accounts are designed to help store a reference to a payment type in Pay Advantage.
You can then use the code (when the type is credit card) to charge the account for that payment type.

A customer payment account code could refer to a credit card payment account or bsb and account number payment account.

Retrieve the customer payment account information based on the customer payment account code. - [Delete a Customer Payment Account](https://docs.payadvantage.com.au/reference/customer_payment_accounts_delete.md): Customer payment accounts are designed to help store a reference to a payment type in Pay Advantage.
You can then use the code (when the type is credit card) to charge the account for that payment type.

A customer payment account code could refer to a credit card payment account or bsb and account number payment account.

Deletes a customer payment account.
This action cannot be undone. - [Modify a Customer Payment Account](https://docs.payadvantage.com.au/reference/customer_payment_accounts_patch.md): Customer payment accounts are designed to help store a reference to a payment type in Pay Advantage.
You can then use the code (when the type is credit card) to charge the account for that payment type.

A customer payment account code could refer to a credit card payment account or bsb and account number payment account.

Updates a customer payment account. - [Create a new Customer Payment Account Link](https://docs.payadvantage.com.au/reference/customer_payment_accounts_links_post.md): Customer payment accounts are designed to help store a reference to a payment type in Pay Advantage.
You can then use the code (when the type is credit card) to charge the account for that payment type.

A customer payment account code could refer to a credit card payment account or bsb and account number payment account.

Creates a new change account link or returns existing link if one already exists. - [Delete Customer](https://docs.payadvantage.com.au/reference/customer_delete.md): Delete a customer account. Only customers that have not had a payment or a DDR attached can be deleted - [Retrieve Customers](https://docs.payadvantage.com.au/reference/customers_search.md): Pay Advantage allows your business to manage customers and their details in the Pay Advantage portal. Storing phone numbers, email addresses and notes for each customer provides a handy tool for managing your customers.

Returns a list of customers sorted by name (ascending by default). The list is paged and will always return the first page of records. - [Create a new Customer](https://docs.payadvantage.com.au/reference/customers_post.md): Pay Advantage allows your business to manage customers and their details in the Pay Advantage portal. Storing phone numbers, email addresses and notes for each customer provides a handy tool for managing your customers.

Creates a new customer using any attributes sent in request body.
Two customer types can be created - A Consumer or a Business.
To generate a BPAY reference for your customer on creation you will need to add `?with=bpayref` to the end of the url.

To generate a persistent PayID for your customer on creation you will need to add `?with=payidref` to the end of the url.

To setup a direct debit or use features such as payment requests, customers require a mobile number and email address.
**It is recommended you create all new customers with a mobile number and email to enable all Pay Advantage features for your customers.** - [Retrieve a Customer](https://docs.payadvantage.com.au/reference/customers_get.md): Pay Advantage allows your business to manage customers and their details in the Pay Advantage portal. Storing phone numbers, email addresses and notes for each customer provides a handy tool for managing your customers.

Returns a customer record using the Code attribute as an identifier. - [Update a Customer](https://docs.payadvantage.com.au/reference/customers_put.md): Pay Advantage allows your business to manage customers and their details in the Pay Advantage portal. Storing phone numbers, email addresses and notes for each customer provides a handy tool for managing your customers.

Updates the specified customer by setting the values of any parameters passed in the request body. For example, if you pass the Email parameter, the customers email will be updated to the new string.

If a parameter is not included in the request body, it will not be updated. This request accepts mostly the same parameters as the customer creation call with a few exceptions. The parameters used to update phone numbers are different from those used when creating a customer.

To generate a BPAY reference for an existing customer you will need to add `?with=bpayref` to the end of the url your are posting to.

Pass the boolean parameter `IsActive` as `false` to set a customer as inactive. For a customer to be set to inactive they must have no on-going Direct Debit Requests or pending payments. If you wish to turn this customer on again later, set them active by changing this parameter to true. - [Generate customer BPAY code](https://docs.payadvantage.com.au/reference/customers_createbpayref.md): Pay Advantage allows your business to manage customers and their details in the Pay Advantage portal. Storing phone numbers, email addresses and notes for each customer provides a handy tool for managing your customers.

To generate a BPAY reference for an existing customer use this endpoint with the customer code.
This endpoint doesn't require any body content to be sent in the request. - [Generate customer PayID](https://docs.payadvantage.com.au/reference/customers_createpayidref.md): Generates a persistent PayID for an existing customer. If a valid, unexpired PayID already exists, it will be returned. Otherwise, a new one will be created. - [Retrieve Debit Batches](https://docs.payadvantage.com.au/reference/debit_batches_search-1.md): For processing batch payments using the Pay Advantage API you will need to use both Debit Batches and Debit Instructions.

Debiting instructions are individual records of bank account payment instructions.
Debit batches are used to schedule and group individual debit instructions together.
This endpoint is useful for the management and submission of large batches of payments.

**As debit batches are processed twice a day, it is recommended to include all instructions for that day into a single batch.**
To use this endpoint, you must first create a debit batch group and then append instructions for each account you want to debit. This is done using the Debit Instructions endpoint.

When the batch contains all the debit instructions you want to process, the batch needs to be authorised and all instructed payments will be scheduled for processing.

Returns a list of debit batch groups ordered by most recently created. The list is paged and will always return the first page of records. If there are no records that match your search you will be returned an empty list. - [Create a new Debit Batch](https://docs.payadvantage.com.au/reference/debit_batches_post-1.md): For processing batch payments using the Pay Advantage API you will need to use both Debit Batches and Debit Instructions.

Debiting instructions are individual records of bank account payment instructions.
Debit batches are used to schedule and group individual debit instructions together.
This endpoint is useful for the management and submission of large batches of payments.

**As debit batches are processed twice a day, it is recommended to include all instructions for that day into a single batch.**
To use this endpoint, you must first create a debit batch group and then append instructions for each account you want to debit. This is done using the Debit Instructions endpoint.

When the batch contains all the debit instructions you want to process, the batch needs to be authorised and all instructed payments will be scheduled for processing.

Generates a new Debit Batch Group that debit instructions can be added to. Name and DateToDebit are always required. DateToDebit must be the day of creation or a future date (AEDT - Sydney). You can include an initial array of Debit Instructions, or send an empty Debit Instructions array and add them later. - [Retrieve a Debit Batch](https://docs.payadvantage.com.au/reference/debit_batches_get-1.md): For processing batch payments using the Pay Advantage API you will need to use both Debit Batches and Debit Instructions.

Debiting instructions are individual records of bank account payment instructions.
Debit batches are used to schedule and group individual debit instructions together.
This endpoint is useful for the management and submission of large batches of payments.

**As debit batches are processed twice a day, it is recommended to include all instructions for that day into a single batch.**
To use this endpoint, you must first create a debit batch group and then append instructions for each account you want to debit. This is done using the Debit Instructions endpoint.

When the batch contains all the debit instructions you want to process, the batch needs to be authorised and all instructed payments will be scheduled for processing.

Returns details associated with a specific debit batch group. Uses the batch debit code as the reference. - [Update a Debit Batch](https://docs.payadvantage.com.au/reference/debit_batches_put-1.md): For processing batch payments using the Pay Advantage API you will need to use both Debit Batches and Debit Instructions.

Debiting instructions are individual records of bank account payment instructions.
Debit batches are used to schedule and group individual debit instructions together.
This endpoint is useful for the management and submission of large batches of payments.

**As debit batches are processed twice a day, it is recommended to include all instructions for that day into a single batch.**
To use this endpoint, you must first create a debit batch group and then append instructions for each account you want to debit. This is done using the Debit Instructions endpoint.

When the batch contains all the debit instructions you want to process, the batch needs to be authorised and all instructed payments will be scheduled for processing.

Updates a debit batch group using its code as an identifier. This will not modify the instructions associated with the batch debit. If a parameter is not included in the request body, it will not be updated. - [Delete a Debit Batch](https://docs.payadvantage.com.au/reference/debit_batches_delete-1.md): For processing batch payments using the Pay Advantage API you will need to use both Debit Batches and Debit Instructions.

Debiting instructions are individual records of bank account payment instructions.
Debit batches are used to schedule and group individual debit instructions together.
This endpoint is useful for the management and submission of large batches of payments.

**As debit batches are processed twice a day, it is recommended to include all instructions for that day into a single batch.**
To use this endpoint, you must first create a debit batch group and then append instructions for each account you want to debit. This is done using the Debit Instructions endpoint.

When the batch contains all the debit instructions you want to process, the batch needs to be authorised and all instructed payments will be scheduled for processing.

A debit batch can be deleted provided it is not in a confirmed or authorised state. This deletes all instructions within the batch. This is how you can cancel a debit batch any time before being processed or authorised. Use a debit batches code in the request to specify which batch to delete. - [Modify a Debit Batch](https://docs.payadvantage.com.au/reference/debit_batches_patch-1.md): For processing batch payments using the Pay Advantage API you will need to use both Debit Batches and Debit Instructions.

Debiting instructions are individual records of bank account payment instructions.
Debit batches are used to schedule and group individual debit instructions together.
This endpoint is useful for the management and submission of large batches of payments.

**As debit batches are processed twice a day, it is recommended to include all instructions for that day into a single batch.**
To use this endpoint, you must first create a debit batch group and then append instructions for each account you want to debit. This is done using the Debit Instructions endpoint.

When the batch contains all the debit instructions you want to process, the batch needs to be authorised and all instructed payments will be scheduled for processing.

Updates a debit batch group using its code as an identifier. This will not modify the instructions associated with the batch debit. If a parameter is not included in the request body, it will not be updated. - [Authorise a debit batch](https://docs.payadvantage.com.au/reference/debit_batches_authorise.md): For processing batch payments using the Pay Advantage API you will need to use both Debit Batches and Debit Instructions.

Debiting instructions are individual records of bank account payment instructions.
Debit batches are used to schedule and group individual debit instructions together.
This endpoint is useful for the management and submission of large batches of payments.

**As debit batches are processed twice a day, it is recommended to include all instructions for that day into a single batch.**
To use this endpoint, you must first create a debit batch group and then append instructions for each account you want to debit. This is done using the Debit Instructions endpoint.

When the batch contains all the debit instructions you want to process, the batch needs to be authorised and all instructed payments will be scheduled for processing.

Once a debit batch has been created and all Debit Instructions added, it must be confirmed and authorised. Once authorised the batch will be scheduled to process on the date defined by the DateToDebit parameter. Use the debit batch Code to specify which debit batch you want to authorise. - [Retrieve all debit instructions](https://docs.payadvantage.com.au/reference/debit_instructions_search-1.md): For processing batch payments in the Pay Advantage API you will need to use both Debit Batch and Debit Instruction API.Debit Instructions are individual instructions to debit an amount from a bank account. Unlike DDR's, debit batch instructions have no schedule management, The batch is simply used to process a batch of payments and record the success or failure of each payment instruction on the day of submission.

**Debit Batches**
Before creating debit instructions you must first create a debit batch group that will be used to control certain functions like the debit date etc for all of the instructions. See debit batches for more information.

**On-Charging Fees**
If you decide to on-charge debit fees directly to your customers then you can make use of the OnchargeFees flag and PayAdvantage will pass on the selected fee to the customer.
Debit Fees will be calculated when the Debit Instruction is processed for payment (typically the DateToDebit from the DebitBatch). The fee will be added to the payment at this point for on-charged debit instructions.

**Group Key Feature**
Any Debit Instruction may have a Group Key assigned. As the name suggests, this field is used for grouping related instructions together. The same group key may be used across any number of batches over any period of time. A good idea is to use a customers unique code or identifier for this field.Please be aware that, when using the Group Key and On-charge features together, any on-charged fee that dishonours will be added to the next on-charged debit instruction with a matching group key. This is by design to assist in fee management and recovery. It is only a real concern if on-charging is used and the group key is shared between different customers. One solution in this scenario is to add a unique suffix to group key for each customer in that group (for example `AB001-01`, `AB001-02`) so these can be filtered at a later date using the first number characters.

Returns a list of debit instruction records (most recent first by default). The list is paged and will always return the first page of records. If there are no records that match your search you will be returned an empty list. - [Create a new Debit Instruction](https://docs.payadvantage.com.au/reference/debit_instructions_post-1.md): For processing batch payments in the Pay Advantage API you will need to use both Debit Batch and Debit Instruction API.Debit Instructions are individual instructions to debit an amount from a bank account. Unlike DDR's, debit batch instructions have no schedule management, The batch is simply used to process a batch of payments and record the success or failure of each payment instruction on the day of submission.

**Debit Batches**
Before creating debit instructions you must first create a debit batch group that will be used to control certain functions like the debit date etc for all of the instructions. See debit batches for more information.

**On-Charging Fees**
If you decide to on-charge debit fees directly to your customers then you can make use of the OnchargeFees flag and PayAdvantage will pass on the selected fee to the customer.
Debit Fees will be calculated when the Debit Instruction is processed for payment (typically the DateToDebit from the DebitBatch). The fee will be added to the payment at this point for on-charged debit instructions.

**Group Key Feature**
Any Debit Instruction may have a Group Key assigned. As the name suggests, this field is used for grouping related instructions together. The same group key may be used across any number of batches over any period of time. A good idea is to use a customers unique code or identifier for this field.Please be aware that, when using the Group Key and On-charge features together, any on-charged fee that dishonours will be added to the next on-charged debit instruction with a matching group key. This is by design to assist in fee management and recovery. It is only a real concern if on-charging is used and the group key is shared between different customers. One solution in this scenario is to add a unique suffix to group key for each customer in that group (for example `AB001-01`, `AB001-02`) so these can be filtered at a later date using the first number characters.

Create a Debit Instruction and add it to an already existing Debit Batch. A Debit Instruction must be appended to a Debit Batch Group. - [Retrieve a Debit Instruction by code](https://docs.payadvantage.com.au/reference/debit_instructions_get-1.md): For processing batch payments in the Pay Advantage API you will need to use both Debit Batch and Debit Instruction API.Debit Instructions are individual instructions to debit an amount from a bank account. Unlike DDR's, debit batch instructions have no schedule management, The batch is simply used to process a batch of payments and record the success or failure of each payment instruction on the day of submission.

**Debit Batches**
Before creating debit instructions you must first create a debit batch group that will be used to control certain functions like the debit date etc for all of the instructions. See debit batches for more information.

**On-Charging Fees**
If you decide to on-charge debit fees directly to your customers then you can make use of the OnchargeFees flag and PayAdvantage will pass on the selected fee to the customer.
Debit Fees will be calculated when the Debit Instruction is processed for payment (typically the DateToDebit from the DebitBatch). The fee will be added to the payment at this point for on-charged debit instructions.

**Group Key Feature**
Any Debit Instruction may have a Group Key assigned. As the name suggests, this field is used for grouping related instructions together. The same group key may be used across any number of batches over any period of time. A good idea is to use a customers unique code or identifier for this field.Please be aware that, when using the Group Key and On-charge features together, any on-charged fee that dishonours will be added to the next on-charged debit instruction with a matching group key. This is by design to assist in fee management and recovery. It is only a real concern if on-charging is used and the group key is shared between different customers. One solution in this scenario is to add a unique suffix to group key for each customer in that group (for example `AB001-01`, `AB001-02`) so these can be filtered at a later date using the first number characters.

Returns a debit instruction record using its unique Code value as an identifier. - [Retrieve all Debit Instructions in a debit batch](https://docs.payadvantage.com.au/reference/debit_batches_debit_instructions-1.md): For processing batch payments in the Pay Advantage API you will need to use both Debit Batch and Debit Instruction API.Debit Instructions are individual instructions to debit an amount from a bank account. Unlike DDR's, debit batch instructions have no schedule management, The batch is simply used to process a batch of payments and record the success or failure of each payment instruction on the day of submission.

**Debit Batches**
Before creating debit instructions you must first create a debit batch group that will be used to control certain functions like the debit date etc for all of the instructions. See debit batches for more information.

**On-Charging Fees**
If you decide to on-charge debit fees directly to your customers then you can make use of the OnchargeFees flag and PayAdvantage will pass on the selected fee to the customer.
Debit Fees will be calculated when the Debit Instruction is processed for payment (typically the DateToDebit from the DebitBatch). The fee will be added to the payment at this point for on-charged debit instructions.

**Group Key Feature**
Any Debit Instruction may have a Group Key assigned. As the name suggests, this field is used for grouping related instructions together. The same group key may be used across any number of batches over any period of time. A good idea is to use a customers unique code or identifier for this field.Please be aware that, when using the Group Key and On-charge features together, any on-charged fee that dishonours will be added to the next on-charged debit instruction with a matching group key. This is by design to assist in fee management and recovery. It is only a real concern if on-charging is used and the group key is shared between different customers. One solution in this scenario is to add a unique suffix to group key for each customer in that group (for example `AB001-01`, `AB001-02`) so these can be filtered at a later date using the first number characters.

Returns a list of debit instruction records using the batches unique Code value as an identifier. - [Delete a Debit Instruction](https://docs.payadvantage.com.au/reference/debit_instructions_delete-1.md): For processing batch payments in the Pay Advantage API you will need to use both Debit Batch and Debit Instruction API.Debit Instructions are individual instructions to debit an amount from a bank account. Unlike DDR's, debit batch instructions have no schedule management, The batch is simply used to process a batch of payments and record the success or failure of each payment instruction on the day of submission.

**Debit Batches**
Before creating debit instructions you must first create a debit batch group that will be used to control certain functions like the debit date etc for all of the instructions. See debit batches for more information.

**On-Charging Fees**
If you decide to on-charge debit fees directly to your customers then you can make use of the OnchargeFees flag and PayAdvantage will pass on the selected fee to the customer.
Debit Fees will be calculated when the Debit Instruction is processed for payment (typically the DateToDebit from the DebitBatch). The fee will be added to the payment at this point for on-charged debit instructions.

**Group Key Feature**
Any Debit Instruction may have a Group Key assigned. As the name suggests, this field is used for grouping related instructions together. The same group key may be used across any number of batches over any period of time. A good idea is to use a customers unique code or identifier for this field.Please be aware that, when using the Group Key and On-charge features together, any on-charged fee that dishonours will be added to the next on-charged debit instruction with a matching group key. This is by design to assist in fee management and recovery. It is only a real concern if on-charging is used and the group key is shared between different customers. One solution in this scenario is to add a unique suffix to group key for each customer in that group (for example `AB001-01`, `AB001-02`) so these can be filtered at a later date using the first number characters.

Deletes a Debit Instruction using its code as an identifier.
A debit instruction can be deleted as long as the “DebitBatch” it belongs to is not confirmed, authorised, or processed.
You can delete a single instruction or multiple instructions by separating the {code} with a comma.You can delete up to a maximum of 1,000 codes per delete request e.g. `v3/debit_instructions/{code},{code},{...}` - [Acknowledge a failure in the batch](https://docs.payadvantage.com.au/reference/debit_instructions_acknowledge_fail_put-1.md): For processing batch payments in the Pay Advantage API you will need to use both Debit Batch and Debit Instruction API.Debit Instructions are individual instructions to debit an amount from a bank account. Unlike DDR's, debit batch instructions have no schedule management, The batch is simply used to process a batch of payments and record the success or failure of each payment instruction on the day of submission.

**Debit Batches**
Before creating debit instructions you must first create a debit batch group that will be used to control certain functions like the debit date etc for all of the instructions. See debit batches for more information.

**On-Charging Fees**
If you decide to on-charge debit fees directly to your customers then you can make use of the OnchargeFees flag and PayAdvantage will pass on the selected fee to the customer.
Debit Fees will be calculated when the Debit Instruction is processed for payment (typically the DateToDebit from the DebitBatch). The fee will be added to the payment at this point for on-charged debit instructions.

**Group Key Feature**
Any Debit Instruction may have a Group Key assigned. As the name suggests, this field is used for grouping related instructions together. The same group key may be used across any number of batches over any period of time. A good idea is to use a customers unique code or identifier for this field.Please be aware that, when using the Group Key and On-charge features together, any on-charged fee that dishonours will be added to the next on-charged debit instruction with a matching group key. This is by design to assist in fee management and recovery. It is only a real concern if on-charging is used and the group key is shared between different customers. One solution in this scenario is to add a unique suffix to group key for each customer in that group (for example `AB001-01`, `AB001-02`) so these can be filtered at a later date using the first number characters.

This endpoint allows you to mark failures as acknowledged. This provides a fast method for identification of which records have been dealt with.Once acknowledged, failed debit instructions will stop appearing in the returned list of failed debit instructions.You can acknowledge a single failure or multiple by separating the `{code}` with a comma. You can acknowledge up to a maximum of 1,000 codes per delete request e.g. `v3/debit_instructions/{code},{code},{...}/ackfail`.

The `PUT`, `POST` and `PATCH` perform the exact same function of marking the failure as acknowledged. - [Acknowledge a failure in the batch](https://docs.payadvantage.com.au/reference/debit_instructions_acknowledge_fail_post-1.md): For processing batch payments in the Pay Advantage API you will need to use both Debit Batch and Debit Instruction API.Debit Instructions are individual instructions to debit an amount from a bank account. Unlike DDR's, debit batch instructions have no schedule management, The batch is simply used to process a batch of payments and record the success or failure of each payment instruction on the day of submission.

**Debit Batches**
Before creating debit instructions you must first create a debit batch group that will be used to control certain functions like the debit date etc for all of the instructions. See debit batches for more information.

**On-Charging Fees**
If you decide to on-charge debit fees directly to your customers then you can make use of the OnchargeFees flag and PayAdvantage will pass on the selected fee to the customer.
Debit Fees will be calculated when the Debit Instruction is processed for payment (typically the DateToDebit from the DebitBatch). The fee will be added to the payment at this point for on-charged debit instructions.

**Group Key Feature**
Any Debit Instruction may have a Group Key assigned. As the name suggests, this field is used for grouping related instructions together. The same group key may be used across any number of batches over any period of time. A good idea is to use a customers unique code or identifier for this field.Please be aware that, when using the Group Key and On-charge features together, any on-charged fee that dishonours will be added to the next on-charged debit instruction with a matching group key. This is by design to assist in fee management and recovery. It is only a real concern if on-charging is used and the group key is shared between different customers. One solution in this scenario is to add a unique suffix to group key for each customer in that group (for example `AB001-01`, `AB001-02`) so these can be filtered at a later date using the first number characters.

This endpoint allows you to mark failures as acknowledged. This provides a fast method for identification of which records have been dealt with.Once acknowledged, failed debit instructions will stop appearing in the returned list of failed debit instructions.You can acknowledge a single failure or multiple by separating the `{code}` with a comma. You can acknowledge up to a maximum of 1,000 codes per delete request e.g. `v3/debit_instructions/{code},{code},{...}/ackfail`.

The `PUT`, `POST` and `PATCH` perform the exact same function of marking the failure as acknowledged. - [Acknowledge a failure in the batch](https://docs.payadvantage.com.au/reference/debit_instructions_acknowledge_fail_patch-1.md): For processing batch payments in the Pay Advantage API you will need to use both Debit Batch and Debit Instruction API.Debit Instructions are individual instructions to debit an amount from a bank account. Unlike DDR's, debit batch instructions have no schedule management, The batch is simply used to process a batch of payments and record the success or failure of each payment instruction on the day of submission.

**Debit Batches**
Before creating debit instructions you must first create a debit batch group that will be used to control certain functions like the debit date etc for all of the instructions. See debit batches for more information.

**On-Charging Fees**
If you decide to on-charge debit fees directly to your customers then you can make use of the OnchargeFees flag and PayAdvantage will pass on the selected fee to the customer.
Debit Fees will be calculated when the Debit Instruction is processed for payment (typically the DateToDebit from the DebitBatch). The fee will be added to the payment at this point for on-charged debit instructions.

**Group Key Feature**
Any Debit Instruction may have a Group Key assigned. As the name suggests, this field is used for grouping related instructions together. The same group key may be used across any number of batches over any period of time. A good idea is to use a customers unique code or identifier for this field.Please be aware that, when using the Group Key and On-charge features together, any on-charged fee that dishonours will be added to the next on-charged debit instruction with a matching group key. This is by design to assist in fee management and recovery. It is only a real concern if on-charging is used and the group key is shared between different customers. One solution in this scenario is to add a unique suffix to group key for each customer in that group (for example `AB001-01`, `AB001-02`) so these can be filtered at a later date using the first number characters.

This endpoint allows you to mark failures as acknowledged. This provides a fast method for identification of which records have been dealt with.Once acknowledged, failed debit instructions will stop appearing in the returned list of failed debit instructions.You can acknowledge a single failure or multiple by separating the `{code}` with a comma. You can acknowledge up to a maximum of 1,000 codes per delete request e.g. `v3/debit_instructions/{code},{code},{...}/ackfail`.

The `PUT`, `POST` and `PATCH` perform the exact same function of marking the failure as acknowledged. - [Retrieve Direct Debits](https://docs.payadvantage.com.au/reference/direct_debits_search-1.md): Returns a list of direct debit records ordered by creation date. The list is paged and will always return the first page of records. If there are no records that match your search you will be returned an empty list. - [Create a new Direct Debit](https://docs.payadvantage.com.au/reference/direct_debits_post-1.md): Generate a direct debit (Recurring payment).
Direct Debits are required to be authorised to become active.

One authorisation method is to share the direct debit request link with a customer allowing them to authorise and sign the direct debit request.

The other method is to submit the direct debit request with CustomerAuthorisationNotRequired = true. This will create an active direct debit without your customer required to authorise and sign.
You should offer the ability for your customer to cancel their subscription via your platform if bypassing customer authorisation.

Your customer must have a valid email and mobile number, or your request will fail and an appropriate error will be returned. You will need to update your customers details using the customer endpoint to include an email and mobile number.

- [Retrieve a Direct Debit](https://docs.payadvantage.com.au/reference/direct_debits_get-1.md): Returns a direct debit record using the code value as an identifier. - [Delete a Direct Debit](https://docs.payadvantage.com.au/reference/direct_debits_delete-1.md): Use this endpoint to delete a direct debit request that is still in draft status. This endpoint will not delete Direct Debits that have been successfully authorised.

Once a Direct Debit has been authorised you cannot delete it, the only way a direct debit can no longer be active is by completing the allocated amount of installments or by being manually cancelled through the Pay Advantage portal. - [Modify a Direct Debit](https://docs.payadvantage.com.au/reference/direct_debits_patch.md): Updates an existing direct debit. It is only necessary to provide a value for the fields that you wish to update.

This endpoint currently only supports updating the direct debit status, but will be extended to change the DDR settings in the future. - [Create a new Direct Debit from Template](https://docs.payadvantage.com.au/reference/direct_debit_from_template_post.md): Creates a direct debit from a subscription template. All amounts, frequency, fees and end conditions are taken from the template's current version; only scheduling and authorisation options may be supplied. - [Bulk send change-account authorisation links](https://docs.payadvantage.com.au/reference/direct_debit_account_change_requests_post.md): Sends a change-account authorisation link to the customers of the specified direct debits. Direct debits that are not active or paused, are pending reauthorisation, or whose customer has no email or mobile are skipped and reported in the response rather than failing the whole request. - [Bulk increase direct debit recurring amounts](https://docs.payadvantage.com.au/reference/direct_debit_amount_adjustments_post.md): Increases the recurring amount of the specified direct debits by a percentage (maximum 10%) or a fixed dollar amount. Direct debits that would exceed trust limits or require re-authorisation are skipped and reported in the response rather than failing the whole request. - [Retrieve a Direct Debit Instalment](https://docs.payadvantage.com.au/reference/direct_debit_instalments_get.md): Returns a single instalment by its unique identifier, including payment history. - [Modify a Direct Debit Instalment](https://docs.payadvantage.com.au/reference/direct_debit_instalments_patch.md): Update an instalment's scheduled date and/or amount. Set Amount to 0 to skip the instalment. - [Retrieve Direct Debit Templates](https://docs.payadvantage.com.au/reference/direct_debit_templates_search.md): Returns a list of all active subscription templates for the current merchant. - [Create a new Direct Debit Template](https://docs.payadvantage.com.au/reference/direct_debit_templates_post.md): Creates a new subscription template. - [Retrieve a Direct Debit Template by Code](https://docs.payadvantage.com.au/reference/direct_debit_templates_get_by_code.md): Returns a single subscription template by its unique code. - [Modify a Direct Debit Template](https://docs.payadvantage.com.au/reference/direct_debit_templates_patch.md): Updates an existing subscription template. - [Delete a Direct Debit Template](https://docs.payadvantage.com.au/reference/direct_debit_templates_delete.md): Deletes a subscription template by its unique code. - [Retrieve a Direct Debit Template by Code with Archived Snapshot](https://docs.payadvantage.com.au/reference/direct_debit_templates_get_archives.md): Returns all archived version snapshots for a subscription template. Includes soft-deleted templates. - [Retrieve a Direct Debit Template by Code and Version](https://docs.payadvantage.com.au/reference/direct_debit_templates_get_archive_by_version.md): Returns an archived snapshot for a specific version of a subscription template. Includes soft-deleted templates. - [Patch payment-portal plan settings (order, visibility, recommended)](https://docs.payadvantage.com.au/reference/direct_debit_templates_patch_portal_settings.md): Bulk-updates the current merchant's active subscription templates in a single atomic operation: their payment-portal display order (sequence), visibility (public/private) and recommended flag. Send the full desired state for every template. - [Determines if the system is currently online.](https://docs.payadvantage.com.au/reference/health_checks_get-1.md): This endpoint can be called to return the status of the Pay Advantage API. - [Retrieve Invoices](https://docs.payadvantage.com.au/reference/invoices_search.md): Manage merchant invoices. Invoices allows for line items. Invoices status lifecycle is: (Draft → Sent → Paid / Cancelled). You can also connect an invoice to any payment.

Returns a paged list of invoices for the merchant. Supports filtering by status, customer, date issued, date due, and amount. - [Create a new Invoice](https://docs.payadvantage.com.au/reference/invoices_post.md): Manage merchant invoices. Invoices allows for line items. Invoices status lifecycle is: (Draft → Sent → Paid / Cancelled). You can also connect an invoice to any payment.

Creates a new invoice in Draft status. - [Retrieve a Invoice](https://docs.payadvantage.com.au/reference/invoices_get.md): Manage merchant invoices. Invoices allows for line items. Invoices status lifecycle is: (Draft → Sent → Paid / Cancelled). You can also connect an invoice to any payment.

Returns a single invoice including its line items and linked payments. - [Update an invoice](https://docs.payadvantage.com.au/reference/invoices_patch.md): Manage merchant invoices. Invoices allows for line items. Invoices status lifecycle is: (Draft → Sent → Paid / Cancelled). You can also connect an invoice to any payment.

Updates an invoice. Only the fields supplied are changed; omitted fields are left unchanged. When 'lineItems' is supplied, the entire set of line items is replaced. Notes (and 'showNotesToCustomer') can be updated at any status; every other field can only be changed while the invoice is in Draft. - [Get next suggested invoice number](https://docs.payadvantage.com.au/reference/invoices_next_number.md): Manage merchant invoices. Invoices allows for line items. Invoices status lifecycle is: (Draft → Sent → Paid / Cancelled). You can also connect an invoice to any payment.

Returns the suggested next invoice number for this merchant, based on the highest existing numeric invoice number. - [Create an invoice from an existing payment](https://docs.payadvantage.com.au/reference/invoices_create_from_payment.md): Manage merchant invoices. Invoices allows for line items. Invoices status lifecycle is: (Draft → Sent → Paid / Cancelled). You can also connect an invoice to any payment.

Creates an invoice from an existing payment. Uses the payment description as the line item, applies the merchant's default tax code, and links the payment. The invoice is marked Paid when the payment's effective amount covers the total; a failed (or partially effective) payment leaves the invoice Approved with the balance still due. - [Update invoice status](https://docs.payadvantage.com.au/reference/invoices_update_status.md): Manage merchant invoices. Invoices allows for line items. Invoices status lifecycle is: (Draft → Sent → Paid / Cancelled). You can also connect an invoice to any payment.

Transitions an invoice to the requested status. Valid transitions: Draft→Approved, Approved→Draft, Draft/Approved→Cancelled. - [Send invoice notification to customer](https://docs.payadvantage.com.au/reference/invoices_notify.md): Manage merchant invoices. Invoices allows for line items. Invoices status lifecycle is: (Draft → Sent → Paid / Cancelled). You can also connect an invoice to any payment.

Sends a notification to the customer via email and/or SMS with a link to view and pay the invoice. The invoice must be in Approved status. - [Get invoice QR code](https://docs.payadvantage.com.au/reference/invoices_qr_code.md): Manage merchant invoices. Invoices allows for line items. Invoices status lifecycle is: (Draft → Sent → Paid / Cancelled). You can also connect an invoice to any payment.

Returns a QR code PNG that links to the customer-facing invoice view. - [Detach a payment from an invoice](https://docs.payadvantage.com.au/reference/invoices_unlink_payment.md): Manage merchant invoices. Invoices allows for line items. Invoices status lifecycle is: (Draft → Sent → Paid / Cancelled). You can also connect an invoice to any payment.

Removes the association between a payment and this invoice. - [Apply a credit to an invoice](https://docs.payadvantage.com.au/reference/invoices_apply_credit.md): Manage merchant invoices. Invoices allows for line items. Invoices status lifecycle is: (Draft → Sent → Paid / Cancelled). You can also connect an invoice to any payment.

Applies a credit to reduce the outstanding balance on this invoice. - [Cancel an invoice credit](https://docs.payadvantage.com.au/reference/invoices_cancel_credit.md): Manage merchant invoices. Invoices allows for line items. Invoices status lifecycle is: (Draft → Sent → Paid / Cancelled). You can also connect an invoice to any payment.

Removes a previously applied credit from this invoice. - [Retrieve Merchant Activations](https://docs.payadvantage.com.au/reference/merchant_activations_search-1.md): The merchant activations endpoint is perfect for software partners or industry associations who would like to streamline the onboarding process. The system allows you to pre register a new merchant and then instantly commence the activation process and/or send an invitation to activate their account.

This allows you to:
- Initiate the signup process from within the client portal or via an API call.
- If via the API a link is returned allowing merchants to instantly begin the activation process without having to wait for an activation email.
- Monitor a merchants progress through the various stages of onboarding and verification

Please note this feature and endpoint is only available to **registered partners**. Certain steps in the merchant activation process can also be co branded with a partners logo to provide an enhanced experience for new merchants.
**Please contact support to discuss this option to register as a partner.**

Retrieve a list of merchant activations - [Create a new Merchant Activation](https://docs.payadvantage.com.au/reference/merchant_activations_post-1.md): The merchant activations endpoint is perfect for software partners or industry associations who would like to streamline the onboarding process. The system allows you to pre register a new merchant and then instantly commence the activation process and/or send an invitation to activate their account.

This allows you to:
- Initiate the signup process from within the client portal or via an API call.
- If via the API a link is returned allowing merchants to instantly begin the activation process without having to wait for an activation email.
- Monitor a merchants progress through the various stages of onboarding and verification

Please note this feature and endpoint is only available to **registered partners**. Certain steps in the merchant activation process can also be co branded with a partners logo to provide an enhanced experience for new merchants.
**Please contact support to discuss this option to register as a partner.**

Create a new merchant activation - [Retrieve a Merchant Activation](https://docs.payadvantage.com.au/reference/merchant_activations_get-1.md): The merchant activations endpoint is perfect for software partners or industry associations who would like to streamline the onboarding process. The system allows you to pre register a new merchant and then instantly commence the activation process and/or send an invitation to activate their account.

This allows you to:
- Initiate the signup process from within the client portal or via an API call.
- If via the API a link is returned allowing merchants to instantly begin the activation process without having to wait for an activation email.
- Monitor a merchants progress through the various stages of onboarding and verification

Please note this feature and endpoint is only available to **registered partners**. Certain steps in the merchant activation process can also be co branded with a partners logo to provide an enhanced experience for new merchants.
**Please contact support to discuss this option to register as a partner.**

Retrieve a merchant activations using the reference code - [Delete a Merchant Activation](https://docs.payadvantage.com.au/reference/merchant_activations_delete-1.md): The merchant activations endpoint is perfect for software partners or industry associations who would like to streamline the onboarding process. The system allows you to pre register a new merchant and then instantly commence the activation process and/or send an invitation to activate their account.

This allows you to:
- Initiate the signup process from within the client portal or via an API call.
- If via the API a link is returned allowing merchants to instantly begin the activation process without having to wait for an activation email.
- Monitor a merchants progress through the various stages of onboarding and verification

Please note this feature and endpoint is only available to **registered partners**. Certain steps in the merchant activation process can also be co branded with a partners logo to provide an enhanced experience for new merchants.
**Please contact support to discuss this option to register as a partner.**

Delete a new merchant activation using the reference code - [Retrieve PayIds](https://docs.payadvantage.com.au/reference/payids_search.md): Get a list of Pay IDs. For more information, please see https://docs.payadvantage.com.au/docs/payid-payments - [Create a new PayId](https://docs.payadvantage.com.au/reference/payids_post.md): Create a new PayID. Allow a customer to pay with the PayID using their personal banking app. - [Retrieve a PayId](https://docs.payadvantage.com.au/reference/payids_get.md): Get a PayID by its unique code. For more information, please see https://docs.payadvantage.com.au/docs/payid-payments - [Retrieve a Refund](https://docs.payadvantage.com.au/reference/refunds_get_by_code.md): The Refunds endpoint handles the creation, cancellation, and monitoring of refunds for payments. As with payments, a refund is never effectively successful, it just hasn’t failed.
If a refund attempt does ever fail, you should cancel the refund or re-attempt the refund to an alternate account (via the Web Portal only).

Please note that you cannot modify refunds.

Returns a single refund record using the Code of a refund as an identifier. - [Retrieve a Refund](https://docs.payadvantage.com.au/reference/refunds_get_attempts.md): The Refunds endpoint handles the creation, cancellation, and monitoring of refunds for payments. As with payments, a refund is never effectively successful, it just hasn’t failed.
If a refund attempt does ever fail, you should cancel the refund or re-attempt the refund to an alternate account (via the Web Portal only).

Please note that you cannot modify refunds.

Returns all refund attempts for a specific refund, showing the complete retry history and current status. - [Retrieve Payment Requests](https://docs.payadvantage.com.au/reference/payment_requests_search-1.md): Payment Requests let you receive a payment by creating a link with preconfigured payment options that can then be:
- used in your integration/application allowing a customer to click/follow a link through a button
- sent through your own system in emails, sms or letters
- sent in an email/sms by the PayAdvantage system.

You are able to configure the options available when the link is followed such as the customer, description of the payment being requested, amount, on-charge fees (not available for BPAY), ExternalID (use-full for tracking subsequent payments), payment options and if you would like us to email/sms the initial link and reminders to the customer.



Get a list of Payment Requests. - [Create a new Payment Request](https://docs.payadvantage.com.au/reference/payment_requests_post-1.md): Payment Requests let you receive a payment by creating a link with preconfigured payment options that can then be:
- used in your integration/application allowing a customer to click/follow a link through a button
- sent through your own system in emails, sms or letters
- sent in an email/sms by the PayAdvantage system.

You are able to configure the options available when the link is followed such as the customer, description of the payment being requested, amount, on-charge fees (not available for BPAY), ExternalID (use-full for tracking subsequent payments), payment options and if you would like us to email/sms the initial link and reminders to the customer.



Create a Payment Request Link. - [Retrieve a Payment Request](https://docs.payadvantage.com.au/reference/payment_requests_get-1.md): Payment Requests let you receive a payment by creating a link with preconfigured payment options that can then be:
- used in your integration/application allowing a customer to click/follow a link through a button
- sent through your own system in emails, sms or letters
- sent in an email/sms by the PayAdvantage system.

You are able to configure the options available when the link is followed such as the customer, description of the payment being requested, amount, on-charge fees (not available for BPAY), ExternalID (use-full for tracking subsequent payments), payment options and if you would like us to email/sms the initial link and reminders to the customer.



Get a single payment request using a reference code - [Delete a Payment Request](https://docs.payadvantage.com.au/reference/payment_requests_delete-1.md): Payment Requests let you receive a payment by creating a link with preconfigured payment options that can then be:
- used in your integration/application allowing a customer to click/follow a link through a button
- sent through your own system in emails, sms or letters
- sent in an email/sms by the PayAdvantage system.

You are able to configure the options available when the link is followed such as the customer, description of the payment being requested, amount, on-charge fees (not available for BPAY), ExternalID (use-full for tracking subsequent payments), payment options and if you would like us to email/sms the initial link and reminders to the customer.



Cancelling a Payment Request. This will mean the payment request link will no longer function and no further reminders will be sent (if reminders were enabled). - [Modify a Payment Request](https://docs.payadvantage.com.au/reference/payment_requests_patch.md): Payment Requests let you receive a payment by creating a link with preconfigured payment options that can then be:
- used in your integration/application allowing a customer to click/follow a link through a button
- sent through your own system in emails, sms or letters
- sent in an email/sms by the PayAdvantage system.

You are able to configure the options available when the link is followed such as the customer, description of the payment being requested, amount, on-charge fees (not available for BPAY), ExternalID (use-full for tracking subsequent payments), payment options and if you would like us to email/sms the initial link and reminders to the customer.



Resend a payment request by providing the amount of days the payment request can remain active. - [Retrieve Payments](https://docs.payadvantage.com.au/reference/payments_search.md): The Payments endpoint holds real-time records of any attempted payment in the Pay Advantage system. It is used for monitoring and tracking payments so that they can be managed appropriately by your own system. The Payments endpoint does not allow re-attempting failed payments.

All payments are associated with either a Customer, or a Debit Instruction. When a payment is attempted PayAdvantage allows a small window for any failures to be reported (typically 2-3 business days). This is due the processing times of some banks and credit card facilities. If no failure has been reported within this window then it is considered `cleared` and will then be settled to your account. BPAY payments are the only exception as they clear/settle immediately. [View information on Payment clearing and settlement](https://help.payadvantage.com.au/hc/en-us/articles/203572506-Payments-Clearance-Times-Settlements).

All payment types can fail (for a number of reasons) in which case the `DateFailed` and `FailCode` fields will be populated. Be aware that a payment can fail after the money has been settled to your account. This could occur many days, months, even years after settlement. Due to the nature of banking services and always allowing for payments to fail or be charged back, It is more correct to consider a payment as not failed rather than succeeded; however for most scenarios you can consider a settled payment as a success,. Charge-backs and late dishonours are rare for most businesses.

Returns a list of payment records arranged by date paid (By default, the most recent will appear first). The list is paged and will always return the first page of records. If there are no records that match your search you will be returned an empty list. - [Retrieve a Payment](https://docs.payadvantage.com.au/reference/payments_get.md): The Payments endpoint holds real-time records of any attempted payment in the Pay Advantage system. It is used for monitoring and tracking payments so that they can be managed appropriately by your own system. The Payments endpoint does not allow re-attempting failed payments.

All payments are associated with either a Customer, or a Debit Instruction. When a payment is attempted PayAdvantage allows a small window for any failures to be reported (typically 2-3 business days). This is due the processing times of some banks and credit card facilities. If no failure has been reported within this window then it is considered `cleared` and will then be settled to your account. BPAY payments are the only exception as they clear/settle immediately. [View information on Payment clearing and settlement](https://help.payadvantage.com.au/hc/en-us/articles/203572506-Payments-Clearance-Times-Settlements).

All payment types can fail (for a number of reasons) in which case the `DateFailed` and `FailCode` fields will be populated. Be aware that a payment can fail after the money has been settled to your account. This could occur many days, months, even years after settlement. Due to the nature of banking services and always allowing for payments to fail or be charged back, It is more correct to consider a payment as not failed rather than succeeded; however for most scenarios you can consider a settled payment as a success,. Charge-backs and late dishonours are rare for most businesses.

Returns a single payment record using the reference code value of a payment as an identifier.
This lets you view the current status of a payment, a history of the payments progression through different states (paid, failed, cleared, settled, etc.), any reason for failure, amount, payment type, any other relevant references. - [Retrieves payments settling on the specified date.](https://docs.payadvantage.com.au/reference/payments_settled.md): The Payments endpoint holds real-time records of any attempted payment in the Pay Advantage system. It is used for monitoring and tracking payments so that they can be managed appropriately by your own system. The Payments endpoint does not allow re-attempting failed payments.

All payments are associated with either a Customer, or a Debit Instruction. When a payment is attempted PayAdvantage allows a small window for any failures to be reported (typically 2-3 business days). This is due the processing times of some banks and credit card facilities. If no failure has been reported within this window then it is considered `cleared` and will then be settled to your account. BPAY payments are the only exception as they clear/settle immediately. [View information on Payment clearing and settlement](https://help.payadvantage.com.au/hc/en-us/articles/203572506-Payments-Clearance-Times-Settlements).

All payment types can fail (for a number of reasons) in which case the `DateFailed` and `FailCode` fields will be populated. Be aware that a payment can fail after the money has been settled to your account. This could occur many days, months, even years after settlement. Due to the nature of banking services and always allowing for payments to fail or be charged back, It is more correct to consider a payment as not failed rather than succeeded; however for most scenarios you can consider a settled payment as a success,. Charge-backs and late dishonours are rare for most businesses.

Returns a list of settled payments for a specified date. If using today as the date, it is recommended to run this as late in the day as possible (6pm - Midnight) so that any settlements that occurred during the day are captured. - [Retrieves payments failed on the specified date.](https://docs.payadvantage.com.au/reference/payments_failed.md): The Payments endpoint holds real-time records of any attempted payment in the Pay Advantage system. It is used for monitoring and tracking payments so that they can be managed appropriately by your own system. The Payments endpoint does not allow re-attempting failed payments.

All payments are associated with either a Customer, or a Debit Instruction. When a payment is attempted PayAdvantage allows a small window for any failures to be reported (typically 2-3 business days). This is due the processing times of some banks and credit card facilities. If no failure has been reported within this window then it is considered `cleared` and will then be settled to your account. BPAY payments are the only exception as they clear/settle immediately. [View information on Payment clearing and settlement](https://help.payadvantage.com.au/hc/en-us/articles/203572506-Payments-Clearance-Times-Settlements).

All payment types can fail (for a number of reasons) in which case the `DateFailed` and `FailCode` fields will be populated. Be aware that a payment can fail after the money has been settled to your account. This could occur many days, months, even years after settlement. Due to the nature of banking services and always allowing for payments to fail or be charged back, It is more correct to consider a payment as not failed rather than succeeded; however for most scenarios you can consider a settled payment as a success,. Charge-backs and late dishonours are rare for most businesses.

Returns a list of failed payments for a specified date. Avoid using today's date as payments can fail at any time during the day. For direct debit bank payments, it is best to query failed payments at least one day since the payment was attempted.
You can view a list of fail codes in the PayAdvantage [Enums & Fail Codes documentation](https://docs.payadvantage.com.au/docs/payment-fail-codes) to better understand reason for failure returned on these payment records and manage appropriately. - [Retrieve Products](https://docs.payadvantage.com.au/reference/products_search.md): Manage merchant products for use on invoice line items.

Returns a paged list of active products for the merchant. - [Create a new Product](https://docs.payadvantage.com.au/reference/products_post.md): Manage merchant products for use on invoice line items.

Creates a new product. - [Retrieve a Product](https://docs.payadvantage.com.au/reference/products_get.md): Manage merchant products for use on invoice line items.

Returns a single product by code. - [Update a product](https://docs.payadvantage.com.au/reference/products_patch.md): Manage merchant products for use on invoice line items.

Updates an existing product. Only the fields supplied in the request body are changed; omitted fields are left unchanged. - [Delete a Product](https://docs.payadvantage.com.au/reference/products_delete.md): Manage merchant products for use on invoice line items.

Soft-deletes a product (sets it as inactive). The product will no longer appear in the products list. - [Retrieve a product by SKU](https://docs.payadvantage.com.au/reference/products_get_by_sku.md): Manage merchant products for use on invoice line items.

Returns a single product by its merchant-defined SKU. If more than one product shares the SKU, the oldest is returned. - [Retrieve a QR Code](https://docs.payadvantage.com.au/reference/qr_codes_get-1.md): Returns a QR code as a PNG for the payment request link. This can then be printed on letters or used in POS situations allowing a customer the ability to scan the QR code and then make payment.

Please ensure you use the value found in the response under `Links.Code` and NOT the payment request code. - [Retrieve a QR Code with Logo](https://docs.payadvantage.com.au/reference/qr_code_with_logos_get.md): Returns a QR code as a PNG with the Pay Advantage logo in the center. This improves brand recognition while maintaining scan functionality.

Please ensure you use the value found in the response under `Links.Code` and NOT the payment request code. - [Retrieve Refunds](https://docs.payadvantage.com.au/reference/refunds_search-1.md): The Refunds endpoint handles the creation, cancellation, and monitoring of refunds for payments. As with payments, a refund is never effectively successful, it just hasn’t failed.
If a refund attempt does ever fail, you should cancel the refund or re-attempt the refund to an alternate account (via the Web Portal only).

Please note that you cannot modify refunds.

Returns a list of refund records. The list is paged and will always return the first page of records. If there are no records that match your search you will be returned an empty list. - [Create a new Refund](https://docs.payadvantage.com.au/reference/refunds_post-1.md): The Refunds endpoint handles the creation, cancellation, and monitoring of refunds for payments. As with payments, a refund is never effectively successful, it just hasn’t failed.
If a refund attempt does ever fail, you should cancel the refund or re-attempt the refund to an alternate account (via the Web Portal only).

Please note that you cannot modify refunds.

Create a refund payment and queue it up to be processed. When you create a refund in Pay Advantage you append a payment as a reference, but the refund is treated as it's own unique payment.
This request must include the relevant payments Code and a Reason for refund.
To refund an amount in full including all on-charged fees you should omit or set the the amount field to Null. To partially refund specify a value in the amount field. When partially refunding only that amount will be refunded. - [Retrieve Tax Codes](https://docs.payadvantage.com.au/reference/tax_codes_search.md): Manage merchant tax codes for invoice line items.

Returns a paged list of tax codes for the merchant. Auto-seeds default GST codes on first call. - [Create a new Tax Code](https://docs.payadvantage.com.au/reference/tax_codes_post.md): Manage merchant tax codes for invoice line items.

Creates a new tax code for the merchant. - [Update a Tax Code](https://docs.payadvantage.com.au/reference/tax_codes_put.md): Manage merchant tax codes for invoice line items.

Updates a tax code. For system tax codes, only the name can be updated. - [Delete a Tax Code](https://docs.payadvantage.com.au/reference/tax_codes_delete.md): Manage merchant tax codes for invoice line items.

Deletes a tax code. System tax codes and codes in use on products or invoice line items cannot be deleted. - [Retrieve Webhook Endpoints](https://docs.payadvantage.com.au/reference/webhook_endpoints_get_list.md): Lists all registered webhook endpoints. You can use this to verify the state of your endpoints as it will return the status of your webhook endpoints. - [Create a new Webhook Endpoint](https://docs.payadvantage.com.au/reference/webhook_endpoints_post.md): Create or re-arms Endpoints. This endpoint is only used for setting up your webhook endpoint for the first time.
This is run the first time you set up your webhook API.
When this runs it performs checks against the webhook endpoint to ensure you have set up your webhook correctly.If you have not configured you webhook listener correctly, then you will need to call this endpoint again to reset the arming process and try again.
For a list of the checks completed when arming a webhook: https://docs.payadvantage.com.au/docs/arming-an-endpoint - [Retrieve a Webhook Endpoint](https://docs.payadvantage.com.au/reference/webhook_endpoints_get.md): Gets a single registered webhook endpoint by its code. You can use this to verify the state of a specific endpoint. - [Delete a Webhook Endpoint](https://docs.payadvantage.com.au/reference/webhook_endpoints_delete.md): Permanently delete a webhook endpoint matching code along with any of its webhooks. Use this endpoint if you no longer want to receive events from a registered webhook endpoint. - [Modify a Webhook Endpoint](https://docs.payadvantage.com.au/reference/webhook_endpoints_patch.md): Force an API to be armed. - [Retrieve Webhooks](https://docs.payadvantage.com.au/reference/webhooks_recent.md): Webhooks serve as a mechanism that enables real-time communication between different web applications or services.
They facilitate the automatic transmission of data from one application to another as soon as a specific event occurs.
Essentially, when an event is triggered in the Pay Advantage application, a pre-configured URL (endpoint) in your application is notified, allowing it to process the data and initiate subsequent actions or updates.
This seamless flow of information allows developers to be automatically notified about Pay Advantage events and respond to them accordingly.
The list of support events can be found here: https://docs.payadvantage.com.au/docs/webhook-events

Gets all current webhooks that have not been accepted. - [Calculates the fees for a payment.](https://docs.payadvantage.com.au/reference/payment_authorization_fees_calculate-1.md): To provide a breakdown of the fee the customer will be charged for this type of transaction enter an amount and a credit card or a customer payment account code or payment type as the input. - [Get Payment Authorizations](https://docs.payadvantage.com.au/reference/payment_authorizations_search-1.md): Credit card transactions are made up of an authorisation and capture step. The authorisation component verifies the card is valid and requests the cardholders bank to place a hold on the funds. The capture then instructs the card issuer to send the funds to Pay Advantage for settlement to your merchant bank account. Generally when you process a card transaction on our platform we combine both the authorisation and the capture into one call for ease of use and simplicity.

We offer the ability for you to separate calls into two components allowing you to first authorise a transaction and place a hold on funds. Then either capture the funds or void the authorisation at a later date. This feature proves valuable in situations where you need to confirm the customer's available funds but might not require capturing those funds immediately, or you may need to capture an amount less than what was initially placed on hold.

For instance:
- Hotel mini-bar, first night of accommodation or security deposit.
- Hospitality venues when opening a bar account.
- Prior to dispatching goods to allow time to verify a customers identity or verify stock. - [Create a Payment Authorization or a Single PayTo Agreement](https://docs.payadvantage.com.au/reference/payment_authorizations_post-1.md): Credit card transactions are always made up of an authorisation and a capture. The authorisation component verifies the card is valid and requests the cardholders bank to place a hold on the funds. The capture then instructs the card issuer to send the funds to Pay Advantage for settlement to your merchant bank account. Generally when you process a card transaction on our platform we combine both the authorisation and the capture into one call for ease of use and simplicity.

We offer the ability for you to separate calls into two components allowing you to first authorise a transaction and place a hold on funds. Then either capture the funds or void the authorisation at a later date. This feature can save merchants the hassle, fees and risks attached with capturing funds upfront and then having to the transaction in part or in full as the authorisation can easily be voided if required.

This can be useful if you are not sure of the final amount or want to ensure the cardholder has sufficient funds such as:
- Hotel mini-bar, first night of accommodation or security deposit.
- Hospitality venues when opening a bar account.
- Prior to dispatching goods to allow time to verify a customers identity or verify stock.

A Single PayTo Agreement can be created by supplying the BankAccount instead of a Credit Card.
A PayTo Agreement is sent to the customer's banking app for their approval. Once approved, we transfer funds from the customer's account for settling into the merchant account. - [Get a Payment Authorization](https://docs.payadvantage.com.au/reference/payment_authorizations_get-1.md): Credit card transactions are always made up of an authorisation and a capture. The authorisation component verifies the card is valid and requests the cardholders bank to place a hold on the funds. The capture then instructs the card issuer to send the funds to Pay Advantage for settlement to your merchant bank account. Generally when you process a card transaction on our platform we combine both the authorisation and the capture into one call for ease of use and simplicity.

We offer the ability for you to separate calls into two components allowing you to first authorise a transaction and place a hold on funds. Then either capture the funds or void the authorisation at a later date. This feature can save merchants the hassle, fees and risks attached with capturing funds upfront and then having to the transaction in part or in full as the authorisation can easily be voided if required.

This can be useful if you are not sure of the final amount or want to ensure the cardholder has sufficient funds such as:
- Hotel mini-bar, first night of accommodation or security deposit.
- Hospitality venues when opening a bar account.
- Prior to dispatching goods to allow time to verify a customers identity or verify stock. - [Capture a Payment Authorization](https://docs.payadvantage.com.au/reference/payment_authorizations_patch-1.md): Credit card transactions are always made up of an authorisation and a capture. The authorisation component verifies the card is valid and requests the cardholders bank to place a hold on the funds. The capture then instructs the card issuer to send the funds to Pay Advantage for settlement to your merchant bank account. Generally when you process a card transaction on our platform we combine both the authorisation and the capture into one call for ease of use and simplicity.

We offer the ability for you to separate calls into two components allowing you to first authorise a transaction and place a hold on funds. Then either capture the funds or void the authorisation at a later date. This feature can save merchants the hassle, fees and risks attached with capturing funds upfront and then having to the transaction in part or in full as the authorisation can easily be voided if required.

This can be useful if you are not sure of the final amount or want to ensure the cardholder has sufficient funds such as:
- Hotel mini-bar, first night of accommodation or security deposit.
- Hospitality venues when opening a bar account.
- Prior to dispatching goods to allow time to verify a customers identity or verify stock. - [Void a Payment Authorization or Single PayTo Agreement](https://docs.payadvantage.com.au/reference/payment_authorizations_delete-1.md): Credit card transactions are always made up of an authorisation and a capture. The authorisation component verifies the card is valid and requests the cardholders bank to place a hold on the funds. The capture then instructs the card issuer to send the funds to Pay Advantage for settlement to your merchant bank account. Generally when you process a card transaction on our platform we combine both the authorisation and the capture into one call for ease of use and simplicity.

We offer the ability for you to separate calls into two components allowing you to first authorise a transaction and place a hold on funds. Then either capture the funds or void the authorisation at a later date. This feature can save merchants the hassle, fees and risks attached with capturing funds upfront and then having to refund the transaction in part or in full as the authorisation can easily be voided if required.

This can be useful if you are not sure of the final amount or want to ensure the cardholder has sufficient funds such as:
- Hotel mini-bar, first night of accommodation or security deposit.
- Hospitality venues when opening a bar account.
- Prior to dispatching goods to allow time to verify a customers identity or verify stock.

A Single PayTo Agreement can be voided if it has not been accepted by the customer. ## Recipes - [Simple Login using Axios / Node.js](https://docs.payadvantage.com.au/recipes/simple-login-using-axios-nodejs.md) ## Changelog - [Pay Advantage 11.12.0](https://docs.payadvantage.com.au/changelog/pay-advantage-11112.md) - [Pay Advantage 11.10.0](https://docs.payadvantage.com.au/changelog/pay-advantage-11100.md) - [Important Upcoming API Update: Webhook Code Format Change (8-Character Codes -> 36-Character UUID)](https://docs.payadvantage.com.au/changelog/important-upcoming-api-update-webhook-code-format-change-8-character-codes-uuid.md) - [Pay Advantage 11.2.0](https://docs.payadvantage.com.au/changelog/pay-advantage-1120.md) - [Pay Advantage 11.1.0](https://docs.payadvantage.com.au/changelog/pay-advantage-1110.md) - [Pay Advantage 10.8.0](https://docs.payadvantage.com.au/changelog/pay-advantage-1080.md) - [Pay Advantage 10.7.0](https://docs.payadvantage.com.au/changelog/pay-advantage-1070.md) - [Pay Advantage 10.6.0](https://docs.payadvantage.com.au/changelog/pay-advantage-1060.md) - [Pay Advantage 10.5.0](https://docs.payadvantage.com.au/changelog/pay-advantage-1050.md) - [Pay Advantage 10.3.0](https://docs.payadvantage.com.au/changelog/pay-advantage-1030.md)