Protocol Rules

Example Secure Payment APIs Security: Encrypted Data

The Example Secure Payment APIs protect all HTTPS Request and Response data according to PCI and PII standards with the AES-GCM encryption external link icon (Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM) as a Transport Layer Security (TLS) authenticated encryption operation). Please see the Protocol Rules "AES-GCM encrypted request and response data" section for these and other Example Secure Payment API security-related details.

The API is implemented as a RESTful (Representational State Transfer) API.

Click a topic to expand/collapse it.

Resource URL description

Resource URL syntax
Syntax: {HTTPS_METHOD} https://{host}/{resourcepath}?{parameter}
Item Description Example
{HTTPS_METHOD} One of several HTTPS Methods used in the API. GET, PUT, POST, DELETE
https://{host} The host address. https://127.0.0.1
{resourcepath} The resource path. Note: a resource is one of the
API endpoints described in the "Payment API
endpoints overview" in the Introduction page. 		/billing/
89396B99-5A57
-4ECA-96C9-
60ED109F8C8A
/transactions
{parameter} Parameters (optional) ?data=3230313530393
2323136313733306330
6261373832326330383
9e61251256b1bd3583b
2f02642a2e678debda2
f67a685d3e56e034f8
Request URL example:
GET https://127.0.0.1/billing/
89396B99-5A57-4ECA-96C9-60
ED109F8C8A/transactions?
data=323031353039323231363
13733306330626137383232633
03839e61251256b1bd3583b2f0
2642a2e678debda2f67a685d3e
56e034f8

Return to top

Request and Response examples

Request examples
Using the HTTPS POST Method 
POST https://{host}/{resourcepath}
 
"Content-Type: application/x-www-form-urlencoded"
"Authorization: PLTOKEN {TOKEN}"
 
data={Encrypted Request Data}
Using the HTTPS GET Method 
GET https://{host}/{resourcepath}?data={Encrypted Request Data}
 
"Authorization: PLTOKEN {TOKEN}"
Response example
HTTPS Status Code XXX
{Encrypted Response Data}

Return to top

AES-GCM encrypted request and response data

To tighten up security, all request and response data should be encrypted.

HTTPS Request data
All HTTPS Request data should have an encrypted string format. The encrypted request data has the following form: 
PCNG Encrypt Function (Key, Data) = Encrypted Request Data
HTTPS Response data
The client should decrypt the response data in order to verify the result. 
PCNG Decrypt Function (Key, Data) = Decrypted Response Data
Examples
GET Transactions
  • URL : GET https://127.0.0.1/billing/{UUID}/transactions?data={data}
  • UUID : 187b2be8-24fb-4892-b16a-7d84d1d0fe83
  • data : pageNo=1&pageSize=10&fromDate=20150101&toDate=20150831
Step 1. Encrypt UUID
PCNG Encrypt Function (Key, UUID) =
"3230313530393233313033333034
663036386562316461373432ab97d
c062040796e4943cb9a2e31ab493f
4c10cc670de4d840469a7b771b59e
9432b48b69fe6dd19c41675e4ccda
06966216f1678838"
PCNG Encrypt Function (Key, Data) =
32303135303932323136313733306
33062613738323263303839e61251
256b1bd3583b2f02642a2e678debd
a2f67a685d3e56e034f8
Step 2. Send Request
URL : GET
https://127.0.0.1/billing/
323031353039323331303333303466
3036386562316461373432ab97dc06
2040796e4943cb9a2e31ab493f4c1c
c670de4d840469a7b771b59e9432b4
8b69fe6dd19c41675e4ccda0696621
6f1678838/transactions?
data=3230313530393232313631373
330633062613738323263303839e61
251256b1bd3583b2f02642a2e678de
bda2f67a685d3e56e034f8
Step 3. Decrypt Response
Success Case 
3230313530393233313033333432
353433313832636138663238864934
fe9dd274394853102e05b1d5028626
dfb9f23ae17cc4f8c4060b20844036
747de4a96d7d876ca639a7e83fae26
e3e82bfa0f5d7371096a7bac8a95f5
c0c23fa363d6dbd285227c33db95f1
98f5c2f797d24d4a7f8bcc43bb9391
b0c4561a10c80f880d8f0f82b1c45b
58aa3db8f9ba
PCNG Decrypt Function (Key, Success Response Data)
{
  "orderID": "83C2A1E7-BF50-440C-AB94-DF24E0533145",
  "applicationId": "ABC",
  "amount": 10,
  "currencyCode": "GBP",
  "ipAddr": "1.1.1.1",
  "paymentInfoID": "517c654b-e956-49e5-a0c5-4d6de609b6dd",
  "paymentInfo": {
    "paymentType": "CreditCard",
    "card": {
      "cardCVVEncKey": "94b2d1f484d3410b90b1d7d52d3479ea"
    }
  }
}
Failure Case
3230313530393233313033363433383
8653338313235323039618016d11daa43e01
68437b21d16cb8acbbe46ed66b125248d30c
bcf47a327097deeca14bb9004f1fb3872338
134ca82bc18875fef763ef05d92c84e76bda
4aa9bd4223b6d6f0a678f6fa32cf97e21759
59806df5dffd93dca8d6acd854ed17fd0d5a6
PCNG Decrypt Function (Key, Failure Response Data)
{
  "error": {
    "code": 997,
    "message": "The request is invalid.",
    "detail": "Invalid uuid"
  }
}
Create Billing Transaction
URL : POST https://127.0.0.1/billing/{uuid}/transaction
Request Data
{
  "orderID": "83C2A1E7-BF50-440C-AB94-DF24E0533145",
  "applicationId": "ABC",
  "amount": 10,
  "currencyCode": "GBP",
  "ipAddr": "1.1.1.1",
  "paymentInfoID": "517c654b-e956-49e5-a0c5-4d6de609b6dd",
  "paymentInfo": {
    "paymentType": "CreditCard",
    "card": {
      "cardCVVEncKey": "94b2d1f484d3410b90b1d7d52d3479ea"
    }
  }
}
Step 1. Encrypt Content
PCNG Encrypt Function (Key, Request Data) =
"323031353039323331303333303466303638
6562316461373432ab97dc062040796e4943c
b9……”
Step 2. Send Request
URL : POST https://127.0.0.1/billing/3230313530393.../transaction
Content-Type : application/x-www-form-urlencoded
Content: 
data=323031353039323331303333303466
3036386562316461373432ab97dc06204079
6e4943cb9……
Step 3. Decrypt Response
Success Case 
323031353039323331303530353363343937
3632326336613936c00d50a2157b281e6360
7ef843a87d10cf05cd4669fde2b8cafa3f3c
8fc1f5f57771e6ee6f3f653d869bcd4f0151
3230f933b4a8502f00ff1a608367064b803f
af0ed02d06ecd928f18b0c15f055116c4bff
c9dd711e5eb150f7757d6132206020605d6c
85605e5e34…
PCNG Decrypt Function (Key, Success Response Data)
{
  "data": {
    "uuid": "187b2be8-24fb-4892-b16a-7d84d1d0fe83",
    "orderID": "939da16f-a4ac-4c15-86cb-3dc9602197d4",
    "transactionID": "201509230000066",
    "amount": 10,
    "currencyCode": "GBP",
    "paymentDate": "23/09/2015 10:51:22",
    "paymentInfo": {
      "paymentType": "creditcard",
      "card": {
        "cardBrand": "Visa",
        "cardLastNum": "1881"
      }
    }
  }
}
Failure Case
32303135303932333130333634333838
653338313235323039618016d11daa43e0168
437b21d16cb8acbbe46ed66b125248d30cbcf
47a327097deeca14bb9004f1fb3872338134c
a82bc18875fef763ef05d92c84e76bda4aa9b
d4223b6d6f0a678f6fa32cf97e2175959806d
f5dffd93dca8d6acd854ed17fd0d5a6
PCNG Decrypt Function (Key, Failure Response Data)
{
  "error": {
    "code": 997,
    "message": "The request is invalid.",
    "detail": "Invalid uuid"
  }
}

Return to top

Response data type

All HTTPS Responses will return an AES-GCM encrypted string in the following format.

32303135303932323136313733306330626
13738323263303839e61251256b1bd3583b2f02642a
2e678debda2f67a685d3e56e034f827047c583ac13a
76dc69c498e2a92789a9bf644c3f6a1ab07859646a8
87827189e452fd1e94f3faf6061cdf42297b6b2e981
b8c9b40e5c7ac98a534439a32d32df42a68ceb19226
2a8fb3872cc4b20ad3d5aa5cbba95b8eba26e45b302
b8d796f29e37e65575ec41d1b2be67d88404fa225aa
6e999274b563f7b2c207c3

To verify a response, you should decrypt the response data. If the response data is successfully decrypted, you can confirm the JSON data. 

{
  "data": {
    "authTransID": "E37C8425-B947-4EB3-903C-8E44E916DDFD",
    "authDate": "12/11/2015 10:01:01"
  }
}

Return to top

How to verify HTTPS Response data

If you decrypt HTTPS Response string data:

  • The success response has a "data" object.
  • The fail response has an "error" object.

A HTTPS Status Code of 200 or 201 means successful transactions; otherwise a different code means a failed transaction.

  • In the case of a failed transaction, you should refer to the "error" object which includes a relevant error description.
  • Eventually, you should double check the validation of the transaction by checking if the HTTPS Status Code is "200" and has a "data" object.
Success case : HTTPS Status Code = 200 AND a data object.
200 OK
{
  "data": {
    "authTransID": "E37C8425-B947-4EB3-903C-8E44E916DDFD",
    "authDate": "12/11/2015 10:01:01"
  }
}
Failure case : HTTPS Status Code != 200 AND has an error object.
404 Not Found
{
  "error": {
    "code": 901,
    "message": "This account (89396B99-5A57-4ECA-96C9-60ED109F8C8A) does not exist.",
    "detail" : null
  }
}

Return to top

Security (HMAC Authentication)

A. The Authentication Header using API Key Authentication

This RESTful API uses the HTTPs Authorization header to pass authentication information. The Authorization header has the following form:

Authorization : PLTOKEN {APP_ID}:{Signature}:{Nonce}:{Timestamp}
"PLTOKEN"
This is a predefined custom scheme by Example for an Authorization header. (Not changed.)
"APP_ID" and "APP_KEY"
These will be provided by Example. APP_ID is public. BUT, APP_KEY should ONLY be shared between Example and Example.
"Signature"
This is a hashed value produced by using the HMAC-SHA256 algorithm.
"Nonce"
This is generated at Client and should be a unique value on each request. Example receives the request and checks to prevent a replay attack.
  • Example will cache Nonce during a period of 5 minutes. Therefore, a request that has the same Nonce will be rejected during those 5 minutes.
  • Nonce should be generated as a unique value.
"Timestamp"
This is calculated using a UNIX timestamp based on UTC Time to overcome different Time Zone issues between Client and Server.
  • Note: If the time gap is longer than 5 minutes, your request will be failed.
B. Constructing the Signature

Note: Please keep the order of the parameters and their encoding as shown in the following diagram.

Authorization = "PLTOKEN" + " " + "APP_ID" + ":" + Signature + ":" + Nonce + ":" + Timestamp
 
Signature = Base64 ( HMAC-SHA256 (Decode(APP_KEY) , UTF-8-Encoding ( RequestString ) ) )
 
RequestString = APP_ID +
                Request-HTTPS-Method +
                URI-Encoding( LowerCase ( Request-Uri) ) ) +
                UNIX-Timestamp +
                Nonce +
                Base64( MD5 ( Request-Content) ) )
C. HTTPS Request example
Request
GET https://127.0.0.1/account/89396B99-5A57-4ECA-96C9-60ED109F8C8A/paymentinfo
Credential (Note: The following credential is an example. Please do not use it.)
APP_ID : 44f0878d9bc947e6a4be54aec17632a5
APP_KEY : 6cuzw6qG3vsJ3DIEm+PmJe37Jm1ceOmyUIj2T18VWYHA=

Please see the following steps:

Step 1.
Generate the UUID as a Nonce.
Step 2.
Calculate the Unix Time stamp based on UTC Now.
Step 3.
Make the Signature.
Field Value
APP_ID 44f0878d9bc947e6
a4be54aec17632a5
Request-HTTPS-Method GET
URI-Encoding
(LowerCase(Request-Uri))) 
https%3a%2f%2f127.0.0.1
%2faccount%2f9396b99-5
a57-4eca-96c9-60ed109f
8c8a%2fpaymentinfo
UNIX-Timestamp 1441009867
Nonce 27071fad-ad4d-4abe
-b250-7a20679cd1e3
Base64
(MD5(Request-Content))) 		-
Make "RequestString" concatenate values: 
RequestString =
44f0878d9bc947e6a4be54aec17632a5GEThttp
%3a%2f%2f127.0.0.1%2faccount%29396b99-5
a57-4eca-96c9-60ed109f8c8a%2fpaymentinfo
144100986727071fad-ad4d-4abe-b250-7a2067
9cd1e3
Make a "Signature" hashing of the above RequestString using APP_KEY: 
Signature = 0/V3xVN8rzfU8fj6lLTSIHF
co9NnXBXVGHlKIkiwKUc=
Step 4.
Add the "Authorization Header" to the Request 
Authorization: PLTOKEN
44f0878d9bc947e6a4be54aec17632a5:0/V3x
VN8rzfU8fj6lLTSIHFco9NnXBXVGHlKIkiwKUc
=:27071fad-ad4d-4abe-b250-7a20679cd1e3
:1441009867

Return to top

Error Handling (HTTPS Status Codes and Error object)

When the API encounters any errors, the corresponding HTTPS Status Code and Error Object will be returned in the following JSON format:

HTTPS Status Code XXX
  {
    error{
      "code": (Error code),
      "message": "(Error description)",
      "details": "(Additional details about the error)"
    }
}

Common Error Code list

Code Message Name Message HTTPS Status Code
901 ACCOUNT_NOTFOUND_ERR This account does not exist.
Cannot find related account by requested uuid. 		404: Not Found
903 PAYMENTINFO_NOTFOUND_ERR This account's payment information does not exist.
Cannot find related payment method by requested uuid and pmid. 		404: Not Found
911 TRANSACTION_NOTFOUND_ERR This account does not have transactions.
Cannot find related transactions. 		404: Not Found
912 REQUEST_NOTFOUND_ERR Request does not exist.
Cannot find related request log from mobile client. 		404: Not Found
932 PAYMENTINFO_VERIFICATION_PSP_ERR PSP verification processing failed.
Detailed information about the reason of failure (PSP error etc.).
Payment Service Provider returns error when verifying the payment method.
"detail" attribute describes the reason of failure. 		400: Bad Request
933 PAYMENTINFO_CREATE_ERR Failed to create payment information.
Error occurred in Example process while user creates a payment method.
"detail" attribute describes the reason of failure. 		400: Bad Request
934 PAYMENTINFO_UPDATE_ERR Failed to update payment information.
Error occurred in the Example process while user updates payment method.
"detail" attribute describes the reason of failure. 		400: Bad Request
935 PAYMENTINFO_DELETE_ERR Failed to delete payment information.
Error occurred in the Example process while user deletes payment method. 		400: Bad Request
936 PAYMENT_CREATE_ERR Failed to create payments.
Error occurred in Example process while user creates payment transaction. 		400: Bad Request
937 PAYMENTINFO_REVERIFY_ERR Failed to re-verify payment information.
Error occurred in Example process while user re-verifies payment method. 		400: Bad Request
938 PAYMENT_CREATE_PSP_FAIL_ERR PSP payment processing failed.
Payment Service Provider returns error when authorizing payment transaction.
Detailed information about the reason of failure (PSP error etc.).
"detail" attribute describes reason of failure. 		400: Bad Request
939 PAYMENT_CHECK_ERR Failed to check to create payments.
Error occurred in Example process while checking 3DS and Sphonic. 		400: Bad Request
940 PAYMENT_PSP_ROUTER_ERR There is no available Payment Service Provider. Please try again.
Error is occurred in the Example process while routing PSP. 		400: Bad Request
941 PAYMENT_PAYOUT_ERR Failed to payout payments.
Error occurred in Example process while CORE makes payout transaction. 		400: Bad Request
942 PAYMENT_PAYOUT_PSP_ERR PSP payout processing is failed.
Error occurred in Example process while CORE makes payout transaction.
"detail" attribute describes reason of failure. 		400: Bad Request
943 PAYMENT_REFUND_ERR Failed to refund payments
Error occurred in Example process while CORE makes refund transaction. 		400: Bad Request
944 PAYMENT_REFUND_PSP_ERR PSP refund processing is failed.
Detailed information about the reason of failure (PSP error etc.) is provided.
Error occurred in a Example process while CORE makes refund transaction.
"detail" attribute describes reason of failure. 		400: Bad Request
945 PAYMENT_3DS_PSP_ERR PSP 3DS processing is failed.
Detailed information about the reason of failure (PSP error etc.) is provided.
Payment Service Provider returns error when proceeding with the 3DS process.
"detail" attribute describes reason of failure. 		400: Bad Request
946 PAYMENT_PSP_TIMEOUT PSP Timeout.
Connection with the Payment Service Provider has timed out. 		400: Bad Request
947 PAYMENT_REJECT_ERR Failed to reject payment.
Error occurred in the Example process while CORE makes a reject transaction. 		400: Bad Request
949 PAYMENTINFO_CANCEL_ERR Request is canceled by the mobile client.
Mobile client made a request using a canceled orderId. 		400: Bad Request
950 PAYMENT_CANCEL_ERR Request is canceled by the mobile client.
Mobile client made a request using a canceled orderId. 		400: Bad Request
974 PAYMENTINFO_CREATE_FAIL_ERR An unexpected error occurred during create account payment information.
Please try again.
Unexpected error occurred in Example process while user creates payment method. 		500: Internal Server Error
975 PAYMENTINFO_UPDATE_FAIL_ERR An unexpected error occurred during update account payment information.
Please try again.
Unexpected error occurred in Example process while user updates payment method. 		500: Internal Server Error
976 PAYMENTINFO_DELETE_FAIL_ERR An unexpected error occurred during delete account payment information.
Please try again.
Unexpected error occurred in Example process while user deletes payment method. 		500: Internal Server Error
979 PAYMENTINFO_REVERIFY_FAIL_ERR An unexpected error occurred during re-verify account payment information.
Please try again.
Unexpected error occurred in Example process while user reverifies payment method. 		500: Internal Server Error
981 PAYMENT_CHECK_FAIL_ERR An unexpected error occurred during check create payment.
Please try again.
Unexpected error occurred in Example process while checking 3DS and Sphonic. 		500: Internal Server Error
982 PAYMENT_CREATE_FAIL_ERR An unexpected error occurred during create payment.
Please try again.
Unexpected error occurred in Example process while user creates payment transaction. 		500: Internal Server Error
984 PAYOUT_CREATE_FAIL_ERR An unexpected error occurred during payout payment.
Please try again.
Unexpected error occurred in Example process while CORE makes payout transaction. 		500: Internal Server Error
985 PAYMENT_REFUND_FAIL_ERR An unexpected error occurred during refund payment.
Please try again.
Unexpected error occurred in Example process while CORE makes refund transaction. 		500: Internal Server Error
987 PAYMENT_REJECT_FAIL_ERR An unexpected error occurred during a reject payment. Please try again.
Unexpected error occurred in a Example process while CORE makes a reject transaction. 		500: Internal Server Error
993 AUTHORIZATION_ERR You do not have authorization.
The client does not have an authorization target in the API. 		403: Forbidden
994 NOTIMPLEMENTED_METHOD_ERR Related function is not implemented.
The client invokes no implemented API. 		501: Not Implemented
995 NOTALLOWED_METHOD_ERR Requested method is not allowed.
The client invokes a non-existing method. 		405: Method Not Allowed
996 RESOURCE_NOTFOUND_ERR Cannot find resource. Please check resource.
The client invokes a non-existing resource. 		404: Not Found
997 REQUEST_ERR The request is invalid.
Information is provided about the invalid field.
Client doesn't send to Example a required attribute.
"detail" attribute describes reason of failure. 		400: Bad Request
998 AUTHENTICATION_ERR Authentication token is missing or incorrect.
The client does not have authentication. 		401: Unauthorized
999 API_INTERNAL_ERR Internal Error.
Unexpected error occurred.
"detail" attribute describes reason of failure. 		500: Internal Server Error
1001 CORE_API_SEND_ERR CORE Service Error (detailed CORE Service Error).
CORE returns error.
"detail" attribute describes reason of failure. 		400: Bad Request
1600 SAKA_GET_CVV_ERR SAKA error - Get CVV
Cannot get CVV from SAKA. 		400: Bad Request
1601 SAKA_GET_CARD_DETAIL_ERR SAKA error - Get Card Detail
Cannot get Card Details from SAKA. 		400: Bad Request
1602 SAKA_ENC_CARD_DETAIL_ERR SAKA error - Tokenized Card Detail
Cannot tokenize Card Details with SAKA. 		400: Bad Request
1603 SAKA_ENC_CARD_SUMMARY_ERR SAKA error - Tokenized Card Summary
Cannot tokenize Card Summary with SAKA. 		400: Bad Request
1604 SAKA_ENC_CARD_NUM_ERR SAKA error - Tokenize Card Number
Cannot tokenize Card Number (PAN) with SAKA. 		400: Bad Request
1700 SPHONIC_CHECK_ERR Sphonic error - Cannot check Risk level.
If Sphonic does not return anything,
or failed to connect to Sphonic.
"detail" attribute describes reason of failure. 		400: Bad Request
1701 SPHONIC_RISK_TRANSACTION_ERR Sphonic error
This transaction is detected as risk transaction.
Detailed Sphonic Error.
Occurs ff Sphonic returns "Fraud" while checking AML.
"detail" attribute describes reason of failure. 		400: Bad Request

Return to top