Developer Center
PortWallet is now PortPos
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
This generate an invoice for the transaction.
Sandbox endpointhttps://api-sandbox.portpos.com/payment/v2/invoice
Live endpointhttps://api.portpos.com/payment/v2/invoice
Request body should be valid JSON format
-
HTTP MethodPOST
-
Authentication
This operation requires authentication via Bearer token:
Bearer token has a
base64of appkey and a token adhered by a colon. The token containsmd5hash 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.
The amount you want to charge for this invoice. LessMore
Existence COMPULSORY
Validation RulesData is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
-
JSON typeString
-
minimum length0.1
-
maximum length99999999
The currency of the invoice expressed as an ISO 4217 alpha code, e.g. BDT or USD. LessMore
Existence COMPULSORY
Validation RulesData must consist of the characters A-Z
-
JSON typeString
-
minimum length3
-
maximum length3
Redirect url after payment. LessMore
Existence COMPULSORY
Validation RulesData must consist of a valid http url.
-
JSON typeString
-
minimum length10
-
maximum length200
Where the system will notify when the payment was made. This will notify only on success/failed payment. LessMore
Existence OPTIONAL
Validation RulesData must consist of a valid http url.
-
JSON typeString
-
minimum length10
-
maximum length200
A reference to track the generated invoice LessMore
Existence OPTIONAL
Validation RulesData must consist of any characters
-
JSON typeString
-
minimum length1
-
maximum length100
The validity time of an invoice in seconds. LessMore
Existence OPTIONAL
Validation RulesData must consist of only valid seconds.
-
JSON typeInteger
-
minimum length60 seconds
-
maximum length31536000 seconds
Details about the product.
The product name you are selling and whether you can order it. LessMore
Existence COMPULSORY
Validation RulesData contains of any character.
-
JSON typeString
-
minimum length3
-
maximum length150
Your product description. LessMore
Existence COMPULSORY
Validation RulesData contains of any character.
-
JSON typeString
-
minimum length3
-
maximum length300
Your billing details.
Your customer billing name. LessMore
Existence COMPULSORY
Validation RulesData contains of any character.
-
JSON typeString
-
minimum length2
-
maximum length50
Your customer email address. LessMore
Existence COMPULSORY
Validation RulesData must be a valid email address.
-
JSON typeString
-
minimum length3
-
maximum length50
Your customer phone number. LessMore
Existence COMPULSORY
Validation RulesData must be a valid phone number.
-
JSON typeString
-
minimum length9
-
maximum length15
Your customer street address. LessMore
Existence COMPULSORY
Validation RulesData contains any character.
-
JSON typeString
-
minimum length2
-
maximum length200
Your customer billing city. LessMore
Existence COMPULSORY
Validation RulesData contains any character.
-
JSON typeString
-
minimum length2
-
maximum length200
Your customer billing state. LessMore
Existence COMPULSORY
Validation RulesData contains any character.
-
JSON typeString
-
minimum length2
-
maximum length50
Your customer billing zipcode. LessMore
Existence COMPULSORY
Validation RulesData contains any character.
-
JSON typeString
-
minimum length3
-
maximum length8
Your customer billing country. e.g BD or BGD LessMore
Existence COMPULSORY
Validation RulesMust be an ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 country code.
-
JSON typeString
-
minimum length2
-
maximum length3
Your shipping details.
Your customer shipping name. LessMore
Existence COMPULSORY
Validation RulesData contains of any character.
-
JSON typeString
-
minimum length2
-
maximum length50
Your customer shipping email address. LessMore
Existence COMPULSORY
Validation RulesData must be a valid email address.
-
JSON typeString
-
minimum length3
-
maximum length50
Your customer shipping phone number. LessMore
Existence COMPULSORY
Validation RulesData must be a valid phone number.
-
JSON typeString
-
minimum length9
-
maximum length15
Your customer shipping street address. LessMore
Existence COMPULSORY
Validation RulesData contains any character.
-
JSON typeString
-
minimum length2
-
maximum length200
Your customer shipping city. LessMore
Existence COMPULSORY
Validation RulesData contains any character.
-
JSON typeString
-
minimum length2
-
maximum length200
Your customer shipping state. LessMore
Existence COMPULSORY
Validation RulesData contains any character.
-
JSON typeString
-
minimum length2
-
maximum length50
Your customer shipping zipcode. LessMore
Existence COMPULSORY
Validation RulesData contains any character.
-
JSON typeString
-
minimum length3
-
maximum length8
Your customer shipping country. e.g BD or BGD LessMore
Existence COMPULSORY
Validation RulesMust be an ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 country code.
-
JSON typeString
-
minimum length2
-
maximum length3
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
201ShowHide -
{ "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 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_idThe existing invoice id for the transaction.
@amountThe original amount of the invoice. -
HTTP MethodGET
-
Authentication
This operation requires authentication via Bearer token:
Bearer token has a
base64of appkey and a token adhered by a colon. The token containsmd5hash 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
200ShowHide -
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" } ] } }
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 MethodGET
-
Authentication
This operation requires authentication via Bearer token:
Bearer token has a
base64of appkey and a token adhered by a colon. The token containsmd5hash 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
200ShowHide -
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
Sandbox endpointhttps://api-sandbox.portpos.com/payment/v2/invoice
Live endpointhttps://api.portpos.com/payment/v2/invoice
Request body should be valid JSON format
-
HTTP MethodPOST
-
Authentication
This operation requires authentication via Bearer token:
Bearer token has a
base64of appkey and a token adhered by a colon. The token containsmd5hash 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.
1 to enable the discount and 0 to disable. LessMore
Existence COMPULSORY
Validation Rules0 or 1.
-
JSON typeInteger
-
minimum length0
-
maximum length1
The discount code you have created in the PortPos discount panel. Maximum items could be 10. LessMore
Existence OPTIONAL
Validation Rules0 or 1.
-
JSON typeArray
-
minimum1
-
maximum100
- Response
201ShowHide -
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" } ] } }
For EMI, you have to generate an invoice using the below additional parameters.
Sandbox endpointhttps://api-sandbox.portpos.com/payment/v2/invoice
Live endpointhttps://api.portpos.com/payment/v2/invoice
Request body should be valid JSON format
-
HTTP MethodPOST
-
Authentication
This operation requires authentication via Bearer token:
Bearer token has a
base64of appkey and a token adhered by a colon. The token containsmd5hash 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.
1 to enable EMI and 0 to disable. LessMore
Existence COMPULSORY
Validation Rules0 or 1.
-
JSON typeInteger
-
minimum length0
-
maximum length1
The emi tenures. Maximum items could be 10. LessMore
Existence OPTIONAL
Validation Rules0 or 1.
-
JSON typeArray
-
minimum0
-
maximum60
- Response
201ShowHide -
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 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_idThe invoice id want to issue a refund for. -
HTTP MethodPOST
-
Authentication
This operation requires authentication via Bearer token:
Bearer token has a
base64of appkey and a token adhered by a colon. The token containsmd5hash 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.
The amount you want to refund. LessMore
amount can not be more than the original invoice amount.
Existence COMPULSORY
Validation RulesData is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
-
JSON typeString
-
minimum length0.1
-
maximum length99999999
The currency of the invoice expressed as an ISO 4217 alpha code, e.g. BDT or USD. LessMore
Existence COMPULSORY
Validation RulesData must consist of the characters A-Z
-
JSON typeString
-
minimum length3
-
maximum length3
- Response
202ShowHide -
Sample response
{ "data": { "order": { "invoice": "85BC30171EA29531", "amount": "3393.00", "currency": "BDT", "status": "REFUND_PENDING" }, "refund": { "amount": 100, "status": "APPROVED" } }, "result": "SUCCESS" }
Status codes
- Codes
-
- 200
-
OK
- 201
-
Created
- 202
-
Accepted
- 400
-
Bad Request
- 404
-
Not Found
- 500
-
Internal Service Error
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 MethodPOST
-
Parameters
invoiceThe invoice with which the transaction was performedamountThe amount of the transactionstatusThe status of the transactionreferenceThe 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.
