When to use this
Send the customer to a Paytia-hosted checkout page, then back to your site on completion. Webhook confirms the result out of band.
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
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.
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.
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)
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
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 - 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
String: A 'UNQUIQUE' ID value for the transaction. This is passed back with each webhook response so you can track the transaction flow.
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
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
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
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
Product image - A URL to show the product as an image in the payment page (Optional) Note: used with transaction_flag=8
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
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
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
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
Product image - A URL to show the product as an image in the payment page (Optional) Note: used with transaction_flag=8
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
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
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
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
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
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
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
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
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
Product image - A URL to show the product as an image in the payment page (Optional) Note: used with transaction_flag=8
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
String: Shipping Method Name - Indicates the name or type of shipping method chosen for the transaction. Note: used with transaction_flag=8
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
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
Decimal: Order Tax Percent - Specifies the percentage of sales tax to be applied to the order Note: used with transaction_flag=8
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
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
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 'agent_id=100' \
--form 'agent_name=Agent Name' \
--form 'reference_number=REF-CK-01' \
--form 'account_number=ACC-CK-01' \
--form 'reserve_amount=0.00' \
--form 'firstname=Firstname' \
--form 'lastname=Lastname' \
--form 'company_name=company_name' \
--form 'billinghouseno=56' \
--form 'billingcountry=GB' \
--form 'billingcity=billingcity' \
--form 'billingstreet=billingstreet' \
--form 'billingstate=billingstate' \
--form 'billingpostcode=SO15 4JS' \
--form 'countrycode=GB' \
--form 'shippingfirstname=shippingfirstname' \
--form 'shippinglastname=shippinglastname' \
--form 'shippinghouseno=10' \
--form 'shippingcity=Southampton' \
--form 'shippingpostcode=SO15 4JS' \
--form 'shippingstate=Hampshire' \
--form 'shippingcountry=GB' \
--form 'currency_code=GBP' \
--form 'languagecode=EN' \
--form 'store_expiry=1' \
--form 'link_expiry=300' \
--form 'linktopay_url=1' \
--form 'transaction_flag=8' \
--form 'reference_id={ADD A UNIQUE REFERENCE NUMBER}' \
--form 'order_details[0][name]=Sample Product 1' \
--form 'order_details[0][description]=Description of sample product 1' \
--form 'order_details[0][unit_price]=1.00' \
--form 'order_details[0][quantity]=1' \
--form 'order_details[0][image_url]=https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQWxwIaOCpuHNN5YhT9RhflA1SBukHCTi0V0w&usqp=CAU' \
--form 'order_details[1][name]=Sample product 2' \
--form 'order_details[1][description]=Description of sample product 2' \
--form 'order_details[1][unit_price]=2.00' \
--form 'order_details[1][quantity]=2' \
--form 'order_details[1][image_url]=https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQtlSOCaCsXyKPcvNeg4ri5kZmyUEKqUzVoDw&usqp=CAU' \
--form 'order_details[2][name]=Sample Product 3' \
--form 'order_details[2][description]=Description of sample product 3' \
--form 'order_details[2][unit_price]=3.00' \
--form 'order_details[2][quantity]=3' \
--form 'order_details[2][image_url]=https://images.pexels.com/photos/821651/pexels-photo-821651.jpeg?auto=compress&cs=tinysrgb&w=1200' \
--form 'order_details[3][name]=Sample product 4' \
--form 'order_details[3][description]=Description of sample product 4' \
--form 'order_details[3][unit_price]=4.00' \
--form 'order_details[3][quantity]=4' \
--form 'order_details[3][image_url]=https://images.pexels.com/photos/335257/pexels-photo-335257.jpeg?auto=compress&cs=tinysrgb&w=1200' \
--form 'checkout_template_id=checkout_3237276' \
--form 'shipping_method_name=FED-EX' \
--form 'shipping_charge=10.00' \
--form 'is_embedded_url=1' \
--form 'order_tax_percent=20.00' \
--form 'country_phonecode=GB' \
--form 'phone_number=1111111111111'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 |
| 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. |
| 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. |
| 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) |
| 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 |
| 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 |
| 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 |
| 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. |
| 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][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][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[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][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][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][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][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][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[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][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][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[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][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[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][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][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_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][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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |