EzyPayment - as a Service (EPaaS)

List of accepted payment purposes

• Education
• Fines
• Food and Beverages
• Government Service
• Hospitals
• Insurance
• Loan
• Rent
• Supplier
• Taxes
• Utilities
• Others
• Payroll
• Domestic helper

List of error codes and errors

PGP Key specifications

• Generate PGP key pairs (with RSA 2048) and share the PGP public key during onboarding.
• Use GNU Privacy Guard (GnuPG) tool to generate the PGP keys. The keys should be generated without a passphrase.

Download SGeBIZ utility Java library for related methods here :

Signature generation for query params in API_R01

Though API_R01 has many query parameters, for the signature we only check few important parameters only.

• client_id
• client_secret
• customer-ref
• invoice-amount
• invoice-ref
• timestamp

Before signing the above query parameters, generate the query param URL as below with the values and generate a single string.

*Make sure to follow the same order of the parameters and correct spelling.

Sample query string with values :

client_id=123456789abcdefgh&client_secret=987654321pqrstuvw&customer-ref=demo001&invoice-amount=100.00&invoice-ref=INV-tst-001&timestamp=1678957248496

Once the above query string generated, then sign it with your private key and ++"url-encode"++ the signature. Once it is done the signature should be like below.

-----BEGIN+PGP+SIGNATURE-----%0D%0AVersion%3A+BCPG+v1.48%0D%0A%0D%0AiJwEAAEIAAYFAmQS2usACgkQcelqcc2GDZSJWAP%2FcNiTFpl4kJLOdhLXGIPtqROI%0D%0AUT1dAp0LWO9vUP%2F%2BwD%2BK%2Fbxegg02EgCVg5IDJ0mgSpZJWNZv%2BRg7QjM%2Fhho0YKKd%0D%0ABsN5%2F6lYdC26ZNXWNGQBUdKJ4VanHU7mzQLaGAXNZ5UdVK6dEgsjbM1btKEO7K9D%0D%0Avhmdefmzod75hRMIVp0%3D%0D%0A%3DVi4w%0D%0A-----END+PGP+SIGNATURE-----%0D%0A

Then append all the relevant query parameters as in API specification and at the end attach the signature. Sample as below;

https://devapp.sgebiz.com/x-ex-payment/api/init/payment/redirection?client_id=123456789abcdefgh&client_secret=987654321pqrstuvw&customer-ref=demo001&invoice-amount=100.00&invoice-ref=INV-tst-001&timestamp=1678957248496&customer-name=kasuntest&customer-mobile=87654321&customer-email=kasun@test.com&invoice-description=testing+desc&purpose=Rent&redirect-back-url=https://test.com/app&signature=-----BEGIN+PGP+SIGNATURE-----%0D%0AVersion%3A+BCPG+v1.48%0D%0A%0D%0AiJwEAAEIAAYFAmQS2usACgkQcelqcc2GDZSJWAP%2FcNiTFpl4kJLOdhLXGIPtqROI%0D%0AUT1dAp0LWO9vUP%2F%2BwD%2BK%2Fbxegg02EgCVg5IDJ0mgSpZJWNZv%2BRg7QjM%2Fhho0YKKd%0D%0ABsN5%2F6lYdC26ZNXWNGQBUdKJ4VanHU7mzQLaGAXNZ5UdVK6dEgsjbM1btKEO7K9D%0D%0Avhmdefmzod75hRMIVp0%3D%0D%0A%3DVi4w%0D%0A-----END+PGP+SIGNATURE-----%0D%0A

If you are using Java library given by SGeBIZ for signature generation.

Use, com.sgebiz.crypto.CryptoUtil signWithPGPPrivate(String input, boolean isASCIIArmor, String privateKey, String privateKeyPass) method with isASCIIArmor = true for signing
Use, com.sgebiz.crypto.CryptoUtil urlEncode(String value) for URL-encode the signature

Signature verification for query params in API_R02

When the parameters received with the API_R02.

• Extract the signature. URL
• If you capture it from a browser URL then the signature may already URL-decoded. If it is not, then decode the signature.
• API_R02 signature generated from below fields
  • status
  • timestamp
• The raw query string will look like below in order.

status=success&timestamp=1678957248496

• generate the similar query string as above with incoming query param and verify with the signature

If you are using Java library given by SGeBIZ for signature verification.

Use, com.sgebiz.crypto.CryptoUtil urlDecode(String value) for URL-decode the signature
Use, com.sgebiz.crypto.CryptoUtil verifyWithPGPPublic(String signedData, String verificationData, boolean isASCIIArmored, String publicKey) method with isASCIIArmor = true for verification

Payload decrypt and verify

Received Response Payload to be decrypted using PGP (Pretty Good Privacy) to get the plain text JSON format. Steps in the following. (Use onepass PGP decrypt and verify)

• Decrypt the signed payload using the private key.
• Verify the signed payload using EzyPayment public key. (EzyPayment public key will be shared in the onboarding.)
• Use Signing Hash Algorithm - SHA 256 and above.
• Use symmetric key algorithm for decryption - AES256 and above.
• The decrypted and verified payload is the actual JSON payload response as per EPaaS API specifications.

If you are using Java library given by SGeBIZ for payload decrypt and verify.

Use, com.sgebiz.crypto.CryptoUtil decryptAndVerifyWithPGPOnePass(String input, boolean isASCIIArmor, String decrptingPrivateKey, String decrptingPrivateKeyPass, String verifingPublicKey) method with isASCIIArmor = true for signing