Pay.com gateway guide

Pay.com fact sheet

Additional notes
Google Pay (PAN only): Google Pay PAN-only transactions behave the same as normal credit card transactions. No wallet or token types are passed, and wallet type information is not returned. This behavior should be confirmed with gateway support..
Store and verify: Store and verify use the same API endpoint. Store operations return a third-party token, and verify operations do not support passing or validating that token. Third-party tokens are not supported in verify operations.
terminal_token GSF is mandatory for purchase, authorize, verify, capture, void, refund, and general credit transactions

Adding Pay.com gateway

To create a gateway in Spreedly, use the gateway type pay_dot_com with api_key and sandbox parameters.

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>pay_dot_com</gateway_type>
        <api_key>your_staging_api_key</api_key>
        <sandbox>true</sandbox>
      </gateway>'
'

<gateway>
    <token>4HSXC07QQH964ATGS314XXXKD3</token>
    <gateway_type>pay_dot_com</gateway_type>
    <name>Pay.com</name>
    <characteristics>
        <supports_purchase type="boolean">true</supports_purchase>
        <supports_authorize type="boolean">true</supports_authorize>
        <supports_capture type="boolean">true</supports_capture>
        <supports_partial_capture type="boolean">true</supports_partial_capture>
        <supports_credit type="boolean">true</supports_credit>
        <supports_partial_credit type="boolean">true</supports_partial_credit>
        <supports_general_credit type="boolean">true</supports_general_credit>
        <supports_void type="boolean">true</supports_void>
        <supports_adjust type="boolean">false</supports_adjust>
        <supports_verify type="boolean">true</supports_verify>
        <supports_reference_purchase type="boolean">false</supports_reference_purchase>
        <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
        <supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
        <supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
        <supports_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
        <supports_offsite_synchronous_authorize type="boolean">false</supports_offsite_synchronous_authorize>
        <supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
        <supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
        <supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
        <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
        <supports_store type="boolean">true</supports_store>
        <supports_remove type="boolean">true</supports_remove>
        <supports_fraud_review type="boolean">false</supports_fraud_review>
        <supports_network_tokenization type="boolean">true</supports_network_tokenization>
        <supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
        <supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
        <supports_transaction_retry type="boolean">true</supports_transaction_retry>
        <supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
        <supports_stored_credentials type="boolean">true</supports_stored_credentials>
    </characteristics>
    <credentials>
      <credential>
            <name>api_key</name>
            <value>your_staging_api_key</value>
      </credential>
    </credentials>
    <gateway_specific_fields>
        <gateway_specific_field>customer_reference_id</gateway_specific_field>
        <gateway_specific_field>statement_descriptor_suffix</gateway_specific_field>
        <gateway_specific_field>payment_method_options</gateway_specific_field>
        <gateway_specific_field>address_line1_check</gateway_specific_field>
        <gateway_specific_field>cvv_check</gateway_specific_field>
        <gateway_specific_field>receipt</gateway_specific_field>
        <gateway_specific_field>receipt_email</gateway_specific_field>
    </gateway_specific_fields>
    <payment_methods>
        <payment_method>credit_card</payment_method>
        <payment_method>third_party_token</payment_method>
        <payment_method>apple_pay</payment_method>
        <payment_method>google_pay</payment_method>
    </payment_methods>
</gateway>

Required Credentials

api_key: The API key for authentication. then it is used in x-paycom-api-key as HTTP headers. For more details regarding authentication check pay.com gateway Authentication Documentation: Authentication

All requests require the following HTTP headers:

x-paycom-api-key: The API key for authentication
Content-Type: application/json
Accept: application/json

Gateway Specific Fields

{
    "transaction": {
        "payment_method_token": "{{payment_method_token}}",
        "amount": 1950,
        "currency_code": "USD",
        "gateway_specific_fields": {
            "pay_dot_com": {
                "customer_reference_id": "customer_123",
                "statement_descriptor_suffix": "SUFFIX123",
                "payment_method_options": {
                    "card": {
                        "accepted_card_brands": ["visa", "mastercard", "amex", "discover", "jcb"],
                        "accepted_card_categories": [],
                        "accepted_card_funding": ["credit", "debit", "prepaid"],
                        "accepted_card_jurisdictions": ["domestic", "international"],
                        "duplicate_card_check": false,
                        "enforce_customer_name_as_cardholder_name": false,
                        "request_threed_secure": "automatic",
                        "security_checks": {
                            "address_line1_check": false,
                            "address_postal_code_check": false,
                            "cvv_check": false
                        }
                    }
                },
                "address_line1_check": false,
                "cvv_check": false,
                "receipt": true,
                "receipt_email": "[email protected]"
            }
        }
    }
}

Parameter Details

Field Name	Description
customer_reference_id	Use this to link a charge to your own customer record (e.g., user ID from your system). This helps when retrieving or reconciling charges with your internal customer data.
statement_descriptor_suffix	Text that appears on the cardholder’s bank statement as part of the transaction description. It’s usually appended to a prefix set for your account to form the full descriptor that the customer sees. This helps the customer recognize the charge.
payment_method_options	An object containing payment method–specific settings for this charge. For example, for card payments this might include accepted card brands, required security checks, 3DS settings, and validation options.
address_line1_check	A card security check flag that indicates whether the billing address line 1 should be validated (typically against the card issuer’s records). If true, the gateway will verify that the provided address matches what the card issuer has on file.
cvv_check	A card security code (CVV) validation flag. When enabled, the CVV/CVC entered by the customer will be validated by the card issuer as part of the authorization.
receipt	Often an object or indicators controlling receipt generation or settings for the charge. Depending on the API, it may specify whether to generate a receipt, what content to include, or receipt customization.
receipt_email	The email address where the payment receipt should be sent. If this is included in the charge request, the gateway will email a receipt to that address once the charge is successful.

Gateway Specific Response Fields

<gateway_specific_response_fields>
        <pay_dot_com>
            <amount_refunded type="integer">0</amount_refunded>
            <customer>cust_650623098462145537</customer>
            <payment_method>pm_card_654719976363527168</payment_method>
            <fingerprint>bac9ef368052b955daaadd05ee7a2afd482f30c4360d1943daf9ac26855af156</fingerprint>
            <partial_approval>nil</partial_approval>  
            <token>tok_card_643446746403312640</token>
            <refunded>nil</refunded>
            <underlying_network_details>
                <network>visa</network>
                <visa>
                    <arn>488080225633</arn>
                    <auth_code>357502</auth_code>
                    <payment_account_reference>28091588831139565690272472685</payment_account_reference>
                    <raw_response_code>00</raw_response_code>
                </visa>
            </underlying_network_details>
        </pay_dot_com>
    </gateway_specific_response_fields>

Parameter Details

Field	Description
amount_refunded	Total amount refunded for this transaction, in the smallest currency unit (e.g., cents for USD).
customer	customer identifier associated with the transaction in gateway.
payment_method	payment method identifier used for the transaction, usable for future transactions in gateway.
fingerprint	Unique card fingerprint for identifying the same physical card across transactions.
partial_approval	Indicates whether the transaction was partially approved (e.g., when the requested amount exceeds available funds but a partial amount was approved).
token	Card token generated by for the card used in this transaction, usable for future transactions.
refunded	Indicates whether the transaction has been fully or partially refunded.
underlying_network_details	Network-level transaction details from the card network (e.g., Visa, Mastercard), containing network-specific information such as network name and transaction ID.

Stored Credentials

For Pay.com , sending stored credential fields can be done using Spreedly’s first-class support. For any Authorize or Purchase request, you need to include two fields that provide Spreedly with more information about the nature of the transaction:

stored_credential_initiator
stored_credential_reason_type

These two fields set up the initial and subsequent transactions based on the conditions and pass the values to the gateway as follows:

Initial transaction: source_data.setup_future_usage = "off_session"
Subsequent transaction: source_data.underlying_network_id = "<network_transaction_id>" and off_session = true

Note:

Store and verify: Store and verify use the same API endpoint. Store operations return a third-party token, and verify operations do not support passing or validating that token. Third-party tokens are not supported in verify operations.