API Reference

PayTo (1.0.0)

PayTo is a modern digital payment solution enabling real-time, account-to-account payments from a customer’s bank account. Developed under the New Payments Platform Australia initiative, PayTo replaces traditional direct debit with a faster, more secure option

This API follows RESTful principles and provides a simple way to integrate PayTo functionality into your systems. It uses semantic versioning to ensure backward compatibility and includes idempotency support through the x-idempotency-id header to prevent duplicate transactions. The API is designed to be developer-friendly while maintaining the security and reliability required for financial transactions.

Download OpenAPI description

payto-send.json

payto-send.yaml

Servers

https://developer.api.commbank.com.au/

Agreements

Endpoints for creating, managing, and retrieving PayTo agreements between creditors and debtors.

Operations

Create an Agreement

Request

Creates an agreement which allows the creditor to pull funds from a debtor account.

The agreement must first be approved by the debtor party in order to pull funds from their acccount.

These direct debit payments can be on an automated schedule, ad-hoc or one-off. If a recurring schedule is provided, then debits will be automatically created as per the approved schedule.

Security

oauth2

Headers

x-idempotency-idstring(uuid)(xIdempotencyId)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...required

Uniquely identifies the operation for safe retries. See API Usage page for more information.

x-request-idstring(uuid)(xRequestId)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...

Unique request id

Bodyapplication/jsonrequired

typestring(string)<= 9 characters^[a-z\s]+$required

The type of agreement Classified as

oneoff: Use oneoff agreement to allow single payment only. Following rules apply
- paymentDetails\schedule is not applicable & should not be provided.
- paymentDetails\maxNumberOfPayment is not applicable & should not be provided.
recurring: Use recurring agreement to allow periodic payments. Following rules apply
- paymentDetails\schedule is mandatory
- paymentDetails\maxNumberOfPayments is not applicable & should not be provided.
adhoc: Use adhoc agreement to allow multiple non-periodic payments. Following rules apply
- maxNumberOfPayments is optional, if supplied then value should be greater than 1.
- paymentDetails\schedule is not applicable & should not be provided.

Enum"oneoff""adhoc""recurring"

referencestring(string)(reference)<= 35 characters/^.*$/required

Short description of the reason for agreement setup as narrative text. Specifies a character string with a maximum length of 35 ASCII printable characters.

descriptionstring(string)(description)<= 140 characters/^.*$/required

Reason for the agreement setup as narrative text. Specifies a character string with a maximum length of 140 ASCII printable characters.

validFromstring(date)(validFrom)<= 10 characters^\d{4}-\d{2}-\d{2}$required

Start date of the validity of the agreement. The agreement is valid as of 00:00:00.000 Australia Sydney time on this date. A particular point in the progression of time in a calendar year expressed in the YYYY-MM-DD format. Can either be today or a future date.

validTostring(date)(validTo)<= 10 characters^\d{4}-\d{2}-\d{2}$

End date of the validity of the agreement. If specified, the agreement is valid until 23:59:59.999 Australia Sydney time on this date. A particular point in the progression of time in a calendar year expressed in the YYYY-MM-DD format. Can either be equal to or after the validFrom date

sourceobject(partyAccount)required

The account details from where the funds will be debited

source.accountobject(accountReference)required

source.account.typestring(string)(accountType)<= 24 characters^[a-zA-Z\s]+$required

Type of account identification.

Enum"bankAccount""alternateIdentification"

source.account.bsbstring(string)(bsb)<= 6 characters^[0-9]{6}$

The BSB (Bank-State-Branch) code

source.account.accountNumberstring(string)(accountNumber)[ 1 .. 28 ] characters^[0-9]+$

source.account.accountNamestring(string)(accountName)[ 1 .. 140 ] characters/^.*$/required

Full Legal Account Name recorded by the Account Server in their records. Specifies a character string with a maximum length of 140 ASCII printable characters.

source.account.alternateIdentificationobject(alternateIdentification)

source.partyobject(party)required

source.party.typestring(string)<= 12 characters^[a-z\s]+$required

Specifies the type of party involved in the transaction as either a person or organisation.

Enum"organisation""person"

source.party.idTypestring(string)<= 32 characters^[a-zA-Z\s]+$

Identification type of the party, for example in the case of a person; passportNumber, driversLicenseNumber etc or in the case of an organisation; australianBusinessNumber, australianCompanyNumber etc

Enum"passportNumber""customerIdentificationNumber""driversLicenseNumber""employeeIdentificationNumber""taxIdentificationNumber""bankPartyIdentification""certificateOfIncorporationNumber""australianBusinessNumber""australianCompanyNumber"

source.party.idstring(string)<= 35 characters/^.*$/

Unique and unambiguous identification of the party. Specifies a character string with a maximum length of 35 ASCII printable characters.

source.party.ultimatePartyNamestring(string)(ultimatePartyName)[ 1 .. 140 ] characters/^.*$/required

Name by which the ultimate party is known and which is usually used to identify that party. Specifies a character string with a maximum length of 140 ASCII printable characters.

source.party.referencestring(string)(reference)<= 35 characters/^.*$/

Short description of the reason for agreement setup as narrative text. Specifies a character string with a maximum length of 35 ASCII printable characters.

destinationobject(partyAccount)required

The account details to where the funds will be credited

destination.accountobject(accountReference)required

destination.account.typestring(string)(accountType)<= 24 characters^[a-zA-Z\s]+$required

Type of account identification.

Enum"bankAccount""alternateIdentification"

destination.account.bsbstring(string)(bsb)<= 6 characters^[0-9]{6}$

The BSB (Bank-State-Branch) code

destination.account.accountNumberstring(string)(accountNumber)[ 1 .. 28 ] characters^[0-9]+$

destination.account.accountNamestring(string)(accountName)[ 1 .. 140 ] characters/^.*$/required

Full Legal Account Name recorded by the Account Server in their records. Specifies a character string with a maximum length of 140 ASCII printable characters.

destination.account.alternateIdentificationobject(alternateIdentification)

destination.partyobject(party)required

destination.party.typestring(string)<= 12 characters^[a-z\s]+$required

Specifies the type of party involved in the transaction as either a person or organisation.

Enum"organisation""person"

destination.party.idTypestring(string)<= 32 characters^[a-zA-Z\s]+$

destination.party.idstring(string)<= 35 characters/^.*$/

Unique and unambiguous identification of the party. Specifies a character string with a maximum length of 35 ASCII printable characters.

destination.party.ultimatePartyNamestring(string)(ultimatePartyName)[ 1 .. 140 ] characters/^.*$/required

Name by which the ultimate party is known and which is usually used to identify that party. Specifies a character string with a maximum length of 140 ASCII printable characters.

destination.party.referencestring(string)(reference)<= 35 characters/^.*$/

Short description of the reason for agreement setup as narrative text. Specifies a character string with a maximum length of 35 ASCII printable characters.

initiatingPartyobject(initiatingParty)required

The party initiating the agreement

initiatingParty.idstring(uuid)(uuid)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...required

Commbank assigned ID for the merchant.

paymentDetailsobject(paymentDetails)required

paymentDetails.typestring(string)<= 10 characters^[a-zA-Z\s]+$required

Identifes the agreement payment arrangement

fixed: Agreement with fixed payment amount, following rules apply
- amount must be specified.
- maxAmount should not be specified.
variable: Agreement with variable payment amount, following rules apply
- maxAmount is recommended. However, amount and max amount are optional. If both amount and max amount are present, amount should be less than max amount
usageBased: Agreement with payment amount based on usage, following rules apply
- maxAmount is recommended. However, amount and max amount are optional. If both amount and max amount are present, amount should be less than max amount
balloon: Agreement with fixed payment amount and large final payment amount, following rules apply
- amount must be specified.
- maxAmount should not be specified.

Enum"fixed""usageBased""variable""balloon"

paymentDetails.amountnumber(decimal)(amount)<= 10 characters<= 9999999.99^\d+\.\d{2}$

Fixed amount to be debited from the debtor's account

paymentDetails.maxAmountnumber(decimal)(amount)<= 10 characters<= 9999999.99^\d+\.\d{2}$

Maximum amount that may be paid from the debtor's account, per instruction

paymentDetails.firstCollectionAmountnumber(decimal)(amount)<= 10 characters<= 9999999.99^\d+\.\d{2}$

Amount different from the Payment amount, as it includes the costs associated with the first debited amount

paymentDetails.purposestring(string)<= 16 characters^[a-zA-Z\s]+$required

Specifies the high level purpose of the agreement based on a set of pre-defined categories.

Enum"mortgage""utility""loan""dependantSupport""gambling""retail""salary""personal""government""pension"

paymentDetails.maxNumberOfPaymentsnumber<= 18 characters

Maximum number of payment instructions to be created and processed during the specified period. This value must be a positive integer.

paymentDetails.finalCollectionAmountnumber(decimal)(amount)<= 10 characters<= 9999999.99^\d+\.\d{2}$

paymentDetails.scheduleobject

Describes the recurring schedule details, if applicable

Both pointInTime and countPerPeriod can't be provided in the same request. Where value for pointInTime is not provided countPerPeriod must have a valid non decimal numeric value, greater than zero

curl -i -X POST \
  https://developer.api.commbank.com.au/agreements \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-idempotency-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'x-request-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -d '{
    "type": "oneoff",
    "reference": "Short reference for oneOff retail purchase",
    "description": "Friendly description of the oneOff agreement",
    "validFrom": "2024-03-07",
    "validTo": "2029-03-07",
    "initiatingParty": {
      "id": "3a817cbb-f91b-40b3-86a9-566078ba185a"
    },
    "source": {
      "account": {
        "type": "bankAccount",
        "bsb": 802950,
        "accountNumber": 333333333,
        "accountName": "ss"
      },
      "party": {
        "type": "organisation",
        "id": "orga-src",
        "ultimatePartyName": "PAAS test client",
        "idType": "australianCompanyNumber"
      }
    },
    "destination": {
      "account": {
        "type": "bankAccount",
        "bsb": 802950,
        "accountNumber": 333333331,
        "accountName": "kk"
      },
      "party": {
        "type": "person",
        "id": "orga-dest",
        "ultimatePartyName": "kk",
        "idType": "australianCompanyNumber"
      }
    },
    "paymentDetails": {
      "type": "usageBased",
      "purpose": "retail",
      "amount": 9.99
    }
  }'

Responses

Accepted

Headers

Content-Languagestring(language)<= 5 characters^en-AU$

Value"en-AU"

Content-Typestring(media)<= 16 characters^application/json$

Value"application/json"

Bodyapplication/json

idstring(uuid)(agreementId)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...

Agreement ID

statusstring(string)<= 12 characters^[a-z\s]+$

Agreement status

Value"accepted"

linksobject

Response

application/json

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "accepted",
  "links": {}
}

Get an Agreement

Request

Retrieve a single agreement

Security

oauth2

Path

idstring(uuid)(agreementId)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...required

Agreement ID

Headers

x-request-idstring(uuid)(xRequestId)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...

UUID that was passed to the request in the x-request-id header.

curl -i -X GET \
  'https://developer.api.commbank.com.au/agreements/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-request-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Responses

Headers

Content-Languagestring(language)<= 5 characters^en-AU$

Value"en-AU"

Content-Typestring(media)<= 16 characters^application/json$

Value"application/json"

Bodyapplication/json

idstring(uuid)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...

Unique id for the agreement

typestring(string)<= 9 characters^[a-z\s]+$required

The type of agreement Classified as

oneoff: Use oneoff agreement to allow single payment only. Following rules apply
- paymentDetails\schedule is not applicable & should not be provided.
- paymentDetails\maxNumberOfPayment is not applicable & should not be provided.
recurring: Use recurring agreement to allow periodic payments. Following rules apply
- paymentDetails\schedule is mandatory
- paymentDetails\maxNumberOfPayments is not applicable & should not be provided.
adhoc: Use adhoc agreement to allow multiple non-periodic payments. Following rules apply
- maxNumberOfPayments is optional, if supplied then value should be greater than 1.
- paymentDetails\schedule is not applicable & should not be provided.

Enum"oneoff""adhoc""recurring"

referencestring(string)(reference)<= 35 characters/^.*$/required

Short description of the reason for agreement setup as narrative text. Specifies a character string with a maximum length of 35 ASCII printable characters.

descriptionstring(string)(description)<= 140 characters/^.*$/required

Reason for the agreement setup as narrative text. Specifies a character string with a maximum length of 140 ASCII printable characters.

validFromstring(date)(validFrom)<= 10 characters^\d{4}-\d{2}-\d{2}$required

validTostring(date)(validTo)<= 10 characters^\d{4}-\d{2}-\d{2}$

sourceobject(partyAccount)required

The account details from where the funds will be debited

source.accountobject(accountReference)required

source.account.typestring(string)(accountType)<= 24 characters^[a-zA-Z\s]+$required

Type of account identification.

Enum"bankAccount""alternateIdentification"

source.account.bsbstring(string)(bsb)<= 6 characters^[0-9]{6}$

The BSB (Bank-State-Branch) code

source.account.accountNumberstring(string)(accountNumber)[ 1 .. 28 ] characters^[0-9]+$

source.account.accountNamestring(string)(accountName)[ 1 .. 140 ] characters/^.*$/required

Full Legal Account Name recorded by the Account Server in their records. Specifies a character string with a maximum length of 140 ASCII printable characters.

source.account.alternateIdentificationobject(alternateIdentification)

source.partyobject(party)required

source.party.typestring(string)<= 12 characters^[a-z\s]+$required

Specifies the type of party involved in the transaction as either a person or organisation.

Enum"organisation""person"

source.party.idTypestring(string)<= 32 characters^[a-zA-Z\s]+$

source.party.idstring(string)<= 35 characters/^.*$/

Unique and unambiguous identification of the party. Specifies a character string with a maximum length of 35 ASCII printable characters.

source.party.ultimatePartyNamestring(string)(ultimatePartyName)[ 1 .. 140 ] characters/^.*$/required

Name by which the ultimate party is known and which is usually used to identify that party. Specifies a character string with a maximum length of 140 ASCII printable characters.

source.party.referencestring(string)(reference)<= 35 characters/^.*$/

Short description of the reason for agreement setup as narrative text. Specifies a character string with a maximum length of 35 ASCII printable characters.

destinationobject(partyAccount)required

The account details to where the funds will be credited

destination.accountobject(accountReference)required

destination.account.typestring(string)(accountType)<= 24 characters^[a-zA-Z\s]+$required

Type of account identification.

Enum"bankAccount""alternateIdentification"

destination.account.bsbstring(string)(bsb)<= 6 characters^[0-9]{6}$

The BSB (Bank-State-Branch) code

destination.account.accountNumberstring(string)(accountNumber)[ 1 .. 28 ] characters^[0-9]+$

destination.account.accountNamestring(string)(accountName)[ 1 .. 140 ] characters/^.*$/required

Full Legal Account Name recorded by the Account Server in their records. Specifies a character string with a maximum length of 140 ASCII printable characters.

destination.account.alternateIdentificationobject(alternateIdentification)

destination.partyobject(party)required

destination.party.typestring(string)<= 12 characters^[a-z\s]+$required

Specifies the type of party involved in the transaction as either a person or organisation.

Enum"organisation""person"

destination.party.idTypestring(string)<= 32 characters^[a-zA-Z\s]+$

destination.party.idstring(string)<= 35 characters/^.*$/

Unique and unambiguous identification of the party. Specifies a character string with a maximum length of 35 ASCII printable characters.

destination.party.ultimatePartyNamestring(string)(ultimatePartyName)[ 1 .. 140 ] characters/^.*$/required

Name by which the ultimate party is known and which is usually used to identify that party. Specifies a character string with a maximum length of 140 ASCII printable characters.

destination.party.referencestring(string)(reference)<= 35 characters/^.*$/

Short description of the reason for agreement setup as narrative text. Specifies a character string with a maximum length of 35 ASCII printable characters.

initiatingPartyobject(initiatingParty)required

The party initiating the agreement

initiatingParty.idstring(uuid)(uuid)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...required

Commbank assigned ID for the merchant.

paymentDetailsobject(paymentDetails)required

paymentDetails.typestring(string)<= 10 characters^[a-zA-Z\s]+$required

Identifes the agreement payment arrangement

fixed: Agreement with fixed payment amount, following rules apply
- amount must be specified.
- maxAmount should not be specified.
variable: Agreement with variable payment amount, following rules apply
- maxAmount is recommended. However, amount and max amount are optional. If both amount and max amount are present, amount should be less than max amount
usageBased: Agreement with payment amount based on usage, following rules apply
- maxAmount is recommended. However, amount and max amount are optional. If both amount and max amount are present, amount should be less than max amount
balloon: Agreement with fixed payment amount and large final payment amount, following rules apply
- amount must be specified.
- maxAmount should not be specified.

Enum"fixed""usageBased""variable""balloon"

paymentDetails.amountnumber(decimal)(amount)<= 10 characters<= 9999999.99^\d+\.\d{2}$

Fixed amount to be debited from the debtor's account

paymentDetails.maxAmountnumber(decimal)(amount)<= 10 characters<= 9999999.99^\d+\.\d{2}$

Maximum amount that may be paid from the debtor's account, per instruction

paymentDetails.firstCollectionAmountnumber(decimal)(amount)<= 10 characters<= 9999999.99^\d+\.\d{2}$

Amount different from the Payment amount, as it includes the costs associated with the first debited amount

paymentDetails.purposestring(string)<= 16 characters^[a-zA-Z\s]+$required

Specifies the high level purpose of the agreement based on a set of pre-defined categories.

Enum"mortgage""utility""loan""dependantSupport""gambling""retail""salary""personal""government""pension"

paymentDetails.maxNumberOfPaymentsnumber<= 18 characters

Maximum number of payment instructions to be created and processed during the specified period. This value must be a positive integer.

paymentDetails.finalCollectionAmountnumber(decimal)(amount)<= 10 characters<= 9999999.99^\d+\.\d{2}$

paymentDetails.scheduleobject

Describes the recurring schedule details, if applicable

Both pointInTime and countPerPeriod can't be provided in the same request. Where value for pointInTime is not provided countPerPeriod must have a valid non decimal numeric value, greater than zero

statusstring(string)<= 12 characters^[a-z\s]+$

Enum"accepted""failed""created""activated""cancelled""suspended"

reasonobject

linksobject

Response

application/json

{
  "type": "recurring",
  "reference": "Short reference of the agreement",
  "description": "Friendly description of the agreement",
  "validFrom": "2024-05-23",
  "source": {
    "account": { … },
    "party": { … }
  },
  "destination": {
    "account": { … },
    "party": { … }
  },
  "paymentDetails": {
    "type": "usageBased",
    "purpose": "retail",
    "amount": "9.99,",
    "schedule": { … }
  },
  "id": "7af61033189711ef9b881ebfd4149e2d",
  "validTo": "2029-05-23",
  "status": "activated"
}

Modify Agreement details

Request

** detailed description **

Security

oauth2

Path

idstring(uuid)(agreementId)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...required

Agreement ID

Headers

x-idempotency-idstring(uuid)(xIdempotencyId)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...required

Uniquely identifies the operation for safe retries. See API Usage page for more information.

x-request-idstring(uuid)(xRequestId)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...

Unique request ID

Bodyapplication/jsonrequired

initiatingPartyobject(initiatingParty)required

initiatingParty.idstring(uuid)(uuid)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...required

Commbank assigned ID for the merchant.

uniLateralobject

biLateralobject

curl -i -X PATCH \
  'https://developer.api.commbank.com.au/agreements/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-idempotency-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'x-request-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -d '{
    "initiatingParty": {
      "id": "3a817cbb-f91b-40b3-86a9-566078ba185a"
    },
    "uniLateral": {
      "reference": "Short reference for oneOff retail purchase",
      "description": "Friendly description of the oneOff agreement",
      "destination": {
        "account": {
          "type": "bankAccount",
          "bsb": 802950,
          "accountNumber": 333333333,
          "accountName": "ss"
        },
        "party": {
          "type": "organisation",
          "id": "orga-src",
          "ultimatePartyName": "PAAS test client",
          "idType": "australianCompanyNumber"
        }
      }
    }
  }'

Responses

Headers

Content-Languagestring(language)<= 5 characters^en-AU$

Value"en-AU"

Content-Typestring(media)<= 16 characters^application/json$

Value"application/json"

Bodyapplication/json

actionIdstring(uuid)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...

Unique ID to identify the agreement status change request.

Response

application/json

{
  "actionId": "4a2794ff-94cb-4bac-8d36-d5fb36c563a0"
}

Validate Agreement

Request

Validation step to be used before creating an Agreement to ensure that the agreement can be successfully created between the two parties.

If one of the parties does not support PayTo, then the validation step will fail.

Security

oauth2

Headers

x-request-idstring(uuid)(xRequestId)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...required

Caller generated UUID that can be used to uniquely identify the request in server logs

Example: ca9d8fcd-91f5-42b9-ae44-78fbc553f094

Bodyapplication/jsonrequired

sourceobject(accountWrapper)required

The account where funds will be debited

source.accountobject(accountReference)required

source.account.typestring(string)(accountType)<= 24 characters^[a-zA-Z\s]+$required

Type of account identification.

Enum"bankAccount""alternateIdentification"

source.account.bsbstring(string)(bsb)<= 6 characters^[0-9]{6}$

The BSB (Bank-State-Branch) code

source.account.accountNumberstring(string)(accountNumber)[ 1 .. 28 ] characters^[0-9]+$

source.account.accountNamestring(string)(accountName)[ 1 .. 140 ] characters/^.*$/required

Full Legal Account Name recorded by the Account Server in their records. Specifies a character string with a maximum length of 140 ASCII printable characters.

source.account.alternateIdentificationobject(alternateIdentification)

destinationobject(accountWrapper)required

The account where funds will be credited

destination.accountobject(accountReference)required

destination.account.typestring(string)(accountType)<= 24 characters^[a-zA-Z\s]+$required

Type of account identification.

Enum"bankAccount""alternateIdentification"

destination.account.bsbstring(string)(bsb)<= 6 characters^[0-9]{6}$

The BSB (Bank-State-Branch) code

destination.account.accountNumberstring(string)(accountNumber)[ 1 .. 28 ] characters^[0-9]+$

destination.account.accountNamestring(string)(accountName)[ 1 .. 140 ] characters/^.*$/required

Full Legal Account Name recorded by the Account Server in their records. Specifies a character string with a maximum length of 140 ASCII printable characters.

destination.account.alternateIdentificationobject(alternateIdentification)

initiatingPartyobject(initiatingParty)required

The party initiating the agreement

initiatingParty.idstring(uuid)(uuid)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...required

Commbank assigned ID for the merchant.

curl -i -X POST \
  https://developer.api.commbank.com.au/agreements/validate \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-request-id: ca9d8fcd-91f5-42b9-ae44-78fbc553f094' \
  -d '{
    "source": {
      "account": {
        "type": "bankAccount",
        "bsb": "string",
        "accountNumber": "string",
        "accountName": "string",
        "alternateIdentification": {
          "type": "EMAIL",
          "value": "string"
        }
      }
    },
    "destination": {
      "account": {
        "type": "bankAccount",
        "bsb": "string",
        "accountNumber": "string",
        "accountName": "string",
        "alternateIdentification": {
          "type": "EMAIL",
          "value": "string"
        }
      }
    },
    "initiatingParty": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    }
  }'

Responses

Headers

Content-Languagestring(language)<= 5 characters^en-AU$

Value"en-AU"

Content-Typestring(media)<= 16 characters^application/json$

Value"application/json"

Bodyapplication/json

validbooleanrequired

Determines if an Agreement can be created between the two parties.

Enumtruefalse

Example: true

Response

application/json

{
  "valid": true
}

Change status of an Agreement

Request

There are three types of agreement states changes that could be requested; 'cancel', 'suspend' and 'release'.

The status can only be changed when the agreement is currently active or suspended.

To release an Agreement is to activate a suspended agreement. Releasing a suspended agreement can only be performed by the party that suspended the agreement.

To suspend an Agreement is equivalent to pausing payments for the agreement.

A cancelled agreement cannot be further updated.

Security

oauth2

Path

idstring(uuid)(agreementId)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...required

Agreement ID

Headers

x-request-idstring(uuid)(xRequestId)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...

UUID that was passed to the request in the x-request-id header.

x-idempotency-idstring(uuid)(xIdempotencyId)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...required

Uniquely identifies the operation for safe retries. See API Usage page for more information.

Bodyapplication/jsonrequired

initiatingPartyobject(initiatingParty)required

The party initiating the agreement

initiatingParty.idstring(uuid)(uuid)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...required

Commbank assigned ID for the merchant.

statusstring(string)<= 7 characters^[a-z\s]+$required

Enumeration of possible status changes.

cancel - cancel an active or suspended agreement
suspend - suspend an active agreement
release - release a suspended agreement

Enum"cancel""suspend""release"

reasonobject

curl -i -X PATCH \
  'https://developer.api.commbank.com.au/agreements/{id}/status' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-idempotency-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'x-request-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -d '{
    "status": "suspend",
    "initiatingParty": {
      "id": "3a817cbb-f91b-40b3-86a9-566078ba185a"
    },
    "reason": {
      "code": "AC02",
      "description": "suspension agreement"
    }
  }'

Responses

Headers

Content-Languagestring(language)<= 5 characters^en-AU$

Value"en-AU"

Content-Typestring(media)<= 16 characters^application/json$

Value"application/json"

Bodyapplication/json

referenceNumberstring(uuid)(uuid)<= 36 characters^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89...

Unique ID to identify the agreement status change request.

Response

application/json

{
  "referenceNumber": "f51553ca-a1ad-4253-825b-9ba809f83a5f"
}

Payments

Endpoints for initiating, managing, and retrieving payment transactions under PayTo agreements.

Operations

Utilities

Endpoints for auxiliary operations such as health checks and other supporting functionalities.

Operations

PayTo (1.0.0)

Agreements

Create an Agreement

RequestExpand all

Responses

Get an Agreement

Request

Responses

Modify Agreement details

RequestExpand all

Responses

Validate Agreement

RequestExpand all

Responses

Change status of an Agreement

RequestExpand all

Responses

Payments

Utilities

Request

Request

Request

Request