PayPal

PayPal® eCommerce Customers

You can link your hosted payment page to your PayPal merchant account to offer another payment option to your buyers. These transactions process through the PayPal platform, but Converge will display the results and issue email receipts or confirmations.

If you already have a PayPal account, all you need to do is register your PayPal Payer ID in Converge to enable the feature.

If you don't have an existing PayPal merchant account, you can register for one through Converge. You can find PayPal Registration and/or Activation in Converge at Settings > Payment Extensions, and in Classic at Terminal > Advanced > System Setup.

Once you enable this feature, customers who arrive at your hosted payment page will automatically see the option to pay with their PayPal account.

PayPal Express Checkout

This message format is used to process PayPal Express Checkout transactions.

error_outline
note
  • Market Segment
    PayPal Express Checkout is available only for Internet based Terminals
  • PayPal Boarding and Enablement
    • You must login to Converge and enable PayPal Express Checkout on your Terminal.
    • You must set up your Bank Account information on PayPal to accept deposits after the transactions are settled.
  • PayPal Branding Guidelines
    You must adhere to the PayPal Branding guidelines.

PayPal Sale (pesale)

The pesale is a transaction in which an authorization and transaction is entered into the unsettled batch (of Converge). This transaction is used to obtain real-time authorization for a PayPal Sale transaction.

error_outline
note

The transaction will be authorized and settled on PayPal.

Request

Input Field Name Req? Description
ssl_transaction_type Y PayPal Express Checkout Sale (pesale
ssl_merchant_id Y Converge ID as provided by Elavon.
ssl_user_id Y Converge User ID as configured on Converge, case sensitive.
ssl_pin Y Converge PIN as configured within Converge, case sensitive.
ssl_amount Y Transaction Sale Amount. Number with 2 decimal places.
This amount includes the Net amount and Sales Tax.
  • The authorized amount passed on request should not contain the tip amount, tips must be passed separately. The total authorized amount will be calculated during the authorization if tip is provided. For example: 1.00.
  • For those terminals processing Multi-Currency, be sure to submit the correct number of decimal places for the transaction as some currencies have no exponents and some can have three.
ssl_invoice_number N The invoice or ticket number.
ssl_description N The description, merchant defined value.
ssl_customer_code N Recommended for purchasing cards.
The Customer Code or PO Number that appears on the cardholder's credit card billing statement.
ssl_transaction_currency N Use only with a terminal that is set up with Multi-Currency.
Transaction currency alphanumeric code must be included in the request to indicate the currency in which you wish to process. If omitted, the terminal default currency is assumed (for example: USD, CAD, and JPY). More than 25 currencies are supported and must be enabled on your PayPal Account before you can start using this feature.
ssl_product_string N Product string for PayPal transactions
If submitted the line item products will be displayed to the Customer on the PayPal Express Checkout site.
Multiple Products can be sent in this list in the format below
Amount::Quantity::Description
Amount::Quantity::Description
ssl_eWallet_shipping N Wallet shipping option to indicate if the shipping address information used is retrieved from the PayPal website or the merchant’s website. Default is N.
Valid values:
  • Y = Use the Shipping address stored in PayPal
  • N = Use the Shipping address from the merchant website or payment form
ssl_paypal_credit N If you are eligible to accept PayPal Credit, then you can send the PayPal Credit Option with your transaction request
Valid values:
  • Y = Show the PayPal Credit checkout flow to the buyer

Response

Output Field Name Description
ssl_result Outcome of a transaction. A response that contains ssl_result of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.
ssl_result_message Transaction result message. Example: APPROVAL, PARTIAL APPROVAL. Refer to the API Reference for an extensive list of possible returned messages.
ssl_txn_id Transaction identification number. This is a unique number used to identify the transaction.
ssl_txn_time Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.
ssl_amount The total transaction authorized or approved amount. This amount will include tip if tip has been provided in the request. Returned based on merchant setup.
ssl_balance_due Remaining balance due in the ssl_balance_due field. Thisis the difference of the amount requested versus the amount authorized that the merchant has to collect from the consumer on partial approvals only.
ssl_invoice_number The invoice or ticket number sent originally on the request. Returned based on merchant setup.
ssl_transaction_currency Transaction currency. Returned only if terminal is setup for Multi-Currency.
errorCode Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information.
errorMessage Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information.
errorName Error name or reason for the error returned only if an error occurred. Refer to the Error Codes section for more information.

Examples

PayPal Express Checkout Auth Only (peauthonly)

Use peauthonly to get a real-time authorization for a PayPal Express Checkout transaction. This transaction will guarantee that the funds are available on the PayPal Account and reduce the cardholder‘s limit to buy for a preset amount of time - usually 7-10 days based on the credit card’s issuing bank. However, when using peauthonly, the authorization will not appear in the batch for settlement.

To place the transaction in the open batch, you must convert the authorization to Sale using cccomplete or reverse it using ccdelete to restore the funds back to the card.

To place the transaction in the open batch, it must be converted to Sale using cccomplete, or reversed using ccdelete to restore the funds back to the card.

Input Field Name Req? Description
ssl_transaction_type Y PayPal Express Checkout Sale (peauthonly)
ssl_merchant_id Y Converge ID as provided by Elavon.
ssl_user_id Y Converge User ID as configured on Converge, case sensitive.
ssl_pin Y Converge PIN as configured within Converge, case sensitive.
ssl_amount Y Transaction Sale Amount. Number with 2 decimal places. This amount includes the Net amount and Sales Tax.
  • The authorized amount passed on request should not contain the tip amount, tips must be passed separately. The total authorized amount will be calculated during the authorization if tip is provided. For example: 1.00.
  • For those terminals processing Multi-Currency, be sure to submit the correct number of decimal places for the transaction as some currencies have no exponents and some can have three.
ssl_invoice_number N The invoice or ticket number.
ssl_description N The description, merchant defined value.
ssl_customer_code N Recommended for purchasing cards.
The Customer Code or PO Number that appears on the cardholder's credit card billing statement.
ssl_salestax N Recommended for purchasing cards.
Sales tax amount applied to this transaction in decimal. Tax exempt transactions can pass 0.00 to properly reflect a tax exempt transaction.
ssl_transaction_currency N Use only with a terminal that is setup with Multi-Currency.
Transaction currency alphanumeric code must be included in the request to indicate the currency in which you wish to process. If omitted, the terminal default currency is assumed (for example: USD, CAD, and JPY). More than 25 currencies are supported and must be enabled on your PayPal Account before you can start using this feature.
ssl_product_string N Product string for PayPal transactions
If submitted the line item products will be displayed to the Customer on the PayPal Express Checkout site.
Multiple Products can be sent in this list in the format below
Amount::Quantity::Description
Amount::Quantity::Description
ssl_eWallet_shipping N Wallet shipping option to indicate if the shipping address information used is retrieved from the PayPal website or the merchant’s website. Default is N.
Valid values:
  • Y = Use the Shipping address stored in PayPal
  • N = Use the Shipping address from the merchant website or payment form
ssl_paypal_credit N If you are eligible to accept PayPal Credit, then you can send the PayPal Credit Option with your transaction request
Valid values:
  • Y = Show the PayPal Credit checkout flow to the buyer

Response

Output Field Name Description
ssl_result Outcome of a transaction. A response that contains ssl_result of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized. Refer to the API Reference for an extensive list of possible returned messages.
ssl_result_message Transaction result message. Example: APPROVAL, PARTIAL APPROVAL. Refer to the API Reference for an extensive list of possible returned messages.
ssl_txn_id Transaction identification number. This is a unique number used to identify the transaction. This value can be used to complete the Auth Only transaction.
ssl_txn_time Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.
ssl_approval_code Transaction approval code.
ssl_amount Transaction authorized or approved amount. Returned based on merchant setup.
ssl_requested_amount The amount originally requested on partial approvals only.
ssl_balance_due Remaining balance due in the ssl_balance_due field. Thisis the difference of the amount requested versus the amount authorized that the merchant has to collect from the consumer on partial approvals only.
ssl_invoice_number The invoice or ticket number sent originally on the request. Returned based on merchant setup.
ssl_transaction_currency Transaction currency. Returned only if terminal is setup for Multi-Currency.
ssl_card_short_description Card description, valid values are: AMEX, CUP, DISC, MC, PP, and VISA.
ssl_card_type Card type, valid values are: CASH, CREDITCARD, DEBITCARD, FOODSTAMP, GIFTCARD or LOYALTY.
errorCode Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information.
errorMessage Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information.
errorName Error name or reason for the error returned only if an error occurred. Refer to the Error Codes section for more information.

error_outline
important
  • In all of these examples, you will have to change the data values, such as my_merchant_id, my_user_id, my_pin, and transaction data to match your Converge account and meet the needs of your website.
  • Code samples provided are for demonstration only and should not be used for live transactions. All sensitive merchant data, including transaction amounts and your Converge credentials, should be placed in server side code, rather than in hidden value fields on an HTML form.

PayPal Express Checkout Return (pereturn)

The pereturn transaction is used to issue a partial or a full return (refund) to a cardholder’s credit card using the Transaction ID of the original Sale or Force transaction. This will guarantee that the same credit card used previously for the purchase is the one being refunded.

Users may choose to generate a partial return by passing the original Transaction ID of the Sale or Force transaction and an amount that is less than the original amount, or a full return by passing the original Transaction ID only without the amount. Enhanced credits for an amount higher than the original Sale/Force amount are not allowed.

error_outline
note

Converge will continue to allow merchants to refund credit card transactions using full card number/track data per current functionality using cccredit. We strongly advise using the ccreturn to reduce risks associated with refund abuse.

Request

Input Field Name Req? Description
ssl_transaction_type Y PayPal Express Checkout Credit (pereturn)
ssl_merchant_id Y Converge ID as provided by Elavon.
ssl_pin Y Converge PIN as configured within Converge, case sensitive.
ssl_user_id Y Converge User ID as configured on Converge, case sensitive.
ssl_txn_id Y Unique identifier returned on the original transaction.
ssl_amount N Amount to be refunded in full or partial. Number with two decimal places. Must be less or equal to the original purchase, if not supplied original full amount is refunded. For example: 1.00.

Response

Output Field Name Description
ssl_result Outcome of a transaction. A response that contains ssl_result of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.
ssl_result_message Transaction result message. Example: APPROVAL.
ssl_txn_id Transaction identification number. This is a unique number used to identify the transaction.
ssl_txn_time Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.
ssl_amount Transaction authorized or approved amount. Returned based on merchant setup.
ssl_approval_code Transaction approval code.
ssl_email Returned based on merchant setup.
ssl_invoice_number The invoice or ticket number sent originally on the request. Returned based on merchant setup.
errorCode Error code returned only   if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information.
errorMessage Detailed explanation of the error returned only   if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information.
errorName Error name or reason for the error returned only   if an error occurred. Refer to the Error Codes section for more information.

PayPal ExpressCheckout Void (pevoid)

The pevoid is a transaction that removes a PayPal AUTH ONLY transaction from the open batch. No funds will deposit into the paypal bank account at settlement. The pevoid command is typically used for same day returns or to correct cashier mistakes. You can only perform this action before the batch is settled. To perform a pevoid, you must submit the Transaction ID received from the original transaction.

Request

Input Field Name Req? Description
ssl_transaction_type Y PayPal ExpressCheckout Void (pevoid)
ssl_merchant_id Y Converge ID as provided by Elavon.
ssl_user_id Y Converge User ID as configured on Converge, case sensitive.
ssl_pin Y Converge PIN as configured within Converge, case sensitive.
ssl_txn_id Y Unique identifier returned on the original transaction.

Response

Output Field Name Description
ssl_result Outcome of a transaction. A response that contains ssl_result of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.
ssl_result_message Transaction result message. Example: APPROVAL.
ssl_txn_id Transaction identification number. This is a unique number used to identify the transaction.
ssl_txn_time Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.
ssl_email Returned based on merchant setup.
ssl_invoice_number The invoice or ticket number sent originally on the request. Returned based on merchant setup.
errorCode Error code returned only   if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information.
errorMessage Detailed explanation of the error returned only   if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information.
errorName Error name or reason for the error returned only   if an error occurred. Refer to the Error Codes section for more information.

PayPal Express Checkout Completion (pecomplete)

A transaction type of pecomplete places an approved Auth Only transaction into the open batch for settlement.

You can convert an Auth Only transaction to a Sale by sending a pecomplete transaction with a Transaction ID that belongs to an Auth Only transaction. All transactions converted to Sale will be placed in the open batch and are handled the same way as Sale transactions.

The following completion types are supported:

  • Full completion: Send pecomplete with the Auth Only Transaction ID without any amount, if you want to convert an existing Auth Only to Sale. The entire Auth Only transaction will move from the Auth Only batch to the Main batch for settlement.

  • Partial-completion: Send pecomplete with the Auth Only Transaction ID with an amount that is less than the original Auth Only amount, if you wish to convert only a portion of the Auth Only to Sale. The Auth Only transaction will move from the Auth Only batch to the Main batch and the transaction will only be settled for smaller amount. You will not be able to use the original Auth Only transaction again.

  • Multi partial-completion: Send pecomplete with the Auth Only Transaction ID with an amount that is less than the Auth Only amount and the Partial Shipment flag, this action will allow you to keep the unused portion of the Auth Only in the Auth Only batch, and convert only the selected portion to the Main batch. The Auth Only will remain in the Auth Only batch and you can perform multiple completions on the single Auth Only transaction until the total amount has been reached. Every completion will create a new fresh sale.

Request

Input Field Name Req? Description
ssl_transaction_type Y PayPal Express Checkout Completion (pecomplete)
ssl_merchant_id Y Converge ID as provided by Elavon.
ssl_user_id Y Converge User ID as configured on Converge, case sensitive.
ssl_pin Y Converge PIN as configured within Converge, case sensitive.
ssl_txn_id Y Unique identifier returned on the original transaction.
ssl_amount N Amount to be refunded in full or partial. Number with two decimal places. Must be less or equal to the original purchase, if not supplied original full amount is refunded. For example: 1.00.
ssl_partial_shipment_flag N Partial shipment flag to indicate the support of partial shipments, defaulted to N if not sent.
Valid values:
  • N – Partial Shipment not supported
  • Y – Partial Shipment supported
  • Response

    Output Field Name Description
    ssl_result Outcome of a transaction. A response that contains ssl_result of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.
    ssl_result_message Transaction result message. Example: APPROVAL.
    ssl_txn_id Transaction identification number. This is a unique number used to identify the transaction.
    ssl_txn_time Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.
    ssl_amount Transaction amount. Returned based on merchant setup.
    ssl_invoice_number The invoice or ticket number sent originally on the request. Returned based on merchant setup.
    errorCode Error code returned only   if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information.
    errorMessage Detailed explanation of the error returned only   if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information.
    errorName Error name or reason for the error returned only   if an error occurred. Refer to the Error Codes section for more information.

    Examples

    Request

    <txn>
        <ssl_merchant_id>my_merchant_id</ssl_merchant_id>
        <ssl_user_id>my_user_id</ssl_user_id>
        <ssl_pin>my_pin</ssl_pin>
        <ssl_description>Keyed Sale API</ssl_description>
        <ssl_transaction_type>pecomplete</ssl_transaction_type>
        <ssl_txn_id>AA4843B-EEBFF0FE-0BDC-47A3-B4F6-5D752E2FBE42</ssl_txn_id>
    </txn>

    Response

    <txn>
        <ssl_result>0</ssl_result>
        <ssl_result_message>APPROVAL</ssl_result_message>
        <ssl_txn_id>AA4843B-EEBFF0FE-0BDC-47A3-B4F6-5D752E2FBE42</ssl_txn_id>
        <ssl_txn_time>07/21/2013 05:19:38 PM</ssl_txn_time>
        <ssl_amount>3.00</ssl_amount>
        <ssl_salestax>0.01</ssl_salestax>
        <ssl_account_balance>0.00</ssl_account_balance>
        <ssl_invoice_number>1234</ssl_invoice_number>
        <ssl_first_name>John</ssl_first_name>
        <ssl_last_name>Doe</ssl_last_name>
        <ssl_avs_address>123 Main</ssl_avs_address>
        <ssl_city>Atlanta</ssl_city>
        <ssl_avs_zip>30123</ssl_avs_zip>
        <ssl_state>GA</ssl_state>
        <ssl_country>USA</ssl_country>
        <ssl_dynamic_dba>123456789012*ABCCORP</ssl_dynamic_dba>
    </txn>

    Paypal with Checkout.js

    To use Paypal with Checkout.js, you must take the following steps:

    1. Include Converge Checkout.js and render a Paypal button on your page.

    2. Prepare a session token.

    3. Provide callback (as shown in the example code below).

    <!DOCTYPE HTML>
    <html>
      <head>
        <meta http-equiv="content-type" content="text/html; charset=UTF-8">
        <script src="https://api.demo.convergepay.com/hosted-payments/Checkout.js"></script>
        <script>
    
            var callback = {
                onError: function (error) {
                    showResult("error", error);
                },
                onDeclined: function (response) {
                    showResult("declined", JSON.stringify(response));
                },
                onApproval: function (response) {
                    showResult("approval", JSON.stringify(response));
                },
                onCancelled: function () {
                    showResult("cancelled", "");
                }
            };
    
            function initiatePayPal () {
                var paymentFields = {
                    ssl_txn_auth_token: document.getElementById('transaction_session_token').value
                };
                ConvergeEmbeddedPayment.initPayPal('paypal-button', paymentFields, callback);
                return false;
            };
    
            function showResult (status, msg) {
                document.getElementById('txn_status').innerHTML = "<b>" + status + "</b>";
                document.getElementById('txn_response').innerHTML = msg + "</b>";
            };
        </script>
    
      </head>
      <body>
            <form>
                Transaction Token: <input type="text" id="transaction_session_token"> <br><br>
                <button onclick="return initiateMasterPass();">Initiate MasterPass</button> <br>
            </form>
            <br>
            <div id="paypal-button"></div>
            <br>
    
            Transaction Status:<div id="txn_status"></div>
            <br>
            Transaction Response:<div id="txn_response"></div>
      </body>
    
    </html>