--- title: "add identification to agreement" method: POST path: "/payto/agreements/{agreement_uid}/add_identification" tags: ["Agreement modification"] --- # add identification to agreement `POST /payto/agreements/{agreement_uid}/add_identification` ## Request - Base URL: `https://api.sandbox.zeptopayments.com` - URL: `https://api.sandbox.zeptopayments.com/payto/agreements/{agreement_uid}/add_identification` - Auth: HTTP bearer Add the identification models introduced in version 20260901 to an agreement created without them: the initiating client and the debtor's registered payment account. Identification can only be added, never changed, and must match the details already on the agreement. Each identification can be added in a separate request. The debtor payment account must belong to the agreement's initiating client; adding one to an agreement with no initiating client identifies you as the initiator. Supply initiator.client_id for any agreement initiated on behalf of a sub-client; without it the agreement is identified as initiated by you. ## Headers - `Zepto-API-Version` string ## Request body - PaytoAddIdentificationRequest: The identification to add to the agreement. At least one of initiator or debtor must be given; each can be added in a separate request. The debtor payment account must belong to the agreement's initiating client, so for an agreement initiated on behalf of a sub-client add the initiator first or in the same request. Adding a payment account to an agreement with no initiating client identifies you as the initiator. - `initiator` object - `client_id` string, uuid, required: The Zepto client UUID identifying the initiating party. Must resolve to a client registered under the calling account with an active PayTo service, whose ABN/ACN and registered names match the initiator details already on the agreement. Omit only for agreements you initiated on your own behalf. Omitting it for a sub-client's agreement identifies you as the initiator. - `debtor` object - `payment_account_uid` string, required: The uid of a payment account registered via the Counterparties API for the agreement's initiating client, or for yourself when the agreement has no initiating client. Its account identifier must match the debtor account already on the agreement and its party_name must match the debtor ultimate_party_name, ignoring case. For a sub-client's agreement, the payment account must have been created under that sub-client's client_id, and initiator.client_id must be given in the same or an earlier request. ## Response `200` successful - object - `data` PaytoAgreement, required - `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 - `payment_account_uid` string, nullable: The uid of the payment account registered via the Counterparties API, identifying the party behind the nominated account. - `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 - `payment_account_uid` string, nullable: The uid of the payment account registered via the Counterparties API, identifying the party behind the nominated account. - `initiator` object, required: The details of the client this agreement is attributed to, sourced from the registered client record: the sub-client identified by `initiator.client_id` at creation, or your own registered details when the initiator was omitted. Agreements created on earlier API versions may instead carry the initiator details supplied at creation. - `client_id` string, uuid, nullable: The sub-client this agreement is attributed to. `null` when no sub-client was identified at creation. - `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 - `404`: Not Found - `422`: Unprocessable Entity - `500`: Internal Server Error --- [API](https://skmtc.dev/zeptopayments/apis/zepto-payto-api.md) - [All operations](https://skmtc.dev/zeptopayments/apis/zepto-payto-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zeptopayments/apis/zepto-payto-api/revisions/dfc64507b23c?raw)