When to use this
Subscription, instalment plan, or recurring invoice. Define interval, start date, amount, and Paytia charges the card on schedule.
Endpoint
POST https://accounts.paytia.com/api/payment_service
Try it
Paste your sandbox key, edit any field, and hit Execute. Nothing is stored — the key travels to the Paytia proxy and the response comes straight back.
Sandbox or live key — nothing is stored.
String: WEBHOOK TRANSACTION URL FOR PAYMENT STAGE (URL on which we will send payment gateway response to the third party)
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)
Decimal: A numeric value for the transaction gross charge stated to two decimal places
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.
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.
String: Paytia required value for Agent Name
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).
String: use for accounting purposes. This is also posted onto the associated payment gateway where the payment gateway supports additional payment metadata fields.
String: First name of the card holder
String: Last name (surname) of the card holder
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.
String: Billing address line 1, used in AVS check.
Two letter country code defined in ISO 3166-1
String: Billing city.
String: Billing street.
String: Billing country/state
String: Billing postal code, used in AVS check
String: Cardholder country code (in two alpha character ISO format)
String: Recipient's first names.
String: Recipient's last name.
String: Billing address line 1, used in AVS check.
String: Shipping city.
String: Shipping Postal code/Zipcode
String: Shipping country/state
String:Two-letter country code defined in ISO 3166-1
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
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)
Numeric: Set the link expiry timer (integer value in seconds) 0 default value (link will not expire)
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
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.
Integer: Enum (0 - 1) Lock the fields on the agent form so they cannot be edited 0 = unlocked 1 = locked
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
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
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
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
String: This adds a description of goods/service purchased value to the customer payment form. Max characters = 100
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
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
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
String: A 'UNQUIQUE' ID value for the transaction. This is passed back with each webhook response so you can track the transaction flow.
Date: Supported format is date (YYYY-MM-DD) example 2022-06-16 This field provides the starting date of the subscription.
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.
String: Daily,weekly,monthly This provides three intervals for a subscription like: Subscription For - Daily | Weekly | Monthly
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.
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.
Numeric: value for the subscription gross charge stated to two decimal places.
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.
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.
String: Billing description. A free text field to add extra information to the billing address.
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
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.
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
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
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
curl --location --request POST 'https://accounts.paytia.com/api/payment_service' \
--header 'X-API-KEY: YOUR_API_KEY' \
--form 'webhook_url_transaction={ADD YOUR WEBHOOK URL HERE}' \
--form 'webhook_url={ADD YOUR WEBHOOK URL HERE}' \
--form 'amount=0.00' \
--form 'reserve_amount=100.00' \
--form 'agent_id=100' \
--form 'agent_name=Agent Name' \
--form 'reference_number=REFERENCE' \
--form 'account_number=account_number' \
--form 'firstname=First' \
--form 'lastname=Last' \
--form 'company_name=company_name' \
--form 'billinghouseno=56' \
--form 'billingcountry=GB' \
--form 'billingcity=billingcity' \
--form 'billingstreet=billingstreet' \
--form 'billingstate=billingstate' \
--form 'billingpostcode=SO15 4ZZ' \
--form 'countrycode=GB' \
--form 'shippingfirstname=shippingfirstname' \
--form 'shippinglastname=shippinglastname' \
--form 'shippinghouseno=10' \
--form 'shippingcity=Southampton' \
--form 'shippingpostcode=SO15 4ZZ' \
--form 'shippingstate=Hampshire' \
--form 'shippingcountry=GB' \
--form 'currency_code=GBP' \
--form 'languagecode=EN' \
--form 'link_expiry=300' \
--form 'linktopay_url=1' \
--form 'web_agent_form=1' \
--form 'web_agent_form_lock=1' \
--form 'email_send=1' \
--form 'email_address=demo@companydomain.com' \
--form 'send_receipt=1' \
--form 'custom_logo=1' \
--form 'saledescription=Description of goods provided for the sale since we are selling you this item today Ready to collect' \
--form 'transaction_flag=4' \
--form 'payment_link_type=3' \
--form 'link_type=0' \
--form 'reference_id={ADD A UNIQUE REFERENCE NUMBER}' \
--form 'start_date=2024-06-20' \
--form 'end_date=2024-08-12' \
--form 'interval=daily' \
--form 'intervalcount=1' \
--form 'subscription_amount=10.00' \
--form 'merchantcode={ADD THE NICKNAME OF YOUR PAYMENT GATEWAY PROFILE HERE}' \
--form 'gateway_customer_id={ADD YOUR STRIPE CUSTOMER CUS_ VALUE HERE}' \
--form 'billingdescription=billingdescription' \
--form 'shippingdescription=shippingdescription' \
--form 'payment_method_detach=0' \
--form 'payment_method=1' \
--form 'store_expiry=1' \
--form 'forever=0'No response yet. Paste your key, tweak the values, and click Execute.
Fields
Full field-by-field reference below. Required vs optional varies by flow — the try-it explorer above starts with sensible defaults.
| Field | Type | Description |
|---|---|---|
| webhook_url_transaction | text | String: WEBHOOK TRANSACTION URL FOR PAYMENT STAGE (URL on which we will send payment gateway response to the third party) |
| 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) |
| amount | text | Decimal: A numeric value for the transaction gross charge stated to two decimal places |
| 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. |
| 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 |
| 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). |
| 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. |
| firstname | text | String: First name of the card holder |
| lastname | text | String: Last name (surname) of the card holder |
| 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. |
| billinghouseno | text | String: Billing address line 1, used in AVS check. |
| billingcountry | text | Two letter country code defined in ISO 3166-1 |
| billingcity | text | String: Billing city. |
| billingstreet | text | String: Billing street. |
| billingstate | text | String: Billing country/state |
| billingpostcode | text | String: Billing postal code, used in AVS check |
| countrycode | text | String: Cardholder country code (in two alpha character ISO format) |
| shippingfirstname | text | String: Recipient's first names. |
| shippinglastname | text | String: Recipient's last name. |
| shippinghouseno | text | String: Billing address line 1, used in AVS check. |
| shippingcity | text | String: Shipping city. |
| shippingpostcode | text | String: Shipping Postal code/Zipcode |
| shippingstate | text | String: Shipping country/state |
| shippingcountry | text | String:Two-letter country code defined in ISO 3166-1 |
| 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 |
| 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) |
| link_expiry | text | Numeric: Set the link expiry timer (integer value in seconds) 0 default value (link will not expire) |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| saledescription | text | String: This adds a description of goods/service purchased value to the customer payment form. Max characters = 100 |
| 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 |
| 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 |
| 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 |
| 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. |
| start_date | text | Date: Supported format is date (YYYY-MM-DD) example 2022-06-16 This field provides the starting date of the subscription. |
| 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. |
| 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. |
| subscription_amount | text | Numeric: value for the subscription gross charge stated to two decimal places. |
| 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. |
| 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. |
| billingdescription | text | String: Billing description. A free text field to add extra information to the billing address. |
| 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 |
| 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. |
| 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 |
| 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 |
| 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 |