--- title: "create agreement" method: POST path: "/payto/agreements" tags: ["Agreements"] --- # create agreement `POST /payto/agreements` ## Request body - PaytoAgreementRequest - `uid` string, required — Supplied unique identifier for agreement, maximum 64 characters containing only unreserved characters as defined in RFC3986. This identifier ensures agreement uniqueness between integrator systems and Zepto. - `purpose` 'mortgage' | 'utility' | 'loan' | 'dependant_support' | 'gambling' | 'retail' | 'salary' | 'personal' | 'government' | 'pension' | 'tax' | 'other', required — The nature of the agreement with the debtor - `debtor` object, required — Who and where the payment is taken from - `ultimate_party_name` string — The ultimate debtor name for the account. Defaults to `party_name` if not provided. HTML name entities are not allowed. - `party_name` string, required — The name of the debtor party for this agreement. HTML name entities are not allowed. - `account_identifier` PaytoAccountIdentifier, required — An identifier representing the parties account - `type` 'bban' | 'alias_phone' | 'alias_email' | 'alias_abn' | 'alias_organisation_identifier', required - `value` union, required - string — A branch code (BSB) and account number separated with a hyphen - string — A PayID email alias - string — A PayID phone alias. e.g. +61-411222333 - string — A PayID ABN alias - string — A PayID organisation identifier alias - `creditor` object, nullable — Who and where the payment will be made to - `ultimate_party_name` string, required — The ultimate creditor name must accurately represent the ultimate creditor party and may be the same as the party_name. HTML name entities are not allowed. - `party_name` string, required — The name of the creditor party must accurately represent the creditor party and may be the same as the ultimate_party_name. HTML name entities are not allowed. - `account_identifier` PaytoAccountIdentifier, required — An identifier representing the parties account - `type` 'bban' | 'alias_phone' | 'alias_email' | 'alias_abn' | 'alias_organisation_identifier', required - `value` union, required - string — A branch code (BSB) and account number separated with a hyphen - string — A PayID email alias - string — A PayID phone alias. e.g. +61-411222333 - string — A PayID ABN alias - string — A PayID organisation identifier alias - `initiator` union — The details of the party that initiated this agreement. Provide either ABN or ACN. The values provided in `initiator` will be ignored unless the merchant has been approved as a third-party payment processor. - object - `name` string, required — The name of the initating party for this agreement. Displayed to the end customer by their financial institution. HTML name entities are not allowed. - `legal_name` string, required — The legal name of the initating party for this agreement. HTML name entities are not allowed. - `abn` string, nullable, required — The Australian Business Number (ABN) of the initiating party for this agreement. - object - `name` string, required — The name of the initating party for this agreement. Displayed to the end customer by their financial institution. HTML name entities are not allowed. - `legal_name` string, required — The legal name of the initating party for this agreement. HTML name entities are not allowed. - `acn` string, nullable, required — The Australian Company Number (ACN) of the initiating party for this agreement. - `description` string, required — The reason for the agreement, as narrative text. ASCII-printable characters only. - `resolution_requested_before` string, date-time, nullable — Requested resolution (accept/decline) deadline for this agreement. It will be provided in any notification sent to the debtor. This time is for informational purposes only and does not affect the expiry time. If not provided, it defaults to 5 days from agreement creation. Value must be an ISO8601 date-time in UTC timezone. - `cancel_if_unresolved` boolean, nullable — An optional field to indicate whether or not Zepto should auto cancel this agreement if it is not authorized by the debtor by the resolution_requested_before point in time. This field must be accompanied by the resolution_requested_before attribute and if not, will result in a 422 response and error code. - `validity_start_date` string, date, nullable — Start date for validity of agreement. If specified, the agreement will be valid from 00:00:00 Australia Sydney time on specified date. If no date specified, the current date will be populated. - `validity_end_date` string, date, nullable — End date of the validity of the agreement. If specified, the agreement will be valid until 23:59:59.999 Australia Sydney time on this date. - `metadata` PaytoMetadata, nullable — Use for your custom data. A place to store any miscellaneous information your system may need in regards to the record you are creating. This will be included in associated webhook payloads under the `resource_metadata` key. Nested values (i.e., objects and arrays) are not allowed. The maximum size of this parameter is 2kb. - `payment_terms` union, required — Defines the terms of what payments can be initiated from agreement - object — An agreement that supports payments for a given fixed amount only - `type` 'fixed', required — The pattern that payments will follow - `frequency` 'adhoc' | 'daily' | 'weekly' | 'fortnightly' | 'monthly' | 'quarterly' | 'semi_annual' | 'annual', required — The frequency at which payments will be made. Can be used in conjunction with `count` to allow more than one payment per period. - `amount` integer, nullable, required — Fixed amount to be debited from the debtor's account. Required for 'fixed' type agreements. - `count` integer, nullable — Count of payments allowed per frequency period. With non-adhoc frequency periods, if count is not given, one payment per frequency period will be allowed. If frequency is adhoc and count is not given, unlimited payments will be allowed. - `first_payment_date` string, date, nullable — The date first payment will be initiated for agreement. Date timezone is Australia Sydney. - `last_payment_date` string, date, nullable — The date last payment will be initiated for agreement. Date timezone is Australia Sydney. - object — An agreement that supports variable payments based up to an optional max amount - `type` 'variable', required — The pattern that payments will follow - `frequency` 'adhoc' | 'daily' | 'weekly' | 'fortnightly' | 'monthly' | 'quarterly' | 'semi_annual' | 'annual', required — The frequency at which payments will be made. Can be used in conjunction with `count` to allow more than one payment per period. - `count` integer, nullable — Count of payments allowed per frequency period. With non-adhoc frequency periods, if count is not given, one payment per frequency period will be allowed. If frequency is adhoc and count is not given, unlimited payments will be allowed. - `max_amount` integer, nullable — The maximum allowed payment amount, in cents. - `first_payment_date` string, date, nullable — The date first payment will be initiated for agreement. Date timezone is Australia Sydney. - `last_payment_date` string, date, nullable — The date last payment will be initiated for agreement. Date timezone is Australia Sydney. - object — An agreement that supports payments based on usage up to an optional max amount - `type` 'usage_based', required — The pattern that payments will follow - `frequency` 'adhoc' | 'daily' | 'weekly' | 'fortnightly' | 'monthly' | 'quarterly' | 'semi_annual' | 'annual', required — The frequency at which payments will be made. Can be used in conjunction with `count` to allow more than one payment per period. - `count` integer, nullable — Count of payments allowed per frequency period. With non-adhoc frequency periods, if count is not given, one payment per frequency period will be allowed. If frequency is adhoc and count is not given, unlimited payments will be allowed. - `max_amount` integer, nullable — The maximum allowed payment amount, in cents. - `first_payment_date` string, date, nullable — The date first payment will be initiated for agreement. Date timezone is Australia Sydney. - `last_payment_date` string, date, nullable — The date last payment will be initiated for agreement. Date timezone is Australia Sydney. - object — An agreement that supports a balloon amount for first and last payments. - `type` 'balloon', required — The pattern that payments will follow - `frequency` 'adhoc' | 'daily' | 'weekly' | 'fortnightly' | 'monthly' | 'quarterly' | 'semi_annual' | 'annual', required — The frequency at which payments will be made. Can be used in conjunction with `count` to allow more than one payment per period. - `amount` integer, required — Fixed amount to be debited from the debtor's account. Required for 'balloon' type agreements. 'first_payment_amount' and 'last_payment_amount' will override this value for their corresponding first and last amounts. - `count` integer, nullable — Count of payments allowed per frequency period. With non-adhoc frequency periods, if count is not given, one payment per frequency period will be allowed. If frequency is adhoc and count is not given, unlimited payments will be allowed. - `first_payment_amount` integer, nullable — Optional specified payment amount for first payment, in cents. Applicable only to 'balloon' terms type. - `last_payment_amount` integer, nullable — Optional specified payment amount for last payment, in cents. Applicable only to 'balloon' terms type. - `first_payment_date` string, date, nullable — The date first payment will be initiated for agreement. Date timezone is Australia Sydney. - `last_payment_date` string, date, nullable — The date last payment will be initiated for agreement. Date timezone is Australia Sydney. - `sandbox` object — SANDBOX ONLY: Parameter that allows you to simulate the debtor performing certain actions against the created agreement to aid integrators while testing their control flows. Defaults to debtor_accept if not given. - `simulate` 'debtor_accept' | 'debtor_decline' | 'expire' | 'debtor_account_type_not_supported' | 'debtor_alias_not_found' | 'creditor_alias_not_found' | 'alias_resolution_service_unavailable' | 'agreement_service_unavailable', required - `delay` integer — An optional attribute that will delay the requested simulation by the given amount of seconds. If `delay` is not provided (default behaviour), the simulated action will happen instantly. ## Response `201` successful - object - `data` PaytoAgreement - `uid` string, required — Supplied unique identifier for agreement, maximum 64 characters containing only unreserved characters as defined in RFC3986. This identifier ensures agreement uniqueness between integrator systems and Zepto. - `state` 'pending' | 'created' | 'active' | 'suspended' | 'cancelled' | 'declined' | 'failed' | 'expired', required — The current state of the agreement - `created_at` string, date-time, required — An ISO 8601 datetime, with offset - `state_caused_by` 'debtor' | 'initiator' | 'zepto_admin' | 'zepto_system', required — The party that caused the agreement to be in its current state - `mms_agreement_id` string, nullable, required — The agreement ID as per the MMS. Formatted as a Universally Unique Identifier (UUID) version 1, as described in IETC RFC 4122 without the 4 hyphen separators. - `links` object, required - `self` string, required — A URL to this agreement - `description` string, required — The reason for the agreement, as narrative text. ASCII-printable characters only. - `purpose` 'mortgage' | 'utility' | 'loan' | 'dependant_support' | 'gambling' | 'retail' | 'salary' | 'personal' | 'government' | 'pension' | 'tax' | 'other', required — The nature of the agreement with the debtor - `resolution_requested_before` string, date-time, nullable, required — Requested resolution (accept/decline) deadline for this agreement. It will be provided in any notification sent to the debtor. This time is for informational purposes only and does not affect the expiry time. If not provided, it defaults to 5 days from agreement creation. Value must be an ISO8601 date-time in UTC timezone. - `cancel_if_unresolved` boolean, nullable, required — An optional field to indicate whether or not Zepto should auto cancel this agreement if it is not authorized by the debtor by the resolution_requested_before point in time. This field must be accompanied by the resolution_requested_before attribute and if not, will result in a 422 response and error code. - `payment_terms` object, required - `type` 'balloon' | 'fixed' | 'usage_based' | 'variable', required — The pattern that payments will follow - `frequency` 'adhoc' | 'daily' | 'weekly' | 'fortnightly' | 'monthly' | 'quarterly' | 'semi_annual' | 'annual', required — The frequency at which payments will be made. Can be used in conjunction with `count` to allow more than one payment per period. - `count` integer, nullable, required — Count of payments allowed per frequency period. With non-adhoc frequency periods, if count is not given, one payment per frequency period will be allowed. If frequency is adhoc and count is not given, unlimited payments will be allowed. - `amount` integer, nullable, required — Fixed amount to be debited from the debtor's account. Required for 'fixed' and 'balloon' types. - `max_amount` integer, nullable, required — The maximum allowed payment amount, in cents. - `first_payment_amount` integer, nullable, required — Optional specified payment amount for first payment, in cents. Applicable only to 'balloon' terms type. - `last_payment_amount` integer, nullable, required — Optional specified payment amount for last payment, in cents. Applicable only to 'balloon' terms type. - `first_payment_date` string, date, nullable, required — The date first payment will be initiated for agreement. Date timezone is Australia Sydney. - `last_payment_date` string, date, nullable, required — The date last payment will be initiated for agreement. Date timezone is Australia Sydney. - `debtor` object, required — Who and where the payment is taken from - `ultimate_party_name` string, required — The ultimate debtor name for the account. Defaults to `party_name` if not provided. HTML name entities are not allowed. - `party_name` string, required — The name of the debtor party for this agreement. HTML name entities are not allowed. - `account_identifier` PaytoAccountIdentifier, required — An identifier representing the parties account - `type` 'bban' | 'alias_phone' | 'alias_email' | 'alias_abn' | 'alias_organisation_identifier', required - `value` union, required - string — A branch code (BSB) and account number separated with a hyphen - string — A PayID email alias - string — A PayID phone alias. e.g. +61-411222333 - string — A PayID ABN alias - string — A PayID organisation identifier alias - `creditor` object, nullable, required — Who and where the payment will be made to - `ultimate_party_name` string, required — The ultimate creditor name must accurately represent the ultimate creditor party and may be the same as the party_name. HTML name entities are not allowed. - `party_name` string, required — The name of the creditor party must accurately represent the creditor party and may be the same as the ultimate_party_name. HTML name entities are not allowed. - `account_identifier` PaytoAccountIdentifier, required — An identifier representing the parties account - `type` 'bban' | 'alias_phone' | 'alias_email' | 'alias_abn' | 'alias_organisation_identifier', required - `value` union, required - string — A branch code (BSB) and account number separated with a hyphen - string — A PayID email alias - string — A PayID phone alias. e.g. +61-411222333 - string — A PayID ABN alias - string — A PayID organisation identifier alias - `initiator` object, required — The details of the party that initiated this agreement - `name` string, required — The name of the initating party for this agreement. Displayed to the end customer by their financial institution. HTML name entities are not allowed. - `legal_name` string, required — The legal name of the initating party for this agreement. HTML name entities are not allowed. - `abn` string, nullable, required — The Australian Business Number (ABN) of the initiating party for this agreement. - `acn` string, nullable, required — The Australian Company Number (ACN) of the initiating party for this agreement. - `validity_start_date` string, date, nullable, required — Start date for validity of agreement. If specified, the agreement will be valid from 00:00:00 Australia Sydney time on specified date. If no date specified, the current date will be populated. - `validity_end_date` string, date, nullable, required — End date of the validity of the agreement. If specified, the agreement will be valid until 23:59:59.999 Australia Sydney time on this date. - `state_reason` object, nullable, required — Details about why the agreement is in the state it is when applicable. - `title` string, required — A short description of the reason or failure - `detail` string, required — A longer description of the reason or failure - `code` 'MMS.API.9000' | 'MMS.API.9001' | 'MMS.API.9002' | 'MMS.API.9003' | 'MMS.API.9005' | 'MMS.API.9006' | 'MMS.API.9007' | 'MMS.API.9008' | 'MMS.API.9009' | 'MMS.API.9010' | 'MMS.API.9011' | 'MMS.API.9013' | 'MMS.API.9015' | 'MMS.API.9016' | 'MMS.API.9017' | 'MMS.API.9018' | 'MMS.API.9019' | 'MMS.API.9101' | 'MMS.API.9102' | 'MMS.API.9103' | 'MMS.API.9104' | 'MMS.API.9105' | 'MMS.API.9106' | 'MMS.API.9107' | 'MMS.API.9108' | 'MMS.API.9109' | 'MMS.API.9110' | 'MMS.API.9111' | 'MMS.API.9112' | 'MMS.API.9113' | 'MMS.API.9114' | 'MMS.API.9115' | 'MMS.API.9116' | 'MMS.API.9117' | 'MMS.API.9118' | 'MMS.API.9119' | 'MMS.API.9120' | 'MMS.API.9121' | 'MMS.API.9301' | 'MMS.API.9302' | 'MMS.API.9303' | 'MMS.API.9401' | 'MMS.API.9402' | 'MMS.API.9501' | 'MMS.API.9601' | 'MMS.API.9900' | 'MMS.API.9901' | 'AC02' | 'AC05' | 'AC06' | 'AC13' | 'AG01' | 'AG03' | 'AM03' | 'AM12' | 'AM14' | 'BE06' | 'MD09' | 'MD16' | 'MD21' | 'NOAS' | 'RR04' | 'SL11' | 'SL12' | 'AC04' | 'MD07' | 'MD08' | 'MD17' | 'MD20' | 'MS02' | 'MS03' | 'NARR' | 'SL01' | 'CTAM' | 'CTCA' | 'CTEX' | 'MCFC' | 'MCOC' | 'MSUC' | 'ZPUNP01' | 'ZPUNP02' | 'ZPUNP06' | 'ZPUNP07' | 'ZPUNP08' | 'UKNWN', required — A unique identifier for this specific type of reason or failure - `metadata` PaytoMetadata, nullable — Use for your custom data. A place to store any miscellaneous information your system may need in regards to the record you are creating. This will be included in associated webhook payloads under the `resource_metadata` key. Nested values (i.e., objects and arrays) are not allowed. The maximum size of this parameter is 2kb. ## Other responses - `400` — Bad Request - `401` — unauthorized - `403` — forbidden - `422` — Unprocessable Entity - `500` — Internal Server Error --- [API](https://skmtc.net/zeptopayments/apis/zepto-api.md) · [All operations](https://skmtc.net/zeptopayments/apis/zepto-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zeptopayments/zepto-api/versions/6353e9b9af6f/schema)