PortPos API

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

Invoices

Create new invoice

POST

/

Create New Invoice for payment

 Sandbox endpoint https://api-sandbox.portpos.com/api/v1/

 Live endpoint https://api.portpos.com/api/v1/

Parameters
app_key

string (required) Example: 9c41cf8bce319cc6300cc2c4e9ef7c8f
Application key
Character limit (Max): 32 char

timestamp

integer (required) Example: 1424941656
Current timestamp
Character limit (Max): 10 digit Unix Timestamp

token

string (required) Example: 249de82fb9a57e88bd3444003093771b
It is the md5 of your secret key + timestamp you provided on second parameter
Character limit (Max): 32 char

call

string (required) Example: gen_invoice
gen_invoice
Character limit (Max): Fixed

amount

double (required) Example: 500.00
The amount you want to charge. Minimum 10.00
Character limit (Max): 8 digit

currency

string (required) Example: BDT
Only BDT acceptable.
Character limit (Max): 3 char

product_name

string (required) Example: Polo T-shirt
The product name you are selling. It can your order it.1x Polo T-shirt
Character limit (Max): 150 char

product_description

string (required) Example: 1x Polo T-shirt with shipping and handling
Your product description1x Polo T-shirt with shipping and handling
Character limit (Max): 300 char

name

string (required) Example: Robbie Amell
Your customer nameRobbie Amell
Character limit (Max): 50 char

email

string (required) Example: [email protected]
Your customer email address.[email protected]
Character limit (Max): 50 char

phone

string (required) Example: +880123456789
Your customer billing phone number.+880123456789
Character limit (Max): 15 char

address

string (required) Example: House 1, Road1, Gulshan 1
Your customer billing address.[email protected]
Character limit (Max): 200 char

city

string (required) Example: Dhaka
Your customer billing city.[email protected]
Character limit (Max): 50 char

state

string (required) Example: Dhaka
Your customer billing state. If there is no state, re-enter city.Dhaka
Character limit (Max): 50 char

zipcode

string (required) Example: 1212
Your customer billing zip/postal code.1212

country

string (required) Example: BD or BGD
Your customer billing country. It is 2 or 3 digit iso code.BD
Character limit (Max): 3 char iso country code

redirect_url

string (required) Example: http://www.yoursite.com
Redirect URL for after payment.http://www.yoursite.com

ipn_url

string (optional) Example: http://www.yoursite.com/ipn
This is ipn url. Where the system will notify when the payment was made. Tt will notify only on success/failed/refund payment.http://www.yoursite.com/ipn
Character limit (Max): 250 char

ship_to_name

string (optional) Example: Robbie Amell
Your customer shipping nameRobbie Amell
Character limit (Max): 50 char

ship_to_email

string (optional) Example: [email protected]
Your customer shipping email address.[email protected]
Character limit (Max): 50 char

ship_to_phone

string (optional) Example: +880123456789
Your customer shipping phone number.+880123456789
Character limit (Max): 15 char

ship_to_address

string (optional) Example: House 1, Road1, Gulshan 1
Your customer shipping address.[email protected]
Character limit (Max): 200 char

ship_to_city

string (optional) Example: Dhaka
Your customer shipping city.[email protected]
Character limit (Max): 50 char

ship_to_state

string (optional) Example: Dhaka
Your customer shipping state. If there is no state, re-enter city.Dhaka
Character limit (Max): 50 char

ship_to_zipcode

string (optional) Example: 1212
Your customer shipping zip/postal code.1212
Character limit (Max): 8 digit

ship_to_country

string (optional) Example: BD or BGD
Your customer shipping country. It is 2 or 3 digit iso code.BD
Character limit (Max): 3 char iso country code

Response 200ShowHide

Success response

								 
{
   "status":200,
   "data":{
      "id":"1711",
      "client_id":"13",
      "amount":"100",
      "currency":"BDT",
      "name":"",
      "email":"[email protected]",
      "phone":"0123456789",
      "address":"ddd",
      "country":"BD",
      "state":"dd",
      "city":"dd",
      "zipcode":"dd",
      "ship_to_name":"",
      "ship_to_email":"",
      "ship_to_phone":"",
      "ship_to_address":"",
      "ship_to_country":"",
      "ship_to_state":"",
      "ship_to_city":"",
      "ship_to_zipcode":"",
      "product_name":"dd",
      "product_description":"ddd",
      "ipn_url":"",
      "gateway_txn_id":"123456789",
      "reason":"",
      "redirect_url":"http:\/\/www.google.com",
      "invoice_id":"854EEE3DCAEA1725"
   }
}

Failed response

								 
{
   "status":400,
   "data":{
      "client_id":"13",
      "currency":"BDT",
      "name":"",
      "email":"[email protected]",
      "phone":"0123456789",
      "address":"ddd",
      "country":"BD",
      "state":"dd",
      "city":"dd",
      "zipcode":"dd",
      "ship_to_name":"",
      "ship_to_email":"",
      "ship_to_phone":"",
      "ship_to_address":"",
      "ship_to_country":"",
      "ship_to_state":"",
      "ship_to_city":"",
      "ship_to_zipcode":"",
      "ipn_url":""
   },
   "message":{
      "amount":"amount is not set",
      "product_name":"product_name is not set",
      "product_description":"product_description is not set",
      "redirect_url":"redirect_url is not set"
   }
}

Verify transaction

POST

/

Verify existing transaction

Sandbox endpoint https://api-sandbox.portpos.com/api/v1/

Live endpoint https://api.portpos.com/api/v1/

Parameters
app_key

string (required) Example: 9c41cf8bce319cc6300cc2c4e9ef7c8f
Application key

timestamp

integer (required) Example: 1424941656
Current timestamp

token

string (required) Example: 249de82fb9a57e88bd3444003093771b
It is the md5 of your secret key + timestamp you provided on second parameter

call

string (required) Example: ipn_validate
ipn_validate

amount

double (required) Example: 500.00
The amount you want to charge. Minimum 10.00

invoice

string (required) Example: 854EEA58BC861985
Existing invoice number. You should receive invoice number when you generate invoice, through IPN and also with redirect url.854EEA58BC861985

Response 200ShowHide

ACCEPTED (Success) response

								 
{
   "status":200,
   "data":{
      "invoice_id":"854EEEF3240FBB53",
      "amount":"100.00",
      "buyer_email":"[email protected]",
      "buyer_name":"",
      "buyer_phone":"0123456789",
      "buyer_address":"ddd",
      "product_name":"test",
      "product_description":"dfdf",
      "currency":"BDT",
      "payer_account":"467922XXXXXX7653",
      "status":"ACCEPTED",
      "payer_name":"Sadiqur Rahman",
      "ip_address":"192.168.2.39",
      "user_agent":"Mozilla\/5.0 (Windows NT 6.3; WOW64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/40.0.2214.115 Safari\/537.36",
      "gateway_name":"BRAC Bank Limited",
      "gateway_url":"http:\/\/www.bracbank.com",
      "issuer_name":"Eastern Bank, Ltd",
      "issuer_phone":"+88028332232",
      "issuer_website":"http:\/\/www.ebl.com.bd",
      "card_brand":"VISA",
      "card_type":"credit",
      "gateway_txn_id":"123456789",
      "reason":"",
      "card_category":"Platinum",
      "issuer_country_iso2":"BD",
      "issuer_country":"Bangladesh"
   }
}

REJECTED payment response

								 
{
   "status":300,
   "data":{
      "invoice_id":"854EEF01F62EBB53",
      "amount":"100.00",
      "buyer_email":"[email protected]",
      "buyer_name":"",
      "buyer_phone":"0123456789",
      "buyer_address":"ddd",
      "product_name":"test",
      "product_description":"dfdf",
      "currency":"BDT",
      "payer_account":"411111XXXXXX11",
      "status":"REJECTED",
      "payer_name":"Test",
      "ip_address":"192.168.2.39",
      "user_agent":"Mozilla\/5.0 (Windows NT 6.3; WOW64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/40.0.2214.115 Safari\/537.36",
      "gateway_name":"BRAC Bank Limited",
      "gateway_url":"http:\/\/www.bracbank.com",
      "issuer_name":"JPMORGAN CHASE BANK, N.A.",
      "issuer_phone":"+14169819200",
      "issuer_website":"http:\/\/www.jpmorganchase.com",
      "card_brand":"VISA",
      "gateway_txn_id":"123456789",
      "reason":"Unsuccessful - Declined",
      "card_type":null,
      "card_category":null,
      "issuer_country_iso2":"US",
      "issuer_country":"United States"
   }
}
}

PENDING payment response

								 
{
   "status":100,
   "data":{
      "invoice_id":"854EEF0AE647C438",
      "amount":"100.00",
      "buyer_email":"[email protected]",
      "buyer_name":"",
      "buyer_phone":"0123456789",
      "buyer_address":"ddd",
      "product_name":"product name",
      "product_description":"product description",
      "payer_account":null,
      "status":null,
      "payer_name":null,
      "ip_address":null,
      "user_agent":null,
      "gateway_name":null,
      "gateway_url":null,
      "issuer_name":null,
      "issuer_phone":null,
      "issuer_website":null,
      "gateway_txn_id":"",
      "reason":"",
      "card_brand":null,
      "card_type":null,
      "card_category":null,
      "issuer_country_iso2":null,
      "issuer_country":null
   }
}

Invalid request response

								 
{
   "status":400,
   "message":"Invalid IPN Request"
}

Get invoice

POST

/

Retrieve existing transaction

Sandbox endpoint https://api-sandbox.portpos.com/api/v1/

Live endpoint https://api.portpos.com/api/v1/

Parameters
app_key

string (required) Example: 9c41cf8bce319cc6300cc2c4e9ef7c8f
Application key

timestamp

integer (required) Example: 1424941656
Current timestamp

token

string (required) Example: 249de82fb9a57e88bd3444003093771b
It is the md5 of your secret key + timestamp you provided on second parameter

call

string (required) Example: get_invoice
get_invoice

invoice

string (required) Example: 854EEA58BC861985
Existing invoice number.854EEA58BC861985

Response 200ShowHide

Sample response

								 
{
   "status":200,
   "data":{
      "invoice_id":"854EEEF3240FBB53",
      "amount":"100.00",
      "buyer_email":"[email protected]",
      "buyer_name":"",
      "buyer_phone":"0123456789",
      "buyer_address":"ddd",
      "product_name":"test",
      "product_description":"dfdf",
      "currency":"BDT",
      "payer_account":"467922XXXXXX7653",
      "status":"ACCEPTED",
      "payer_name":"Sadiqur Rahman",
      "ip_address":"192.168.2.39",
      "user_agent":"Mozilla\/5.0 (Windows NT 6.3; WOW64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/40.0.2214.115 Safari\/537.36",
      "gateway_name":"BRAC Bank Limited",
      "gateway_url":"http:\/\/www.bracbank.com",
      "issuer_name":"Eastern Bank, Ltd",
      "issuer_phone":"+88028332232",
      "issuer_website":"http:\/\/www.ebl.com.bd",
      "card_brand":"VISA",
      "card_type":"credit",
      "gateway_txn_id":"123456789",
      "reason":"",
      "card_category":"Platinum",
      "issuer_country_iso2":"BD",
      "issuer_country":"Bangladesh"
   }
}

Invalid request response

								 
{
   "status":400,
   "message":"Invalid Request"
}

Refund Request

POST

/

Refund Request

Sandbox endpoint https://api-sandbox.portpos.com/api/v1/

Live endpoint https://api.portpos.com/api/v1/

Parameters
app_key

string (required) Example: 9c41cf8bce319cc6300cc2c4e9ef7c8f
Application key

timestamp

integer (required) Example: 1424941656
Current timestamp

token

string (required) Example: 249de82fb9a57e88bd3444003093771b
It is the md5 of your secret key + timestamp you provided on second parameter

call

string (required) Example: refund_request
refund_request

invoice

string (required) Example: 854EEA58BC861985
The invoice number you want to issue a refund for.854EEA58BC861985

amount

double (required) Example: 10.00
The amount you want to refund. Amount can not be more than the original invoice amount.10.00

Response 200ShowHide

Sample response

								 
{
   "status":210,
   "data":{
      "invoice_id":"854EEEF3240FBB53",
      "amount":"100.00",
      "buyer_email":"[email protected]",
      "buyer_name":"",
      "buyer_phone":"0123456789",
      "buyer_address":"ddd",
      "product_name":"test",
      "product_description":"dfdf",
      "currency":"BDT",
      "payer_account":"467922XXXXXX7653",
      "status":"REFUND_PENDING",
      "payer_name":"Sadiqur Rahman",
      "ip_address":"192.168.2.39",
      "user_agent":"Mozilla\/5.0 (Windows NT 6.3; WOW64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/40.0.2214.115 Safari\/537.36",
      "gateway_name":"BRAC Bank Limited",
      "gateway_url":"http:\/\/www.bracbank.com",
      "issuer_name":"Eastern Bank, Ltd",
      "issuer_phone":"+88028332232",
      "issuer_website":"http:\/\/www.ebl.com.bd",
      "card_brand":"VISA",
      "card_type":"credit",
      "gateway_txn_id":"123456789",
      "reason":"",
      "card_category":"Platinum",
      "issuer_country_iso2":"BD",
      "issuer_country":"Bangladesh"
   }
}

Invalid request response

								 
{
   "status":400,
   "message":"Refund amount exceeded. Refundable amount is 19.00"
}

Status codes

Status code 200 means success/accepted.

Status Code

Codes
100

integer PENDING
The transaction is pending. The user has not completed the transaction yet.

120

integer CANCELLED
Either the user or merchant has cancelled the payment.

130

integer EXPIRED
The invoice is expired. Customer did not make the payment in desired time.

200

integer ACCEPTED
The request is successful or the transaction has been accepted.

210

integer REFUND_PENDING
The refund request has been submitted.

215

integer REFUND_PROCESSING
The refund request has been submitted to the acquiring bank.

220

integer REFUNDED
The transaction is fully refunded.

230

integer PARTIALLY_REFUNDED
The transaction is partially refunded

240

integer CHARGED_BACK
We received a charge back request from the issuing bank and we have deducted the transaction amount from your account.

300

integer REJECTED
User attempted to pay with his/her card but the payment could not be completed. Either the issuing bank declined the transaction or the card is restricted by the acquiring bank.

400

integer INVALID_REQUEST
Your request could not completed. Either you provided wrong parameters or you forgot to provide some mandatory parameters

500

integer NOT_ALLOWED
You are not allowed to perform this action.

Developer Center

PortPos Developer API v1.0.0(Deprecated)

Introduction

Invoices

Success response

Failed response

ACCEPTED (Success) response

REJECTED payment response

PENDING payment response

Invalid request response

Sample response

Invalid request response

Sample response

Invalid request response

Status codes

Status codes