> For the complete documentation index, see [llms.txt](https://docs.payshield.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payshield.ai/transaction-processing/integrations-and-apis/rest-api/site-sid-payments.md).

# 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.

<mark style="color:green;">`POST`</mark> `https://uat.txshield.payshield.ai/soap/feeapi.php`

#### Request Header

`Authorization: Bearer <token>`

#### Request Body

| Name                                                | Type    | Description                                                                                                  |
| --------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| amount\_coupon<mark style="color:red;">\*</mark>    | String  | Coupon amount                                                                                                |
| (numerical index)<mark style="color:red;">\*</mark> | 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<mark style="color:red;">\*</mark>  | String  | Shipping amount                                                                                              |
| country<mark style="color:red;">\*</mark>           | String  | Country of the user - will provide the list of payments available for that country                           |
| items<mark style="color:red;">\*</mark>             | Array   | Contains the cart items                                                                                      |
| amount\_purchase<mark style="color:red;">\*</mark>  | String  | Total amount of purchase                                                                                     |
| summary<mark style="color:red;">\*</mark>           | Array   | Contains a summary of cart contents                                                                          |
| fxrate\_posted<mark style="color:red;">\*</mark>    | String  | Rate used for conversion of cart currency to gw currency. Enter Buy cart currency Sell Gw currency           |
| sid<mark style="color:red;">\*</mark>               | String  | Site id (unique identifier for the web site)                                                                 |
| currency\_code<mark style="color:red;">\*</mark>    | String  | 3 digit currency code of the cart currency                                                                   |
| rcode<mark style="color:red;">\*</mark>             | String  | Site RCODE                                                                                                   |
| cart<mark style="color:red;">\*</mark>              | Array   | Information about the purchase items. This is only compulsory for feeapi, do not sent the cart to rawfeeapi. |
| amount\_tax<mark style="color:red;">\*</mark>       | String  | tax amount                                                                                                   |
| item\_desc<mark style="color:red;">\*</mark>        | String  | Item description                                                                                             |
| item\_no<mark style="color:red;">\*</mark>          | String  | Article number                                                                                               |
| amount\_unit<mark style="color:red;">\*</mark>      | String  | Unit price amount (without commas and only 2 decimals places)                                                |
| quantity<mark style="color:red;">\*</mark>          | String  | Quantity of the item                                                                                         |
| name<mark style="color:red;">\*</mark>              | String  | Category, can be used freely                                                                                 |

{% tabs %}
{% tab title="200: OK " %}

```javascript
[{
    "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"
        }
    }
}]
```

{% endtab %}
{% endtabs %}

### 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.

<mark style="color:green;">`POST`</mark> `https://uat.txshield.payshield.ai/soap/rawfeeapi.php`

#### Request Body

| Name                                       | Type   | Description                                                                        |
| ------------------------------------------ | ------ | ---------------------------------------------------------------------------------- |
| sid<mark style="color:red;">\*</mark>      | String | Site id (unique identifier for the web site)                                       |
| currency<mark style="color:red;">\*</mark> | String | 3 digit currency code. cart currency                                               |
| country<mark style="color:red;">\*</mark>  | String | Country of the user - will provide the list of payments available for that country |
| rcode<mark style="color:red;">\*</mark>    | String | Site RCODE                                                                         |

{% tabs %}
{% tab title="200: OK " %}

```javascript
[
  {
    "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--"
      },
    }
  }
]
```

{% endtab %}
{% endtabs %}

### {sid}/getpaymentoptions

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

### {sid}/getpaymentoptionsfrombin

## POST /{sid}/getpaymentoptionfrombin

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

```json
{"openapi":"3.0.0","info":{"title":"Txshield Api Version 1","version":"1.0"},"servers":[{"url":"/api/v1/index.php"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Personal API token of a user associated with the site. "}},"schemas":{"paymethods":{"properties":{"paymethod":{"type":"string","description":"This is the paymethod value to use in the \"tx\" API call"},"display_title":{"type":"string"},"description":{"type":"string"},"currency_code":{"type":"string"},"currency_symbol":{"type":"string"},"image":{"type":"string"},"cart":{"type":"array","items":{"$ref":"#/components/schemas/cart"}},"amount_shipping":{"description":"The Cart shipping amount","type":"number"},"amount_coupon":{"description":"The Cart discount amount","type":"number"},"amount_tax":{"description":"The Cart tax amount","type":"number"},"currency":{"description":"Transaction currency, ISO 3 letter code","type":"string"},"fields":{"type":"array","items":{"properties":{"field_in_txapi":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"input_type":{"type":"string","enum":["hidden","text","select"]},"value":{"type":"string"},"options":{"type":"array","items":{"properties":{"value":{"type":"string"},"label":{"type":"string"}}}}}}}}},"cart":{"properties":{"quantity":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"amount_unit":{"type":"number"},"amount_unit_posted":{"type":"number"}}},"errorModel":{"required":["code","message"],"properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}}}}},"paths":{"/{sid}/getpaymentoptionfrombin":{"post":{"tags":["payment options"],"description":"Lookup payment option and convert the cart currency based on your BIN. This is for credit card only.","parameters":[{"name":"sid","in":"path","description":"ID of site","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"hash":{"description":"sha256 hash of sid+timestamp+amounttotal+currency+rcode e.g. hash('sha256', '22'.'1234568995265421'.'17.00'.'USD'.'222b6c')","type":"string"},"timestamp":{"description":"timestamp value used in the hash e.g. 1234568995265421","type":"string"},"BIN":{"description":"First 6 digits of the credit card","type":"string"},"addFee":{"description":"This will add the processing fees on top of the amount.","type":"boolean"},"item_quantity[]":{"description":"The Cart quantities for each line item","type":"array","default":[1],"items":{"type":"integer"}},"item_name[]":{"description":"The Cart name for each line item","type":"array","items":{"type":"string"}},"item_no[]":{"description":"The Cart number for each line item","type":"array","items":{"type":"string"}},"item_description[]":{"description":"The Cart description for each line item","type":"array","items":{"type":"string"}},"item_amount_unit[]":{"description":"The Cart amount per unit for each line item","type":"array","items":{"type":"number"}},"amount_shipping":{"description":"The Cart shipping amount","type":"number","default":0},"amount_coupon":{"description":"The Cart discount amount","type":"number","default":0},"amount_tax":{"description":"The Cart tax amount","type":"number","default":0},"currency":{"description":"Transaction currency, ISO 3 letter code","type":"string"}},"required":["hash","timestamp","BIN","item_quantity[]","item_name[]","item_amount_unit[]"]}}}},"responses":{"200":{"description":"Lookup result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/paymethods"}}}},"default":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorModel"}}}}}}}}}
```

### {sid}/getvendorpaymentoptions

{% openapi src="/files/1u9LF7bPvfCrr8hfmbfx" path="/{sid}/getvendorpaymentoptions" method="post" %}
[TxProcessV1.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fs4d4ErTmJJRKIfdGk2bV%2FTxProcessV1.yml?alt=media\&token=af4079fb-44fd-4acc-b178-10ee83c6802d)
{% endopenapi %}

## Transactions

### {sid}/singletx

## POST /{sid}/singletx

> Create a single Transaction

```json
{"openapi":"3.0.0","info":{"title":"Txshield Api Version 1","version":"1.0"},"servers":[{"url":"/api/v1/index.php"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Personal API token of a user associated with the site. "}},"requestBodies":{"post_sid_singletx":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"hash":{"description":"sha256 hash of sid+timestamp+amounttotal+currency+rcode e.g. hash('sha256', '22'.'1234568995265421'.'17.00'.'USD'.'222b6c')","type":"string"},"timestamp":{"description":"timestamp value used in the hash e.g. 1234568995265421","type":"string"},"tid":{"description":"Merchant reference","type":"string"},"dynamic_descriptor":{"description":"descriptor that needs to be sent to gateway","type":"string"},"card_type":{"description":"Which paymethod to use. Look at the \"getPaymentOptions\" API call to see what paymethods are available and what payment fields need completeting.","type":"string"},"card_no":{"description":"The card number","type":"integer","format":"int64"},"card_ccv":{"description":"The card 3/4 digit verification code","type":"integer"},"card_exp_month":{"description":"2 digit for the month. Please have leading zeroes e.g. 05","type":"string"},"card_exp_year":{"description":"4 digit year i.e. 2016","type":"string"},"card_name":{"description":"The name printed on the card","type":"string"},"threeDSecure":{"description":"json string containing 3ds2 check values","type":"string"},"device_info":{"description":"json string containing device information check values","type":"string"},"firstname":{"description":"First name of the customer.","type":"string"},"lastname":{"description":"Last name of the customer.","type":"string"},"email":{"description":"Email of the customer.","type":"string"},"phone":{"description":"Phone of the customer. Please not most payment providers require this.","type":"string"},"address":{"description":"Billing street address","type":"string"},"suburb_city":{"description":"Billing suburb or city","type":"string"},"state":{"description":"Billing state, 2 letter code for US/Canada. Australia should use 2/3 letter codes.","type":"string"},"country":{"description":"Billing country, ISO 3166 2 digit code.","type":"string"},"postcode":{"description":"Billing postcode/zipcode.","type":"string"},"shipping_address":{"description":"Shipping street address","type":"string"},"shipping_suburb_city":{"description":"Shipping suburb or city","type":"string"},"shipping_state":{"description":"Shipping state, 2 letter code for US/Canada. Australia should use 2/3 letter codes.","type":"string"},"shipping_country":{"description":"Shipping country, ISO 3166 2 digit code.","type":"string"},"shipping_postcode":{"description":"Shipping postcode/zipcode.","type":"string"},"item_quantity[]":{"description":"The Cart quantities for each line item","type":"array","default":[1],"items":{"type":"integer"}},"item_name[]":{"description":"The Cart name for each line item","type":"array","items":{"type":"string"}},"item_no[]":{"description":"The Cart number for each line item","type":"array","items":{"type":"string"}},"item_description[]":{"description":"The Cart description for each line item","type":"array","items":{"type":"string"}},"item_amount_unit[]":{"description":"The Cart amount per unit for each line item","type":"array","items":{"type":"number"}},"amount_shipping":{"description":"The Cart shipping amount","type":"number","default":0},"amount_coupon":{"description":"The Cart discount amount","type":"number","default":0},"amount_tax":{"description":"The Cart tax amount","type":"number","default":0},"currency":{"description":"Transaction currency, ISO 3 letter code","type":"string"},"tx_action":{"description":"Transaction action eg, PAYMENT, PREAUTH","type":"string"},"postback_url":{"description":"The URL of the page to recieve the  postback.","type":"string"}},"required":["hash","timestamp","card_type","firstname","lastname","email","item_quantity[]","item_name[]","item_no[]","item_description[]","item_amount_unit[]","currency","tx_action","postback_url"]}}}}},"schemas":{"standardResponse":{"properties":{"txid":{"type":"integer","format":"int64","description":"Transaction id"},"parent_txid":{"type":"integer","format":"int64","description":"Each Transaction has a unique id. The parent transaction is the transaction that groups all transaction together."},"status":{"type":"string","description":"Has the value \"OK\" for a successful transaction, \"EXC\" for a failed transaction, \"PEND\" for a transaction in progress."},"tx_action":{"type":"string","description":"The state change txaction, e.g. \"PAYMENT\", \"REFUND\""},"amount":{"type":"number","description":"The amount of the transaction"},"currency":{"type":"string","description":"The currency of the transaction"},"reference":{"description":"Merchant reference","type":"string"},"error_code":{"type":"string","description":"The error code, if status value equal \"EXC\"."},"error_msg":{"type":"string","description":"The error message, if status value equal \"EXC\"."},"vrfy":{"type":"string","description":"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"}}},"errorModel":{"required":["code","message"],"properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}}}}},"paths":{"/{sid}/singletx":{"post":{"tags":["transaction"],"description":"Create a single Transaction","parameters":[{"name":"sid","in":"path","description":"ID of site","required":true,"schema":{"type":"integer"}}],"requestBody":{"$ref":"#/components/requestBodies/post_sid_singletx"},"responses":{"200":{"description":"New transaction result","content":null,"application/json":null,"schema":null,"$ref":"#/components/schemas/standardResponse"},"201":{"description":"Callbacks will be sent to the URL in the postback_url parameter","content":null,"application/json":null,"schema":null,"$ref":"#/components/schemas/standardResponse"},"default":{"description":"unexpected error","content":null,"application/json":null,"schema":null,"$ref":"#/components/schemas/errorModel"}}}}}}
```

### {sid}/flagcapture

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | Integer | Site ID     |

#### Request Body

| Name                                           | Type    | Description                                                                               |
| ---------------------------------------------- | ------- | ----------------------------------------------------------------------------------------- |
| parent\_txid<mark style="color:red;">\*</mark> | String  | The parent txid from the Auth transaction.                                                |
| amount<mark style="color:red;">\*</mark>       | Decimal | The amount to capture. Should be the same as the original amount in the Auth transaction. |
| hash<mark style="color:red;">\*</mark>         | String  | The md5 hash of sid+amount+rcode                                                          |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

### {sid}/convertnpay

## POST /{sid}/convertnpay

> Create a Transaction by converting incoming amount to the descriptor currency

```json
{"openapi":"3.0.0","info":{"title":"Txshield Api Version 1","version":"1.0"},"servers":[{"url":"/api/v1/index.php"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Personal API token of a user associated with the site. "}},"requestBodies":{"post_sid_singletx":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"hash":{"description":"sha256 hash of sid+timestamp+amounttotal+currency+rcode e.g. hash('sha256', '22'.'1234568995265421'.'17.00'.'USD'.'222b6c')","type":"string"},"timestamp":{"description":"timestamp value used in the hash e.g. 1234568995265421","type":"string"},"tid":{"description":"Merchant reference","type":"string"},"dynamic_descriptor":{"description":"descriptor that needs to be sent to gateway","type":"string"},"card_type":{"description":"Which paymethod to use. Look at the \"getPaymentOptions\" API call to see what paymethods are available and what payment fields need completeting.","type":"string"},"card_no":{"description":"The card number","type":"integer","format":"int64"},"card_ccv":{"description":"The card 3/4 digit verification code","type":"integer"},"card_exp_month":{"description":"2 digit for the month. Please have leading zeroes e.g. 05","type":"string"},"card_exp_year":{"description":"4 digit year i.e. 2016","type":"string"},"card_name":{"description":"The name printed on the card","type":"string"},"threeDSecure":{"description":"json string containing 3ds2 check values","type":"string"},"device_info":{"description":"json string containing device information check values","type":"string"},"firstname":{"description":"First name of the customer.","type":"string"},"lastname":{"description":"Last name of the customer.","type":"string"},"email":{"description":"Email of the customer.","type":"string"},"phone":{"description":"Phone of the customer. Please not most payment providers require this.","type":"string"},"address":{"description":"Billing street address","type":"string"},"suburb_city":{"description":"Billing suburb or city","type":"string"},"state":{"description":"Billing state, 2 letter code for US/Canada. Australia should use 2/3 letter codes.","type":"string"},"country":{"description":"Billing country, ISO 3166 2 digit code.","type":"string"},"postcode":{"description":"Billing postcode/zipcode.","type":"string"},"shipping_address":{"description":"Shipping street address","type":"string"},"shipping_suburb_city":{"description":"Shipping suburb or city","type":"string"},"shipping_state":{"description":"Shipping state, 2 letter code for US/Canada. Australia should use 2/3 letter codes.","type":"string"},"shipping_country":{"description":"Shipping country, ISO 3166 2 digit code.","type":"string"},"shipping_postcode":{"description":"Shipping postcode/zipcode.","type":"string"},"item_quantity[]":{"description":"The Cart quantities for each line item","type":"array","default":[1],"items":{"type":"integer"}},"item_name[]":{"description":"The Cart name for each line item","type":"array","items":{"type":"string"}},"item_no[]":{"description":"The Cart number for each line item","type":"array","items":{"type":"string"}},"item_description[]":{"description":"The Cart description for each line item","type":"array","items":{"type":"string"}},"item_amount_unit[]":{"description":"The Cart amount per unit for each line item","type":"array","items":{"type":"number"}},"amount_shipping":{"description":"The Cart shipping amount","type":"number","default":0},"amount_coupon":{"description":"The Cart discount amount","type":"number","default":0},"amount_tax":{"description":"The Cart tax amount","type":"number","default":0},"currency":{"description":"Transaction currency, ISO 3 letter code","type":"string"},"tx_action":{"description":"Transaction action eg, PAYMENT, PREAUTH","type":"string"},"postback_url":{"description":"The URL of the page to recieve the  postback.","type":"string"}},"required":["hash","timestamp","card_type","firstname","lastname","email","item_quantity[]","item_name[]","item_no[]","item_description[]","item_amount_unit[]","currency","tx_action","postback_url"]}}}}},"schemas":{"standardResponse":{"properties":{"txid":{"type":"integer","format":"int64","description":"Transaction id"},"parent_txid":{"type":"integer","format":"int64","description":"Each Transaction has a unique id. The parent transaction is the transaction that groups all transaction together."},"status":{"type":"string","description":"Has the value \"OK\" for a successful transaction, \"EXC\" for a failed transaction, \"PEND\" for a transaction in progress."},"tx_action":{"type":"string","description":"The state change txaction, e.g. \"PAYMENT\", \"REFUND\""},"amount":{"type":"number","description":"The amount of the transaction"},"currency":{"type":"string","description":"The currency of the transaction"},"reference":{"description":"Merchant reference","type":"string"},"error_code":{"type":"string","description":"The error code, if status value equal \"EXC\"."},"error_msg":{"type":"string","description":"The error message, if status value equal \"EXC\"."},"vrfy":{"type":"string","description":"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"}}},"errorModel":{"required":["code","message"],"properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}}}}},"paths":{"/{sid}/convertnpay":{"post":{"tags":["transaction"],"description":"Create a Transaction by converting incoming amount to the descriptor currency","parameters":[{"name":"sid","in":"path","description":"ID of site","required":true,"schema":{"type":"integer"}}],"requestBody":{"$ref":"#/components/requestBodies/post_sid_singletx"},"responses":{"200":{"description":"New transaction result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/standardResponse"}}}},"201":{"description":"Callbacks will be sent to the URL in the postback_url parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/standardResponse"}}}},"default":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorModel"}}}}}}}}}
```

## Other

### {sid}/payout

## POST /{sid}/payout

> Create a payout Transaction

```json
{"openapi":"3.0.0","info":{"title":"Txshield Api Version 1","version":"1.0"},"servers":[{"url":"/api/v1/index.php"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Personal API token of a user associated with the site. "}},"schemas":{"standardResponse":{"properties":{"txid":{"type":"integer","format":"int64","description":"Transaction id"},"parent_txid":{"type":"integer","format":"int64","description":"Each Transaction has a unique id. The parent transaction is the transaction that groups all transaction together."},"status":{"type":"string","description":"Has the value \"OK\" for a successful transaction, \"EXC\" for a failed transaction, \"PEND\" for a transaction in progress."},"tx_action":{"type":"string","description":"The state change txaction, e.g. \"PAYMENT\", \"REFUND\""},"amount":{"type":"number","description":"The amount of the transaction"},"currency":{"type":"string","description":"The currency of the transaction"},"reference":{"description":"Merchant reference","type":"string"},"error_code":{"type":"string","description":"The error code, if status value equal \"EXC\"."},"error_msg":{"type":"string","description":"The error message, if status value equal \"EXC\"."},"vrfy":{"type":"string","description":"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"}}},"errorModel":{"required":["code","message"],"properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}}}}},"paths":{"/{sid}/payout":{"post":{"tags":["payout"],"description":"Create a payout Transaction","parameters":[{"name":"sid","in":"path","description":"ID of site","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"hash":{"description":"sha256 hash of sid+timestamp+amounttotal+currency+rcode e.g. hash('sha256', '22'.'1234568995265421'.'17.00'.'USD'.'222b6c')","type":"string"},"timestamp":{"description":"timestamp value used in the hash e.g. 1234568995265421","type":"string"},"tid":{"description":"Merchant reference","type":"string"},"card_no":{"description":"The card number","type":"integer","format":"int64"},"card_exp_month":{"description":"2 digit for the month. Please have leading zeroes e.g. 05","type":"string"},"card_exp_year":{"description":"4 digit year i.e. 2016","type":"string"},"card_name":{"description":"The name printed on the card","type":"string"},"firstname":{"description":"First name of the customer.","type":"string"},"lastname":{"description":"Last name of the customer.","type":"string"},"email":{"description":"Email of the customer.","type":"string"},"phone":{"description":"Phone of the customer. Please not most payment providers require this.","type":"string"},"address":{"description":"Billing street address","type":"string"},"suburb_city":{"description":"Billing suburb or city","type":"string"},"state":{"description":"Billing state, 2 letter code for US/Canada. Australia should use 2/3 letter codes.","type":"string"},"country":{"description":"Billing country, ISO 3166 2 digit code.","type":"string"},"postcode":{"description":"Billing postcode/zipcode.","type":"string"},"amount":{"description":"The payout amount","type":"number","default":0},"currency":{"description":"Transaction currency, ISO 3 letter code","type":"string"},"postback_url":{"description":"The URL of the page to recieve the  postback.","type":"string"}},"required":["hash","timestamp","email","amount","currency","postback_url"]}}}},"responses":{"200":{"description":"New transaction result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/standardResponse"}}}},"201":{"description":"Callbacks will be sent to the URL in the postback_url parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/standardResponse"}}}},"default":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorModel"}}}}}}}}}
```

### /cardtransactions

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

## POST /cardtransactions

> search card transactions in month and year

```json
{"openapi":"3.0.0","info":{"title":"Txshield Api Version 1","version":"1.0"},"servers":[{"url":"/api/v1/index.php"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Personal API token of a user associated with the site. "}},"schemas":{"statusResponse":{"properties":{"tid":{"type":"string","description":"tid sent through with the transaction"},"txid":{"type":"integer","format":"int64","description":"Transaction id"},"parent_txid":{"type":"integer","format":"int64","description":"Each Transaction has a unique id. The parent transaction is the transaction that groups all transaction together."},"status":{"type":"string","description":"Has the value \"OK\" for a successful transaction, \"EXC\" for a failed transaction, \"PEND\" for a transaction in progress."},"tx_action":{"type":"string","description":"The state change txaction, e.g. \"PAYMENT\", \"REFUND\""},"amount":{"type":"number","description":"The amount of the transaction"},"currency":{"type":"string","description":"The currency of the transaction"},"reference":{"description":"Merchant reference","type":"string"},"ref1":{"type":"string","description":"your reference 1"},"ref2":{"type":"string","description":"your reference 2"},"ref3":{"type":"string","description":"your reference 3"},"ref4":{"type":"string","description":"your reference 4"},"vrfy":{"type":"string","description":"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"}}},"errorModel":{"required":["code","message"],"properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}}}}},"paths":{"/cardtransactions":{"post":{"tags":["transaction"],"description":"search card transactions in month and year","requestBody":{"content":{"application/json":{"schema":{"properties":{"card_no":{"description":"card number masked or unmasked","type":"string"},"card_firstsix":{"description":"first six digits of card number","type":"integer","format":"dd"},"card_lastfour":{"description":"last four digits of card number","type":"integer","format":"dddd"},"month_year":{"description":"month and year of the transaction ddyyyy","type":"integer","format":"ddYYYY"}},"required":["month_year"]}}}},"responses":{"200":{"description":"Lookup result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/statusResponse"}}}},"default":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorModel"}}}}}}}}}
```

### /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 /cardsearchandemail

> search card transactions in month and year

```json
{"openapi":"3.0.0","info":{"title":"Txshield Api Version 1","version":"1.0"},"servers":[{"url":"/api/v1/index.php"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Personal API token of a user associated with the site. "}},"schemas":{"statusResponse":{"properties":{"tid":{"type":"string","description":"tid sent through with the transaction"},"txid":{"type":"integer","format":"int64","description":"Transaction id"},"parent_txid":{"type":"integer","format":"int64","description":"Each Transaction has a unique id. The parent transaction is the transaction that groups all transaction together."},"status":{"type":"string","description":"Has the value \"OK\" for a successful transaction, \"EXC\" for a failed transaction, \"PEND\" for a transaction in progress."},"tx_action":{"type":"string","description":"The state change txaction, e.g. \"PAYMENT\", \"REFUND\""},"amount":{"type":"number","description":"The amount of the transaction"},"currency":{"type":"string","description":"The currency of the transaction"},"reference":{"description":"Merchant reference","type":"string"},"ref1":{"type":"string","description":"your reference 1"},"ref2":{"type":"string","description":"your reference 2"},"ref3":{"type":"string","description":"your reference 3"},"ref4":{"type":"string","description":"your reference 4"},"vrfy":{"type":"string","description":"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"}}},"errorModel":{"required":["code","message"],"properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}}}}},"paths":{"/cardsearchandemail":{"post":{"tags":["transaction"],"description":"search card transactions in month and year","requestBody":{"content":{"application/json":{"schema":{"properties":{"card_no":{"description":"card number masked or unmasked","type":"string"},"card_firstsix":{"description":"first six digits of card number","type":"integer","format":"dd"},"card_lastfour":{"description":"last four digits of card number","type":"integer","format":"dddd"},"month_year":{"description":"month and year of the transaction ddyyyy","type":"integer","format":"ddYYYY"}},"required":["month_year"]}}}},"responses":{"200":{"description":"Lookup result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/statusResponse"}}}},"default":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorModel"}}}}}}}}}
```

### 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

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | String | The sid that you want to check the balance of. |

#### Request Body

| Name                                     | Type   | Description            |
| ---------------------------------------- | ------ | ---------------------- |
| object<mark style="color:red;">\*</mark> | String | The root json object.  |
| rcode                                    | String | the rcode for the sid. |

{% tabs %}
{% tab title="200: OK " %}

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

```

{% endtab %}
{% endtabs %}

#### Example

example json body for the call

```
{
    “rcode”: “1239ff1a10f0a0567388b5664f2dc10088848c5b999"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.payshield.ai/transaction-processing/integrations-and-apis/rest-api/site-sid-payments.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
