API Endpoints

Environments

Endpoint URLs

🚧

Full endpoint URLs below are for UAT environment. Replace base URL portion from above table to obtain production ones.

Payment Endpoints

Inquiry Endpoints

Void Endpoints

Settlement Endpoints

Refund Endpoints

Access Token

When Admin creates new Company in admin portal system will generate identification token for that company.

This token should be sent with any request to PACO APIs (Payment, Settlement, Void, Refund, Inquiry) in headers;

Header name: token

If token is missing or not valid there will be generalized fail response send with message "Access Denied".

Payload Encryption

PACO APIs are an implementation of Javascript Object Signing and Encryption (JOSE) and provides an alternative to IP whitelisting as the second factor of authentication. Payload encryption adds Integrity, Authenticity, Non-repudiation and Confidentiality to PACO RESTful APIs.

API Protections

Our APIs require BASIC HTTP authentication for all clients. Usernames and passwords for BASIC HTTP authentication will be shared as part of client onboarding.

The IP Whitelisting will be mandatory for production environment while it will be optional for non-production environments provided the message encryption is enabled.

The Message Encryption will be mandatory for production environment while it will be optional for non-production environments provided the IP Whitelisting is enabled or vice versa.

API Protections

Message Encryption

The request and response message must be signed and encrypted. Clients will also be required to decrypt then validate the signature of all responses to access the payload.

Requests and response payload will be signed using JSON Web Signatures (JWS) and encrypted using JSON Web Encryption (JWE). The payloads will be formatted as: JWE (JWS (payload))) The payloads of JOSE requests and responses is identical to their unencrypted representations. The 'ContentType' and 'Accept' http headers will be used to distinguish the formats:

Content-Type is responsible for identification of sent request type.

Accept is responsible for identification of expected response type.

📘

Content type and Accept headers value for unencrypted REST request is application/json

📘

Content type and Accept headers value for encrypted is application/jose

If the encrypted request cannot be decrypted, is invalid, or using an unsupported algorithm, the request will be rejected with response content type = application/json. Responses will be signed and encrypted using the same algorithms supplied in the requests. Unsupported algorithms or invalid tokens will be rejected 4xx HTTP response. Algorithms supported are subject to change based on the latest security best practices. Refer to Error Messages topic below for message validation.

Merchant (Company) need to specify issuer as api key that is generated when 2c2p register new company.

Merchant (Company) need to specify audience as "PacoAudience" (TBC exact wording).

Example of JWT (unencrypted)

header
{
    "alg": "RSA-OAEP",
    "enc": "A128CBC-HS256",
    "kid": "6b21b61a256a422dbf195925e12db6e9",
    "typ": "JWT"
}
payload
{
    "aud":"PacoAudience",
    "iss":<apiKey>,
    "request":{<requestbody>},
    "exp": 1596432250,
    "iat": 1596428650,
    "nbf": 1596428650
}

Signature (JWS)

Request payloads must be signed with the client’s private key. PACO will validate the signature using the client’s JWK public key.

Response payloads will be signed using PACO’s private key. The response will contain a 'kid' header to identify the public key that the client will use to validate the signature. The 'jti' header serves as a nonce with JWT and will be populated with a UUID. Validating a nonce is not mandatory and may be optionally validated by both PACO and the client.

JWS Algorithms

The following JWS algorithms are supported:

• RS256, RS384, RS512
• PS256, PS384, PS512

Expiry

To prevent token reuse, the 'exp' header will be used with JWS. Since 'exp' is not defined as part of the JWS, (rather - it is defined as part of JWT), the 'Crit' header is used to indicate that the 'exp' header must be understood and processed.

Signatures will expire 5 minutes after generation.

Encryption (JWE)

Request content encryption keys (CEK) must be encrypted with PACO’s public key. JWE headers must contain a key identifier (kid) which can be used to locate the appropriate key from the JWK public key set.

Response CEK will be encrypted using the client’s public key. The client will decrypt the CEK using their private key then use the CEK to decrypt the response payload. PACO will use the same algorithm as the request if an appropriate public key is available.

JWE Algorithms

The following JWE algorithms ('alg' JWE header) are supported:

• RSA-OAEP

JWE Encryption Algorithms

The following JWE Encryption algorithms ('enc' JWE header used with CEK) are supported:

• A128CBC-HS256, A192CBC-HS384, A256CBC-HS512
• A128GCM, A192GCM, A256GCM

JOSE References

JOSE is quite popular encryption and signing scheme with adopted by many industries. There is numerous implementations and frameworks for various programming languages. Following is only few example based on .NET language:

• Ultimate Javascript Object Signing and Encryption (JOSE) and JSON Web Token (JWT) Implementation for .NET and .NET Core (https://github.com/dvsekhvalnov/jose-jwt)
• ASP.NET Core – How to digitally sign your JWT (https://www.sharepointeurope.com/asp-net-core-how-to-digitally-sign-your-jwt/)
• NuGet Gallery | System.IdentityModel.Tokens.Jwt 6.9.0 (https://www.nuget.org/packages/System.IdentityModel.Tokens.Jwt/)

Using JOSE for Message Encryption and Signing with 2C2P (PACO) API Integration

This shot list provide necessary steps to successfully integrate with our API using JOSE message encryption and signing.

Preparation

1. Generate RSA key pairs using any available tool. For example: Go to the URL "https://www.devglan.com/online-tools/rsa-encryption-decryption" to generate an RSA key.

2. RSA key size must be 4096 so change the "Select RSA Key Size" to "4096 bit".
   1. Note: Private key must be in PKCS#8 format. Pubic key must be in X.509 format. If using online tool from above, no other actions needed. If you create keys using other tools, you need to convert them to corresponding key formats.

3. Click on the “Generate RSA Key Pair” button for 2 times one for signing Key, one for encryption Key.
   1. 1st RSA Key Generate for “Merchant Signing Key” and save both keys to use as “Public Merchant Signing Key” and “Private Merchant Signing Key”
   2. 2nd RSA Key Generate for “Merchant Encryption Key” and save both keys to use as “Public Merchant Encryption Key” and “Private Merchant Encryption Key”

4. Set both signing and encryption public keys on PACO Portal.
5. Save private keys on your end. DO NOT share your private keys. You will need them to encrypt/decrypt messages between PACO and your system.

This diagram show all participating key-pairs from both merchant side and PGW side.

Sending Request

Sending encrypted request to PACO

JOSE Encryption Workflow

1. The merchant creates JSON request payload according to PACO specification.
   1. Wrap request into this cbliconstruct: { "request": }
2. The merchant signs payload by using merchant’s signing private key from preparation topic.
3. The merchant encrypts payload by using PGW’s encryption public key from PACO.
4. The merchant send payment request to PACO with content-type:application/jose; and accept:application/jose; http headers.
5. The PGW decrypt payload by using PGW’s encryption private key from PACO.
6. The PGW verify payload by using merchant’s signing public key from preparation topic.
7. The PGW process authorized and create response.
8. The PGW sign response by using PGW’s signing private key from PACO.
9. The PGW encrypt response by using Merchant’s encryption public key from preparation topic.
10. The PGW send backend notification to merchant.
11. The merchant decrypt response by using Merchant’s encryption private key from preparation topic.
12. The merchant verify response by using PGW’s signing public key from PACO.

Encryption Note

1. PACO team will provide two public keys and API key. These keys are Base64 encoded RSA public keys.
   1. For UAT,.please download PACO default public keys from here.
   2. For Production,.please download PACO default public keys from here. Please contact us for password to decompress the archive.
2. From workflow step 2 and 3, JOSE JWT must be encrypt by using PACO encryption public key and merchant private signing key with the detiail below.
   1. claim "iss" must be equal to API key.
   2. claim "aud" must be equal to "PacoAudience".
   3. for encryption use "alg": "RSA-OAEP" and "enc": "A128CBC-HS256".
   4. for signing use "alg": "PS256".
3. From workflow step 11 and 12, please user merchant private encryption key and PACO public signing key to read PACO response in JSON format with the detiail below.
   1. claim "iss" will be equal to "PacoIssuer".
   2. claim "aud" will be equal to API key.

Sample Code

This is sample code in C# language (download) and PHP language (download).

Environment-dependent Parameters
Unless explicitly specify otherwise, all parameters in the source code are hard coded with UAT values. Be careful when using this sample connecting to production environment. In addition to the obvious like API Endpoints, these parameters are also vary as well.

Please contact your service provider for password to extract above files.