# PayTo Agreements and Payments

Source: https://docs.gocardless.com/docs/collect-payments/recurring-payments/payto

# PayTo Agreements and Payments

PayTo is a real-time payment scheme for Australian bank accounts. GoCardless supports two use cases: setting up an open mandate with your customer, and taking one-off real-time payments.

> **Info:**
> PayTo uses the term "agreement" for the contract between you and your customer. This maps to a
>   "mandate" in the GoCardless API. The two terms are synonymous — customers will see "agreement" in
>   the payment flow.

## Step 1: Create a Billing Request

Use the `mandate_request` field when creating a Billing Request to set up a PayTo mandate. The following requirements must be met:

- `scheme` must be `pay_to`
- `purpose_code` is required
- `description` is required
- `constraints` is optional

### Purpose code

The `purpose_code` attribute specifies the high-level purpose of the mandate. Accepted values are: `mortgage`, `utility`, `loan`, `dependant_support`, `gambling`, `retail`, `salary`, `personal`, `government`, `pension`, `tax`, and `other`.

See the full list of supported values in [Billing Request Purpose Codes](/docs/collect-payments/scheme-guidance/billing-request-purpose-codes).

### Constraints

Constraints specify the limits on recurring payments, allowing you to collect payments without requiring the payer to re-consent each time — provided payments fall within the agreed constraints.

| Parameter                        | Description                                                                                                                           |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `start_date`                     | Date from which the consent is valid. Must not be in the past; the payer must have enough time to complete the flow before this date. |
| `end_date`                       | Date after which payments cannot be collected. Must not be in the past or before `start_date`.                                        |
| `max_amount_per_payment`         | Maximum amount that can be charged per payment.                                                                                       |
| `periodic_limits[].period`       | Repeating time frame: `year`, `month`, `week`, or `day`.                                                                              |
| `periodic_limits[].max_payments` | Maximum number of payments that can be taken within the period.                                                                       |

### Example request

```http
POST https://api.gocardless.com/billing_requests HTTP/1.1
]
      }
    }
  }
}
```

You'll receive a full Billing Request object in response:

```json

        ]
      }
    },
    "payment_request": null,
    "metadata": null,
    "links": ,
    "purpose_code": "mortgage",
    "creditor_name": "Hotel Park Grand",
    "actions": [
      ,
      ,
      
    ]
  }
}
```

## Step 2: Create a Billing Request Flow

Create a Billing Request Flow to generate a hosted checkout link for your customer. For PayTo, always include an `exit_uri`.

> **Warning:**
> Some banks do not yet support PayTo. If a customer's bank is unsupported, they will be redirected
>   to the `exit_uri` rather than reaching a dead end. We recommend sending them back to your checkout
>   page so they can choose an alternative payment method.

```php
$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->billingRequestFlows()->create([
  "params" => [
    "redirect_uri" => "https://my-company.com/landing",
    "exit_uri" => "https://my-company.com/exit",
    "links" => [
      "billing_request" => "BRQ000010NMDMH2"
    ]
  ]
]);
```

```python

client = gocardless_pro.Client(access_token="your_access_token_here", environment='sandbox')

client.billing_request_flows.create(params=
})
```

```ruby
@client = GoCardlessPro::Client.new(
  access_token: "your_access_token",
  environment: :sandbox
)

@client.billing_request_flows.create(
  params: 
  }
)
```

```java

String accessToken = "your_access_token_here";
GoCardlessClient client = GoCardlessClient
    .newBuilder(accessToken)
    .withEnvironment(SANDBOX)
    .build();

BillingRequestFlow billingRequestFlow = client.billingRequestFlows().create()
  .withRedirectUri("https://my-company.com/landing")
  .withExitUri("https://my-company.com/exit")
  .withLinksBillingRequest("BRQ000010NMDMH2")
  .execute();
```

```javascript
const constants = require("gocardless-nodejs/constants");
const gocardless = require("gocardless-nodejs");
const client = gocardless("your_access_token_here", constants.Environments.Sandbox);

const billingRequestFlow = await client.billingRequestFlows.create(,
});
```

```cs
String accessToken = "your_access_token";
GoCardlessClient gocardless = GoCardlessClient.Create(accessToken, Environment.SANDBOX);

var resp = await gocardless.BillingRequestFlows.CreateAsync(
  new GoCardless.Services.BillingRequestFlowCreateRequest()
  ,
  }
);

GoCardless.Resources.BillingRequestFlow billingRequestFlow = resp.BillingRequestFlow;
```

```http
POST https://api.gocardless.com/billing_request_flows HTTP/1.1

  }
}
```

```go
package main

	gocardless "github.com/gocardless/gocardless-pro-go/v6"
)

accessToken := "your_access_token_here";
opts := gocardless.WithEndpoint(gocardless.SandboxEndpoint)
client, err := gocardless.New(accessToken, opts)

billingRequestFlowCreateParams := gocardless.BillingRequestFlowCreateParams
billingRequestFlowCreateParams.RedirectUri = "https://my-company.com/landing"
billingRequestFlowCreateParams.ExitUri = "https://my-company.com/exit"
billingRequestFlowCreateParams.Links.BillingRequest = "BRQ000010NMDMH2"
billingRequestFlow, err := client.BillingRequestFlows.Create(context, billingRequestFlowCreateParams)
```

```json

  }
}
```

Send the `authorisation_url` from the response to your customer via a button, email, SMS, or any other channel.

## Existing customers and locking

**Skip steps for existing customers** — If you already have a customer on record, pass their ID in `links.customer` on the Billing Request to skip the customer details step. Similarly, pass `links.customer_bank_account` to skip the bank account step. The customer can still edit these details unless they are locked.

**Lock details** — Set `lock_customer_details` or `lock_bank_account` to `true` on the Billing Request Flow to prevent the customer from changing those details. When both are locked, the customer skips directly to the confirmation step.

**Lock scheme and currency** — For mandate-only requests, you can set `lock_currency` to `true` on the Billing Request Flow. This prevents the customer from changing the scheme or currency, ensuring the mandate is always set up in PayTo.

## What the customer will see

### Collect customer details

The customer provides their personal details. This step is skipped if customer details already exist or have been locked.

![Collect customer details screen](/images/docs/collect-payments/recurring-payments/payto/screenshot_2024-01-11_at_08.18.24.png)

### Collect bank details

The customer provides their PayID or bank details. This step is skipped if bank details already exist or have been locked.

![Collect bank details screen](/images/docs/collect-payments/recurring-payments/payto/screenshot_2024-01-11_at_08.32.02.png)

### Bank authorisation

The customer is prompted to complete the authorisation in their banking app. Depending on their bank, they may also receive a push notification or SMS.

![Bank authorisation screen](/images/docs/collect-payments/recurring-payments/payto/screenshot_2024-01-11_at_08.54.56.png)

### Confirmation

Once authorisation is complete, a confirmation screen is shown. All required actions are fulfilled and the Billing Request is complete.

![Confirmation screen](/images/docs/collect-payments/recurring-payments/payto/screenshot_2024-01-11_at_08.53.18.png)

## What's next?

  
#### [Billing Request Purpose Codes](/docs/collect-payments/scheme-guidance/billing-request-purpose-codes)

Full list of supported purpose codes for PayTo and other schemes.

  
#### [Test Bank Details](/docs/developer-resources/test-bank-details)

Use sandbox bank details to test your PayTo integration.

  
#### [Billing Request Events](/docs/collect-payments/events-and-webhooks/billing-request-events)

Understand the webhook events fired during the PayTo agreement lifecycle.

  
#### [Setting Up Mandates](/docs/collect-payments/setting-up-mandates)

Learn how to set up Direct Debit mandates using Billing Requests.