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)
{
// ...
}