Pay729-Logo

Documentation
Explore our guides and examples to integrate Paytia.

API overview

The INIT API allows the integration of the Paytia Agent Capture Assist transaction processing web form with a third-party database application, to:

1. Automatically associate payments with related order data such as names, addresses, account or order references, and identify the agent facilitating the payment.
2. Initiate a transaction request, enabling Paytia to process the payment through a payment gateway service.
3. Render the Paytia Agent Capture Assist functions within the third-party application via a Paytia i-frame form.

Process flow

The third-party application must map its internal database fields to the Paytia constant data fields provided in the sample code section. This ensures that the correct information from the host application is sent to Paytia and the Payment gateway, e.g., the total_payment_amount in the host database maps to the Paytia amount field.

Using the Paytia INIT API, the third-party application will first send the initial payment request using the provided JavaScript code snippet (this can be customised to your business's requirements). This post replaces the process of sending data directly to a Payment gateway provider when a bank card payment capture is required.

Note: You will need to ensure that you have an active/saved API key in the Paytia Administration portal.

API key setup URL

https://paytiadirect.paytia.com/merchant/thirdpartyaccess

See the Paytia knowledge base article:

Adding an API Key on Paytia

Ensure the API key Webhook settings are set to Single JSON Data format.




Note: Each Paytia account will have a separate X-API-KEY header field value containing the Paytia API key for that account.

Sample Request with Parameters (using Postman service)

In this request, the third-party application must use agent_id (a required field) as a key to validate the agent, by default Paytia auto-creates agent ID 100. This triggers Paytia to generate the ACA form based on the agent’s session.

Note: Agent IDs will only become active when an agent has received and clicked the welcome email link and set a dedicated password or if your account is only using the API service to drive Paytia then you will require the Paytia ‘Auto user creation’ license which removes a requirement for an agent to have a registered email address).

Note: Paytia will check the license count of active concurrent phone calls (for Phone (MOTO) payments) on your Paytia account (each agent license includes a single concurrent phone call channel license).

If the concurrent call limit reaches the maximum number of purchased concurrent call licenses, Paytia will return an error:

“concurrent license limit reached” upon sending the API payment request.

Access Token for Enhanced Security:

https://accounts.paytia.com/api/api_token_documentation

Header values

AUTHENTICATION PARAMETERS
ADD DOMAIN
JS FILES TO EMBED AGENT CAPTURE ASSIST SCREENS IN YOUR APPLICATION

NOTE: The URL will now open in a new window

JavaScript Example:

JS/PHP Code examples 
 
  $curl = curl_init($url);
  $data = [
    "reference_id" => "euat1000193723-144548351000XXXX",
    "webhook_transaction_url" => "http://b581-117-192-200-120.ngrok.io",
    "webhook_url" => "http://b581-117-192-200-120.ngrok.io",
    "amount" => 1.0,
    "agent_id" => 100,
    "firstname" => "test",
    "lastname" => "test",
    "billingcountry" => "US",
    "billingstate" => 'Erkrath',
    "billinghouseno" => "DHL",
    "billingstreet" => "billingstreet",
    "billingcity" => "billingcity",
    "billingpostcode" => '1234434',
    "merchantcode" => "", // your gateway nickname of paytia
    "billingfirstname" => "billingfirstname",
    "billinglastname" => "billinglastname",
    "shippingcountry" => "US",
    "shippingfirstname" => "shippingfirstname",
    "shippinglastname" => "shippinglastname",
    "shippingcity" => "shippingcity",
    "description" => "description",
    "shippingpostcode" => "111",
    "shippinghouseno" => "122",
    "account_number" => "1111",
    "reference_number" => "1231223",
    "transaction_flag" => "0",
    "web_agent_form" => "1",
    "web_agent_form_lock" => "1",
];
$url = "https://qapartner.pay729.guru:450/api/payment_service";

curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
    
$headers = array(
        "X-API-KEY: //This key is available from the Paytia merchant portal, API secret key sub-menu"
    );
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
$result = curl_exec($curl);
$info = curl_getinfo($curl);
curl_close($curl);
$result_data = json_decode($result);

                                      

     
      <button onclick="callAPIinNewTab()">Call API in new tab</button>  
      const X_API_KEY = "3cf2e9eb2906ac546f0128ec39fa76ae893834d54d5411eff12ae6c28ad21XXXX";
      //This key is available from the Paytia merchant portal, API secret key sub-menu
      const requestAPI = useRequest();

      const data = [{
      reference_id: "euat1000193723-144548351000",
      webhook_transaction_url: "http://b581-117-192-200-120.ngrok.io",
      webhook_url: "http://b581-117-192-200-120.ngrok.io",
      amount: 1.0,
      agent_id: 100,
      firstname: "test",
      lastname: "test",
      billingcountry: "US",
      billingstate: 'Erkrath',
      billinghouseno: "DHL",
      billingstreet: "billingstreet",
      billingcity: "billingcity",
      billingpostcode: '1234434',
      merchantcode: "", // your gateway nickname of paytia
      billingfirstname: "billingfirstname",
      billinglastname: "billinglastname",
      shippingcountry: "US",
      shippingfirstname: "shippingfirstname",
      shippinglastname: "shippinglastname",
      shippingcity: "shippingcity",
      description: "description",
      shippingpostcode: "111",
      shippinghouseno: "122",
      account_number: "1111",
      reference_number: "1231223",
      transaction_flag: "0",
      web_agent_form: "1",
      web_agent_form_lock: "1",
  }];

        function callAPIinNewTab() {

            requestAPI
                .request(data, X_API_KEY)
                .then((response) => {
                    if (response.url) {
                        window.open(response.url)
                    }
                })
                .catch((error) => {
                    alert(error);
                });

        }
Response 

  • response :{
    "httpStatus":true,
    "reference_id":"euat1000193723-14454835100012swx",
    "status":{
        "statusCode":200,
        "statusDescription":"Success"
    },
    "url":"https:\/\/accounts.pay729.guru:450\/thirdparty\/embededurl\Mjk3ODU2JA==\/ZXVhdDEwMDAxOTM3MjMtMTQ0NTQ4MzUxMDAwMTJzd3g="
    }
USING THE RETUREND URL

The host database/web service must extract the URL returned by Paytia from the payment_request (INIT) and embed it into an iframe within the application. When the iframe URL is loaded, Paytia will render the Agent Capture Assist user screen pre-populated with data from the INIT post, similar to the following screenshots of the Agent Capture Assist user screen.

REFERENCE DOCUMENT URLS FOR THE IFRAME API
IFrame API Key Integration:

https://accounts.paytia.com/api/iframe-docs

IFrame API Key Integration with Access Token for Enhanced Security:

https://accounts.paytia.com/api/enhanced-api-key-access-token-docs

Paytia supports multiple payment types and services, from telephone calls to payments via link or QR code, through this one API.

You can use the following fields to enhance your payment post request for different use case scenarios you are developing to solve.

If you have a specific use case scenario you wish to discuss, please contact techsupport@paytia.com

WEBHOOK DETAILS

The Webhook URL is a callback URL where the third party wants to receive notifications of the outcomes of transactions or every stage of the payment/transaction while using the Paytia API. This webhook URL will receive real-time updates and notifications for each step, starting from when the customer and merchant connect to the Paytia platform until the payment/transaction is completed.

For example: A webhook will be sent when Paytia has successfully verified and matched the User/Agent ID typed in using the agent's telephone keypad or passed in a SIP header through a telephony service. This webhook provides real-time updates to confirm that the User/Agent ID has been correctly identified and validated by Paytia.

Response Example
Response 

  • response :{
   "payment_stage":"agent_id",
   "reference_id":"stripe094",
   "agent_id":"100"
  }
Webhook Fields Description
Webhook fields Description
payment_stage The stage will be defined in this field.
For example: payment_stage = agent_id (Matches the User/Agent ID that is either typed in using the agent's telephone keypad or sent in a SIP header through a telephony service.) .
reference_id The reference number you sent to Paytia.
agent_id User/Agent ID.
For example: agent_id = 100 (Unique agent ID)
Additional optional payment_stage values
amount_verify Customer confirm the amount
For example: amount_verify = accepted/rejected
cardnum Customer is ready to enter card number.
pan_digit Card holder is entering PAN digits - each digit received is classed as state value.
For example: pan_digit = XXXXXXXXXXXXXXXX
card_type Card brand returned from BIN check.
For example: card_type = visa
card_verify Last 4 digits of card number returned.
For example: card_verify = 4242
expiry Expiry date capture stage reached.
expiry_digit Digit of MMYY.
For example: expiry_digit = MM YY
cv2 CV2 capture started.
cvv_digit 3 or 4 digits collected depending on card brand Visa and Mastercard vs AMEX.
For example: cvv_digit = XXX
EXCEPTION SCENARIOS IN PAYTIA PAYMENT IVR

The Paytia Payment IVR has some exceptions that need to be handled by third-party developers. Using the webhook notification URL, those exceptions will be passed in the event of an exception being triggered. Third-party developers need to manage these stages when the exception occurs during the payment process. Below is an outline of the exception scenarios:

  1. Amount Rejected by the Customer: During the payment process, the Paytia customer has the choice (Press 2 during the amount confirmation stage) to reject the amount mentioned by the merchant/agent. In this scenario, the payment is not processed, and the IVR reconnects the customer to the merchant/agent to proceed further. If the customer rejects the amount, Paytia sends the following response to the webhook URL of the third party:

    Sample response:

    {"payment_stage":"amount_verify","reference_id":"stripe123","amount_verify":"rejected"}


  2. Card Number Failed: Card number failures in the Paytia payment IVR can occur in three specific scenarios:
    2a. LUHN Check: The telephony IVR system runs a LUHN algorithm to validate the card number. If the card number is identified as invalid, it indicates that the card number entered is invalid. In this scenario, the following response is sent to the webhook URL:

    Sample response:

    {"payment_stage":"card_number","reference_id":"r23sr1111A111593444231a31a12","card_number":"failedluhn"}


    2b. BIN check: After passing the LUHN check, Paytia performs a BIN check algorithm to identify the card number and provider/brand. If the system cannot identify the card brand, it returns information that the card number is invalid. In this scenario, the following webhook response is sent by Paytia:

    Sample response:

    {"payment_stage":"card_number","reference_id":"r23sr1111A111593444231a31a12","card_number":"failedbincheck" }


    2c. Incorrect card entered by the customer: Paytia’s IVR provides a choice to the customer to confirm if the card entered is CORRECT (Press 1) or NOT (press 2). If the customer doesn’t confirm the card is correct the IVR will auto-delete the last provided data and will allow the customer to re-enter the correct card information. In this scenario, the below Webhook response will be sent by Paytia.

    Sample response:

    {"payment_stage":"card_number","reference_id":"r23sr1111A111593444231a31a12","card_number":"failedcustreject"}


  3. Card Expiry Date Failed: The expiry date of the card represents the month and year (MMYY) up to which the card is valid. Paytia IVR also provides the customer with the option to confirm (Press 1) or reject (Press 2) the details entered for the card expiry field. If the customer rejects the entered expiry date, the Paytia IVR prompts the customer to re-enter the correct expiry date. In this scenario, the following webhook response is sent by Paytia showing the stage is reset:

    Sample response:

    {"payment_stage":"card_number","reference_id":"r23sr1111A111593444231a31a12","card_number":"failedcustreject"}

API FIELD VALUES AND CONTROLS
Request Field Mandatory Field Type Description
reference_id Yes String A unique ID values which tracks the transaction post and responses. Please do not have any spaces in the posited value. We support - (hyphen) also as a spacer.
reference_flag No Number Stripe Only
  • 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.
webhook_url Yes 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 No String WEBHOOK TRANSACTION URL FOR PAYMENT STAGE (URL on which we will send payment gateway response to the third party).
webhook_url_token No String If populated Paytia will send the token for the card to this URL.
merchantcode No String Merchantcode is the Gateway ID (If null then default MID will pick up from merchant 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.
amount Yes Decimal A numeric value for the transaction gross charge stated to two decimal places.
agent_name No String Agent Name (alpha format. firstname lastname accepted as one field).
agent_id Yes (required when agent license enabled) 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.
firstname Yes String First name of the card holder.
lastname Yes String Last name of the card holder.
company_name No 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.
countrycode Yes String Two letter country code defined in ISO 3166-1 format.
Note when you send a payment request to Paytia this countrycode should be the registered country of the payees payment card. This field is used in conjunction with the currency_code field to allow you to send different countries that all use the same currency type i.e. USD for United Stated, Ecuador etc.
billingcountry Only required for AVS String Two letter country code defined in ISO 3166-1 format.
billingstate Only required for AVS String Billing state, used in AVS (Address Verification System) check.
billinghouseno Only required for AVS String Billing address line 1, used in AVS check.
billingstreet Only required for AVS String Billing address line 2, used in AVS check.
billingcity Only required for AVS String Billing city.
billingstate No String Billing state/county.
billingpostcode Only required for AVS String Billing postal code, used in AVS check.
billingdescription No String Free text description field for billing information notes.
shippingfirstname (required for AVS) String Shipping address first name.
shippinglastname No String Shipping address last name.
shippinghouseno No String Shipping house number in numeric digits (used for AVS checks).
shippingstreet No String Shipping street.
shippingcity No String Shipping city.
shippingpostcode No String Shipping postcode.
shippingstate No String Shipping state.
shippingcountry No String Two letter country code defined in ISO Format.
shippingdescription No String Free text description field for shipping information notes.
reference_number No String Invoice reference Number (pass to the PSP) for referencing the order.
account_number No String This field is used for accounting purposes.This is also posted onto the associated payment gateway where the payment gateway supports additional payment metadata fields.
currency_code No String Three Letter (If empty/null then the default currency will pick up from the Paytia merchant account according to country the package was activated for).You need to also ensure you set the countrycode field value to the country the peyees payment card is registered to.
transaction_flag Yes Integer Transaction flags allow you to set the transaction request type you wish to facilitate.
  • 0 = Immediate transaction (or you can leave blank, we will handle both)
  • 1 = Tokenisation of the captured card only
  • 2 = Pre-auth (tokenize and process the payment transaction)
  • 3 = Pre-auth only (set a reserve on the card only)
  • 4 = Link to Pay (generate a payment link)
  • 5 = Set a recurring Payment schedule
  • 6 = Bank to bank payments
  • 7 = Rolling reserve (Stripe only)
  • 8 = Checkout payment type (used for “Checkout” in third-party/payment_service and API/payment_service)
reserve_amount Yes Decimal Amount value representing the reservation charge to be held on a payment card e.g. 0.00.
gateway_customer_id No String (Stripe Gateway only) This allows the ID value representing the customer to be passed with the transaction.
Note: This field is exclusively for stripe gateway and transaction flag set to 0.
payment_method No Integer (Stripe Gateway only)
  • 0 = default (pay with existing payment card on customer account)
  • 1 = capture new payment card (pm_ value) to process the payment
  • 2 = pay with an existing payment card on the customer account with payment id (not required)
token_expirydate No Date This field allows an explicit date to be set for a captured card token to be expired. Format YYYY-MM-DD, default set to +7 days. This will valid only for tokenize request, If this value is not pre-set Paytia will use the card holders card expiry date to be the expiration date of the token.
payment_method_detach No Integer 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.
redirect_url No String Once payment complete then it will redirect you on the given url.
voice_country No String Supported values and two alpha character ISO values for countries i.e. GB,US,DE etc.
voice_language No String Supported values are language names in lower case format i.e. english, french, spanish, portugese, german, italian, arabic etc.
pm_id No String pm_id is payment method ID with the provided gateway_customer_id.
order_details Yes(required when transaction_flag = 8) Array This is used for product details, including product name, unit price, quantity, description, and image. These details are passed in an array with indexing for the checkout link.
Example of all checkout parameters:
order_details[0][name] - Sample Product 1
order_details[0][unit_price] - 20.00
order_details[0][quantity] - 2
order_details[0][description] - Description (Optional)
order_details[0][image_url] - product image URL (Optional)
order_details[1][name] - Sample Product 2
order_details[1][unit_price] - 30.00
order_details[1][quantity] - 4
order_details[1][description] - Test Description (Optional)
order_details[1][image_url] - product image URL (Optional)
Additional fields of checkout:
checkout_template_id - checkout_111023(Optional)
shipping_method_name - Next day air (Optional)
shipping_charge - 20.00 (Optional but if you pass shipping_method_name then this is required OR vice-versa)
is_embedded_url - 1(default 0)
order_tax_percent - 4 (Optional)
country_phonecode - GB (Optional)
phone_number - 1234567801 (Optional but if you pass country_phonecode then this is required OR vice-versa)
Note: If transaction_flag = 8, then use web_agent_form is 2.
checkout_template_id No String If a checkout template is used, then the checkout_template_id value of the checkout template should be specified. This checkout template ID can be found in the Paytia merchant portal under the "Checkout Template" menu.
Note: The default template ID is used if this field is empty.
shipping_method_name No String The name of the shipping method for the checkout payment link.
Note:Maximum characters allowed is 20.
shipping_charge No Decimal A numeric value for the shipping charges of checkout to two decimal places.
order_tax_percent No Integer/Decimal A numeric value for the TAX percentage of the checkout, which can be an integer or rounded to two decimal places.
is_embedded_url No Integer Allow only (0 - 1) This setting controls the which type of checkout URL passed in the response.
  • If the passed value is = 0 then passed normal checkout URL in response.
  • If the passed value is = 1 then passed Iframe checkout URL in response.
country_phonecode No String The two-letter country code, defined in ISO 3166-1 format, is used for the checkout phone number country code of the shipping address.
Note: supported values and two alpha character ISO values for countries i.e. GB,US,DE etc.
phone_number No Number The phone number is used for the checkout phone number of the shipping address.
Note: The maximum and minimum length allowed depends on the country of the phone number.
store_expiry No Integer Allow only (0 - 1) This setting controls the store or not card expiry digits.
  • 0 = not store card expiry (default)
  • 1 = store the card expiry
Note: If the passed value is 1, also check whether the store card expiry feature is activated. If the store card expiry feature is enabled in the Settings -> Feature Setting menu on your account, then use the store_expiry value of 1.
Payment links
payment_link_type No Integer Stripe ONLY: This works when transaction_flag is set to 4.
  • 0 = It not used
  • 1 = Reserve payment link
  • 2 = Capture card (TOKEN)
  • 3 = Recurring payment schedule
  • 4 = Capture (TOKEN) then charge an immediate amount
web_agent_form No Integer 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 = t will return Iframe url in response
  • 2 = blank request accepted and will return Iframe url
Note: 0 is active by default
linktopay_url No String This controls the webhook URL the customers payment link will be returned to.
  • 0 = It will send the customers payment link to the URL provided in the linktoapy url field
  • 1 = It will send the customers payment link to the URL provided in the URL the API post came from.
Note: 0 is activated by default
web_agent_form_lock No Integer Lock the fields on the agent form so they cannot be edited
  • 0 = unlocked
  • 1 = locked
link_expiry No Integer Set the link expiry timer (integer value in seconds)
0 default value (link will not expire).
email_send No Integer 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
Note: 0 is the default value
send_receipt No Integer 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
link_type No Integer Enum (0 - 3) This controls Paytia generating a payment link or a QR code for payment
  • 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
Note: 0 is active by default
email_address No String The email address Paytia will use to send the payment link to the customer. 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. Instead, the email will be sent directly to the customer.
custom_logo No Integer 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
Note: 0 will be the default value
saledescription No String This adds a description of goods/service purchased value to the customer payment form.
Note: Max characters = 40
Recurring Payments
start_date Yes Date Supported format is date (YYYY-MM-DD).
For example 2024-05-20 This field provides the starting date of the subscription.
end_date Yes Date Supported format is date (YYYY-MM-DD).
For example 2022-06-16 The date at which this phase of the subscription ends. If set, ‘intervafrequency’ must not be set. Consider that the end date is the last subscription plan start date + the duration of the subscription period. So start date and weekly term would be final start date plus 7 days = end date.
interval Yes String Daily,weekly,monthly.
This provides three intervals for a subscription like: Subscription For - Daily | Weekly | Monthly.
intervalcount Yes 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 Yes Integer 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 Yes Decimal A numeric value for the subscription gross charge stated to two decimal places.
forever No Integer This controls subscription charges will recur until cancelled(No end date)
  • 0 = Recurring have an end date enable
  • 1 = Recurring with no end date
Note: 0 is the default value

For more information or specific use case scenarios, please contact techsupport@paytia.com.