Skip to content

Take Payment

This guide provides an overview of how to use the Synqpay API to process payments. It covers key concepts like the transaction flow and the different statuses involved in the payment process.

Overview

The Synqpay Payment API is the backend component of the Synqpay platform designed to process credit card transactions. The API is responsible for initiating, completing (or capturing) payments, voiding transactions, and retrieving transaction details. This guide provides a high-level overview of how to process credit card transactions and manage their statuses.

The Synqpay API enables credit card payment processing within your application. It allows you to manage the lifecycle of a payment, from initiation to completion. Transactions can go through various stages, and the API will notify you of their status so you can take appropriate action.

The payment process is driven by two key methods:

  • startTransaction: This method initiates the payment and, by default, handles the entire transaction. It processes the payment and provides the final response, including whether the transaction was approved or declined. If configured differently (e.g. notifyUpdate true), it can return an intermediate response and await further input via continueTransaction.

  • continueTransaction: This method is used when a transaction is in progress and requires further action (e.g., after a card is read or for additional input). It allows you to continue and complete the transaction.

Transaction Flow

  1. A transaction is initiated, and the API provides a status update.
  2. The response will include a commandStatus field to indicate the current state of the transaction:
    • UPDATE: If notifyUpdate is set to true, this status is returned, indicating that the card has been read. During continueTransaction, the client can modify the credit terms, adjust the amount, or apply loyalty benefits based on the detected card details.
    • REFERRAL: If updateReferral is set to true, the status will be REFERRAL, and an authorization number will need to be provided to complete the transaction. This step requires telephone authorization to proceed.
    • COMPLETED: The transaction has finished processing. Check the result field to determine whether the transaction was approved or failed.

Transaction Status

Once the transaction reaches the COMPLETED status, the transactionStatus field will provide the final state of the payment. The possible values are:

  • AUTHORIZED: The payment was authorized but not yet captured (for AUTH_ONLY transactions). Possible processing for this status is VOID or CAPTURE
  • CAPTURED: The authorized payment has been successfully captured and located on the device's batch file.Possible processing for this status is VOID or settlement / deposit (according to device configuration).
  • DECLINED: The transaction was declined by the payment processor or card issuer
  • SETTLED: The transaction has been fully processed and settled.
  • DEPOSITED: The transaction has been deposited to the gateway and is located on the gateway’s batch file.
  • VOIDED: The transaction was voided and no further action is needed.
  • INFORMATIVE: The transaction was declined by the payment processor or card issuer, and an informative record is located on the batch file for that transaction, that do not require further processing.

Reference ID

The referenceId is a unique identifier generated by the client for each transaction. It plays a crucial role in ensuring transactional integrity and avoiding duplicate payments. Specifically:

  • Duplicate Prevention: In cases of communication errors or unknown statuses, the referenceId helps identify and prevent duplicate transactions by checking whether the referenceId already exists. If it does, an error is returned, preventing duplicate transactions.
  • Mandatory Usage: This field is required when performing certain operations, such as:
    • VOID: To void an existing transaction.
    • CAPTURE: To capture an authorized transaction.

By using a unique referenceId for every transaction, clients can ensure accurate tracking and management of their payment operations.

Authorization Only Transaction

An Authorization Only transaction, also known as a pre-authorization, is used to verify and hold funds on a card without immediately capturing them. This is often used in scenarios where the final transaction amount might change, such as in hospitality or car rental industries.

Taking an Authorization Only Transaction

To initiate an AUTH_ONLY transaction, you use the startTransaction method with the following basic details:

  • paymentMethod: CREDIT_CARD.
  • transactionType: Set to AUTH_ONLY.
  • amount: The amount to authorize.
  • currency: The ISO numeric code for the currency (e.g., 376 for ILS).
  • referenceId: A unique identifier for the transaction.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "jsonrpc": "2.0",
    "method": "startTransaction",
    "id": "12345",
    "params": {
        "paymentMethod": "CREDIT_CARD",
        "transactionType": "AUTH_ONLY",
        "amount": 10000,
        "currency": 376,
        "referenceId": "abcdef1234561"
    }
}
When the transaction is successfully authorized, the commandStatus will be COMPLETED, and the transactionStatus will be AUTHORIZED.

Capturing an Authorization Only Transaction

Capturing a transaction finalizes the payment by moving the funds from the cardholder’s account to the merchant's account. The Synqpay API allows you to capture an authorized transaction through the startTransaction method with transactionType set to CAPTURE.

Key Points When Capturing
  • Eligible Transactions: Only transactions in the AUTHORIZED status can be captured.
  • Adjustable Amount: The amount field must be provided during the capture request. The amount can be equal to or lower than the originally authorized amount but cannot exceed it.

How to Capture an Authorization Only Trnsaction

  1. Ensure Eligibility: Verify that the transaction is in the AUTHORIZED status.
  2. Set up the Request:
    • Use the startTransaction method.
    • Set the transactionType to CAPTURE.
    • Provide the referenceId of the original transaction.
    • Specify the amount to capture.
  3. Send the Request: Submit the startTransaction request to the Synqpay API.

Example Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "jsonrpc": "2.0",
    "method": "startTransaction",
    "id": "12345",
    "params": {
        "paymentMethod": "CREDIT_CARD",
        "transactionType": "CAPTURE",
        "amount": 9000,
        "currency": 376,
        "referenceId": "abcdef1234561"
    }
}

Response Handling

  • If the capture is successful:
    • commandStatus will be COMPLETED.
    • transactionStatus will be updated to CAPTURED (Or DEPOSITED if gateway is configured).
  • If the transaction cannot be captured (e.g., it is not in the AUTHORIZED status), an error message will be returned.

Common Use Cases for AUTH_ONLY and CAPTURE

  • Securing Funds: Use AUTH_ONLY to hold funds for orders that may change, such as hotel bookings or rentals.
  • Finalizing Payments: Use CAPTURE to collect funds once the final amount is confirmed.

By using AUTH_ONLY and CAPTURE transactions, you can provide flexibility in payment handling while ensuring secure fund management.

Voiding a Transaction

Voiding a transaction is the process of canceling a payment that has been authorized or captured but has not yet been settled or deposited. The Synqpay API allows you to void eligible transactions by initiating a request through the startTransaction method with transactionType set to VOID.

When to Void

  • Authorized Transactions: Transactions in the AUTHORIZED status can be voided to cancel the authorization before any funds are captured.
  • Captured Transactions: Transactions in the CAPTURED status can be voided, as long as they have not been settled or deposited.

How to Void a Transaction

To void a transaction, follow these steps:

  1. Ensure Eligibility: Verify that the transaction is in an eligible status (AUTHORIZED or CAPTURED).
  2. Set up the Request:
    • Use the startTransaction method.
    • Include the transactionType field set to VOID.
    • Provide the unique referenceId of the transaction to identify it for voiding.
  3. Send the Request: Submit the startTransaction request to the Synqpay API.

Example Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    "jsonrpc": "2.0",
    "method": "startTransaction",
    "id": "12345",
    "params": {
        "paymentMethod": "CREDIT_CARD",
        "transactionType": "VOID",
        "referenceId": "abcdef1234561"
    }
}

Response Handling

  • If the transaction is successfully voided:
    • commandStatus will be COMPLETED.
    • transactionStatus will be VOIDED.
  • If the transaction cannot be voided (e.g., it has already been settled), the API will return an appropriate error message.

Common Use Cases

  • Error Correction: Canceling an incorrect or duplicate transaction.
  • Customer Request: Canceling a transaction at the cardholder's request before further processing.

By using startTransaction with transactionType set to VOID, you can easily void transactions to ensure funds are not unnecessarily processed, giving you control and flexibility over payment operations.