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
<base path>/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 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 (minimum: 200) | / | 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 (Accepts alpha-numeric characters, 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
<base path>/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 |
| REQUEST_NOT_ALLOWED | F | API Request not allowed |
For technical inquiry, please send your message to hello@jazzypay.com
APPENDIX B: Test Cards
Use any of the following test card numbers to create a successful payment transaction:
| Card Number | CVC | DATE |
|---|---|---|
| 4000056655665556 | Any 3 digits | Any future date |
| 5555555555554444 | Any 3 digits | Any future date |
Use any of the following test card numbers to create a failed payment transaction:
| Card Number | CVC | DATE |
|---|---|---|
| 4000000000000002 | Any 3 digits | Any future date |
| 4000000000000069 | Any 3 digits | Any future date |
For technical inquiry, please send your message to hello@jazzypay.com
