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

post

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

Path parameters

sidintegerRequired

ID of site

Body

hashstringRequired

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

timestampstringRequired

timestamp value used in the hash e.g. 1234568995265421

BINstringRequired

First 6 digits of the credit card

addFeebooleanOptional

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

item_quantity[]integer[]Required

The Cart quantities for each line item

Default: [1]

item_name[]string[]Required

The Cart name for each line item

item_description[]string[]Optional

The Cart description for each line item

item_amount_unit[]number[]Required

The Cart amount per unit for each line item

amount_shippingnumberOptional

The Cart shipping amount

Default: 0

amount_couponnumberOptional

The Cart discount amount

Default: 0

amount_taxnumberOptional

The Cart tax amount

Default: 0

currencystringOptional

Transaction currency, ISO 3 letter code

Responses

200

Lookup result

application/json

default

unexpected error

application/json

post

HTTPcURLJavaScriptPython

POST /api/v1/index.php/{sid}/getpaymentoptionfrombin HTTP/1.1
Host: uat.txshield.payshield.ai
Content-Type: multipart/form-data
Accept: */*
Content-Length: 232

{
  "hash": "text",
  "timestamp": "text",
  "BIN": "text",
  "addFee": true,
  "item_quantity[]": [
    1
  ],
  "item_name[]": [
    "text"
  ],
  "item_description[]": [
    "text"
  ],
  "item_amount_unit[]": [
    1
  ],
  "amount_shipping": 0,
  "amount_coupon": 0,
  "amount_tax": 0,
  "currency": "text"
}

{
  "paymethod": "text",
  "display_title": "text",
  "description": "text",
  "currency_code": "text",
  "currency_symbol": "text",
  "image": "text",
  "cart": [],
  "amount_shipping": 1,
  "amount_coupon": 1,
  "amount_tax": 1,
  "currency": "text",
  "fields": []
}

{sid}/getvendorpaymentoptions

post

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

Path parameters

sidintegerRequired

ID of site

Body

rcodestringRequired

countrystringRequired

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

Responses

200

Lookup result

application/json

default

unexpected error

application/json

post

HTTPcURLJavaScriptPython

POST /api/v1/index.php/{sid}/getvendorpaymentoptions HTTP/1.1
Host: uat.txshield.payshield.ai
Content-Type: multipart/form-data
Accept: */*
Content-Length: 33

{
  "rcode": "text",
  "country": "text"
}

{
  "paymethod": "text",
  "display_title": "text",
  "description": "text",
  "currency_code": "text",
  "currency_symbol": "text",
  "image": "text",
  "cart": [],
  "amount_shipping": 1,
  "amount_coupon": 1,
  "amount_tax": 1,
  "currency": "text",
  "fields": []
}

Transactions

{sid}/singletx

post

Create a single Transaction

Path parameters

sidanyRequired

ID of site

Body

hashstringRequired

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

timestampstringRequired

timestamp value used in the hash e.g. 1234568995265421

tidstringOptional

Merchant reference

dynamic_descriptorstringOptional

descriptor that needs to be sent to gateway

card_typestringRequired

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

card_nointeger · int64Optional

The card number

card_ccvintegerOptional

The card 3/4 digit verification code

card_exp_monthstringOptional

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

card_exp_yearstringOptional

4 digit year i.e. 2016

card_namestringOptional

The name printed on the card

threeDSecurestringOptional

json string containing 3ds2 check values

device_infostringOptional

json string containing device information check values

firstnamestringRequired

First name of the customer.

lastnamestringRequired

Last name of the customer.

emailstringRequired

Email of the customer.

phonestringOptional

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

addressstringOptional

Billing street address

suburb_citystringOptional

Billing suburb or city

statestringOptional

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

countrystringOptional

Billing country, ISO 3166 2 digit code.

postcodestringOptional

Billing postcode/zipcode.

shipping_addressstringOptional

Shipping street address

shipping_suburb_citystringOptional

Shipping suburb or city

shipping_statestringOptional

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

shipping_countrystringOptional

Shipping country, ISO 3166 2 digit code.

shipping_postcodestringOptional

Shipping postcode/zipcode.

item_quantity[]integer[]Required

The Cart quantities for each line item

Default: [1]

item_name[]string[]Required

The Cart name for each line item

item_no[]string[]Required

The Cart number for each line item

item_description[]string[]Required

The Cart description for each line item

item_amount_unit[]number[]Required

The Cart amount per unit for each line item

amount_shippingnumberOptional

The Cart shipping amount

Default: 0

amount_couponnumberOptional

The Cart discount amount

Default: 0

amount_taxnumberOptional

The Cart tax amount

Default: 0

currencystringRequired

Transaction currency, ISO 3 letter code

tx_actionstringRequired

Transaction action eg, PAYMENT, PREAUTH

postback_urlstringRequired

The URL of the page to recieve the postback.

Responses

200

New transaction result

201

Callbacks will be sent to the URL in the postback_url parameter

default

unexpected error

post

HTTPcURLJavaScriptPython

POST /api/v1/index.php/{sid}/singletx HTTP/1.1
Host: <?=SITE_DOMAIN?>
Content-Type: multipart/form-data
Accept: */*
Content-Length: 749

{
  "hash": "text",
  "timestamp": "text",
  "tid": "text",
  "dynamic_descriptor": "text",
  "card_type": "text",
  "card_no": 1,
  "card_ccv": 1,
  "card_exp_month": "text",
  "card_exp_year": "text",
  "card_name": "text",
  "threeDSecure": "text",
  "device_info": "text",
  "firstname": "text",
  "lastname": "text",
  "email": "text",
  "phone": "text",
  "address": "text",
  "suburb_city": "text",
  "state": "text",
  "country": "text",
  "postcode": "text",
  "shipping_address": "text",
  "shipping_suburb_city": "text",
  "shipping_state": "text",
  "shipping_country": "text",
  "shipping_postcode": "text",
  "item_quantity[]": [
    1
  ],
  "item_name[]": [
    "text"
  ],
  "item_no[]": [
    "text"
  ],
  "item_description[]": [
    "text"
  ],
  "item_amount_unit[]": [
    1
  ],
  "amount_shipping": 0,
  "amount_coupon": 0,
  "amount_tax": 0,
  "currency": "text",
  "tx_action": "text",
  "postback_url": "text"
}

No content

{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

post

Create a Transaction by converting incoming amount to the descriptor currency

Path parameters

sidintegerRequired

ID of site

Body

hashstringRequired

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

timestampstringRequired

timestamp value used in the hash e.g. 1234568995265421

tidstringOptional

Merchant reference

card_typestringRequired

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

card_nointeger · int64Optional

The card number

card_ccvintegerOptional

The card 3/4 digit verification code

card_exp_monthstringOptional

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

card_exp_yearstringOptional

4 digit year i.e. 2016

card_namestringOptional

The name printed on the card

firstnamestringRequired

First name of the customer.

lastnamestringRequired

Last name of the customer.

emailstringRequired

Email of the customer.

phonestringOptional

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

addressstringOptional

Billing street address

suburb_citystringOptional

Billing suburb or city

statestringOptional

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

countrystringOptional

Billing country, ISO 3166 2 digit code.

postcodestringOptional

Billing postcode/zipcode.

shipping_addressstringOptional

Shipping street address

shipping_suburb_citystringOptional

Shipping suburb or city

shipping_statestringOptional

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

shipping_countrystringOptional

Shipping country, ISO 3166 2 digit code.

shipping_postcodestringOptional

Shipping postcode/zipcode.

item_quantity[]integer[]Required

The Cart quantities for each line item

Default: [1]

item_name[]string[]Required

The Cart name for each line item

item_description[]string[]Required

The Cart description for each line item

item_amount_unit[]number[]Required

The Cart amount per unit for each line item

amount_shippingnumberOptional

The Cart shipping amount

Default: 0

amount_couponnumberOptional

The Cart discount amount

Default: 0

amount_taxnumberOptional

The Cart tax amount

Default: 0

currencystringRequired

Transaction currency, ISO 3 letter code

tx_actionstringRequired

Transaction action eg, PAYMENT, PREAUTH

postback_urlstringRequired

The URL of the page to recieve the postback.

Responses

200

New transaction result

application/json

201

Callbacks will be sent to the URL in the postback_url parameter

application/json

default

unexpected error

application/json

post

HTTPcURLJavaScriptPython

POST /api/v1/index.php/{sid}/convertnpay HTTP/1.1
Host: uat.txshield.payshield.ai
Content-Type: multipart/form-data
Accept: */*
Content-Length: 657

{
  "hash": "text",
  "timestamp": "text",
  "tid": "text",
  "card_type": "text",
  "card_no": 1,
  "card_ccv": 1,
  "card_exp_month": "text",
  "card_exp_year": "text",
  "card_name": "text",
  "firstname": "text",
  "lastname": "text",
  "email": "text",
  "phone": "text",
  "address": "text",
  "suburb_city": "text",
  "state": "text",
  "country": "text",
  "postcode": "text",
  "shipping_address": "text",
  "shipping_suburb_city": "text",
  "shipping_state": "text",
  "shipping_country": "text",
  "shipping_postcode": "text",
  "item_quantity[]": [
    1
  ],
  "item_name[]": [
    "text"
  ],
  "item_description[]": [
    "text"
  ],
  "item_amount_unit[]": [
    1
  ],
  "amount_shipping": 0,
  "amount_coupon": 0,
  "amount_tax": 0,
  "currency": "text",
  "tx_action": "text",
  "postback_url": "text"
}

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

Other

{sid}/payout

post

Create a payout Transaction

Path parameters

sidintegerRequired

ID of site

Body

hashstringRequired

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

timestampstringRequired

timestamp value used in the hash e.g. 1234568995265421

tidstringOptional

Merchant reference

card_nointeger · int64Optional

The card number

card_exp_monthstringOptional

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

card_exp_yearstringOptional

4 digit year i.e. 2016

card_namestringOptional

The name printed on the card

firstnamestringOptional

First name of the customer.

lastnamestringOptional

Last name of the customer.

emailstringRequired

Email of the customer.

phonestringOptional

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

addressstringOptional

Billing street address

suburb_citystringOptional

Billing suburb or city

statestringOptional

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

countrystringOptional

Billing country, ISO 3166 2 digit code.

postcodestringOptional

Billing postcode/zipcode.

amountnumberRequired

The payout amount

Default: 0

currencystringRequired

Transaction currency, ISO 3 letter code

postback_urlstringRequired

The URL of the page to recieve the postback.

Responses

200

New transaction result

application/json

201

Callbacks will be sent to the URL in the postback_url parameter

application/json

default

unexpected error

application/json

post

HTTPcURLJavaScriptPython

POST /api/v1/index.php/{sid}/payout HTTP/1.1
Host: uat.txshield.payshield.ai
Content-Type: multipart/form-data
Accept: */*
Content-Length: 331

{
  "hash": "text",
  "timestamp": "text",
  "tid": "text",
  "card_no": 1,
  "card_exp_month": "text",
  "card_exp_year": "text",
  "card_name": "text",
  "firstname": "text",
  "lastname": "text",
  "email": "text",
  "phone": "text",
  "address": "text",
  "suburb_city": "text",
  "state": "text",
  "country": "text",
  "postcode": "text",
  "amount": 0,
  "currency": "text",
  "postback_url": "text"
}

{
  "txid": 1,
  "parent_txid": 1,
  "status": "text",
  "tx_action": "text",
  "amount": 1,
  "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.

post

search card transactions in month and year

Authorizations

Body

card_nostringOptional

card number masked or unmasked

card_firstsixinteger · ddOptional

first six digits of card number

card_lastfourinteger · ddddOptional

last four digits of card number

month_yearinteger · ddYYYYOptional

month and year of the transaction ddyyyy

Responses

200

Lookup result

application/json

default

unexpected error

application/json

post

HTTPcURLJavaScriptPython

POST /api/v2/index.php/cardtransactions HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 69

{
  "card_no": "text",
  "card_firstsix": 1,
  "card_lastfour": 1,
  "month_year": 1
}

{
  "tid": "text",
  "txid": 1,
  "parent_txid": 1,
  "status": "text",
  "tx_action": "text",
  "amount": 1,
  "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.

post

search card transactions in month and year

Authorizations

Body

card_nostringOptional

card number masked or unmasked

card_firstsixinteger · ddOptional

first six digits of card number

card_lastfourinteger · ddddOptional

last four digits of card number

month_yearinteger · ddYYYYOptional

month and year of the transaction ddyyyy

Responses

200

Lookup result

application/json

default

unexpected error

application/json

post

HTTPcURLJavaScriptPython

POST /api/v2/index.php/cardsearchandemail HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 69

{
  "card_no": "text",
  "card_firstsix": 1,
  "card_lastfour": 1,
  "month_year": 1
}

{
  "tid": "text",
  "txid": 1,
  "parent_txid": 1,
  "status": "text",
  "tx_action": "text",
  "amount": 1,
  "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"
}