JazzyPay - Secure Online Payments

Introduction

This document is intended for software integrators developing platforms that leverage web payment services.

JazzyPay REST API provides the integrator a way to initiate a payment without leaving their own website. The partner merchant sends an Initiate Request to JazzyPay, and JazzyPay will send a URL of the payment form page to be rendered by the partner merchant.

The payment form page allows the payor to select from 27 payment methods. After the payment is successful, JazzyPay will redirect the payor to the partner merchant’s page. JazzyPay will also send an SMS and email to the payor and merchant to inform them of the payment status.

Payment Sequence Diagram

Initialize Payment

Initialize Payment is the main API to create a transaction. On successful request, this will return an HTML5 URL that the partner merchant will use to redirect payors to JazzyPay’s payment form page.

Endpoint

/api/payment/initialize

Protocol Method

HTTPS POST

Header Parameters - Request

Name Description Type Required Sample
client-id Client ID provided by JazzyPay, to identify partner merchant String M 3434ec97-8a1b-4b42-9117-0944fc45ece8
client-secret Client secret key, provided by JazzyPay and paired with the Client ID String M @K4MYtsku#zY!NbY
Content-Type To indicate the type of request sent from the client to the server. String M application/json

Body Parameters - Request

Name Description Type Sample Required Sample
firstName First name String 128 M Juan
lastName Last name String 128 M Dela Cruz
email Email address String 128 M juandelacruz@gmail.com
phoneCode Phone number country code Numeric 1-4 M 63
phoneNumber Phone number without country code Numeric 10 M 9475816332
amount Amount to be paid in Philippine peso Amount / M 2500.00
description Payment description String 128 M Checkup
traceNo Partner merchant's submitted reference number. It must be unique in every transaction. String (Alpha-numeric characters, as well as dashes and underscores) 64 M ABC10000
successUrl Webpage URL to redirect payor after successful transaction String 512 M http://example.com/sucessful
cancelUrl Webpage URL to redirect payor after a failed transaction String 512 M http://example.com/failed

Sample Request

POST

Headers
Content-Type: application/json
client-id: 3434ec97-8a1b-4b42-9117-0944fc45ece8
client-secret: @K4MYtsku#zY!NbY

Body
{
"firstName": "Juan",
"lastName": "Dela Cruz",
"email": "juandelacruz@gmail.com",
"phoneCode": "63",
"phoneNumber": "9475816332",
"amount": 2500.00,
"description": "Checkup",
"traceNo": "ABC10000",
"successUrl": "http://example.com/sucessful",
"cancelUrl": "http://example.com/failed"
}

Body Parameters - Response

Name Description Type
status The state of the Initialize Payment call.

Success - request to Initiate Payment was successful.
Failed - request to Initiate Payment did not go through
String
traceNo Partner merchant’s submitted reference number String
referenceNo JazzyPay's transaction reference number. You can use this to check the transaction details using Query Payment API String
redirectUrl JazzyPay’s payment form URL String

Sample Response

{
"status": "Success",
"traceNo": "ABC10000",
"referenceNo": "APR-1458145",
"redirectUrl": "https://epikpay.com/payment/form/BID-10483270/redirect?client_id=100200&code=kjTMnKdQWfiZ81sf6lUmLDNNVCVFTa"
}

Sample Payment Form

When a payor is sent to redirectUrl from Initiate Payment response, they should see a form with the details from the request.

Upon completion of payment transaction, payor will be redirected back to partner merchants page.

Query Payment

Query Payment is an on-demand API. After an Initiate Payment call, partner merchants can use this API to check the transaction details from JazzyPay.

Endpoint

/api/payment/query

Protocol/Method

HTTPS POST

Header Parameters - Request

Name Description Type Required Sample
client-id Client ID provided by JazzyPay, to identify partner merchant String M 3434ec97-8a1b-4b42-9117-0944fc45ece8
client-secret Client secret key, provided by JazzyPay and paired with the Client ID String M @K4MYtsku#zY!NbY
Content-Type To indicate the type of request sent from the client to the server. String M application/json

Body Parameters - Request

Name Description Type Length Required Sample
referenceNo The reference number returned from the Initiate Payment API call String 128 Cond. APR-1458145
traceNo Partner merchant’s submitted transaction number

For a ​query ​request, the priority of checking is referenceNo > traceNo.
String 128 Cond. ABC10000

Sample Request

POST

Headers
Content-Type: application/json
client-id: 3434ec97-8a1b-4b42-9117-0944fc45ece8
client-secret: @K4MYtsku#zY!NbY

Body
{
"referenceNo": "APR-1458145"
}

Body Parameters - Response

Name Description Type
traceNo Partner merchant's submitted reference number String
referenceNo JazzyPay's transaction reference number String
status The state of the Query Payment call.

Success - request to Query Payment was successful
Failed - request to Query Payment did not go through
String
paymentStatus Payment status.

Success - the payor successfully made payment
Failed - the payor attempts to pay but encountered an error
Pending - the payor selected an Over-the-Counter payment type
String
paymentMethod Payment method payor selected String
paymentType Payment type String
amount Amount to be paid by the payor Amount
total The total amount charged to the payor Amount
currency Payment amount currency. Defaults to “PHP” for Philippine Peso String
date Date of the transaction Datetime

Sample Response

{
"status": "Success",
"referenceNo": "APR-1458145",
"paymentStatus": "Success",
"paymentMethod": "Credit Card - Mastercard",
"paymentType": "Card",
"amount": 2500,
"total": 2540,
"currency": "PHP",
"date": "2021-03-03T10:19:32.000Z"
}

APPENDIX A: Error Response Codes

Code Status Remarks
CLIENT_AUTH_FAILED F Client authentication failed
PARAM_MISSING_OR_INVALID F One or more mandatory parameters is/are not valid/missing
TRANSACTION_NOT_EXIST F Transaction does not exist
TRANSACTION_PENDING F The payor did not attempt to pay
INVALID_TRACE_NO F Trace number submitted is invalid or not unique

For technical inquiry, please send your message to hello@jazzypay.com

Scroll to top button