PortWallet is now PortPos

 Back to top

PortPos Developer API v2.0.0

Introduction

The PortPos API is organised around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. JSON will be returned in all responses from the API, including errors (though if you're using API bindings, we will convert the response to the appropriate language-specific object). To make the PortPos API as explorable as possible, accounts have sandbox API keys. These keys can be active at the same time. Data created with test-mode credentials will never hit the credit card networks and will never cost anyone money.

You need to login to PortPos panel to generate App key. Please visit Live panel OR Sandbox panel to generate app key.

PortPos payment URL is:

 Sandbox https://payment-sandbox.portpos.com/payment/?invoice=Your_Invoice_ID
 Live https://payment.portpos.com/payment/?invoice=Your_Invoice_ID 
 Only TLS Version 1.2 supported.

Invoice

Create Invoice

This generate an invoice for the transaction.

Sandbox endpoint
https://api-sandbox.portpos.com/payment/v2/invoice
Live endpoint
https://api.portpos.com/payment/v2/invoice
Request body should be valid JSON format
  • HTTP Method
    POST
  • Authentication

    This operation requires authentication via Bearer token:

    Bearer token has a base64 of appkey and a token adhered by a colon. The token contains md5 hash of a concatenation of secretkey and current unix timestamp.
    Example:
    base64(APPKEY:md5(SECRETKEYTIMESTAMP))
    Code Example : $authorization = “Bearer “. base64_encode(APPKEY.”:”.md5(SECRETKEY.time()))

Details about the order.

order.amount Decimal COMPULSORY

The amount you want to charge for this invoice.

Existence COMPULSORY

Validation Rules

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

  • JSON type
    String
  • minimum length
    0.1
  • maximum length
    99999999
order.currencyUpper case alphabetic text COMPULSORY

The currency of the invoice expressed as an ISO 4217 alpha code, e.g. BDT or USD.

Existence COMPULSORY

Validation Rules

Data must consist of the characters A-Z

  • JSON type
    String
  • minimum length
    3
  • maximum length
    3
order.redirect_urlValid http url COMPULSORY

Redirect url after payment.

Existence COMPULSORY

Validation Rules

Data must consist of a valid http url.

  • JSON type
    String
  • minimum length
    10
  • maximum length
    200
order.ipn_urlValid http url OPTIONAL

Where the system will notify when the payment was made. This will notify only on success/failed payment.

Existence OPTIONAL

Validation Rules

Data must consist of a valid http url.

  • JSON type
    String
  • minimum length
    10
  • maximum length
    200
order.reference String OPTIONAL

A reference to track the generated invoice

Existence OPTIONAL

Validation Rules

Data must consist of any characters

  • JSON type
    String
  • minimum length
    1
  • maximum length
    100
order.validity Seconds OPTIONAL

The validity time of an invoice in seconds.

Existence OPTIONAL

Validation Rules

Data must consist of only valid seconds.

  • JSON type
    Integer
  • minimum length
    60 seconds
  • maximum length
    31536000 seconds

Details about the product.

product.name String COMPULSORY

The product name you are selling and whether you can order it.

Existence COMPULSORY

Validation Rules

Data contains of any character.

  • JSON type
    String
  • minimum length
    3
  • maximum length
    150
product.description String COMPULSORY

Your product description.

Existence COMPULSORY

Validation Rules

Data contains of any character.

  • JSON type
    String
  • minimum length
    3
  • maximum length
    300

Your billing details.

billing.customer.name String COMPULSORY

Your customer billing name.

Existence COMPULSORY

Validation Rules

Data contains of any character.

  • JSON type
    String
  • minimum length
    2
  • maximum length
    50
billing.customer.email Valid email address COMPULSORY

Your customer email address.

Existence COMPULSORY

Validation Rules

Data must be a valid email address.

  • JSON type
    String
  • minimum length
    3
  • maximum length
    50
billing.customer.phone Valid phone number COMPULSORY

Your customer phone number.

Existence COMPULSORY

Validation Rules

Data must be a valid phone number.

  • JSON type
    String
  • minimum length
    9
  • maximum length
    15
billing.customer.address.streetString COMPULSORY

Your customer street address.

Existence COMPULSORY

Validation Rules

Data contains any character.

  • JSON type
    String
  • minimum length
    2
  • maximum length
    200
billing.customer.address.city String COMPULSORY

Your customer billing city.

Existence COMPULSORY

Validation Rules

Data contains any character.

  • JSON type
    String
  • minimum length
    2
  • maximum length
    200
billing.customer.address.stateString COMPULSORY

Your customer billing state.

Existence COMPULSORY

Validation Rules

Data contains any character.

  • JSON type
    String
  • minimum length
    2
  • maximum length
    50
billing.customer.address.zipcodeString COMPULSORY

Your customer billing zipcode.

Existence COMPULSORY

Validation Rules

Data contains any character.

  • JSON type
    String
  • minimum length
    3
  • maximum length
    8
billing.customer.address.countryISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 COMPULSORY

Your customer billing country. e.g BD or BGD

Existence COMPULSORY

Validation Rules

Must be an ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 country code.

  • JSON type
    String
  • minimum length
    2
  • maximum length
    3

Your shipping details.

shipping.customer.name String COMPULSORY

Your customer shipping name.

Existence COMPULSORY

Validation Rules

Data contains of any character.

  • JSON type
    String
  • minimum length
    2
  • maximum length
    50
shipping.customer.email Valid email address COMPULSORY

Your customer shipping email address.

Existence COMPULSORY

Validation Rules

Data must be a valid email address.

  • JSON type
    String
  • minimum length
    3
  • maximum length
    50
shipping.customer.phone Valid phone number COMPULSORY

Your customer shipping phone number.

Existence COMPULSORY

Validation Rules

Data must be a valid phone number.

  • JSON type
    String
  • minimum length
    9
  • maximum length
    15
shipping.customer.address.streetString COMPULSORY

Your customer shipping street address.

Existence COMPULSORY

Validation Rules

Data contains any character.

  • JSON type
    String
  • minimum length
    2
  • maximum length
    200
shipping.customer.address.city String COMPULSORY

Your customer shipping city.

Existence COMPULSORY

Validation Rules

Data contains any character.

  • JSON type
    String
  • minimum length
    2
  • maximum length
    200
shipping.customer.address.stateString COMPULSORY

Your customer shipping state.

Existence COMPULSORY

Validation Rules

Data contains any character.

  • JSON type
    String
  • minimum length
    2
  • maximum length
    50
shipping.customer.address.zipcodeString COMPULSORY

Your customer shipping zipcode.

Existence COMPULSORY

Validation Rules

Data contains any character.

  • JSON type
    String
  • minimum length
    3
  • maximum length
    8
shipping.customer.address.countryISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 COMPULSORY

Your customer shipping country. e.g BD or BGD

Existence COMPULSORY

Validation Rules

Must be an ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 country code.

  • JSON type
    String
  • minimum length
    2
  • maximum length
    3

Any additional information to be included on the invoice. The field must include as key value pair up to 10 items. Example: 


                                                                       

"customs":[

    {"key1":"value1"},

    {"key2":"value2"}

]
  • Response  201 
  • 													

{

    "result": "success",

    "data": {

        "invoice_id": "85BE2D4A320E9009",

        "reference": "ABC123",

        "order": {

            "amount": "1000.00",

            "currency": "BDT",

            "type": "emi_purchase",

            "has_emi": 1,

            "has_discount": 0,

            "redirect_url": "http://www.yoursite.com",

            "created_at": "Wed, 07 Nov 2018 18:03:47 +0600",

            "status": "PENDING",

            "emi": {

                "partner": null,

                "tenor": null,

                "is_used": 0

            }

        },

        "product": {

            "name": "x Polo T-shirt",

            "description": "x Polo T-shirt with shipping and handling"

        },

        "billing": {

            "customer": {

                "name": "Robbie Amell",

                "email": "[email protected]",

                "phone": "801234567893",

                "address": {

                    "street": "House 1, Road1, Gulshan 1",

                    "city": "Dhaka",

                    "state": "Dhaka",

                    "zipcode": 1212,

                    "country": "Bangladesh"

                }

            }

        },

        "shipping": {

            "customer": {

                "name": "TEst",

                "email": "[email protected]",

                "phone": "017171817171",

                "address": {

                    "street": "TEst",

                    "city": "TEst",

                    "state": "TEst",

                    "zipcode": 1212,

                    "country": "Bangladesh"

                }

            }

        },

        "action": {

            "type": "redirect",

            "url": "https://payment-sandbox.portpos.com/payment/index/emi/?invoice=85BE2D4A320E9009",

            "payload": null,

            "method": "GET"

        },

        "customs": [

            {

                "ss": "122"

            },

            {

                "sdaas": "2343"

            },

            {

                "discount_code": "Bengal 1,Bengal 2"

            }

        ]

    }

}
IPN validate
/

IPN validate allows the merchant to verify a valid payment notification. For further information on IPN please go to the end of this document.

Sandbox endpoint
https://api-sandbox.portpos.com/payment/v2/invoice/ipn/@invoice_id/@amount


Live endpoint
https://api.portpos.com/payment/v2/invoice/ipn/@invoice_id/@amount
  • URL
    @invoice_id The existing invoice id for the transaction.
    @amount The original amount of the invoice.
  • HTTP Method
    GET
  • Authentication

    This operation requires authentication via Bearer token:

    Bearer token has a base64 of appkey and a token adhered by a colon. The token contains md5 hash of a concatenation of secretkey and current unix timestamp.
    Example:
    base64(APPKEY:md5(SECRETKEYTIMESTAMP))
    Code Example :
    $authorization = “Bearer “. base64_encode(APPKEY.”:”.md5(SECRETKEY.time()))

  • Response  200
  • Http Status code on Success
    
{

   "result":"success",

   "data":{

      "invoice_id":"85BC30171EA29531",

      "reference":"123",

      "order":{

         "amount":"3393.00",

         "currency":"BDT",

         "type":"purchase",

         "has_emi":0,

         "discount_availed":0,

         "redirect_url":"http://www.yoursite.com",

         "created_at":"Sun, 14 Oct 2018 14:35:09 +0600",

         "status":"ACCEPTED"

      },

      "product":{

         "name":"x Polo T-shirt",

         "description":"x Polo T-shirt with shipping and handling"

      },

      "billing":{

         "customer":{

            "name":"Robbie Amell",

            "email":"[email protected]",

            "phone":"801234567893",

            "address":{

               "street":"Unknown",

               "city":"Unknown",

               "state":"Unknown",

               "zipcode":"Unknown",

               "country":"Bangladesh"

            }

         },

         "payer":{

            "name":"Robbie Amell",

            "account":"411111xxxxxx1111",

            "ip_address":"123.456.789.123",

            "user_agent":"Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:61.0) Gecko/20100101 Firefox/61.0"

         },

         "gateway":{

            "category":"card",

            "network":"visa",

            "status":"APPROVED",

            "approve_code":"5BC3018D9DA53",

            "reason":"APPROVED cardSecurityCode: MATCH 3DSecure:

AUTHENTICATION_SUCCESSFUL "

         },

         "source":{

            "category":"card",

            "number":"411111xxxxxx1111",

            "brand":{

               "name":"VISA",

               "type":null,

               "category":null

            },

            "issuer":{

               "name":"JPMORGAN CHASE BANK, N.A.",

               "phone":"+14169819200",

               "website":"http://www.jpmorganchase.com",

               "country":{

                  "name":"United States",

                  "iso2":"US",

                  "iso3":"USA"

               }

            }

         }

      },

      "shipping":{

         "customer":{

            "name":null,

            "email":null,

            "phone":null,

            "address":{

               "street":null,

               "city":null,

               "state":null,

               "zipcode":null,

               "country":null

            }

         }

      },

      "transactions":[

         {

            "amount":"3393.00",

            "currency":"BDT",

            "status":"ACCEPTED",

            "type":"purchase",

            "time":"Sun, 14 Oct 2018 14:43:04 +0600"

         },

         {

            "amount":"-102.79",

            "currency":"BDT",

            "status":"ACCEPTED",

            "type":"fee",

            "time":"Sun, 14 Oct 2018 14:43:04 +0600"

         }

      ],

      "customs":[

         {

            "card_hash":"80e0f2352f868abb3e8fe7238c6103ac"

         }

      ]

   }

}
Retrieving an invoice
/

Retrieves the details of a previous transaction. The previous transaction information is returned by providing the invoice ID from your previous request. 

Sandbox endpoint 
https://api-sandbox.portpos.com/payment/v2/invoice/@invoice_id


Live endpoint 
https://api.portpos.com/payment/v2/invoice/@invoice_id
  • HTTP Method
    GET
  • Authentication

    This operation requires authentication via Bearer token:

    Bearer token has a base64 of appkey and a token adhered by a colon. The token contains md5 hash of a concatenation of secretkey and current unix timestamp.
    Example:
    base64(APPKEY:md5(SECRETKEYTIMESTAMP))
    Code Example : $authorization = “Bearer “. base64_encode(APPKEY.”:”.md5(SECRETKEY.time()))

  • Response  200
  • Sample response
    
								 

{

   "result":"success",

   "data":{

      "invoice_id":"85BC30171EA29531",

      "reference":"123",

      "order":{

         "amount":"3393.00",

         "currency":"BDT",

         "type":"purchase",

         "has_emi":0,

         "discount_availed":0,

         "redirect_url":"http://www.yoursite.com",

         "created_at":"Sun, 14 Oct 2018 14:35:09 +0600",

         "status":"ACCEPTED"

      },

      "product":{

         "name":"x Polo T-shirt",

         "description":"x Polo T-shirt with shipping and handling"

      },

      "billing":{

         "customer":{

            "name":"Robbie Amell",

            "email":"[email protected]",

            "phone":"801234567893",

            "address":{

               "street":"Unknown",

               "city":"Unknown",

               "state":"Unknown",

               "zipcode":"Unknown",

               "country":"Bangladesh"

            }

         },

         "payer":{

            "name":"Robbie Amell",

            "account":"411111xxxxxx1111",

            "ip_address":"123.456.789.123",

            "user_agent":"Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:61.0) Gecko/20100101 Firefox/61.0"

         },

         "gateway":{

            "category":"card",

            "network":"visa",

            "status":"APPROVED",

            "approve_code":"5BC3018D9DA53",

            "reason":"APPROVED cardSecurityCode: MATCH3DSecure: AUTHENTICATION_SUCCESSFUL "

         },

         "source":{

            "category":"card",

            "number":"411111xxxxxx1111",

            "brand":{

               "name":"VISA",

               "type":null,

               "category":null

            },

            "issuer":{

               "name":"JPMORGAN CHASE BANK, N.A.",

               "phone":"+14169819200",

               "website":"http://www.jpmorganchase.com",

               "country":{

                  "name":"United States",

                  "iso2":"US",

                  "iso3":"USA"

               }

            }

         }

      },

      "shipping":{

         "customer":{

            "name":null,

            "email":null,

            "phone":null,

            "address":{

               "street":null,

               "city":null,

               "state":null,

               "zipcode":null,

               "country":null

            }

         }

      },

      "transactions":[

         {

            "amount":"3393.00",

            "currency":"BDT",

            "status":"ACCEPTED",

            "type":"purchase",

            "time":"Sun, 14 Oct 2018 14:43:04 +0600"

         },

         {

            "amount":"-102.79",

            "currency":"BDT",

            "status":"ACCEPTED",

            "type":"fee",

            "time":"Sun, 14 Oct 2018 14:43:04 +0600"

         }

      ],

      "customs":[

         {

            "card_hash":"80e0f2352f868abb3e8fe7238c6103ac"

         }

      ]

   }

}
Create an invoice with discount
/

Create an invoice with discount

Sandbox endpoint
https://api-sandbox.portpos.com/payment/v2/invoice
Live endpoint
https://api.portpos.com/payment/v2/invoice
Request body should be valid JSON format
  • HTTP Method
    POST
  • Authentication

    This operation requires authentication via Bearer token:

    Bearer token has a base64 of appkey and a token adhered by a colon. The token contains md5 hash of a concatenation of secretkey and current unix timestamp.
    Example:
    base64(APPKEY:md5(SECRETKEYTIMESTAMP))
    Code Example : $authorization = “Bearer “. base64_encode(APPKEY.”:”.md5(SECRETKEY.time()))

If you want to give a discount on the invoice.

discount.enable Integer COMPULSORY

1 to enable the discount and 0 to disable.

Existence COMPULSORY

Validation Rules

0 or 1.

  • JSON type
    Integer
  • minimum length
    0
  • maximum length
    1
discount.codes Array OPTIONAL

The discount code you have created in the PortPos discount panel. Maximum items could be 10.

Existence OPTIONAL

Validation Rules

0 or 1.

  • JSON type
    Array
  • minimum
    1
  • maximum
    100
  • Response  201
  • Success response
    
													

{

    "result": "success",

    "data": {

        "invoice_id": "85BE2D4A320E9009",

        "reference": "ABC123",

        "order": {

            "amount": "1000.00",

            "currency": "BDT",

            "type": "emi_purchase",

            "has_emi": 1,

            "has_discount": 0,

            "redirect_url": "http://www.yoursite.com",

            "created_at": "Wed, 07 Nov 2018 18:03:47 +0600",

            "status": "PENDING",

            "emi": {

                "partner": null,

                "tenor": null,

                "is_used": 0

            }

        },

        "product": {

            "name": "x Polo T-shirt",

            "description": "x Polo T-shirt with shipping and handling"

        },

        "billing": {

            "customer": {

                "name": "Robbie Amell",

                "email": "[email protected]",

                "phone": "801234567893",

                "address": {

                    "street": "House 1, Road1, Gulshan 1",

                    "city": "Dhaka",

                    "state": "Dhaka",

                    "zipcode": 1212,

                    "country": "Bangladesh"

                }

            }

        },

        "shipping": {

            "customer": {

                "name": "TEst",

                "email": "[email protected]",

                "phone": "017171817171",

                "address": {

                    "street": "TEst",

                    "city": "TEst",

                    "state": "TEst",

                    "zipcode": 1212,

                    "country": "Bangladesh"

                }

            }

        },

        "action": {

            "type": "redirect",

            "url": "https://payment-sandbox.portpos.com/payment/index/emi/?invoice=85BE2D4A320E9009",

            "payload": null,

            "method": "GET"

        },

        "customs": [

            {

                "ss": "122"

            },

            {

                "sdaas": "2343"

            },

            {

                "discount_code": "Bengal 1,Bengal 2"

            }

        ]

    }

}
Create an invoice with EMI
/

For EMI, you have to generate an invoice using the below additional parameters.

Sandbox endpoint
https://api-sandbox.portpos.com/payment/v2/invoice
Live endpoint
https://api.portpos.com/payment/v2/invoice
Request body should be valid JSON format
  • HTTP Method
    POST
  • Authentication

    This operation requires authentication via Bearer token:

    Bearer token has a base64 of appkey and a token adhered by a colon. The token contains md5 hash of a concatenation of secretkey and current unix timestamp.
    Example:
    base64(APPKEY:md5(SECRETKEYTIMESTAMP))
    Code Example : $authorization = “Bearer “. base64_encode(APPKEY.”:”.md5(SECRETKEY.time()))

If you want to enable EMI on the invoice.

emi.enable Integer COMPULSORY

1 to enable EMI and 0 to disable.

Existence COMPULSORY

Validation Rules

0 or 1.

  • JSON type
    Integer
  • minimum length
    0
  • maximum length
    1
emi.tenures Array OPTIONAL

The emi tenures. Maximum items could be 10.

Existence OPTIONAL

Validation Rules

0 or 1.

  • JSON type
    Array
  • minimum
    0
  • maximum
    60
  • Response  201
  • Success response
    
													

{

    "result": "success",

    "data": {

        "invoice_id": "85BE2D4A320E9009",

        "reference": "ABC123",

        "order": {

            "amount": "1000.00",

            "currency": "BDT",

            "type": "emi_purchase",

            "has_emi": 1,

            "has_discount": 0,

            "redirect_url": "http://www.yoursite.com",

            "created_at": "Wed, 07 Nov 2018 18:03:47 +0600",

            "status": "PENDING",

            "emi": {

                "partner": null,

                "tenor": null,

                "is_used": 0

            }

        },

        "product": {

            "name": "x Polo T-shirt",

            "description": "x Polo T-shirt with shipping and handling"

        },

        "billing": {

            "customer": {

                "name": "Robbie Amell",

                "email": "[email protected]",

                "phone": "801234567893",

                "address": {

                    "street": "House 1, Road1, Gulshan 1",

                    "city": "Dhaka",

                    "state": "Dhaka",

                    "zipcode": 1212,

                    "country": "Bangladesh"

                }

            }

        },

        "shipping": {

            "customer": {

                "name": "TEst",

                "email": "[email protected]",

                "phone": "017171817171",

                "address": {

                    "street": "TEst",

                    "city": "TEst",

                    "state": "TEst",

                    "zipcode": 1212,

                    "country": "Bangladesh"

                }

            }

        },

        "action": {

            "type": "redirect",

            "url": "https://payment-sandbox.portpos.com/payment/index/emi/?invoice=85BE2D4A320E9009",

            "payload": null,

            "method": "GET"

        },

        "customs": [

            {

                "ss": "122"

            },

            {

                "sdaas": "2343"

            },

            {

                "discount_code": "Bengal 1,Bengal 2"

            }

        ]

    }

}
Refund Request
/

Refund API allows you to refund a successful transaction and funds will be refunded to your account. You can optionally refund part of the transaction. You can do so up to 5 times, until the entire transaction has been refunded.

Sandbox endpoint
https://api-sandbox.portpos.com/payment/v2/invoice/refund/@invoice_id


Live endpoint
https://api.portpos.com/payment/v2/invoice/refund/@invoice_id


Request body should be valid JSON format
  • URL

    @invoice_id The invoice id want to issue a refund for.

  • HTTP Method
    POST
  • Authentication

    This operation requires authentication via Bearer token:

    Bearer token has a base64 of appkey and a token adhered by a colon. The token contains md5 hash of a concatenation of secretkey and current unix timestamp.
    Example:
    base64(APPKEY:md5(SECRETKEYTIMESTAMP))
    Code Example : $authorization = “Bearer “. base64_encode(APPKEY.”:”.md5(SECRETKEY.time()))

Information about the refund associated with this transaction.

refund.amount Decimal COMPULSORY

The amount you want to refund.

amount can not be more than the original invoice amount.

Existence COMPULSORY

Validation Rules

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

  • JSON type
    String
  • minimum length
    0.1
  • maximum length
    99999999
refund.currencyUpper case alphabetic text OPTIONAL

The currency of the invoice expressed as an ISO 4217 alpha code, e.g. BDT or USD.

Existence COMPULSORY

Validation Rules

Data must consist of the characters A-Z

  • JSON type
    String
  • minimum length
    3
  • maximum length
    3
  • Response  202
  • Sample response
    
								 

{

    "data": {

            "order": {

            "invoice": "85BC30171EA29531",

            "amount": "3393.00",

            "currency": "BDT",

            "status": "REFUND_PENDING"

        },

        "refund": {

        "amount": 100,

        "status": "APPROVED"

    }

},

"result": "SUCCESS"

}

Status codes 

Status Codes
  • Codes
  • 200

    OK

    201

    Created

    202

    Accepted

    400

    Bad Request

    404

    Not Found

    500

    Internal Service Error

Instant Payment Notification (IPN)

Instant Payment Notification (IPN) is an automated notification service used by PortPos to notify a merchant via an IPN Listener on specific events occurring during a PortPos transaction. Such as:

  • ● Successful Transactions
  • ● Unsuccessful Transactions

  • HTTP Method
    POST
  • Parameters
    • invoice The invoice with which the transaction was performed
    • amount The amount of the transaction
    • status The status of the transaction
    • referenceThe reference of the invoice

It can also be used by merchants to automate their back-office and administrative functions which includes completing orders and and its status.

What is a Listener?

The listener is a web page or application that is created on the merchant’s server which has an API called IPN Validate that allows it to accept and verify IPN messages sent from PortPos.

ipn-image