Pay729-Logo

Documentation
Explore our guides and examples to integrate Paytia.

API overview

The INIT API enables the Paytia Secure Virtual Terminal to be integrated with a third-party database application in order that:

1. Payments can be automatically associated with related order data — for example, names, addresses, account or order references and we capture which agent who is facilitating a payment.

2. Initiating a transaction request so Paytia processes the payment through a payment gateway service.

3. Rendering the Paytia Agent Capture Assist functions within the third-party application through a Paytia i-frame form.

Process flow

The third-party application will need to hold a mapping between its internal database fields and the Paytia const data fields listed in the sample code provided. This allows the correct information from the host application to be sent to Paytia and onto the Payment gateway i.e. total_payment_amount on the host database maps to the Paytia amount field.

Using the INIT API, the third-party application will first send the initial request for payment by using below JS code which is provided in snippet.This will simulate the process used to send data to the Payment provider when a bank card payment is required to be taken.

On the Paytia Administration portal you will need to ensure you have an active/saved API key.

API key setup URL

https://paytiadirect.pay729.net/merchant/thirdpartyaccess

See the Paytia knowledge base article -

https://www.paytia.com/en/help/adding-an-api-key-on-paytia

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




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

Generate access token URL

https://paytiadirect.pay729.net/merchant/thirdpartyaccess

See the Paytia knowledge base article -

https://www.paytia.com/en/help/generating-access-token-on-paytia



Note: Each Paytia account you use will have a separate ACCESS-TOKEN field value containing the Paytia client tokens for that account.

Below is the sample request with parameters : (using the postman service).

In this request, the third-party application needs to use agent_id (required field) as a key to validate the agent which in-turn will trigger Paytia to generate the ACA form on the basis of the agent’s session (agent ID’s setup become active when an agent has received and clicked the welcome email link and have set a dedicated password).

Note: Paytia will check a licence count of active concurrent phone calls (for MOTO payments) available on your Paytia account (each agent licences includes a single concurrent phone call licence).

If the call limit reaches the maximum limit of the purchased concurrent call licenses then upon sending the API payment request (below) Paytia will return an error as “concurrent license limit reached”.

Header values

AUTHENTICATION PARAMETERS
ADD DOMAIN
This JS file include
Get Access Token (expires in 1 hour) and Refresh Token 
  
                                                                        
  $url = "https://accounts.pay729.guru:449/api/authorize";
  $curl = curl_init($url);
  $data = [
    "client_id" => "string", //This key is available from the Paytia merchant portal, API secret key sub-menu > Generate tokens button"
    "client_secret" => "string", //This key is available from the Paytia merchant portal, API secret key sub-menu > Generate tokens button"
  ];
  $curl = curl_init($url);

  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);

                                      

      
      const X_API_KEY = "3cf2e9eb2906ac546f0128ec39fa76ae893834d54d5411eff12ae6c28ad21XXXX";
      //This key is available from the Paytia merchant portal, API secret key sub-menu
      var REFRESH_TOKEN = '';
        const authorizeData = {
            client_id: "eNFE2Hnuy5qi185bhHhRGoux0Uz7tZ2A5vIvsR+fXXXX", //This key is available from the Paytia merchant portal, API secret key sub-menu > Generate tokens button"
            client_secret: "P4KsPBIg6eNfl3Bs7VUcHp+3bwoEN49CCmsgahUBXXXX", //This key is available from the Paytia merchant portal, API secret key sub-menu > Generate tokens button"
        }
        const getRefreshToken = () => fetch('https://accounts.pay729.guru:449/api/authorize', {
            method: 'POST',
            headers: {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'X-API-KEY': X_API_KEY
            },
            body: JSON.stringify(authorizeData)
        })
        .then((response) => {
            return response.json().then((data) => {
                ACCESS_TOKEN = data.access_token;
                REFRESH_TOKEN = data.refresh_token;
                return true;
            })
        });
        getRefreshToken();
Response 

  • response :{
    "httpStatus":true,
    "access_token":"lbJwVHcUkEMoUVQfjym3rj34OOQcCj+es/3dJt6gXXXX",
    "refresh_token":"safjfsdfghjfoUVQfjym3rj34OOQcCj+es/3dJt6gXXXX",
    "expire_time":"2024-03-12 11:27:27",
    "status":{
        "statusCode":200,
        "statusDescription":"Success"
    }
    }
Get Access Token if Expired 
                                                                          
  $url = "https://accounts.pay729.guru:449/api/refresh_token";
  $curl = curl_init($url);
  $data = [
    "client_id" => "string", //This key is available from the Paytia merchant portal, API secret key sub-menu > Generate tokens button"
    "client_secret" => "string", //This key is available from the Paytia merchant portal, API secret key sub-menu > Generate tokens button"
    "refresh_token" => "string", //previous curl authorize response includes refresh_token 
  ];
  $curl = curl_init($url);

  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);

                                      

       
      const X_API_KEY = "3cf2e9eb2906ac546f0128ec39fa76ae893834d54d5411eff12ae6c28ad21XXXX";
      //This key is available from the Paytia merchant portal, API secret key sub-menu
      var ACCESS_TOKEN = '';
        const refreshTokenData = {
            client_id: "eNFE2Hnuy5qi185bhHhRGoux0Uz7tZ2A5vIvsR+fXXXX", //This key is available from the Paytia merchant portal, API secret key sub-menu > Generate tokens button"
            client_secret: "P4KsPBIg6eNfl3Bs7VUcHp+3bwoEN49CCmsgahUBXXXX", //This key is available from the Paytia merchant portal, API secret key sub-menu > Generate tokens button"
            refresh_token: REFRESH_TOKEN //previous js function getRefreshToken includes this value in response
        };
        const getAccessToken = () => fetch('https://accounts.pay729.guru:449/api/refresh_token', {
            method: 'POST',
            headers: {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'X-API-KEY': X_API_KEY
            },
            body: JSON.stringify(refreshTokenData)
        })
        .then((response) => {
            return response.json().then((data) => {
                ACCESS_TOKEN = data.access_token;
                return true;
            })
        });
        getAccessToken();
Response 

  • response :{
    "httpStatus":true,
    "access_token":"lbJwVHcUkEMoUVQfjym3rj34OOQcCj+es/3dJt6gXXXX",
    "refresh_token":"safjfsdfghjfoUVQfjym3rj34OOQcCj+es/3dJt6gXXXX",
    "expire_time":"2024-03-12 11:27:27",
    "status":{
        "statusCode":200,
        "statusDescription":"Success"
    }
    }
NOTE: THE URL WILL NOW OPEN IN NEW WINDOW 
  
                                                                        
  $url = "https://accounts.pay729.guru:449/api/authorize";
  $curl = curl_init($url);
  $data = [
    "client_id" => "string", //This key is available from the Paytia merchant portal, API secret key sub-menu > Generate tokens button"
    "client_secret" => "string", //This key is available from the Paytia merchant portal, API secret key sub-menu > Generate tokens button"
  ];
  $curl = curl_init($url);

  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);
  
  $url = "https://accounts.pay729.guru:449/api/refresh_token";
  $curl = curl_init($url);
  $data = [
    "client_id" => "string", //This key is available from the Paytia merchant portal, API secret key sub-menu > Generate tokens button"
    "client_secret" => "string", //This key is available from the Paytia merchant portal, API secret key sub-menu > Generate tokens button"
    "refresh_token" => "string", //previous curl authorize response includes refresh_token 
  ];
  $curl = curl_init($url);

  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);
  
  $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://accounts.pay729.guru:449/api/payment_service";
$curl = curl_init($url);

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"
    "ACCESS-TOKEN: //previous curl refresh_token includes this value in response
);
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, ACCESS_TOKEN) //previous js function getAccessToken includes this value in response
                .then((response) => {
                  console.log("Response:", response);
                  if (response.url) {
                        const iframe = document.createElement('iframe');
                        iframe.src = response.url;
                        iframe.width = '400';
                        iframe.height = '400';
                        iframe.frameborder = '0'; // Hide iframe border
                        iframe.allowfullscreen = true; // Enable fullscreen mode
                        // Add the iframe to the body or a specific container
                        document.body.appendChild(iframe);
                    }
                })
                .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 will need to 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 that shown on the following screenshots of Agent Capture Assist.

For reference Postman Collection is below

Enhanced_security_X_API_KEY.postman_collection

Paytia support 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 sue case scenarios you are developing to solve.

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

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.
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
Yes Decimal
firstname Yes String First name of the card holder
lastname Yes String Last name of the card holder
company_name no Decimal 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 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.
billingdescription No String Free text description field for billing information notes.
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 String 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
gateway_customer_id No String Stripe Gateway onlyThis 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
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 Payment_method_detach field controls card on file retention. If you wish the captured card to be deleted after it has been used for a payment then use this switch.
  • 0 = retain the card
  • 1 = remove the card
redirect_url No String Once payment complete then itl redirect you on the given url
Payment links
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 = It will return Iframe url in response
  • 2 = blank request accepted and will return Iframe url 0 is active by default
linktopay_url No String This controls the webhook URL the customers payment link will be returned to.
  • 0 = will send the customers payment link to the URL provided in the linktoapy url field
  • 1 = will send the customers payment link to the URL provided in the URL the API post came from. 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 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 This controls Paytia generating a link or a QR code for payment
  • 0 = Link generated
  • 1 = QR code (email_address is required, will send QRcode on mail)
  • 2 = Link with QR code 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 0 will be the default value
saledescription No String This adds a description of goods/service purchased value to the customer payment form Max characters = 40
Recurring Payments
start_date Yes Date Supported format is date (YYYY-MM-DD) For example 2022-06-16 This field provides the starting date of the subscription.
end_date Yes 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. 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.