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.

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.

note

The transaction will be authorized and settled on PayPal.

Request

Input Field NameReq?Description
ssl_transaction_typeYPayPal Express Checkout Sale (pesale
ssl_merchant_idYConverge ID as provided by Elavon.
ssl_user_idYConverge User ID as configured on Converge, case sensitive.
ssl_pinYConverge PIN as configured within Converge, case sensitive.
ssl_amountYTransaction 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_numberNThe invoice or ticket number.
ssl_descriptionNThe description, merchant defined value.
ssl_customer_codeNRecommended for purchasing cards.
The Customer Code or PO Number that appears on the cardholder’s credit card billing statement.
ssl_transaction_currencyNUse 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_stringNProduct 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
ssl_eWallet_shippingNWallet 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_creditNIf 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 NameDescription
ssl_resultOutcome 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_messageTransaction result message. Example: APPROVAL, PARTIAL APPROVAL. Refer to the API Reference for an extensive list of possible returned messages.
ssl_txn_idTransaction identification number. This is a unique number used to identify the transaction.
ssl_txn_timeDate 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_amountThe 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_dueRemaining 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_numberThe invoice or ticket number sent originally on the request. Returned based on merchant setup.
ssl_transaction_currencyTransaction currency. Returned only if terminal is setup for Multi-Currency.
errorCodeError 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.
errorMessageDetailed 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.
errorNameError 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 NameReq?Description
ssl_transaction_typeYPayPal Express Checkout Sale (peauthonly)
ssl_merchant_idYConverge ID as provided by Elavon.
ssl_user_idYConverge User ID as configured on Converge, case sensitive.
ssl_pinYConverge PIN as configured within Converge, case sensitive.
ssl_amountYTransaction 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_numberNThe invoice or ticket number.
ssl_descriptionNThe description, merchant defined value.
ssl_customer_codeNRecommended for purchasing cards.
The Customer Code or PO Number that appears on the cardholder’s credit card billing statement.
ssl_salestaxNRecommended 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_currencyNUse 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_stringNProduct 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
ssl_eWallet_shippingNWallet 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_creditNIf 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 NameDescription
ssl_resultOutcome 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_messageTransaction result message. Example: APPROVAL, PARTIAL APPROVAL. Refer to the API Reference for an extensive list of possible returned messages.
ssl_txn_idTransaction 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_timeDate 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_codeTransaction approval code.
ssl_amountTransaction authorized or approved amount. Returned based on merchant setup.
ssl_requested_amountThe amount originally requested on partial approvals only.
ssl_balance_dueRemaining 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_numberThe invoice or ticket number sent originally on the request. Returned based on merchant setup.
ssl_transaction_currencyTransaction currency. Returned only if terminal is setup for Multi-Currency.
ssl_card_short_descriptionCard description, valid values are: AMEX, CUP, DISC, MC, PP, and VISA.
ssl_card_typeCard type, valid values are: CASH, CREDITCARD, DEBITCARD, FOODSTAMP, GIFTCARD or LOYALTY.
errorCodeError 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.
errorMessageDetailed 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.
errorNameError name or reason for the error returned only if an error occurred. Refer to the Error Codes section for more information.

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.

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 NameReq?Description
ssl_transaction_typeYPayPal Express Checkout Credit (pereturn)
ssl_merchant_idYConverge ID as provided by Elavon.
ssl_pinYConverge PIN as configured within Converge, case sensitive.
ssl_user_idYConverge User ID as configured on Converge, case sensitive.
ssl_txn_idYUnique identifier returned on the original transaction.
ssl_amountNAmount 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 NameDescription
ssl_resultOutcome 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_messageTransaction result message. Example: APPROVAL.
ssl_txn_idTransaction identification number. This is a unique number used to identify the transaction.
ssl_txn_timeDate 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_amountTransaction authorized or approved amount. Returned based on merchant setup.
ssl_approval_codeTransaction approval code.
ssl_emailReturned based on merchant setup.
ssl_invoice_numberThe invoice or ticket number sent originally on the request. Returned based on merchant setup.
errorCodeError 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.
errorMessageDetailed 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.
errorNameError 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 NameReq?Description
ssl_transaction_typeYPayPal ExpressCheckout Void (pevoid)
ssl_merchant_idYConverge ID as provided by Elavon.
ssl_user_idYConverge User ID as configured on Converge, case sensitive.
ssl_pinYConverge PIN as configured within Converge, case sensitive.
ssl_txn_idYUnique identifier returned on the original transaction.

Response

Output Field NameDescription
ssl_resultOutcome 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_messageTransaction result message. Example: APPROVAL.
ssl_txn_idTransaction identification number. This is a unique number used to identify the transaction.
ssl_txn_timeDate 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_emailReturned based on merchant setup.
ssl_invoice_numberThe invoice or ticket number sent originally on the request. Returned based on merchant setup.
errorCodeError 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.
errorMessageDetailed 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.
errorNameError 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 NameReq?Description
ssl_transaction_typeYPayPal Express Checkout Completion (pecomplete)
ssl_merchant_idYConverge ID as provided by Elavon.
ssl_user_idYConverge User ID as configured on Converge, case sensitive.
ssl_pinYConverge PIN as configured within Converge, case sensitive.
ssl_txn_idYUnique identifier returned on the original transaction.
ssl_amountNAmount 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_flagNPartial 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 NameDescription
    ssl_resultOutcome 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_messageTransaction result message. Example: APPROVAL.
    ssl_txn_idTransaction identification number. This is a unique number used to identify the transaction.
    ssl_txn_timeDate 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_amountTransaction amount. Returned based on merchant setup.
    ssl_invoice_numberThe invoice or ticket number sent originally on the request. Returned based on merchant setup.
    errorCodeError 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.
    errorMessageDetailed 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.
    errorNameError 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 initiatePayPal();">Initiate PayPal</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>