---
title: "create payment"
method: POST
path: "/payto/payments"
tags: ["Payments"]
---

# create payment

`POST /payto/payments`

## Request body

- PaytoPaymentRequest
  - `uid` string, required — Supplied unique identifier for payment, maximum 64 characters containing only unreserved characters as defined in RFC3986. This identifier ensures payment uniqueness between integrator systems and Zepto.
  - `agreement_uid` string, required — A supplied unique ID
  - `amount` integer, required — Amount in cents.
  - `priority` 'unattended' | 'attended', required — Execution priority of payment. `attended` payments will be prioritised over `unattended` payments.
  - `reference` string, nullable — Free-form text for reconciliation purposes. Typically this field will be shown to both parties on bank statements, however, the debtor can also control this via the agreement. The reference given here takes precedence over the agreeement's reference when it has been set by the debtor.
  - `description` string, nullable — Free-form text for the matching/reconciliation of a transaction. Similar to the reference field, this can be shown on both parties' bank statements. The difference is that this description can be a longer string and banks can show this seperately from the reference.
  - `creditor` object — Who and where the payment is sent to. Optional in request if `creditor` details are present on the agreement.
    - `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.
    - `ultimate_party_name` string, nullable, required — The ultimate creditor name must accurately represent the ultimate creditor party and may be the same as the party_name.
    - `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_reference` string, nullable — A reference to aid the creditor in reconciling the payment
  - `debtor` object — Optional debtor party name overrides. Allows providing custom debtor party names that differ from the agreement. Only available to integrators with extended KYC permissions. Contact Zepto for more information if you would like this feature enabled for your account.
    - `party_name` string — The party name of the debtor
    - `ultimate_party_name` string — The ultimate debtor name for the account. Defaults to `party_name` if not provided.
  - `last_payment` boolean, nullable — This is a required field with agreements that have a payment_terms.type of `balloon`. If `true`, it indicates that this payment is the last payment for the agreement, and should be validated against the last_payment_date and last_payment_amount. No further payments can be made with the agreement once the last payment has been made. This field should be set to `false` for all other payments against a `balloon` agreement, and must be unset for payments on non-`balloon` agreements.
  - `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.
  - `sandbox` object — SANDBOX ONLY: Parameter that allows you to simulate the created payment going through certain scenarios to aid integrators while testing their control flows. Defaults to auto_settle if not given.
    - `simulate` 'auto_settle' | 'requires_investigation' | 'investigate_and_settle' | 'investigate_and_fail' | 'insufficient_funds' | 'creditor_account_type_not_supported' | 'creditor_account_closed' | 'debtor_account_closed' | 'financial_infrastructure_unavailable' | 'debtor_alias_not_found' | 'creditor_alias_not_found' | 'alias_resolution_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` PaytoPayment, required
    - `uid` string, required — Supplied unique identifier for payment, maximum 64 characters containing only unreserved characters as defined in RFC3986. This identifier ensures payment uniqueness between integrator systems and Zepto.
    - `agreement_uid` string, required — A supplied unique ID
    - `source_payto_refund_uid` string, nullable, required — The UID of the PayTo Refund that created this Payment when this Payment is facilitating a refund.
    - `state` 'created' | 'submitting' | 'pending' | 'under_investigation' | 'failed' | 'settled', required — The current state of the payment
    - `reference` string, nullable, required — Free-form text for reconciliation purposes. Typically this field will be shown to both parties on bank statements, however, the debtor can also control this via the agreement. The reference given here takes precedence over the agreeement's reference when it has been set by the debtor.
    - `description` string, nullable, required — Free-form text for the matching/reconciliation of a transaction. Similar to the reference field, this can be shown on both parties' bank statements. The difference is that this description can be a longer string and banks can show this seperately from the reference.
    - `priority` 'unattended' | 'attended', required — Execution priority of payment. `attended` payments will be prioritised over `unattended` payments.
    - `creditor` object, required — Who and where the payment is sent to. Optional in request if `creditor` details are present on the agreement.
      - `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.
      - `ultimate_party_name` string, nullable, required — The ultimate creditor name must accurately represent the ultimate creditor party and may be the same as the party_name.
      - `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_reference` string, nullable, required — A reference to aid the creditor in reconciling the payment
    - `debtor` object, required — Who and where the payment is from
      - `ultimate_party_name` string, required — The ultimate debtor name for the account. Defaults to `party_name` if not provided.
      - `party_name` string, required — The party name of the debtor
      - `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
    - `amount` integer, required — Amount in cents.
    - `last_payment` boolean, nullable, required — This is a required field with agreements that have a payment_terms.type of `balloon`. If `true`, it indicates that this payment is the last payment for the agreement, and should be validated against the last_payment_date and last_payment_amount. No further payments can be made with the agreement once the last payment has been made. This field should be set to `false` for all other payments against a `balloon` agreement, and must be unset for payments on non-`balloon` agreements.
    - `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.
    - `failure` PaytoPaymentFailure, nullable, required — Details about the payment failure, when the state is 'failed'
      - `title` string, required — A short description of the reason or failure
      - `detail` string, required — A longer description of the reason or failure
      - `code` 'ZPPAY24' | 'AB01' | 'AB02' | 'AB03' | 'AB04' | 'AB08' | 'AC02' | 'AC03' | 'AC05' | 'AC06' | 'AC07' | 'AC13' | 'AC14' | 'AC15' | 'AG01' | 'AG03' | 'AG07' | 'AGNT' | 'AM01' | 'AM02' | 'AM03' | 'AM04' | 'AM06' | 'AM09' | 'AM12' | 'AM19' | 'AM21' | 'BE05' | 'BE06' | 'BE08' | 'BE22' | 'CH20' | 'CH21' | 'CURR' | 'CUST' | 'DT02' | 'DT04' | 'ED05' | 'ED06' | 'FF04' | 'FF08' | 'FF10' | 'FF11' | 'FRAD' | 'MD01' | 'MD02' | 'MD20' | 'MS02' | 'MS03' | 'NARR' | 'NAUT' | 'RR02' | 'RR03' | 'RR04' | 'RC05' | 'SL01' | 'SL11' | 'SL12' | 'SL13' | 'SL14' | 'TD03' | 'TM01' | 'AVED' | 'BVSD' | 'MCGP' | 'NACT' | 'ZPUNP01' | 'ZPUNP02' | 'ZPUNP06' | 'ZPUNP07' | 'ZPUNP08' | 'UKNWN', required — A unique identifier for this specific type of reason or failure
      - `retryable` boolean, required — A boolean value indicating whether or not this payment can be retried.
    - `created_at` string, date-time, required
    - `links` object, required
      - `self` string, required — A URL to this payment
      - `agreement` string, required — A URL to the associated agreement
      - `source_refund` string, nullable, required — A URL to the associated source refund

## 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/revisions/6353e9b9af6f/schema)