PayTo^® Send Quick Start

Establish your first successful PayTo agreement and receive payment

Overview

This guide walks you through integrating PayTo, establishing your first PayTo agreement and receiving a payment.

By the end of this guide, you will:

• Configure access to our environments
• Build your PayTo integration
• Create a PayTo agreement and receive a response
• Understand how to handle agreement and payment statuses
• Prepare for Go-Live

For complete endpoint documentation, request and response formats, and field-level details, see the PayTo API Reference.

---

Plan for Go-Live early

While this guide focuses on getting you up and running quickly, there are a number of operational requirements that must be completed before you can go live with PayTo.

These include:

• Implementing approved CX messaging for agreements and payments
• Implementing customer terms and conditions and collection consent
• Completing compliance attestation

We recommend reviewing these requirements early in your integration to avoid delays later.

See also: Business Readiness Requirements

---

Step 1

Configure your access to our non-prod environment

Before calling the PayTo API, you must configure your environment. This ensures your system can securely connect to our APIs.

To call the PayTo API, you will need:

• mTLS certificate (available through DigiCert X9)
  Used to establish a secure connection
• Source IP whitelisting
  The IP addresses your system uses must be registered
• JWT signing key
  Used to authenticate API requests

Make sure you are using the non-prod environment for initial testing.

If your environment is not fully configured, API requests may fail due to authentication or connectivity errors.

See also: Security & Getting Access

---

Step 2

Build your initial integration

Depending on your use case, you will need to integrate PayTo into your payment workflow.

PayTo is typically triggered when:

• an end customer chooses PayTo as a self service payment option
• a business sends a PayTo agreement to an end customer to pre-authorise single or multiple payments

At a minimum, your application should:

1. Capture agreement details

You will need to collect:

• Customer identifier:
  • PayID or
  • BSB, account number and account name

You will also need to provide:

• Agreement terms:

  • Amount
  • Frequency (e.g. weekly, monthly, or ad-hoc)

• Agreement description (e.g. "Gym Membership")

Agreement structure is based on your use case and is typically defined as part of your PayTo onboarding process.

2. Implement customer authorisation flow

Your PayTo solution should:

• Clearly explain the PayTo agreement and authorisation flow to the user
• Prompt the user to authorise the agreement in their banking app
• Trigger agreement creation after user confirmation

---

Step 3

Create your first PayTo agreement

You can create an agreement by sending a PayTo agreement creation request with the agreement details outlined above.

Before sending your request, make sure your request includes all required authentication and signing headers.

Note: PayTo currently has a 5 transactions per second limit.

Environmental values

PayTo environment values

Name	Value
PayTo Base URL	Prod: https://secure.edge.api.commbank.com.au/payments/v1/ — Test: https://secure.edge.api.test.commbank.com.au/payments/v1/

Example Create Agreement Request

{
  "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
  }
}

Example Create Agreement Response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "accepted",
  "links": {}
}

Each time you create an agreement, you need to retain the Agreement ID. Once the agreement is activated you can initiate a payment using the Agreement ID.

See also: Error Codes and Troubleshooting

---

Step 4

Understand and handle agreement and payment statuses

Agreement statuses

The response includes an agreement status, indicating the current state of the agreement.

PayTo agreement statuses

Status	Description
PENDING	Awaiting customer approval
ACTIVE	Approved and ready for payments
REJECTED	Customer declined the agreement
CANCELLED	Agreement cancelled
PAUSED	Agreement temporarily suspended

Payment statuses

Once a payment is initiated, the response includes a payment status.

PayTo payment statuses

Status	Description
PROCESSING	Payment is being processed
COMPLETED	Payment completed successfully
FAILED	Payment was not successful

Payments are typically processed in near real-time, but your integration should:

• Handle asynchronous outcomes (e.g. processing → completed)
• Store and track the paymentId
• Support retries where appropriate

Handling responses in your PayTo solution

You should:

• Display appropriate confirmation and status messaging to users
• Ensure messaging is clear and user-friendly
• Avoid exposing raw API fields (e.g. internal reason codes)

See also: Error Codes and Troubleshooting

---

Step 5

Initiate your first PayTo payment

Once the agreement is ACTIVE, you can initiate a payment.

You can create a payment by sending:

• Agreement ID
• Amount
• Payment reference

Example Create Payment Request

{
  "amount": 0,
  "reference": "string",
  "description": "string",
  "lastPayment": true,
  "initiatingParty": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "destination": {
    "account": {
      "accountName": "string",
      "type": "bankAccount",
      "bsb": "string",
      "accountNumber": "string",
      "alternateIdentification": {
        "type": "EMAIL",
        "value": "string"
      }
    },
    "party": {
      "ultimatePartyName": "string"
    }
  }
}

Example Create Payment Response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "received"
}

See also: Error Codes and Troubleshooting

---

Step 6

Webhook Notifications (optional)

Agreement and Payment status changes can be received as Webhook Notifications.

Prerequisites

1. You've set up an HTTPS endpoint that CommBank will send Webhook Notifications (i.e. HTTPS POST) to.
2. This HTTPS URL has been onboarded by CommBank.

We will send a HTTPS POST from the following IPs:

• Non prod: 13.210.150.143, 52.63.197.18, 54.153.173.227
• Prod: 13.210.179.249, 13.237.68.178, 13.211.223.231

When you receive a HTTPS POST you should verify the timestamp and HMAC signature:

1. Verify the timestamp header specifies a time close to the current time.
2. Generate your own HMAC signature using the request URL, the timestamp header and the JSON request:

HMAC-SHA256(`POST${url}${timestamp}${json-request}`, secretKey)

3. Compare to the x-hmac-signature header using crypto.timingSafeEqual() function or similar to avoid timing attacks.
4. Process the webhook notification only if the timestamp and x-hmac-signature headers were verified successfully.

Example webhook notification

{
  "clientId": "<<clientId>>",
  "correlationId": "fc499a68-878e-44be-aa78-e16d409e0fbb",
  "payload": "{\"id\":\"fc499a68-878e-44be-aa78-e16d409e0fbb\",\"eventName\":\"AGREEMENT_PENDING\",\"apiVersion\":\"v1\",\"createdDate\":\"2025-01-28T03:57:34.785Z\",\"data\":{\"agreementID\":\"ffba8c6b-dd2b-11ef-a54d-92681288b289\",\"status\":\"CREATED\",\"statusReason\":\"PayTo Mandate awaiting customer acceptance\"}}"
}

---

Step 7

Prepare for production and Go-Live

Once your integration is working in non-prod, you can begin preparing for production.

This involves both technical validation and go-live readiness requirements.

1. Complete non-prod connectivity and technical testing

Before production access can be enabled, you will need to:

• Verify connectivity to non-prod PayTo endpoints
• Demonstrate that your integration behaves as expected
• Successfully execute required test cases (evidence required)

Test cases will be provided by our Integration Team.

2. Implement operational requirements

As mentioned above, you will need to submit evidence of completion of business go-live requirements.

See also: Business Readiness Requirements

3. Configure your production environment

Before going live, repeat environment configuration in production:

• Upload and verify your mTLS certificate
• Configure source IP whitelisting
• Publish your JWT signing key

See also: Security & Getting Access

4. Obtain production access and go live

Refer to the Go-Live Checklist and make sure every item has been completed.

Once all requirements are met, reviewed, and approved, you will be able to go live and start processing PayTo payments within your own systems.

PayTo is a registered trade mark of NPP Australia Ltd ABN 68 601 428 737.