API Reference
This reference section provides in-depth integration details of the TLPE API.
Environments
There are two environments of TLPE: TEST and LIVE.
| Environment | URL |
|---|---|
| TEST | https://test-api.tlpe.io |
| LIVE | https://api.tlpe.io |
Security/Authentication
All requests must be sent over SSL.
All requests are authenticated against an Authorization header with an access token and IP whitelisting.
Versioning
All changes made to the API are backwards compatible, hence any major features that are
released, that would otherwise break existing implementations, will be released using a new
version.
HTTP Status Codes
For each request you send to our API the HTTP status code of the response will already tell you
the basic result.
| Status | Description |
|---|---|
| 200 | Successful request |
| 400 | Bad request. This might either point to a malformed syntax or values sent that cannot be understood by the system. |
| 401 | Unauthorized. Invalid authorization header provided, or IP not whitelisted. |
| 403 | Forbidden. Invalid access token provided or accessing restricted URL. |
| 404 | Not found. Requested resource or endpoint is not found. i.e., Endpoint/URL does not exist or has expired. This can also be caused by typographical errors. |
| 422 | Unprocessable Entity. Caused by invalid parameter values being sent. |
| 500 | Internal Server Error. A system errors. |
| 503 | Service Unavailable. Indicates that a server is not ready to handle the request. |
For payments and transaction related, more fine-grained information to find out why a payment failed can be found in the response and error messages.
Transaction Body Payload Data
| Parameter Name | Required? | Description | Format |
|---|---|---|---|
| credit_card | Conditional1 | Customer card information that is only required for direct or server-to-server integration. | Refer to Card Data table |
| first_name | Required | Customer's first name | Alphabet, hyphen, period, spaces {1-50} |
| last_name | Required | Customer's last name | Alphabet, hyphen, period, spaces {1-50} |
| billing_address | Required | Address where the transaction will be billed | Refer to Billing Address Data table |
| shipping_address | Optional | Address where the items will be delivered | Refer to Shipping Address Data table |
| contact | Required | Customer's contact information | Refer to Contact Data table |
| payment | Required | Transaction related information | Refer to Payment Data table |
| route | Required | Integrator and customer communication | Refer to Route Data table |
| 3d_secure | Conditional2 | Contains device footprint and is only required for card brands and | Refer to 3D Secure Data table |
| time_offset | Required | Client time zone | ±[HH]:[MM] |
| customer_ip_address | Conditional3 | Client IP Address | IP Address |
¹credit_card object is required for direct or server-to-server integration
²3d_secure object is required for direct or server-to-server integration that is 3ds 2.0 enabled account
3parameter may be required for some integration or payment brands
Card Data
| Parameter Name | Required? | Description | Format |
|---|---|---|---|
| card_holder_name | Required | Full name of card holder | Alphabet |
| number | Required | Card number detail | Numeric {15-16} |
| expiration_month | Required | Month of card expiration | Numeric {2} |
| expiration_year | Required | Year of card expiration | Numeric {2} |
| cvv | Required | Card security code | Numeric {3-4} |
Route Data
| Parameter Name | Required? | Description | Format |
|---|---|---|---|
| callback_url | Conditional1 | Integrator’s URL where customer will be redirected after payment | https://{domain}/{path} |
| notify_user | Optional | Flag for sending email to customer | true or false |
¹callback_url is required for checkout payment integration and direct or server-to-server integration
with 3ds enabled accounts
Billing Address Data
| Parameter Name | Required? | Description | Format |
|---|---|---|---|
| line1 | Required | House/Lot No., Building, Street | Alphanumeric, special characters {1-80} |
| line2 | Required | Area, District, or additional address line | Alphanumeric, special characters {1-80} |
| city_municipality | Required | City address | Alphanumeric {1-60} |
| zip | Required | Postal code | Alphanumeric, hyphen, period {1-10} |
| state_province_region | Required | State, province, or region | Alphanumeric {1-40} |
| country_code | Required | 2-digit country code | ISO 3166-1 Alpha-2 code |
Shipping Address Data
| Parameter Name | Required? | Description | Format |
|---|---|---|---|
| line1 | Required | Billing/Shipping Address line 1 | Alphanumeric, special characters {1-80} |
| line2 | Required | Billing/Shipping Address line 2 | Alphanumeric, special characters {1-80} |
| city_municipality | Required | Billing/Shipping city or municipality address | Alphanumeric {1-60} |
| zip | Required | Billing/Shipping zip code | Alphanumeric, hyphen, period {1-10} |
| state_province_region | Required | Billing/Shipping state, province, or region | Alphanumeric {1-40} |
| country_code | Required | Billing/Shipping country 2-digit code | ISO 3166-1 Alpha-2 code |
Contact Data
| Parameter Name | Required? | Description | Format |
|---|---|---|---|
| Required | Customer's email address | Valid email address | |
| mobile | Conditional1 | Customer's mobile number | Numeric |
¹some payment methods or connectors requires mobile number
Payment Data
| Parameter Name | Required? | Description | Format |
|---|---|---|---|
| description | Optional | Transaction or item description | Alphanumeric {1-200} |
| amount | Required | Transaction amount | Decimal number |
| currency | Required | 3-digit currency code | ISO 4217 standard |
| option | Required | Generated token from /options endpoint | Alphanumeric (token) |
| merchant_reference_id | Required | Integrator’s own reference number | Alphanumeric {1-45} |
| other_references | Optional | Integrator’s other reference number/s | Alphanumeric {1-45} |
3D Secure Data
The following parameters should be coming from the device footprint where the transaction is being processed.
Parameter Name
Required?
Format
timezone
Conditional1
±[HH][MM]
browser_color_depth
Required
Numeric
browser_language
Required
Alphanumeric, special characters
browser_screen_height
Required
Numeric
browser_screen_width
Required
Numeric
os
Required
Alphanumeric
browser_accept_header
Required
Alphanumeric, special characters
user_agent
Required
Alphanumeric, special characters
browser_javascript_enabled
Required
true or false
browser_java_enabled
Required
true or false
accept_content
Required
Alphanumeric, special characters
¹some payment methods or connectors requires this in the request payload.
with 3ds enabled accounts
Notify Status Payload Body Claims
Parameter Name
Description
iss
Issuer – claim identifies the principal that issued the JWT
sub
Subject – claim identifies the principal that is the subject of the JWT
aud
Audience – claim identifies the recipients that the JWT is intended for
exp
Expiration Time – claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing
iat
Issued at – claim identifies the time at which the JWT was issued
jti
JWT ID – claim provides a unique identifier for the JWT
first_name
Customer’s first name provided for the transaction
last_name
Customer’s last name provided for the transaction
email
Customer’s email provided for the transaction
mobile
Customer's contact number provided for the transaction
billing_address
Address where the transaction will be billed
shipping_address
Address where the transaction will be shipped
amount
Total amount of transaction
currency
Currency of the transaction
option
Payment option used to pay for the transaction
description
Transaction or item description
merchant_reference_id
Integrator provided reference number of the transaction
other_references
Integrator provided reference number of the transaction
status_code
Status code of the payment transaction
message
Status message of the payment transaction
timestamp
Date and time of the payment for the transaction in UTC
transaction_id
TLPE generated transaction reference number
custom_parameters
Other custom parameters passed for the transaction
Response Status Codes
Status Code
Description
OK.00.00
Payment Successful
OK.00.10
Payment Pending
OK.01.00
Waiting for payment (Checkout)
OK.02.00
Full Refund Successful
OK.02.10
Full Refund Pending
OK.03.00
Full Refund Waiting
OK.04.00
Partial Refund Successful
OK.04.10
Partial Refund Pending
OK.05.00
Partial Refund Waiting
OK.06.00
Reversal Successful
OK.06.10
Reversal Pending
OK.07.00
Reversal Waiting
OK.08.10
Preauthorization Pending
OK.08.00
Preauthorization Successful
OK.09.00
Capture Successful
Error Codes
Error Code
Description
ER.00.00
Payment Failed
ER.01.00
Internal Error
ER.01.10
Internal unauthorized
ER.01.20
Internal bad request
ER.01.30
Internal invalid request
ER.01.40
Internal timeout
ER.02.00
Client Error
ER.02.10
Client unauthorized
ER.02.20
Client bad request
ER.02.30
Client invalid request
ER.02.40
Client timeout
ER.03.00
Server Error
ER.03.10
Server unauthorized
ER.03.20
Server bad request
ER.03.30
Server invalid request
ER.03.40
Server timeout
ER.20.00
Refund Failed
ER.20.10
Transaction not refundable
ER.20.20
Transaction already refunded
ER.20.30
Invalid refund amount
ER.20.40
Maximum refund request count exceeded
ER.20.50
Transaction has pending refunds
ER.20.60
Insufficient refundable amount
ER.30.00
Reversal Failed
ER.30.10
Transaction not reversable
ER.30.20
Transaction already reversed
ER.40.00
Preauthorization Failed
Test Cards
Card Brand
Card Number
Card Expiry
CVV
American Express
3411 111111 11111
Any future date
1234
China UnionPay
6250947000000014
Mobile #: +852 11112222
Any future date
123
SMS Code: 111111/123456
MasterCard
5105 1051 0510 5100
Any future date
Any 3-digit code
MasterCard (3D)
5204 2427 5008 5996
Any future date
Any 3-digit code
Visa
4111 1111 1111 1111
Any future date
Any 3-digit code
Visa (3D)
4000 0000 0000 1091
Any future date
Any 3-digit code
Visa (3D2)
4200 0000 0000 0000
Any future date
Any 3-digit code
Diners Club International
3696 190300 0009
Future date
123
Discover Card Network
6011492100005191
Future date
123
Postman Collection
Collection
Endpoint
TLPE Integration
/Options
TLPE Integration
/Checkout
TLPE Integration
/Payment
TLPE Integration
/EPL
TLPE Integration
/Refund
TLPE Integration
/Sync
TLPE Integration
/All
The following parameters should be coming from the device footprint where the transaction is being processed.
| Parameter Name | Required? | Format |
|---|---|---|
| timezone | Conditional1 | ±[HH][MM] |
| browser_color_depth | Required | Numeric |
| browser_language | Required | Alphanumeric, special characters |
| browser_screen_height | Required | Numeric |
| browser_screen_width | Required | Numeric |
| os | Required | Alphanumeric |
| browser_accept_header | Required | Alphanumeric, special characters |
| user_agent | Required | Alphanumeric, special characters |
| browser_javascript_enabled | Required | true or false |
| browser_java_enabled | Required | true or false |
| accept_content | Required | Alphanumeric, special characters |
¹some payment methods or connectors requires this in the request payload.
with 3ds enabled accounts
Notify Status Payload Body Claims
| Parameter Name | Description |
|---|---|
| iss | Issuer – claim identifies the principal that issued the JWT |
| sub | Subject – claim identifies the principal that is the subject of the JWT |
| aud | Audience – claim identifies the recipients that the JWT is intended for |
| exp | Expiration Time – claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing |
| iat | Issued at – claim identifies the time at which the JWT was issued |
| jti | JWT ID – claim provides a unique identifier for the JWT |
| first_name | Customer’s first name provided for the transaction |
| last_name | Customer’s last name provided for the transaction |
| Customer’s email provided for the transaction | |
| mobile | Customer's contact number provided for the transaction |
| billing_address | Address where the transaction will be billed |
| shipping_address | Address where the transaction will be shipped |
| amount | Total amount of transaction |
| currency | Currency of the transaction |
| option | Payment option used to pay for the transaction |
| description | Transaction or item description |
| merchant_reference_id | Integrator provided reference number of the transaction |
| other_references | Integrator provided reference number of the transaction |
| status_code | Status code of the payment transaction |
| message | Status message of the payment transaction |
| timestamp | Date and time of the payment for the transaction in UTC |
| transaction_id | TLPE generated transaction reference number |
| custom_parameters | Other custom parameters passed for the transaction |
Response Status Codes
| Status Code | Description |
|---|---|
| OK.00.00 | Payment Successful |
| OK.00.10 | Payment Pending |
| OK.01.00 | Waiting for payment (Checkout) |
| OK.02.00 | Full Refund Successful |
| OK.02.10 | Full Refund Pending |
| OK.03.00 | Full Refund Waiting |
| OK.04.00 | Partial Refund Successful |
| OK.04.10 | Partial Refund Pending |
| OK.05.00 | Partial Refund Waiting |
| OK.06.00 | Reversal Successful |
| OK.06.10 | Reversal Pending |
| OK.07.00 | Reversal Waiting |
| OK.08.10 | Preauthorization Pending |
| OK.08.00 | Preauthorization Successful |
| OK.09.00 | Capture Successful |
Error Codes
| Error Code | Description |
|---|---|
| ER.00.00 | Payment Failed |
| ER.01.00 | Internal Error |
| ER.01.10 | Internal unauthorized |
| ER.01.20 | Internal bad request |
| ER.01.30 | Internal invalid request |
| ER.01.40 | Internal timeout |
| ER.02.00 | Client Error |
| ER.02.10 | Client unauthorized |
| ER.02.20 | Client bad request |
| ER.02.30 | Client invalid request |
| ER.02.40 | Client timeout |
| ER.03.00 | Server Error |
| ER.03.10 | Server unauthorized |
| ER.03.20 | Server bad request |
| ER.03.30 | Server invalid request |
| ER.03.40 | Server timeout |
| ER.20.00 | Refund Failed |
| ER.20.10 | Transaction not refundable |
| ER.20.20 | Transaction already refunded |
| ER.20.30 | Invalid refund amount |
| ER.20.40 | Maximum refund request count exceeded |
| ER.20.50 | Transaction has pending refunds |
| ER.20.60 | Insufficient refundable amount |
| ER.30.00 | Reversal Failed |
| ER.30.10 | Transaction not reversable |
| ER.30.20 | Transaction already reversed |
| ER.40.00 | Preauthorization Failed |
Test Cards
| Card Brand | Card Number | Card Expiry | CVV |
|---|---|---|---|
| American Express | 3411 111111 11111 | Any future date | 1234 |
| China UnionPay | 6250947000000014 Mobile #: +852 11112222 |
Any future date | 123 SMS Code: 111111/123456 |
| MasterCard | 5105 1051 0510 5100 | Any future date | Any 3-digit code |
| MasterCard (3D) | 5204 2427 5008 5996 | Any future date | Any 3-digit code |
| Visa | 4111 1111 1111 1111 | Any future date | Any 3-digit code |
| Visa (3D) | 4000 0000 0000 1091 | Any future date | Any 3-digit code |
| Visa (3D2) | 4200 0000 0000 0000 | Any future date | Any 3-digit code |
| Diners Club International | 3696 190300 0009 | Future date | 123 |
| Discover Card Network | 6011492100005191 | Future date | 123 |
Postman Collection
| Collection | Endpoint |
|---|---|
| TLPE Integration | /Options |
| TLPE Integration | /Checkout |
| TLPE Integration | /Payment |
| TLPE Integration | /EPL |
| TLPE Integration | /Refund |
| TLPE Integration | /Sync |
| TLPE Integration | /All |