---
title: "PayTo iOS Component"
description: "Add PayTo to your Components integration."
url: "https://docs.adyen.com/payment-methods/payto/ios-component"
source_url: "https://docs.adyen.com/payment-methods/payto/ios-component.md"
canonical: "https://docs.adyen.com/payment-methods/payto/ios-component"
last_modified: "2026-06-01T15:33:15+02:00"
language: "en"
---

# PayTo iOS Component

Add PayTo to your Components integration.

[View source](/payment-methods/payto/ios-component.md)

You can add PayTo to your existing integration. The following instructions show only what you must add to your integration specifically for PayTo.

If an instruction on this page corresponds with a step in the main integration guide, it includes a link to that corresponding step of the main integration guide.

What you must add to your integration depends on the [server-side flow](/online-payments/build-your-integration) that your integration uses:

## Sessions flow Component

### Before-You-Begin

## Requirements

| Requirement          | Description                                                                                                                                                                 |   |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| **Integration type** | Make sure that you have an existing Sessions flow [iOS Components integration](/online-payments/build-your-integration/sessions-flow?platform=iOS\&integration=Components). |   |
| **Checkout API**     | Make sure that you use Checkout API v70 or later.                                                                                                                           |   |
| **Setup steps**      | Before you begin, [add PayTo in your Customer Area](/payment-methods/add-payment-methods).                                                                                  |   |

### Add-Parameters-Sessions-Request

## Add additional parameters to your /sessions request

When you [create a payment session](/online-payments/build-your-integration/sessions-flow?platform=iOS\&integration=Components#create-a-payment-session), add the following parameters:

The additional parameters that you include depends on the type of PayTo payment.

* [One time payment](#one-time-payment)
* [Subscription setup and first payment](#subscription-setup-and-first-payment)

Subsequent subscription payments can only be performed with:

* [Advanced flow](/payment-methods/payto/ios-component?flow=Advanced+flow\&integration=Component#add-additional-parameters-to-your-payments-request)
* [API Only](/payment-methods/payto/api-only#add-additional-parameters-to-your-payments-request)

### One-time payment

To offer one-time payments, add the following additional parameters.

| Parameter                                                                                                                              | Required                                                                                    | Description                                                                                                                                                                               |   |
| -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| [shopperName.firstName](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-shopperName-firstName)               | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's first name.                                                                                                                                                                 |   |
| [shopperName.lastName](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-shopperName-lastName)                 | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's last name.                                                                                                                                                                  |   |
| [shopperStatement](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-shopperStatement)                         |                                                                                             | The text that shows up on the shopper's statement.                                                                                                                                        |   |
| [lineItems.quantity](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-lineItems-quantity)                     |                                                                                             | From 0 to 9999.                                                                                                                                                                           |   |
| [lineItems.sku](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-lineItems-sku)                               |                                                                                             | Up to 200 characters.                                                                                                                                                                     |   |
| [lineItems.description](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-lineItems-description)               |                                                                                             | Used to display the payment statement description to the shopper. Up to 280 characters. If multiple items, the item descriptions will be appended with a "," separator.                   |   |
| [lineItems.amountIncludingTax](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-lineItems-amountIncludingTax) |                                                                                             | From 1 to 100000000.                                                                                                                                                                      |   |
| [lineItems.itemCategory](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-lineItems-itemCategory)             |                                                                                             | Up to 200 characters.                                                                                                                                                                     |   |
| [reference](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-reference)                                       |                                                                                             | The reference to uniquely identify a payment. We recommend using a unique value per payment; however, it is not a requirement. Important: For PayTo, the maximum length is 35 characters. |   |

**Example request for creating a session for a one-time payment**

```bash
curl https://checkout-test.adyen.com/v71/sessions \
-H "x-API-key: ADYEN_API_KEY" \
-H "content-type: application/json" \
-d '{
   "merchantAccount": "ADYEN_MERCHANT_ACCOUNT",
   "amount": {
       "value": 3000,
       "currency": "AUD"
   },
   "reference": "YOUR_PAYMENT_REFERENCE",
   "countryCode":"AU",
   "shopperName": {
      "firstName": "Simon",
      "lastName": "Hopper"
   },
   "shopperReference": "YOUR_SHOPPER_REFERENCE"
   "returnUrl": "your-package-name.example.com/checkout?shopperOrder=12xy.."
}'
```

The response includes the following.

| Parameter            | Description                                                                                     |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| `mandate.frequency`  | **adhoc**                                                                                       |
| `mandate.endsAt`     | The end date. By default, it is set to one day after the payment request is sent.               |
| `mandate.amount`     | The amount of the payment. It is the same as the amount sent in the payment request.            |
| `mandate.amountRule` | **exact**                                                                                       |
| `mandate.count`      | **1**                                                                                           |
| `mandate.remarks`    | The text that appears on the shopper's statement. By default, the text is **One time payment**. |

**Example response for creating a session for a one-time payment**

```bash
curl https://checkout-test.adyen.com/v71/sessions \
-H "x-API-key: ADYEN_API_KEY" \
-H "content-type: application/json" \
-d '{
    "mandate": {
       "frequency":"adhoc",
       "endsAt":"2025-01-31",
       "amount":"3000",
       "amountRule":"exact",
       "count":"1",
       "remarks":"One time payment"
    },
    "sessionData": "Ab02b4c0!BQABAgBfYI29..."
}'
```

### Subscription setup and first payment

To set up a subscription agreement with specific conditions and accept the first payment from the shopper, add the following parameters.

| Parameter                                                                                                                                                  | Required                                                                                    | Description                                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [shopperName.firstName](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-shopperName-firstName)                                   | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's first name.                                                                                                                                                                                                                                                                                                                                                                        |
| [shopperName.lastName](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-shopperName-lastName)                                     | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's last name.                                                                                                                                                                                                                                                                                                                                                                         |
| [storePaymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-storePaymentMethod)                                         | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **true** to store payment details for subscription payments.                                                                                                                                                                                                                                                                                                                              |
| [recurringProcessingModel](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-recurringProcessingModel)                             | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Subscription**                                                                                                                                                                                                                                                                                                                                                                                 |
| [shopperInteraction](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-shopperInteraction)                                         | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Ecommerce**                                                                                                                                                                                                                                                                                                                                                                                    |
| [mandate.frequency](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-mandate-frequency)                                           | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The frequency with which a shopper should be charged. Possible values: adhoc, daily, weekly, biWeekly, monthly, quarterly, halfYearly, yearly. **adhoc**: Suitable for Card On File and Unscheduled Card On File recurring processing models. **daily**, **weekly**, **biWeekly**, **monthly**, **quarterly**, **halfYearly**, **yearly**: Suitable for Subscription recurring processing model. |
| [mandate.endsAt](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-mandate-endsAt)                                                 | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | End date of the billing plan, in YYYY-MM-DD format.                                                                                                                                                                                                                                                                                                                                              |
| [mandate.amount](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-mandate-amount)                                                 | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The billing amount (in minor units) of the recurring transactions. 1 to 1000000000.                                                                                                                                                                                                                                                                                                              |
| [mandate.amountRule](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-mandate-amountRule)                                         | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The limitation rule of the billing amount. Possible values: max: The transaction amount can not exceed the amount. exact: The transaction amount should be the same as the amount.                                                                                                                                                                                                               |
| [mandate.remarks](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-mandate-remarks)                                               | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The agreement description shown to the shopper up to 140 characters.                                                                                                                                                                                                                                                                                                                             |
| [mandate.count](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-mandate-count)                                                   |                                                                                             | The number of transactions that can be performed within the given frequency. Conditions: If the frequency is different than `adhoc` the count has to be provided and should be >= 1 If frequency is `adhoc` the count can be omitted or will represent the total number of payments that can be done.                                                                                            |
| [mandate.startsAt](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-mandate-startsAt)                                             |                                                                                             | Start date of the billing plan, in YYYY-MM-DD format. By default, the transaction date.                                                                                                                                                                                                                                                                                                          |
| [lineItems.quantity](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-lineItems-quantity) **[1](#lineitems)**                     |                                                                                             | From 0 to 9999.                                                                                                                                                                                                                                                                                                                                                                                  |
| [lineItems.sku](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-lineItems-sku) **[1](#lineitems)**                               |                                                                                             | Up to 200 characters. Note that this field is only available from v70 onwards.                                                                                                                                                                                                                                                                                                                   |
| [lineItems.description](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-lineItems-description) **[1](#lineitems)**               |                                                                                             | Used to display the payment statement description to the shopper. Up to 280 characters. If multiple items, the item descriptions will be appended with a "," separator.                                                                                                                                                                                                                          |
| [lineItems.amountIncludingTax](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-lineItems-amountIncludingTax) **[1](#lineitems)** |                                                                                             | From 1 to 100000000.                                                                                                                                                                                                                                                                                                                                                                             |
| [lineItems.itemCategory](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-lineItems-itemCategory) **[1](#lineitems)**             |                                                                                             | Up to 200 characters.                                                                                                                                                                                                                                                                                                                                                                            |
| [reference](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-reference)                                                           |                                                                                             | The reference to uniquely identify a payment. We recommend using a unique value per payment; however, it is not a requirement. Important: For PayTo, the maximum length is 35 characters.                                                                                                                                                                                                        |

[]()\
**1** The `lineItems` information are consolidated and provided to PayTo as the payment description, and can be shown in the shopper's banking app (depending on the bank's capabilities).

The following example shows a request to create a session that offers the shopper a subscription agreement with a first payment of 30 AUD and a weekly payment of up to 90 AUD.

| Parameter            | Example value                  | Description                                                                                           |
| -------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `amount.value`       | **3000**                       | After the shopper accepts the subscription agreement, they make a first, immediate payment of 30 AUD. |
| `mandate.frequency`  | **weekly**                     | A payment must be made weekly.                                                                        |
| `mandate.amount`     | **9000**                       | The amount of the weekly payment.                                                                     |
| `mandate.amountRule` | **max**                        | The maximum amount of the weekly payment is the `mandate.amount` of 90 AUD.                           |
| `mandate.count`      | **1**                          | The shopper can make only one payment each week.                                                      |
| `mandate.endsAt`     | **2025-12-31**                 | The subscription agreement ends on December 31, 2025.                                                 |
| `mandate.remarks`    | **Your agreement description** | The description of the agreement that appears in the shopper agreement.                               |

**Example request for setting up subscription with a first payment**

```bash
curl https://checkout-test.adyen.com/v71/sessions \
-H "x-API-key: ADYEN_API_KEY" \
-H "Idempotency-Key: YOUR_IDEMPOTENCY_KEY" \
-H "content-type: application/json" \
-d '{
   "merchantAccount": "ADYEN_MERCHANT_ACCOUNT",
   "amount": {
       "value": 3000,
       "currency": "AUD"
   },
   "reference": "YOUR_PAYMENT_REFERENCE",
   "countryCode":"AU",
   "mandate":{
      "frequency":"weekly",
      "endsAt":"2025-12-31",
      "amount":"9000",
      "amountRule":"max",
      "count":"1",
      "remarks":"Agreement description"
   },
   "shopperName": {
      "firstName": "Simon",
      "lastName": "Hopper"
   },
    "shopperReference": "YOUR_SHOPPER_REFERENCE"
    "recurringProcessingModel": "Subscription",
    "shopperInteraction": "Ecommerce",
    "returnUrl": "your-package-name.example.com/checkout?shopperOrder=12xy.."
}'
```

The response includes the `mandate` object with the same information that you sent in the request.

**Example response for setting up a subscription with a first payment**

```bash
curl https://checkout-test.adyen.com/v71/sessions \
-H "x-API-key: ADYEN_API_KEY" \
-H "content-type: application/json" \
-d '{
    "mandate": {
       "frequency":"weekly",
       "endsAt":"2025-12-31",
       "amount":"9000",
       "amountRule":"max",
       "count":"1",
       "remarks":"Agreement description"
    },
   "sessionData": "Ab02b4c0!BQABAgBfYI29..."
}'
```

The shopper receives a notification from their bank (through SMS, email, or in their banking app) to authorize or decline the agreement.

When the subscription agreement is accepted, you get the [RECURRING\_CONTRACT](https://docs.adyen.com/api-explorer/Webhooks/latest/post/RECURRING_CONTRACT) webhook that includes the `recurringDetailReference` for subsequent subscription payments.

Subsequent subscription payments can only be performed with:

* [Advanced flow](/payment-methods/payto/ios-component?flow=Advanced+flow\&integration=Component#add-additional-parameters-to-your-payments-request)
* [API Only](/payment-methods/payto/api-only#add-additional-parameters-to-your-payments-request)

### Required webhooks

The following webhook notifications indicate the status of the transaction.

**OFFER\_CLOSED**

This notification will be returned when the agreement failed or is canceled by the user.\
In this case, the `refusalReasonRaw` will be included in the `additionalData` object in the format `errorCode:errorDescription`. The contents of `refusalReasonRaw` will provide details about the reason for the failure or cancellation. Process the `refusalReasonRaw` to obtain more information about the decline or cancellation reason.

**AUTHORISATION**

You will receive this notification for a payment on an accepted agreement, the payment outcome could be authorized or rejected.\
In case the payment fails due to an error, you can consume the `refusalReasonRaw` that is returned in the `additionalData` object of your notification to get additional information about the reason for the payment being refused.

**REFUND**

When the refund is successfully received, the outcome will most likely succeed unless you receive a REFUND\_FAILED notification.

**REFUND\_FAILED**

Because refunds are asynchronous events, the outcome might fail due to unexpected reasons. In such cases you will receive a REFUND\_FAILED notification.

**RECURRING\_CONTRACT**

Contains the token in the payload of the notification sent to you in the `pspReference` parameter.

**DISABLE\_RECURRING**

When an agreement arrives to term, or is canceled (by you or the shopper), you will receive a DISABLE\_RECURRING notification to keep you informed about a token deletion.

[Token lifecycle webhooks](/online-payments/tokenization/managing-tokens/#webhooks) are also supported.

### Add-Configuration

## Add additional configuration for PayTo

You do not need to add any configuration parameters for PayTo.

### Initialize

## Initialize the Component for PayTo

To [initialize](#initialize-the-component) PayTo, it depends if the payment is a one-off payment or a recurring payment with the shopper's stored PayTo payment details.

### Tab: One-off payment

For a one-off payment, use the PayToComponent.

**Initialize the Component**

```swift
let paymentMethods = session.sessionContext.paymentMethods
// Check that the payment method is supported before showing the Component.
guard let paymentMethod = paymentMethods.paymentMethod(ofType: PayToPaymentMethod.self) else { return }

let configuration = PayToComponent.Configuration()

let component = PayToComponent(paymentMethod: paymentMethod,
                               context: context,
                               configuration: configuration)

self.currentComponent = component

// Set the session as the delegate.
component.delegate = session

let componentViewController = viewController(for: component)
present(componentViewController)
```

### Tab: Recurring payment

For a recurring payment using the shopper's stored PayTo payment details, use the `StoredPaymentMethodComponent`.

**Initialize the Stored Payment Method Component for PayTo**

```swift
let paymentMethods = session.sessionContext.paymentMethods

// Check that the payment method is supported before showing the Component.
guard let paymentMethod = paymentMethods.stored.compactMap { $0 as? StoredPayToPaymentMethod }.first else { return }

let storedConfiguration: StoredPaymentMethodComponent.Configuration

let component = StoredPaymentMethodComponent(paymentMethod: paymentMethod,
                                             context: context,
                                             configuration: storedConfiguration)

self.currentComponent = component

// Set the session as the delegate.
component.delegate = session

let componentViewController = viewController(for: component)
present(componentViewController)
```

## Test and go live

To test, use the `shopperAccountIdentifier` with the following emails to simulate testing scenarios:

| Type      | shopperAccountIdentifier                               | Result        | Description                                                               |
| --------- | ------------------------------------------------------ | ------------- | ------------------------------------------------------------------------- |
| Agreement | \[Any valid input]                                     | Authorised    | Successful payment.                                                       |
|           | expire\@adyen-test.com                                 | OFFER\_CLOSED | The Agreement has expired, please request your shopper to pay again.      |
|           | debtor\_account\_type\_not\_supported\@adyen-test.com  | OFFER\_CLOSED | The agreement has been refused.                                           |
| Payment   | \[Any valid input]                                     | Authorised    | Successful payment.                                                       |
|           | insufficient\_funds\@adyen-test.com                    | Refused       | Insufficient Funds                                                        |
|           | debtor\_account\_closed\@adyen-test.com                | Refused       | The Shopper account is closed.                                            |
|           | financial\_infrastructure\_unavailable\@adyen-test.com | Error         | NPP is unable to process the payment due to back office issues or outage. |

## Advanced flow Component

### Before-You-Begin

## Requirements

| Requirement          | Description                                                                                                                                                                                                                          |   |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - |
| **Integration type** | Make sure that you have an existing Advanced flow [iOS Components integration](/online-payments/build-your-integration/advanced-flow?platform=iOS\&integration=Drop-in).                                                             |   |
| **Checkout API**     | Make sure that you use Checkout API v70 or later.                                                                                                                                                                                    |   |
| **Action handling**  | Make sure that your existing integration is set up to [handle the additional action](/online-payments/build-your-integration/advanced-flow/?platform=iOS\&integration=Components#handle-the-redirect). `action.type`: ****await****. |   |
| **Setup steps**      | Before you begin, [add PayTo in your Customer Area](/payment-methods/add-payment-methods).                                                                                                                                           |   |

### Add-Configuration

## Add additional configuration for PayTo

You do not need to add any configuration parameters for PayTo.

### Initialize

## Initialize the Component for PayTo

To [initialize](#initialize-the-component) PayTo, it depends if the payment is a one-off payment or a recurring payment with the shopper's stored PayTo payment details.

### Tab: One-off payment

For a one-off payment, use the PayToComponent.

**Initialize the Component**

```swift
// Check that the payment method is supported before showing the Component.
guard let paymentMethod = paymentMethods.paymentMethod(ofType: PayToPaymentMethod.self) else {
    return }

let configuration =  PayToComponent.Configuration()

let component = PayToComponent(paymentMethod: paymentMethod,
                               context: context,
                               configuration: configuration)

component.delegate = self

let componentViewController = viewController(for: component)
present(viewController: componentViewController)

self.currentComponent = component
```

### Tab: Recurring payment

For a recurring payment using the shopper's stored PayTo payment details, use the `StoredPaymentMethodComponent`.

**Initialize the Stored Payment Method Component for PayTo**

```swift
// Check that the payment method is supported before showing the Component.
guard let paymentMethod = paymentMethods.stored.compactMap { $0 as? StoredPayToPaymentMethod }.first else { return }

let storedConfiguration: StoredPaymentMethodComponent.Configuration

// Create the Component.
let component = StoredPaymentMethodComponent(paymentMethod: paymentMethod,
                                             context: context,
                                             configuration: storedConfiguration)

self.currentComponent = component
// Set the Component as the delegate.
component.delegate = self

let componentViewController = viewController(for: component)
present(componentViewController)
```

### Add-Parameters-Payments-Request

## Add additional parameters to your /payments request

When you [make a payment](/online-payments/build-your-integration/advanced-flow/?platform=iOS\&integration=Components#make-a-payment), add the following parameters to the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request:

The additional parameters that you include depends on the type of payment.

* [One time payment](#one-time-payment)
* [Subscription setup and first payment](#subscription-setup-and-first-payment)
* [Subsequent subscription payment](#subsequent-subscription-payment)

### One-time payment

For one-time payments, add the following additional parameters.

| Parameter                                                                                                                                                               | Required                                                                                    | Description                                                                                                                                                                               |   |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| [paymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod)                                                                | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **payto**                                                                                                                                                                                 |   |
| [paymentMethod.shopperAccountIdentifier](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-listOfValues-shopperAccountIdentifier) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's banking details or PayID reference, used to complete the payment. [Possible values](#values). 1                                                                             |   |
| [shopperName.firstName](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperName-firstName)                                                | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's first name.                                                                                                                                                                 |   |
| [shopperName.lastName](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperName-lastName)                                                  | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's last name.                                                                                                                                                                  |   |
| [shopperStatement](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperStatement)                                                          |                                                                                             | The text that shows up on the shopper's statement.                                                                                                                                        |   |
| [lineItems.quantity](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-lineItems-quantity)                                                      |                                                                                             | The number of items From 0 to 9999.                                                                                                                                                       |   |
| [lineItems.sku](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-lineItems-sku)                                                                |                                                                                             | Up to 200 characters.                                                                                                                                                                     |   |
| [lineItems.description](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-lineItems-description)                                                |                                                                                             | Used to display the payment statement description to the shopper. Up to 280 characters. If multiple items, the item descriptions will be appended with a "," separator.                   |   |
| [lineItems.amountIncludingTax](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-lineItems-amountIncludingTax)                                  |                                                                                             | From 1 to 100000000.                                                                                                                                                                      |   |
| [lineItems.itemCategory](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-lineItems-itemCategory)                                              |                                                                                             | Up to 200 characters.                                                                                                                                                                     |   |
| [reference](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-reference)                                                                        |                                                                                             | The reference to uniquely identify a payment. We recommend using a unique value per payment; however, it is not a requirement. Important: For PayTo, the maximum length is 35 characters. |   |

**Example request for one-time payments**

```bash
curl https://checkout-test.adyen.com/v72/payments \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'idempotency-key: YOUR_IDEMPOTENCY_KEY' \
-H 'content-type: application/json' \
-X POST
-d '{
    "merchantAccount": "ADYEN_MERCHANT_ACCOUNT",
    "reference": "YOUR_REFERENCE",
    "amount": {
        "currency": "AUD",
        "value": 3000
    },
    "paymentMethod": {
        "type": "payto",
        "shopperAccountIdentifier": "PayID@example.com"
    },
    "countryCode": "AU",
    "shopperName": {
        "firstName": "Simon",
        "lastName": "Hopper"
    },
    "shopperReference": "YOUR_SHOPPER_REFERENCE",
    "returnUrl": "your-package-name.example.com/checkout?shopperOrder=12xy.."
}'
```

The response includes:

**Example response for one-time payments**

```bash
curl https://checkout-test.adyen.com/v72/payments \
-H "x-API-key: ADYEN_API_KEY" \
-H "content-type: application/json" \
-d '{
   "resultCode": "Pending",
   "action": {
      "paymentData": "Ab02....M9tFK",
      "paymentMethodType": "payto",
      "type": "await"
   }
}'
```

### Subscription setup and first payment

To set up a subscription agreement with specific conditions and accept the first payment from the shopper, add the following parameters.

| Parameter                                                                                                                                                               | Required                                                                                    | Description                                                                                                                                                                                                                                                                                                                                                                                      |   |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - |
| [paymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod)                                                                | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **payto**                                                                                                                                                                                                                                                                                                                                                                                        |   |
| [paymentMethod.shopperAccountIdentifier](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-listOfValues-shopperAccountIdentifier) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's banking details or PayID reference, used to complete the payment. [Possible values](#values). 1                                                                                                                                                                                                                                                                                    |   |
| [shopperName.firstName](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperName-firstName)                                                | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's first name.                                                                                                                                                                                                                                                                                                                                                                        |   |
| [shopperName.lastName](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperName-lastName)                                                  | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's last name.                                                                                                                                                                                                                                                                                                                                                                         |   |
| [storePaymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-storePaymentMethod)                                                      | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **true** to store payment details for subscription payments.                                                                                                                                                                                                                                                                                                                              |   |
| [recurringProcessingModel](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-recurringProcessingModel)                                          | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Subscription**                                                                                                                                                                                                                                                                                                                                                                                 |   |
| [shopperInteraction](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperInteraction)                                                      | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Ecommerce**                                                                                                                                                                                                                                                                                                                                                                                    |   |
| [mandate.frequency](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-mandate-frequency)                                                        | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The frequency with which a shopper should be charged. Possible values: adhoc, daily, weekly, biWeekly, monthly, quarterly, halfYearly, yearly. **adhoc**: Suitable for Card On File and Unscheduled Card On File recurring processing models. **daily**, **weekly**, **biWeekly**, **monthly**, **quarterly**, **halfYearly**, **yearly**: Suitable for Subscription recurring processing model. |   |
| [mandate.endsAt](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-mandate-endsAt)                                                              | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | End date of the billing plan, in YYYY-MM-DD format.                                                                                                                                                                                                                                                                                                                                              |   |
| [mandate.amount](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-mandate-amount)                                                              | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The billing amount (in minor units) of the recurring transactions. 1 to 1000000000.                                                                                                                                                                                                                                                                                                              |   |
| [mandate.amountRule](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-mandate-amountRule)                                                      | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The limitation rule of the billing amount. Possible values: max: The transaction amount can not exceed the amount. exact: The transaction amount should be the same as the amount.                                                                                                                                                                                                               |   |
| [mandate.remarks](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-mandate-remarks)                                                            | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The agreement description shown to the shopper, up to 140 characters.                                                                                                                                                                                                                                                                                                                            |   |
| [mandate.startsAt](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-mandate-startsAt)                                                          |                                                                                             | Start date of the billing plan, in YYYY-MM-DD format. By default, the transaction date.                                                                                                                                                                                                                                                                                                          |   |
| [mandate.count](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-mandate-count)                                                                |                                                                                             | The number of transactions that can be performed within the given frequency. Conditions: If the frequency is different than `adhoc` the count has to be provided and should be >= 1 If frequency is `adhoc` the count can be omitted or will represent the total number of payments that can be done.                                                                                            |   |
| [shopperStatement](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperStatement)                                                          |                                                                                             | The text that shows up on the shopper's statement. Appears in Mandate Remarks in one-off payment flow, if no Remarks are provided.                                                                                                                                                                                                                                                               |   |
| [lineItems.quantity](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-lineItems-quantity) **[1](#lineitems)**                                  |                                                                                             | From 0 to 9999.                                                                                                                                                                                                                                                                                                                                                                                  |   |
| [lineItems.sku](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-lineItems-sku) **[1](#lineitems)**                                            |                                                                                             | Up to 200 characters. Note that this field is only available from v70 onwards.                                                                                                                                                                                                                                                                                                                   |   |
| [lineItems.description](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-lineItems-description) **[1](#lineitems)**                            |                                                                                             | Used to display the payment statement description to the shopper. Up to 280 characters. If multiple items, the item descriptions will be appended with a "," separator.                                                                                                                                                                                                                          |   |
| [lineItems.amountIncludingTax](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-lineItems-amountIncludingTax) **[1](#lineitems)**              |                                                                                             | From 1 to 100000000.                                                                                                                                                                                                                                                                                                                                                                             |   |
| [lineItems.itemCategory](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-lineItems-itemCategory) **[1](#lineitems)**                          |                                                                                             | Up to 200 characters.                                                                                                                                                                                                                                                                                                                                                                            |   |
| [reference](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-reference)                                                                        |                                                                                             | The reference to uniquely identify a payment. We recommend using a unique value per payment; however, it is not a requirement. Important: For PayTo, the maximum length is 35 characters.                                                                                                                                                                                                        |   |

[]()\
**1** The `lineItems` information are consolidated and provided to PayTo as the payment description, and can be shown in the shopper's banking app (depending on the bank's capabilities).

The following example shows a payment request that gives the shopper a subscription agreement with a first payment of 30 AUD and a weekly payment of up to 90 AUD.

| Parameter            | Example value                  | Description                                                                                           |
| -------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `amount.value`       | **3000**                       | After the shopper accepts the subscription agreement, they make a first, immediate payment of 30 AUD. |
| `mandate.frequency`  | **weekly**                     | A payment must be made weekly.                                                                        |
| `mandate.amount`     | **9000**                       | The amount of the weekly payment.                                                                     |
| `mandate.amountRule` | **max**                        | The maximum amount of the weekly payment is the `mandate.amount` of 90 AUD.                           |
| `mandate.count`      | **1**                          | The shopper can make only one payment each week.                                                      |
| `mandate.endsAt`     | **2025-12-31**                 | The subscription agreement ends on December 31, 2025.                                                 |
| `mandate.remarks`    | **Your agreement description** | The description of the agreement that appears in the shopper agreement.                               |

**Example request for subscriptions**

```bash
curl https://checkout-test.adyen.com/v72/payments \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'idempotency-key: YOUR_IDEMPOTENCY_KEY' \
-H 'content-type: application/json' \
-X POST
-d '{
    "merchantAccount": "ADYEN_MERCHANT_ACCOUNT",
    "reference": "YOUR_REFERENCE",
    "amount": {
        "currency": "AUD",
        "value": 3000
    },
    "paymentMethod": {
        "type": "payto",
        "shopperAccountIdentifier": "PayID@example.com"
    },
    "countryCode": "AU",
    "shopperName": {
        "firstName": "Simon",
        "lastName": "Hopper"
    },
    "mandate":{
        "frequency": "weekly",
        "endsAt": "2025-12-31",
        "amount": "9000",
        "amountRule": "max",
        "count": "1",
        "remarks": "Your agreement description"
    },
    "shopperReference": "YOUR_SHOPPER_REFERENCE"
    "storePaymentMethod": true,
    "recurringProcessingModel": "Subscription",
    "shopperInteraction": "Ecommerce",
    "returnUrl": "your-package-name.example.com/checkout?shopperOrder=12xy.."
}'
```

The response includes:

**Example response for subscriptions**

```bash
curl https://checkout-test.adyen.com/v72/payments \
-H "x-API-key: ADYEN_API_KEY" \
-H "content-type: application/json" \
-d '{
   "resultCode": "Pending",
   "action": {
      "paymentData": "Ab02....M9tFK",
      "paymentMethodType": "payto",
      "type": "await"
   }
}'
```

The shopper receives a notification from their bank (through SMS, email, or in their banking app) to authorize or decline the agreement.

When the subscription agreement is accepted, you get the [RECURRING\_CONTRACT](https://docs.adyen.com/api-explorer/Webhooks/latest/post/RECURRING_CONTRACT) webhook that includes the `recurringDetailReference` for subsequent subscription payments.

### Subsequent subscription payment

For a subsequent subscription payment, add the following parameters.

| Parameter                                                                                                                                                         | Required                                                                                    | Description                                                                                                                                                                                                                                                                                                               |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [paymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod)                                                          | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **payto**                                                                                                                                                                                                                                                                                                                 |
| [paymentMethod.storedPaymentMethodId](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod-PayToDetails-storedPaymentMethodId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | From the [recurring.token.created](https://docs.adyen.com/api-explorer/Tokenization-webhooks/latest/post/recurring.token.created) webhook associated with the shopper, the `data.storedPaymentMethodId`. This stored payment method can only be used according to the conditions specified in the subscription agreement. |
| [shopperInteraction](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperInteraction)                                                | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **ContAuth**                                                                                                                                                                                                                                                                                                              |
| [reference](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-reference)                                                                  |                                                                                             | The reference to uniquely identify a payment. We recommend using a unique value per payment; however, it is not a requirement. Important: For PayTo, the maximum length is 35 characters.                                                                                                                                 |

**Example request for subsequent payments**

```bash
curl https://checkout-test.adyen.com/v72/payments \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'idempotency-key: YOUR_IDEMPOTENCY_KEY' \
-H 'content-type: application/json' \
-X POST
-d '{
    "merchantAccount": "ADYEN_MERCHANT_ACCOUNT",
    "reference": "YOUR_REFERENCE",
    "amount": {
        "currency": "AUD",
        "value": 3000
    },
    "paymentMethod": {
        "type": "payto",
        "storedPaymentMethodId": "FKSPNCQ8HXSKGK82"
    },
    "shopperReference": "YOUR_SHOPPER_REFERENCE"
    "recurringProcessingModel": "Subscription",
    "shopperInteraction": "ContAuth"
}'
```

The response includes:

**Example response for subsequent payments**

```bash
curl https://checkout-test.adyen.com/v72/payments \
-H "x-API-key: ADYEN_API_KEY" \
-H "content-type: application/json" \
-d '{
   "additionalData": {
       "bankAccount.ownerName": null,
       "recurring.contractTypes": "RECURRING",
       "recurring.recurringDetailReference": "BPRMC9F77R9B99X3",
       "recurringProcessingModel": "Subscription",
       "recurring.shopperReference": "YOUR_SHOPPER_REFERENCE",
       "tokenization.shopperReference": "YOUR_SHOPPER_REFERENCE",
       "recurring.firstPspReference": "ZMXFX9BFHT7ST5Q9",
       "tokenization.storedPaymentMethodId": "BPRMC9F77R9B99X3",
       "bankAccount.iban": null
   },
   "pspReference": "PPJT7Z8LGBT8W6G6",
   "resultCode": "Received",
   "merchantReference": "YOUR_REFERENCE"
}'
```

### Shopper account identifiers

The following table shows the possible values you can use for the `shopperAccountIdentifier` parameter.

| Identifier                    | Regular expression (RegEx) for allowed values                                                                                                         |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| BSB-AccountNumber             | `` ^\d{6}-[ -~]{1,28}$` ``                                                                                                                            |
| PayID Email                   | ``^(?:[a-z0-9!#$%&'*+\/=?^_`{\|}~-]+(?:\.[a-z0-9!#$%&'*+\/=?^_`{\|}~-]+)*@(?:[a-z0-9] (?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9] (?:[a-z0-9-]*[a-z0-9])?)$`` |
| PayID Phone Number            | `^\+[0-9]{1,3}-[1-9]{1,1}[0-9]{1,29}$`                                                                                                                |
| PayID ABN                     | `^((\d{9})\|(\d{11}))$`                                                                                                                               |
| PayID Organisation Identifier | `^[!-@\[-~][ -@\[-~]{0,254}[!-@\[-~]$`                                                                                                                |

### Required webhooks

The following webhook notifications indicate the status of the transaction.

**OFFER\_CLOSED**

This notification will be returned when the agreement failed or is canceled by the user.\
In this case, the `refusalReasonRaw` will be included in the `additionalData` object in the format `errorCode:errorDescription`. The contents of `refusalReasonRaw` will provide details about the reason for the failure or cancellation. Process the `refusalReasonRaw` to obtain more information about the decline or cancellation reason.

**AUTHORISATION**

You will receive this notification for a payment on an accepted agreement, the payment outcome could be authorized or rejected.\
In case the payment fails due to an error, you can consume the `refusalReasonRaw` that is returned in the `additionalData` object of your notification to get additional information about the reason for the payment being refused.

**REFUND**

When the refund is successfully received, the outcome will most likely succeed unless you receive a REFUND\_FAILED notification.

**REFUND\_FAILED**

Because refunds are asynchronous events, the outcome might fail due to unexpected reasons. In such cases you will receive a REFUND\_FAILED notification.

**RECURRING\_CONTRACT**

Contains the token in the payload of the notification sent to you in the `pspReference` parameter.

**DISABLE\_RECURRING**

When an agreement arrives to term, or is canceled (by you or the shopper), you will receive a DISABLE\_RECURRING notification to keep you informed about a token deletion.

[Token lifecycle webhooks](/online-payments/tokenization/managing-tokens/#webhooks) are also supported.

## Test and go live

To test, use the `shopperAccountIdentifier` with the following emails to simulate testing scenarios:

| Type      | shopperAccountIdentifier                               | Result        | Description                                                               |
| --------- | ------------------------------------------------------ | ------------- | ------------------------------------------------------------------------- |
| Agreement | \[Any valid input]                                     | Authorised    | Successful payment.                                                       |
|           | expire\@adyen-test.com                                 | OFFER\_CLOSED | The Agreement has expired, please request your shopper to pay again.      |
|           | debtor\_account\_type\_not\_supported\@adyen-test.com  | OFFER\_CLOSED | The agreement has been refused.                                           |
| Payment   | \[Any valid input]                                     | Authorised    | Successful payment.                                                       |
|           | insufficient\_funds\@adyen-test.com                    | Refused       | Insufficient Funds                                                        |
|           | debtor\_account\_closed\@adyen-test.com                | Refused       | The Shopper account is closed.                                            |
|           | financial\_infrastructure\_unavailable\@adyen-test.com | Error         | NPP is unable to process the payment due to back office issues or outage. |
