100 of 100
| Field | Type | Description |
|---|---|---|
| account_number | text | String: use for accounting purposes. This is also posted onto the associated payment gateway where the payment gateway supports additional payment metadata fields. |
| agent_id | text | Number: The numeric ID number of the agent is up to 6 digits long, required with telephony payments. The length of this field is set by the Paytia platform so please check what your account is set to. By default, Paytia uses three-digit ID numbers for agents allowing 999 agent values to be utilised. |
| agent_name | text | String: Paytia required value for Agent Name |
| amount | text | Decimal: A numeric value for the transaction gross charge stated to two decimal places |
| billingcity | text | String: Billing city. |
| billingcountry | text | Two letter country code defined in ISO 3166-1 |
| billingdescription | text | String: Billing description. A free text field to add extra information to the billing address. |
| billinghouseno | text | String: Billing address line 1, used in AVS check. |
| billingpostcode | text | String: Billing postal code, used in AVS check |
| billingstate | text | String: Billing country/state |
| billingstreet | text | String: Billing street. |
| checkout_template_id | text | Integrer: The ID number of the checkout template you want Paytia to show your customer. These are configured in the Paytia portal administration section > Checkout template Note: used with transaction_flag=8 |
| client_id | text | String: Client ID for API authentication |
| client_secret | text | String: Client secret for API authentication |
| company_name | text | String: Allows a value to be passed for the customer's company name. This is displayed on the payment page the customer views to complete their payment. |
| country_phonecode | text | String: Country Phonecode - allows Paytia to insert the correct country dialling code for you i.e. GB will be inserted as +44 Please ensure you send the value as a two alpha character ISO format e.g. GB Note: used with transaction_flag=8 |
| countrycode | text | String: Cardholder country code (in two alpha character ISO format) |
| currency_code | text | String: Three alpha character values (If null then the default currency will pick up from merchant account according to country set) Currenly currency is controlled only from Operating settings in the merchant portal https://demo.pay729.{domain_extension}/merchant/addon_license_country |
| custom_logo | select | Integer: Enum (0 - 1) This activates adding a custom logo to the transaction payment form customers see when paying. The custom logo is uploaded in the Paytia merchant portal, Settings menu. 0 = disabled 1 = use the custom logo setup on the Paytia merchant portal 0 will be the default value |
| description | text | String: Description of the payment or service being purchased |
| email_address | text | String: Used to provide Paytia with the email address to send the link to the customer on If an email address is present and the send_email value is not set to 0 then Paytia will not return a web_payment_form URL |
| email_send | select | Numeric: This field control if instructing Paytia to send a link as an email to an email address you provide. 0 = disabled 1 = send using Paytia email service 2 = send using Paytia merchant customised email server settings 0 is the default value |
| end_date | text | Date: Supported format is date (YYYY-MM-DD) example 2022-06-16 The date at which this phase of the subscription ends. If set, 'intervafrequency' must not be set. |
| firstname | text | String: First name of the card holder |
| forever | text | Integer: Enum (0 - 1) Default value is 0 which is infinity date/forever end date = off. To set the end date to never ending use 1 |
| gateway_customer_control | text | Briantree payment gateway ONLY 0 = Default (off) 1 = Use gateway_customer_id to create a new customer ID. If a 1 in passed this field, the system will first check if the customer ID passed in the gateway_customer_id field already exists on the payment gateway. If it does, an error message will be returned to prompt the user to enter a different customer ID. If the ID does not exist, a new customer record will be created on the payment gateway using the ID value specified customer in the gateway_customer_id field. |
| gateway_customer_id | text | String: Stripe and Braintree ONLY This field control allows you to post the cus_ value (Stripe), or the CustomerID or a new ID value (Braintree)., representing the customer record the transaction should be placed for. |
| interval | select | String: Daily,weekly,monthly This provides three intervals for a subscription like: Subscription For - Daily | Weekly | Monthly |
| intervalcount | text | Integer: The number of intervals (specified in the interval attribute) between subscription billings. For Example: Interval=month and interval_count=3 bills every 3 months. |
| intervalfrequency | text | Integer: representing the multiplier applied to the price interval. For Example - intervalfrequency=2 applied to a price with interval-month and intervalcount=3 results in a phase of duration 2*3 months = 6 months. If set, end_date must not be set. |
| is_embedded_url | select | Integrer: Is Embedded URL - Used when posting to the Paytia URL endpoint api/payment_service. If you send value=1 in the is_embedded_url field Paytia will return the payment checkout page as an Iframe URL in the post response. Note: used with transaction_flag=8 |
| languagecode | text | String: ISO country code (2 alpha characters) (If null then the default language will be picked up from merchant country code set on the Paytia admin portal) |
| lastname | text | String: Last name (surname) of the card holder |
| link_expiry | text | Numeric: Set the link expiry timer (integer value in seconds) 0 default value (link will not expire) |
| link_type | select | Integer: Enum (0 - 3) This controls Paytia generating a payment link or a QR code. 0 = Payment link generated 1 = QR code generated (email_address is required in order for the generated QR code to be sent to a customer) 2 = QR code is returned in the webhook_url 0 is active by default |
| linktopay_url | select | Integer: Enum (0 - 1) This controls linktopay url for payment 0 = will send linktoapy url and webhook response to webhook url 1 = return linktopay_url in response 0 is active by default |
| merchantcode | text | String: Gateway ID (If null, then Paytia will default to the default payment gateway profile (MID) from the Paytia account) Note: On the Paytia admin portal, this field is tied to the payment gateway nickname value. (Portal > Manage gateway section, edit Payment Gateway). If no match is found between the received merchantcode API post value and the portal gateway nickname, then Paytia will default to using the details saved in the default (primary) gateway entry. |
| mode | text | String: The value to be sent should be "bank". |
| order_details[0][description] | text | String: Description - (Optional) of the first product you have sold Note: used with transaction_flag=8 Note: ingrament the [0] value inside the [ ] field value brackets each additional product you post |
| order_details[0][image_url] | text | Product image - A URL to show the product as an image in the payment page (Optional) Note: used with transaction_flag=8 |
| order_details[0][name] | text | String: Product name - of the first product you have sold Note: used with transaction_flag=8 Note: increment the [0] value inside the [ ] field value brackets each additional product you post |
| order_details[0][quantity] | text | Integer: Quanity sold (using whole numbers) Note: used with transaction_flag=8 Note: increment the [0] value inside the [ ] field value brackets each additional product you post |
| order_details[0][unit_price] | text | Decimal: Price - of the first product you have sold Note: used with transaction_flag=8 Note: increment the [0] value inside the [ ] field value brackets each additional product you post |
| order_details[1][description] | text | String: Description - (Optional) of the first product you have sold Note: used with transaction_flag=8 Note: increment the [1] value inside the [ ] field value brackets each additional product you post |
| order_details[1][image_url] | text | Product image - A URL to show the product as an image in the payment page (Optional) Note: used with transaction_flag=8 |
| order_details[1][name] | text | String: Product name - of the first product you have sold Note: used with transaction_flag=8 Note: increment the [0] value inside the [ ] field value brackets each additional product you post |
| order_details[1][quantity] | text | Integer: Quanity sold (using whole numbers) Note: used with transaction_flag=8 Note: increment the [1] value inside the [ ] field value brackets each additional product you post |
| order_details[1][unit_price] | text | Decimal: Price - of the first product you have sold Note: used with transaction_flag=8 Note: increment the [0] value inside the [ ] field value brackets each additional product you post |
| order_details[2][description] | text | String: Description - (Optional) of the first product you have sold Note: used with transaction_flag=8 Note: ingrament the [1] value inside the [ ] field value brackets each additional product you post |
| order_details[2][image_url] | text | Product image - A URL to show the product as an image in the payment page (Optional) Note: used with transaction_flag=8 Note: increment the [1] value inside the [ ] field value brackets each additional product you post |
| order_details[2][name] | text | String: Product name - of the next product you have sold Note: used with transaction_flag=8 Note: increment the [1] value inside the [ ] field value brackets each additional product you post |
| order_details[2][quantity] | text | Integer: Quanity sold (using whole numbers) Note: used with transaction_flag=8 Note: increment the [1] value inside the [ ] field value brackets each additional product you post |
| order_details[2][unit_price] | text | Decimal: Price - of the first product you have sold Note: used with transaction_flag=8 Note: increment the [1] value inside the [ ] field value brackets each additional product you post |
| order_details[3][description] | text | String: Description - (Optional) of the first product you have sold Note: used with transaction_flag=8 Note: increment the [1] value inside the [ ] field value brackets each additional product you post |
| order_details[3][image_url] | text | Product image - A URL to show the product as an image in the payment page (Optional) Note: used with transaction_flag=8 |
| order_details[3][name] | text | String: Product name - of the first product you have sold Note: used with transaction_flag=8 Note: ingrament the [0] value inside the [ ] field value brackets each additional product you post |
| order_details[3][quantity] | text | Integer: Quanity sold (using whole numbers) Note: used with transaction_flag=8 Note: increment the [1] value inside the [ ] field value brackets each additional product you post |
| order_details[3][unit_price] | text | Decimal: Price - of the first product you have sold Note: used with transaction_flag=8 Note: ingrament the [0] value inside the [ ] field value brackets each additional product you post |
| order_tax_percent | text | Decimal: Order Tax Percent - Specifies the percentage of sales tax to be applied to the order Note: used with transaction_flag=8 |
| payment_link_type | select | Stripe ONLY: This works when transaction_flag is set to 4 Action - 0 = not used 1 = Reserve payment link 2 = Capture card (TOKEN) 3 = Recurring payment schedule 4 = Capture (TOKEN) then charge an immediate amount |
| payment_link_via | select | Integrer: Contols the sending of the message format Email vs SMS message delviery. 1 is the default setting 1 = Send email message format 2 = Send SMS message format |
| payment_method | select | Stripe and Braintree Gateways only 0 = default (pay with existing payment card on customer account) 1 = capture new payment card (pm_ value (Stripe) or customer ID (Braintree)) to process the payment |
| payment_method_detach | select | Integer: Enum - Stripe ONLY (0 - 1) This setting controls the storage of the payment card after the payment has been completed. You will use this with Stripe if you want to delete vs retain the card on file. If the passed value is = 0 then the payment card is retained after the transaction completes. If the value passed is = 1 then the payment card is removed after completing the transaction. |
| phone_number | text | String: PhoneNumber - allows the passing of the customers preffered telephone number excluding the country code or the leading Zero digit. This will be shown with the country code you sent in. Note: used with transaction_flag=8 |
| redirect_url | text | String: This is the website URL paytia should redirect customers following the transaction being completed. |
| reference_flag | select | Integer: This value is used to switch the value passed in reference_number and reference_id so that 0 = show the reference_id field in the Paytia ACA user webform screen and send to reference_id to the PSP as the reference number field. 1 = show the reference_number value in the ACA screen and pass both reference_id and reference number to PSP. |
| reference_id | text | String: A 'UNQUIQUE' ID value for the transaction. This is passed back with each webhook response so you can track the transaction flow. |
| reference_number | text | String: Invoice Reference Number (this field is mapped and passed to the final payment gateway connector in ) for referencing the order. Note: on some payment gateways this is unique field meaning the payment gateway will reject repeat values that are not unique). |
| reserve_amount | text | Decimal: A numeric value for the transaction gross charge stated to two decimal places. This is used to send a reserve (secondary) amount. If transaction_flag = 2 (Reserve/charge), reserve_amount can be set as amount to be reserved on a payment card, and the amount field will be the amount that needs to be charged immediately. If the transaction_flag = 3 (Reserve), the reserve_amountvalue only will be reserved on the card for payment capture later in a payment flow. |
| saledescription | text | String: This adds a description of goods/service purchased value to the customer payment form. Max characters = 100 |
| secure_code | select | Integrer: Secure code generates a unique 4 digit numeric code agents share with customs who can then verify the message received's trust by matchin gthe secure code value received. 0 = disabled 1 = generate and send secure code |
| send_receipt | select | Integer: send_receipt requires a licence called "Receipt to the customer" to be active on your account. 0 = off (by default) 1 = on / send email receipt to the email_address value passed |
| shipping_charge | text | Decimal: Shipping Order Charge - Allow you to set the cost for shipping the order. If you include the value shipping_charges then Paytia will include these charges on the template. By default Paytia will otherwise display 'Free' on the checkout link. Note: used with transaction_flag=8 |
| shipping_method_name | text | String: Shipping Method Name - Indicates the name or type of shipping method chosen for the transaction. Note: used with transaction_flag=8 |
| shippingcity | text | String: Shipping city. |
| shippingcountry | text | String:Two-letter country code defined in ISO 3166-1 |
| shippingdescription | text | String: shipping description. free text field to add extra information to the billing address. This adds a description of goods/service purchased value to the customer payment form Max characters = 40 |
| shippingfirstname | text | String: Recipient's first names. |
| shippinghouseno | text | String: Billing address line 1, used in AVS check. |
| shippinglastname | text | String: Recipient's last name. |
| shippingpostcode | text | String: Shipping Postal code/Zipcode |
| shippingstate | text | String: Shipping country/state |
| sms_send | select | Integrer: Turns on SMS sending 0 = Disabled (do not send SMS) 1 = send SMS message This is the default setting. 1 = Send SMS message |
| start_date | text | Date: Supported format is date (YYYY-MM-DD) example 2022-06-16 This field provides the starting date of the subscription. |
| store_expiry | select | Integer: Enum (0 - 1) This controls Paytia capturing, storing, and returning the card expiry date after a telephone (MOTO) transactione. 0 = Do not store expiry date 1 = Capture, store and return the expiry date in te transaction outcome webhook 0 is active by default |
| sub_sched_id | text | Stripe Gateway Only Enter the subscription reference number that was returned when the payment schedule was set up We are expecting a value starting sub_sched_ or sub_ |
| subscription_amount | text | Numeric: value for the subscription gross charge stated to two decimal places. |
| token_id | text | String: The token that was returned after a successful capture form is stored. |
| token_mode | text | String: The available values for this field are: create: for later use, allows the post of sensitive data to Paytia for encryption, token generation, and storage. retrieve: allows retrieval of a token in case the webhook return process failed. remove: allows requesting the deletion of a customer's bank account details from the Paytia service. |
| transaction_flag | select | Integer: Enum (0 - 9) 0 = Phone - None required = immediate charge 1 = Phone - Capture - Tokenisation only (ensure you send 0.00 in amount) 2 = Phone - Pre-auth (Capture to pre-auth (reserve) and take an immediate payment) 3 = Phone - Pre-auth only (set a reserve on a card and return a transaction token) 4 = Link to Pay 5 = Phone - Recurring payment 6 = Bank to bank payments (to be added) 7 = Phone - Rolling reserve (Stripe only) 8 = Checkout payment type (used for "Checkout" in thirdparty/payment_service and API/payment_service) 9 = Bank outbound payment processing |
| transaction_id | text | String: Required field cus_value (Stripe) or thiswill be the unique transaction ID of your account gateway in the case of type= reserve_settle or remove. If the type is set to store_payment then this will be the token ID of transaction. |
| type | select | String value - Required field - Allows you to complete a validation, Reserve, and Capture payment type Supported values remove - this removes a Reserve Pre-Auth set on a card reserve_settle - Completes a Reserve Pre-Auth charge for the amount sent. Works with the Stripe pi_ value returned in the transaction post API. store_payment - works with a (Stripe) pm_ value. Card on file payment processed. cancel - cancels a subscription update - updates a subscription |
| unlock_fields | text | String: This control allows you to specify the names of the webform fields you wish to remain unlocked on the ACA web form. Add each field name in a comma-delimited format e.g. voice_country,voice_language |
| voice_country | text | String: ISO country code (2 alpha characters) (If null then the default language will be picked up from merchant country code set on the Paytia admin portal) |
| voice_language | text | String: This allows you to set the language by setting a language name i.e. french |
| web _agent_form | text | Set this value to 3 |
| web_agent_form | select | Integer: Enum (0 - 2)This controls Paytia returning the form the agent will see showing/allowing the payment data to be captured 0 = It will not return Iframe url 1 = It will return Iframe url in response 2 = blank request accepted and will return Iframe url 0 is active by default Note: Set agent form to 0 if using payment links with a bot service where no agent is involved. |
| web_agent_form_lock | select | Integer: Enum (0 - 1) Lock the fields on the agent form so they cannot be edited 0 = unlocked 1 = locked |
| webhook_url | text | String: WEBHOOK URL FOR PAYMENT STAGE (Specify the call back URL you want to receive webhook notifications to) (In the case of linktopay: this will be the linktopay_url you want the Link to pay response to be sent) |
| webhook_url_transaction | text | String: WEBHOOK TRANSACTION URL FOR PAYMENT STAGE (URL on which we will send payment gateway response to the third party) |
Using the reference
Individual flow pages list only the fields they use. This page lists every field Paytia recognises — useful when you're tracing a response, cross-checking a field name, or building internal tooling that speaks to the API.
Types are indicative: most fields are passed as form strings, so "Decimal" means a numeric string formatted to two decimal places, not a typed float. "Select" fields have a closed enum — see the relevant flow page for the allowed values.