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

{% openapi src="<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>" path="/{sid}/getpaymentoptionfrombin" 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 %}

### {sid}/getvendorpaymentoptions

{% openapi src="<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>" 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

{% openapi src="<https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2FquHscMMZrM9nAeU4MI91%2Fswagger.yaml?alt=media&token=01c44baa-fa48-40f8-80fd-cbe7a9adc8e0>" path="/{sid}/singletx" method="post" %}
[swagger.yaml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2FquHscMMZrM9nAeU4MI91%2Fswagger.yaml?alt=media\&token=01c44baa-fa48-40f8-80fd-cbe7a9adc8e0)
{% endopenapi %}

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

{% openapi src="<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>" path="/{sid}/convertnpay" 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 %}

## Other

### {sid}/payout

{% openapi src="<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>" path="/{sid}/payout" 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 %}

### /cardtransactions

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

{% openapi src="<https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2F4htBNt54qGKkmxdrR9WY%2FTxProcessV2.yml?alt=media&token=3af94572-79dc-489b-8c2c-3fc0143b6be8>" path="/cardtransactions" method="post" %}
[TxProcessV2.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2F4htBNt54qGKkmxdrR9WY%2FTxProcessV2.yml?alt=media\&token=3af94572-79dc-489b-8c2c-3fc0143b6be8)
{% endopenapi %}

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

{% openapi src="<https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2F4htBNt54qGKkmxdrR9WY%2FTxProcessV2.yml?alt=media&token=3af94572-79dc-489b-8c2c-3fc0143b6be8>" path="/cardsearchandemail" method="post" %}
[TxProcessV2.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2F4htBNt54qGKkmxdrR9WY%2FTxProcessV2.yml?alt=media\&token=3af94572-79dc-489b-8c2c-3fc0143b6be8)
{% endopenapi %}

### 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"
}
```