Complete the payment using the Pay API

You can complete the payment using the Pay API

Call the Pay operation as soon as you have executed the authentication operations successfully through the Initiate Authentication and Authenticate Payer API calls. You must use the same parameter values used in the
authentication operations or any mismatch between parameters will result in an error.

To carry out this operation, you will need the following details from other API calls:

ParameterDatatypeDescription
sessionIdStringA session ID is a unique identifier that a server generates as part of the response to the Create Session API call and assigns to a merchant transaction for the duration of the session (15 min). This must be a valid GUID.
orderIdStringThis is a unique identifier for this order to discern it from others order you created. If orderId is not sent with the request, an orderId is created by the server and returned in the response. The orderid can be used to refer to this order in subsequent transactions and in retrieving meta data about the order. The orderId must always be unique for every order created under your merchant profile. This must be a valid GUID. This is generated as part of the Initiate Authentication API call.
threeDSecureIdString3D Secure ID of the order created through the Authenticate Payer API operation.

πŸ“˜

Payment can be accepted in two ways, by using a combination of Authorization and Capture API calls or the Pay API. If you want the customer account to be debited immediately at the end of the API call, use the Pay API.

The Pay operation is used to perform an authorization on the card and capture the transaction in a single message.

API Request

To initiate a Pay API call, you will need to provide the following required fields.

ParameterDatatypeDescription
sessionIdStringA session ID is a unique identifier that a server generates as part of the create session API call and assigns to a merchant transaction for the duration of the session (15 min). This is the Id parameter in the session object, in the response of the Create Session API call.
orderIdStringThis is a unique identifier for this order to discern it from the other orders you created. If orderId is not sent with the request, an orderId is created by the server and returned in the response. The orderid can be used to refer to this order in subsequent transactions and in retrieving metadata about the order. The orderId must always be unique for every order created under your merchant profile. This must be a valid GUID.
threeDSecureIdString3D Secure ID of the order created through the Authenticate Payer operation.
paymentOperationStringType of payment operation that is carried out with this transaction
customerPhoneNumberStringCustomer's phone number eg: "511111111". If phoneCountryCode is passed, phoneNumber must be passed.
customerPhoneCountryCodeStringCountry code of customer's phone number eg: "+971". If phoneNumber is passed, phoneCountryCode must be passed
paymentMethodObjectPayment method used for the transaction. Use this to enter the card details.
paymentMethod.cardNumberStringValid card number, as a string without separators. Length of 16 for Visa, MasterCard, and Mada cards. Length of 15 for American Express cards.
paymentMethod.cardholderNameStringName on card
paymentMethod.cvvStringCard Verification Value. This code is usually composed of a three-digit number provided and available at the back of the card or 4 digit number above the card number on the right side on the front of the card
paymentMethod.expiryDateObjectExpiry month and year of the card
paymentMethod.expiryDate.monthString2 digit number for the month
paymentMethod.expiryDate.yearString2-digit year code
returnUrlStringThe URL where the client will be automatically redirected to once the Authentication process has been successful. Must be dynamic, based on the order being created. Must be a URL with a HTTPS protocol.
sourceStringSource of capturing the transaction, like, HPP

You can find a complete list of parameters which can be used with the Authenticate Payer API here.

πŸ“˜

You can use various test cards available here to test this API.

Below is an example of executing a Pay call with the mandatory parameters.

❗️

Amount and Currency passed in this API will not be picked up for processing

Please note the Amount and Currency for the transaction must be passed in the Create Session API only. This Session ID in this API call will be processed at the backend to pick the Amount and Currency for processing the payment.

Sample Request

curl --location 'https://api.merchant.geidea.net/pgw/api/v2/direct/pay' \
--header 'accept: text/plain' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic NDAyMjVhODktYmUzMS00ZjJlLWExMGEtMjdiMmJiYzRlM2IzOjlmMzdkOTg1LWIzOGUtNGM5MS1iNGIyLTQxMDU1M2ZkZjA4Yg==' \
--data '{
    "orderId": "32da2ee6-64fb-4cda-e85c-08dc33b7e268",
    "threeDSecureId": "bd55e727-529a-4174-b8e7-08dc33b7e269",
    "sessionId": "833432e9-c17c-4baa-5390-08dc33dd067b",
    "paymentOperation": "Pay",
    "customerPhoneNumber": null,
    "customerPhoneCountryCode": null,
    "paymentMethod": {
        "cardholderName": "otst-PUT",
        "cardNumber": "5123450000000008",
        "cvv": "100",
        "expiryDate": {
            "month": 1,
            "year": 39
        }
    },
    "ReturnUrl": "https://omnytr.free.beeceptor.com",
    "source": "MobileApp"
}'
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.merchant.geidea.net/pgw/api/v2/direct/pay',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "orderId": "32da2ee6-64fb-4cda-e85c-08dc33b7e268",
    "threeDSecureId": "bd55e727-529a-4174-b8e7-08dc33b7e269",
    "sessionId": "833432e9-c17c-4baa-5390-08dc33dd067b",
    "paymentOperation": "Pay",
    "customerPhoneNumber": null,
    "customerPhoneCountryCode": null,
    "paymentMethod": {
        "cardholderName": "otst-PUT",
        "cardNumber": "5123450000000008",
        "cvv": "100",
        "expiryDate": {
            "month": 1,
            "year": 39
        }
    },
    "ReturnUrl": "https://omnytr.free.beeceptor.com",
    "source": "MobileApp"
}',
  CURLOPT_HTTPHEADER => array(
    'accept: text/plain',
    'Content-Type: application/json',
    'Authorization: Basic NDAyMjVhODktYmUzMS00ZjJlLWExMGEtMjdiMmJiYzRlM2IzOjlmMzdkOTg1LWIzOGUtNGM5MS1iNGIyLTQxMDU1M2ZkZjA4Yg=='
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

API Response

The key parameters sent in the API response are as follows:

ParameterDescription
orderIdThis is a unique identifier for this order to discern it from the other orders you created. This value is echoed from the request.
amountThe amount for which the purchase has been initiated.
currencyThe currency in which the purchase has been initiated.
responseMessageDetailed message associated with response from gateway
detailedResponseMessageMessage associated with response from gateway
languageLanguage used for API request
responseCodeCode associated with response message returned by the gateway
detailedResponseCodeDetailed Code associated with response message returned by the gateway

A sample response for a Pay API call is as follows:

{
    "order": {
        "orderId": "a01e4c7a-8125-4f1b-5a52-08dc33b78153",
        "amount": 1850.00,
        "tipAmount": 0.00,
        "convenienceFeeAmount": 0.00,
        "totalAmount": 1850.00,
        "settleAmount": 1850.00,
        "currency": "EGP",
        "settleCurrency": "EGP",
        "language": "en",
        "detailedStatus": "Paid",
        "status": "Success",
        "threeDSecureId": "ea2496d1-a619-4b9a-111f-08dc33b7815d",
        "merchantId": "4907f9f6-af43-434a-340a-08da8933ece3",
        "merchantPublicKey": "40225a89-be31-4f2e-a10a-27b2bbc4e3b3",
        "parentOrderId": null,
        "merchantReferenceId": null,
        "mcc": "4011",
        "callbackUrl": "https://webhook.site/af2f847c-6de5-4174-b406-81141137a132",
        "billingAddress": null,
        "shippingAddress": null,
        "returnUrl": "https://webhook.site/92c440a0-4b17-4f96-ad72-bb8c91080f05",
        "cardOnFile": false,
        "tokenId": null,
        "initiatedBy": "Internet",
        "agreementId": null,
        "agreementType": null,
        "amountVariability": null,
        "paymentOperation": "Pay",
        "custom": null,
        "paymentIntent": null,
        "restrictPaymentMethods": false,
        "paymentMethods": null,
        "platform": null,
        "statementDescriptor": null,
        "description": null,
        "setDefaultPaymentMethod": false,
        "recurrence": null,
        "transactions": [
            {
                "transactionId": "ea2496d1-a619-4b9a-111f-08dc33b7815d",
                "type": "Authentication",
                "status": "Success",
                "amount": 1850.00,
                "currency": "EGP",
                "source": "DirectAPI",
                "authorizationCode": null,
                "rrn": null,
                "stan": "0",
                "paymentMethod": {
                    "type": "Card",
                    "brand": "mastercard",
                    "cardholderName": "kanti",
                    "maskedCardNumber": "512345******0008",
                    "wallet": null,
                    "expiryDate": {
                        "month": 1,
                        "year": 39
                    },
                    "sameBank": false,
                    "issuingCountry": null,
                    "fundingType": null,
                    "issuingBank": null,
                    "cardCategory": null
                },
                "codes": {
                    "acquirerCode": null,
                    "acquirerMessage": null,
                    "responseCode": "000",
                    "responseMessage": "Success",
                    "detailedResponseCode": "000",
                    "detailedResponseMessage": "The operation was successful"
                },
                "authenticationDetails": {
                    "acsEci": "02",
                    "authenticationToken": "kHyn+7YFi1EUAREAAAAvNUe6Hv8=",
                    "paResStatus": null,
                    "veResEnrolled": null,
                    "xid": "cd652834-863c-48e1-8686-05dd9c5a15f5",
                    "accountAuthenticationValue": null,
                    "proofXml": null,
                    "threeDSecureServerTransactionId": null,
                    "acsTransactionId": "c8c22e2a-1a86-4170-b169-a9895626e8b3",
                    "directoryServerId": "A999999999",
                    "dsTransactionId": "cd652834-863c-48e1-8686-05dd9c5a15f5",
                    "methodCompleted": false,
                    "methodSupported": "SUPPORTED",
                    "protocolVersion": "2.1.0",
                    "requestorId": "MAS00001_INT_MPGS_MTTESTGEIDEATESTE",
                    "requestorName": "Geidea Technology",
                    "transactionStatus": "Y",
                    "statusReasonCode": null,
                    "acsReferenceNumber": null,
                    "dsReferenceNumber": null
                },
                "postilionDetails": null,
                "terminalDetails": null,
                "meezaDetails": null,
                "bnplDetails": null,
                "bankInstallmentDetails": null,
                "correlationId": "24f2b523-a48b-43a8-b5e2-6a06589259f9",
                "parentTransactionId": null,
                "paymentAttemptId": "f4a0940b-1d1e-4336-b5bb-505293c04e42",
                "acquirer": {
                    "additionalResponseData": null,
                    "batch": null,
                    "customData": null,
                    "date": null,
                    "id": null,
                    "merchantId": "001222222222",
                    "settlementDate": null,
                    "time": null,
                    "timeZone": null,
                    "transactionId": null
                },
                "authorizationResponse": {
                    "autoExpiry": null,
                    "avsCode": null,
                    "cardLevelIndicator": null,
                    "cardSecurityCodeError": null,
                    "cardSecurityCodePresenceIndicator": null,
                    "commercialCard": null,
                    "commercialCardIndicator": null,
                    "financialNetworkCode": null,
                    "financialNetworkDate": null,
                    "marketSpecificData": null,
                    "merchantAdviceCode": null,
                    "paySvcData": null,
                    "posData": null,
                    "posEntryMode": null,
                    "posEntryModeChanged": null,
                    "processingCode": null,
                    "responseCode": null,
                    "date": null,
                    "responseMessage": null,
                    "returnAci": null,
                    "time": null,
                    "timeZone": null,
                    "trackQuality": null,
                    "transactionIdentifier": null,
                    "transactionIntegrityClass": null,
                    "validationCode": null,
                    "vpasResponse": null
                },
                "madaDetails": null,
                "refundType": null,
                "refundStatus": null,
                "isExtensionComplete": null,
                "extensionDate": "2024-02-29T05:57:14.3195946",
                "deviceId": null,
                "createdDate": "2024-02-29T05:55:15.3453855",
                "createdBy": "PGW",
                "updatedDate": "2024-02-29T05:57:14.3203156",
                "updatedBy": "PGW"
            },
            {
                "transactionId": "96f7ed6a-87d4-4a69-bb5e-08dc33b7e269",
                "type": "Pay",
                "status": "Success",
                "amount": 1850.00,
                "currency": "EGP",
                "source": "HPP",
                "authorizationCode": "007405",
                "rrn": "406005007405",
                "stan": "7405",
                "paymentMethod": {
                    "type": "Card",
                    "brand": "mastercard",
                    "cardholderName": "otst-PUT",
                    "maskedCardNumber": "512345******0008",
                    "wallet": null,
                    "expiryDate": {
                        "month": 1,
                        "year": 39
                    },
                    "sameBank": false,
                    "issuingCountry": null,
                    "fundingType": null,
                    "issuingBank": null,
                    "cardCategory": null
                },
                "codes": {
                    "acquirerCode": "00",
                    "acquirerMessage": "Approved",
                    "responseCode": "000",
                    "responseMessage": "Success",
                    "detailedResponseCode": "000",
                    "detailedResponseMessage": "The operation was successful"
                },
                "authenticationDetails": null,
                "postilionDetails": null,
                "terminalDetails": null,
                "meezaDetails": null,
                "bnplDetails": null,
                "bankInstallmentDetails": null,
                "correlationId": "f9115d04-b8df-41d4-ad36-5467212a535e",
                "parentTransactionId": null,
                "paymentAttemptId": "f4a0940b-1d1e-4336-b5bb-505293c04e42",
                "acquirer": {
                    "additionalResponseData": null,
                    "batch": 20240229,
                    "customData": null,
                    "date": "0229",
                    "id": "NBE_S2I",
                    "merchantId": "001222222222",
                    "settlementDate": "2024-02-29T00:00:00",
                    "time": null,
                    "timeZone": "+0200",
                    "transactionId": "123456789"
                },
                "authorizationResponse": {
                    "autoExpiry": null,
                    "avsCode": null,
                    "cardLevelIndicator": null,
                    "cardSecurityCodeError": "M",
                    "cardSecurityCodePresenceIndicator": null,
                    "commercialCard": "888",
                    "commercialCardIndicator": "3",
                    "financialNetworkCode": "777",
                    "financialNetworkDate": null,
                    "marketSpecificData": null,
                    "merchantAdviceCode": null,
                    "paySvcData": null,
                    "posData": "1025100006600",
                    "posEntryMode": "812",
                    "posEntryModeChanged": null,
                    "processingCode": "003000",
                    "responseCode": "00",
                    "date": null,
                    "responseMessage": null,
                    "returnAci": null,
                    "time": null,
                    "timeZone": null,
                    "trackQuality": null,
                    "transactionIdentifier": "123456789",
                    "transactionIntegrityClass": null,
                    "validationCode": null,
                    "vpasResponse": null
                },
                "madaDetails": null,
                "refundType": null,
                "refundStatus": null,
                "isExtensionComplete": null,
                "extensionDate": "2024-02-29T05:57:29.9931386Z",
                "deviceId": null,
                "createdDate": "2024-02-29T05:57:28.3705469",
                "createdBy": "PGW",
                "updatedDate": "2024-02-29T05:57:29.9938619Z",
                "updatedBy": "PGW"
            }
        ],
        "orderItems": [],
        "isTokenPayment": false,
        "paymentMethod": {
            "type": "Card",
            "brand": "mastercard",
            "cardholderName": "otst-PUT",
            "maskedCardNumber": "512345******0008",
            "wallet": null,
            "expiryDate": {
                "month": 1,
                "year": 39
            },
            "sameBank": false,
            "issuingCountry": null,
            "fundingType": null,
            "issuingBank": null,
            "cardCategory": null
        },
        "totalAuthorizedAmount": 1850.00,
        "totalCapturedAmount": 1850.00,
        "totalRefundedAmount": 0,
        "orderSource": "GeideaGateway",
        "paymentBrands": [
            "mastercard"
        ],
        "multiCurrency": {
            "authCurrency": "EGP",
            "authAmount": 1850.00,
            "settleCurrency": "EGP",
            "settleAmount": 1850.00,
            "exchangeRate": null,
            "exchangeFeePercentage": null,
            "exchangeFeeAmount": null
        },
        "isTest": true,
        "cashOnDelivery": false,
        "amountToCollect": null,
        "isDownPayment": false,
        "exchangeRate": null,
        "exchangeFeePercentage": null,
        "exchangeFeeAmount": null,
        "deviceId": null,
        "gatewayDecision": "ContinueToPay",
        "subscriptionId": null,
        "subscriptionOccurrenceId": null,
        "refundType": null,
        "refundStatus": null,
        "bankId": "1003",
        "isPayWithToken": false,
        "customerName": null,
        "customerEmail": null,
        "createCustomer": false,
        "customerReferenceId": null,
        "customerId": null,
        "customerPhoneNumber": null,
        "customerPhoneCountryCode": null,
        "customerCustomValue": null,
        "airLine": null,
        "createdDate": "2024-02-29T05:55:15.3453855",
        "createdBy": "PGW",
        "updatedDate": "2024-02-29T05:55:48.5924015",
        "updatedBy": "PGW"
    },
    "responseMessage": "Success",
    "detailedResponseMessage": "The operation was successful",
    "language": "en",
    "responseCode": "000",
    "detailedResponseCode": "000"
}