Site - SID - Payments

Payment Options

soap/feeapi

FeeAPI provides a way to get a list of payment methods and information for a given sid. These request should only be used server-to-server as they use the rcode.

FeeAPI will give you the cart converted to the currency of the payment method and the list of payment methods and the fields. Fields section in the response will have the input requirement for sending the transaction to the gateway.

FeeAPI differs from RawFeeAPI in that it requires the cart details. This can be very useful if you want to display the cart details to the customer in the currency that they will be paying.

POST https://uat.txshield.payshield.ai/soap/feeapi.php

Request Body

Name	Type	Description
amount_coupon*	String	Coupon amount
(numerical index)*	Array	Contains information about one item in the cart (Repeat until all cart items are listed)
addfee	Boolean	This will add the processing fees on top of the amount.
amount_shipping*	String	Shipping amount
country*	String	Country of the user - will provide the list of payments available for that country
items*	Array	Contains the cart items
amount_purchase*	String	Total amount of purchase
summary*	Array	Contains a summary of cart contents
fxrate_posted*	String	Rate used for conversion of cart currency to gw currency. Enter Buy cart currency Sell Gw currency
sid*	String	Site id (unique identifier for the web site)
currency_code*	String	3 digit currency code of the cart currency
rcode*	String	Site RCODE
cart*	Array	Information about the purchase items. This is only compulsory for feeapi, do not sent the cart to rawfeeapi.
amount_tax*	String	tax amount
item_desc*	String	Item description
item_no*	String	Article number
amount_unit*	String	Unit price amount (without commas and only 2 decimals places)
quantity*	String	Quantity of the item
name*	String	Category, can be used freely

200: OK

[{
    "mxsid":"188",
    "payby":"visa",
    "title":"Visa",
    "display_title":"Test",
    "description":"\u00a0",
    "transfertime":null,
    "transferlimit":null,
    "currency_code":"USD",
    "currency_symbol":"$",
    "image":"https://txprocess.uat.ipayoptions.com/secure/dbfile.php?type=pmimg&id=1&nocache=575a36bb51db4",
    "fee":12.63,
    "cart": {
        "summary": {
            "quantity":"1",
            "amount_purchase":16.36,
            "amount_shipping":0,
            "amount_tax":0,
            "currency_code":"USD",
            "amount_shipping_posted":null,
            "amount_tax_posted":null,
            "amount_coupon_posted":null,
            "amount_coupon":0,
            "currency_symbol":"$",
            "fxrate":0.85846649
        },
        "items": [{
            "quantity":"1",
            "name":"Economy single",
            "item_no":"e1234",
            "item_desc":"Single Economy ticket LHR - ZAR",
            "amount_unit":3.73,
            "amount_unit_posted":"3.20"
        },
        {
            "name":"Processing Fees",
            "quantity":1,
            "amount_unit_posted":10.84,
            "amount_unit":12.63,
            "item_no":"",
            "item_desc":"Processing Fees"
        }]
    },
    "fields":
    {
        "card_name":
        {
            "description":"",
            "type":"text",
            "title":"Card Holder Name",
            "required":1
        },
        "card_no":
        {
            "description":"No spaces or dashes allowed",
            "type":"text",
            "title":"Card Number",
            "required":1,
            "pattern":"[0-9] { 13,19 }"
        },
        "card_cvv":
        {
            "description":"CVV",
            "type":"text",
            "title":"CVV",
            "required":1,
            "pattern":"[0-9]{3,4}"
        },
        "card_exp_month":
        {
            "description":"",
            "type":"select",
            "options":["01","02","03","04","05","06","07","08","09","10","11","12"],
            "title":"Card Expiry Month"
        },
        "card_exp_year":
        {
            "description":"",
            "type":"select",
            "options":[2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027],
            "title":"Card Expiry Year"
        }
    }
}]

soap/rawfeeapi.php

RawFeeAPI provides a way to get a list of payment methods and information for a given sid. These request should only be used server-to-server as they use the rcode.

RawFeeAPI will give you the list of payment methods and the fields. Fields section in the response will have the input requirement for sending the transaction to the gateway.

RawFeeAPI differs from FeeAPI in that it does not need the cart details.

POST https://uat.txshield.payshield.ai/soap/rawfeeapi.php

Request Body

Name	Type	Description
sid*	String	Site id (unique identifier for the web site)
currency*	String	3 digit currency code. cart currency
country*	String	Country of the user - will provide the list of payments available for that country
rcode*	String	Site RCODE

200: OK

[
  {
    "mxsid": "10146",
    "payby": "bpay",
    "title": "BPay",
    "display_title": null,
    "description": null,
    "transfertime": null,
    "transferlimit": null,
    "currency_code": "AUD",
    "currency_symbol": "$",
    "image": "--Logo URL--",
    "fee": {
      "srccode": "AUD",
      "destcode": "USD",
      "rate": 0.96801106010318,
      "effectivedate": "2011-04-04",   
      "flatfee": 3,
      "mdr": 1
    },
    "fields": {
      "card_no": {
        "description": "",
        "type": "hidden",
        "value": "70720297711",
        "title": ""
      },
      "description": {
        "description": "",
        "type": "span",
        "value": "--HTML String--"
      },
    }
  }
]

{sid}/getpaymentoptions

retrieves a collection of payment options that are available for this sid.

{sid}/getpaymentoptionsfrombin

Lookup payment option and convert the cart currency based on your BIN. This is for credit card only.

POSThttps://uat.txshield.payshield.ai/api/v1/index.php/{sid}/getpaymentoptionfrombin

Path parameters

sid*integer

ID of site

Body

multipart/form-data

hash*string

md5 hash of sid+timestamp+amounttotal+currency+rcode e.g. md5('22'.'1234568995265421'.'17.00'.'USD'.'222b6c')

timestamp*string

timestamp value used in the hash e.g. 1234568995265421

BIN*string

First 6 digits of the credit card

addFeeboolean

This will add the processing fees on top of the amount.

item_quantity[]*array of integer

The Cart quantities for each line item

item_name[]*array of string

The Cart name for each line item

item_description[]array of string

The Cart description for each line item

item_amount_unit[]*array of number

The Cart amount per unit for each line item

amount_shippingnumber

The Cart shipping amount

amount_couponnumber

The Cart discount amount

amount_taxnumber

The Cart tax amount

currencystring

Transaction currency, ISO 3 letter code

Response

200default

Lookup result

Body

application/json

paymethodstring

This is the paymethod value to use in the "tx" API call

display_titlestring

descriptionstring

currency_codestring

currency_symbolstring

imagestring

cartarray of object

amount_shippingnumber

The Cart shipping amount

amount_couponnumber

The Cart discount amount

amount_taxnumber

The Cart tax amount

currencystring

Transaction currency, ISO 3 letter code

fieldsarray of object

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://uat.txshield.payshield.ai/api/v1/index.php/{sid}/getpaymentoptionfrombin', {
    method: 'POST',
    headers: {
      "Content-Type": "multipart/form-data"
    },
    body: JSON.stringify({
      "hash": "text",
      "timestamp": "text",
      "BIN": "text",
      "item_quantity[]": [
        0
      ],
      "item_name[]": [
        "text"
      ],
      "item_amount_unit[]": [
        0
      ]
    }),
});
const data = await response.json();

Response

200default

{
  "paymethod": "text",
  "display_title": "text",
  "description": "text",
  "currency_code": "text",
  "currency_symbol": "text",
  "image": "text",
  "cart": [
    {
      "quantity": 0,
      "name": "text",
      "description": "text",
      "amount_unit": 0,
      "amount_unit_posted": 0
    }
  ],
  "amount_shipping": 0,
  "amount_coupon": 0,
  "amount_tax": 0,
  "currency": "text",
  "fields": [
    {
      "field_in_txapi": "text",
      "label": "text",
      "description": "text",
      "input_type": "hidden",
      "value": "text",
      "options": [
        {
          "value": "text",
          "label": "text"
        }
      ]
    }
  ]
}

{sid}/getvendorpaymentoptions

Lookup which payment options from the provider. depending on the country and the payby type used with the sid

POSThttps://uat.txshield.payshield.ai/api/v1/index.php/{sid}/getvendorpaymentoptions

Path parameters

sid*integer

ID of site

Body

multipart/form-data

rcode*string

country*string

Country of the user - will provide the list of payments available for that country

Response

200default

Lookup result

Body

application/json

paymethodstring

This is the paymethod value to use in the "tx" API call

display_titlestring

descriptionstring

currency_codestring

currency_symbolstring

imagestring

cartarray of object

amount_shippingnumber

The Cart shipping amount

amount_couponnumber

The Cart discount amount

amount_taxnumber

The Cart tax amount

currencystring

Transaction currency, ISO 3 letter code

fieldsarray of object

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://uat.txshield.payshield.ai/api/v1/index.php/{sid}/getvendorpaymentoptions', {
    method: 'POST',
    headers: {
      "Content-Type": "multipart/form-data"
    },
    body: JSON.stringify({
      "rcode": "text",
      "country": "text"
    }),
});
const data = await response.json();

Response

200default

{
  "paymethod": "text",
  "display_title": "text",
  "description": "text",
  "currency_code": "text",
  "currency_symbol": "text",
  "image": "text",
  "cart": [
    {
      "quantity": 0,
      "name": "text",
      "description": "text",
      "amount_unit": 0,
      "amount_unit_posted": 0
    }
  ],
  "amount_shipping": 0,
  "amount_coupon": 0,
  "amount_tax": 0,
  "currency": "text",
  "fields": [
    {
      "field_in_txapi": "text",
      "label": "text",
      "description": "text",
      "input_type": "hidden",
      "value": "text",
      "options": [
        {
          "value": "text",
          "label": "text"
        }
      ]
    }
  ]
}

Transactions

{sid}/singletx

Create a single Transaction

POST<?=PROTOCOL?>://<?=SITE_DOMAIN?>/api/v1/index.php/{sid}/singletx

Path parameters

sid*any

ID of site

Body

multipart/form-data

hash*string

md5 hash of sid+timestamp+amounttotal+currency+rcode e.g. md5('22'.'1234568995265421'.'17.00'.'USD'.'222b6c')

timestamp*string

timestamp value used in the hash e.g. 1234568995265421

tidstring

Merchant reference

dynamic_descriptorstring

descriptor that needs to be sent to gateway

card_type*string

Which paymethod to use. Look at the "getPaymentOptions" API call to see what paymethods are available and what payment fields need completeting.

card_nointeger (int64)

The card number

card_ccvinteger

The card 3/4 digit verification code

card_exp_monthstring

2 digit for the month. Please have leading zeroes e.g. 05

card_exp_yearstring

4 digit year i.e. 2016

card_namestring

The name printed on the card

threeDSecurestring

json string containing 3ds2 check values

device_infostring

json string containing device information check values

firstname*string

First name of the customer.

lastname*string

Last name of the customer.

email*string

Email of the customer.

phonestring

Phone of the customer. Please not most payment providers require this.

addressstring

Billing street address

suburb_citystring

Billing suburb or city

statestring

Billing state, 2 letter code for US/Canada. Australia should use 2/3 letter codes.

countrystring

Billing country, ISO 3166 2 digit code.

postcodestring

Billing postcode/zipcode.

shipping_addressstring

Shipping street address

shipping_suburb_citystring

Shipping suburb or city

shipping_statestring

Shipping state, 2 letter code for US/Canada. Australia should use 2/3 letter codes.

shipping_countrystring

Shipping country, ISO 3166 2 digit code.

shipping_postcodestring

Shipping postcode/zipcode.

item_quantity[]*array of integer

The Cart quantities for each line item

item_name[]*array of string

The Cart name for each line item

item_no[]*array of string

The Cart number for each line item

item_description[]*array of string

The Cart description for each line item

item_amount_unit[]*array of number

The Cart amount per unit for each line item

amount_shippingnumber

The Cart shipping amount

amount_couponnumber

The Cart discount amount

amount_taxnumber

The Cart tax amount

currency*string

Transaction currency, ISO 3 letter code

tx_action*string

Transaction action eg, PAYMENT, PREAUTH

postback_url*string

The URL of the page to recieve the postback.

Response

200201default

New transaction result

Request

JavaScriptCurlPythonHTTP

const response = await fetch('<?=PROTOCOL?>://<?=SITE_DOMAIN?>/api/v1/index.php/{sid}/singletx', {
    method: 'POST',
    headers: {
      "Content-Type": "multipart/form-data"
    },
    body: JSON.stringify({
      "hash": "text",
      "timestamp": "text",
      "card_type": "text",
      "firstname": "text",
      "lastname": "text",
      "email": "text",
      "item_quantity[]": [
        0
      ],
      "item_name[]": [
        "text"
      ],
      "item_no[]": [
        "text"
      ],
      "item_description[]": [
        "text"
      ],
      "item_amount_unit[]": [
        0
      ],
      "currency": "text",
      "tx_action": "text",
      "postback_url": "text"
    }),
});
const data = await response.json();

{sid}/flagcapture

POST https://uat.txshield.payshield.ai/api/v1/index.php/{sid}/flagcapture

Mark an AUTH transaction as finalised and ready to be captured.

Path Parameters

Name	Type	Description
sid*	Integer	Site ID

Request Body

Name	Type	Description
parent_txid*	String	The parent txid from the Auth transaction.
amount*	Decimal	The amount to capture. Should be the same as the original amount in the Auth transaction.
hash*	String	The md5 hash of sid+amount+rcode

200: OK

{
    // Response
}

400: Bad Request

{
    // Response
}

{sid}/convertnpay

Create a Transaction by converting incoming amount to the descriptor currency

POSThttps://uat.txshield.payshield.ai/api/v1/index.php/{sid}/convertnpay

Path parameters

sid*integer

ID of site

Body

multipart/form-data

hash*string

md5 hash of sid+timestamp+amounttotal+currency+rcode e.g. md5('22'.'1234568995265421'.'17.00'.'USD'.'222b6c')

timestamp*string

timestamp value used in the hash e.g. 1234568995265421

tidstring

Merchant reference

card_type*string

Which paymethod to use. Look at the "getPaymentOptions" API call to see what paymethods are available and what payment fields need completeting.

card_nointeger (int64)

The card number

card_ccvinteger

The card 3/4 digit verification code

card_exp_monthstring

2 digit for the month. Please have leading zeroes e.g. 05

card_exp_yearstring

4 digit year i.e. 2016

card_namestring

The name printed on the card

firstname*string

First name of the customer.

lastname*string

Last name of the customer.

email*string

Email of the customer.

phonestring

Phone of the customer. Please not most payment providers require this.

addressstring

Billing street address

suburb_citystring

Billing suburb or city

statestring

Billing state, 2 letter code for US/Canada. Australia should use 2/3 letter codes.

countrystring

Billing country, ISO 3166 2 digit code.

postcodestring

Billing postcode/zipcode.

shipping_addressstring

Shipping street address

shipping_suburb_citystring

Shipping suburb or city

shipping_statestring

Shipping state, 2 letter code for US/Canada. Australia should use 2/3 letter codes.

shipping_countrystring

Shipping country, ISO 3166 2 digit code.

shipping_postcodestring

Shipping postcode/zipcode.

item_quantity[]*array of integer

The Cart quantities for each line item

item_name[]*array of string

The Cart name for each line item

item_description[]*array of string

The Cart description for each line item

item_amount_unit[]*array of number

The Cart amount per unit for each line item

amount_shippingnumber

The Cart shipping amount

amount_couponnumber

The Cart discount amount

amount_taxnumber

The Cart tax amount

currency*string

Transaction currency, ISO 3 letter code

tx_action*string

Transaction action eg, PAYMENT, PREAUTH

postback_url*string

The URL of the page to recieve the postback.

Response

200201default

New transaction result

Body

application/json

txidinteger (int64)

Transaction id

parent_txidinteger (int64)

Each Transaction has a unique id. The parent transaction is the transaction that groups all transaction together.

statusstring

Has the value "OK" for a successful transaction, "EXC" for a failed transaction, "PEND" for a transaction in progress.

tx_actionstring

The state change txaction, e.g. "PAYMENT", "REFUND"

amountnumber

The amount of the transaction

currencystring

The currency of the transaction

referencestring

Merchant reference

error_codestring

The error code, if status value equal "EXC".

error_msgstring

The error message, if status value equal "EXC".

vrfystring

This is a sha256 hash so the data can be verified. Generate sha256 hash of the string of sid;rcode;txid;status;amount;currency;txaction

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://uat.txshield.payshield.ai/api/v1/index.php/{sid}/convertnpay', {
    method: 'POST',
    headers: {
      "Content-Type": "multipart/form-data"
    },
    body: JSON.stringify({
      "hash": "text",
      "timestamp": "text",
      "card_type": "text",
      "firstname": "text",
      "lastname": "text",
      "email": "text",
      "item_quantity[]": [
        0
      ],
      "item_name[]": [
        "text"
      ],
      "item_description[]": [
        "text"
      ],
      "item_amount_unit[]": [
        0
      ],
      "currency": "text",
      "tx_action": "text",
      "postback_url": "text"
    }),
});
const data = await response.json();

Response

200201default

{
  "txid": 0,
  "parent_txid": 0,
  "status": "text",
  "tx_action": "text",
  "amount": 0,
  "currency": "text",
  "reference": "text",
  "error_code": "text",
  "error_msg": "text",
  "vrfy": "text"
}

Other

{sid}/payout

Create a payout Transaction

POSThttps://uat.txshield.payshield.ai/api/v1/index.php/{sid}/payout

Path parameters

sid*integer

ID of site

Body

multipart/form-data

hash*string

md5 hash of sid+timestamp+amounttotal+currency+rcode e.g. md5('22'.'1234568995265421'.'17.00'.'USD'.'222b6c')

timestamp*string

timestamp value used in the hash e.g. 1234568995265421

tidstring

Merchant reference

card_nointeger (int64)

The card number

card_exp_monthstring

2 digit for the month. Please have leading zeroes e.g. 05

card_exp_yearstring

4 digit year i.e. 2016

card_namestring

The name printed on the card

firstnamestring

First name of the customer.

lastnamestring

Last name of the customer.

email*string

Email of the customer.

phonestring

Phone of the customer. Please not most payment providers require this.

addressstring

Billing street address

suburb_citystring

Billing suburb or city

statestring

Billing state, 2 letter code for US/Canada. Australia should use 2/3 letter codes.

countrystring

Billing country, ISO 3166 2 digit code.

postcodestring

Billing postcode/zipcode.

amount*number

The payout amount

currency*string

Transaction currency, ISO 3 letter code

postback_url*string

The URL of the page to recieve the postback.

Response

200201default

New transaction result

Body

application/json

txidinteger (int64)

Transaction id

parent_txidinteger (int64)

Each Transaction has a unique id. The parent transaction is the transaction that groups all transaction together.

statusstring

Has the value "OK" for a successful transaction, "EXC" for a failed transaction, "PEND" for a transaction in progress.

tx_actionstring

The state change txaction, e.g. "PAYMENT", "REFUND"

amountnumber

The amount of the transaction

currencystring

The currency of the transaction

referencestring

Merchant reference

error_codestring

The error code, if status value equal "EXC".

error_msgstring

The error message, if status value equal "EXC".

vrfystring

This is a sha256 hash so the data can be verified. Generate sha256 hash of the string of sid;rcode;txid;status;amount;currency;txaction

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://uat.txshield.payshield.ai/api/v1/index.php/{sid}/payout', {
    method: 'POST',
    headers: {
      "Content-Type": "multipart/form-data"
    },
    body: JSON.stringify({
      "hash": "text",
      "timestamp": "text",
      "email": "text",
      "amount": 0,
      "currency": "text",
      "postback_url": "text"
    }),
});
const data = await response.json();

Response

200201default

{
  "txid": 0,
  "parent_txid": 0,
  "status": "text",
  "tx_action": "text",
  "amount": 0,
  "currency": "text",
  "reference": "text",
  "error_code": "text",
  "error_msg": "text",
  "vrfy": "text"
}

/cardtransactions

Will search for all transactions done for the given card number either in the last 3 months, or in the month specified.

search card transactions in month and year

POSThttps://uat.txshield.payshield.ai/api/v2/index.php/cardtransactions

Authorization

bearerAuth

Body

application/json

card_nostring

card number masked or unmasked

card_firstsixinteger (dd)

first six digits of card number

card_lastfourinteger (dddd)

last four digits of card number

month_yearinteger (ddYYYY)

month and year of the transaction ddyyyy

Response

200default

Lookup result

Body

application/json

tidstring

tid sent through with the transaction

txidinteger (int64)

Transaction id

parent_txidinteger (int64)

Each Transaction has a unique id. The parent transaction is the transaction that groups all transaction together.

statusstring

Has the value "OK" for a successful transaction, "EXC" for a failed transaction, "PEND" for a transaction in progress.

tx_actionstring

The state change txaction, e.g. "PAYMENT", "REFUND"

amountnumber

The amount of the transaction

currencystring

The currency of the transaction

referencestring

Merchant reference

ref1string

your reference 1

ref2string

your reference 2

ref3string

your reference 3

ref4string

your reference 4

vrfystring

This is a sha256 hash so the data can be verified. Generate sha256 hash of the string of sid;rcode;txid;status;amount;currency;txaction

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://uat.txshield.payshield.ai/api/v2/index.php/cardtransactions', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200default

{
  "tid": "text",
  "txid": 0,
  "parent_txid": 0,
  "status": "text",
  "tx_action": "text",
  "amount": 0,
  "currency": "text",
  "reference": "text",
  "ref1": "text",
  "ref2": "text",
  "ref3": "text",
  "ref4": "text",
  "vrfy": "text"
}

/cardsearchandemail

Functionally the same as /cardtransactions except that it will email a list of the transactions found to the email address stored against the transaction.

search card transactions in month and year

POSThttps://uat.txshield.payshield.ai/api/v2/index.php/cardsearchandemail

Authorization

bearerAuth

Body

application/json

card_nostring

card number masked or unmasked

card_firstsixinteger (dd)

first six digits of card number

card_lastfourinteger (dddd)

last four digits of card number

month_yearinteger (ddYYYY)

month and year of the transaction ddyyyy

Response

200default

Lookup result

Body

application/json

tidstring

tid sent through with the transaction

txidinteger (int64)

Transaction id

parent_txidinteger (int64)

Each Transaction has a unique id. The parent transaction is the transaction that groups all transaction together.

statusstring

Has the value "OK" for a successful transaction, "EXC" for a failed transaction, "PEND" for a transaction in progress.

tx_actionstring

The state change txaction, e.g. "PAYMENT", "REFUND"

amountnumber

The amount of the transaction

currencystring

The currency of the transaction

referencestring

Merchant reference

ref1string

your reference 1

ref2string

your reference 2

ref3string

your reference 3

ref4string

your reference 4

vrfystring

This is a sha256 hash so the data can be verified. Generate sha256 hash of the string of sid;rcode;txid;status;amount;currency;txaction

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://uat.txshield.payshield.ai/api/v2/index.php/cardsearchandemail', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200default

{
  "tid": "text",
  "txid": 0,
  "parent_txid": 0,
  "status": "text",
  "tx_action": "text",
  "amount": 0,
  "currency": "text",
  "reference": "text",
  "ref1": "text",
  "ref2": "text",
  "ref3": "text",
  "ref4": "text",
  "vrfy": "text"
}

v3/{sid}/balance

Returns the available funds that the merchant can request to withdraw / have settled to them. Does not do the withdrawal, just the balance.

Returns available balance for the sid

POST https://uat.txshield.payshield.ai/api/v3/{sid}/balance

Returns the available funds that the merchant can request to withdraw / have settled to them. Does not do the withdrawal, just the balance.

Path Parameters

Name	Type	Description
sid*	String	The sid that you want to check the balance of.

Request Body

Name	Type	Description
object*	String	The root json object.
rcode	String	the rcode for the sid.

200: OK

{"status":"ok","sid":"18","balance":"95.76","currency":"USD"}

Example

example json body for the call

{
    “rcode”: “1239ff1a10f0a0567388b5664f2dc10088848c5b999"
}