Guides Payments - API Refunds - API API Interface

Checkout Integration Guide

Version : 1.0
Released : 2026/01/01

Introduction

This guide explains how to integrate the payment API into your application. It covers authentication, request flow, transaction handling, and callbacks.

General Information

The Checkout service provides a quick and convenient way to build a secure payment page. It enables merchants to collect payment details, submit transactions, and send them for processing seamlessly.

To use the Checkout service on a website, an integration process is required. This integration offers a set of APIs that allow businesses to customize and control their payment processing workflows. These APIs support payment acquisition (purchases) through defined interactions between the merchant’s website and the payment system and also the refund requests from the authorized merchants for their transactions.

All API requests must be sent in JSON format, and responses are also returned as JSON data.

Process Flow

The diagram below illustrates how a payment is initiated, processed, and completed through the Checkout system.

Customer places an order and starts the payment process
Website validates the order and sends payment details, order info, and hash to the Checkout system
Checkout system verifies the request and returns a secure redirect URL
Customer is redirected to the Checkout payment page
Customer selects a payment method, enters payment details, and confirms the transaction
Payment is processed by the Payment Gateway
Payment Gateway sends a callback with the transaction result
Payment result is displayed to the customer
Transaction may be declined if invalid data is detected

Authentication

All API requests require Bearer token authentication. Tokens are issued privately and must be kept secure. 

Authorization: Bearer YOUR_API_TOKEN

Payment Flow

A payment request is submitted to the API. Depending on the card and issuer, the transaction may complete immediately or require additional customer verification.

2DS and 3DS Transactions

2DS transactions complete instantly. 3DS transactions require redirecting the customer to an authentication page.

Callbacks

Transaction results are sent asynchronously to the callback URL provided during the payment request.

Environments

Sandbox and production environments are available. Use sandbox credentials for testing and validation.

Payment API Requests

Version 1.0
POST https://api-dev.cruisepay.finance/api/v1/payment

Authentication

All requests sent to the Cruisepay API must be authenticated using a Bearer token. This token verifies that the request originates from an authorized account and defines the permitted access scope.

Requests with missing, expired, or invalid tokens will receive a 401 Unauthorized response. 

Authorization: Bearer  ••••••••••••••••••••••

Request Parameters

Payment Details

paymentMethod string required

Customer’s payment method.
CARD or GOOGLEPAY or APPLEPAY (Only as given)

Example: CARD
amount number required

Amount of the transaction.
The format depends on the currency exponent.

Example: 100.5
currency string required

Payment Currency
3 Letter Currency Code

Example: USD
invoiceNumber string required

Transasction ID assigned by Merchant.
Minimum length of 7 characters.

Example: ABC123

Card Details

cardNumber string required

Card primary account number (PAN).
All non-numeric characters will be ignored.
Minimum length of 7 characters.

Example: 4000000000000002
expMonth string required

Card Expiry Month - 2 Digits only

Example: 08
expYear string required

Card Expiry Year - last 2 Digits of the year value only

Example: 29
cvv string required

CVV Code - 3 Digits or 4 (for AMEX)

Example: 123

Customer Identity

firstName string required

Customer's First Name.
A Maxumum of 50 Characters allowed

Example: Sherlock
lastName string required

Customer's Last Name.
A Maxumum of 50 Characters allowed

Example: Holmes
email email required

Customer's email

Example: [email protected]
phone string required

Customer's Phone Number
Min 7 digits - Max 18 digits - No need to enter country code.

Example: 6549873215

Billing Details

address string required

Customer's Address
Min 3 & Max 45 characters

Example: 221 B, Baker Street
city string required

Customer's City
Min 3 & Max 45 characters

Example: London
state string required

Customer's State
Min 2 & Max 45 characters

Example: State
zip string required

Customer's Zip Code
Only Alpha Numeric values allowed

Example: NW16XE
country string required

Customer's Country Code
2-letter country code

Example: UK

Network Information

ip string required

IP address (IPv4 or IPv6)

Example: 192.168.1.1

Redirects & Webhooks

returnUrl string Optional

URL to redirect Customer after processing

Example: Https://abcwebsite.com
statusUrl string Optional

API endpoint to receive the payment status
To know either Success or Failure

Example: Https://abcwebsite.com/returnurl

Payload Structure

Request Payload (JSON) 
{
  "paymentMethod": "CARD",
  "amount": "66.00",
  "currency": "USD",
  "invoiceNumber": "abcd1234",

  "cardNumber": "4000000000000002",
  "expMonth": "05",
  "expYear": "28",
  "cvv": "123",

  "firstName": "Sherlock",
  "lastName": "Holmes",
  "email": "[email protected]",
  "phone": "9876543210",

  "address": "221B Baker Street",
  "city": "London",
  "state": "State",
  "zip": "NW16XE",
  "country": "UK",

  "ip": "192.168.5.6",

  "returnUrl": "https://www.clientsite.com",
  "statusUrl": "https://clientsite.com/api/statusurl",

  "additionalParameters": {}
}

Callback Responses

Get Status API Request

Version 1.0
GET https://api-dev.cruisepay.finance/api/v1/orderStatus

Get Transaction Status

The Get Transaction Status endpoint requires authentication using a Bearer token. This request returns the current status of a transaction based on the provided identifier.

Requests with missing, expired, or invalid tokens will receive a 401 Unauthorized response. 

Authorization: Bearer ••••••••••••••••••••••

Request Parameters

Invoice Detail

invoiceNumber string required

Transasction ID assigned by Merchant.
Minimum length of 7 characters.

Example: ABC123

Payload Structure

Request Payload (JSON) 
{
  "invoiceNumber": "abcd1234",
}

Status Callback Responses

Refund API Requests

Version 1.0
POST https://api-dev.cruisepay.finance/api/v1/initiateRefund

Authentication

Refund requests must be authenticated using a Bearer token. 

Authorization: Bearer ••••••••••••••

Request Parameters

Refund Details

invoiceNumber string required

Original transaction's invoice number.

Example: Invoice0001
currency string required

Refund Currency
3 Letter Currency Code

Example: USD
refundAmount number required

Amount to refund. Must be less than or equal to the original transaction amount.

Example: 25.00
reason string required

Reason for initiating the refund.

Example: Customer requested refund
refund Id string Optional

Any random ID value to denote the particular request. Optional Field

Example: 654321

Payload Structure

Refund Request Payload (JSON) 
{
  "invoiceNumber": "0004invoice",
  "currency": "USD",
  "refundAmount": "40.00",
  "reason": "Requested by Client",
  "refundId": "654321" // Optional
}

Callback Responses