Skip to main content

Create Payment API

This section provides a detailed overview of the payment API, which is an essential component of the Convenient Checkout API. The payment API is responsible for processing payments and managing the payment lifecycle.

Payment API Overview​

The payment API is a RESTful API that enables merchants to process payments and manage the payment lifecycle. The API provides endpoints for creating payments, confirming payment, capturing partial or full amount, retrieving payment details, and cancelling payments.

The payment API is designed to be flexible and extensible, allowing merchants to integrate it with their existing systems and workflows. The API supports various payment methods, including Credit cards, HSA cards, ACH, Apple Pay and Google Pay.

Payment API Integration​

The payment API integration involves integrating the payment API into the merchant's website or application to process payments and manage the payment lifecycle. The integration includes creating payments, retrieving payment details, and updating payment status.

The payment API integration follows these steps:

  1. Create Payment: The merchant sends a payment request to create a new payment. The request includes the payment amount, customer details, and payment method details.
  2. Get Payment: The merchant sends a payment request to retrieve payment details based on the payment ID or merchant transaction ID. The response includes the captured payment amount, payment method details, and payment status.
  3. Confirm Payment: The merchant sends a payment request to confirm a payment. The request includes the payment ID and the confirmation amount.
  4. Cancel Payment: The merchant sends a payment request to cancel a payment. The request includes the payment ID.
  5. Refund Payment: The merchant sends a payment request to refund a payment. The request includes the payment ID and the refund amount.
  6. Capture Payment: The merchant sends a payment request to capture an authorized payment. The request includes the payment ID and the capture amount.

The payment API integration enables merchants to process payments securely and efficiently, providing a seamless payment experience for their customers.

Payment Lifecycle​

The payment lifecycle is the process of managing payments from creation to completion.

Following diagram illustrates the payment lifecycle:

Payment Lifecycle

The payment lifecycle is managed using the payment API endpoints, enabling merchants to process payments securely and efficiently.

Payment API Endpoints​

The payment API request and response payloads are defined using the JSON format. The request payload includes the payment amount, customer details, agent information, and payment method details. The response payload includes the payment ID, payment status, and payment details. The detailed documentation of the payment API request and response payloads can be found in the API Documentation. The payment API provides the following endpoints:

  • Create Payment: (Link to Create Payment API) This endpoint is used to create a new payment. The request payload includes the payment amount, customer details, and payment method details. The response contains the payment ID and payment status.
  • Get Payment by Payment ID: (Link to Get Payment API) This endpoint is used to retrieve payment details based on the payment ID. The request payload includes the payment ID, and the response contains the payment details.
  • Get Payment by Merchant Transaction ID: (Link to Get Payment API) This endpoint is used to retrieve payment details based on the merchant transaction ID. The request payload includes the merchant transaction ID, and the response contains the payment details. Merchant transaction ID can be retrieved from the response of get session or checkout session API.
  • Confirm Payment by Payment ID: This endpoint is used to confirm a payment. The request payload includes the payment ID and the confirmation amount.
  • Capture Full or Partial Payment: (Link to Capture Payment API) This endpoint is used to capture a full or partial payment amount. The request payload includes the payment ID and the capture amount.
  • Cancel Payment by Payment ID: ( Link to Cancel Payment API) This endpoint is used to cancel a payment. The request payload includes the payment ID.

The payment API endpoints enable merchants to process payments, retrieve payment details, and manage the payment lifecycle effectively.

How Merchants can use Payment API?​

Merchants can use the payment API to process payments either through the Convenient Checkout API for payment or through the CCG widget.

Applicable Session modes for payments API​

PAYMENT, PAYMENT_WITH_WALLET

Steps to use Payment API​

  1. Create Payment API Request: The merchant needs to create a payment request by providing the payment amount, customer details, and payment method details. The request payload is sent to the payment API endpoint to create a new payment or update existing one. As per API documentation Create Payment API, immediately ACCEPTED (HTTP code 202) response is sent back which contains the payment ID and payment status.
  2. Get Payment API Request: The merchant can retrieve payment details based on the payment ID or merchant transaction ID. The request payload is sent to the payment API endpoint to retrieve payment details.
  3. Get Session/Checkout Session API Request: The merchant can retrieve the session details based on the session ID. The session response contains the payment details.
  4. Webhook Notification: The payment API sends webhook notifications to the merchant's server to notify them about the payment status updates. The merchant can use the webhook notifications to update their systems and workflows accordingly. Webhook notifications are sent for both successful and failed payments. Please refer to the Webhook Notification for more details.

Note:​

The merchant can either rely on the webhook notifications or poll the payment API to get the payment status updates. The payment API provides endpoints to retrieve payment details based on the payment ID or merchant transaction ID.

Conclusion​

This document provided an overview of the payment API, including its endpoints, and steps to use API. The payment API is a critical component of the Convenient Checkout APIs, enabling merchants to process payments and manage the payment lifecycle effectively. By integrating the payment API into their systems, merchants can offer a seamless and secure payment experience to their customers.