PEP DOCS

Accepting a payment

Learn More
New to the PayExplorer Connect SDK? Here are some helpful resources:
PayExplorer Connect SDK API

The SDK supports sale, refund, reversal, and other operations. This guide uses a standard payment (sale) to demonstrate the common Exchange flow: prepare parameters, start a request, and handle its result. Financial, device, and system operations can follow the same calling pattern, using the entry points, parameters, and business results in their API references.

Transaction Flow

Use Event Notification Services for progress feedback. Use Abort Transaction when interruption is needed and Transaction Query when the original request's status or result needs checking. Validate the implemented paths with the Go-Live Checklist.

Preparing Transaction Parameters

API reference PaymentParam Object

A PaymentParam object should be created before initiating a transaction, with the key parameters properly configured:

Amount (totalAmount): The transaction amount as a decimal string (e.g., "99.99").
Currency (currency): Enum value. Three-letter currency code based on ISO 4217.
Transaction Reference (transactionReference): A global order reference generated by the EPOS system.
Other Optional Parameters: Tip amount, cashier information, product summary, etc., depending on business requirements.

// Build a payment parameter object
PaymentParam paymentParam = PaymentParam.newBuilder()
    .transactionReference("12345678")
    .totalAmount("99.99")   
    .build();

using System;
using PayExplorerConnect;

// Replace the sample values with your transaction data.
public PaymentParam CreatePaymentParam()
{
    return new PaymentParam.Builder()
        .TransactionReference("12345678")
        .TotalAmount("99.99")
        .Build();
}

#import <PayExplorerConnect/RetailerManager.h>
#import <PayExplorerConnect/PaymentParam+Builder.h>

// Build payment parameters
PaymentParam *params = [PaymentParam makeWithBuilder:^(PaymentParamBuilder *builder) {
    builder.transactionReference(@"12345678");
    builder.totalAmount(@"99.99");
}];

Start the Payment Exchange

Register callbacks and start the request with the prepared parameters. The SDK returns results asynchronously; save the Exchange ID to track the request.

// Start the payment exchange with callback
RetailerManager.provideFinancialService()
        .newPaymentExchange(paymentParam)
        .startAsyncExchange(new Exchange.RetailerSDKCallback<PaymentResult>() {

            @Override
            public void onError(int code, String msg) {
                // Application logic: handle request/communication errors
            }

            @Override
            public void onResult(PaymentResult result) {
                handlePaymentResult(result);
            }
        });

public void HandlePaymentError(int code, string message)
{
    // Application logic: handle request/communication errors
}

public string StartPayment()
{
    PaymentParam paymentParam = CreatePaymentParam();

    // Start the payment exchange with callback
    string exchangeId = RetailerManager
        .ProvideFinancialService()
        .NewPaymentExchange(paymentParam)
        .StartAsyncExchange(HandlePaymentResult, HandlePaymentError);

    return exchangeId;
}

// Start the payment exchange with callback
[[RetailerManager sharedManager] payment:params block:^(NSString *exchangeId) {
    // exchangeId is used for tracking the transaction
} result:^(id result, NSInteger errcode, NSString *msg) {
    if (errcode != 0 && result == nil) {
        [self handlePaymentError:errcode message:msg];
        return;
    }
    PaymentResult *paymentResult = (PaymentResult *)result;
    [self handlePaymentResult:paymentResult];
}];

Warning

The onError callback indicates that the request failed to be sent or processed by the SDK.
A completed transaction result is always returned through the result callback.
For detailed error definitions, see: Error Codes

Handling Transaction Results

API reference PaymentResult Object

For every Exchange, first confirm completion, then determine the business outcome. If the result type exposes an end flag such as endFlag or EndFlag, false identifies an intermediate response and true identifies the final response. If no end flag is exposed, receiving a valid result callback completes that Exchange. Use the flag provided by the result type in the SDK version you use.

The SDK returns a PaymentResult object through the result callback. After confirming the final response, read the following fields to determine the payment outcome and retrieve transaction details:

Transaction Status (response) Indicates whether the transaction was successful.
Response Reason (responseReason) Provides the detailed transaction outcome code, such as failure, cancellation, or pending.
Additional Information (additionalResponseInformation) Additional information explaining the response reason.
Transaction Amount (totalAmount) The actual transaction amount, expressed as a decimal string (for example, "99.99").
Transaction Timestamp (transactionDateTime) The date and time when the transaction occurred.
Other Optional Fields: Additional information may be available depending on the acquiring application implementation, such as issuer reference data (issuerReferenceData) and payment receipts (paymentReceipts).

// Handle payment result returned from the SDK
private void handlePaymentResult(PaymentResult result) {
    // Skip null or intermediate responses.
    if (result == null || !result.isEndFlag()) {
        return;
    }
    // Check transaction status
    if (Response5Code.SUCC == result.getResponse()) {
        // Transaction succeeded
        String authorisationCode = result.getAuthorisationCode();
        // Application logic: update UI or record transaction
    } else {
        // Transaction failed, cancelled, or pending
        RetailerResultDetail1Code reason = result.getResponseReason();
        String responseInfo = result.getAdditionalResponseInformation();
        // Application logic: handle failure reason
    }
}

// Handle payment result returned from the SDK
public void HandlePaymentResult(PaymentResult result)
{
    // Skip null or intermediate responses.
    if (result?.EndFlag != true) return;

    // Check transaction status
    if (result.Response == ResponseCode.SUCC)
    {
        // Transaction succeeded
        // Application logic: update UI or record transaction
    }
    else
    {
        // Transaction failed, cancelled, or pending
        // Application logic: handle failure reason
    }
}

// Handle payment result
- (void)handlePaymentResult:(PaymentResult *)result {
    // Skip null or intermediate responses.
    if (!result || !result.endFlag) {
        return;
    }
    if (result.response == ResponseCodeSUCC) {
        // Transaction succeeded
        NSString *authCode = result.authorisationCode;
        // Application logic: update UI or record transaction
    } else {
        // Transaction failed, cancelled, or pending
        RetailerResultDetailCode reason = result.responseReason;
        NSString *info = result.additionalResponseInformation;
        // Application logic: handle failure reason
    }
}

// Handle payment error
- (void)handlePaymentError:(NSInteger)code message:(NSString *)msg {
    // Application logic: handle SDK errors
}

Warning

Important: After confirming the final response, the transaction is considered successful only when response == SUCC.

Accepting a payment

Learn More
New to the PayExplorer Connect SDK? Here are some helpful resources:
PayExplorer Connect SDK API

Transaction Flow

Preparing Transaction Parameters

API reference PaymentParam Object

A PaymentParam object should be created before initiating a transaction, with the key parameters properly configured:

Amount (totalAmount): The transaction amount as a decimal string (e.g., "99.99").
Currency (currency): Enum value. Three-letter currency code based on ISO 4217.
Transaction Reference (transactionReference): A global order reference generated by the EPOS system.
Other Optional Parameters: Tip amount, cashier information, product summary, etc., depending on business requirements.

// Build a payment parameter object
PaymentParam paymentParam = PaymentParam.newBuilder()
    .transactionReference("12345678")
    .totalAmount("99.99")   
    .build();

using System;
using PayExplorerConnect;

// Replace the sample values with your transaction data.
public PaymentParam CreatePaymentParam()
{
    return new PaymentParam.Builder()
        .TransactionReference("12345678")
        .TotalAmount("99.99")
        .Build();
}

#import <PayExplorerConnect/RetailerManager.h>
#import <PayExplorerConnect/PaymentParam+Builder.h>

// Build payment parameters
PaymentParam *params = [PaymentParam makeWithBuilder:^(PaymentParamBuilder *builder) {
    builder.transactionReference(@"12345678");
    builder.totalAmount(@"99.99");
}];

Start the Payment Exchange

Register callbacks and start the request with the prepared parameters. The SDK returns results asynchronously; save the Exchange ID to track the request.

// Start the payment exchange with callback
RetailerManager.provideFinancialService()
        .newPaymentExchange(paymentParam)
        .startAsyncExchange(new Exchange.RetailerSDKCallback<PaymentResult>() {

            @Override
            public void onError(int code, String msg) {
                // Application logic: handle request/communication errors
            }

            @Override
            public void onResult(PaymentResult result) {
                handlePaymentResult(result);
            }
        });

public void HandlePaymentError(int code, string message)
{
    // Application logic: handle request/communication errors
}

public string StartPayment()
{
    PaymentParam paymentParam = CreatePaymentParam();

    // Start the payment exchange with callback
    string exchangeId = RetailerManager
        .ProvideFinancialService()
        .NewPaymentExchange(paymentParam)
        .StartAsyncExchange(HandlePaymentResult, HandlePaymentError);

    return exchangeId;
}

// Start the payment exchange with callback
[[RetailerManager sharedManager] payment:params block:^(NSString *exchangeId) {
    // exchangeId is used for tracking the transaction
} result:^(id result, NSInteger errcode, NSString *msg) {
    if (errcode != 0 && result == nil) {
        [self handlePaymentError:errcode message:msg];
        return;
    }
    PaymentResult *paymentResult = (PaymentResult *)result;
    [self handlePaymentResult:paymentResult];
}];

Warning

Handling Transaction Results

API reference PaymentResult Object

The SDK returns a PaymentResult object through the result callback. After confirming the final response, read the following fields to determine the payment outcome and retrieve transaction details:

Transaction Status (response) Indicates whether the transaction was successful.
Response Reason (responseReason) Provides the detailed transaction outcome code, such as failure, cancellation, or pending.
Additional Information (additionalResponseInformation) Additional information explaining the response reason.
Transaction Amount (totalAmount) The actual transaction amount, expressed as a decimal string (for example, "99.99").
Transaction Timestamp (transactionDateTime) The date and time when the transaction occurred.
Other Optional Fields: Additional information may be available depending on the acquiring application implementation, such as issuer reference data (issuerReferenceData) and payment receipts (paymentReceipts).

// Handle payment result returned from the SDK
private void handlePaymentResult(PaymentResult result) {
    // Skip null or intermediate responses.
    if (result == null || !result.isEndFlag()) {
        return;
    }
    // Check transaction status
    if (Response5Code.SUCC == result.getResponse()) {
        // Transaction succeeded
        String authorisationCode = result.getAuthorisationCode();
        // Application logic: update UI or record transaction
    } else {
        // Transaction failed, cancelled, or pending
        RetailerResultDetail1Code reason = result.getResponseReason();
        String responseInfo = result.getAdditionalResponseInformation();
        // Application logic: handle failure reason
    }
}

// Handle payment result returned from the SDK
public void HandlePaymentResult(PaymentResult result)
{
    // Skip null or intermediate responses.
    if (result?.EndFlag != true) return;

    // Check transaction status
    if (result.Response == ResponseCode.SUCC)
    {
        // Transaction succeeded
        // Application logic: update UI or record transaction
    }
    else
    {
        // Transaction failed, cancelled, or pending
        // Application logic: handle failure reason
    }
}

// Handle payment result
- (void)handlePaymentResult:(PaymentResult *)result {
    // Skip null or intermediate responses.
    if (!result || !result.endFlag) {
        return;
    }
    if (result.response == ResponseCodeSUCC) {
        // Transaction succeeded
        NSString *authCode = result.authorisationCode;
        // Application logic: update UI or record transaction
    } else {
        // Transaction failed, cancelled, or pending
        RetailerResultDetailCode reason = result.responseReason;
        NSString *info = result.additionalResponseInformation;
        // Application logic: handle failure reason
    }
}

// Handle payment error
- (void)handlePaymentError:(NSInteger)code message:(NSString *)msg {
    // Application logic: handle SDK errors
}

Warning

Important: After confirming the final response, the transaction is considered successful only when response == SUCC.