Consult a Payment Status


Endpoints

HTTP Method API URL API Version
GET https://connect2.payxpert.com/payment/{merchantToken}/status >= 002.50
GET https://connect2.payxpert.com/transaction/{merchantToken}/status >= 002

This call permits to a merchant to fetch the status of a given payment. Note that the merchantToken that uniquely identifies the payment is part of the URL (the string {merchantToken} in the URL must be replaced by the merchant token value).

The following request parameter is accepted (in query string):

Accepted parameters

Name Type Value Required API Version
apiVersion String(8) API version to be used (default 002.50) yes >= 002.50

Response

The body of the response to a payment consult request is in JSON format.

The following fields are present in the response:

Name Type Description
status String(32) Human readable status of the payment. Could be “Authorized”, “Not authorized”, “Not processed”, “Expired”, “Call failed” or “Pending”. “Pending” meaning that an unsuccessful transaction attempt has been done but that the shopper can still try.
merchantToken String(32) The merchant token for the payment.
operation String(32) The type of operation of the payment. Can be sale, authorize or submission.
errorCode String Result code of the transaction (see API Response Codes for possible values). For API >= 002.50 this is the last initial transaction attempt code.
errorMessage String Human readable message associated with the code. For API >= 002.50 this is the last initial transaction attempt message.
transactions Array of Transaction Attempt objects A list of transaction attempts done to process this payment (see here for format). For API 002.50 contains only initial transactions, i.e. Sale, Authorize, Submission and (first) Collection operations. Starting with API 002.51 it contains all the transactions related to the payment, so also subsequent Collection, Cancel, Refund, Rebill operations and every types of transactions.
order Order Object Information about order
shipping Shipping Object Information about shipping
ctrlCustomData String(2048) Merchant data initially submitted by the merchant with the payment creation.
currency String(3) Currency for this payment
amount Integer(32bits) The payment amount in cents (for 1€ => 100). For API >= 002.50 this is the amount of the last initial transaction attempt. If the payment has not yet been processed this is the initial requested amount.
Name Type Description API Version
merchantToken String(32) The merchant token for the payment. >= 002
paymentType String(32) The type of payment. Can be BankTransfer, CreditCard or ToditoCash. >= 002 & < 002.50
paymentMeanInfo Object Details on the payment mean. Will vary according to the paymentType. See a description of the structure. >= 002.02 & < 002.50
operation String(32) The type of operation of the payment. Can be sale, authorize or submission. >= 002
errorCode String Result code of the transaction (see API Response Codes for possible values). For API >= 002.50 this is the last initial transaction attempt code. >= 002
errorMessage String Human readable message associated with the code. For API >= 002.50 this is the last initial transaction attempt message. >= 002
status String(32) Human readable status of the payment. Could be “Authorized”, “Not authorized”, “Not processed”, “Expired”, “Call failed” or “Pending”. “Pending” meaning that an unsuccessful transaction attempt has been done but that the shopper can still try. >= 002
transactionID Integer(64bits) The unique ID of the transaction >= 002 & < 002.50
subscriptionID Integer(64bits) Initial subscription reference (to be used to cancel the automated rebilling, only present if the transaction is type Recurrent) >= 002 & < 002.50
ctrlCustomData String(2048) Merchant data initially submitted by the merchant with the payment creation. >= 002
orderID String(100) The merchant order ID. >= 002
currency String(3) Currency for this payment >= 002
amount Integer(32bits) The payment amount in cents (for 1€ => 100). For API >= 002.50 this is the amount of the last initial transaction attempt. If the payment has not yet been processed this is the initial requested amount. >= 002
shopperName String(80) The name provided by the customer. >= 002 & < 002.50
shopperAddress String(255) The address provided by the customer. >= 002 & < 002.50
shopperZipcode String(10) The zip code provided by the customer. >= 002 & < 002.50
shopperCity String(50) The city provided by the customer. >= 002 & < 002.50
shopperState String(30) The state provided by the customer. >= 002 & < 002.50
shopperCountryCode String(2) The country code provided by the customer. >= 002 & < 002.50
shopperPhone String(20) The phone number provided by the customer. >= 002 & < 002.50
shopperEmail String(100) The email address provided by the customer. >= 002 & < 002.50
shopperBirthDate String(8) Date of shopper birth date, format YYYYMMDD >= 002.03 & < 002.50
shopperIDNumber String(32) Customers document (passport number, ID number, taxpayer ID…) >= 002.03 & < 002.50
shopperIPAddress String(15) The IP address of the customer. >= 002 & < 002.50
cardHolderName String(35) In case of CreditCard payment, the card holder name provided by the customer. >= 002 & <= 002.01
statementDescriptor String(50) Descriptor that will appear on shopper bank statement. >= 002 & < 002.50
transactions Array of Transaction Attempt objects A list of transaction attempts done to process this payment (see here for format). For API 002.50 contains only initial transactions, i.e. Sale, Authorize, Submission and (first) Collection operations. Starting with API 002.51 it contains all the transactions related to the payment, so also subsequent Collection, Cancel, Refund, Rebill operations and every types of transactions. >= 002.50

Code samples


use PayXpert\Connect2Pay\Connect2PayClient;
use PayXpert\Connect2Pay\containers\constant\PaymentMethod;

$connect2pay = "https://connect2.payxpert.com";
// This will be provided once your account is approved
$originator  = "000000";
$password    = "Gr3atPassw0rd!";
$merchantToken = "example"

$c2pClient = new Connect2PayClient($connect2pay, $originator, $password);
$status = $c2pClient->getPaymentStatus($merchantToken);

if ($status != null && $status->getErrorCode() != null) {
  echo "Merchant token: " . $status->getMerchantToken() . "\n";
  echo "Status: " . $status->getStatus() . "\n";
  echo "Error code: " . $status->getErrorCode() . "\n";

  if ($status->getCtrlCustomData()) {
    echo "Custom Data: " . $status->getCtrlCustomData() . "\n";
  }

  $transactionsCount = count($status->getTransactions());

  if ($transactionsCount > 0) {
    echo "Number of transactions associated with this payment: " . $transactionsCount . "\n";

    $transaction = $status->getLastInitialTransactionAttempt();

    if ($transaction !== null) {
      echo "~~\n";
      echo "~~ More recent initial transaction for this payment\n";
      echo "~~\n";

      echo "Transaction ID: " . $transaction->getTransactionID() . "\n";
      echo "Payment method: " . $transaction->getPaymentMethod() . "\n";
      if ($transaction->getPaymentNetwork()) {
        echo "Payment network: " . $transaction->getPaymentNetwork() . "\n";
      }
      echo "Operation: " . $transaction->getOperation() . "\n";
      echo "Amount: " . number_format($transaction->getAmount() / 100, 2) . " " . $status->getCurrency() . "\n";
      echo "Result code: " . $transaction->getResultCode() . "\n";
      echo "Result message: " . $transaction->getResultMessage() . "\n";

      $transactionDate = $transaction->getDateAsDateTime();
      if ($transactionDate !== null) {
        echo "Transaction date: " . $transactionDate->format("Y-m-d H:i:s T") . "\n";
      }

      if ($transaction->getSubscriptionID()) {
        echo "Subscription ID: " . $transaction->getSubscriptionID() . "\n";
      }
      $paymentMeanInfo = $transaction->getPaymentMeanInfo();
      if ($paymentMeanInfo !== null) {
        switch ($transaction->getPaymentMethod()) {
          case PaymentMethod::CREDIT_CARD:
            if ($paymentMeanInfo->getCardNumber() !== null) {
              echo "Payment Mean Information:\n";
              echo "* Card Holder Name: " . $paymentMeanInfo->getCardHolderName() . "\n";
              echo "* Card Number: " . $paymentMeanInfo->getCardNumber() . "\n";
              echo "* Card Expiration: " . $paymentMeanInfo->getCardExpireMonth() . "/" . $paymentMeanInfo->getCardExpireYear() . "\n";
              echo "* Card Brand: " . $paymentMeanInfo->getCardBrand() . "\n";

              if ($paymentMeanInfo->getCardLevel() !== null) {
                echo "* Card Level/subtype: " . $paymentMeanInfo->getCardLevel() . "/" . $paymentMeanInfo->getCardSubType() . "\n";
                echo "* Card country code: " . $paymentMeanInfo->getIinCountry() . "\n";
                echo "* Card bank name: " . $paymentMeanInfo->getIinBankName() . "\n";
              }
            }

            break;
          case PaymentMethod::BANK_TRANSFER:
            $sender = $paymentMeanInfo->getSender();
            $recipient = $paymentMeanInfo->getRecipient();

            if ($sender !== null) {
              echo "Payment Mean Information:\n";
              echo "* Sender Account:\n";
              echo ">> Holder Name: " . $sender->getHolderName() . "\n";
              echo ">> Bank Name: " . $sender->getBankName() . "\n";
              echo ">> IBAN: " . $sender->getIban() . "\n";
              echo ">> BIC: " . $sender->getBic() . "\n";
              echo ">> Country code: " . $sender->getCountryCode() . "\n";
            }

            if ($recipient !== null) {
              echo "* Recipient Account:\n";
              echo ">> Holder Name: " . $recipient->getHolderName() . "\n";
              echo ">> Bank Name: " . $recipient->getBankName() . "\n";
              echo ">> IBAN: " . $recipient->getIban() . "\n";
              echo ">> BIC: " . $recipient->getBic() . "\n";
              echo ">> Country code: " . $recipient->getCountryCode() . "\n";
            }

            break;
          case PaymentMethod::DIRECT_DEBIT:
            $account = $paymentMeanInfo->getBankAccount();

            if ($account !== null) {
              echo "Payment Mean Information:\n";
              echo "* Statement descriptor: " . $paymentMeanInfo->getStatementDescriptor() . "\n";

              $collectedAt = $paymentMeanInfo->getCollectedAtAsDateTime();
              if ($collectedAt != null) {
                echo "* Collected At: " . $collectedAt->format("Y-m-d H:i:s T") . "\n";
              }

              echo "* Bank Account:\n";
              echo ">> Holder Name: " . $account->getHolderName() . "\n";
              echo ">> Bank Name: " . $account->getBankName() . "\n";
              echo ">> IBAN: " . $account->getIban() . "\n";
              echo ">> BIC: " . $account->getBic() . "\n";
              echo ">> Country code: " . $account->getCountryCode() . "\n";

              $sepaMandate = $account->getSepaMandate();

              if ($sepaMandate != null) {
                echo "* SEPA mandate:\n";
                echo ">> Description: " . $sepaMandate->getDescription() . "\n";
                echo ">> Status: " . $sepaMandate->getStatus() . "\n";
                echo ">> Type: " . $sepaMandate->getType() . "\n";
                echo ">> Scheme: " . $sepaMandate->getScheme() . "\n";
                echo ">> Signature type: " . $sepaMandate->getSignatureType() . "\n";
                echo ">> Phone number: " . $sepaMandate->getPhoneNumber() . "\n";

                $signedAt = $sepaMandate->getSignedAtAsDateTime();
                if ($signedAt != null) {
                  echo ">> Signed at: " . $signedAt->format("Y-m-d H:i:s T") . "\n";
                }

                $createdAt = $sepaMandate->getSignedAtAsDateTime();
                if ($createdAt != null) {
                  echo ">> Created at: " . $createdAt->format("Y-m-d H:i:s T") . "\n";
                }

                $lastUsedAt = $sepaMandate->getLastUsedAtAsDateTime();
                if ($lastUsedAt != null) {
                  echo ">> Last used at: " . $lastUsedAt->format("Y-m-d H:i:s T") . "\n";
                }

                echo ">> Download URL: " . $sepaMandate->getDownloadUrl() . "\n";
              }
            }

            break;
          case PaymentMethod::WECHAT:
          case PaymentMethod::ALIPAY:
              echo "Payment Mean Information:\n";
              echo "* Total Fee: " . $paymentMeanInfo->getTotalFee() . "\n";
              echo "* Exchange Rate: " . $paymentMeanInfo->getExchangeRate() . "\n";

            break;
        }
      }

      $shopper = $transaction->getShopper();
      if ($shopper !== null) {
        echo "Shopper info:\n";
        echo "* Name: " . $shopper->getFirstName() . "\n";
        echo "* Address: " . $shopper->getAddress1() . " - " . $shopper->getZipcode() . " " . $shopper->getCity() . " - " .
             $shopper->getCountryCode() . "\n";
        echo "* Email: " . $shopper->getEmail() . "\n";

        if ($shopper->getBirthDate() !== null) {
          echo "* Birth date: " . $shopper->getBirthDate() . "\n";
        }

        if ($shopper->getIdNumber() !== null) {
          echo "* ID Number: " . $shopper->getIdNumber() . "\n";
        }

        if ($shopper->getIpAddress() !== null) {
          echo "* IP Address: " . $shopper->getIpAddress() . "\n";
        }
      }
    }

    if ($transactionsCount > 1) {
      echo "~~\n";
      echo "~~ Other transactions associated with that payment\n";
      echo "~~\n";

      foreach ($status->getTransactions() as $attempt) {
        if ($attempt->getTransactionId() != $transaction->getTransactionId()) {
          echo "Transaction ID: " . $attempt->getTransactionID() . "\n";
          if ($attempt->getRefTransactionID() != null) {
            echo "Referral Transaction ID: " . $attempt->getRefTransactionID() . "\n";
          }
          $attemptDate = $attempt->getDateAsDateTime();
          if ($attemptDate !== null) {
            echo "Date: " . $attemptDate->format("Y-m-d H:i:s T") . "\n";
          }

          echo "Payment type: " . $attempt->getPaymentMethod() . "\n";
          echo "Operation: " . $attempt->getOperation() . "\n";
          echo "Amount: " . number_format($attempt->getAmount() / 100, 2) . " " . $status->getCurrency() . "\n";
          echo "Result code: " . $attempt->getResultCode() . "\n";
          echo "Result message: " . $attempt->getResultMessage() . "\n";
          echo "~~\n";
        }
      }
    }
  } else {
    echo "No transaction attempt found for the payment.\n";
  }
} else {
  echo "Error: " . $c2pClient->getClientErrorMessage() . "\n";
}
    
    use PayXpert\Connect2Pay\Connect2PayClient;

    $url = "https://connect2.payxpert.com";
    // This will be provided once your account is approved
    $originator  = "000000";
    $password    = "Gr3atPassw0rd!";
    $merchantToken = "example"
    
    $c2pClient = new Connect2PayClient($url, $originator, $password);

    $status = $c2pClient->getPaymentStatus($merchantToken);

    if ($status != null && $status->getErrorCode() != null) {
      echo "Merchant token: " . $status->getMerchantToken() . "\n";
      echo "Status: " . $status->getStatus() . "\n";
      echo "Error code: " . $status->getErrorCode() . "\n";
    
      $transaction = $status->getLastTransactionAttempt();
    
      if ($transaction !== null) {
        echo "Number of transaction attempts: " . count($status->getTransactions()) . "\n";
        echo "Payment type: " . $transaction->getPaymentType() . "\n";
        echo "Operation: " . $transaction->getOperation() . "\n";
    
        echo "Error message: " . $transaction->getResultMessage() . "\n";
        echo "Transaction ID: " . $transaction->getTransactionID() . "\n";
    
        $transactionDate = $transaction->getDateAsDateTime();
        if ($transactionDate !== null) {
          echo "Transaction date: " . $transactionDate->format("Y-m-d H:i:s T") . "\n";
        }
    
        if ($transaction->getSubscriptionID()) {
          echo "Subscription ID: " . $transaction->getSubscriptionID() . "\n";
        }
        $paymentMeanInfo = $transaction->getPaymentMeanInfo();
        if ($paymentMeanInfo !== null) {
          switch ($transaction->getPaymentType()) {
            case Connect2PayClient::_PAYMENT_TYPE_CREDITCARD:
              if (!empty($paymentMeanInfo->getCardNumber())) {
                echo "Payment Mean Information:\n";
                echo "* Card Holder Name: " . $paymentMeanInfo->getCardHolderName() . "\n";
                echo "* Card Number: " . $paymentMeanInfo->getCardNumber() . "\n";
                echo "* Card Expiration: " . $paymentMeanInfo->getCardExpireMonth() . "/" . $paymentMeanInfo->getCardExpireYear() . "\n";
                echo "* Card Brand: " . $paymentMeanInfo->getCardBrand() . "\n";
    
                if (!empty($paymentMeanInfo->getCardLevel())) {
                  echo "* Card Level/subtype: " . $paymentMeanInfo->getCardLevel() . "/" . $paymentMeanInfo->getCardSubType() . "\n";
                  echo "* Card country code: " . $paymentMeanInfo->getIinCountry() . "\n";
                  echo "* Card bank name: " . $paymentMeanInfo->getIinBankName() . "\n";
                }
              }
    
              break;
            case Connect2PayClient::_PAYMENT_TYPE_TODITOCASH:
              if (!empty($paymentMeanInfo->getCardNumber())) {
                echo "Payment Mean Information:\n";
                echo "* Card Number: " . $paymentMeanInfo->getCardNumber() . "\n";
              }
    
              break;
            case Connect2PayClient::_PAYMENT_TYPE_BANKTRANSFER:
              $sender = $paymentMeanInfo->getSender();
              $recipient = $paymentMeanInfo->getRecipient();
    
              if ($sender !== null) {
                echo "Payment Mean Information:\n";
                echo "* Sender Account:\n";
                echo ">> Holder Name: " . $sender->getHolderName() . "\n";
                echo ">> Bank Name: " . $sender->getBankName() . "\n";
                echo ">> IBAN: " . $sender->getIban() . "\n";
                echo ">> BIC: " . $sender->getBic() . "\n";
                echo ">> Country code: " . $sender->getCountryCode() . "\n";
              }
    
              if ($recipient !== null) {
                echo "* Recipient Account:\n";
                echo ">> Holder Name: " . $recipient->getHolderName() . "\n";
                echo ">> Bank Name: " . $recipient->getBankName() . "\n";
                echo ">> IBAN: " . $recipient->getIban() . "\n";
                echo ">> BIC: " . $recipient->getBic() . "\n";
                echo ">> Country code: " . $recipient->getCountryCode() . "\n";
              }
    
              break;
            case Connect2PayClient::_PAYMENT_TYPE_DIRECTDEBIT:
              $account = $paymentMeanInfo->getBankAccount();
    
              if ($account !== null) {
                echo "Payment Mean Information:\n";
                echo "* Statement descriptor: " . $paymentMeanInfo->getStatementDescriptor() . "\n";
    
                $collectedAt = $paymentMeanInfo->getCollectedAtAsDateTime();
                if ($collectedAt != null) {
                  echo "* Collected At: " . $collectedAt->format("Y-m-d H:i:s T") . "\n";
                }
    
                echo "* Bank Account:\n";
                echo ">> Holder Name: " . $account->getHolderName() . "\n";
                echo ">> Bank Name: " . $account->getBankName() . "\n";
                echo ">> IBAN: " . $account->getIban() . "\n";
                echo ">> BIC: " . $account->getBic() . "\n";
                echo ">> Country code: " . $account->getCountryCode() . "\n";
    
                $sepaMandate = $account->getSepaMandate();
    
                if ($sepaMandate != null) {
                  echo "* SEPA mandate:\n";
                  echo ">> Description: " . $sepaMandate->getDescription() . "\n";
                  echo ">> Status: " . $sepaMandate->getStatus() . "\n";
                  echo ">> Type: " . $sepaMandate->getType() . "\n";
                  echo ">> Scheme: " . $sepaMandate->getScheme() . "\n";
                  echo ">> Signature type: " . $sepaMandate->getSignatureType() . "\n";
                  echo ">> Phone number: " . $sepaMandate->getPhoneNumber() . "\n";
    
                  $signedAt = $sepaMandate->getSignedAtAsDateTime();
                  if ($signedAt != null) {
                    echo ">> Signed at: " . $signedAt->format("Y-m-d H:i:s T") . "\n";
                  }
    
                  $createdAt = $sepaMandate->getSignedAtAsDateTime();
                  if ($createdAt != null) {
                    echo ">> Created at: " . $createdAt->format("Y-m-d H:i:s T") . "\n";
                  }
    
                  $lastUsedAt = $sepaMandate->getLastUsedAtAsDateTime();
                  if ($lastUsedAt != null) {
                    echo ">> Last used at: " . $lastUsedAt->format("Y-m-d H:i:s T") . "\n";
                  }
    
                  echo ">> Download URL: " . $sepaMandate->getDownloadUrl() . "\n";
                }
              }
    
              break;
          }
        }
    
        if ($status->getCtrlCustomData()) {
          echo "Custom Data: " . $status->getCtrlCustomData() . "\n";
        }
    
        $shopper = $transaction->getShopper();
        if ($shopper !== null) {
          echo "Shopper info:\n";
          echo "* Name: " . $shopper->getName() . "\n";
          echo "* Address: " . $shopper->getAddress() . " - " . $shopper->getZipcode() . " " . $shopper->getCity() . " - " .
               $shopper->getCountryCode() . "\n";
          echo "* Email: " . $shopper->getEmail() . "\n";
    
          if (!empty($shopper->getBirthDate())) {
            echo "* Birth date: " . $shopper->getBirthDate() . "\n";
          }
    
          if (!empty($shopper->getIdNumber())) {
            echo "* ID Number: " . $shopper->getIdNumber() . "\n";
          }
    
          if (!empty($shopper->getIpAddress())) {
            echo "* IP Address: " . $shopper->getIpAddress() . "\n";
          }
        }
      }
    } else {
      echo "Error: " . $c2pClient->getClientErrorMessage() . "\n";
    }

  // Instantiate the client and send the status request
  // Second argument is the originator ID, third one is the associated API key
  Connect2payClient c2p = new Connect2payClient("https://connect2.payxpert.com", "123456", "GreatP4ssw0rd");

  PaymentStatusRequest  request  = new PaymentStatusRequest();
  PaymentStatusResponse response = null;

  request.setMerchantToken("example");

  try {

    response = c2p.getPaymentStatus(request);
    System.out.println(response.getMerchantToken());
    System.out.println(response.getStatus());
    System.out.println(response.getErrorCode());

  } catch (Exception e) {
    logger.error("Ooops, an error occurred preparing the payment: " + e.getMessage());
    // Handle the error...
  }

  // Instantiate the client and send the status request
  // Second argument is the originator ID, third one is the associated API key
  Connect2payClient c2p = new Connect2payClient("https://connect2.payxpert.com", "123456", "GreatP4ssw0rd");

  PaymentStatusRequest  request  = new PaymentStatusRequest();
  PaymentStatusResponse response = null;

  request.setMerchantToken("example");

  try {

    response = c2p.getPaymentStatus(request);
    System.out.println(response.getMerchantToken());
    System.out.println(response.getStatus());
    System.out.println(response.getErrorCode());

  } catch (Exception e) {
    logger.error("Ooops, an error occurred preparing the payment: " + e.getMessage());
    // Handle the error...
  }

const paymentPage = require("payxpert")("123456", "GreatP4ssw0rd").connect2pay;

const responseConsultPayment = await paymentPage.consultPaymentStatus(merchantToken);

// Process responseConsultPayment here


var client = new Connect2PayClient(OriginatorConfig.ORIGINATOR_ID, OriginatorConfig.ORIGINATOR_PASSWORD);

var requestPaymentStatus = client.NewRequestPaymentStatus(response.merchantToken);
var responsePaymentStatus = await requestPaymentStatus.Send();

if (responsePaymentStatus.transactions.Count > 0)
{
    // ...
}