Skip to main content

Brands

Brand through which the transaction is performed. A specific list of parameters must be added to your SALE request based on the value of the brand parameter. Please note that for some brands, you must collect additional parameters as specified in the relevant sections. If you are unable to collect this data, you can use the checkout integration, and our system will collect required parameters

Supported brands​

Use the following brand names as values for the brand parameter in the requests:

applepay (see Appendix B for Sale operation details)
googlepay (see Appendix B for Sale operation details)
om-wallet
naps
vcard (see Appendix B for Sale operation details)

Appendix B​

You have to add to your SALE request specific list of parameters which is determined by the value for the brand parameter.

You should get additional information from account manager.

Apple Pay​

To use the Apple Pay payment method, configure the Wallets setting in the admin dashboard. Ensure that the payment provider has confirmed the Apple Pay certificates and verified your domain in the Apple Pay account.

To enable payers to make Apple Pay payments, you can either connect to the Checkout page or work directly via the S2S APM protocol:

Checkout Page: No additional development is required on your side.

S2S APM Protocol: You must be able to obtain the Apple Pay payment token and include it in the SALE request.

Regardless of the protocol you have to make settings in the admin panel and set the following configurations:

• Merchant Identifier, Country and Shop Name – according to the merchant’s data from Apple Pay Developper account
• Certificate and Private Key – generated Apple Pay certificate and private key
• Merchant Capabilities and Supported Networks – configurations for Apple Pay payments
• Processing Private Key – private key that uses for payment token decryption (requires if payment provider supports).

⚠️ Pay attention

Before using Apple Pay via S2S APM protocol, you should review next section carefully. There is a description on how you can obtain Apple Pay payment token (it refers to the official Apple Pay documentation)

  1. Each payment must be checked for Apple Pay accessibility
  2. Show Apple Pay button to your payers
  3. Validate the merchant identity
  4. Provide a payment request and create a session
  5. Receive Apple Pay payment token (paymentData object)

After you implement Apple Pay payment tokens generation on your site, you need to pass for the SALE request:

• brand = applepay
• parameters[paymentToken] - Apple Pay payment token

Request example
curl -d "action=SALE&client_key=YOUR_CLIENT_KEY&brand=applepay&order_id=ORDER12345&order_amount=100.01&order_currency=QAR&order_description=Product&payer_ip=123.123.123.123&return_url=http://client.site.com/return.php&identifier=USER_IDENTIFIER&parameters[paymentToken]={\"paymentData\":{\"data\":\"YOUR_ENCRYPTED_DATA\",\"signature\":\"YOUR_SIGNATURE\",\"header\":{\"publicKeyHash\":\"YOUR_PUBLIC_KEY_HASH\",\"ephemeralPublicKey\":\"YOUR_EPHEMERAL_PUBLIC_KEY\",\"transactionId\":\"YOUR_TRANSACTION_ID\"},\"version\":\"EC_v1\"},\"paymentMethod\":{\"displayName\":\"Visa 6244\",\"network\":\"Visa\",\"type\":\"credit\"},\"transactionIdentifier\":\"YOUR_TRANSACTION_IDENTIFIER\"},{\"transactionId\":\"TRANSACTION_ID_2\",\"version\":\"EC_v1\"},\"paymentMethod\":{\"displayName\":\"Visa 0224\",\"network\":\"Visa\",\"type\":\"debit\"},\"transactionIdentifier\":\"TRANSACTION_IDENTIFIER_2\"}&hash=YOUR_HASH" https://test.apiurl.com/post-va -k

We also recommend checking out the demo provided by Apple for Apple Pay: https://applepaydemo.apple.com/

Set Up Apple Pay

If you are using the S2S protocol for Apple Pay payments, you will need to configure your Apple Developer account. Follow these steps to set up Apple Pay in your Apple Developer account:

1. Create a Merchant ID in the "Certificates, Identifiers & Profiles" section.
2. Register and verify the domains involved in the interaction with Apple Pay (e.g., the checkout page URL where the Apple Pay button is placed) in the "Merchant Domains" section.
3. Create a Merchant Identity Certificate in the "Merchant Identity Certificate" section:

  • Generate a pair of certificates (*.csr and *.key) and upload the *.csr file in the "Merchant Identity Certificate" section.
  • Create a Merchant Identity Certificate based on the generated CSR file.
  • Download the *.pem file from the portal.

⚠️ Note

The *.csr file can be obtained from the payment provider that processes Apple Pay, and the *.pem file should be uploaded to your payment provider's dashboard, following their instructions.

4. Create a Processing Private Key in the "Apple Pay Payment Processing Certificate" section:

  • Generate a pair of certificates (*.csr and *.key) and upload the *.csr file.
  • Create a Payment Processing Certificate based on the generated CSR file.

For more detailed instructions on setting up Apple Pay, refer to the following resource: Learn more about setting up Apple Pay

Next, enter the data from your Apple Pay developer account into the platform's admin panel: Go to the "Merchants" section, initiate editing, open the "Wallets" tab, navigate to the Apple Pay settings, and fill in the following fields:

  • Merchant Identifier: Enter the Merchant ID.
  • Certificate: Upload the *.pem file downloaded from the "Merchant Identity Certificate" section.
  • Private Key: Upload the *.key file from the certificate pair generated for the Merchant Identity Certificate.
  • Processing Private Key (required for token decryption): Paste the text from the Processing Private Key file. Ensure it is a single line of text (without spaces or breaks) placed between "BEGIN" and "END."

Google Pay​

To provide the payers with the possibility of Google Pay™ payment you can connect to the Checkout or work directly via S2S APM protocol. Before using googlepay payment method, you should review this section carefully to meet all the Google Pay™ requirements:

  1. Overview the documentation on Google Pay Integration first:
    • for sites - Google Pay Web developer documentation
    • for Android app - Google Pay Android developer documentation
  2. Make sure you complete all the items on the integration checklist:
    • for sites - Google Pay Web integration checklist
    • for Android app - Google Pay Android integration checklist
  3. To brand your site with Google Pay elements, you must meet the requirements:
    • for sites - Google Pay Web Brand Guidelines
    • for Android app - Google Pay Android brand guidelines
  4. The merchants must adhere to the Google Pay APIs Acceptable Use Policy and accept the terms that the Google Pay API Terms of Service defines.

To work with Google Pay™ payments through gateway, you need to make settings in the admin panel. You can set the following configurations:
• choose the environment: TEST or PRODUCTION
• specify "Allowed Auth Method" - PAN_ONLY or CRYPTOGRAM_3DS
• determine "Supported Networks" - MASTERCARD, VISA, AMEX, DISCOVER, JCB
These configuration will be applied and used when platform interacts with Google Pay.
If you are using Checkout integration to work with googlepay payment method, it requires no additional code implementation.

If you are using S2S APM integration to work with googlepay payment method, you need to pass the additional parameters in the SALE request:
• brand = googlepay
• parameters[paymentToken] - Google Pay payment token.
To obtain Google Pay payment token you should get the PaymentData according to the Google Pay API Integration documentation (see the links above).
Pass the following parameters to receive PaymentData:
• allowPaymentMethods: CARD
• tokenizationSpecification = { "type": "PAYMENT_GATEWAY" }
• allowedCardNetworks = ['MASTERCARD', 'VISA', 'AMEX', 'DISCOVER', 'JCB'];
• allowedCardAuthMethods = ['PAN_ONLY', 'CRYPTOGRAM_3DS'];
• gateway = value provided by your support manager
• gatewayMerchantId = CLIENT_KEY (API key)

Example of data to get PaymentData
{
    "apiVersionMinor": 0,
    "apiVersion": 2,
    "paymentMethodData": {
        "description": "Mastercard •••• 5179",
        "tokenizationData": {
            "type": "PAYMENT_GATEWAY",
            "token": {
                "signature": "MEYCIQC+IHxUu9Wwra2Vu6tBa2wJPCMT3pWtN1VphLGYtNVLLwIhAOkdbNje//eLrXVc+n6LOlc4PqxWOUcqwrmki/CNA1ur",
                "intermediateSigningKey": {
                    "signedKey": "{\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwhRrvGB0kZ1248MEJAPwX0YfrQInhyyRM7nyGFjQuzGSViZG3QC9NMvXR9Zd6uVcVzAz+6K/+NEGIWbX8zbk6A\\u003d\\u003d\",\"keyExpiration\":\"1571208568000\"}",
                    "signatures": [
                        "MEUCIQCR6vIEiyHB8qmlho4/tLd7W8CIGrZDJlCI48CBHeFPvQIgLZJIe4cZv6pYtYYa56QCI/vvg1GqXTP3bTBjO49r5mI="
                    ]
                },
                "protocolVersion": "ECv2",
                "signedMessage": {
                    "encryptedMessage": "k85CGUMmd5PaGmQlHFqHc0HrDZmjM1yG82rFB/p31ZyUleN5nihzjOZif/BKXwg3XA2oLXqBSSWcAdfZwXxCEOqvAQE+kpTC7qVO4wTPip6RruraT6vO9M9FtIf0kcqzYSAN7pl1SUA5jC9rHrqucPoh0Sspup78SWBt8TnmVKC9O3sQhIZ3SMoGOG4mdjtIrgCwWH2cbrxUH0dHAqOe5ANGOY/mII4nTEp7xaKu41hK/kFE15zVyqgPJXP9bPxzMVk/ozEZSfhSzVTS+9stjkUkT5EibKB3O1bbxyybKcGQ5vxBOtNOBKKdNuqNmN2eEK3UbSKb1M3gv45gT9cCeEvlzO7Wg0N100vUBp9RPDN9TH4tj4w578sWFKfTi6FsSrZB27SGWcU0EaKHO9buo94mRBY5yqffF3bKg5mAMPzjDhyHSujqWKAs9C5fBzMEuEr2z7A23kfLqBceH5uS9LJMiZyVKCwfpY9u2XyCjKdp7Iu003d",
                    "ephemeralPublicKey": "BAMDAtfgcPNuzItrwGLigGj3rtxmyHhZLwx1B4RJZ2oo11jpFf3SA6a3utryCMmlCEcqLfLn6WDH2ArrNBGnEwu003d",
                    "tag": "TqhZXY53Fe4QBKafm6NqS6EzwVeiKXhRlp8NeWrAu003d"
                }
            }
        },
        "type": "CARD",
        "info": {
            "cardNetwork": "MASTERCARD",
            "cardDetails": "5179"
        }
    }
}

As a result you receive you will be returned a dataset with PaymentData.token object contains data that you need add to the SALE request as parameters[paymentToken] parameter.

Request Example
curl -d "action=SALE&client_key=YOUR_CLIENT_KEY&brand=googlepay&order_id=ORDER_ID&order_amount=100.01&order_currency=QAR&order_description=Product&payer_ip=123.123.123.123&return_url=http://client.site.com/return.php&identifier=USER_IDENTIFIER&parameters[paymentToken]={\"apiVersionMinor\": 0, \"apiVersion\": 2, \"paymentMethodData\": {\"description\": \"Mastercard •••• 5179\", \"tokenizationData\": {\"type\": \"PAYMENT_GATEWAY\", \"token\": {\"signature\": \"YOUR_SIGNATURE\", \"intermediateSigningKey\": {\"signedKey\": \"YOUR_SIGNED_KEY\", \"signatures\": [\"YOUR_SIGNATURE_2\"]}, \"protocolVersion\": \"ECv2\", \"signedMessage\": {\"encryptedMessage\": \"ENCRYPTED_MESSAGE\", \"ephemeralPublicKey\": \"EPHEMERAL_PUBLIC_KEY\", \"tag\": \"TAG\"}}}, \"type\": \"CARD\", \"info\": {\"cardNetwork\": \"MASTERCARD\", \"cardDetails\": \"5179\"}}}&hash=YOUR_HASH" https://test.apiurl.com/post-va -k

⚠️ Pay attention

in the case of PAN_ONLY, the responsibility for passing 3ds is transferred to the acquirer, through which the payment is processed

Set up Google Pay

The admin panel settings apply to merchants integrated with the platform via the Checkout protocol.

For merchants using the S2S protocol and obtaining the Google Pay payment token independently, these settings will not apply.

Exceptions are "Environment" and “Private Key” configurations.

The "Environment" configuration remains relevant, as it defines the environment where the token was generated and from which the platform expects to receive payment data. Ensure that the environment used to generate the payment token matches the corresponding setting in the admin panel to avoid processing issues.

The “Private Key” is required for Google token decryption. If it is absent, the card flow cannot be applied to the payment.

Additionally, to work with Google Pay payments, you must verify the website domains from which Google Pay is processed in the Google Business Console.

vcard​

To make payments on Test connector kindly set the value “vcard” for the brand parameter.

Sample curl request
curl -d "action=SALE&client_key=c2b8fb04-110f-11ea-bcd3-0242c0a85004&brand=vcard&
order_id=ORDER12345&order_amount=1.99&order_currency=QAR&order_description=Product&
[email protected]&payer_ip=123.123.123.123&
return_url=https://client.site.com/return.php&hash=2702ae0c4f99506dc29b5615ba9ee3c0" https://test.apiurl.com/post-va -k

To simulate success scenario use identifier parameter value [email protected] and [email protected] for decline.