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.

πŸ“˜

You need to use the orderId and threeDSecureId parameters returned in the Authenticate Payer API response to call the Pay API.

πŸ“˜

Payment can be accepted in two ways, by using a combination of Authorisation 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.

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

ParameterDatatypeDescription
amountfloatThe total amount for the transaction. The amount must be greater than 0.01. Must not have more than 2 digits after the decimal point.
currencystringCurrency of the order for which the authentication is initiated. Please follow ISO 4217 alpha code standards for the currency code. The currency code must be 3 characters in length. The currencies must be limited to the list configured for your merchant account.
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.
paymentMethodstringPayment 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

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

Below is an example of executing a Pay call for a payment of 123.21 EGP with the mandatory parameters.

curl --location 'https://api.merchant.geidea.net/pgw/api/v1/direct/pay' \
--header 'accept: text/plain' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic NjYyMGMzZTItNTA4OC00MWE4LThiZTYtOThjMDAzMTUzOTMyOmY2Yzg3NGJkLTdjYTAtNGRhNi04MmVkLTQwMzkzNGViNDg4Yw==' \
--data '{
        "orderId": "0e5ff0f5-cbc0-4c25-86c0-08db103ef12c",
    "threeDSecureId": "cccaf72f-9abc-4852-535f-08db103ef15a",
    "amount": 123.21,
    "currency": "EGP",
    "paymentMethod": {
        "cardNumber": "5123450000000008",
        "cardholderName": "test",
        "cvv": "123",
        "expiryDate": {
            "month": 5,
            "year": 39
        }
    }
}'

API Response

The 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.
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": "906ac143-f842-490f-96b0-08db103ef12c",
        "amount": 123.00,
        "tipAmount": 0.00,
        "convenienceFeeAmount": 0.00,
        "totalAmount": 123.00,
        "settleAmount": 123.00,
        "currency": "EGP",
        "settleCurrency": "EGP",
        "language": "en",
        "detailedStatus": "Paid",
        "status": "Success",
        "threeDSecureId": "36bce7a8-ff67-497c-6dde-08db103ef15a",
        "merchantId": "6876f6bc-f8eb-4253-f160-08d973705ffb",
        "merchantPublicKey": "6620c3e2-5088-41a8-8be6-98c003153932",
        "parentOrderId": null,
        "merchantReferenceId": "string",
        "mcc": "7011",
        "callbackUrl": "https://webhook.site/b64f56f2-9423-4368-9aa3-e2de7f7bae33",
        "customerEmail": "[email protected]",
        "billingAddress": {
            "countryCode": "IND",
            "street": "Street 1",
            "city": "Hyderabad",
            "postCode": "500081"
        },
        "shippingAddress": {
            "countryCode": "IND",
            "street": "Street 1",
            "city": "Hyderabad",
            "postCode": "500081"
        },
        "returnUrl": "https://someurl.com",
        "cardOnFile": false,
        "tokenId": null,
        "initiatedBy": "Internet",
        "agreementId": "PG231",
        "agreementType": "Recurring",
        "paymentOperation": "Pay",
        "custom": "Payment for Subscription",
        "paymentIntent": null,
        "restrictPaymentMethods": true,
        "paymentMethods": null,
        "platform": {
            "integrationType": "API integration",
            "name": "GPG",
            "version": "2.0.9",
            "pluginVersion": "0.1.1",
            "partnerId": "G25021"
        },
        "statementDescriptor": {
            "name": "Electronics",
            "phone": "8123456789"
        },
        "description": "Payment for electronics",
        "createCustomer": false,
        "setDefaultPaymentMethod": true,
        "customerReferenceId": "string",
        "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa5",
        "recurrence": {
            "recurrenceId": "16d65092-bf91-4715-7310-08db10c07d88",
            "orderId": "906ac143-f842-490f-96b0-08db103ef12c",
            "amount": 10.00,
            "currency": "EGP",
            "cycleInterval": "Day",
            "cycleFrequency": 2,
            "numberOfPayments": 2,
            "startDate": "2023-02-27T00:00:00",
            "endDate": "2023-02-28T00:00:00",
            "minimumDaysBetweenPayments": 5,
            "description": "For Subscription ID - Appu Tech",
            "createdDate": "0001-01-01T00:00:00",
            "createdBy": "",
            "updatedDate": null,
            "updatedBy": null
        },
        "transactions": [
            {
                "transactionId": "36bce7a8-ff67-497c-6dde-08db103ef15a",
                "type": "Authentication",
                "status": "Failed",
                "amount": 123.00,
                "currency": "EGP",
                "source": "HPP",
                "authorizationCode": null,
                "rrn": null,
                "stan": null,
                "paymentMethod": {
                    "type": "Card",
                    "brand": "mastercard",
                    "cardholderName": "Test",
                    "maskedCardNumber": "512345******2346",
                    "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": "010",
                    "detailedResponseMessage": "User changed payment method"
                },
                "authenticationDetails": {
                    "acsEci": "02",
                    "authenticationToken": null,
                    "paResStatus": null,
                    "veResEnrolled": null,
                    "xid": null,
                    "accountAuthenticationValue": null,
                    "proofXml": null,
                    "threeDSecureServerTransactionId": "ee81dcff-f6a2-44c1-8874-0eb8392b8b42",
                    "acsTransactionId": "17c00cf5-7e3c-43b8-bbf2-4428e1a7ef21",
                    "directoryServerId": "A999999999",
                    "dsTransactionId": "b08153dc-fd12-4308-bf5d-3318c765b411",
                    "methodCompleted": false,
                    "methodSupported": "SUPPORTED",
                    "protocolVersion": "2.1.0",
                    "requestorId": "MAS00001_INT_MPGS_APTESTGEIDEAPF",
                    "requestorName": "GEIDEA",
                    "transactionStatus": "Y",
                    "statusReasonCode": null
                },
                "postilionDetails": null,
                "terminalDetails": null,
                "meezaDetails": null,
                "bnplDetails": null,
                "bankInstallmentDetails": null,
                "correlationId": "af532d57-08d0-480b-9367-cf1eb791d9ff",
                "parentTransactionId": null,
                "paymentAttemptId": "19325ca8-c2ec-4282-9acd-d81b77d1f24f",
                "acquirer": {
                    "additionalResponseData": null,
                    "batch": null,
                    "customData": null,
                    "date": null,
                    "id": null,
                    "merchantId": "GEIDEA_PF",
                    "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,
                "createdDate": "2023-02-27T08:43:55.3725184",
                "createdBy": "PGW",
                "updatedDate": "2023-02-27T08:45:23.5296506",
                "updatedBy": "PGW"
            },
            {
                "transactionId": "69df45a0-7aaf-4f71-6de0-08db103ef15a",
                "type": "Pay",
                "status": "Success",
                "amount": 123.00,
                "currency": "EGP",
                "source": "HPP",
                "authorizationCode": "228791",
                "rrn": "305808228791",
                "stan": "228791",
                "paymentMethod": {
                    "type": "Card",
                    "brand": "mastercard",
                    "cardholderName": "Test",
                    "maskedCardNumber": "512345******2346",
                    "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": "fd2a4e35-78ae-46ce-925c-927d92ccba6c",
                "parentTransactionId": null,
                "paymentAttemptId": "19325ca8-c2ec-4282-9acd-d81b77d1f24f",
                "acquirer": {
                    "additionalResponseData": null,
                    "batch": 20230227,
                    "customData": null,
                    "date": "0227",
                    "id": "BMNF_S2I",
                    "merchantId": "GEIDEA_PF",
                    "settlementDate": "2023-02-27T00: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,
                "createdDate": "2023-02-27T08:45:51.994227",
                "createdBy": "PGW",
                "updatedDate": "2023-02-27T08:45:54.1930168Z",
                "updatedBy": "PGW"
            }
        ],
        "orderItems": [],
        "isTokenPayment": false,
        "paymentMethod": {
            "type": "Card",
            "brand": "mastercard",
            "cardholderName": "Test",
            "maskedCardNumber": "512345******2346",
            "wallet": null,
            "expiryDate": {
                "month": 1,
                "year": 39
            },
            "sameBank": false,
            "issuingCountry": null,
            "fundingType": null,
            "issuingBank": null,
            "cardCategory": null
        },
        "totalAuthorizedAmount": 123.00,
        "totalCapturedAmount": 123.00,
        "totalRefundedAmount": 0,
        "orderSource": "GeideaGateway",
        "paymentBrands": [
            "mastercard"
        ],
        "multiCurrency": {
            "authCurrency": "EGP",
            "authAmount": 123.00,
            "settleCurrency": "EGP",
            "settleAmount": 123.00,
            "exchangeRate": null,
            "exchangeFeePercentage": null,
            "exchangeFeeAmount": null
        },
        "isTest": true,
        "cashOnDelivery": false,
        "amountToCollect": null,
        "isDownPayment": false,
        "exchangeRate": null,
        "exchangeFeePercentage": null,
        "exchangeFeeAmount": null,
        "deviceId": "deea6803-3360-4b65-c3c3-08db0a88a53d",
        "gatewayDecision": "ContinueToPay",
        "subscriptionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "subscriptionOccurrenceId": null,
        "customerPhoneNumber": "8123456789",
        "customerPhoneCountryCode": "+91",
        "createdDate": "2023-02-27T08:43:55.3725184",
        "createdBy": "PGW",
        "updatedDate": "2023-02-27T08:45:25.5720398",
        "updatedBy": "PGW"
    },
    "responseMessage": "Success",
    "detailedResponseMessage": "The operation was successful",
    "language": "en",
    "responseCode": "000",
    "detailedResponseCode": "000"
}